Public Member Functions
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:
[legend]

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