Class: TStyleSet

Declaration: StyleSet.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MReferencedCollectible

Inherited By:

None.

Purpose:

TStyleSet, derived from MReferencedCollectible, encapsulates a collection of text styles that can be applied to a range of characters. Although style sets are not immutable, the styles they contain are. You change a style set by adding and/or removing styles.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Although value semantics are used externally, derived classes must take into account the fact that copy-on-write semantics are used internally. The internal storage for style sets can be shared across multiple style sets with reference counting. However, modifications to one style set should never affect another one. Therefore, the implementation of member functions that change the contents of a style set must call CopySharedDataBeforeWrite before making changes. Derived classes must preserve the value semantics presented to clients of class TStyleSet. Reference counting is used with style sets at two levels. Internal storage is reference counted. Externally, the style sets as a whole can be reference counted too. The Unreachable member function is inherited from the mixin class, MReferenceCounted. As defined for class MReferenceCounted, Unreachable is called when the reference count on an object reaches zero. Normally, all that is necessary is to override the inherited version with one that deletes an instance of your derived class.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TStyleSet::MemberByValue

virtual bool MemberByValue (const TStyle & style) const
virtual bool MemberByValue (const TStyleSet & set) const
virtual bool MemberByValue (const TStyleSet & set, TStyleSet & members) const

Interface Category:

API.

Purpose:

Compares, by value, one or more styles against the contents of this style set. Two styles are equal when compared by value if the styles have the same category, name, and internal values.

Calling Context:

Called when checking a single style for membership in this style set.
Called when checking multiple styles for membership in this style set.
Called when checking multiple styles for membership in this style set and you want to know which styles were found when one or more of the styles being searched for were not found.

Parameters:

const TStyle & style -The input style to check for membership.
const TStyleSet & set -The input styles to check for membership.
const TStyleSet & set -The input styles to check for membership.
TStyleSet & members -The output styles that were found to be members of this style set and the input style set.

Return Value:

Returns true if all styles being checked for membership by value were found.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyleSet::MemberByName

virtual bool MemberByName (const TStyle & style) const
virtual bool MemberByName (const TStyleSet & set) const
virtual bool MemberByName (const TStyleCategory & category, const TStyleName & name) const
virtual bool MemberByName (const TStyle & style, const TStyle * & member) const
virtual bool MemberByName (const TStyleSet & set, TStyleSet & members) const
virtual bool MemberByName (const TStyleCategory & category, const TStyleName & name, const TStyle * & member) const

Interface Category:

API.

Purpose:

Compares, by name, one or more styles against the contents of this style set. Two styles are equal when compared by name if the styles have the same category and name. The internal values do not have to be the same to produce a match by name.

Calling Context:

Called when checking a single style for membership in this style set.
Called when checking multiple styles for membership in this style set.
Called when checking by style category and style name for a matching style in this style set.
Called when checking a single style for membership in this style set and you want to know the value of the matching style when one is found in this style set.
Called when checking multiple styles for membership in this style set and you want to know the value of the matching styles when one or more matches are found in this style set.
Called when checking by style category and style name for a matching style in this style set and you want to know the value of the matching style when one is found in this style set.

Parameters:

const TStyle & style -The style to check for membership.
const TStyleSet & set -The styles to check for membership.
const TStyleCategory & category -The category to use with the name to check for membership.
const TStyleName & name -The name to use with the category to check for membership.
const TStyle & style -The style to check for membership.
const TStyle * & member -When a match is found, the matching style is returned in this output parameter.
const TStyleSet & set -The styles to check for membership.
TStyleSet & members -When any matches are found, the matching style(s) are returned in this output parameter. When searching for multiple matches, it is possible for the return value of the function to be false and for this output parameter to still be filled in. In that situation, the subset of all the styles being checked for that did match is represented in the output style set.
const TStyleCategory & category -The category to use with the name to check for membership.
const TStyleName & name -The name to use with the category to check for membership.
const TStyle * & member -When a match is found, the matching style is returned in this output parameter.

Return Value:

Returns true if all styles being checked for membership are found.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyleSet::Add

virtual void Add (const TStyle & style)
virtual void Add (const TStyleSet & set)

Interface Category:

API.

Purpose:

Adds one or more styles to this style set.

Calling Context:

Called when adding a single style to this style set.
Called when adding multiple styles to this style set.

Parameters:

const TStyle & style -The style to add.
const TStyleSet & set -The styles to add.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Due to the invariant of style sets that there can never be two styles with the same category and name in the same style set, adding a style can effectively replace one style with another. This happens when the style being added is already represented in this style set by another style with the same category and name.

Member Function: TStyleSet::Remove

virtual void Remove (const TStyleCategory & category, const TStyleName & name)
virtual void Remove (const TStyle & style)
virtual void Remove (const TStyleSet & set)

Interface Category:

API.

Purpose:

Removes one or more styles from this style set.

Calling Context:

Called when removing the style with the specified category and specified name from this style set.
Called when removing a single style from this style set.
Called when removing multiple styles from this style set.

Parameters:

const TStyleCategory & category -The category to use with a name to find the matching style to remove.
const TStyleName & name -The name to use with a category to find the matching style to remove.
const TStyle & style -The style to remove.
const TStyleSet & set -The styles to remove.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyleSet::RemoveAll

virtual void RemoveAll ()

Interface Category:

API.

Purpose:

Removes all styles from this style set.

Calling Context:

Called when you want to remove all styles from a style set.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyleSet::RemoveNonPropagatingStyles

virtual void RemoveNonPropagatingStyles ()

Interface Category:

API.

Purpose:

Removes all nonpropagating styles from this style set.

