Class: TText

Declaration: Text.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MOrderableCollectible

Inherited By:

TFilteredText TStandardText

Purpose:

TText is the abstract base class for all text objects. Each text instance contains Unicode character codes and styling information that can be associated with individual characters or groups of characters. Clients requiring only storage management for Unicode characters can use this class too. The text protocol supports common string manipulation functions like insertion and deletion. TText references are recommended for use throughout the system in all public interfaces that take text parameters. A default implementation, TStandardText, is provided. Do not use this class in public interfaces except where a concrete class is required. This ensures that other implementations of the text protocol can exist and be used polymorphically with public interfaces that take TText references. Within the TText interfaces for accessing and modifying the encapsulated data, terms are used in the following manner: text refers to both the Unicode character codes and the styling information associated with them, characters refers to only the Unicode character codes, and styles refers to only the styles and style sets that provide the styling information. Any function name that does not imply just the characters or just the styles can be assumed to involve both. For example, the Insert function inserts both characters and styling information.

Instantiation:

TText objects are never instantiated directly by clients. As an abstract base class, TText objects are only indirectly instantiated when a concrete derived class is instantiated. There is no instance data associated with the abstract class. So, this class has no impact on whether TText derived classes should be allocated on the heap or the stack.

Deriving Classes:

As an abstract base class, there are pure virtual functions that must be implemented in any concrete derived class of TText. The class TStandardText provides an implementation of this text protocol as a standard part of the system. In addition to the descriptions of the pure virtual functions here, see the class and member function descriptions pertaining to TStandardText as a good example of a concrete derived class of TText. Classes deriving either directly or indirectly from TText should not override Replace, Insert, and Delete. These member functions have been implemented in TText to use the following atomic member functions: HandleDeleteCharacters, HandleInsertCharacterGap, HandleCopyCharacters, HandleDeleteStyles, HandleInsertStylesGap, and HandleCopyStyles. These handle member functions should be overridden to provide the desired behavior. Any new implementation of the TText protocol intended for general use should provide a superset of the TStandardText implementation. Otherwise, it is unlikely that the new implementation will be widely adopted. For example, TStandardText objects can be constructed in a number of ways. Ideally, other implementations of the TText protocol would provide a similar set of constructors.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TText::~TText

virtual ~ TText ()

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.

Member Function: TText::GetLength

virtual TTextCount GetLength () const

Interface Category:

API.

Purpose:

Gets the length of the text string encapsulated by this text object.

Calling Context:

Call to get the length of the text string encapsulated by this text object.

Parameters:

Takes no parameters.

Return Value:

The length of the text string encapsulated by this text object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TText::TText

TText ()
TText (const TText & that)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

Called by the stream-in operators.
Called to copy an object.

Parameters:

Takes no parameters.
const TText & that -The source object for the assignment.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TText::GetCharacterAt

virtual UniChar GetCharacterAt (TTextIndex index) const

Interface Category:

API.

Purpose:

Gets the character at a specified index.

Calling Context:

To get the character stored at a particular index.

Parameters:

TTextIndex index -The index of the character to get.

Return Value:

The character at the specified index.

Exceptions:

Throws an exception if the index is less than zero or beyond the current length of the text, passes all other exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Use a TCharacterIterator for fast sequential access. Even random access to more than a few characters will benefit from using a TCharacterIterator.

Member Function: TText::SetCharacterAt

virtual void SetCharacterAt (TTextIndex index, const UniChar thatChar)

Interface Category:

API.

Purpose:

Sets the character at a specified index.

Calling Context:

To set the character stored at a specified index.

Parameters:

TTextIndex index -The index of the character to set.
const UniChar thatChar -The new character value.

Return Value:

None.

Exceptions:

Throws an exception if the index is less than zero or beyond the current length of the text, passes all other exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Use a TCharacterIterator for fast sequential access. Even random access to more than a few characters will benefit from using a TCharacterIterator.

Member Function: TText::operator[]

UniChar operator [] (TTextIndex index) const

Interface Category:

API.

Purpose:

Returns the UniChar at the given index.

Calling Context:

To get the UniChar at a given index.

Parameters:

TTextIndex index -The index of the UniChar of interest.

Return Value:

The UniChar at the given index.

Exceptions:

Throws an exception if the index is less than zero or beyond the current length of the text, passes all other exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TText::PartialCopy

virtual TText * PartialCopy (const TTextRange & range, TTextCount extraSpace =0, TMemoryHeap * whichHeap =NIL) const

Interface Category:

API.

Purpose:

Creates a copy of any part of any text object polymorphically. Use this member function when polymorphic extraction of a range of text is required. This is a copy function that passes ownership of new storage to the client instead of an extract function with a client provided text object as an output parameter. Otherwise, it is not possible to extract a range of text polymorphically.

Calling Context:

To get a polymorphic copy of any part of a text object.

Parameters:

const TTextRange & range -The text range in this text object to copy.
TTextCount extraSpace =0 -Similar to constructors, the caller can request additional space be allocated with the newly constructed text object.
TMemoryheap * whichHeap =NIL -The heap to allocate the new object in.

Return Value:

A copy of the specified text range in a newly created text object is returned. The caller gets ownership of the storage for this new object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Derived classes can take advantage of virtual specialization to return a pointer of their own derived class type. For example, the override of this function in TStandardText returns a TStandardText object pointer.

Member Function: TText::Extract

virtual TTextCount Extract (const TTextRange & thisRange, TText & that) const
virtual TTextCount Extract (const TTextRange & thisRange, TUnicodeArray & that) const
virtual TTextCount Extract (const TTextRange & thisRange, UniChar that [], TTextCount thatMaxCount) const
virtual TTextCount Extract (const TTextRange & thisRange, char that [], TTextCount thatMaxCount) const

Interface Category:

API.

Purpose:

Copies text in the specified text range of this text object into the output text object.
Copies text in the specified text range of this text object into the output TUnicodeArray object.
Copies text in the specified text range of this text object into the output UniChar array. The resulting UniChar array is NOT null terminated.
Copies text in the specified text range of this text object into the output character array. The resulting character array is null terminated. This means that the size of the character array must be one byte more than the length of the text to be extracted. In other words, the length of the character array should be one more than thatMaxCount. Otherwise, the extraction may write off the end of the character array, resulting in heap corruption problems.

Calling Context:

When copying text from one text object to another.
When copying text from a text object into a TUnicodeArray object.
When copying text from a text object into a UniChar array.
When copying text from a text object into a character array.

Parameters:

const TTextRange & thisRange -The text range in this text object to be copied to that text object.
TText & that -The output text instance.
const TTextRange & thisRange -The text range in this text object to be copied to that text object.
TUnicodeArray & that -The output TUnicodeArray.
const TTextRange & thisRange -The text range in this text object to be copied to that text object.
UniChar that [] -The output UniChar array.
TTextCount thatMaxCount -The maximum number of characters to extract.
const TTextRange & thisRange -The text range in this text object to be copied to that text object.
char that [] -The output char array.
TTextCount thatMaxCount -The maximum number of characters to extract.

Return Value:

The number of characters extracted; this can differ from the requested length.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

For more accurate extraction of 8-bit character data, use TTranscoder. When extracting into a character array, the resulting array is null terminated. This means that the length of the character array must be one more than thatMaxCount. When extracting into a UniChar array, the resulting array is NOT null terminated.

Member Function: TText::ExtractCharacters

virtual TTextCount ExtractCharacters (const TTextRange & thisRange, TText & that) const

Interface Category:

API.

Purpose:

Copies only the characters in the specified text range of this text object into the output text object. Use Extract instead If you are interested in both the character and style information.

Calling Context:

Call to copy characters from one text object to another.

Parameters:

const TTextRange & thisRange -The text range for the characters in this text object to be copied to that text object.
TText & that -The output text object. The current contents of that is replaced by the characters copied from this text object.

Return Value:

The number of characters extracted; this can differ from the requested length.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TText::Replace

virtual void Replace (const TText & that, const TTextRange & thatRange =TTextRange :: GetMaximumRange (), const TTextRange & thisRange =TTextRange :: GetMaximumRange ())
virtual void Replace (const TUnicodeArray & that, const TTextRange & thatRange =TTextRange :: GetMaximumRange (), const TTextRange & thisRange =TTextRange :: GetMaximumRange ())
virtual void Replace (const UniChar that [], TTextCount thatLength, const TTextRange & thisRange =TTextRange :: GetMaximumRange ())
virtual void Replace (UniChar that, const TTextRange & thisRange =TTextRange :: GetMaximumRange ())
virtual void Replace (const char nullTerminatedArray [], const TTextRange & thisRange =TTextRange :: GetMaximumRange ())

Interface Category:

API.

Purpose:

Replaces text in the specified range of this text object with the specified text input. This member function is implemented in TText to use the following handle member functions: HandleInsertCharacterGap, HandleDeleteCharacters, HandleCopyCharacters, HandleDeleteStyles, HandleInsertStylesGap, and HandleCopyStyles. Classes deriving from TText should override these handle member functions to implement the desired behavior. Do not override the Replace member functions.

Calling Context:

Call to replace a portion of a text object with other text.

Parameters:

const TText & that -Text object containing the replacement text.
const TTextRange & thatRange =TTextRange :: GetMaximumRange () -The range of replacement text to use.
const TTextRange & thisRange =TTextRange :: GetMaximumRange () -The range in this text object to replace.
const TUnicodeArray & that -TUnicodeArray containing the replacement text.
const TTextRange & thatRange =TTextRange :: GetMaximumRange () -The range of replacement text to use.
const TTextRange & thisRange =TTextRange :: GetMaximumRange () -The range in this text object to replace.
const UniChar that [] -UniChar array containing the replacement text.
TTextCount thatLength -Length of the UniChar array.
const TTextRange & thisRange =TTextRange :: GetMaximumRange () -The range in this text object to replace.
UniChar that -Replacement character.
const TTextRange & thisRange =TTextRange :: GetMaximumRange () -The range in this text object to replace.
const char nullTerminatedArray [] -char array containing the replacement text.
const TTextRange & thisRange =TTextRange :: GetMaximumRange () -The range in this text object to replace.

