<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://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/html; charset=utf-8" />
<title>API Extractor — 3.2. Manipulating Object and Value Types</title>
<link rel="stylesheet" href="_static/pysidedocs.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '#',
VERSION: '0.10.0',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<!--[if lt IE 7]>
<style media="screen" type="text/css">
#container {
height:100%;
}
</style>
<![endif]-->
<link rel="top" title="API Extractor v0.10.0 documentation" href="index.html" />
<link rel="up" title="3. The API Extractor Type System" href="typesystem.html" />
<link rel="next" title="3.3. Modifying Functions" href="typesystem_modify_function.html" />
<link rel="prev" title="3.1. Specifying Types" href="typesystem_specifying_types.html" />
</head>
<body id="typesystem_manipulating_objects">
<div id="container">
<div id="header">
<div id="header_container">
<div id="logo"><a href="http://www.pyside.org"><img alt="PySide" src="_static/pysidelogo.png" width="199" height="102" /></a></div>
<ul id="relbar">
<li class="right">
<a href="typesystem_modify_function.html" title="3.3. Modifying Functions"
accesskey="N">next</a></li>
<li class="right">
<a href="typesystem_specifying_types.html" title="3.1. Specifying Types"
accesskey="P">previous</a> |</li>
<li><a href="contents.html">API Extractor v0.10.0 documentation</a> »</li>
<li><a href="typesystem.html" accesskey="U">3. The API Extractor Type System</a> »</li>
</ul>
</div>
</div>
<div id="body" >
<div id="sidebar">
<h3><a href="contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">3.2. Manipulating Object and Value Types</a><ul>
<li><a class="reference internal" href="#inject-code">3.2.1. inject-code</a></li>
<li><a class="reference internal" href="#modify-field">3.2.2. modify-field</a></li>
<li><a class="reference internal" href="#modify-function">3.2.3. modify-function</a></li>
<li><a class="reference internal" href="#add-function">3.2.4. add-function</a></li>
<li><a class="reference internal" href="#conversion-rule">3.2.5. conversion-rule</a></li>
</ul>
</li>
</ul>
<h3>Previous topic</h3>
<p class="topless"><a href="typesystem_specifying_types.html"
title="previous chapter">3.1. Specifying Types</a></p>
<h3>Next topic</h3>
<p class="topless"><a href="typesystem_modify_function.html"
title="next chapter">3.3. Modifying Functions</a></p>
<div id="search_box">
<h3>Quick search</h3>
<form action="search.html" method="get">
<input type="text" name="q" id="q" />
<input type="submit" value="Go" id="search_button" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="section" id="manipulating-object-and-value-types">
<span id="id1"></span><h1>3.2. Manipulating Object and Value Types</h1>
<div class="section" id="inject-code">
<span id="id2"></span><h2>3.2.1. inject-code</h2>
<blockquote>
<div><p>The inject-code node inserts the given code into the generated code for the
given type or function, and it is a child of the <a class="reference internal" href="typesystem_specifying_types.html#object-type"><em>object-type</em></a>, <a class="reference internal" href="typesystem_specifying_types.html#value-type"><em>value-type</em></a>,
<a class="reference internal" href="#modify-function"><em>modify-function</em></a> and <a class="reference internal" href="#add-function"><em>add-function</em></a> nodes.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><value-type></span>
<span class="nt"><inject-code</span> <span class="na">class=</span><span class="s">"native | target | target-declaration"</span>
<span class="na">position=</span><span class="s">"beginning | end"</span> <span class="na">since=</span><span class="s">"..."</span><span class="nt">></span>
// the code
<span class="nt"></inject-code></span>
<span class="nt"></value-type></span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">class</span></tt> attribute specifies which module of the generated code that
will be affected by the code injection. The <tt class="docutils literal"><span class="pre">class</span></tt> attribute accepts the
following values:</p>
<blockquote>
<div><ul class="simple">
<li>native: The c++ code</li>
<li>target: The binding code</li>
<li>target-declaration: The code will be injected into the generated header
file containing the c++ wrapper class definition.</li>
</ul>
</div></blockquote>
<p>If the <tt class="docutils literal"><span class="pre">position</span></tt> attribute is set to <em>beginning</em> (the default), the code
is inserted at the beginning of the function. If it is set to <em>end</em>, the code
is inserted at the end of the function.</p>
<p>The <tt class="docutils literal"><span class="pre">since</span></tt> attribute specify the API version where this code was injected.</p>
</div></blockquote>
</div>
<div class="section" id="modify-field">
<h2>3.2.2. modify-field</h2>
<blockquote>
<div><p>The modify-field node allows you to alter the access privileges for a given
C++ field when mapping it onto the target language, and it is a child of an
<a class="reference internal" href="typesystem_specifying_types.html#object-type"><em>object-type</em></a> or a <a class="reference internal" href="typesystem_specifying_types.html#value-type"><em>value-type</em></a> node.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><object-type></span>
<span class="nt"><modify-field</span> <span class="na">name=</span><span class="s">"..."</span>
<span class="na">write=</span><span class="s">"true | false"</span>
<span class="na">read=</span><span class="s">"true | false"</span> <span class="nt">/></span>
<span class="nt"></object-type></span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">name</span></tt> attribute is the name of the field, the <em>optional</em> <tt class="docutils literal"><span class="pre">write</span></tt>
and <tt class="docutils literal"><span class="pre">read</span></tt> attributes specify the field’s access privileges in the target
language API (both are set to true by default).
The <tt class="docutils literal"><span class="pre">remove</span></tt> attribute is an <em>optional</em> attribute, which can mark the field
to be discarded on generation; it has the same purpose of the deprecated tag
<a class="reference internal" href="typesystem_modify_function.html#remove"><em>remove</em></a>.</p>
</div></blockquote>
</div>
<div class="section" id="modify-function">
<span id="id3"></span><h2>3.2.3. modify-function</h2>
<blockquote>
<div><p>The modify-function node allows you to modify a given C++ function when mapping
it onto the target language, and it is a child of an <a class="reference internal" href="typesystem_specifying_types.html#object-type"><em>object-type</em></a> or a <a class="reference internal" href="typesystem_specifying_types.html#value-type"><em>value-type</em></a>
node. Use the <a class="reference internal" href="typesystem_modify_function.html#modify-argument"><em>modify-argument</em></a> node to specify which argument the modification
affects.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><object-type></span>
<span class="nt"><modify-function</span> <span class="na">signature=</span><span class="s">"..."</span>
<span class="na">since=</span><span class="s">"..."</span>
<span class="na">remove=</span><span class="s">"all | c++"</span>
<span class="na">access=</span><span class="s">"public | private | protected"</span>
<span class="na">rename=</span><span class="s">"..."</span> <span class="nt">/></span>
<span class="nt"></object-type></span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">signature</span></tt> attribute is a normalized C++ signature, excluding return
values but including potential const declarations.</p>
<p>The <tt class="docutils literal"><span class="pre">since</span></tt> attribute specify the API version when this function was modified.</p>
<p>The <tt class="docutils literal"><span class="pre">remove</span></tt>, <tt class="docutils literal"><span class="pre">access</span></tt> and <tt class="docutils literal"><span class="pre">rename</span></tt> attributes are <em>optional</em> attributes
for added convenience; they serve the same purpose as the deprecated tags <a class="reference internal" href="typesystem_modify_function.html#remove"><em>remove</em></a>, <a class="reference internal" href="typesystem_modify_function.html#access"><em>access</em></a> and <a class="reference internal" href="typesystem_modify_function.html#rename"><em>rename</em></a>.</p>
</div></blockquote>
</div>
<div class="section" id="add-function">
<span id="id4"></span><h2>3.2.4. add-function</h2>
<blockquote>
<div><p>The add-function node allows you to add a given function onto the target language,
and it is a child of an <a class="reference internal" href="typesystem_specifying_types.html#object-type"><em>object-type</em></a> or <a class="reference internal" href="typesystem_specifying_types.html#value-type"><em>value-type</em></a> nodes if the
function is suposed to be a method, or <a class="reference internal" href="typesystem_specifying_types.html#namespace"><em>namespace-type</em></a> and <a class="reference internal" href="typesystem_specifying_types.html#typesystem"><em>typesystem</em></a> if
the function is suposed to be a function inside a namespace or a global function.</p>
<p>Typically when adding a function some code must be injected to provide the function
logic. This can be done using the <a class="reference internal" href="#inject-code"><em>inject-code</em></a> node.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><object-type></span>
<span class="nt"><add-function</span> <span class="na">signature=</span><span class="s">"..."</span> <span class="na">return-type=</span><span class="s">"..."</span> <span class="na">access=</span><span class="s">"public | protected"</span> <span class="na">static=</span><span class="s">"yes | no"</span> <span class="na">since=</span><span class="s">"..."</span><span class="nt">/></span>
<span class="nt"></object-type></span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">return-type</span></tt> attribute defaults to <em>void</em>, the <tt class="docutils literal"><span class="pre">access</span></tt> to <em>public</em> and the <tt class="docutils literal"><span class="pre">static</span></tt> one to <em>no</em>.</p>
<p>The <tt class="docutils literal"><span class="pre">since</span></tt> attribute specify the API version when this function was added.</p>
</div></blockquote>
</div>
<div class="section" id="conversion-rule">
<span id="conversion-rule-on-types"></span><h2>3.2.5. conversion-rule</h2>
<blockquote>
<div><p>The conversion-rule node allows you to write customized code to convert the given argument between the target
language and C++, and is a child of the <a class="reference internal" href="typesystem_specifying_types.html#value-type"><em>value-type</em></a>, <a class="reference internal" href="typesystem_specifying_types.html#object-type"><em>object-type</em></a>, <a class="reference internal" href="typesystem_specifying_types.html#primitive-type"><em>primitive-type</em></a> and
<a class="reference internal" href="typesystem_specifying_types.html#container-type"><em>container-type</em></a> nodes.</p>
<p>The code pointed by the file attribute is very tied to the generator using APIExtractor, so it don’t follow any
rules, but the generator rules..</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><value-type</span> <span class="na">name=</span><span class="s">"Foo"</span><span class="nt">></span>
<span class="nt"><convertion-rule</span> <span class="na">file=</span><span class="s">"my_converter_implementation.h"</span> <span class="na">since=</span><span class="s">"..."</span><span class="nt">/></span>
<span class="nt"></value-type></span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">since</span></tt> attribute specify the API version when this conversion rule became valid.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">You can also use the conversion-rule node to specify <a class="reference internal" href="typesystem_arguments.html#conversion-rule"><em>how the conversion of a single function argument should be done in a function</em></a>.</p>
</div>
</div></blockquote>
</div>
</div>
</div> <!-- container -->
<div id="footer">
<a href="http://www.indt.org.br"><img src="_static/logo_indt.jpg" alt="Indt" border="0" /></a>
<a href="http://www.openbossa.org"><img src="_static/logo_openbossa.png" alt="Openbossa" border="0" /></a>
<a href="http://qt.nokia.com/"><img src="_static/logo_qt.png" alt="Qt" border="0" /></a>
<a href="http://www.python.org"><img src="_static/logo_python.jpg" alt="Python" border="0" /></a>
</div>
</div>
</body>
</html>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
388a191dbad6b966fd8a7add43a4053b
>
files
>
56
