Class: TStyleSetIterator

Declaration: StyleSet.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

This class provides read-only sequential iteration over the styles in a style set. You must supply the style set at the time of construction. By definition, style sets can only be modified via the style set protocol and not directly during iteration. You cannot remove any of the styles and you cannot modify any of the styles returned during iteration. You can choose to iterate over all the styles or only the styles in a specified style category. Style categories are used internally to group related styles and it is anticipated that some clients will create new style categories of their own.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

This class is not designed for deriving.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TStyleSetIterator::TStyleSetIterator

TStyleSetIterator (const TStyleSet & set)
TStyleSetIterator (const TStyleSet & set, const TStyleCategory & category)
TStyleSetIterator (const TStyleSet & set, const TStyleKind & kind)

Interface Category:

API.

Purpose:

Constructs a style set iterator that iterates over all the styles in the specified style set.
Constructs a style set iterator that iterates over only the styles in the specified style category of the specified style set.
Constructs a style set iterator that iterates over only the styles in the specified style kind of the specified style set.

Calling Context:

Called to create an iterator for all styles.
Called to create an iterator for only the styles in a particular style category.
Called to create an iterator for only the styles in a particular style kind.

Parameters:

const TStyleSet & set -The set to be iterated over.
const TStyleSet & set -The set to be iterated over.
const TStyleCategory & category -The style category to be iterated over.
const TStyleSet & set -The set to be iterated over.
const TStyleKind & kind -The style kind to be iterated over.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

A reference to the input style set is used throughout the life of a style set iterator. Therefore, a style set iterator is only valid as long as the associated style set is in existence. The First member function must be called to synchronize the iterator with the associated style set after any change has been made to the style set.

Member Function: TStyleSetIterator::First

virtual const TStyle * First ()

Interface Category:

API.

Purpose:

Gets the first style in the associated style set. If a style category is specified, gets the first style of the specified category.

Calling Context:

Called immediately after constructing a style set iterator to get the first style.

Parameters:

Takes no parameters.

Return Value:

A const pointer to the first style is returned. For an empty style set or one that contains no styles of the specified category, a NIL pointer is returned.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

You must call this function before calling Next for the first time. Calling First initializes the iterator for subsequent calls to Next. If the associated style set changes in the middle of iterating, you must call First and begin iterating sequentially from the beginning again. Otherwise, it is not guaranteed that you will get back all the styles currently in the associated style set.

Member Function: TStyleSetIterator::Next

virtual const TStyle * Next ()

Interface Category:

API.

Purpose:

Returns the next style in the associated style set. If a style category is specified, returns the next style of the specified category.

Calling Context:

Called after the initial call to First to iterate over all subsequent styles.

Parameters:

Takes no parameters.

Return Value:

A const pointer to the next style is returned. When there is no next style to return, a NIL pointer is returned.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

You must call First before calling this function for the first time. Calling First initializes the iterator for subsequent calls to Next. If the associated style set changes in the middle of iterating, you must call First and begin iterating sequentially from the beginning again. Otherwise, it is not guaranteed that you will get back all the styles currently in the associated style set.