Clonable group. More...

#include <ilviews/protos/proto.h>

Inheritance diagram for IlvPrototype:

Public Member Functions
	IlvPrototype (const char *name)
	Creates an empty prototype. More...

	IlvPrototype (IlvGroup &group)
	Creates a prototype by copying an existing group. More...

IlvProtoInstance *	clone (const char *name=0)
	Creates a new instance of the prototype, with the name name. More...

void	deleteInstance (IlvProtoInstance *instance)
	Deletes an instance. More...

IlvProtoInstance *	getInstance (const char *name) const
	Finds an instance of the prototype by name. More...

IlvProtoInstance *	nextInstance (IlAny &link) const
	Iterator on the instances of the prototype. More...

virtual void	setName (const char *name)
	Changes the name of this group. More...

IlBoolean	update (const IlvGroup &group)
	Updates the prototype and all its instances to a new definition. More...

Public Member Functions inherited from IlvGroup
	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	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...

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

Friends
class	IlvAbstractProtoLibrary

class	IlvProtoInstance

class	IlvProtoLibrary

Additional Inherited Members
Static Public Member Functions inherited from IlvGroup
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...

Detailed Description

Clonable group.

Library: ilvproto

An IlvPrototype is a group that can create instances of the IlvProtoInstance class. Prototype instances can be updated if the prototype is changed. When prototype instances are saved to streams or files, only the values that are changed with respect to the prototype will be saved; the other values will be inherited from the prototype. Prototypes are loaded automatically when you load a file containing prototype instances. You can also load a prototype explicitly using the function IlvLoadPrototype().

See also: IlvAbstractProtoLibrary, IlvGetPrototype, IlvGroup, IlvLoadPrototype(), IlvProtoGraphic, IlvProtoInstance, IlvProtoLibrary.

Constructor & Destructor Documentation

§ IlvPrototype() [1/2]

IlvPrototype::IlvPrototype ( const char * name )

Creates an empty prototype.

Parameters

name	Name of the prototype. Prototypes cannot have a null name.

§ IlvPrototype() [2/2]

IlvPrototype::IlvPrototype ( IlvGroup & group )

Creates a prototype by copying an existing group.

Parameters

group Group to transform into a prototype. A full copy of group is made.

Member Function Documentation

§ clone()

IlvProtoInstance* IlvPrototype::clone ( const char * name = 0 )

Creates a new instance of the prototype, with the name name.

If name is 0 , a unique name of the form <prototype-name>_<index> is assigned to the instance.

Parameters

name	Name of the newly created instance.

§ deleteInstance()

void IlvPrototype::deleteInstance ( IlvProtoInstance * instance )

Deletes an instance.

You can also delete the instance directly using the delete operator, which will remove it from the instance list of the prototype. All instances of a prototype are destroyed when the prototype is destroyed.

Parameters

instance Instance of the prototype to delete.

§ getInstance()

IlvProtoInstance* IlvPrototype::getInstance ( const char * name ) const

Finds an instance of the prototype by name.

Parameters

name	The name of the prototype that is searched.

Returns: The instance that has a name that matches name, or 0 if there is none.

§ nextInstance()

IlvProtoInstance* IlvPrototype::nextInstance ( IlAny & link ) const

Iterator on the instances of the prototype.

Parameters

link	If `0`, the function returns the first instance of the prototype, and modifies link so that subsequent calls will iterate through all the instances of the prototype. Returns `0` (and sets link to `0`) when all the instances have been returned.

Returns: The next instance in the list of the prototype instances.

See also: IlvGroup::nextNode(), IlvGroup::nextUserAccessor().

§ setName()

virtual void IlvPrototype::setName ( const char * name )

virtual

Changes the name of this group.

Parameters

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

Reimplemented from IlvGroup.

§ update()

IlBoolean IlvPrototype::update ( const IlvGroup & group )

virtual

Updates the prototype and all its instances to a new definition.

When a prototype is edited (for example, by adding graphic nodes or accessors) its instances need to be updated at some point to reflect the new definition. This method does so by proceeding in the following order:

Store the modified values of all the instances of the prototype in a temporary array.
Remove all the nodes, accessors, and subscriptions of the prototype, replacing them by those of group (by calling IlvGroup::update(group)).
Rebuild the initial values array and reapply them to obtain a consistent state.
Update all the instances of the prototype in the same way, replacing their nodes, accessors, and subscriptions with copies of the nodes, accessors, and subscription of the prototype (by calling IlvGroup::update(*this) on each instance).
Reapply the modified values of the instances to themselves, so that the state of the instance is more or less the same as it was before the update.

Some information may be lost in the process, such as links the instances were connected to: if the new definition for the prototype has changed drastically, connections and subscriptions may be lost. However, for localized changes, this process is necessary to allow a prototype to evolve from one version to another with the instances still being used in other panels.

In Studio, update() is called each time a prototype definition window is saved.

Parameters

group The group to update the prototype from.

Returns: IlTrue if the update process was successful.

Reimplemented from IlvGroup.

Public Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

§ IlvPrototype() [1/2]

§ IlvPrototype() [2/2]

Member Function Documentation

§ clone()

§ deleteInstance()

§ getInstance()

§ nextInstance()

§ setName()

§ update()