Return Value:

None.

Exceptions:

Throws the exception TTextException::kInvalidReplace if the text object to extract from is the same object as the text object to do the replace in. Passes all other exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TText::Insert

virtual void Insert (const TText & that, const TTextRange & thatRange =TTextRange :: GetMaximumRange (), TTextOffset thisOffset =TTextOffset :: GetMaximum ())
virtual void Insert (const TUnicodeArray & that, const TTextRange & thatRange =TTextRange :: GetMaximumRange (), TTextOffset thisOffset =TTextOffset :: GetMaximum ())
virtual void Insert (const UniChar that [], TTextCount thatLength, TTextOffset thisOffset =TTextOffset :: GetMaximum ())
virtual void Insert (UniChar that, TTextOffset thisOffset =TTextOffset :: GetMaximum ())
virtual void Insert (const char nullTerminatedArray [], TTextOffset thisOffset =TTextOffset :: GetMaximum ())

Interface Category:

API.

Purpose:

Inserts text from the input text object or character array at the specified offset. Both the characters and styles are inserted when the input is a text object. When inserting a character array or text from an unstyled text object, the inserted text will remain unstyled. By default, text is inserted at the end of the text object. This member function is implemented in TText to use the following handle member functions: HandleInsertCharacterGap, HandleCopyCharacters, HandleInsertStylesGap, and HandleCopyStyles. Classes deriving from TText should override these handle member functions to implement the desired behavior. Do not override the Insert member functions.

Calling Context:

Call to insert text from another text object into this text object.
Call to insert text from a TUnicodeArray into this text object.
Call to insert text from a UniChar array into this text object.
Call to insert a single UniChar into this text object.
Call to insert text from a char array into this text object.

Parameters:

const TText & that -Text object containing the text to insert.
const TTextRange & thatRange =TTextRange :: GetMaximumRange () -The range of text to insert.
TTextOffset thisOffset =TTextOffset :: GetMaximum () -The offset at which to insert the input text.
const TUnicodeArray & that -TUnicodeArray object containing the text to insert.
const TTextRange & thatRange =TTextRange :: GetMaximumRange () -The range of text to insert.
TTextOffset thisOffset =TTextOffset :: GetMaximum () -The offset at which to insert the input text.
const UniChar that [] -UniChar array containing the text to insert.
TTextCount thatLength -Number of characters from the array to insert.
TTextOffset thisOffset =TTextOffset :: GetMaximum () -The offset at which to insert the input text.
UniChar that -UniChar character to insert.
TTextOffset thisOffset =TTextOffset :: GetMaximum () -The offset at which to insert the input text.
const char nullTerminatedArray [] -char array containing the text to insert.
TTextOffset thisOffset =TTextOffset :: GetMaximum () -The offset at which to insert the input text.

Return Value:

None.

Exceptions:

Throws the exception TTextException::kInvalidReplace if the text object to insert is the same object as the text object to insert into. Passes all other exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TText::Delete

virtual void Delete (const TTextRange & range =TTextRange :: GetMaximumRange ())

Interface Category:

API.

Purpose:

Deletes the text contained within the specified TTextRange from this text object. This member function is implemented in TText to use the handle member functions HandleDeleteCharacters and HandleDeleteStyles. Classes deriving from TText should override these handle member functions to implement the desired behavior. Do not override the Replace member functions.

Calling Context:

Called directly to remove some or all of the text from a text object.

Parameters:

const TTextRange & range =TTextRange :: GetMaximumRange () -The text range within this text object to be deleted. The default is to delete all character and style information.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TText::StylesAt

virtual TTextIndex StylesAt (TTextIndex indexOfInterest, TStyleSet & returnSet, const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind ()) const
virtual TTextIndex StylesAt (TTextIndex indexOfInterest, TStyleSet & returnSet, TTextRange & currentRunRange, const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind ()) const

Interface Category:

API.

Purpose:

Fills in a given style set with the styles of the specified kind that are associated with the specified index. When it matters, callers can also get the maximal contiguous text range with the same style information that contains the specified index.

Calling Context:

Called directly to get the styles for a specified index.
Called directly to get the styles for a specified index and the maximal contiguous text range that contains the same style information and the index of interest.

Parameters:

TTextIndex indexOfInterest -The index to get styles for.
TStyleSet & set -The output style set to copy the styles for the specified index into.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to include in the resulting set.
TTextIndex indexOfInterest -The index to get styles for.
TStyleSet & set -The output style set to copy the styles for the specified index into. The styles in the returned set are owned by the text. They are not to be deleted.
TTextRange & currentRunRange -The maximal contiguous text range that contains the output styles and overlaps the index of interest too.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to include in the resulting set.

