IlvValueInterface Class Reference

Value interface class. More...

#include <ilviews\intrface\value.h>

Inheritance diagram for IlvValueInterface:

Public Member Functions
virtual IlBoolean	applyValue (const IlvValue &value)
	Apply an accessor. More...
virtual IlBoolean	changeValue (const IlvValue &val)
	Changes the value of an accessor. More...
virtual IlBoolean	changeValues (const IlvValue *values, IlUShort count=0)
	Changes several accessor values simultaneously. More...
virtual void	getAccessors (const IlSymbol *const **names, const IlvValueTypeClass *const **types, IlUInt &count) const
	Retrieves the list of available accessors of an object. More...
virtual const char *	getName () const
	Returns the name of the instance. The semantic and implementation of this method are defined by concrete subclasses. The default implementation returns 0. More...
virtual IlvValue &	queryValue (IlvValue &val) const
	Retrieves an accessor value. More...
virtual void	queryValues (IlvValue *values, IlUShort count) const
	Retrieves multiple accessor values simultaneously. More...

Detailed Description

Value interface class.

Library: xviews or winviews or mviews (mutually exclusive)

IlvValueInterface is an abstract class defining the programming interface for subclasses wishing to expose their properties and methods through a generic and uniform mechanism similar to introspection.
An application can manipulate an instance of IlvValueInterface, or more precisely an instance of a subclass, by using its methods queryValue() and changeValue(), and without explicit knowledge of the concrete subclass.

Although applications seldom need this feature directly, it is extremely useful when defining a binding between Views libraries and a scripting language. The IlvValueInterface mechanism then becomes the invisible layer by which the scripting language is able to manipulate C++ objects.

Many predefined classes derive from IlvValueInterface, in particular IlvGraphic, IlvView, IlvGadgetItem, IlvManager, and of course all their subclasses.

IlvValueInterface implementation is based on the class IlvValue, which is basically a triplet [ name, type, value ] and a set of operators.

In order to expose a property, a subclass of IlvValueInterface defines an accessor. An accessor can be seen as an association between a name, a type identifier, and a data member with functions to get and set this data member value.
To define new accessors, a subclass must override the method getAccessors() and declare a name and a type for each accessor. The name must be unique.
Then, the subclass must override queryValue() if the subclass allows to get the data members values, and applyValue() if it allows to set these values.

Accessors

This class defines the following accessors:

Name	Type	Equivalent methods
name	String	getName()

See also

IlvValue.

Member Function Documentation

applyValue()

virtual IlBoolean IlvValueInterface::applyValue ( const IlvValue &  value )

virtual

Apply an accessor.

This member function is called by changeValue() and changeValues() methods. It must not be called directly.
This method must be overriden by subclasses wishing to add a new accessor modifiable by changeValue().

Parameters

value

The new value of the accessor.

Returns

IlTrue on success, otherwise IlFalse.

Reimplemented in IlvSystemPort, IlvScriptFunction, IlvGraphicInstance, and IlvGraphicCOMAdapter.

changeValue()

virtual IlBoolean IlvValueInterface::changeValue ( const IlvValue &  val )

virtual

Changes the value of an accessor.

The changeValue() method can be used in the following way:

IlvValue arg("x", 340);
object->changeValue(arg);

Parameters

val	The new value of the accessor.

Returns

IlTrue if the accessor value is changed successfuly.

See also

IlvValue.

changeValues()

virtual IlBoolean IlvValueInterface::changeValues ( const IlvValue *  values, IlUShort  count = 0  )

virtual

Changes several accessor values simultaneously.

This method iterates through the array values and calls applyValue() for each of them.
It can be used in the following way:

IlvValue args[2] = {
    IlvValue("label", "hello"),
    IlvValue("x", 100)
};
object->changeValues(args, 2);

Parameters

values	The array of new values.
count	The number of item in the array.

Returns

IlTrue if all calls to applyValue() return IlTrue. Otherwise, it returns IlFalse.

See also

IlvValue.

getAccessors()

virtual void IlvValueInterface::getAccessors ( const IlSymbol *const **  names, const IlvValueTypeClass *const **  types, IlUInt &  count  ) const

virtual

Retrieves the list of available accessors of an object.

Retrieves the list of accessors of an object. names is the resulting array of symbols. Each symbol is the name of an accessor. types is the array of the types of accessors, count is the number of accessors. The existing types for accessors are the following:

• IlvValueBooleanType
• IlvValueIntType
• IlvValueUIntType
• IlvValueFloatType
• IlvValueDoubleType
• IlvValueStringType
• IlvValueDirectionType
• IlvValueColorType
• IlvValueFontType
• IlvValuePatternType
• IlvValueColorPatternType
• IlvValueGradientPatternType
• IlvValueLineStyleType
• IlvValueFillStyleType
• IlvValueFillRuleType
• IlvValueArcModeType
• IlvValueBitmapType
• IlvValueStringArrayType
• IlvValueUIntArrayType
• IlvValueMenuItemArrayType
• IlvValueMatrixItemArrayType
• IlvValueNotebookPageArrayType

The possible accessors for an object are described in the corresponding class.

Parameters

names	The array of symbols returned by the method. Each symbol is the name of an accessor.
types	The array of types returned by the method. Each value is the type of an accessor.
count	The number of items in the arrays names and types.

Reimplemented in IlvGraphic, IlvGraphicCOMAdapter, and IlvGraphicHandle.

getName()

virtual const char* IlvValueInterface::getName ( ) const

virtual

Returns the name of the instance. The semantic and implementation of this method are defined by concrete subclasses. The default implementation returns 0.

Returns

The name of the instance.

Reimplemented in IlvBitmap, IlvGraphic, IlvView, IlvBitmapFilter, IlvBitmapStreamer, and IlvNamedProperty.

queryValue()

virtual IlvValue& IlvValueInterface::queryValue ( IlvValue &  val ) const

virtual

Retrieves an accessor value.

The queryValue() method can be used in the following way:

IlvValue arg("label");
char* label = (char*)labelObject->queryValue(arg);

This method must be overriden by subclasses wishing to add a new readable accessor.

Parameters

val	The IlvValue used both to identify the accessor and to store the return value.

Returns

A reference to val, which contains the resulting value.

See also

IlvValue.

Reimplemented in IlvScriptFunction, IlvGraphicInstance, and IlvGraphicCOMAdapter.

queryValues()

virtual void IlvValueInterface::queryValues ( IlvValue *  values, IlUShort  count  ) const

virtual

Retrieves multiple accessor values simultaneously.

All the accessor values are returned in the array.
The method iterates through the array values and calls queryValue() for each of them.
The queryValues() method can be used in the following way:

IlvValue args[2] = { "label",  "x" };
object->queryValues(args, 2);
IlvPrint((char*)arg[0]);

Parameters

values	An array of IlvValue used both to identify the accessors and to store their return values.
count	The number of items in the array.

See also

IlvValue.