rwlogo
Rogue Wave Views 5.6

Rogue Wave Views
Prototypes Package API Reference Guide

Product Documentation:

Rogue Wave Views
Documentation Home

List of all members | Public Member Functions | Static Public Member Functions | Friends
IlvGroup Class Reference

Base class to hold graphic objects together and assign behaviors to them. More...

#include <ilviews/protos/group.h>

Inheritance diagram for IlvGroup:
IlvAccessorHolder IlvAccessible IlvProtoInstance IlvPrototype

Public Member Functions

 IlvGroup (const char *name=0)
 Creates a new, empty group with the specified name. More...
 
 IlvGroup (const IlvGroup &source)
 Creates a copy of the source group. More...
 
void addAccessor (IlvUserAccessor *accessor, IlBoolean owner=IlTrue, IlBoolean initialize=IlTrue, IlBoolean sort=IlFalse, IlvUserAccessor *previous=0)
 Adds an accessor to the group. More...
 
void addNode (IlvGroupNode *node, IlBoolean uniqueName=IlFalse)
 Adds the node node to the group. More...
 
virtual IlBoolean changeValue (const IlvValue &val)
 Changes the object's value. Both the name and the new value are contained in val. More...
 
virtual IlBoolean changeValues (const IlvValue *values, IlUShort count)
 Changes several values of an object in a single call. The default implementation calls changeValue for all values. More...
 
IlvGroupNodefindNode (const char *name, IlBoolean actual=IlTrue) const
 Finds the node whose name is specified as argument. More...
 
IlUInt getAccessorList (const char **&names, const char **&types, IlBoolean all=IlFalse, IlBoolean output=IlFalse) const
 Returns names and types of the attributes defined in the group. More...
 
virtual void getAccessors (const IlSymbol *const **accessors, const IlvValueTypeClass *const **types, IlUInt &count) const
 Returns the names of all the accessors known by this object. More...
 
virtual const char * getName () const
 Returns the object name. More...
 
IlUInt getNodeCount () const
 Returns the number of nodes in the group. More...
 
const char ** getNodeNames (IlUInt &count)
 Returns the names of all the nodes of the group, including the nodes of subgroups. More...
 
IlvGroupNode ** getNodes (IlUInt &count)
 Returns the nodes in the group. More...
 
IlvGroupgetParent () const
 If this group is a subgroup of another group, returns the parent group. Otherwise, returns 0.
 
IlvGroupNodegetParentNode () const
 Returns the instance of IlvSubGroupNode that contains the group if this group is a subgroup of another group, or 0 otherwise.
 
IlvGroupgetTopGroup ()
 Returns the top-most parent of the group if this group is a subgroup. Otherwise, it returns 0.
 
virtual const IlvValueTypeClassgetValueType (const IlSymbol *) const
 Returns the type of a given attribute. More...
 
IlBoolean hasAccessor (IlvAccessor *accessor)
 Returns IlTrue if accessor is already contained in the group. Otherwise, it returns IlFalse.
 
IlBoolean isEmpty () const
 Returns IlTrue if the group contains no nodes. Otherwise, it returns IlFalse.
 
virtual IlBoolean isOutputValue (const IlSymbol *valueName) const
 Indicates whether value designates an accessor that can generate notifying values. More...
 
virtual IlvAccessornextAccessor (IlAny &link) const
 Iterator through the accessors. More...
 
IlvGroupNodenextNode (IlAny &link) const
 Node iterator. More...
 
virtual IlvUserAccessornextUserAccessor (IlAny &link) const
 User accessor iterator. More...
 
virtual IlvValuequeryValue (IlvValue &val) const
 Queries the value designated by value from the object. Both the value and the value type are stored in value. More...
 
virtual void queryValues (IlvValue *values, IlUShort count) const
 Queries several values in a single call. The default implementation calls queryValue for each value. More...
 
void removeAccessor (IlvAccessor *accessor, IlBoolean deleteIt=IlTrue)
 Removes an accessor from the group. More...
 
void removeNode (IlvGroupNode *node, IlBoolean deleteIt=IlTrue)
 Removes a node from the group. More...
 
IlBoolean save (ILVSTDPREF ostream *stream=0, const char *path=0)
 Saves a group to an output stream or to a disk file. More...
 
