Class: TParagraphStyleRuns

Declaration: ParagraphStyleRuns.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TStyleRuns

Inherited By:

None.

Purpose:

TParagraphStyleRuns is a concrete class that is a mechanism for specifying style sets for ranges of text that are delimited with paragraph markers. TParagraphStyleRuns objects associate a style set with a each paragraph in the text, and provide information about the paragraph styles that are present within the text. A paragraph is a contiguous range of text terminated by a new paragraph marker or the last character in the model. A paragraph always contains at least a single character, which can be a paragraph marker. Each TParagraphStyleRuns object maintains styles whose GetKind member function returns a reference to a TParagraphStyleKind object. Styles whose GetKind member function returns an object of type other than TParagraphStyleKind are ignored.

Instantiation:

Always allocate on the heap.

Deriving Classes:

Styles and TParagraphStyleRuns objects are linked together by their kind. A style is only added to the TParagraphStyleRuns object for which calling GetKind returns the same value for both the style and the TParagraphStyleRuns 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 never goes out of scope.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TParagraphStyleRuns::~TParagraphStyleRuns

virtual ~ TParagraphStyleRuns ()

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: TParagraphStyleRuns::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: TParagraphStyleRuns::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 the exception TTextException::kInvalidVersionNumber if the version number is not supported.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TParagraphStyleRuns::InitializeRuns

virtual void InitializeRuns (const TText & theText)

Interface Category:

API.

Purpose:

Initializes the newly created TParagraphStyleRuns object by iterating over the characters in the text to determine where the paragraph boundaries are.

Calling Context:

Called by TParagraphStyleKind::CreateStyleRuns to initialize the newly created TParagraphStyleRuns object.

Parameters:

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

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TParagraphStyleRuns::HasStyles

virtual bool HasStyles () const

Interface Category:

API.

Purpose:

Determines if the TParagraphStyleRuns object contains any style information. TParagraphStyleRuns objects maintain information about where the paragraph boundaries are based on the characters that are inserted or removed from the text. This boundary information is considered to be style information, so if there is more than one paragraph in the text the TParagraphStyleRuns object has style information and HasStyles returns true. If there is only one paragraph that has paragraph style information such as margins, HasStyles also returns true. HasStyles only returns false if there is exactly one paragraph in the text, and it does not have any paragraph-based styles associated with it.

Calling Context:

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

Parameters:

Takes no parameters.

Return Value:

Returns false if there is exactly one paragraph in the text, and it does not have any paragraph-based styles associated with it. Returns true otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TParagraphStyleRuns::GetKind

virtual const TStyleKind & GetKind () const

Interface Category:

API.

Purpose:

Calling Context:

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

Parameters:

Takes no parameters.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TParagraphStyleRuns::GetLength

virtual TTextCount GetLength () const

Interface Category:

API.

Purpose:

Returns the total length of the set of style runs that the TParagraphStyleRuns object currently has. A style run is the term used to describe a maximal contiguous range of text with the same style information. For TParagraphStyleRuns, a style run corresponds to a paragraph, where a paragraph is a contiguous range of text terminated by a new paragraph character or the last character in the model. A paragraph always contains at least a single character (kParagraphSeparator or kEndOfText).

Calling Context:

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

Parameters:

Takes no parameters.

Return Value:

Returns the total length of the set of style runs that the TParagraphStyleRuns object currently has. This is the sum of the lengths of the paragraphs, where the length of a paragraph includes the paragraph marker.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

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

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 affect how the style runs should be updated. For instance, if a paragraph marker is one of the characters being removed, the two adjoining style runs are merged.

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

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 affect how the style runs should be updated. For instance, if a paragraph marker is added, the affected style run is divided into two style runs.

Member Function: TParagraphStyleRuns::HandleCopyStyles

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

Interface Category:

API.

Purpose:

Copies the paragraph-based styles from a specified range of a specified TText object into the TParagraphStyleRuns object, where the TParagraphStyleRuns 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 is different. 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 paragraph-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 TParagraphStyleRuns 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: TParagraphStyleRuns::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 TParagraphStyleRuns object corresponds. The styles are added to each paragraph that the specified range intersects. If the specified range is of length zero, the styles are added to the paragraph containing the beginning offset of the range. The TParagraphStyleRuns object only adds paragraph-based styles; for example, styles whose GetKind member function returns a reference to a TParagraphStyleKind 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: TParagraphStyleRuns::CopyStyles

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

Interface Category:

API.

Purpose:

