195 lines
9.9 KiB
HTML
195 lines
9.9 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
||
|
|
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
||
|
|
<meta name="generator" content="Doxygen 1.8.18"/>
|
||
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
||
|
|
<title>AngelScript: Object handles</title>
|
||
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
||
|
|
<script type="text/javascript" src="jquery.js"></script>
|
||
|
|
<script type="text/javascript" src="dynsections.js"></script>
|
||
|
|
<link href="navtree.css" rel="stylesheet" type="text/css"/>
|
||
|
|
<script type="text/javascript" src="resize.js"></script>
|
||
|
|
<script type="text/javascript" src="navtreedata.js"></script>
|
||
|
|
<script type="text/javascript" src="navtree.js"></script>
|
||
|
|
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
||
|
|
<script type="text/javascript" src="search/searchdata.js"></script>
|
||
|
|
<script type="text/javascript" src="search/search.js"></script>
|
||
|
|
<script type="text/javascript">
|
||
|
|
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
|
||
|
|
$(document).ready(function() { init_search(); });
|
||
|
|
/* @license-end */
|
||
|
|
</script>
|
||
|
|
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
||
|
|
<div id="titlearea">
|
||
|
|
<table cellspacing="0" cellpadding="0">
|
||
|
|
<tbody>
|
||
|
|
<tr style="height: 56px;">
|
||
|
|
<td id="projectlogo"><img alt="Logo" src="aslogo_small.png"/></td>
|
||
|
|
<td id="projectalign" style="padding-left: 0.5em;">
|
||
|
|
<div id="projectname">AngelScript
|
||
|
|
</div>
|
||
|
|
</td>
|
||
|
|
<td> <div id="MSearchBox" class="MSearchBoxInactive">
|
||
|
|
<span class="left">
|
||
|
|
<img id="MSearchSelect" src="search/mag_sel.png"
|
||
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
||
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
||
|
|
alt=""/>
|
||
|
|
<input type="text" id="MSearchField" value="Search" accesskey="S"
|
||
|
|
onfocus="searchBox.OnSearchFieldFocus(true)"
|
||
|
|
onblur="searchBox.OnSearchFieldFocus(false)"
|
||
|
|
onkeyup="searchBox.OnSearchFieldChange(event)"/>
|
||
|
|
</span><span class="right">
|
||
|
|
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
|
||
|
|
</span>
|
||
|
|
</div>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
<!-- end header part -->
|
||
|
|
<!-- Generated by Doxygen 1.8.18 -->
|
||
|
|
<script type="text/javascript">
|
||
|
|
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
|
||
|
|
var searchBox = new SearchBox("searchBox", "search",false,'Search');
|
||
|
|
/* @license-end */
|
||
|
|
</script>
|
||
|
|
</div><!-- top -->
|
||
|
|
<div id="side-nav" class="ui-resizable side-nav-resizable">
|
||
|
|
<div id="nav-tree">
|
||
|
|
<div id="nav-tree-contents">
|
||
|
|
<div id="nav-sync" class="sync"></div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div id="splitbar" style="-moz-user-select:none;"
|
||
|
|
class="ui-resizable-handle">
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<script type="text/javascript">
|
||
|
|
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
|
||
|
|
$(document).ready(function(){initNavTree('doc_script_handle.html',''); initResizable(); });
|
||
|
|
/* @license-end */
|
||
|
|
</script>
|
||
|
|
<div id="doc-content">
|
||
|
|
<!-- window showing the filter options -->
|
||
|
|
<div id="MSearchSelectWindow"
|
||
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
||
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
||
|
|
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<!-- iframe showing the search results (closed by default) -->
|
||
|
|
<div id="MSearchResultsWindow">
|
||
|
|
<iframe src="javascript:void(0)" frameborder="0"
|
||
|
|
name="MSearchResults" id="MSearchResults">
|
||
|
|
</iframe>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<div class="PageDoc"><div class="header">
|
||
|
|
<div class="headertitle">
|
||
|
|
<div class="title">Object handles </div> </div>
|
||
|
|
</div><!--header-->
|
||
|
|
<div class="contents">
|
||
|
|
<div class="textblock"><p>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>
|
||
|
|
<p>Not 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.</p>
|
||
|
|
<dl class="section see"><dt>See also</dt><dd><a class="el" href="doc_obj_handle.html">Object handles to the application</a></dd></dl>
|
||
|
|
<h1><a class="anchor" id="doc_script_handle_1"></a>
|
||
|
|
General usage</h1>
|
||
|
|
<p>An object handle is declared by appending the @ symbol to the data type.</p>
|
||
|
|
<pre>
|
||
|
|
object@ obj_h;
|
||
|
|
</pre><p>This code declares the object handle obj and initializes it to null, i.e. it doesn't hold a reference to any object.</p>
|
||
|
|
<p>In 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>
|
||
|
|
<pre>
|
||
|
|
object obj;
|
||
|
|
object@ obj_h;
|
||
|
|
obj.Method();
|
||
|
|
obj_h.Method();
|
||
|
|
</pre><p>Operators 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>
|
||
|
|
<pre>
|
||
|
|
object obj;
|
||
|
|
object@ obj_h;
|
||
|
|
obj_h = obj;
|
||
|
|
</pre><p>When 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>
|
||
|
|
<pre>
|
||
|
|
object obj;
|
||
|
|
object@ obj_h;
|
||
|
|
@obj_h = @obj;
|
||
|
|
</pre><p>Note that the compiler can often implicitly determine that it is the handle of the object that is needed rather than the actual object itself. In these cases it is not necessary to explicitly prepend the expression with @.</p>
|
||
|
|
<p>An 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>
|
||
|
|
<pre>
|
||
|
|
object@ obj_a, obj_b;
|
||
|
|
if( obj_a is obj_b ) {}
|
||
|
|
if( obj_a !is null ) {}
|
||
|
|
</pre><p>Observe, the == and != operators will do a value comparison on the objects referred to by the handles using the <a class="el" href="doc_script_class_ops.html#doc_script_class_cmp_ops">opEquals</a> or <a class="el" href="doc_script_class_ops.html#doc_script_class_cmp_ops">opCmp</a> operator overloads. Though, if the expressions are prepended with @ the operators will have the same function as <code>is</code> and <code>!is</code>.</p>
|
||
|
|
<h1><a class="anchor" id="doc_script_handle_2"></a>
|
||
|
|
Object life times</h1>
|
||
|
|
<p>An 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>
|
||
|
|
<pre>
|
||
|
|
object@ obj_h;
|
||
|
|
{
|
||
|
|
object obj;
|
||
|
|
@obj_h = @obj;</pre><pre> // The object would normally die when the block ends,
|
||
|
|
// but the handle is still holding a reference to it
|
||
|
|
}</pre><pre> // The object still lives on in obj_h ...
|
||
|
|
obj_h.Method();</pre><pre> // ... until the reference is explicitly released
|
||
|
|
// or the object handle goes out of scope
|
||
|
|
@obj_h = null;
|
||
|
|
</pre><h1><a class="anchor" id="doc_script_handle_3"></a>
|
||
|
|
Object relations and polymorphing</h1>
|
||
|
|
<p>Object 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>
|
||
|
|
<pre>
|
||
|
|
interface I {}
|
||
|
|
class A : I {}
|
||
|
|
class B : I {}</pre><pre> // Store reference in handle to interface
|
||
|
|
I @i1 = A();
|
||
|
|
I @i2 = B();</pre><pre> void function(I @i)
|
||
|
|
{
|
||
|
|
// Functions implemented by the interface can be
|
||
|
|
// called directly on the interface handle. But if
|
||
|
|
// special treatment is need for a specific type, a
|
||
|
|
// cast can be used to get a handle to the true type.
|
||
|
|
A @a = cast<A>(i);
|
||
|
|
if( a !is null )
|
||
|
|
{
|
||
|
|
// Access A's members directly
|
||
|
|
...
|
||
|
|
}
|
||
|
|
else
|
||
|
|
{
|
||
|
|
// The object referenced by i is not of type A
|
||
|
|
...
|
||
|
|
}
|
||
|
|
}
|
||
|
|
</pre><h1><a class="anchor" id="doc_script_handle_4"></a>
|
||
|
|
Const handles</h1>
|
||
|
|
<p>Sometimes it is necessary to hold handles to objects that shouldn't be allowed to be modified. This is done by prefixing the type with 'const', e.g.</p>
|
||
|
|
<pre>
|
||
|
|
obj @a; // handle to modifiable object
|
||
|
|
const obj @b; // handle to non-modifiable object
|
||
|
|
</pre><p>A handle to a non-modifiable object can refer to both modifiable objects and non-modifiable objects, but the script will not allow the object to be modified through that handle, nor allow the handle to be passed to another handle that would allow modifications.</p>
|
||
|
|
<p>This syntax is not to be confused with handles that are themselves read-only, i.e. the handle cannot be re-assigned to refer to a different object. Read-only handles like this are declared by adding the 'const' keyword as a suffix after the '@' symbol.</p>
|
||
|
|
<pre>
|
||
|
|
obj @ const c = obj(); // read-only handle to a modifiable object
|
||
|
|
const obj @ const d = obj(); // read-only handle to a non-modifiable object
|
||
|
|
</pre><p>A read-only handle can only be initialized when declared. </p>
|
||
|
|
</div></div><!-- contents -->
|
||
|
|
</div><!-- PageDoc -->
|
||
|
|
</div><!-- doc-content -->
|
||
|
|
<!-- start footer part -->
|
||
|
|
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
|
||
|
|
<ul>
|
||
|
|
<li class="footer">Generated on Sat Dec 5 2020 23:20:24 for AngelScript by
|
||
|
|
<a href="http://www.doxygen.org/index.html">
|
||
|
|
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.18 </li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|