Calling Context:

Called in word-processing software that wants to ignore the nonpropagating styles in a style set.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyleSet::Count

virtual long Count () const
virtual long Count (const TStyleCategory & category) const

Interface Category:

API.

Purpose:

Gets the total number of styles in this style set.
Gets the number of styles in the specified style category.

Calling Context:

Called when you need to know the total number of styles in a style set.
Called when you need to know the number of styles in a style set that are part of one particular category.

Parameters:

Takes no parameters.
const TStyleCategory & category -The category to be counted.

Return Value:

The number of styles for the entire style set or in the specified category only.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyleSet::CreateIterator

virtual TStyleSetIterator * CreateIterator () const
virtual TStyleSetIterator * CreateIterator (const TStyleCategory & category) const

Interface Category:

API.

Purpose:

Returns an iterator for the entire style set. Used to iterate over all the styles in a style set regardless of the category for each style.
Returns an iterator for the specified style category. Used to iterate over only the styles in the specified category.

Calling Context:

Called when iteration over all the styles is required.
Called when iteration over the styles in a single category is required.

Parameters:

Takes no parameters.
const TStyleCategory & category -The category to iterate over.

Return Value:

The newly created TStyleSetIterator is returned and ownership of the storage for this new object is passed to the caller.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyleSet::operator==

virtual bool operator ==(const TStyleSet & that) const

Interface Category:

API.

Purpose:

Compares two objects for equality. Two style sets are equal when they have exactly the same number of styles with the same values for each style in both sets.

Calling Context:

Called to compare two style sets for equality.

Parameters:

const TStyleSet & that -The style set to compare with this style set.

Return Value:

Returns true if the two style sets are equivalent. This does not mean they have to be the exact same style set though. It merely means that the contents of the two sets are the same.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyleSet::CopySharedDataBeforeWrite

virtual void CopySharedDataBeforeWrite ()

Interface Category:

API.

Purpose:

Makes a copy of internal data so that this style set has a reference count of one. Derived classes that add new member functions that modify the style set must call this member function to preserve the internal implementation of copy-on-write semantics.

Calling Context:

Called in a new member function added to a derived class of TStyleSet that changes the contents of the style set.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is only of concern to implementors of derived classes.

Member Function: TStyleSet::Unreachable

virtual void Unreachable ()

Interface Category:

API.

Purpose:

Deletes this object. Derived classes must override this member function to do the same thing for their derived classes.

Calling Context:

Not intended to be called directly by clients. Rather, the manager classes that keep track of reference counting on style sets call this member function when the reference count of a style set has reached zero.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyleSet::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Generates a hash value.

Calling Context:

Called to generate a hash value.

Parameters:

Takes no parameters.

Return Value:

The numeric value of the hash.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyleSet::operator!=

bool operator != (const TStyleSet & that) const

Interface Category:

API.

Purpose:

Determines if two objects are not equal.

Calling Context:

Called to compare two objects.

Parameters:

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

Return Value:

Returns true if the objects are not equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is implemented in terms of the operator ==function, and therefore does not need to be overridden by derived classes.

Member Function: TStyleSet::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 when the streamed in version number cannot be handled.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyleSet::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: TStyleSet::operator=

TStyleSet & operator =(const TStyleSet & set)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TStyleSet & set -The source object for the assignment.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyleSet::~TStyleSet

virtual ~ TStyleSet ()

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: TStyleSet::TStyleSet

TStyleSet ()
TStyleSet (const TStyle & style)
TStyleSet (const TStyleSet & set)

Interface Category:

API.

Purpose:

Default constructor. Constructs an empty style set.
Constructs a style set containing the specified style object.
Copy constructor.

Calling Context:

Called by the stream-in operators.
Called to construct a style set containing a single specified style object.
Called to copy an object.

Parameters:

Takes no parameters.
const TStyle & style -The style object to put in the style set.
const TStyleSet & set -The object to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyleSet::GetEmptyStyleSet

static const TStyleSet & GetEmptyStyleSet ()

Interface Category:

API.

Purpose:

Returns an empty style set.

Calling Context:

Called when you need to return an empty style set.

Parameters:

Takes no parameters.

Return Value:

An empty style set.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyleSet::GetStamp

TPseudoTimeStamp GetStamp () const

Interface Category:

API.

Purpose:

Returns a TPseudoTimeStamp that is used as a unique identifier for style sets. Style sets with the same stamp values are guaranteed to be equal. Style sets with different stamp values are not guaranteed to be different. The only way that two style sets can have the same stamp is if one is a copy, created using the copy constructor or operator=, of the other. The stamp value is not maintained across streaming. Note: According to the definition of Hash, two unequal style sets can have the same value returned by Hash. On the other hand, two unequal style sets will never have the same values returned by GetStamp.

Calling Context:

Called to compare the time stamps of two style sets. If the two time stamps are equal, then the two style sets are equal.

Parameters:

Takes no parameters.

Return Value:

Returns a TPseudoTimeStamp that is used as a unique identifier for style sets.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The stamp value is not maintained across streaming.

Member Function: TStyleSet::IsEmpty

virtual bool IsEmpty () const

Interface Category:

API.

Purpose:

Determines if the style set contains any styles. IsEmpty returns false as soon as the first style is encountered. For performance, it is better to use this member function than the Count member function to determine if there are any styles in the set. The Count member function iterates through all of the styles in the set, so using the count to determine if the style set is empty can be time consuming if there are several styles in the set.

Calling Context:

Called to determine if there are any styles in a given style set.

Parameters:

Takes no parameters.

Return Value:

Returns true if there are no styles in the set, false otherwise.

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.