Class: TViewDictionary

Declaration: ViewDictionary.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

This class provides member functions for naming and finding views in a view hierarchy. You can name a view, search a view hierarchy for a named view, and limit the scope of the search to allow a hierarchy to be constructed from pieces supplied by different developers. The main client of this class is a developer who uses a user interface builder to create a view hierarchy.

Instantiation:

Never allocate. Use the static member functions directly.

Deriving Classes:

None.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TViewDictionary::SetName

static void SetName (TView & view, const TText & name)

Interface Category:

API.

Purpose:

Sets the name of a view. Views initially have the empty string as their name. When the view's name is the empty string, it pays no storage overhead for the name.

Calling Context:

Called by user interface builders, and other clients who want to distinguish views. (This might be useful in a debugging situation, for example.) Usually used in conjunction with the Find member function to later look up the view.

Parameters:

TView & view -The view to be named.
const TText & name -The new name.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TViewDictionary::GetName

static void GetName (const TView & view, TText & name)

Interface Category:

API.

Purpose:

Gets the name of a view. This member function is not typically called by developers.

Calling Context:

Called by the Find member function. It is also useful for distinguishing views when displaying view hierarchies, whether in debugging situations or in user interface builders.

Parameters:

const TView & view -The view name to get.
TText & name -Filled in with the name of the view. By default, a view has the empty string as its name.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TViewDictionary::Find

static TView * Find (const TView & view, const TText & name)

Category:

API.

Purpose:

Finds views by name in a view hierarchy. Searches the view and its descendants, in an undefined order, looking for a view that has the same name as the argument. Returns the first view it finds. If no view is found, NIL is returned. Searching does not descend into child views that are barrier views. A barrier view is a view for which TViewDictionary::IsSearchBarrier returns true. Barrier views allow naming to work in a complex hierarchy, where different parts of the complex hierarchy have been designed by different developers. Each developer's part is separated from the other parts by a barrier view. Because searches do not descend into barrier views, the different name spaces are kept separate.

Calling Context:

Called to find a named view within a view hierarchy. The main reason to call this is to find named views within a view hierarchy that has been constructed with a user interface builder. Using Find decouples the application from the specifics of the view hierarchy -the views can be rearranged, and the application can still find the ones it needs. Typically, the application dynamically casts the result of Find to a more specific class.

Parameters:

const TView & view -The view to start the search at.
const TText & name -The name of the view to search for.

Return Value:

The first view found with the name.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TViewDictionary::SetSearchBarrier

static void SetSearchBarrier (TView & view, bool isBarrier)

Interface Category:

API.

Purpose:

Changes a view to or from being a barrier view. Searching does not descend into child views that are barrier views.

Calling Context:

Called to provide a multipart name space for view lookup. Typically called by a Compound Document framework attempting to stitch together a large hierarchy out of subhierarchies developed independently.

Parameters:

TView & view -The view to set or clear.
bool isBarrier -The new value of the barrier property.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TViewDictionary::IsSearchBarrier

static bool IsSearchBarrier (const TView & view)

Interface Category:

API.

Purpose:

Tells if a view is a search barrier. By default, a view is not a search barrier. Searching does not descend into child views that are barrier views.

Calling Context:

Called internally by TViewDictionary::Find. Typically not called by anyone else, but might be useful for advanced uses of view hierarchies.

Parameters:

const TView & view -The view to examine to see if it is a barrier view.

Return Value:

Returns true if the view is a barrier view, false if it is not a barrier view.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

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