Class: TCharacterStyleRuns

Declaration: CharacterStyleRuns.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TStyleRuns

Inherited By:

None.

Purpose:

TCharacterStyleRuns is concrete class that implements the protocol to manage character-based styles as they are applied to text. Character-based styles are styles that can be applied to a range of characters or a substring of text. These include character formatting information such as point size, weight (bold/regular), and tracking, as well as non-formatting information such as language. Each TCharacterStyleRuns object maintains styles whose GetKind member function returns a reference to a TCharacterStyleKind object. Styles whose GetKind member function returns an object of type other than TCharacterStyleKind are ignored.

Instantiation:

Always allocate on the heap.

Deriving Classes:

Styles and TCharacterStyleRuns objects are linked together by their kind. A style will only be added to the TCharacterStyleRuns object for which calling GetKind returns the same value for both the style and the TCharacterStyleRuns object. The value returned by GetKind must be unique for each class deriving either directly or indirectly from TStyleRuns. Classes deriving either directly or indirectly from TStyleRuns should maintain a const static TStyleKind data member, because the member function GetKind returns a const reference to the TStyleKind object. Having the TStyleKind object as a static data member ensures that the value returned by GetKind will never go out of scope.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TCharacterStyleRuns::~TCharacterStyleRuns

virtual ~ TCharacterStyleRuns ()

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: TCharacterStyleRuns::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 into.

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:

None.

Member Function: TCharacterStyleRuns::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 from.

Return Value:

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

Exceptions:

Throws the exception TTextException::kInvalidVersionNumber if the version number is not supported.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCharacterStyleRuns::InitializeRuns

virtual void InitializeRuns (const TText & theText)

Interface Category:

API.

Purpose:

Initializes the newly created TCharacterStyleRuns object.

Calling Context:

Called by TCharacterStyleKind::CreateStyleRuns to initialize the newly created TCharacterStyleRuns object.

Parameters:

const TText & theText -The text that the TCharacterStyleRuns object corresponds to.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCharacterStyleRuns::HasStyles

virtual bool HasStyles () const

Interface Category:

API.

Purpose:

Determines if the TCharacterStyleRuns object contains any style information.

Calling Context:

Called to determine if a TCharacterStyleRuns object contains any style information.

Parameters:

Takes no parameters.

Return Value:

Returns true if the TCharacterStyleRuns object contains any style information. Returns false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCharacterStyleRuns::GetKind

virtual const TStyleKind & GetKind () const

Interface Category:

API.

Purpose:

Calling Context:

Called to determine which kind of style the TCharacterStyleRuns object knows about.

Parameters:

Takes no parameters.

Return Value:

Returns the style kind that the TCharacterStyleRuns object knows about. The object that is returned is a static data member of TCharacterStyleRuns, which must not be modified.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCharacterStyleRuns::GetLength

virtual TTextCount GetLength () const

Interface Category:

API.

Purpose:

Returns the total length of the set of style runs that the TCharacterStyleRuns object currently has. A style run is the term used to describe a maximal contiguous range of text with the same style information.

Calling Context:

Called to determine the total length of the set of style runs that the TCharacterStyleRuns object currently has.

Parameters:

Takes no parameters.

Return Value:

Returns the length of the set of style runs that the TCharacterStyleRuns object currently has.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCharacterStyleRuns::HandleDelete

virtual void HandleDelete (const TText & textToBeModified, TTextOffset beginOffset, TTextCount length)

Interface Category:

API.

Purpose:

Updates the style runs when characters are going to be deleted from the corresponding TText object.

Calling Context:

This member function is called when characters are going to be removed from the corresponding TText object.

Parameters:

const TText & textToBeModified -The TText object that the characters are going to be removed from.
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:

None.

Member Function: TCharacterStyleRuns::HandleInsertGap

virtual void HandleInsertGap (const TText & modifiedText, TTextOffset beginOffset, TTextCount length)

Interface Category:

API.

Purpose:

Updates the style runs when new characters have been inserted into the corresponding TText object.

Calling Context:

This member function is called when new characters have been inserted into the corresponding TText object.

Parameters:

const TText & modifiedText -The TText object that had the new characters inserted into it.
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:

None.

Member Function: TCharacterStyleRuns::HandleCopyStyles

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

Interface Category:

API.

Purpose:

Copies the character-based styles from a specified range of a specified TText object into the TCharacterStyleRuns object, where the TCharacterStyleRuns object corresponds to a different TText object. 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 that the styles are being copied into becomes unstyled.

Calling Context:

Called when copying the character-based 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 HandleInsertGap 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 thatCount -The length of the range of styles to be copied.
TTextOffset thisOffset -The beginning offset where the styles are to be copied into.
const TText & thisText -The TText object that the TCharacterStyleRuns object to be modified corresponds to.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCharacterStyleRuns::AddStyles