Return Value:

The starting index of the next style run. A style run is the term used to describe a maximal contiguous text range of text with the same style information.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Clients are not required to concern themselves with the underlying association of style information with the character codes. However, clients that take advantage of this knowledge can do some things more efficiently. For example, it is not necessary to make a StylesAt call for every character in a text object when iterating over style information. Rather, you can take advantage of style run information to make only one StylesAt call for each style run and then jump ahead to the next run (using the returned starting index for the next run).

Member Function: TText::CopyStylesAt

virtual TStyleSet * CopyStylesAt (TTextIndex indexOfInterest, const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind (), TMemoryHeap * whichHeap =NIL) const
virtual TStyleSet * CopyStylesAt (TTextIndex indexOfInterest, TTextRange & currentRunRange, const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind (), TMemoryHeap * whichHeap =NIL) const

Interface Category:

API.

Purpose:

Creates a new style set on the heap with a copy the styles of the specified kind that are associated with the specified index.
Creates a new style set on the heap with a copy of the styles of the specified kind that are associated with the specified index. Also returns the maximal contiguous text range with the same style information that overlaps the specified index.

Calling Context:

Called directly to copy the styles for a specified index.
Called directly to copy the styles for a specified index and gets the maximal contiguous text range that contains the same style information and the index of interest.

Parameters:

TTextIndex indexOfInterest -The index to copy styles from.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to copy.
TTextIndex indexOfInterest -The index to copy styles from.
TTextRange & currentRunRange -The maximal contiguous text range that contains the returned styles and overlaps the index of interest too.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to copy.
TMemoryHeap * whichHeap =NIL -The heap to allocate the new object in.

Return Value:

A copy of the styles of the specified kind at the specified index is returned. The caller gets ownership of the storage for this new object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TText::IsStyled

virtual bool IsStyled () const

Interface Category:

API.

Purpose:

Determines if this text object has style information associated with it.

Calling Context:

Call directly to check for styles. Called indirectly in the implementation of other pure virtual functions by derived classes.

Parameters:

Takes no parameters.

Return Value:

Returns true if there are any styles associated with this text object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Any of the style functions can still be called on text that is unstyled. Setter functions convert text from unstyled text to styled text and set the appropriate style information.

Member Function: TText::StylesExist

virtual bool StylesExist (const TStyleSet & set, const TTextRange & range, const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind ()) const

Interface Category:

API.

Purpose:

Determines if any of the characters within the specified text range are styled with all of the styles of the specified kind in the specified style set.

Calling Context:

Called directly to check for the existence of the specified styles anywhere within the specified text range.

Parameters:

const TStyleSet & set -The styles to look for.
const TTextRange & range -The text range to look at.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to look for. Only styles of this kind will be checked.

Return Value:

Returns true if at least one character within the specified text range is styled with all the styles of the specified kind in the specified style set.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TText::StylesContinuous

virtual bool StylesContinuous (const TStyleSet & set, const TTextRange & range) const

Interface Category:

API.

Purpose:

Determines if every character within the specified text range is styled with all the styles in the specified style set.

Calling Context:

Called directly to check for the existence of the specified styles for every character within the specified text range.

Parameters:

const TStyleSet & set -The styles to look for.
const TTextRange & range -The text range to look at.

Return Value:

Returns true if every character within the specified text range is styled with all the styles in the specified style set.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TText::AllStyles

virtual void AllStyles (TSetOf < TStyle > & returnSet, const TTextRange & range, const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind ()) const

Interface Category:

API.

Purpose:

Gets the maximal set of styles of the specified kind for the specified text range. It is not required that styles in the returned set be continuous throughout the entire text range. It only matters that a style exist on at least one character in the text range for it to be included in this maximal set of styles.

Calling Context:

Called directly to get the maximal set of styles of the specified kind associated with a specified text range.

Parameters:

TSetOf < TStyle > & set -The output set to fill. Any objects in this set at the time of the call are removed before filling the set with the styles found.
const TTextRange & range -The text range to look at.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to include in the resulting set.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The styles in the returned set are owned by the text. They are not to be modified or deleted.

Member Function: TText::AllContinuousStyles

virtual void AllContinuousStyles (TStyleSet & returnSet, const TTextRange & range, const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind ()) const

Interface Category:

API.

Purpose:

Gets the maximal set of continuous styles of the specified kind for the specified text range. It is required that styles in the returned set be continuous throughout the entire text range.

Calling Context:

Called directly to get the maximal set of continuous styles of the specified kind associated with a specified text range.

Parameters:

TStyleSet & set -The output set to fill. Any objects in this set at the time of the call are removed before filling the set with the styles found.
const TTextRange & range -The text range to look at.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to include in the resulting set.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The styles in the returned set are owned by the text. They are not to be deleted.

Member Function: TText::AddStyles

