Class: TViewGroupHandle

Declaration: ViewGroupHandle.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TAttributeGroup

Inherited By:

TGUIPaintsHandle

Purpose:

A TViewGroupHandle is very similar to a TInheritedGroupHandle, with one major difference. In TViewGroupHandle the internal master group is not created automatically; rather, it is created on demand when new attributes are added to the group. This class also provides the protocol to do local (nonhierarchy searching) lookups of attributes.

Instantiation:

Allocate on the heap or the stack. This class is designed for cheap stack allocation; derived classes can be heap allocated and receive change notifications if they explicitly request to do so.

Deriving Classes:

Override the GetView function in a derived class to hold onto a TViewHandle and return the contents of that handle. You would typically do this in a group handle derived class that was allocated on the heap and that has dynamic (view lifetime independent) extent.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

See TAttributeGroup and TAttributeGroupHandle for more information. This class has been designed for cheap stack allocation; it (or more typically, derived classes) can also be heap allocated.

Member Function: TViewGroupHandle::TViewGroupHandle

TViewGroupHandle (TView * viewAlias)
TViewGroupHandle (const TViewGroupHandle & copy)

Interface Category:

API.

Purpose:

Default constructor for other than internal use. It creates a TViewGroupHandle object when given a pointer to a TView alias object. Creating this object does not create an attribute group for the view; only adding attributes to this handle creates a group that's local to the view.
Copy constructor.

Calling Context:

Developers should call this constructor function to create a TViewGroupHandle for a view alias.
Called to copy an object.

Parameters:

TView * viewAlias -A pointer to an alias for a TView object.
const TViewGroupHandle & copy -A reference to the object to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TViewGroupHandle::~TViewGroupHandle

virtual ~ TViewGroupHandle ()

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

TViewGroupHandle & operator =(const TViewGroupHandle & group)

Interface Category:

API.

Purpose:

Assignment operator. The resulting handle refers to the same view as the original handle did.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TViewGroupHandle & group -The object to be assigned.

Return Value:

A non-const reference to the left-hand side TViewGroupHandle object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TViewGroupHandle::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & toStream -The stream to which this object is streamed out.

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:

None.

Member Function: TViewGroupHandle::operator<<=

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

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromStream -The stream from which this object is streamed in.

Return Value:

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

Exceptions:

Can throw a TInvalidVersionError exception when an invalid version is detected.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TViewGroupHandle::Member

virtual TAttribute * Member (const TAttribute & anAttribute, EWhereToLookup lookup =TAttributeGroup :: kLocalAndParents) const
virtual bool Member (const TAttributeGroup & anAttributeGroup, EWhereToLookup lookup =TAttributeGroup :: kLocalAndParents) const

Interface Category:

API.

Purpose:

Determines if the given attribute is in this attribute group. Returns a TAttribute attribute pointer if there is a TAttribute in the group that matches the parameter anAttribute. The if the lookup parameter is kLocalAndParents, or kParentGroups, parent chain is searched until a matching attribute is found or until there is a NIL parent pointer.
Determines if the given attributes are in this attribute group. Returns true if the set of attributes in the parameter anAttributeGroup are all members of this TAttributeGroup attribute group. This member function operates on all of the exported attributes. That is, anAttributeGroup is considered a member of this attribute group if all of its elements can be found in the superset formed by the union of elements of this group and the elements of all of this group's ancestors.

Calling Context:

Call this function directly.
Call this function directly.

Parameters:

const TAttribute & anAttribute -A reference to an attribute.
EWhereToLookup lookup =TAttributeGroup :: kLocalAndParents -Controls the scope of the lookup. Can be kLocalGroup (only look in the current group), kParentGroups (only look in the ancestors of the current group), or kLocalAndParents (look in the current group and its ancestors).
const TAttributeGroup & anAttributeGroup -A reference to an attribute group.
EWhereToLookup lookup =TAttributeGroup :: kLocalAndParents -Controls the scope of the lookup. Can be kLocalGroup (only look in the current group), kParentGroups (only look in the ancestors of the current group), or kLocalAndParents (look in the current group and its ancestors).

