rwlogo
Rogue Wave Views 5.5.1

Rogue Wave Views
Prototypes Package API Reference Guide
Product Documentation:

Rogue Wave Views
Documentation Home

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

List of all members.

Public Member Functions

 IlvGroup (const IlvGroup &source)
 Creates a copy of the source group.
 IlvGroup (const char *name=0)
 Creates a new, empty group with the specified name.
void addAccessor (IlvUserAccessor *accessor, IlBoolean owner=IlTrue, IlBoolean initialize=IlTrue, IlBoolean sort=IlFalse, IlvUserAccessor *previous=0)
 Adds an accessor to the group.
void addNode (IlvGroupNode *node, IlBoolean uniqueName=IlFalse)
 Adds the node node to the group.
virtual IlBoolean changeValue (const IlvValue &val)
 Changes the object's value. Both the name and the new value are contained in val.
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.
IlvGroupNode * findNode (const char *name, IlBoolean actual=IlTrue) const
 Finds the node whose name is specified as argument.
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.
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.
virtual const char * getName () const
 Returns the object name.
IlUInt getNodeCount () const
 Returns the number of nodes in the group.
const char ** getNodeNames (IlUInt &count)
 Returns the names of all the nodes of the group, including the nodes of subgroups.
IlvGroupNode ** getNodes (IlUInt &count)
 Returns the nodes in the group.
IlvGroup * getParent () const
 If this group is a subgroup of another group, returns the parent group. Otherwise, returns 0.
IlvGroupNode * getParentNode () const
 Returns the instance of IlvSubGroupNode that contains the group if this group is a subgroup of another group, or 0 otherwise.
IlvGroup * getTopGroup ()
 Returns the top-most parent of the group if this group is a subgroup. Otherwise, it returns 0.
virtual const IlvValueTypeClass * getValueType (const IlSymbol *) const
 Returns the type of a given attribute.
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.
virtual IlvAccessor * nextAccessor (IlAny &link) const
 Iterator through the accessors.
IlvGroupNode * nextNode (IlAny &link) const
 Node iterator.
virtual IlvUserAccessor * nextUserAccessor (IlAny &link) const
 User accessor iterator.
virtual IlvValue & queryValue (IlvValue &val) const
 Queries the value designated by value from the object. Both the value and the value type are stored in value.
virtual void queryValues (IlvValue *values, IlUShort count) const
 Queries several values in a single call. The default implementation calls queryValue for each value.
void removeAccessor (IlvAccessor *accessor, IlBoolean deleteIt=IlTrue)
 Removes an accessor from the group.
void removeNode (IlvGroupNode *node, IlBoolean deleteIt=IlTrue)
 Removes a node from the group.
IlBoolean save (ILVSTDPREF ostream *stream=0, const char *path=0)
 Saves a group to an output stream or to a disk file.
virtual void setName (const char *name)
 Changes the name of this group.
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.
virtual void unSubscribe (IlvAccessible *subscriber, IlSymbol *sourceValue=0, IlSymbol *subscriberValue=0)
 Cancels subscriptions previously made.
virtual IlBoolean update (const IlvGroup &source)
 Updates the group (deep-inplace copy).

Static Public Member Functions

static IlvGroup * load (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.

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:
name Name 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:
accessor Accessor to add.
owner If set to IlTrue, the accessor will be deleted when the group is deleted.
initialize Set to IlTrue if IlvAccessor::initialize is called once the accessor has been added.
sort Set 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.
previous Must 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:
node Node to add to the group.
uniqueName If 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:
v The 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:
v The changed values (both name and values).
c The 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:
name Name 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.
actual Obsolete 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:
names A pointer to an allocated array of strings indicating all attribute names. Must be freed with delete[] when no longer needed.
types A 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.
all If 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.
output If 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:
a Pointer to an array filled on return with the names of the accessors defined for the object.
t Pointer to an array filled on return with the type of each accessor.
c Number 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:
count Number 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:
count Number 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:
The name 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:
value Name 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:
name Name of the file to look for if stream is NULL.
display Display used to initialize graphic objects and accessors.
stream Input stream to read the group description from.
path If 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:
link Hidden 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: 

 IlvGroup* g; IlvUserAccessor* a; IlvAny link=0;
 while ((a=(IlvUserAccessor*)g->nextUserAccessor(link)) != 0) {
    // do whatever is needed with a, but do not destroy it
    // or remove it from g !
 }
Parameters:
link Hidden 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:
value The 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:
v The array of value names to be queried
c The number of values to be queried.

Reimplemented from IlvAccessorHolder.

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

Removes an accessor from the group.

Parameters:
accessor Accessor 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).
deleteIt If set to IlFalse, the accessor will not be deleted.
void IlvGroup::removeNode ( IlvGroupNode *  node,
IlBoolean  deleteIt = IlTrue 
)

Removes a node from the group.

Parameters:
node Node to be removed.
deleteIt If 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:
stream Output stream to write the groups description into.
path If 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:
name The 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:
subscriber The object to be notified of accesses to sourceValue.
sourceValue The name of the attribute to be observed by the subscription.
subscriberValue The name of the attribute to be notified in the subscriber.
type The expected value type to be pushed to the subscriber.
mode The 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:
subscriber The object that is to be notified of accesses to sourceValue.
sourceValue The name of the attribute to be observed by the subscription.
subscriberValue The 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:
source Group to update from.
See also:
IlvPrototype, IlvProtoInstance.

Reimplemented in IlvPrototype, and IlvProtoInstance.

© 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.