virtual void AddStyles (const TStyle & style, const TTextRange & range =TTextRange :: GetMaximumRange ())
virtual void AddStyles (const TStyleSet & set, const TTextRange & range =TTextRange :: GetMaximumRange (), const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind ())

Interface Category:

API.

Purpose:

Adds the specified style to each character within the specified text range.
Adds the styles of the specified kind in the specified style set to each character within the specified text range.

Calling Context:

Called directly to add a single style.
Called directly to add multiple styles at once.

Parameters:

const TStyle & style -The style to add.
const TTextRange & range =TTextRange :: GetMaximumRange () -The text range to add a single style to.
const TStyleSet & set -The set of styles to add.
const TTextRange & range =TTextRange :: GetMaximumRange () -The text range to add a set of styles to.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to add. The styles that are not of this kind are ignored.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Consistent with the style set invariant of only one style of the same category and name in a style set, new styles replace existing styles when the category and the name are the same. In the absence of category and name collisions, the new styles are simply added to what was there already.

Member Function: TText::RemoveStyles

virtual void RemoveStyles (const TStyle & style, const TTextRange & range =TTextRange :: GetMaximumRange ())
virtual void RemoveStyles (const TStyleSet & set, const TTextRange & range =TTextRange :: GetMaximumRange (), const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind ())
virtual void RemoveStyles (const TStyleCategory & category, const TStyleName & name, const TTextRange & range =TTextRange :: GetMaximumRange (), const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind ())
virtual void RemoveStyles (const TStyleKind & styleKind, const TTextRange & range =TTextRange :: GetMaximumRange ())
virtual void RemoveStyles ()

Interface Category:

API.

Purpose:

Removes the specified style from each character within the specified text range.
Removes the specified styles from each character within the specified text range.
Removes the specified style from each character within the specified text range.
Removes all of the styles of the specified kind from each character in the text object.
Removes all styles from each character in the text object.

Calling Context:

Called directly to remove the specified style.
Called directly to remove the styles of the specified kind that are in the specified set of styles.
Called directly to remove the style of the specified category, name, and kind.
Called directly to remove the styles of the specified kind.
Called directly to remove all styles.

Parameters:

const TStyle & style -The style to look for.
const TTextRange & range =TTextRange :: GetMaximumRange () -The text range to look at.
const TStyleSet & set -The set of styles to look for.
const TTextRange & range =TTextRange :: GetMaximumRange () -The text range to look at.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to look for. Only styles of this kind are removed.
const TStyleCategory & category -The category to look for.
const TStyleName & name -The name to look for.
const TTextRange & range =TTextRange :: GetMaximumRange () -The text range to look at.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to look for. Only styles of this kind are removed.
const TStyleKind & styleKind -The kind of styles to look for. Only styles of this kind are removed.
const TTextRange & range =TTextRange :: GetMaximumRange () -The text range to look at.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The input style or style set are used for comparison with the style information currently associated with text in the specified range. Only a category and name comparison is done. Styles are removed from the text that match the names of the input styles.

Member Function: TText::ReplaceStyles

virtual void ReplaceStyles (const TStyle & replacementStyle, const TTextRange & range =TTextRange :: GetMaximumRange ())
virtual void ReplaceStyles (const TStyleSet & replacementSet, const TTextRange & range =TTextRange :: GetMaximumRange (), const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind ())

Interface Category:

API.

Purpose:

Replaces existing styles with the specified style. The styles of the same kind as the specified style are replaced. All other styles are not touched.
Replaces the existing styles of the specified kind with the styles of the specified kind in the specified style set.

Calling Context:

Called directly to replace existing styles with one style.
Called directly to replace existing styles a set of styles.

Parameters:

const TStyle & style -The style to add after removing the existing styles.
const TTextRange & range =TTextRange :: GetMaximumRange () -The text range to replace styles in.
const TStyleSet & set -The set of styles to add after removing the existing styles.
const TTextRange & range =TTextRange :: GetMaximumRange () -The text range to replace styles in.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to be replaced. Only styles of this kind are removed and added.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TText::IsEqualCharacters

bool IsEqualCharacters (const TText & that) const
virtual bool IsEqualCharacters (const TText & that, const TTextRange & thatRange, const TTextRange & thisRange =TTextRange :: GetMaximumRange ()) const

Interface Category:

API.

Purpose:

Compares the character information of this text object with the input text object. Compares two text objects in their entirety or compares a text range in one text object with a different text range in the other text object.

Calling Context:

Called to compare all of one text object against all of another text object.
Called to compare a text range in one text object against a different text range in another text object.

Parameters:

const TText & that -The text object to compare against this text object.
const TText & that -The text object to compare against this text object.
const TTextRange & thatRange -The text range in that text object to be compared against text from this text object.
const TTextRange & thisRange =TTextRange :: GetMaximumRange () -The text range in this text object to be compared against the text from that text object.

Return Value:

Returns true if the characters compared between the two text objects are equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