virtual void AddStyles (const TStyle & newStyle, const TTextRange & range)
virtual void AddStyles (const TStyleSet & newStyles, const TTextRange & range)

Interface Category:

API.

Purpose:

Adds the given style or style set to the specified range, where the specified range is a range of characters in the text to which the TCharacterStyleRuns object corresponds. The TCharacterStyleRuns object will only add character-based styles; e.g. styles whose GetKind member function returns a reference to a TCharacterStyleKind object.

Calling Context:

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

Parameters:

const TStyle & newStyle -The style to add.
const TTextRange & range -The range to add the single style to.
const TStyleSet & newStyles -The set of styles to add.
const TTextRange & range -The range to add the set of styles to.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCharacterStyleRuns::CopyStyles

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

Interface Category:

API.

Purpose:

Copies the character-based styles from a specified range of a given TText object into the TCharacterStyleRuns object, where the TCharacterStyleRuns object corresponds to a different TText object. The TCharacterStyleRuns object will only copy character-based styles; styles whose GetKind member function returns a reference to a TCharacterStyleKind object.

Calling Context:

Called when copying the character-based styles from one TText object into another.

Parameters:

const TText & thatText -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.
const TText & thisText -The TText object that the TCharacterStyleRuns object to be modified corresponds to.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCharacterStyleRuns::RemoveStyles

virtual void RemoveStyles (const TStyleCategory & category, const TStyleName & name, const TTextRange & range)
virtual void RemoveStyles (const TStyle & style, const TTextRange & range)
virtual void RemoveStyles (const TStyleSet & set, const TTextRange & range)
virtual void RemoveStyles (const TTextRange & range)

Interface Category:

API.

Purpose:

Removes the specified styles from the specified range, where the specified range is a range of characters in the text to which the TCharacterStyleRuns object corresponds.

Removes the style with the specified name and category from the specified range.
Removes the specified style from the specified range.
Removes the specified styles from the specified range.
Removes all of the styles that are maintained by the TCharacterStyleRuns object from the specified range.

Calling Context:

Called directly to remove the specified style.
Called directly to remove the specified style.
Called directly to remove the specified styles.
Called directly to remove the all of the styles that are maintained by the TCharacterStyleRuns object from a particular range.

Parameters:

const TStyleCategory & category -The category of the styles that are to be removed.
const TStyleName & name -The name of styles that are to be removed.
const TTextRange & range -The range to remove the styles from.
const TStyle & style -The style to be removed.
const TTextRange & range -The range to remove the styles from.
const TStyleSet & set -The style set containing the styles to be removed.
const TTextRange & range -The range to remove the styles from.
const TTextRange & range -The range to remove the styles from.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCharacterStyleRuns::ReplaceStyles

virtual void ReplaceStyles (const TStyle & newStyle, const TTextRange & range)
virtual void ReplaceStyles (const TStyleSet & newStyles, const TTextRange & range)

Interface Category:

API.

Purpose:

ReplaceStyles is equivalent to removing the current styles from the specified range, and then adding the specified styles to the specified range. The specified range is a range of characters in the text to which the TCharacterStyleRuns object corresponds. The TCharacterStyleRuns object will only add character-based styles; styles whose GetKind member function returns a reference to a TCharacterStyleKind object.

Replaces existing styles with the specified style.
Replaces existing styles with the specified style set.

Calling Context:

Called directly to replace existing styles with the specified style.
Called directly to replace existing styles with the specified style set.

Parameters:

const TStyle & newStyle -The style to add after removing the existing styles.
const TTextRange & range -The range to replace styles in.
const TStyleSet & newStyles -The set of styles to add after removing the existing styles.
const TTextRange & range -The range to replace styles in.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCharacterStyleRuns::PartialCopy

virtual TStyleRuns * PartialCopy (TTextOffset thisOffset, TTextCount thisLength, TTextOffset thatOffset, const TText & theText, TMemoryHeap * whichHeap =NIL) const

Interface Category:

API.

Purpose:

Creates a new TCharacterStyleRuns object then copies the styles from the specified specified range into the new object starting at the specified offset.

Calling Context:

Called directly to get a polymorphic copy of any part of a TCharacterStyleRuns object.

Parameters:

TTextOffset thisOffset -The offset at the beginning of the range of styles to be copied.
TTextCount thisLength -The length of the range of styles to be copied.
TTextOffset thatOffset -The beginning offset where the styles are to be copied into.
const TText & theText -The text that the new TCharacterStyleRuns object will correspond to.
TMemoryHeap * whichHeap =NIL -The heap in which the new object is to be allocated.

Return Value:

Returns a pointer to a new TCharacterStyleRuns object. The caller of this member function is responsible for the storage of the returned object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a copy function that passes ownership of new storage to the client.

Member Function: TCharacterStyleRuns::StylesAt

