Rogue Wave Views Prototypes Package API Reference Guide |
Rogue Wave Views Documentation Home |
Base class to hold graphic objects together and assign behaviors to them. More...
#include <ilviews/protos/group.h>
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... | |
IlvGroupNode * | findNode (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... | |
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. 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 IlvAccessor * | nextAccessor (IlAny &link) const |
Iterator through the accessors. More... | |
IlvGroupNode * | nextNode (IlAny &link) const |
Node iterator. More... | |
virtual IlvUserAccessor * | nextUserAccessor (IlAny &link) const |
User accessor iterator. More... | |
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. 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 IlvValue & | pullValue (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 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. More... | |
Static Public Member Functions inherited from IlvAccessible | |
static void | DeclareAccessor (const IlSymbol *attr, IlvValueTypeClass *type, const IlSymbol *const **accessors, const IlvValueTypeClass *const **types, IlUInt &count, IlBoolean checkDuplicates=IlFalse, IlAny accessorList=0) |
static const IlvValueTypeClass * | GetType (IlSymbol *name) |
Returns the type instance from a name. More... | |
static IlBoolean | StringToValue (const char *s, IlSymbol *type, IlvValue &v, IlvDisplay *display) |
Converts the character string s to an IlvValue with the type type. More... | |
static IlBoolean | StringToValue (const char *s, const IlvValueTypeClass *typeClass, IlvValue &v, IlvDisplay *d) |
Converts the character string s to an IlvValue with the type type. More... | |
static IlBoolean | ValuesAreEqual (IlvValue &v1, IlvValue &v2, IlBoolean compareNames=IlTrue) |
Compares two values. More... | |
Friends | |
class | IlvGroupInputFile |
class | IlvGroupNode |
class | IlvGroupOutputFile |
class | IlvSubGroupNode |
class | IlvUserAccessor |
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:
IlvGraphicNode
is used for instances of IlvGraphic
subclasses. IlvSubGroupNode
is used to include subgroups in groups. 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.
IlvGroup::IlvGroup | ( | const char * | name = 0 | ) |
Creates a new, empty group with the specified name.
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.
void IlvGroup::addAccessor | ( | IlvUserAccessor * | accessor, |
IlBoolean | owner = IlTrue , |
||
IlBoolean | initialize = IlTrue , |
||
IlBoolean | sort = IlFalse , |
||
IlvUserAccessor * | previous = 0 |
||
) |
Adds an accessor to the group.
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.
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 . |
Changes the object's value. Both the name and the new value are contained in val.
v | The value to be set (both name and value). |
Reimplemented from IlvAccessorHolder.
Changes several values of an object in a single call. The default implementation calls changeValue()
for all values.
v | The changed values (both name and values). |
c | The number of values. |
Reimplemented from IlvAccessorHolder.
IlvGroupNode* IlvGroup::findNode | ( | const char * | name, |
IlBoolean | actual = IlTrue |
||
) | const |
Finds the node whose name is specified as argument.
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 . |
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.
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 IlvUserAccessor s 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. |
|
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.
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 |
Returns the object name.
Implements IlvAccessible.
IlUInt IlvGroup::getNodeCount | ( | ) | const |
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.
count | Number of nodes, returned by the method. |
findNode
method. The returned pointer must be released using the delete[]
operator. IlvGroupNode** IlvGroup::getNodes | ( | IlUInt & | count | ) |
Returns the nodes in the group.
count | Number of nodes, returned by the method. |
delete[]
when no longer needed.
|
virtual |
Returns the type of a given attribute.
s | The name of the accessor. |
IlvValueNoType
if the accessor does not exist. Reimplemented from IlvAccessible.
Indicates whether value designates an accessor that can generate notifying values.
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. value | Name of the accessor. |
pushValue()
. Reimplemented from IlvAccessorHolder.
|
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 IlvGraphic
s, 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.
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. |
0
otherwise. The group can be deleted with delete[]
when it is no longer needed.
|
virtual |
Iterator through the accessors.
link | a placeholder for an internal marker in the accessors list that allows for iterating. |
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 ! }
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. |
0
if all nodes have been iterated through.
|
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:
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. |
0
if all user accessors have been iterated through. Queries the value designated by value from the object. Both the value and the value type are stored in value.
value | The queried value name. |
Reimplemented from IlvAccessorHolder.
Queries several values in a single call. The default implementation calls queryValue()
for each value.
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.
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.
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.
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. |
IlTrue
if save was successful.
|
virtual |
Changes the name of this group.
name | The new name of this group. The string is copied. |
Reimplemented in IlvPrototype.
|
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()
.
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. |
Reimplemented from IlvAccessible.
|
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.
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.
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 IlvProtoInstance
s when a prototype is modified.
source | Group to update from. |
Reimplemented in IlvProtoInstance, and IlvPrototype.
© Copyright 2016, 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.