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

http://github.com/xbmc/xbmc · C++ Header · 37 lines · 0 code · 0 blank · 37 comment · 0 complexity · b100c1edc82d209c8cc837552b73de46 MD5 · raw file

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