Context Class Reference

---

Detailed Description

This is a general, flexible Context object that is used for callbacks. Instances of this object are used to pass information to the C++ API callbacks that implement a PluginItem.

The main reason context objects are used in XSI is to ensure backward compatibility for XSI plugins. In future versions it will be possible to add additional information and functionality to the context object without changing the signature of the callback routines.

In some cases a specialized class will be provided rather than a basic Context object. Some of these classes derive from Context (as is the case with PPGEventContext) whereas others do not (for example PluginRegistrar).

See also:

PPGEventContext, UpdateContext, PluginRegistrar

Since:

4.0

#include <xsi_context.h>

Inheritance diagram for Context:

List of all members.

Public Member Functions
	Context ()
	~Context ()
	Context (const CRef &in_ref)
	Context (const Context &in_obj)
bool	IsA (siClassID in_ClassID) const
siClassID	GetClassID () const
Context &	operator= (const Context &in_obj)
Context &	operator= (const CRef &in_ref)
CRef	GetSource () const
CValue	GetAttribute (const CString &in_AttributeName)
CStatus	PutAttribute (const CString &in_AttributeName, const CValue &in_val)
CStatus	PutArrayAttribute (const CString &in_AttributeName, const CRefArray &in_array)
CRefArray	GetArrayAttribute (const CString &in_AttributeName) const
CValue	GetUserData ()
CStatus	PutUserData (const CValue &in_val)

---

Constructor & Destructor Documentation

Context

(

)

Default constructor.

~Context

(

)

Default destructor.

Context

(

const CRef &

in_ref

)

Constructor.

Parameters:

in_ref

constant reference object.

Context

(

const Context &

in_obj

)

Copy constructor.

Parameters:

in_obj

constant class object.

---

Member Function Documentation

bool IsA

(

siClassID

in_ClassID

)

const [virtual]

Returns true if a given class type is compatible with this API class.

Parameters:

in_ClassID

class type.

Returns:

true if the class is compatible, false otherwise.

Reimplemented from CBase.

Reimplemented in HardwareShaderContext, ICENodeContext, OperatorContext, PPGEventContext, RendererContext, and ToolContext.

siClassID GetClassID

(

)

const [virtual]

Returns the type of the API class.

Returns:

The class type.

Implements CBase.

Reimplemented in HardwareShaderContext, ICENodeContext, OperatorContext, PPGEventContext, RendererContext, and ToolContext.

Context& operator=

(

const Context &

in_obj

)

Creates an object from another object.

Parameters:

in_obj

constant class object.

Returns:

The new Context object.

Context& operator=

(

const CRef &

in_ref

)

Creates an object from a reference object. The newly created object is set to empty if the input reference object is not compatible.

Parameters:

in_ref

constant class object.

Returns:

The new Context object.

Reimplemented in HardwareShaderContext, ICENodeContext, OperatorContext, PPGEventContext, RendererContext, and ToolContext.

CRef GetSource

(

)

const

Returns the object that is the cause of the callback being fired. The type of object returned depends on the callback. For example this returns a CustomProperty object in the context of a Define callback for a CustomProperty PluginItem, and it returns a PPGLayout object in the context of a DefineLayout callback. This specific information is documented along with the callbacks of each PluginItem.

See also:

PluginRegistrar::RegisterProperty

Returns:

A reference to the plug-in item.

CValue GetAttribute

(

const CString &

in_AttributeName

)

Returns an attribute on the context. Attributes are used to provide additional context information above and beyond the object returned by Context::GetSource. Supported attributes, if any, are documented along with the callbacks of each PluginItem.

Parameters:

in_AttributeName

The name of the attribute to get.

Returns:

The attribute value.

See also:

PPG.Inspected (object model equivalent of PPGEventContext::GetSource)

CStatus PutAttribute	(	const CString &	in_AttributeName,
		const CValue &	in_val
	)

Sets a single attribute value on the context. This is a way to pass additional information or instructions to XSI regarding the outcome of the callback. Supported attributes, if any, are documented along with the callbacks of each PluginItem. If the attribute does not exist it is added, otherwise the existing value is replaced by the new value.

Parameters:

in_AttributeName	The name of the attribute to set.
in_val	The attribute value to set.

Returns:

CStatus::OK

CStatus::Fail

CStatus PutArrayAttribute	(	const CString &	in_AttributeName,
		const CRefArray &	in_array
	)

Sets an attribute value as an array of values on the context. If the attribute does not exist it is added, otherwise the existing value is replaced by the new value.

Parameters:

in_AttributeName	The name of the attribute to set.
in_array	The attribute values to set.

Returns:

CStatus::OK

CStatus::Fail

CRefArray GetArrayAttribute

(

const CString &

in_AttributeName

)

const

Returns an attribute value as an array of values on the context.

Parameters:

in_AttributeName

The name of the attribute to get.

Returns:

The attribute values to get.

CValue GetUserData

(

)

Returns the user data stored in the context.

Returns:

The raw user data.

CStatus PutUserData

(

const CValue &

in_val

)

Allows you to store a CValue inside the context object. This is called User Data because XSI does not care about the content or meaning of the data. This information is not persisted. A common use for this feature is to store a pointer to a newly allocated C++ object during an Init callback, and then to use Context::GetUserData to retrieve the pointer when other callbacks are called.

Warning:

In the case where a pointer is stored during the Init callback, the object should be destroyed during the Term callback.

Parameters:

in_val

User data to be set.

Returns:

CStatus::OK success

CStatus::Fail failure.

---

The documentation for this class was generated from the following file:

• xsi_context.h