virtual void setName (const char *name)
 Changes the name of this group. More...
 
virtual void subscribe (IlvAccessible *subscriber, IlSymbol *sourceValue, IlSymbol *subscriberValue, IlvValueTypeClass *type, IlvValueSubscriptionMode mode=IlvValueSubscriptionChange)
 Subscribes the subscriber object to the value sourceValue of this object. More...
 
virtual void unSubscribe (IlvAccessible *subscriber, IlSymbol *sourceValue=0, IlSymbol *subscriberValue=0)
 Cancels subscriptions previously made. More...
 
virtual IlBoolean update (const IlvGroup &source)
 Updates the group (deep-inplace copy). More...
 
- Public Member Functions inherited from IlvAccessorHolder
virtual IlUInt compareValues (const IlvAccessible *ref, IlvValue *values, IlUShort count, IlvValueArray &diffs) const
 Compares two objects and returns the differing attributes. More...
 
- Public Member Functions inherited from IlvAccessible
virtual IlUInt compareAllValues (const IlvAccessible *ref, IlvValueArray &diffs, IlBoolean any=IlFalse) const
 Compares two objects and returns the differing attributes. More...
 
virtual IlBoolean convertValues (IlvValue *v, IlUShort c, IlvDisplay *d) const
 Convert values to match the types defined by the object accessors. More...
 
IlUInt getSubscriptions (IlvAccessible *subscriber, IlSymbol **&sourceValue, IlSymbol **&subscriberValue, IlvValueTypeClass **&type, IlvValueSubscriptionMode *&mode, IlvAccessible ***subscribers=0) const
 Returns alls subscriptions made by subscriber. More...
 
virtual IlvValuepullValue (IlvValue &v) const
 See below.
 
virtual void pullValues (IlvValue *vals, IlUShort c) const
 Propagates value queries to the subscribers to this object. More...
 
virtual IlBoolean pushValue (const IlvValue &v) const
 See below.
 
virtual IlBoolean pushValues (const IlvValue *vals, IlUShort c) const
 Propagates value changes to the subscribers to this object. More...
 

Static Public Member Functions

static IlvGroupload (const char *name, IlvDisplay *display, ILVSTDPREF istream *stream=0, const char *path=0)
 Loads a group from an input stream or from a disk file. More...
 

Friends

class IlvGroupInputFile
 
class IlvGroupNode
 
class IlvGroupOutputFile
 
class IlvSubGroupNode
 
class IlvUserAccessor
 

Detailed Description

Base class to hold graphic objects together and assign behaviors to them.

Library: ilvproto

IlvGroup is the base class used in the prototypes library to logically compose objects and assign behaviors to them. An IlvGroup is a tree. The nodes of the tree are instances of subclasses of the IlvGroupNode class. The IlvGroupNode class must be subclassed for all objects contained in groups. IlvGroupNode has two subclasses:

Other subclasses of IlvGroupNode may be written to include other types of objects in groups.

Accessors are base 'bricks' of behavior that hold data (in which case they are called 'attributes') or perform side effects. Therefore, an attribute is a name that can be referenced to store data or perform side effects when a call to changeValue or queryValue is made. An attribute can consist of several accessors, each one defining part of what the attribute is meant to do.

To be placed in an IlvManager or IlvContainer, create an IlvProtoGraphic object that encapsulates the group, and then place that object into the container or manager. An alternative method is to retrieve the IlvGroupHolder associated with the manager or container, and use the IlvGroupHolder::addGroup() method.

See Also
IlvGraphicNode, IlvGroupNode, IlvSubGroupNode, IlvProtoGraphic, IlvGroupHolder.

Constructor & Destructor Documentation

IlvGroup::IlvGroup ( const char *  name = 0)

Creates a new, empty group with the specified name.

Parameters
nameName of the group. The string pointed to by the parameter is copied (if it exists).
IlvGroup::IlvGroup ( const IlvGroup source)

Creates a copy of the source group.

A complete copy of the group hierarchy is made by calling the copy method of each node.

Member Function Documentation

void IlvGroup::addAccessor ( IlvUserAccessor accessor,
IlBoolean  owner = IlTrue,
IlBoolean  initialize = IlTrue,
IlBoolean  sort = IlFalse,
IlvUserAccessor previous = 0 
)

