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.
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.
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.
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.
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.
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.
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.
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.
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.
Click the icon to mail questions or corrections about this material to Taligent personnel.