IlvPrototype Class Reference

Clonable group. More...

#include <ilviews/protos/proto.h>

Inheritance diagram for IlvPrototype:

List of all members.

Public Member Functions
	IlvPrototype (IlvGroup &group)
	Creates a prototype by copying an existing group.
	IlvPrototype (const char *name)
	Creates an empty prototype.
IlvProtoInstance *	clone (const char *name=0)
	Creates a new instance of the prototype, with the name name.
void	deleteInstance (IlvProtoInstance *instance)
	Deletes an instance.
IlvProtoInstance *	getInstance (const char *name) const
	Finds an instance of the prototype by name.
IlvProtoInstance *	nextInstance (IlAny &link) const
	Iterator on the instances of the prototype.
virtual void	setName (const char *name)
	Changes the name of this group.
IlBoolean	update (const IlvGroup &group)
	Updates the prototype and all its instances to a new definition.
Friends
class	IlvAbstractProtoLibrary
class	IlvProtoInstance
class	IlvProtoLibrary

---

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

See also:

IlvAbstractProtoLibrary, IlvGetPrototype, IlvGroup, IlvLoadPrototype, IlvProtoGraphic, IlvProtoInstance, IlvProtoLibrary.

---

Constructor & Destructor Documentation

IlvPrototype::IlvPrototype

(

const char *

name

)

Creates an empty prototype.

Parameters:

name

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

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

IlvProtoInstance* IlvPrototype::clone

(

const char *

name = 0

)

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

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

Parameters:

name

Name of the newly created instance.

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.

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.

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 NULL (and sets link to NULL) when all the instances have been returned.

Returns:

The next instance in the list of the prototype instances.

See also:

IlvGroup::nextNode, IlvGroup::nextUserAccessor.

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.

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.