virtual TTextIndex StylesAt (TTextIndex indexOfInterest, TStyleSet & returnSet, TTextRange & returnRange) const
virtual TTextIndex StylesAt (TTextIndex indexOfInterest, TStyleSet & returnSet) const

Interface Category:

API.

Purpose:

Determines the set of character-based styles associated with the specified index. When it matters, callers can also get the maximal contiguous range with the same style information that contains the specified index.

Calling Context:

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

Parameters:

TTextIndex indexOfInterest -The index to get styles for.
TStyleSet & returnSet -The output style set to copy the styles into.
TTextRange & returnRange -The maximal contiguous range that contains the output styles and overlaps the index of interest.
TTextIndex indexOfInterest -The index to get styles for.
TStyleSet & returnSet -The output style set to copy the styles into.

Return Value:

The starting index of the next style run. A style run is the term used to describe a maximal contiguous 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: TCharacterStyleRuns::GetStyleBounds

virtual void GetStyleBounds (TTextIndex indexOfInterest, TTextRange & returnRange) const

Interface Category:

API.

Purpose:

Determines the maximal contiguous range with the same character-based style information that contains the specified index.

Calling Context:

Called directly to obtain boundary information about the character-based styles at a specified index.

Parameters:

TTextIndex indexOfInterest -The index to get the style boundary information for.
TTextRange & returnRange -The resulting boundary information.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCharacterStyleRuns::StylesExist

virtual bool StylesExist (const TStyleSet & theSet, const TTextRange & range) const

Interface Category:

API.

Purpose:

Determines if any index within the specified range contains all of the character-based styles in the specified style set. This function only considers character-based styles; styles whose GetKind member function returns a reference to a TCharacterStyleKind object.

Calling Context:

Called directly to check for the existence of the specified character-based styles anywhere within the specified range.

Parameters:

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

Return Value:

Returns true if at least one index within the specified range contains all of the character-based styles in the specified style set. Returns false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCharacterStyleRuns::StyleContinuous

virtual bool StyleContinuous (const TStyle & theStyle, const TTextRange & range) const

Interface Category:

API.

Purpose:

Determines if every index within the specified range contains the specified style.

Calling Context:

Called directly to determine if a given style is continuous over a given range.

Parameters:

const TStyle & theStyle -The style to look for.
const TTextRange & range -The range to look at.

Return Value:

Returns true if every index within the specified range contains the specified style. Returns false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCharacterStyleRuns::GetStylesInRange

virtual void GetStylesInRange (TSetOf < TStyle > & resultingSet, const TTextRange & range) const

Interface Category:

API.

Purpose:

Get the maximal set of styles that the TCharacterStyleRuns object has in the specified range. It is not required that styles in the resulting set be continuous throughout the entire range. It only matters that a style exist at one or more indices in the range for it to be included in this maximal set of styles. When two styles with the same name and different values exist, both styles are included in the resulting union. This is why a collection of TStyle pointers is returned instead of a TStyleSet, as more than one style with the same name is not allowed in the same TStyleSet.

Calling Context:

Called to get the maximal set of styles that the TCharacterStyleRuns object has in the specified range.

Parameters:

TSetOf < TStyle > & resultingSet -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 range to look at.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The styles in the resulting set are owned by the TCharacterStyleRuns object. They are not to be deleted.

Member Function: TCharacterStyleRuns::GetContinuousStyles

virtual void GetContinuousStyles (TStyleSet & resultingSet, const TTextRange & range) const

Interface Category:

API.

Purpose:

Gets the maximal set of continuous styles that the TCharacterStyleRuns object has in the specified range. It is required that styles in the resulting set be continuous throughout the entire range.

Calling Context:

Called directly to get the maximal set of continuous styles that the TCharacterStyleRuns object has in a particular range.

Parameters:

TStyleSet & resultingSet -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 range to look at.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCharacterStyleRuns::GetStyleKind

static const TStyleKind & GetStyleKind ()

Interface Category:

API.

Purpose:

This is a static member function for obtaining a reference to a TCharacterStyleKind object which is used to indicate character-based styles. This is the value returned by the GetKind member function of character-based styles and TCharacterStyleRuns objects. Character-based styles are styles that can be applied to a range of characters or a substring of text. These include character formatting information such as point size, weight (bold/regular), and tracking, as well as non-formatting information such as language.

Calling Context:

Called to obtain a reference to a TCharacterStyleKind object which is used to indicate character-based styles.

Parameters:

Takes no parameters.

Return Value:

Returns a reference to a TCharacterStyleKind object which is used to indicate character-based styles. The returned object is a static data member of TCharacterStyleRuns. As such it should never be modified, and will not go out of scope.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCharacterStyleRuns::TCharacterStyleRuns

TCharacterStyleRuns ()

Interface Category:

API.

Purpose:

Default constructor.

Calling Context:

Called directly to create a new TCharacterStyleRuns 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.