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

#include <ilviews/protos/group.h>

Inheritance diagram for IlvGroup:

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

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:

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.

See also: IlvGraphicNode, IlvGroupNode, IlvSubGroupNode, IlvProtoGraphic, IlvGroupHolder.

Constructor & Destructor Documentation

§ IlvGroup() [1/2]

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() [2/2]

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

§ addAccessor()

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.

§ addNode()

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

§ changeValue()

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.

§ changeValues()

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.

§ findNode()

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.

§ getAccessorList()

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

Returns: The number of names and types.

See also: IlvOutputAccessor

§ getAccessors()

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.

§ getName()

virtual const char* IlvGroup::getName ( ) const

virtual

Returns the object name.

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

Implements IlvAccessible.

§ getNodeCount()

IlUInt IlvGroup::getNodeCount ( ) const

Returns the number of nodes in the group.

Returns: The number of nodes in the group.

§ getNodeNames()

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.

§ getNodes()

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.

§ getValueType()

virtual const IlvValueTypeClass* IlvGroup::getValueType ( const IlSymbol * s ) const

virtual

Returns the type of a given attribute.

Parameters

s	The name of the accessor.

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

Reimplemented from IlvAccessible.

§ isOutputValue()

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.

§ load()

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 `0`.
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.

§ nextAccessor()

virtual IlvAccessor* IlvGroup::nextAccessor ( IlAny & link ) const

virtual

Iterator through the accessors.

Parameters

link	a placeholder for an internal marker in the accessors list that allows for iterating.

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.

§ nextNode()

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.

§ nextUserAccessor()

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.

§ queryValue()

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.

§ queryValues()

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.

§ removeAccessor()

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.

§ removeNode()

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.

§ save()

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.

§ setName()

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.

§ subscribe()

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.

§ unSubscribe()

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.

§ update()

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 IlvProtoInstance, and IlvPrototype.

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

§ IlvGroup() [1/2]

§ IlvGroup() [2/2]

Member Function Documentation

§ addAccessor()

§ addNode()

§ changeValue()

§ changeValues()

§ findNode()

§ getAccessorList()

§ getAccessors()

§ getName()

§ getNodeCount()

§ getNodeNames()

§ getNodes()

§ getValueType()

§ isOutputValue()

§ load()

§ nextAccessor()

§ nextNode()

§ nextUserAccessor()

§ queryValue()

§ queryValues()

§ removeAccessor()

§ removeNode()

§ save()

§ setName()

§ subscribe()

§ unSubscribe()

§ update()