PageRenderTime 24ms CodeModel.GetById 14ms app.highlight 5ms RepoModel.GetById 2ms app.codeStats 0ms

/xbmc/visualizations/Vortex/angelscript/docs/manual/doc_script_handle.html

http://github.com/xbmc/xbmc
HTML | 90 lines | 89 code | 0 blank | 1 comment | 0 complexity | 28694a8ce484fccf0bade27ff9cfdc8e MD5 | raw file
 1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 2<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
 3<title>AngelScript: Object handles</title>
 4<link href="tabs.css" rel="stylesheet" type="text/css">
 5<link href="doxygen.css" rel="stylesheet" type="text/css">
 6</head><body>
 7<!-- Generated by Doxygen 1.5.9 -->
 8<div class="contents">
 9<h1><a class="anchor" name="doc_script_handle">Object handles </a></h1>An object handle is a type that can hold a reference to an object. With object handles it is possible to declare more than one variables that refer to the same physical object.<p>
10Not all types allow object handles to be used. None of the primitive data types, bool, int, float, etc, can have object handles. Object types registered by the application may or may not allow object handles, depending on how they have been registered.<h2><a class="anchor" name="doc_script_handle_1">
11General usage</a></h2>
12An object handle is declared by appending the @ symbol to the data type.<p>
13<pre>
14  object@ obj_h;
15</pre><p>
16This code declares the object handle obj and initializes it to null, i.e. it doesn't hold a reference to any object.<p>
17In expressions variables declared as object handles are used the exact same way as normal objects. But you should be aware that object handles are not guaranteed to actually reference an object, and if you try to access the contents of an object in a handle that is null an exception will be raised.<p>
18<pre>
19  object obj;
20  object@ obj_h;
21  obj.Method();
22  obj_h.Method();
23</pre><p>
24Operators like = or any other operator registered for the object type work on the actual object that the handle references. These will also throw an exception if the handle is empty.<p>
25<pre>
26  object obj;
27  object@ obj_h;
28  obj_h = obj;
29</pre><p>
30When you need to make an operation on the actual handle, you should prepend the expression with the @ symbol. Setting the object handle to point to an object is for example done like this:<p>
31<pre>
32  object obj;
33  object@ obj_h;
34  @obj_h = @obj;
35</pre><p>
36An object handle can be compared against another object handle (of the same type) to verify if they are pointing to the same object or not. It can also be compared against null, which is a special keyword that represents an empty handle. This is done using the identity operator, <code>is</code>.<p>
37<pre>
38  object@ obj_a, obj_b;
39  if( obj_a is obj_b ) {}
40  if( obj_a !is null ) {}
41</pre><h2><a class="anchor" name="doc_script_handle_2">
42Object life times</a></h2>
43An object's life time is normally for the duration of the scope the variable was declared in. But if a handle outside the scope is set to reference the object, the object will live on until all object handles are released.<p>
44<pre>
45  object@ obj_h;
46  {
47    object obj;
48    @obj_h = @obj;</pre><p>
49<pre>    // The object would normally die when the block ends,
50    // but the handle is still holding a reference to it
51  }</pre><p>
52<pre>  // The object still lives on in obj_h ...
53  obj_h.Method();</pre><p>
54<pre>  // ... until the reference is explicitly released
55  // or the object handle goes out of scope
56  @obj_h = null;
57</pre><h2><a class="anchor" name="doc_script_handle_3">
58Object relations and polymorphing</a></h2>
59Object handles can be used to write common code for related types, by means of inheritance or interfaces. This allows a handle to an interface to store references to all object types that implement that interface, similarly a handle to a base class can store references to all object types that derive from that class.<p>
60<pre>
61  interface I {}
62  class A : I {}
63  class B : I {}</pre><p>
64<pre>  // Store reference in handle to interface 
65  I @i1 = A();  
66  I @i2 = B();</pre><p>
67<pre>  void function(I @i)
68  { 
69    // Functions implemented by the interface can be  
70    // called directly on the interface handle. But if
71    // special treatment is need for a specific type, a 
72    // cast can be used to get a handle to the true type.
73    A @a = cast&lt;A&gt;(i);
74    if( a !is null )
75    {
76      // Access A's members directly
77      ...
78    }
79    else
80    { 
81      // The object referenced by i is not of type A
82      ...
83    }
84  }
85</pre> </div>
86<hr size="1"><address style="text-align: right;"><small>Generated on Wed Dec 16 19:34:51 2009 for AngelScript by&nbsp;
87<a href="http://www.doxygen.org/index.html">
88<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.9 </small></address>
89</body>
90</html>