Generally, styles are applied to text through a user interface mechanism--for example, a menu item that selects a font for input text, or a cursor tool that highlights selected text. This section describes the styling mechanism and how you can apply styles to text programmatically.
CommonPoint
style classes
The abstract class TStyle, derived from TAttribute, defines the basic protocol for all text styles. At a minimum, each style class must implement the virtual function GetName. Styles also have a kind and a category associated with them; see "Style kinds" and "Style categories" below.
Every style object is defined by a name and a value--for example, the name text color and the value red. The implementation of each concrete style class defines the style name for all instances of that class, as a token. The style name is different from the class name. Style classes that are mutually exclusive--for example, the underline style and the double underline style--share the same style name. The value for each style object is defined when you instantiate the object.
NOTE 
Because TStyle derives from TAttribute, style objects are immutable. You assign a value to them when you instantiate them, and you cannot subsequently modify the value. To modify the value of a style associated with specific text, you must replace the original style object with another style object containing the new value. See "Style sets" on page 46 for more information.
Most of the style classes provided by the CommonPoint application system derive from one of three abstract classes derived from TStyle:
TFontStyle is the basis for classes that describe various attributes of a font, including font name (for example, Chicago), point size, and weight. Some of the font styling options are described below in "Font styles."
| Font styles | ||
| You assign font attributes to characters using the text styling mechanism. The system provides a number of classes, all derived from TFontStyle, that describe font attributes such as font name, point size, and weight. The following lists the font attribute classes that derive from TFontStyle. See the online class description for more information on a particular class. | TFontFamilyStyle lets you identify the font you want to use--for example, Chicago--using a TToken to specify the font name. This class supports orthogonal fonts, allowing a particular font to be available in a variety of weights, widths, and postures. TFontTransformStyle encapsulates a TGrafMatrix to use to transform each glyph, using the font currently applied to the text. TFontScaleStyle is the base class for several font attributes based on a GCoordinate value: |
|
TLineLayoutStyle is the basis for classes that describe character attributes other than font attributes, such as color, underlining, and superscripts and subscripts.
TAbstractParagraphStyle is the basis for classes that describe paragraph formatting attributes such as margin widths, justification, and spacing between lines and paragraphs.
Each concrete style class provides the storage mechanism for the value of each instance and member functions to access that data. Some style classes also provide convenience functions for easily creating style objects with standard or default values--for example, TTextColorStyle::GetRed. This figure shows a few examples of some of the CommonPoint style classes and their data access functions:
The text system provides a large set of concrete TStyle subclasses that cover most text attributes. See the online class and member function documentation for a complete description of all the available style classes.
Style kinds
Each style class has a kind associated with it. Currently the system provides two kinds of styles:
The text object uses this kind to determine how to store and manipulate its associated style objects; Character and Paragraph styles are maintained separately, because they have different formatting requirements. The text object manipulates styles differently for each kind using the appropriate TStyleRuns derived class--TCharacterStyleRuns or TParagraphStyleRuns.
NOTE 
The TStyleRuns class and the storage mechanism for each of the style kinds are described in "Style runs and style runs groups" on page 63. You need to use this mechanism directly only if you are creating your own style or text classes.
The system defines classes that encapsulate the style kind. These classes provide a function that returns the style kind value as an instance of TToken, and a function that creates the appropriate TStyleRuns object for that style kind, as shown in this figure:
Many of the TText member functions for manipulating style information require you to specify the style kind. These functions provide a default value that assumes you are manipulating styles of the kind Character. If you are manipulating styles of the kind Paragraph or of another kind you have created, you must specify the kind explicitly. You can get the kind of a style object by calling its GetKind function. You can also get the kind by calling the static function GetStyleKind on the appropriate TStyleRuns derived class for the style kind--for example, TParagraphStyleRuns::GetStyleKind.
Style categories
Each style class must also belong to a particular style category. Each style class encapsulates its style category in an instance of TToken. The basic text classes define a type--TStyleCategory--that you can use when referring to a style category.
NOTE 
This category mechanism is inherited from TAttribute; see the chapter "Attributes" in the manual Foundation Services for more information.
The system-provided styles are categorized as follows:
Style sets
A text object maintains all the styles associated with any given range of text in a style set object; each contiguous range of adjacent characters with identical styling information shares a single style set. Paragraph styles are maintained in a class--TParagraphStyleSet--that derives from TStyleSet. You can directly create TStyleSet instances and collect style objects in them to manipulate groups of style objects simultaneously.
Style objects are immutable, but style set objects are not. You can add and remove style objects from a style set at any time, using the TStyleSet::Add and Remove member functions. You can also replace any specific type of style by adding a new style object of the same type but with a different value. You can add and remove styles individually or in sets, or empty a style set of all style objects.
To change the value of a particular style element, you create a new style object with the new value and apply it to the character range. When you add styles to a style set, the style set first compares the style names and categories of the new styles with the style names and categories of the existing styles. A style set cannot contain two styles with the same name, so when you add a style object of a type that already exists, it replaces the original. For example, if a style set contains a blue color text style object and you add a red color text style object, the red style replaces the blue style.
NOTE
You can apply the same style set to multiple noncontiguous ranges of text. However, if you change the style information for only a portion of the text to which the style set applies, the text object copies the pertinent style data and creates a new style set for the modified range.
The style set protocol also includes member functions for querying the contents of the set. You can query for particular styles or groups of styles either by name or by specific value. For example, you might be interested in whether a style set contains any color style object, or whether it contains a green color style object.
The MemberByValue function queries a style set for specific styles with specific values. The MemberByName function queries a style set for specific types of style, regardless of the values. These functions return a Boolean value. When you query for multiple styles simultaneously, these functions return True only if the result is True for each style in the input set.
To query a style set for a particular style or set of styles with a particular value, use the TStyleSet::MemberByValue member function. This example shows how to query the style set
Once you have added a style set to a text object, you need to make style changes directly on the text object. Changes made to a style set after it has been applied to a text object are not automatically applied to the text object. How a text object manages style sets
When you add a style to a style set, the style set makes its own copy of the style object and takes responsibility for it. Likewise, when you apply a style set to a text object, the text object makes a copy of the style set for its own use. Each text object stores all its associated style information and ensures that all the characters in each identical style run share a single style set.
Querying a style set
myStyleSet for an instance of TTextColorStyle with the
value red:
if (myStyleSet.MemberByValue(TTextColorStyle::GetRed()))
{
// The style set contains a TTextColorStyle instance that contains the value red.
}
To query a style set for a particular style or set of styles regardless of the values, use the TStyleSet::MemberByName member function. This example shows how to query the style set myStyleSet for an instance of TTextColorStyle, regardless of the value. If an instance is found, it is returned in colorStyle:
TStyleSet provides overloaded versions of the MemberByName member function that take a style name and category rather than a style instance. For example: TTextColorStyle* colorStyle;
if (myStyleSet.MemberByName(TTextColorStyle::GetRed(), colorStyle))
{
// The style set contains a TTextColorStyle instance.
}
TStyleCategory category = TStyle::GetEmptyStyle().GetCategory();
TStyleName name = TTextColorStyle::GetRed().GetName();
if (myStyleSet.MemberByName(category, name))
{
// The style set contains any TTextColorStyle instance.
}
[Contents]
[Previous]
[Next]
Click the icon to mail questions or corrections about this material to Taligent personnel.