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, asITypeInfo *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
  asITypeInfo   *GetType() const;
  int            GetTypeId() const;
  
  // Returns the reference
  void *GetRef();
};

Public script interface

See also

ref in the script language

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.