Copies the paragraph-based styles from a specified range of a given TText object into the TParagraphStyleRuns object, where the TParagraphStyleRuns object corresponds to a different TText object. The styles are copied into each paragraph that the specified range intersects. If the specified range is of length zero, the styles are copied into the paragraph containing the beginning offset of the range. CopyStyles copies the paragraph-based styles from the first paragraph that intersects the specified range into all of the paragraphs starting at the specified offset and extending to the end of the specified range. In contrast, HandleCopyStyles copies the styles paragraph-by-paragraph. The TParagraphStyleRuns object only copies paragraph-based styles; for example, styles whose GetKind member function returns a reference to a TParagraphStyleKind object.

Calling Context:

Called when copying the paragraph-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 TParagraphStyleRuns 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: TParagraphStyleRuns::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 TParagraphStyleRuns object corresponds. The styles are removed from each paragraph that the specified range intersects. If the specified range is of length zero, the styles are removed from the paragraph containing the beginning offset of the range.

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 TParagraphStyleRuns 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 TParagraphStyleRuns 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: TParagraphStyleRuns::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 TParagraphStyleRuns object corresponds. The styles are replaced in each paragraph that the specified range intersects. If the specified range is of length zero, the styles are replaced in the paragraph containing the beginning offset of the range. The TParagraphStyleRuns object only adds paragraph-based styles; for example, styles whose GetKind member function returns a reference to a TParagraphStyleKind 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: TParagraphStyleRuns::PartialCopy

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

Interface Category:

API.

Purpose:

Creates a new TParagraphStyleRuns object, then copies the styles from the specified specified range into the new object starting at the specified offset. The styles are copied from each paragraph that intersects the specified range.

Calling Context:

Called directly to get a polymorphic copy of any part of a TParagraphStyleRuns 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 TParagraphStyleRuns 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 TParagraphStyleRuns 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: TParagraphStyleRuns::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 paragraph-based styles associated with the specified index Callers can also get the bounds of the paragraph containing the specified index.

Calling Context:

Called directly to get the style set and bounds of the paragraph containing the index of interest.
Called directly to get the paragraph-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 bounds of the paragraph containing 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 paragraph.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TParagraphStyleRuns::GetStyleBounds

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

Interface Category:

API.

Purpose:

Determines the bounds of the paragraph containing the specified index.

Calling Context:

Called directly to obtain boundary information about the paragraph that contains a specified index.

Parameters:

TTextIndex indexOfInterest -The index to get the paragraph 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: TParagraphStyleRuns::StylesExist

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

Interface Category:

API.

Purpose:

Determines if any paragraph intersecting the specified range contains all of the paragraph-based styles in the specified style set. This function only considers paragraph-based styles; e.g styles whose GetKind member function returns a reference to a TParagraphStyleKind object.

Calling Context:

Called directly to check for the existence of the specified paragraph-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 paragraph intersecting the specified range contains all of the paragraph-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: TParagraphStyleRuns::StyleContinuous

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

Interface Category:

API.

Purpose:

Determines if every paragraph intersecting 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 paragraph intersecting 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: TParagraphStyleRuns::GetStylesInRange

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

Interface Category:

API.

Purpose:

Get the maximal set of styles that the TParagraphStyleRuns object has in all of the paragraphs that intersect 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 in one or more of the paragraphs that intersect the specified 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, because 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 TParagraphStyleRuns object has in all of the paragraphs that intersect 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 TParagraphStyleRuns object. Do not delete them.

Member Function: TParagraphStyleRuns::GetContinuousStyles

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

Interface Category:

API.

Purpose:

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

static const TStyleKind & GetStyleKind ()

Interface Category:

API.

Purpose:

A static member function for obtaining a reference to a TParagraphStyleKind object that is used to indicate paragraph-based styles. This is the value returned by the GetKind member function of paragraph-based styles and TParagraphStyleRuns objects. Paragraph-based styles are styles that can be applied to a paragraph of text, where a paragraph is a contiguous range of text terminated by a new paragraph character or the last character in the model. Paragraph-based styles contain paragraph formatting information, such as margins and tab stops.

Calling Context:

Called to obtain a reference to a TParagraphStyleKind object that is used to indicate paragraph-based styles.

Parameters:

Takes no parameters.

Return Value:

Returns a reference to a TParagraphStyleKind object that is used to indicate paragraph-based styles. The returned object is a static data member of TParagraphStyleRuns. 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: TParagraphStyleRuns::TParagraphStyleRuns

TParagraphStyleRuns ()

Interface Category:

API.

Purpose:

Default constructor.

Calling Context:

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