Deukhoofd
/
Angelscript
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Angelscript/docs/manual/doc_reg_objprop.html

173 lines
14 KiB
HTML
Raw Permalink Normal View History

initial commit
2021-04-12 18:25:02 +00:00
<!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: Registering object properties</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&amp;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&amp;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&amp;dn=gpl-2.0.txt GPL-v2 */
$(document).ready(function(){initNavTree('doc_reg_objprop.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">Registering object properties </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Class member variables can be registered so that they can be directly accessed by the script without the need for any method calls.</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span>MyStruct</div>
<div class="line">{</div>
<div class="line"> <span class="keywordtype">int</span> a;</div>
<div class="line">};</div>
<div class="line"> </div>
<div class="line">r = engine-&gt;<a class="code" href="classas_i_script_engine.html#a0aa35bf824180fe6aed685b40f0e8c34">RegisterObjectProperty</a>(<span class="stringliteral">&quot;mytype&quot;</span>, <span class="stringliteral">&quot;int a&quot;</span>, <a class="code" href="angelscript_8h.html#a717eccea17214bc1eb64bb9789c4915a">asOFFSET</a>(MyStruct,a)); assert( r &gt;= 0 );</div>
</div><!-- fragment --><p>If a class member is indirect, i.e. the class holds a pointer to the member that is allocated on the heap, then it is possible to registered the property using &amp; to tell the script engine that an dereference is needed to access the member.</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span>MyStruct</div>
<div class="line">{</div>
<div class="line"> OtherStruct *a;</div>
<div class="line">};</div>
<div class="line"> </div>
<div class="line">r = engine-&gt;<a class="code" href="classas_i_script_engine.html#a0aa35bf824180fe6aed685b40f0e8c34">RegisterObjectProperty</a>(<span class="stringliteral">&quot;mytype&quot;</span>, <span class="stringliteral">&quot;othertype &amp;a&quot;</span>, <a class="code" href="angelscript_8h.html#a717eccea17214bc1eb64bb9789c4915a">asOFFSET</a>(MyStruct,a)); assert( r &gt;= 0 );</div>
</div><!-- fragment --><p>Of course, the application must make sure the pointer is valid during the whole time that it may be accessed from the script.</p>
<h1><a class="anchor" id="doc_reg_objprop_composite"></a>
Composite members</h1>
<p>If the application class that is being registered uses composition, then it is possible to register the properties of the composite members like this:</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span>Component</div>
<div class="line">{</div>
<div class="line"> <span class="keywordtype">int</span> a;</div>
<div class="line">};</div>
<div class="line"> </div>
<div class="line"><span class="keyword">struct </span>Object</div>
<div class="line">{</div>
<div class="line"> Component *comp;</div>
<div class="line">};</div>
<div class="line"> </div>
<div class="line">r = engine-&gt;<a class="code" href="classas_i_script_engine.html#a0aa35bf824180fe6aed685b40f0e8c34">RegisterObjectProperty</a>(<span class="stringliteral">&quot;object&quot;</span>, <span class="stringliteral">&quot;comp_a&quot;</span>, <a class="code" href="angelscript_8h.html#a717eccea17214bc1eb64bb9789c4915a">asOFFSET</a>(Component, a), <a class="code" href="angelscript_8h.html#a717eccea17214bc1eb64bb9789c4915a">asOFFSET</a>(Object, comp), <span class="keyword">true</span>); assert( r &gt;= 0 );</div>
</div><!-- fragment --><p>The last parameter indicates that to reach the property of the composite member it is necessary to dereference the pointer. If the composite member is inlined, then the parameter should be set to false.</p>
<h1><a class="anchor" id="doc_reg_objprop_accessor"></a>
Property accessors</h1>
<p>It is also possible to expose properties through <a class="el" href="doc_script_class_prop.html">property accessors</a>, which are a pair of class methods with prefixes 'get_' and 'set_' and the function decorator 'property' for getting and setting the property value. These methods should be registered with <a class="el" href="doc_register_func.html">RegisterObjectMethod</a>. This is especially useful when the offset of the property cannot be determined, or if the type of the property is not registered in the script and some translation must occur, i.e. from <code>char*</code> to <code>string</code>.</p>
<p>If the application class contains a C++ array as a member, it may be advantageous to expose the array through <a class="el" href="doc_script_class_prop.html">indexed property accessors</a> rather than attempting to matching the C++ array type to a registered type in AngelScript. To do this you can create a couple of simple proxy functions that will translate to the array access.</p>
<dl class="section note"><dt>Note</dt><dd>The behaviour of virtual properties can be customized with the engine property <a class="el" href="doc_adv_custom_options.html#doc_adv_custom_options_lang_mod">asEP_PROPERTY_ACCESSOR_MODE</a>.</dd></dl>
<div class="fragment"><div class="line"><span class="keyword">struct </span>MyStruct</div>
<div class="line">{</div>
<div class="line"> <span class="keywordtype">int</span> array[16];</div>
<div class="line">};</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Write a couple of proxy </span></div>
<div class="line"><span class="keywordtype">int</span> MyStruct_get_array(<span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> idx, MyStruct *o)</div>
<div class="line">{</div>
<div class="line"> <span class="keywordflow">if</span>( idx &gt;= 16 ) <span class="keywordflow">return</span> 0;</div>
<div class="line"> <span class="keywordflow">return</span> o-&gt;array[idx];</div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line"><span class="keywordtype">void</span> MyStruct_set_array(<span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> idx, <span class="keywordtype">int</span> value, MyStruct *o)</div>
<div class="line">{</div>
<div class="line"> <span class="keywordflow">if</span>( idx &gt;= 16 ) <span class="keywordflow">return</span>;</div>
<div class="line"> o-&gt;array[idx] = value;</div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Register the proxy functions as member methods</span></div>
<div class="line">r = engine-&gt;<a class="code" href="classas_i_script_engine.html#ad74043be9cc30f105c62f482ca720574">RegisterObjectMethod</a>(<span class="stringliteral">&quot;mytype&quot;</span>, <span class="stringliteral">&quot;int get_array(uint) property&quot;</span>, <a class="code" href="angelscript_8h.html#a78f8f2c7f1c88b12e74a5ac47b4184ae">asFUNCTION</a>(MyStruct_get_array), <a class="code" href="angelscript_8h.html#a3ec92ea3c4762e44c2df788ceccdd1e4ac08652c72f1cc0dc81c37812fab0e253">asCALL_CDECL_OBJLAST</a>); assert( r &gt;= 0 );</div>
<div class="line">r = engine-&gt;<a class="code" href="classas_i_script_engine.html#ad74043be9cc30f105c62f482ca720574">RegisterObjectMethod</a>(<span class="stringliteral">&quot;mytype&quot;</span>, <span class="stringliteral">&quot;void set_array(uint, int) property&quot;</span>, <a class="code" href="angelscript_8h.html#a78f8f2c7f1c88b12e74a5ac47b4184ae">asFUNCTION</a>(MyStruct_set_array), <a class="code" href="angelscript_8h.html#a3ec92ea3c4762e44c2df788ceccdd1e4ac08652c72f1cc0dc81c37812fab0e253">asCALL_CDECL_OBJLAST</a>); assert( r &gt;= 0 );</div>
</div><!-- fragment --> </div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<div class="ttc" id="aclassas_i_script_engine_html_ad74043be9cc30f105c62f482ca720574"><div class="ttname"><a href="classas_i_script_engine.html#ad74043be9cc30f105c62f482ca720574">asIScriptEngine::RegisterObjectMethod</a></div><div class="ttdeci">virtual int RegisterObjectMethod(const char *obj, const char *declaration, const asSFuncPtr &amp;funcPointer, asDWORD callConv, void *auxiliary=0, int compositeOffset=0, bool isCompositeIndirect=false)=0</div><div class="ttdoc">Registers a method for the object type.</div></div>
<div class="ttc" id="aangelscript_8h_html_a3ec92ea3c4762e44c2df788ceccdd1e4ac08652c72f1cc0dc81c37812fab0e253"><div class="ttname"><a href="angelscript_8h.html#a3ec92ea3c4762e44c2df788ceccdd1e4ac08652c72f1cc0dc81c37812fab0e253">asCALL_CDECL_OBJLAST</a></div><div class="ttdeci">@ asCALL_CDECL_OBJLAST</div><div class="ttdoc">A cdecl function that takes the object pointer as the last parameter.</div><div class="ttdef"><b>Definition:</b> angelscript.h:234</div></div>
<div class="ttc" id="aangelscript_8h_html_a78f8f2c7f1c88b12e74a5ac47b4184ae"><div class="ttname"><a href="angelscript_8h.html#a78f8f2c7f1c88b12e74a5ac47b4184ae">asFUNCTION</a></div><div class="ttdeci">#define asFUNCTION(f)</div><div class="ttdoc">Returns an asSFuncPtr representing the function specified by the name.</div><div class="ttdef"><b>Definition:</b> angelscript.h:675</div></div>
<div class="ttc" id="aclassas_i_script_engine_html_a0aa35bf824180fe6aed685b40f0e8c34"><div class="ttname"><a href="classas_i_script_engine.html#a0aa35bf824180fe6aed685b40f0e8c34">asIScriptEngine::RegisterObjectProperty</a></div><div class="ttdeci">virtual int RegisterObjectProperty(const char *obj, const char *declaration, int byteOffset, int compositeOffset=0, bool isCompositeIndirect=false)=0</div><div class="ttdoc">Registers a property for the object type.</div></div>
<div class="ttc" id="aangelscript_8h_html_a717eccea17214bc1eb64bb9789c4915a"><div class="ttname"><a href="angelscript_8h.html#a717eccea17214bc1eb64bb9789c4915a">asOFFSET</a></div><div class="ttdeci">#define asOFFSET(s, m)</div><div class="ttdoc">Returns the offset of an attribute in a struct.</div><div class="ttdef"><b>Definition:</b> angelscript.h:672</div></div>
<!-- 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>