Class: TTextChunkIterator

Declaration: BreakWord.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

An abstract base class for a wide range of TTextChunkIterators. The system is designed to have many iterators available, but initially only four are supported. These iterators are for character, word, and sentence selection, as well as for word wrapping. For performance reasons, the TTextChunkIterators maintain a pointer to the text they iterate over. If the text object is ever edited, the iterator can be resynchronized by calling the Set function. If the text object is destroyed, then the iterator should also be destroyed. TTextChunkIterator references should be used when streaming, either locally or on remote systems. This should be done with the proviso that reference iterators are only guaranteed to be valid in a single address space. After being streamed back in, TTextChunkIterator references should call TTextChunkIteratorReference::IsValid and take the proper action if this function returns false.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

This class should not be derived.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TTextChunkIterator::GetPreferredWordSelectionIteratorReference

static void GetPreferredWordSelectionIteratorReference (TTextChunkIteratorReference &)

Interface Category:

API.

Purpose:

Returns a reference to a word selection iterator.

Calling Context:

Called by a client to receive a reference to a system-supported word iterator.

Parameters:

TTextChunkIteratorReference & -Contains the requested iterator reference.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextChunkIterator::CreatePreferredWordSelectionIterator

static TTextChunkIterator * CreatePreferredWordSelectionIterator (const TText * text, const TInsertionOffset & ip =kInitialInsertionOffset)

Interface Category:

API.

Purpose:

Returns a word selection iterator.

Calling Context:

Called by a client to receive a system-supported word iterator.

Parameters:

const TText * text -A pointer to the text to be iterated over.
const TInsertionOffset & ip =kInitialInsertionOffset-The initial starting point for the iterator. The default value is the first insertion point of the text.

Return Value:

Returns a pointer to a new word selection iterator.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextChunkIterator::GetPreferredSentenceSelectionIteratorReference

static void GetPreferredSentenceSelectionIteratorReference (TTextChunkIteratorReference &)

Interface Category:

API.

Purpose:

Returns a reference to a sentence selection iterator.

Calling Context:

Called by a client to receive a reference to a system-supported sentence iterator.

Parameters:

TTextChunkIteratorReference & -Contains the requested iterator reference.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextChunkIterator::CreatePreferredSentenceSelectionIterator

static TTextChunkIterator * CreatePreferredSentenceSelectionIterator (const TText * text, const TInsertionOffset & ip =kInitialInsertionOffset)

Interface Category:

API.

Purpose:

Returns a sentence selection iterator.

Calling Context:

Called by a client to receive a system-supported sentence iterator.

Parameters:

const TText * text -A pointer to the text to be iterated over.
const TInsertionOffset & ip =kInitialInsertionOffset-The initial starting point for the iterator. The default value is the first insertion point of the text.

Return Value:

Returns a pointer to a new sentence selection iterator.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextChunkIterator::GetPreferredWordWrapIteratorReference

static void GetPreferredWordWrapIteratorReference (TTextChunkIteratorReference &)

Interface Category:

API.

Purpose:

Returns a reference to a word-wrapping selection iterator.

Calling Context:

Called by a client to receive a reference to a system-supported word-wrapping iterator.

Parameters:

TTextChunkIteratorReference & -Contains the requested iterator reference.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextChunkIterator::CreatePreferredWordWrapIterator

static TTextChunkIterator * CreatePreferredWordWrapIterator (const TText * text, const TInsertionOffset & ip =kInitialInsertionOffset)

Interface Category:

API.

Purpose:

Returns a word-wrapping selection iterator.

Calling Context:

Called by a client to receive a system-supported word-wrapping iterator.

Parameters:

const TText * text -A pointer to the text to be iterated over.
const TInsertionOffset & ip =kInitialInsertionOffset-The initial starting point for the iterator. The default value is the first insertion point of the text.

Return Value:

Returns a pointer to a new word-wrapping iterator.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextChunkIterator::GetPreferredCharacterClusterIteratorReference

static void GetPreferredCharacterClusterIteratorReference (TTextChunkIteratorReference &)

Interface Category:

API.

Purpose:

Returns a reference to a character-cluster selection iterator.

Calling Context:

Called by a client to receive a reference to a system-supported character-cluster iterator.

Parameters:

TTextChunkIteratorReference & -Contains the requested iterator reference.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextChunkIterator::CreatePreferredCharacterClusterIterator

static TTextChunkIterator * CreatePreferredCharacterClusterIterator (const TText * text, const TInsertionOffset & ip =kInitialInsertionOffset)

Interface Category:

API.

Purpose:

Returns a character-cluster selection iterator.

Calling Context:

Called by a client to receive a system-supported character-cluster iterator.

Parameters:

const TText * text -A pointer to the text to be iterated over.
const TInsertionOffset & ip =kInitialInsertionOffset-The initial starting point for the iterator. The default value is the first insertion point of the text.

Return Value:

Returns a pointer to a new character-cluster selection iterator.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextChunkIterator::First

virtual bool First (TTextRange & firstTextChunk)

Interface Category:

API.

Purpose:

Returns the first selection range in the text.

Calling Context:

Called to get the first selection in the text.

Parameters:

TTextRange & firstTextChunk -The returned selection reference.

Return Value:

Returns true if the selection range is found.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextChunkIterator::Last

virtual bool Last (TTextRange & lastTextChunk)

Interface Category:

API.

Purpose:

Returns the last selection range in the text.

Calling Context:

Called to get the last selection in the text.

Parameters:

TTextRange & lastTextChunk -The returned selection reference.

Return Value:

Returns true if the selection range is found.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextChunkIterator::Next

virtual bool Next (TTextRange & nextTextChunk)

Interface Category:

API.

Purpose:

Returns the next selection range in the text.

Calling Context:

Called to get the next selection in the text.

Parameters:

TTextRange & nextTextChunk -The returned selection reference.

Return Value:

Returns true if the selection range is found.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextChunkIterator::Previous

virtual bool Previous (TTextRange & previousTextChunk)

Interface Category:

API.

Purpose:

Returns the previous selection range in the text.

Calling Context:

Called to get the previous selection in the text.

Parameters:

TTextRange & previousTextChunk -The returned selection reference.

Return Value:

Returns true if the selection range is found.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextChunkIterator::Current

virtual bool Current (TTextRange & thisTextChunk)

Interface Category:

API.

Purpose:

Returns the current selection range in the text.

Calling Context:

Called to get the current selection in the text.

Parameters:

TTextRange & thisTextChunk -The returned selection reference.

Return Value:

Returns true if the selection range is found.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextChunkIterator::Set

virtual void Set (const TInsertionOffset & ip =kInitialInsertionOffset)
virtual void Set (const TText * text, const TInsertionOffset & ip =kInitialInsertionOffset)

Interface Category:

API.

Purpose:

Sets the iterator to a specific insertion point.
Sets the iterator to point to a text and at a specific insertion point.

Calling Context:

Called to set or reset the iterator starting point. It is usually called when the current text is modified.
Called to set or reset the iterator text. It is usually called when the text is reset to a different text.

Parameters:

const TInsertionOffset & ip =kInitialInsertionPoint -The initial starting point for the iterator. The default value is the first insertion point of the text.
const TText * text -The text to which the iterator should be pointing to.
const TInsertionOffset & ip =kInitialInsertionOffset -The initial starting point for the iterator. The default value is the first insertion point of the text.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextChunkIterator::GetIteratorReference

virtual void GetIteratorReference (TTextChunkIteratorReference & ref) const

Interface Category:

API.

Purpose:

Returns an iterator reference of the current iterator type.

Calling Context:

Called when in need of a reference to an iterator that needs to be either streamed or passed around between systems.

Parameters:

TTextChunkIteratorReference & ref -The returned iterator reference.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextChunkIterator::operator=

TTextChunkIterator & operator =(const TTextChunkIterator &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TTextChunkIterator & -The source object for the assignment.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextChunkIterator::TTextChunkIterator

TTextChunkIterator ()
TTextChunkIterator (const TTextChunkIterator &)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

Called by the stream-in operators and directly to instantiate this class.
Called to copy an object.

Parameters:

Takes no parameters.
const TTextChunkIterator & -The object to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextChunkIterator::~TTextChunkIterator

virtual ~ TTextChunkIterator ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.