When comparing characters here, a simple bitwise comparison is done. For case-insensitive or language-sensitive comparisons of characters, see the comparison functionality in the international comparison classes.

Member Function: TText::IsEqualStyles

bool IsEqualStyles (const TText & that, const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind ()) const
virtual bool IsEqualStyles (const TText & that, const TTextRange & thatRange, const TTextRange & thisRange =TTextRange :: GetMaximumRange (), const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind ()) const

Interface Category:

API.

Purpose:

Compares the style information of this text object with the input text object.

Calling Context:

Called to compare all styles of the specified kind for one text object against all styles of the specified kind for another text object.
Called to compare styles of the specified kind in a text range in one text object against styles of the specified kind in a different text range in another text object.

Parameters:

const TText & that -The text object to compare against this text object.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to compare. Only compares styles of this kind.
const TText & that -The text object to compare against this text object.
const TTextRange & thatRange -The text range in that text object to be compared against text from this text object.
const TTextRange & thisRange =TTextRange :: GetMaximumRange () -The text range in this text object to be compared against the text from that text object.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to compare. Only compares styles of this kind.

Return Value:

Returns true if the compared styles are equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TText::operator==

bool operator ==(const TText & that) const

Interface Category:

API.

Purpose:

Equality operator.

Calling Context:

Called to compare two TText objects.

Parameters:

const TText & that -The TText object to compare with this object.

Return Value:

Returns true if the objects are equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function compares only the characters in the text, not the styles.

Member Function: TText::operator!=

bool operator != (const TText & that) const

Interface Category:

API.

Purpose:

Inequality operator.

Calling Context:

Called to compare two TText objects.

Parameters:

const TText & that -The TText object to compare with this object.

Return Value:

Returns true if the object are not equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function compares only the characters in the text, not the styles.

Member Function: TText::operator>

virtual bool operator >(const TText & that) const

Interface Category:

API.

Purpose:

Relational operator (greater than).

Calling Context:

Called to compare two TText objects.

Parameters:

const TText & that -The TText object to compare to this object.

Return Value:

Returns true if this object is greater than the specified object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function compares only the characters in the text, not the styles.

Member Function: TText::operator>=

bool operator >=(const TText & that) const

Interface Category:

API.

Purpose:

Relational operator (greater than or equal to).

Calling Context:

Called to compare two TText objects.

Parameters:

const TText & that -The TText object to compare to this object.

Return Value:

Returns true if this object is greater than or equal to the specified object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function compares only the characters in the text, not the styles.

Member Function: TText::operator<

virtual bool operator < (const TText & that) const

Interface Category:

API.

Purpose:

Relational operator (less than).

Calling Context:

Called to compare two TText objects.

Parameters:

const TText & that -The TText object to compare to this object.

Return Value:

Returns true if this object is less than the specified object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function compares only the characters in the text, not the styles.

Member Function: TText::operator<=

bool operator <= (const TText & that) const

Interface Category:

API.

Purpose:

Relational operator (less than or equal to).

Calling Context:

Called to compare two TText objects.

Parameters:

const TText & that -The TText object to compare to this object.

Return Value:

Returns true if this object is less than or equal to the specified object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function compares only the characters in the text, not the styles.

Member Function: TText::operator=

virtual TText & operator =(const TText & that)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TText & that -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: TText::operator>>=

virtual TStream & operator >>=(TStream & toStream) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & toStream -The stream to write data out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Derived classes must override this member function to provide their own streaming code. The inherited streaming operator must be called first before streaming out your own data.

Member Function: TText::operator<<=

virtual TStream & operator <<= (TStream & fromStream)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromStream -The stream to read data in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Derived classes must override this member function to provide their own streaming code. The inherited streaming operator must be called first before streaming in your own data.

Member Function: TText::PartialStreamOut

virtual void PartialStreamOut (TStream & toStream, const TTextRange & range) const

Interface Category:

API.

Purpose:

Streams out a complete text object for the text contained within the specified text range.

Calling Context:

Called when you want to stream out only part of an existing text object. The standard streaming operators only work on the entire text object.

Parameters:

TStream & toStream -The stream to write data out to.
const TTextRange & range -The text range to be streamed out.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TText::HandleCopyStyles

virtual void HandleCopyStyles (const TText & that, TTextOffset thatOffset, TTextCount thatLength, TTextOffset thisOffset)

Interface Category:

API.

Purpose:

Copies the styles from a specified range of a given TText object into the text starting at the specified offset. This member function replaces the current styles with the styles to be copied. If there are no styles to be copied, then the specified range of the text that the styles are being copied into becomes unstyled. The behavior of HandleCopyStyles and CopyStyles may be different. For instance, for paragraph-based styles CopyStyles only copies the paragraph-based styles from the first paragraph of the specified range, while HandleCopyStyles copies the styles paragraph-by-paragraph.

Calling Context:

Called to copy the styles from one TText object into another. This member function should only be called when the corresponding text has been changed, so this member function is usually called directly after HandleInsertStylesGap has been called.

