Class: TStyleRuns

Declaration: TextStyleRuns.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

TCharacterStyleRuns TParagraphStyleRuns

Purpose:

TStyleRuns is an abstract base class which provides the protocol required to manage how styles of a given kind are to be applied to text. Classes derived from TStyleRuns supply a mechanism for specifying style sets for particular ranges of text. They associate a given style set with a given range of text, and provide information about the style sets present within the text. A style run is the term used to describe a maximal contiguous range of text with the same style information. Examples of the sort of style information maintained by classes derived from TStyleRuns include character formatting information such as point size, paragraph formatting information such as margins and tab stops, and boundary information such as where one paragraph ends and another begins.

Instantiation:

Always allocate on the heap.

Deriving Classes:

Classes deriving from TStyleRuns must override all of the member functions in order to provide the correct behavior for a given kind of style. Polymorphic assignment of one TStyleRuns object to another is not supported, so the assignment operator should be protected. Styles and TStyleRuns objects are linked together by their kind. A style will only be added to the TStyleRuns object for which calling GetKind returns the same value for both the style and the TStyleRuns object. The value returned by GetKind must be unique for each class deriving from TStyleRuns. Classes deriving from TStyleRuns should maintain a const static TStyleKind, 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: TStyleRuns::~TStyleRuns

virtual ~ TStyleRuns ()

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: TStyleRuns::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: TStyleRuns::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 no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyleRuns::InitializeRuns

virtual void InitializeRuns (const TText & theText)

Interface Category:

API.

Purpose:

Initializes the newly created TStyleRuns object. This member function should be overridden to perform any actions that need to be done the first time the corresponding kind of style is applied to the text. For instance, for TParagraphStyleRuns this member function is overridden to iterate over the characters in the text to determine where the paragraph boundaries are.

Calling Context:

Called by TStyleKind::CreateStyleRuns to initialize the newly created TStyleRuns object.

Parameters:

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

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyleRuns::HasStyles

virtual bool HasStyles () const

Interface Category:

API.

Purpose:

Determines if the TStyleRuns object contains any style information. Note that style information may include information that is determined from the characters in the text. For instance, TParagraphStyleRuns objects maintain information about where the paragraph boundaries are. This information is determined from the characters that are inserted or removed from the text. This boundary information is considered to be style information.

Calling Context:

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

Parameters:

Takes no parameters.

Return Value:

Returns true if the TStyleRuns 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: TStyleRuns::GetKind

virtual const TStyleKind & GetKind () const

Interface Category:

API.

Purpose:

Styles and TStyleRuns objects are linked together by their kind. A style will only be added to the TStyleRuns object for which calling GetKind returns the same value for both the style and the TStyleRuns object. The value returned by GetKind must be unique for each class deriving from TStyleRuns. Classes deriving from TStyleRuns should maintain a const static TStyleKind, 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.

Calling Context:

Called to determine if the TStyleRuns object knows about a given kind of style.

Parameters:

Takes no parameters.

Return Value:

Returns the style kind that the TStyleRuns object knows about.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The member function GetKind returns a const reference to the TStyleKind object, so the TStyleKind should be a static member of the class that will never go out of scope.

Member Function: TStyleRuns::GetLength

virtual TTextCount GetLength () const

Interface Category:

API.

Purpose:

Returns the total length of the set of style runs that the TStyleRuns 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 length of the set of style runs that the TStyleRuns object currently has.

Parameters:

Takes no parameters.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyleRuns::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:

This member function must be called before the characters are actually removed from the corresponding TText object, 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: TStyleRuns::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:

This member function must be called after the new characters have been inserted into the corresponding TText object, 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: TStyleRuns::HandleCopyStyles

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

Interface Category:

API.

Purpose:

Copies the styles from a specified range of a specified TText object into the TStyleRuns object, where the TStyleRuns 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. 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 when copying 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 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 TStyleRuns 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: TStyleRuns::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 TStyleRuns object corresponds. The TStyleRuns object is responsible for ensuring that only styles of the corresponding kind are added.

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: TStyleRuns::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 TStyleRuns object, where the TStyleRuns object corresponds to a different TText object. 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 when copying 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 TStyleRuns 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: TStyleRuns::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 TStyleRuns 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 TStyleRuns 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 TStyleRuns 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: TStyleRuns::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 TStyleRuns object corresponds.

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: TStyleRuns::PartialCopy

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

Interface Category:

API.

Purpose:

Creates a new TStyleRuns object of the same kind as the current TStyleRuns 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 TStyleRuns 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 TStyleRuns 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 TStyleRuns 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: TStyleRuns::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 style set 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 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 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: TStyleRuns::GetStyleBounds

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

Interface Category:

API.

Purpose:

Determines the maximal contiguous 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 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: TStyleRuns::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 styles of the corresponding kind in the specified style set. This function only considers styles of the kind that the TStyleRuns object maintains; e.g the GetKind member function for the style and the TStyleRuns object returns the same value.

Calling Context:

Called directly to check for the existence of the specified 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 the styles of the corresponding 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: TStyleRuns::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: TStyleRuns::GetStylesInRange

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

Interface Category:

API.

Purpose:

Gets the maximal set of styles that the TStyleRuns 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 TStyleRuns 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 TStyleRuns object. They are not to be deleted.

Member Function: TStyleRuns::GetContinuousStyles

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

Interface Category:

API.

Purpose:

Gets the maximal set of continuous styles that the TStyleRuns 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 TStyleRuns 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: TStyleRuns::TStyleRuns

TStyleRuns ()

Interface Category:

API.

Purpose:

Default constructor.

Calling Context:

TStyleRuns is an abstract base class, so this constructor is protected and may not be called directly. This constructor is only called by the constructors of derived classes of TStyleRuns, such as TCharacterStyleRuns and TParagraphStyleRuns.

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.