Adds an accessor to the group.

Parameters
accessorAccessor to add.
ownerIf set to IlTrue, the accessor will be deleted when the group is deleted.
initializeSet to IlTrue if IlvAccessor::initialize is called once the accessor has been added.
sortSet to IlTrue if accessors are sorted after the accessor has been added. If adding multiple accessors, you can optimize insertion by setting IlTrue only when the last of a batch of accessors has been added.
previousMust be an accessor of the group. If provided, accessor will be added after previous.
void IlvGroup::addNode ( IlvGroupNode node,
IlBoolean  uniqueName = IlFalse 
)

Adds the node node to the group.

Parameters
nodeNode to add to the group.
uniqueNameIf this flag is set to IlTrue, the name of the new node is checked against the names of existing nodes in this group, and if a duplicate is found, the name of the new node is modified by adding a suffix of the form node->getName() + "_" + index .
virtual IlBoolean IlvGroup::changeValue ( const IlvValue v)
virtual

Changes the object's value. Both the name and the new value are contained in val.

Parameters
vThe value to be set (both name and value).
Returns
Whether the object considered the operation successful or not.

Reimplemented from IlvAccessorHolder.

virtual IlBoolean IlvGroup::changeValues ( const IlvValue v,
IlUShort  c 
)
virtual

Changes several values of an object in a single call. The default implementation calls changeValue for all values.

Parameters
vThe changed values (both name and values).
cThe number of values.
Returns
Whether the object considered the operation successful or not.

Reimplemented from IlvAccessorHolder.

IlvGroupNode* IlvGroup::findNode ( const char *  name,
IlBoolean  actual = IlTrue 
) const

Finds the node whose name is specified as argument.

Parameters
nameName of the node to find. The node name can contain dot characters to find a node contained in a subgroup. For example: subgroup1.subgroup2.rectangle.
actualObsolete parameter. Should be left to IlTrue.
Returns
The group node found, or 0 if no node has been found.
IlUInt IlvGroup::getAccessorList ( const char **&  names,
const char **&  types,
IlBoolean  all = IlFalse,
IlBoolean  output = IlFalse 
) const

Returns names and types of the attributes defined in the group.

Parameters
namesA pointer to an allocated array of strings indicating all attribute names. Must be freed with delete[] when no longer needed.
typesA pointer to an allocated array of type names indicating, for each name in names, the type of the corresponding attribute. Must be freed with delete[] when no longer needed.
allIf set to IlTrue, all the attributes of the group are returned, including private accessors and accessors of subgroups. Otherwise, only the names and types of the IlvUserAccessors added to this group that are not flagged as private, and the built-in accessors defined by the IlvGraphicNode class (x, y, with, height, visible, and so on) are returned.
outputIf set to IlTrue, only the attributes that have a notifying accessor are returned.
Returns
The number of names and types.
See Also
IlvOutputAccessor
virtual void IlvGroup::getAccessors ( const IlSymbol *const **  a,
const IlvValueTypeClass *const **  t,
IlUInt c 
) const
virtual

Returns the names of all the accessors known by this object.

Subclasses of IlvAccessible must override this method by calling the static method DeclareAccessor for each accessor handled by the subclass. The returned arrays are filled by the method and must not be freed.

Parameters
aPointer to an array filled on return with the names of the accessors defined for the object.
tPointer to an array filled on return with the type of each accessor.
cNumber of accessors, set by the method.

Reimplemented from IlvAccessorHolder.

virtual const char* IlvGroup::getName ( ) const
virtual

Returns the object name.

Returns
The object name. This pointer must not be freed.

Implements IlvAccessible.

IlUInt IlvGroup::getNodeCount ( ) const

Returns the number of nodes in the group.

Returns
The number of nodes in the group.
const char** IlvGroup::getNodeNames ( IlUInt count)

Returns the names of all the nodes of the group, including the nodes of subgroups.

Parameters
countNumber of nodes, returned by the method.
Returns
The name of subgroup nodes prefixed by the name of the group and a dot (for example, a subgroup of name B inside a group of name A would be named A.B). These names can be used as the parameters of the findNode method. The returned pointer must be released using the delete[] operator.
IlvGroupNode** IlvGroup::getNodes ( IlUInt count)

