Class: TStyle

Declaration: Style.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TAttribute

Inherited By:

TFontStyle TLanguageStyle TLineLayoutStyle TNullStyle TSharedStyle TSingleLineOrientationStyle TAbstractParagraphStyle

Purpose:

TStyles represent characteristics of a substring of text. Typically, these include character formatting information, such as point size, weight (bold/regular), and tracking; plus paragraph formatting information, such as margins and tab stops. However, styles can also be used to represent nonformatting information about text, such as language (English, French, and so forth). A style can be referenced by name. Derived classes of TStyle should be defined to provide the storage and access to their values.

Instantiation:

TStyles are never instantiated directly by clients. As an abstract base class, TStyle is only indirectly instantiated when a concrete derived class is instantiated. There is no instance data associated with the abstract class. Therefore, class has no impact on whether TStyle derived classes should be allocated on the heap or the stack.

Deriving Classes:

All concrete text style classes must derive either directly or indirectly from TStyle. For example, character properties stored in a TStyleSet object must derive from TStyle. Similarly, paragraph properties stored in a TProperties object must derive from TStyle. An invariant that must be preserved by derived classes is the immutable nature of styles (the value of a style is determined at the time of creation and cannot be changed). This invariant is expressed in TStyle by declaring the assignment operator as a protected member function. Derived classes are required to protect their assignment operators too. All derived classes must override the following member functions: GetName, operator==, and the streaming operators. Some derived classes might need to override these member functions: GetCategory, GetKind, and IsPropagatingStyle. Before doing type casting in member functions such as operator==, be sure to use the inherited member function TAttribute::NamesMatch to determine if the two style objects have similar types.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TStyle::GetCategory

virtual const TStyleCategory & GetCategory () const

Interface Category:

API.

Purpose:

Each derived class provides its internal category via this member function. The default implementation provides for a general Text category. A derived class might choose to override this default implementation when a special category is desired. For example, text styles of interest when laying out a line of text are in the TextLineLayout category. Categories can be used to enhance performance. Iterating over only the text styles in a specific category rather than all text styles stored in a style set can be significantly faster.

Calling Context:

Called when the category associated with an object is needed.

Parameters:

Return Value:

The TToken for the associated category.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Derived classes are not required to override this member function. For the performance reasons mentioned earlier, it might make sense to group related style derived classes in the same category for efficient iteration over just those styles. Currently, there are four categories in use. Text is the category everyone gets by default. The Text Line Layout and the TextParagraph Formatting categories are used internally to efficiently iterate over character and paragraph styles when formatting text for display in the system. These two categories are reserved for internal use. Styles used to apply fonts are in the Font Attribute category. If you want to place your own TStyle derived classes in some category other than the default one, you must register your category name with Taligent. The style categories must be managed by Taligent. Otherwise, there could be accidental usage of the same category by multiple independent development efforts.

Member Function: TStyle::GetName

virtual const TStyleName & GetName () const

Interface Category:

API.

Purpose:

Each derived class provides its internal name via this member function. This is not necessarily the class name. For example, there are related underlining styles that are each separate derived classes. However, they share the same internal name.

Calling Context:

Called when the name associated with a style is needed.

Parameters:

Return Value:

The TToken for the associated name.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Multiple styles should share the same internal name when they are mutually exclusive; that is, when they cannot be applied to the same characters at the same time (for example, underline and double-underline styles). Like the style categories, the style names must be registered with Taligent. Otherwise, there could be accidental usage of the same style name by multiple independent development efforts.

Member Function: TStyle::IsPropagatingStyle

virtual bool IsPropagatingStyle () const

Interface Category:

API.

Purpose:

Returns whether a given style is intended to propagate. Style propagation is an important issue in the word-processing domain. When typing new text into an existing text object, many word processors propagate the styles associated with the existing text to the newly typed text. However, there are cases where certain styles are not intended to propagate to new text that is typed. Style derived classes that want to be nonpropagating are considered to be the exception rather than the rule. This is why the default implementation indicates the style is intended to propagate. Embedding data as a nondisplaying character with an associated style for the embedded data is one of the exceptions. The style for the embedded data should be a nonpropagating style. Otherwise, the style containing the embedded data would propagate to any normal characters typed afterwards. This mechanism can be used to embed graphics, sound, or other data in a text object.

Calling Context:

Called when deciding whether to propagate this style object.

Parameters:

Return Value:

Returns true if the style object is supposed to propagate. The default implementation always returns true.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Derived classes that are not intended to propagate should override this member function to always return false.

Member Function: TStyle::operator>>=

virtual TStream & operator >>=(TStream & toStream) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

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:

Derived classes must call the inherited streaming operator first and stream out their own instance data afterwards.

Member Function: TStyle::operator<<=

virtual TStream & operator <<= (TStream & fromStream)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Derived classes must call the inherited streaming operator first and stream in their own instance data afterwards.

Member Function: TStyle::GetNullStyle

static const TStyle & GetNullStyle ()

Interface Category:

API.

Purpose:

Returns an empty style object. In some situations, it might be appropriate to return an empty style object reference rather than raise an exception. An interface that returns a const TStyle reference can use this member function to produce a valid return value in these situations.

Calling Context:

Called when a reference to an empty style object is required.

Parameters:

Return Value:

Returns a reference to an empty style object derived from TStyle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Member Function: TStyle::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Generates a hash value.

Calling Context:

Called to generate a hash value.

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

  1. TStyle ()
  2. TStyle (const TStyle & style)

Interface Category:

API.

Purpose:

  1. Default constructor.
  2. Copy constructor.

Calling Context:

  1. Called by the stream-in operators and by derived class constructors.
  2. Called to copy an object.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyle::~TStyle

virtual ~ TStyle ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyle::GetKind

virtual const TStyleKind & GetKind () const

Interface Category:

API.

Purpose:

Returns the kind of the style. Defaults to character-based, which refers to styles that are applied to a substring of text. The returned kind is polymorphically compared to determine if this style is to be managed by a given instance of a derived class of TStyleRuns. The kind of a style can never be changed, so the style kind should be a const static member of TStyle and any derived class that overrides this member function.

Calling Context:

Called when the style kind is needed, usually to determine which derived class of TStyleRuns can manage a given style.

Parameters:

Return Value:

A const reference to a derived class of TStyleKind. The returned object should be a const static member function of the style class.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

There are currently two kinds of styles. Character based styles are styles that can be applied to a substring of text. Paragraph based styles are styles that can be applied to an entire paragraph, where a paragraph is a contiguous range of text terminated by a new paragraph character or the last character in the model.

Member Function: TStyle::operator!=

bool operator != (const TStyle & that) const

Interface Category:

API.

Purpose:

Inequality operator.

Calling Context:

Called to compare a compatible object.

Parameters:

Return Value:

Returns true if the objects are not equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStyle::operator==

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

Interface Category:

API.

Purpose:

Equality operator.

Calling Context:

Called when an object is compared to another compatible object.

Parameters:

Return Value:

Returns true when two styles have the same category, name, and internal values. If any difference is encountered, returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The comparison operator that takes a reference to another style is a pure virtual function. As such, concrete derived classes must provide an overriding implementation. Derived classes can take advantage of inherited TAttribute::NamesMatch to do the comparison of category and name. Only after TAttribute::NamesMatch returns true should the internal values of two styles be compared. There are several other member functions that do comparisons. They are all supported indirectly by this pure virtual function. So, you control the behavior of all the comparison functions with your override for this pure virtual function.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.