Parameters:

const TText & that -The TText object from which the styles are to be copied.
TTextOffset thatOffset -The offset at the beginning of the range of styles to be copied.
TTextCount thatLength -The length of the range of styles to be copied.
TTextOffset thisOffset -The beginning offset where the styles are to be copied into.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TText::HandleInsertStylesGap

virtual void HandleInsertStylesGap (TTextOffset beginOffset, TTextCount length)

Interface Category:

API.

Purpose:

Updates the style runs when new characters have been inserted into the text.

Calling Context:

This member function is called when new characters have been inserted into the text.

Parameters:

TTextOffset beginOffset -The offset at the beginning of the range of newly inserted characters.
TTextCount length -The length of the range of newly inserted characters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function must be called after the new characters have been inserted into the text, because the characters may have an affect on how the style runs should be updated. For instance, if a paragraph marker is added, the paragraph-based style runs will have to be updated to take this into account.

Member Function: TText::HandleDeleteStyles

virtual void HandleDeleteStyles (TTextOffset beginOffset, TTextCount length)

Interface Category:

API.

Purpose:

Updates the style runs when characters are going to be deleted from the text.

Calling Context:

This member function is called when characters are going to be removed from the text.

Parameters:

TTextOffset beginOffset -The offset at the beginning of the range of characters that are going to be removed.
TTextCount length -The length of the range of characters that are going to be removed.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function must be called before the characters are actually removed from the text, because the characters may have an affect on how the style runs should be updated. For instance, if a paragraph marker is one of the characters being removed, the paragraph-based style runs will have to be updated to take this into account.

Member Function: TText::HandleCopyCharacters

virtual void HandleCopyCharacters (const TText & that, TTextOffset thatOffset, TTextCount thatLength, TTextOffset thisOffset)
virtual void HandleCopyCharacters (const UniChar that [], TTextCount thatLength, TTextOffset thisOffset)

Interface Category:

API.

Purpose:

Copies the characters from a specified range of a given TText object or UniChar array into the text starting at the specified offset.

Calling Context:

Called to copy the characters from a TText object or UniChar array into another TText object.

Parameters:

const TText & that -The TText object to copy the characters from.
TTextOffset thatOffset -The offset at the beginning of the range of characters to be copied.
TTextCount thatLength -The length of the range of characters to be copied.
TTextOffset thisOffset -The beginning offset where the characters are to be copied into.
const UniChar that [] -The array of characters to copy.
TTextCount thatLength -The length of the array of characters.
TTextOffset thisOffset -The beginning offset where the characters are to be copied into.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

If the current characters in the text are not to be replaced, then HandleInsertCharacterGap must be called before this member function is used in order to create an opening in the text where the new characters are to be added.

Member Function: TText::HandleInsertCharacterGap

virtual void HandleInsertCharacterGap (TTextOffset beginOffset, TTextCount length)

Interface Category:

API.

Purpose:

Opens up space in the text where new characters are to be added by calling the HandleCopyCharacters member function. For instance, to insert characters into text, call HandleInsertCharacterGap to create a gap where the new characters are to be added, then call HandleCopyCharacters to fill that gap in with the new characters.

Calling Context:

Called to open a gap in the text where new characters are to be inserted.

Parameters:

TTextOffset beginOffset -The offset at the beginning of the range where the gap is to be created.
TTextCount length -The length of the gap to create.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function must be followed by a call to HandleCopyCharacters in order to initialize the new character values. This member function does not initialize any of the values within the gap that it creates.

Member Function: TText::HandleDeleteCharacters

virtual void HandleDeleteCharacters (TTextOffset beginOffset, TTextCount length)

Interface Category:

API.

Purpose:

Deletes the characters in the specified range of text, and collapses the character storage to completely remove the gap that is left when the characters are deleted.

Calling Context:

Called to delete the characters from a range of text.

Parameters:

TTextOffset beginOffset -The offset at the beginning of the range of characters to delete.
TTextCount length -The length of the range of characters to delete.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TText::GetStyleBounds

virtual void GetStyleBounds (TTextIndex indexOfInterest, TTextRange & currentRunRange, const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind ()) const

Interface Category:

API.

Purpose:

For a specified style kind, this member function determines the maximal contiguous text range with the same style information that contains the specified index. For instance, for paragraph-based styles the resulting range will be the range of the paragraph containing the specified index.

Calling Context:

Called directly to obtain boundary information about the styles of a specified kind at a specified index.

Parameters:

TTextIndex indexOfInterest -The index to get the style boundary information for.
TTextRange & currentRunRange -The resulting range.
const TStyleKind & styleKind =TCharacterStyleRuns :: GetStyleKind () -The kind of styles to look at.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TText::GetStyleKinds

virtual void GetStyleKinds (TSetOf < TStyleKind > & returnSet) const

Interface Category:

API.

Purpose:

Generates the complete set of the kinds of styles that are being applied to the text. This member function is used to get all of the styles in a particular range, regardless of kind. For instance, to get all of the styles at a given index, use this member function to get all of the kinds of styles, then iterate through the resulting set calling StylesAt for each kind.

Calling Context:

Called directly to get the complete set of the kinds of styles that are being applied to the text.

Parameters:

TSetOf < TStyleKind > & returnSet -The output set to fill. Any objects in this set at the time of the call are removed before filling the set with the kinds of styles that are being applied to the text.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The TStyleKind objects in the returned set are owned by the text. They are not to be modified or deleted.

Member Function: TText::CopyStyles

virtual void CopyStyles (const TText & that, const TTextRange & thatRange, TTextOffset thisOffset)

Interface Category:

API.

Purpose:

Copies the styles from a specified range of a given TText object into the text starting at the specified offset. The behavior of HandleCopyStyles and CopyStyles may be different. For instance, for paragraph-based styles CopyStyles only copies the paragraph-based styles from the first paragraph of the specified range, while HandleCopyStyles copies the styles paragraph-by-paragraph.

Calling Context:

Called to copy the styles from one TText object into another.

Parameters:

const TText & that -The TText object from which the styles are to be copied.
const TTextRange & thatRange -The range of styles to be copied.
TTextOffset thisOffset -The beginning offset where the styles are to be copied into.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TText::GetConstUniCharChunk

virtual const UniChar * GetConstUniCharChunk (TTextIndex indexOfInterest, TTextIndex & chunkStart, TTextCount & chunkLength) const

Interface Category:

API.

Purpose:

Returns a const pointer to the contiguous block of text storage containing the character at the specified index, and determines the starting index and the length of the storage that is returned. When the specified index is out of bounds, the return value will be NIL and the length will be 0. Note: There is currently a known bug in TStandardText::GetConstUniCharChunk which is preventing it from returning NIL when the specified index is outside the bounds of the text. This bug is expected to be fixed in the next release.

Calling Context:

This member function should only be used by character or text iterators.

Parameters:

TTextIndex indexOfInterest -The index to get the contiguous block of text storage for.
TTextIndex & chunkStart -The output index indicating where the resulting contiguous block of text storage begins.
TTextCount & chunkLength -The output length of the resulting contiguous block of text storage.

Return Value:

Returns a const pointer to the contiguous block of text storage containing the character at the specified index, and fills in the values representing the starting index and the length of the storage that is returned. When the specified index is out of bounds, the return value will be NIL and the length will be 0.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function should only be used by character or text iterators. It is very dangerous, as it exposes the internal storage of the text.

Member Function: TText::GetUniCharChunk

virtual void GetUniCharChunk (TTextIndex indexOfInterest, UniChar * & chunkPtr, TTextIndex & chunkStart, TTextCount & chunkLength)

Interface Category:

API.

Purpose:

Gets a pointer to the contiguous block of text storage containing the character at the specified index, and determines the starting index and the length of the resulting storage. When the specified index is out of bounds, the resulting pointer will be NIL and the length will be 0.

Calling Context:

This member function should only be used by character or text iterators.

Parameters:

TTextIndex indexOfInterest -The index to get the contiguous block of text storage for.
UniChar * & chunkPtr -The pointer to be set to point to the contiguous block of text storage.
TTextIndex & chunkStart -The output index indicating where the resulting contiguous block of text storage begins.
TTextCount & chunkLength -The output length of the resulting contiguous block of text storage.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function should only be used by character or text iterators. It is very dangerous, as it exposes the internal storage of the text.

Member Function: TText::operator+=

virtual TText & operator += (const TText & that)

Interface Category:

API.

Purpose:

Appends to the current contents of this text object the contents of the input text object.

Calling Context:

Called to append one text object to another.

Parameters:

const TText & that -The text object to append to this text object.

Return Value:

After the append has been done, a reference to this text object is returned.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Derived classes should take advantage of virtual specialization when overriding the assignment operators. For example, the TStandardText::operator+= override returns a TStandardText reference.

Member Function: TText::IsEqual

bool IsEqual (const TText & that) const
virtual bool IsEqual (const TText & that, const TTextRange & thatRange, const TTextRange & thisRange =TTextRange :: GetMaximumRange ()) const

Interface Category:

API.

Purpose:

Compares the character and style information of this text object with the input text object. Compares two text objects in their entirety or compares a text range in one text object with a different text range in the other text object.

Calling Context:

Called to compare all of one text object against all of another text object.
Called to compare a text range in one text object against a different text range in another text object.

Parameters:

const TText & that -The text object to compare against this text object.
const TText & that -The text object to compare against this text object.
const TTextRange & thatRange -The text range in that text object to be compared against text from this text object.
const TTextRange & thisRange =TTextRange :: GetMaximumRange () -The text range in this text object to be compared against the text from that text object.

Return Value:

Returns true if the characters and styles compared between the two text objects are equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Member Function: TText::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Generates a hash value.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The hash value.

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.