IlvDvInterface Class Reference

Application Framework interface class. More...

#include <ilviews/appframe/interf.h>

Inheritance diagram for IlvDvInterface:

Public Member Functions
IlBoolean	callMethod (const IlSymbol *methodName, IlvDvValue *returnedValue,...)
	Generic method for calling a method that is exported in a class interface. More...
IlvDvValue &	getFieldValue (const IlSymbol *fieldName, IlvDvValue &value) const
	Gets a field value. More...
virtual IlBoolean	isProcessingAction (const IlSymbol *methodName) const
	Returns IlTrue if the given action can be processed by the class. More...
virtual IlBoolean	processAction (const IlSymbol *actionName)
	Processes an action. More...
virtual IlBoolean	refreshAction (const IlSymbol *actionName, IlvDvActionDescriptor *desc) const
	Refresh all the menu items that reference the action given by the parameter actionName. More...
void	setFieldValue (const IlSymbol *fieldName, const IlvDvValue &value)
	Sets a field value. More...

Detailed Description

Application Framework interface class.

Library: ilvappframe

Application Framework provides an introspection mechanism that allows a C++ class to:

• have its fields and methods introspected,
• get and change the value of the field of an instance by calling generic methods getFieldValue(fieldName) and setFieldValue(fieldName, value),
• and invoke a method with any parameters by calling generic method callMethod(methodName, values).
  

This mechanism provides the following advantages:

• Fields and methods of the introspectable class are automatically accessible and usable from script.
• A COM interface can automatically be generated for that class.
• A document can notify its document views of an event without being dependent on their type.

To be introspected, a class must both inherit from the IlvDvInterface class and add some macros in its declaration and its implementation file.
Here is a sample of how to use Application Framework introspection:

// Delaration of A 
class A
: public IlvDvInterface {
public:
    void setX(int x) { _x = x; }
    int getX() const { return _x; }
protected:
    int _x;
};

// Implementation file of A; use these macros to 
// introspect methods setX, getX, and field _x.
 
IlvDvBeginInterface(A)
    Method1(SetX, setX)
    TypedMethod (GetX, getX)
    Field(X, _x)
IlvDvEndInterface()

...
// ***********************************************************
// How to use introspection
// Using an instance of A as an interface, it is possible
// to invoke its methods and to modify its field
// without being aware of class A !!!
A* a = new A;
IlvDvInterface* interf = a;

// First we invoke its methods
IlvDvValue returnedValue;
interf->callMethod(IlGetSymbol("SetX"), &returnedValue, 100); 
interf->callMethod(IlGetSymbol("GetX"), &returnedValue);
assert((IlInt) returnedValue == 100);

// Then we modify its field directly
interf->setFieldValue(IlGetSymbol("X"), 200);
assert((IlInt)interf->
getFieldValue(IlGetSymbol("X"), &returnedValue) == 200);

Naming Convention for Macros Used for Scripting and Introspection
The root of the macro name must be Method. If the declared method returns a value, the macro must begin with prefix Typed.
If the declared method contains arguments, the macro must end with the suffix number equal to the number of parameters of the method.

Here are some macro samples:

• Method IlFloat getPosition() const will be declared TypedMethod(GetPosition, getPosition, IlFloat) in the interface table.
• Method const char* set(int) will be declared TypedMethod1(Set, set, int, ExportedFirstParameterName, const char*) in the interface table.
• Method void setPosition(int x, int y) will be declared Method2(SetPosition, setPosition, int, X, int, Y) in the interface table.

Member Function Documentation

callMethod()

IlBoolean IlvDvInterface::callMethod	(	const IlSymbol *	methodName,
		IlvDvValue *	returnedValue,
			...
	)

Generic method for calling a method that is exported in a class interface.

Calls a method that is exported in the interface table of the class by using the macro xxxMethodxxx(externalName, method,...). The externalName corresponds to the methodName parameter.

Parameters

methodName	The name of the method to call.
returnedValue	The returned value of the called method is stored in this parameter. If the type of the called method is void, this field is not filled.

Returns

IlTrue if the C++ method is called.

getFieldValue()

IlvDvValue& IlvDvInterface::getFieldValue	(	const IlSymbol *	fieldName,
		IlvDvValue &	value
	)		const

Gets a field value.

Gets the value of the field declared in the interface table with an external name that is equal to the fieldName parameter. The value is set in the value parameter.

Returns

The parameter value.

isProcessingAction()

virtual IlBoolean IlvDvInterface::isProcessingAction ( const IlSymbol *  methodName ) const

virtual

Returns IlTrue if the given action can be processed by the class.

Returns

IlTrue if the given action can be processed by the class.

Reimplemented in IlvDvDocTemplate.

processAction()

virtual IlBoolean IlvDvInterface::processAction ( const IlSymbol *  actionName )

virtual

Processes an action.

Tries to process the action given by the parameter actionName. If a macro Action(actionName, actionMethod) is inserted in the interface table of the class with a specified external name equal to the actionName parameter, the processAction method will automatically call the actionMethod method.

Returns

IlTrue if the action is processed.

Reimplemented in IlvDvApplication, IlvDvDocTemplate, and IlvDvDockableMainWindow.

refreshAction()

virtual IlBoolean IlvDvInterface::refreshAction ( const IlSymbol *  actionName, IlvDvActionDescriptor *  desc  ) const

virtual

Refresh all the menu items that reference the action given by the parameter actionName.

If a macro RefreshAction(actionName, refreshMethod) is inserted in the interface table of the class with a specified external name equal to the actionName parameter, the refreshAction method will automatically call the refreshMethod method, with desc as the parameter.
All modifications brought to the desc parameter are directly dispatched to all the menu items that reference the action.

Returns

IlTrue if the given action is refreshed.

Reimplemented in IlvDvApplication.

setFieldValue()

void IlvDvInterface::setFieldValue	(	const IlSymbol *	fieldName,
		const IlvDvValue &	value
	)

Sets a field value.

Sets the value value to the field that is declared in the interface table with an external name equal to the fieldName parameter.