Class: TSharedStyle

Declaration: Style.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TStyle

Inherited By:

None.

Purpose:

TSharedStyle implements the style protocol using surrogates for TInternalAttribute objects. The surrogates create master model is used. The master objects, TInternalAttributes, are reference counted. Assignment or initialization creates additional references to the master object. The master objects are immutable.

Instantiation:

TSharedStyles are never instantiated directly by clients. As an abstract base class, TSharedStyle is only indirectly instantiated when a concrete derived class is instantiated. Instances of concrete derived classes of TSharedStyle can be allocated on either the heap or the stack.

Deriving Classes:

Derive classes from TSharedStyle when the style requires a significant amount of data. The Attributes ERS recommends using surrogates when your internal data exceeds eight bytes. There are rules. In your constructor you must do the following: 1. Create the specific TInternalAttribute that corresponds to the TSharedStyle in whose constructor you are currently executing. 2. Call TSharedStyle::AdoptByManager, passing the newly created internal attribute. 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: TSharedStyle::~TSharedStyle

virtual ~ TSharedStyle ()

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: TSharedStyle::GetName

virtual const TStyleName & GetName () const

Interface Category:

API.

Purpose:

Returns the name of the internal attribute. The internal attribute provides its internal name via its GetName member function. The name 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:

Takes no parameters.

Return Value:

The TToken for the associated name.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Do not override the member function. Override the GetName member function on the internal attribute instead. 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: TSharedStyle::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator. Streams out the internal attribute.

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:

Derived classes should provide all of their data via the internal attribute. Override the streaming operators of the internal attribute to stream out the data. This stream-out operator calls the stream-out operator on the internal attribute.

Member Function: TSharedStyle::operator<<=

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

Interface Category:

API.

Purpose:

Stream-in operator. Streams in the internal attribute.

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 no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Derived classes should provide all of their data via the internal attribute. Override the streaming operators of the internal attribute to stream in the data. This stream-in operator calls the stream-in operator on the internal attribute.

Member Function: TSharedStyle::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Returns the value resulting from calling Hash on the internal attribute.

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: TSharedStyle::operator==

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

Interface Category:

API.

Purpose:

Determines if two objects are equal. If the two styles have the same name and category, then NamesAndValuesMatch is called on the internal attributes.

Calling Context:

Called when an object is compared to another compatible object.

Parameters:

const TStyle & style -The style to be compared against this style.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSharedStyle::operator!=

bool operator != (const TStyle & that) const

Interface Category:

API.

Purpose:

Determines if two objects are not equal. Returns true if operator== returns false, and false otherwise.

Calling Context:

Called when an object is compared to another compatible object.

Parameters:

const TStyle & that -The style to be compared against this style.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSharedStyle::TSharedStyle

TSharedStyle ()
TSharedStyle (const TSharedStyle & style)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

Called by the stream-in operators and the constructors of derived classes.
Called to copy an object.

Parameters:

Takes no parameters.
const TSharedStyle & style -The style to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Member Function: TSharedStyle::GetInternalAttribute

TInternalAttribute * GetInternalAttribute () const

Interface Category:

API.

Purpose:

Returns a pointer to the internal attribute.

Calling Context:

Can only be called directly by an instance of a derived class of TSharedStyle, because this is a protected member function.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the internal attribute.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Internal attributes are reference counted, and instances of internal attributes should be considered immutable.

Member Function: TSharedStyle::SetInternalAttribute

virtual void SetInternalAttribute (TInternalAttribute * attribute, TStream * stream =NIL)

Interface Category:

API.

Purpose:

Sets the internal attribute data member. First, the new and the old internal attribute pointers are compared. If they are the same, nothing is done. If they are not the same, then the reference count on the old one is decremented, and the reference count on the new one is incremented. If this member function is called during streaming, and an object's reference count hits zero, it is marked for deletion when the stream context goes away.

Calling Context:

Can only be called directly by an instance of a derived class of TSharedStyle, because this is a protected member function.

Parameters:

TInternalAttribute * attribute -The new internal attribute.
TStream * stream =NIL -The stream that was being used when this function was called.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSharedStyle::AdoptByManager

void AdoptByManager (TInternalAttribute * attribute, TStream * stream =NIL)

Interface Category:

API.

Purpose:

Every constructor of a derived class of TSharedStyle must allocate a new corresponding derived class of TInternalAttribute. The new internal attribute must be passed to the attribute manager by calling the non-virtual member function AdoptByManager. AdoptByManager tries to give the internal attribute to the attribute manager. If there is not an internal attribute equivalent to the one just created and passed in, the new attribute is adopted by the attribute manager. If an internal attribute exists in the attribute manager that is identical to the newly created internal attribute, then the newly created internal attribute is deleted, and the shared attribute's internal attribute pointer is adjusted to point to the pre-existing internal attribute. The test to check if an internal attribute exists in the attribute manager that is identical to the newly created internal attribute uses the virtual TAttributeGroup::Member member function.

Calling Context:

Called whenever a new internal attribute is created, and must be called within each constructor of a derived class of TSharedAttribute.

Parameters:

TInternalAttribute * attribute -The internal attribute to be passed to the attribute manager.
TStream * stream =NIL -The stream that the internal attribute is being retrieved from.

Return Value:

None.

Exceptions:

Throws on exception if the category of the new internal attribute is invalid.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.