Returns the nodes in the group.

Parameters
countNumber of nodes, returned by the method.
Returns
An array of group nodes, that should be deleted with delete[] when no longer needed.
virtual const IlvValueTypeClass* IlvGroup::getValueType ( const IlSymbol s) const
virtual

Returns the type of a given attribute.

Returns
The type of this object accessor, or IlvValueNoType if the accessor does not exist.
Parameters
Thename of the accessor.

Reimplemented from IlvAccessible.

virtual IlBoolean IlvGroup::isOutputValue ( const IlSymbol value) const
virtual

Indicates whether value designates an accessor that can generate notifying values.

Returns
IlTrue if value designates an accessor that can generate notifying values, that is, a value for which pushValue calls may be issued. The default implementation returns IlFalse. Subclasses such as IlvAccessorHolder redefine this method.
Parameters
valueName of the accessor.
See Also
pushValue.

Reimplemented from IlvAccessorHolder.

static IlvGroup* IlvGroup::load ( const char *  name,
IlvDisplay display,
ILVSTDPREF istream *  stream = 0,
const char *  path = 0 
)
static

Loads a group from an input stream or from a disk file.

If stream is non-null, the group description is read from stream. Otherwise, a description file named <name>.ivp is searched for on the disk, and the group is loaded from this file. Group description files only contain a group hierarchical structure. The actual objects are saved separately in an object-dependent way, defined by the subclass of IlvGroupNode. For IlvGraphics, the objects are saved in a .ilv file. If supplied, the path argument is used as a base directory to build the name of the graphic file (.ilv) that contains the graphic nodes of the group.

Parameters
nameName of the file to look for if stream is NULL.
displayDisplay used to initialize graphic objects and accessors.
streamInput stream to read the group description from.
pathIf non-null, used as a base directory to find files that may be referenced by the group.
Returns
A pointer to a newly allocated group if the loading process was successful, and 0 otherwise. The group can be deleted with delete[] when it is no longer needed.
virtual IlvAccessor* IlvGroup::nextAccessor ( IlAny link) const
virtual

Iterator through the accessors.

Returns the next accessor from a list of accessors owned by the IlvAccessorHolder object. If link is NULL, the first accessor is returned, and link is modified so that the next call to nextAccessor will return all the accessors successively. When all the accessors have been returned, the method returns 0.

Implements IlvAccessorHolder.

IlvGroupNode* IlvGroup::nextNode ( IlAny link) const

Node iterator.

Lets you iterate through all the nodes in the group (no node should be moved or removed when iterating through all nodes). A typical use is:

IlvGroup* g; IlvGroupNode* gn; IlvAny link=0;
while ((gn=g->nextNode(link)) != 0) {
   // do whatever is needed with gn, but do not destroy it
   // or remove it from g !
}
Parameters
linkHidden value used to maintain internal data of the iterator. It should be set to 0 to start iterating at the beginning. Successive invocations of the method should always pass the same link for the iterator to perform correctly.
Returns
The next node in a group of nodes, or 0 if all nodes have been iterated through.
virtual IlvUserAccessor* IlvGroup::nextUserAccessor ( IlAny link) const
virtual

User accessor iterator.

Lets you iterate through all the user accessors in the group (no accessor should be moved or removed while iterating through all accessors). A typical use is:

while ((a=(IlvUserAccessor*)g->nextUserAccessor(link)) != 0) {
// do whatever is needed with a, but do not destroy it
// or remove it from g !
}
Parameters
linkHidden value used to maintain internal data of the iterator. It should be set to 0 to start iterating at the beginning. Successive invocations of the method should always pass the same link for the iterator to perform correctly.
Returns
The next user accessor in a group, or 0 if all user accessors have been iterated through.
virtual IlvValue& IlvGroup::queryValue ( IlvValue value) const
virtual

Queries the value designated by value from the object. Both the value and the value type are stored in value.

Parameters
valueThe queried value name.
Returns
The value passed in argument, set to the object value.

Reimplemented from IlvAccessorHolder.

virtual void IlvGroup::queryValues ( IlvValue v,
IlUShort  c 
) const
virtual

Queries several values in a single call. The default implementation calls queryValue for each value.

