Rogue Wave Views
Prototypes Package API Reference Guide
Product Documentation:

Rogue Wave Views
Documentation Home
List of all members | Public Member Functions | Friends
IlvPrototype Class Reference

Clonable group. More...

#include <ilviews/protos/proto.h>

Inheritance diagram for IlvPrototype:
IlvGroup IlvAccessorHolder IlvAccessible IlvValueInterface

Public Member Functions

 IlvPrototype (const char *name)
 Creates an empty prototype. More...
 
 IlvPrototype (IlvGroup &group)
 Creates a prototype by copying an existing group. More...
 
IlvProtoInstanceclone (const char *name=0)
 Creates a new instance of the prototype, with the name name. More...
 
void deleteInstance (IlvProtoInstance *instance)
 Deletes an instance. More...
 
IlvProtoInstancegetInstance (const char *name) const
 Finds an instance of the prototype by name. More...
 
IlvProtoInstancenextInstance (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...
 
IlvGroupNodefindNode (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...
 
IlvGroupgetParent () const
 If this group is a subgroup of another group, returns the parent group. Otherwise, returns 0.
 
IlvGroupNodegetParentNode () const
 Returns the instance of IlvSubGroupNode that contains the group if this group is a subgroup of another group, or 0 otherwise.
 
IlvGroupgetTopGroup ()
 Returns the top-most parent of the group if this group is a subgroup. Otherwise, it returns 0.
 
virtual const IlvValueTypeClassgetValueType (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 IlvAccessornextAccessor (IlAny &link) const
 Iterator through the accessors. More...
 
IlvGroupNodenextNode (IlAny &link) const
 Node iterator. More...
 
virtual IlvUserAccessornextUserAccessor (IlAny &link) const
 User accessor iterator. More...
 
virtual IlvValuequeryValue (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 IlvValuepullValue (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 IlvGroupload (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 IlvValueTypeClassGetType (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::IlvPrototype ( const char *  name)

Creates an empty prototype.

Parameters
nameName of the prototype. Prototypes cannot have a null name.
IlvPrototype::IlvPrototype ( IlvGroup group)

Creates a prototype by copying an existing group.

Parameters
groupGroup 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 0 , a unique name of the form <prototype-name>_<index> is assigned to the instance.

Parameters
nameName 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
instanceInstance of the prototype to delete.
IlvProtoInstance* IlvPrototype::getInstance ( const char *  name) const

Finds an instance of the prototype by name.

Parameters
nameThe 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
linkIf 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().
virtual void IlvPrototype::setName ( const char *  name)
virtual

Changes the name of this group.

Parameters
nameThe 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
groupThe group to update the prototype from.
Returns
IlTrue if the update process was successful.

Reimplemented from IlvGroup.


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