AngelScript
ref object

Path: /sdk/add_on/scripthandle/

The ref type is a generic container that can hold any handle. It is a value type, but behaves very much like an object handle.

The type is registered with RegisterScriptHandle(asIScriptEngine*).

See Also
Registering a generic handle type

Public C++ interface

class CScriptHandle
{
public:
// Constructors
CScriptHandle();
CScriptHandle(const CScriptHandle &other);
CScriptHandle(void *ref, int typeId);
~CScriptHandle();
// Copy the stored reference from another handle object
CScriptHandle &operator=(const CScriptHandle &other);
// Set the reference
void Set(void *ref, asIObjectType *type);
// Compare equalness
bool operator==(const CScriptHandle &o) const;
bool operator!=(const CScriptHandle &o) const;
bool opEquals(void *ref, int typeId) const;
// Dynamic cast to desired handle type
void Cast(void **outRef, int typeId);
// Returns the type of the reference held
asIObjectType *GetType() const;
int GetTypeId() const;
};

Example usage in script

In the scripts it can be used as follows:

  ref@ unknown;
  // Store a handle in the ref variable
  object obj;
  @unknown = @obj;
  // Compare equalness
  if( unknown != null )
  {
    // Dynamically cast the handle to wanted type
    object @obj2 = cast<object>(unknown);
    if( obj2 != null )
    {
      ...
    }
  }

Example usage from C++

Even though the CScriptHandle is a value type, when registering properties of its type they should be registered as handles. The same goes for function arguments and return types.

CScriptHandle g_handle;
void Function(CScriptHandle handle)
{
... use the methods of CScriptHandle to determine the true object held in it
}
void Register(asIScriptEngine *engine)
{
int r;
r = engine->RegisterGlobalProperty("ref @g_handle", &g_handle); assert( r >= 0 );
r = engine->RegisterGlobalFunction("void Function(ref @)", asFUNCTION(Function), asCALL_CDECL); assert( r >= 0 );
}

To set an object pointer in the handle from the application, you'll use the Set() method passing a pointer to the object and the type of the object.

To retrieve an object pointer from the application you'll use the Cast() method passing in a pointer to the pointer and the wanted type id. If the type id given doesn't match the stored handle the returned pointer will be null.

To retrieve an object of an unknown type use the GetType() or GetTypeId() to determine the type stored in the handle, then use the Cast() method.