Return Value:

Returns a TAttribute pointer to the matching attribute; otherwise, returns NIL if no matching attribute is found.
Returns true if the set of attributes for the attribute group that is passed in are all members of this TAttributeGroup attribute group; otherwise, returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TViewGroupHandle::Add

virtual void Add (const TAttribute & anAttribute)
virtual void Add (const TAttributeGroup & aGroup)

Interface Category:

API.

Purpose:

Adds an attribute to this attribute group. Causes the creation of a local attribute group (local to the view that is passed in with the constructor function) if one is not already present.
Adds all attributes from the specified group to this group. Any duplicate attributes in this group are replaced with attributes from the specified group. Only attributes that are actually in the specified group are added; attributes that are only inherited through the parent chain are not added. Causes the creation of a local attribute group if one was not already present.

Calling Context:

Call this function directly.
Call this function directly.

Parameters:

const TAttribute & anAttribute -A reference to the attribute to be added.
const TAttributeGroup & aGroup -A reference to an attribute group, the attributes from which are copied to this attribute group.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TViewGroupHandle::AddAllInherited

virtual void AddAllInherited (const TAttributeGroup & aGroup)

Interface Category:

API.

Purpose:

Adds all attributes, including those in the parent chain for the specified attribute group, to this attribute group. Duplicate attributes are replaced with the newly added attributes. Creates a local attribute group associated with the view that was given in the constructor for this object, if one is not already present.

Calling Context:

Call this function directly.

Parameters:

const TAttributeGroup & aGroup -A reference to the attribute group from which the attributes are copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TViewGroupHandle::CountAllInherited

virtual long CountAllInherited () const

Interface Category:

API.

Purpose:

Returns the number of elements in this group and in all of its ancestors. To accomplish this, this function calls GetAllInheritedAttributes on this attribute group and does a count on the resultant set.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a long value that indicates the number of elements in this group and in all of its ancestors.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Note that this is a relatively expensive operation.

Member Function: TViewGroupHandle::Count

virtual long Count () const

Interface Category:

API.

Purpose:

Returns the number of elements in this attribute group.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a long value that is the number of elements in this group.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TViewGroupHandle::Delete

virtual void Delete (const TAttribute & anAttribute)

Interface Category:

API.

Purpose:

Deletes the specified attribute from this attribute group. Note: When notification is turned on, this member function calls NotifyChanged to propagate change notification.

Calling Context:

Call this function directly.

Parameters:

const TAttribute & anAttribute -A reference to the attribute to delete.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function deletes attributes only from this attribute group.

Member Function: TViewGroupHandle::DeleteAll

virtual void DeleteAll ()

Interface Category:

API.

Purpose:

Deletes all of the attributes in this attribute group. Note: When notification is turned on, this member function calls NotifyChanged to propagate change notification.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function deletes attributes only from this attribute group.

Member Function: TViewGroupHandle::CreateIterator

virtual TIteratorOver < TAttribute > * CreateIterator () const

Interface Category:

API.

Purpose:

Creates and returns an iterator that only iterates over the contents of this attribute group.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns an iterator for this attribute group, or NIL if there is no local attribute group associated with the view that was given to this object's constructor.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

If you want to iterate over all attributes, including those that are inherited through the parent chain, use AllInheritedAttributes coupled with the appropriate iterator.

Member Function: TViewGroupHandle::GetAllInheritedAttributes

virtual void GetAllInheritedAttributes (TSetOf < TAttribute > & fillIn) const

Interface Category:

API.

Purpose:

Builds an attribute group consisting of all attributes that are found anywhere in this attribute group and in this group's parent chain. Attributes that are found in children replace matching attributes that were found in a parent.

Calling Context:

Call this function directly.

Parameters:

TSetOf < TAttribute > & fillIn -The list of attributes that is filled in by the function.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TViewGroupHandle::GetParent

virtual TAttributeGroup * GetParent () const

Interface Category:

API.

Purpose:

Returns a pointer to this attribute group's parent group.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the parent group for this attribute group.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TViewGroupHandle::SetParent

