/xbmc/visualizations/Vortex/angelscript/docs/doxygen/source/doc_adv_single_ref_type.h

 1/**
 2
 3\page doc_adv_single_ref_type Registering a single-reference type
 4
 5A variant of the uninstanciable reference types is the single-reference
 6type. This is a type that have only 1 reference accessing it, i.e. the script
 7cannot store any extra references to the object during execution. The script
 8is forced to use the reference it receives from the application at the moment
 9the application passes it on to the script.
10
11The reference can be passed to the script through a property, either global
12or a class member, or it can be returned from an application registered
13function or class method.
14
15The script engine will not permit declaration of functions that take this
16type as a parameter, neither as a reference nor as a handle. If that was allowed
17it would mean that a reference to the instance is placed on the stack, which 
18in turn means that it is no longer a single-reference type.
19
20\code
21// Registering the type so that it cannot be instanciated
22// by the script, nor allow scripts to store references to the type
23r = engine->RegisterObjectType("single", 0, asOBJ_REF | asOBJ_NOHANDLE); assert( r >= 0 );
24\endcode
25
26This sort of type is most useful when you want to have complete control over
27references to an object, for example so that the application can destroy and
28recreate objects of the type without having to worry about potential references
29held by scripts. This allows the application to control when a script has access
30to an object and it's members.
31
32
33\see \ref doc_reg_basicref
34
35
36
37*/