Class: TStyleRunsGroup

Declaration: StyleRunsGroup.h

Taxonomy Categories:

Member Functions:

~TStyleRunsGroup
operator>>=
operator<<=
HasStyles
GetStyleKinds
GetLength
HandleDelete
HandleInsertGap
HandleCopyStyles
AddStyles
CopyStyles
RemoveStyles
ReplaceStyles
StylesAt
GetStyleBounds
StylesExist
StylesContinuous
GetStylesInRange
GetContinuousStyles
TStyleRunsGroup

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

None.

Purpose:

A TStyleRunsGroup object encapsulates all of the style information and modifications for the text that created it. TStyleRunsGroup is a concrete class that contains a collection of TStyleRuns objects. A TStyleRuns object maintains the styles of a particular kind as they are applied to the text; see descriptions of TStyleKind and TStyleRuns. Whenever a TStandardText object is modified, one or more of the member functions HandleDelete, HandleInsertGap, and HandleCopyStyles is called on the corresponding TStyleRunsGroup object. These member functions iterate through each TStyleRuns object in the collection, calling the corresponding member function on each. A style run is the term used to describe a maximal contiguous range of text with the same style information.

Instantiation:

Always allocate on the heap.

Deriving Classes:

Derive classes from TStyleRunsGroup in order to override the current behavior.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TStyleRunsGroup::~TStyleRunsGroup

virtual ~ TStyleRunsGroup ()

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: TStyleRunsGroup::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 the object streams itself 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:

None.

Member Function: TStyleRunsGroup::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 the object streams itself in from.

Return Value:

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

Exceptions:

Throws exception TTextException::kInvalidVersionNumber when the streamed in version number cannot be handled.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyleRunsGroup::HasStyles

virtual bool HasStyles () const

Interface Category:

API.

Purpose:

Determines if the TStyleRunsGroup object contains any style information.

Calling Context:

Called to find out if there is any style information applied to the text that the TStyleRunsGroup corresponds to.

Parameters:

Takes no parameters.

Return Value:

Returns true if the TStyleRunsGroup 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: TStyleRunsGroup::GetStyleKinds

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

Interface Category:

API.

Purpose:

Gets the complete set of style kinds that the TStyleRunsGroup contains. Use this member function when you need to get all of the styles in a particular range, regardless of style kind. For instance, if you need to get all of the styles at a given index, use this member function to get all of the style kinds, then iterate through the returnSet calling StylesAt for each kind.

Calling Context:

Called to get the complete set of style kinds that are applied to the text that the TStyleRunsGroup applies to.

Parameters:

TSetOf < TStyleKind > & returnSet -The set to be filled in.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Do not delete or modify the TStyleKind objects in the resulting set. The set can be deleted, but not the contents.

Member Function: TStyleRunsGroup::GetLength

virtual TTextCount GetLength (const TStyleKind & styleKind) const

Interface Category:

API.

Purpose:

Determines the length of the style runs for the given style kind. As an example, consider a TStandardText object of length 10 that has character-based styles applied to the characters at index 4 and 5. There will be three style runs, the first from index 0 to 3 containing no styles, the second from index 4 to 5 containing the character-based styles, and the third from index 6 to 9 containing no styles. The total length of these style runs is 10, so GetLength returns 10 even though only 2 characters have styles applied to them.

Calling Context:

Called to get the total length of the style runs for the given style kind.

Parameters:

const TStyleKind & styleKind -The style kind of interest.

Return Value:

Returns the total length of the style runs for the given style kind.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyleRunsGroup::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 text. This member function iterates over the collection of TStyleRuns, calling HandleDelete on each.

Calling Context:

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:

This member function must be called before the characters are actually removed from the corresponding TText object, because the characters can 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 have to be updated to take this into account.

Member Function: TStyleRunsGroup::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 text. This member function iterates over the collection of TStyleRuns, calling HandleInsertGap on each.

Calling Context:

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:

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

Member Function: TStyleRunsGroup::HandleCopyStyles

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

Interface Category:

API.

Purpose:

Copies the styles from a specified range of a given TText object into the TStyleRunsGroup corresponding to another 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 of the text that the styles are being copied into becomes unstyled. The behavior of HandleCopyStyles and CopyStyles can 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 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 thatLength -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 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: TStyleRunsGroup::AddStyles

virtual void AddStyles (const TStyle & newStyle, const TTextRange & range, const TText & thisText)
virtual void AddStyles (const TStyleSet & newStyles, const TTextRange & range, const TText & thisText, const TStyleKind & styleKind)

Interface Category:

API.

Purpose:

Adds the specified style to the corresponding TStyleRuns object within the specified text range. The member function GetKind is called on the style and on each TStyleRuns object in the collection to determine which TStyleRuns object can manage the given style. If no corresponding TStyleRuns object is found, the member function CreateStyleRuns is polymorphically called on the style kind to create the corresponding TStyleRuns object. The style is added to the new TStyleRuns object, and the new TStyleRuns object is added to the collection managed by TStyleRunsGroup.
Adds the styles of the specified kind to the corresponding TStyleRuns object within the specified text range. A style set can consist of styles of different kinds, so the style kind must be supplied to indicate which styles in the set to add.

Calling Context:

Called directly to add a single style.
Called directly to add styles of a particular kind from a given style set.

Parameters:

const TStyle & newStyle -The style to add.
const TTextRange & range -The text range to add the single style to.
const TText & thisText -The text that the style is being added to.
const TStyleSet & newStyles -The set of styles to add.
const TTextRange & range -The text range to add the set of styles to.
const TText & thisText -The text that the set of styles is being added to.
const TStyleKind & styleKind -The kind of styles to add.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyleRunsGroup::CopyStyles

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

Interface Category:

API.

Purpose:

Copies the styles from a specified range of a given TText object into the TStyleRunsGroup corresponding to another TText object. The behavior of HandleCopyStyles and CopyStyles can 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 & 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 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: TStyleRunsGroup::RemoveStyles

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

Interface Category:

API.

Purpose:

Removes the specified style from the specified range of text.
Removes the styles of the specified kind that are in the given style from the specified range of text. A style set can consist of styles of different kinds, so the style kind must be supplied to indicate which styles in the set to remove.
Removes the styles of the specified name, category, and kind from the specified range of text.
Removes the styles of the specified kind from the specified range of text

Calling Context:

Called directly to remove the specified style.
Called directly to remove the specified styles.
Called directly to remove the specified styles.
Called directly to remove the specified styles.

Parameters:

const TStyle & style -The style to be removed.
const TTextRange & range -The range of text to remove the style from.
const TStyleSet & set -The style set containing the styles to be removed.
const TTextRange & range -The range of text to remove the styles from.
const TStyleKind & styleKind -The kind of the styles that are to be removed.
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 of text to remove the styles from.
const TStyleKind & styleKind -The kind of the styles that are to be removed.
const TStyleKind & styleKind -The kind of the styles that are to be removed.
const TTextRange & range -The range of text 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: TStyleRunsGroup::ReplaceStyles

virtual void ReplaceStyles (const TStyle & newStyle, const TTextRange & range, const TText & thisText)
virtual void ReplaceStyles (const TStyleSet & newStyles, const TTextRange & range, const TStyleKind & styleKind, const TText & thisText)

Interface Category:

API.

Purpose:

ReplaceStyles is equivalent to removing the current styles of the specified kind from the specified range, and then adding the specified styles to the specified range.

Replaces existing styles with the specified style.
Replaces existing styles with the specified styles. A style set can consist of styles of different kinds, so the style kind must be supplied to indicate which styles are to be removed and which styles in the set are to be added.

Calling Context:

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

Parameters:

const TStyle & newStyle -The style to add after removing the existing styles.
const TTextRange & range -The range of text to replace the styles in.
const TText & thisText -The TText object that the styles correspond to.
const TStyleSet & newStyles -The styles to add after removing the existing styles.
const TTextRange & range -The range of text to replace the styles in.
const TStyleKind & styleKind -The kind of styles to remove and add.
const TText & thisText -The TText object that the styles correspond to.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyleRunsGroup::StylesAt

virtual TTextIndex StylesAt (TTextIndex indexOfInterest, TStyleSet & returnSet, TTextRange & currentRange, const TStyleKind & styleKind, const TText & thisText) const
virtual TTextIndex StylesAt (TTextIndex indexOfInterest, TStyleSet & returnSet, const TStyleKind & styleKind, const TText & thisText) const

Interface Category:

API.

Purpose:

Fills in the given style set with the styles of a specified kind that are applied to a specified index of the text. When needed, callers can 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 and the maximal contiguous text range that contains the same style information and the index of interest.
Called directly to get the styles for a specified index.

Parameters:

TTextIndex indexOfInterest -The index to get styles for.
TStyleSet & returnSet -The output style set to copy the styles for the specified index into.
TTextRange & currentRange -The maximal contiguous text range that contains the output styles and overlaps the index of interest.
const TStyleKind & styleKind -The styles kind of interest.
const TText & thisText -The TText object that the styles correspond to.
TTextIndex indexOfInterest -The index to get styles for.
TStyleSet & returnSet -The output style set to copy the styles for the specified index into.
const TStyleKind & styleKind -The styles kind of interest.
const TText & thisText -The TText object that the styles correspond to.

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:

None.

Member Function: TStyleRunsGroup::GetStyleBounds

virtual void GetStyleBounds (TTextIndex indexOfInterest, TTextRange & currentRange, const TStyleKind & styleKind, const TText & thisText) 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 is 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 & currentRange -The resulting range.
const TStyleKind & styleKind -The kind of styles to look at.
const TText & thisText -The TText object that the styles correspond to.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyleRunsGroup::StylesExist

virtual bool StylesExist (const TStyleSet & theSet, const TTextRange & theRange, const TStyleKind & styleKind) 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 & theSet -The styles to look for.
const TTextRange & theRange -The text range to look at.
const TStyleKind & styleKind -The kind of styles to look at.

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. Returns false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyleRunsGroup::StylesContinuous

virtual bool StylesContinuous (const TStyleSet & theSet, const TTextRange & theRange) 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 & theSet -The styles to look for.
const TTextRange & theRange -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: TStyleRunsGroup::GetStylesInRange

virtual void GetStylesInRange (TSetOf < TStyle > & returnSet, const TStyleKind & styleKind, const TTextRange & range) 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. 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. More than one style with the same name is not allowed in the same TStyleSet.

Calling Context:

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

Parameters:

TSetOf < TStyle > & returnSet -The output set to fill in. Any objects in this set at the time of the call are removed before filling the set with the styles found. The styles in the resulting set are owned by the text. They are not to be deleted.
const TStyleKind & styleKind -The kind of styles to look at.
const TTextRange & range -The text 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 text. Do not delete them.

Member Function: TStyleRunsGroup::GetContinuousStyles

virtual void GetContinuousStyles (TStyleSet & returnSet, const TStyleKind & styleKind, const TTextRange & range) const

Interface Category:

API.

Purpose:

Gets the maximal set of continuous styles of a 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 a specified kind associated with a specified text range.

Parameters:

TStyleSet & 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 styles found.
const TStyleKind & styleKind -The kind of styles to look at.
const TTextRange & range -The text range to look at.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyleRunsGroup::TStyleRunsGroup

TStyleRunsGroup ()

Interface Category:

API.

Purpose:

Default constructor.

Calling Context:

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