virtual void SetParent (TAttributeGroup * myNewParent)

Interface Category:

API.

Purpose:

Sets up a new parent group for this attribute group. Normally, you do not need to call this function, because the attribute groups in the view hierarchy are automatically chained together. Note: When notification is turned on, this member function calls NotifyChanged to propagate change notification.

Calling Context:

Call this function directly.

Parameters:

TAttributeGroup * myNewParent -A pointer to the new parent group.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TViewGroupHandle::NotifyChanged

virtual void NotifyChanged ()

Interface Category:

API.

Purpose:

Notifies all dependent attribute groups that this group has changed. Derived classes override this function to be informed of changes in attributes (inherited and local) or the attribute group hierarchy.

Calling Context:

Called when notification is turned on and this attribute group has been changed (something added or removed).

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TViewGroupHandle::BeginChanges

virtual void BeginChanges ()

Interface Category:

API.

Purpose:

There is a changes pending flag which is used to prevent notification when a batch of changes is to be made to an attribute group. This function sets this flag to true to indicate that a batch of changes is about to be made, and that change notification should be postponed until after the changes has been made.

Calling Context:

Use this member function to prevent notification on each change in a batch of changes to an attribute group.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TViewGroupHandle::EndChanges

virtual void EndChanges ()

Interface Category:

API.

Purpose:

This member function calls NotifyChanged to propagate change notification, and resets the changes pending flag to false so notification will no longer be postponed.

Calling Context:

Call this member function when you have finished doing a batch of changes to an attribute group. This function calls NotifyChanged so that all dependent attribute groups will be notified that the group has changed.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TViewGroupHandle::ChangesPending

virtual bool ChangesPending ()

Interface Category:

API.

Purpose:

Returns the value of the flag that is used to indicate if notification is currently postponed.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if notification is currently postponed for the attribute group. Returns false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TViewGroupHandle::SetChangesPending

virtual void SetChangesPending (bool pending)

Interface Category:

API.

Purpose:

Sets the value of the flag that is used to indicate if notification is currently postponed. Setting the flag to true indicates that notification is to be postponed, and setting the flag to false indicates that notification is no longer postponed.

Calling Context:

Called directly to change the value of the flag that indicates if change notification is currently postponed for an attribute group.

Parameters:

bool pending -A Boolean value for indicating if changes are pending.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TViewGroupHandle::EnableChangeNotification

void EnableChangeNotification ()

Interface Category:

API.

Purpose:

Turns on change notification for derived classes. Normally, change notification is disabled for this class and for derived classes of this class.

Calling Context:

Call this function directly if you want to receive change notification in your derived class of TViewGroupHandle.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TViewGroupHandle::GetView

virtual TView * GetView () const

Interface Category:

API.

Purpose:

Returns a pointer to the view that is associated with this group handle. You can override this function in a derived class to use the TViewHandle that your derived class is holding onto and return the contents of that handle. You would typically do this in a group handle derived class that was allocated on the heap and that has dynamic (view lifetime independent) extent.

Calling Context:

Call this function directly. Also called by the framework during most operations to get access to the local attribute group. If this function return NIL, the framework operation which called this function will return safely with a reasonable value.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the TView object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TViewGroupHandle::GetLocalGroup

TAttributeGroup * GetLocalGroup () const

Interface Category:

API.

Purpose:

Gets a pointer to the attribute group that the view associated with this view group handle is holding onto, if there is one.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the local group, or NIL if none exists.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TViewGroupHandle::GetValidLocalGroup

virtual TAttributeGroup * GetValidLocalGroup ()

Interface Category:

API.

Purpose:

Gets a pointer to the local attribute group. If no local group exists, this function creates and installs one.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the local group.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TViewGroupHandle::FindAttributeGroup

virtual TAttributeGroup * FindAttributeGroup () const

Interface Category:

API.

Purpose:

Gets a pointer to the nearest (traversing up the parent chain) group. The nearest group is the local group, if there is one associated with the view that this handle was created with.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the nearest group.

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.