Creating your own styles

• Define the style name (allocate a token to contain the name)
• Override GetName to return the name
• Determine the category
• Determine the kind
• Define the functions and data members needed to create, display, or use the style

• Deriving your style from TSharedStylewhen the style requires a significant amount of stored data
• Creating a nonpropagating style

Style runs and style runs groups

TStandardText uses an instance of TStyleRunsGroup to manage its style data. A TStyleRunsGroup instance owns a TStyleRuns instance for each kind of style associated with the text. TText style manipulation functions--such as AddStyles or CopyStyles--actually call the corresponding function in TStyleRunsGroup; these functions then call TStyleRuns functions, which are implemented to handle styles of a particular kind.

The style run for each style kind is created by the TStyleKind class that defines that kind. For example, when you add Character styles to a text object, the text object calls the TCharacterStyleKind CreateStyleRuns function to create a TCharacterStyleRuns in which to maintain those styles, as shown in this figure.

When you create your own style class, you need to decide whether to use one of the defined kinds or to create a new kind. To define the style's kind, override the TStyle::GetKind function to return the correct kind. If your style class is of a kind already defined by the CommonPoint application system, TStandardText can store and manipulate instances of that class automatically.

When you create a style of a new kind, you need to:

• Derive from TStyleRuns to create a style runs class to manage styles of your new kind. TStyleRuns provides a number of virtual member functions that your need to override to correctly manipulate styles of your new kind. See the header file or the online class and member function documentation for a complete list and descriptions of the TStyleRuns virtual functions.
• Derive from TStyleKind to define the new kind. You need to override GetKindName to return the new style kind as a TToken, and the CreateStyleRuns function to create an instance of your TStyleRuns derived class.
• Override TStyle::GetKind to return the new kind.

Using TSharedStyle

TSharedStyle derives from TStyle and provides the same public protocol. An instance of a class derived from TSharedStyle is a surrogate for the actual style data, encapsulated in a TInternalAttribute instance. Multiple instances of a shared style with the same name and value share the same internal attribute. The internal attribute is created when the shared style is constructed, and it is immutable.

When you derive a class from TSharedStyle, the constructors (except the copy constructor) for your class must:

• Create the TInternalAttribute containing the style data.
• Call TSharedStyle::AdoptByManager to pass the internal attribute to the attribute manager.

TSharedStyle::SetInternalAttribute( copyFrom.GetInternalAttribute );

Style propagation

You generally want most style information to propagate. However, some style classes are not meant to propagate. For example, you might create a style class that embeds data other than text (perhaps graphics or sound) as a nondisplaying character. You would not want this style to propagate to characters typed immediately following the embedded data. The TStyle::IsPropagatingStyle member function by default returns the Boolean value True and the style propagates itself. To create a nonpropagating style, override the IsPropagatingStyle function in your style class to return the value False.