Angelscript/docs/manual/doc_script_class_prop.html

200 lines
10 KiB
HTML
Raw Normal View History

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: Property accessors</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_script_class_prop.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">Property accessors </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><dl class="section note"><dt>Note</dt><dd>The application can optionally <a class="el" href="doc_adv_custom_options.html#doc_adv_custom_options_lang_mod">turn off support for property accessors</a>, so you need to verify your application's manual to determine if this is supported for your application or not.</dd></dl>
<p>Many times when working with properties it is necessary to make sure specific logic is followed when accessing them. An example would be to always send a notification when a property is modified, or computing the value of the property from other properties. By implementing property accessor methods for the properties this can be implemented by the class itself, making it easier for the one who accesses the properties.</p>
<p>In AngelScript property accessors are declared with the following syntax:</p>
<pre>
class MyObj
{
// A virtual property with accessors
int prop
{
get const
{
// The actual value of the property could be stored
// somewhere else, or even computed at access time.
return realProp;
}
set
{
// The new value is stored in a hidden parameter appropriately called 'value'.
realProp = value;
}
}</pre><pre> // The actual value can be stored in a member or elsewhere.
// It is actually possible to use the same name for the real property, if so is desired.
private int realProp;
}
</pre><p>Behind the scene the compiler transforms this into two methods with the name of the property and the prefixes <code>get_</code> and <code>set_</code>, and with the function decorator 'property'. The following generates the equivalent code, and is perfectly valid too:</p>
<pre>
class MyObj
{
int get_prop() const property { return realProp; }
void set_prop(int value) property { realProp = value; }
private int realProp;
}
</pre><p>If you implement the property accessors by explicitly writing the two methods you must make sure the return type of the get accessor and the parameter type of the set accessor match, otherwise the compiler will not know which is the correct type to use.</p>
<p>For interfaces the first alternative is usually the preferred way of declaring the property accessors, as it gets quite short and easy to read.</p>
<pre>
interface IProp
{
int prop { get const; set; }
}
</pre><p>You can also leave out either the get or set accessor. If you leave out the set accessor, then the property will be read-only. If you leave out the get accessor, then the property will be write-only.</p>
<p>Property accessors can also be implemented for global properties, which follows the same rules, except the functions are global.</p>
<p>When the property accessors have been declared it is possible to access them like ordinary properties, and the compiler will automatically expand the expressions to the appropriate function calls, either <code>set_</code> or <code>get_</code> depending on how the property is used in the expression.</p>
<pre>
void Func()
{
MyObj obj;</pre><pre> // Set the property value just like a normal property.
// The compiler will convert this to a call to set_prop(10000).
obj.prop = 10000;</pre><pre> // Get the property value just a like a normal property.
// The compiler will convert this to a call to get_prop().
assert( obj.prop == 1000 );
}
</pre><p>Observe that as property accessors are actually a pair of methods rather than direct access to the value, some restrictions apply as to how they can be used in expressions that inspect and mutate in the same operation. Compound assignments can be used on property accessors if the owning object is a reference type, but not if the owning object is a value type. This is because the compiler must be able to guarantee that the object stays alive between the two calls to the get accessor and set accessor.</p>
<p>The increment and decrement operators are currently not supported.</p>
<p>In such cases the expression must be expanded so that the read and write operation are performed separately, e.g. the increment operator must be rewritten as follows:</p>
<pre>
a++; // will not work if a is a virtual property
a += 1; // this is OK, as long as the owner of the virtual
// property is a reference type or the property is global
</pre><h1><a class="anchor" id="doc_script_class_prop_index"></a>
Indexed property accessors</h1>
<p>Property accessors can be used to emulate a single property or an array of properties accessed through the index operator. Property accessors for indexed access work the same way as ordinary property accessors, except that they take an index argument. The get accessor should take the index argument as the only argument, and the set accessor should take the index argument as the first argument, and the new value as the second argument.</p>
<pre>
string firstString;
string secondString;</pre><pre> // A global indexed get accessor
string get_stringArray(int idx) property
{
switch( idx )
{
case 0: return firstString;
case 1: return secondString;
}
return "";
}</pre><pre> // A global indexed set accessor
void set_stringArray(int idx, const string &amp;in value) property
{
switch( idx )
{
case 0: firstString = value; break;
case 1: secondString = value; break;
}
}</pre><pre> void main()
{
// Setting the value of the indexed properties
stringArray[0] = "Hello";
stringArray[1] = "World";</pre><pre> // Reading the value of the indexed properties
print(StringArray[0] + " " + stringArray[1] + "\n");
}
</pre><p>Compound assignments currently doesn't work for indexed properties. </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>