Parameters
vThe array of value names to be queried
cThe number of values to be queried.

Reimplemented from IlvAccessorHolder.

void IlvGroup::removeAccessor ( IlvAccessor accessor,
IlBoolean  deleteIt = IlTrue 
)

Removes an accessor from the group.

Parameters
accessorAccessor to remove. If it was added with the owner parameter set to IlTrue in the addAccessor method, it is deleted (unless the destroy flag is set to false).
deleteItIf set to IlFalse, the accessor will not be deleted.
void IlvGroup::removeNode ( IlvGroupNode node,
IlBoolean  deleteIt = IlTrue 
)

Removes a node from the group.

Parameters
nodeNode to be removed.
deleteItIf IlTrue, the node is deleted.
IlBoolean IlvGroup::save ( ILVSTDPREF ostream *  stream = 0,
const char *  path = 0 
)

Saves a group to an output stream or to a disk file.

If stream is non-null, the group description is written to stream. Otherwise, the group is saved to the file [name].ivp. If supplied, the path argument is used as a base directory to build the name of the graphic file (.ilv) that contains the graphic nodes of the group.

Parameters
streamOutput stream to write the groups description into.
pathIf supplied, used as a base directory to find the files the group description may reference.
Returns
IlTrue if save was successful.
virtual void IlvGroup::setName ( const char *  name)
virtual

Changes the name of this group.

Parameters
nameThe new name of this group. The string is copied.

Reimplemented in IlvPrototype.

virtual void IlvGroup::subscribe ( IlvAccessible subscriber,
IlSymbol sourceValue,
IlSymbol subscriberValue,
IlvValueTypeClass type,
IlvValueSubscriptionMode  mode = IlvValueSubscriptionChange 
)
virtual

Subscribes the subscriber object to the value sourceValue of this object.

After this subscription, every call to this object pushValue method with a value name of sourceValue will cause the subscriber changeValue method to be called with the value name subscriberValue, and with the value data passed to the initial pushValue call of the value source. The type parameter specifies the type of the sourceValue and subscriberValue values. An IlvAccessible object can subscribe several times to another IlvAccessible object for different source values and/or subscriber values, but it may not subscribe several times to the same object and subscriber values. The mode argument specifies whether the subscriber wants to be notified of value changes (this is the default mode IlvValueSubscriptionChange), or if it wants to be notified of value queries (mode IlvValueSubscriptionQuery). In this last case, the source object notifies its subscribers of calls to pullValue instead of pushValue by calling queryValue instead of changeValue.

Parameters
subscriberThe object to be notified of accesses to sourceValue.
sourceValueThe name of the attribute to be observed by the subscription.
subscriberValueThe name of the attribute to be notified in the subscriber.
typeThe expected value type to be pushed to the subscriber.
modeThe type of access to sourceValue to be reported to subscriber.
See Also
IlvValueSubscriptionMode

Reimplemented from IlvAccessible.

virtual void IlvGroup::unSubscribe ( IlvAccessible subscriber,
IlSymbol sourceValue = 0,
IlSymbol subscriberValue = 0 
)
virtual

Cancels subscriptions previously made.

Cancels the subscription of the subscriber object to the specified sourceValue and subscriberValue. If sourceValue is 0, the subscriptions of subscriber to all source values are cancelled. If subscriberValue is 0, the subscriptions of subscriber for all subscriber values are removed. If both are 0, all subscriptions of subscriber to this source object are cancelled.

Parameters
subscriberThe object that is to be notified of accesses to sourceValue.
sourceValueThe name of the attribute to be observed by the subscription.
subscriberValueThe name of the attribute to be notified in the subscriber.

Reimplemented from IlvAccessible.

virtual IlBoolean IlvGroup::update ( const IlvGroup source)
virtual

Updates the group (deep-inplace copy).

Uses compareValues to store the differing values between this and source, replaces all the nodes and behaviors of this by those of source, and then reassigns the previously stored differing values to this (by calling changeValues. This method is mainly used to update IlvProtoInstances when a prototype is modified.

Parameters
sourceGroup to update from.
See Also
IlvPrototype, IlvProtoInstance.

Reimplemented in IlvProtoInstance, and IlvPrototype.


© Copyright 2012, Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.