<!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.1. Specifying 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.2. Manipulating Object and Value Types" href="typesystem_manipulating_objects.html" />
<link rel="prev" title="3. The API Extractor Type System" href="typesystem.html" />
</head>
<body id="typesystem_specifying_types">
<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_manipulating_objects.html" title="3.2. Manipulating Object and Value Types"
accesskey="N">next</a></li>
<li class="right">
<a href="typesystem.html" title="3. The API Extractor Type System"
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.1. Specifying Types</a><ul>
<li><a class="reference internal" href="#typesystem">3.1.1. typesystem</a></li>
<li><a class="reference internal" href="#load-typesystem">3.1.2. load-typesystem</a></li>
<li><a class="reference internal" href="#rejection">3.1.3. rejection</a></li>
<li><a class="reference internal" href="#primitive-type">3.1.4. primitive-type</a></li>
<li><a class="reference internal" href="#namespace-type">3.1.5. namespace-type</a></li>
<li><a class="reference internal" href="#enum-type">3.1.6. enum-type</a></li>
<li><a class="reference internal" href="#reject-enum-value">3.1.7. reject-enum-value</a></li>
<li><a class="reference internal" href="#value-type">3.1.8. value-type</a></li>
<li><a class="reference internal" href="#object-type">3.1.9. object-type</a></li>
<li><a class="reference internal" href="#interface-type">3.1.10. interface-type</a></li>
<li><a class="reference internal" href="#container-type">3.1.11. container-type</a></li>
<li><a class="reference internal" href="#function">3.1.12. function</a></li>
</ul>
</li>
</ul>
<h3>Previous topic</h3>
<p class="topless"><a href="typesystem.html"
title="previous chapter">3. The API Extractor Type System</a></p>
<h3>Next topic</h3>
<p class="topless"><a href="typesystem_manipulating_objects.html"
title="next chapter">3.2. Manipulating Object and Value Types</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="specifying-types">
<h1>3.1. Specifying Types</h1>
<div class="section" id="typesystem">
<span id="id1"></span><h2>3.1.1. typesystem</h2>
<blockquote>
<div><p>This is the root node containing all the type system information. It can
have a number of attributes, described below.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><typesystem</span> <span class="na">package=</span><span class="s">"..."</span> <span class="na">default-superclass=</span><span class="s">"..."</span><span class="nt">></span>
<span class="nt"></typesystem></span>
</pre></div>
</div>
<p>The <strong>package</strong> attribute is a string describing the package to be used,
e.g. “QtCore”.
The <em>optional</em> <strong>default-superclass</strong> attribute is the canonical C++ base class
name of all objects, e.g., “object”.</p>
</div></blockquote>
</div>
<div class="section" id="load-typesystem">
<h2>3.1.2. load-typesystem</h2>
<blockquote>
<div><p>The load-typesystem node specifies which type systems to load when mapping
multiple libraries to another language or basing one library on another, and
it is a child of the typesystem node.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><typesystem></span>
<span class="nt"><load-typesystem</span> <span class="na">name=</span><span class="s">"..."</span> <span class="na">generate=</span><span class="s">"yes | no"</span> <span class="nt">/></span>
<span class="nt"></typesystem></span>
</pre></div>
</div>
<p>The <strong>name</strong> attribute is the filename of the typesystem to load, the
<strong>generate</strong> attribute specifies whether code should be generated or not. The
later must be specified when basing one library on another, making the generator
able to understand inheritance hierarchies, primitive mapping, parameter types
in functions, etc.</p>
<p>Most libraries will be based on both the QtCore and QtGui modules, in which
case code generation for these libraries will be disabled.</p>
</div></blockquote>
</div>
<div class="section" id="rejection">
<h2>3.1.3. rejection</h2>
<blockquote>
<div><p>The rejection node rejects the given class, or the specified function or
field, and it is a child of the typesystem node.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><typesystem></span>
<span class="nt"><rejection</span> <span class="na">class=</span><span class="s">"..."</span>
<span class="na">function-name=</span><span class="s">"..."</span>
<span class="na">field-name=</span><span class="s">"..."</span> <span class="nt">/></span>
<span class="nt"></typesystem></span>
</pre></div>
</div>
<p>The <strong>class</strong> attribute is the C++ class name of the class to reject. Use the
<em>optional</em> <strong>function-name</strong> or <strong>field-name</strong> attributes to reject a particular
function or field. Note that the <strong>field-name</strong> and <strong>function-name</strong> cannot
be specified at the same time. To remove all occurrences of a given field or
function, set the class attribute to *.</p>
</div></blockquote>
</div>
<div class="section" id="primitive-type">
<span id="id2"></span><h2>3.1.4. primitive-type</h2>
<blockquote>
<div><p>The primitive-type node describes how a primitive type is mapped from C++ to
the target language, and is a child of the typesystem node. Note that most
primitives are already specified in the QtCore typesystem.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><typesystem></span>
<span class="nt"><primitive-type</span> <span class="na">name=</span><span class="s">"..."</span>
<span class="na">since=</span><span class="s">"..."</span>
<span class="na">target-name=</span><span class="s">"..."</span>
<span class="na">default-constructor=</span><span class="s">"..."</span>
<span class="na">preferred-conversion=</span><span class="s">"yes | no"</span> <span class="nt">/></span>
<span class="nt"></typesystem></span>
</pre></div>
</div>
<p>The <strong>name</strong> attribute is the name of the primitive in C++, the optional,
<strong>target-name</strong> attribute is the name of the primitive type in the target
language. If the later two attributes are not specified their default value
will be the same as the <strong>name</strong> attribute.</p>
<p>The <em>optional</em> <strong>since</strong> value is used to specify the API version of this type.</p>
<p>If the <em>optional</em> <strong>preferred-conversion</strong> attribute is set to <em>no</em>, it
indicates that this version of the primitive type is not the preferred C++
equivalent of the target language type. For example, in Python both “qint64”
and “long long” become “long” but we should prefer the “qint64” version. For
this reason we mark “long long” with preferred-conversion=”no”.</p>
<p>The <em>optional</em> <strong>preferred-conversion</strong> attribute tells how to build a default
instance of the primitive type. It should be a constructor call capable of
creating a instance of the primitive type. Example: a class “Foo” could have
a <strong>preferred-conversion</strong> value set to “Foo()”. Usually this attribute is
used only for classes declared as primitive types and not for primitive C++
types, but that depends on the application using <em>ApiExtractor</em>.</p>
</div></blockquote>
</div>
<div class="section" id="namespace-type">
<span id="namespace"></span><h2>3.1.5. namespace-type</h2>
<blockquote>
<div><p>The namespace-type node maps the given C++ namespace to the target language,
and it is a child of the typesystem node. Note that within namespaces, the
generator only supports enums (i.e., no functions or classes).</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><typesystem></span>
<span class="nt"><namespace-type</span> <span class="na">name=</span><span class="s">"..."</span>
<span class="na">generate=</span><span class="s">"yes | no"</span>
<span class="na">package=</span><span class="s">"..."</span> <span class="nt">/></span>
<span class="nt"></typesystem></span>
</pre></div>
</div>
<p>The <strong>name</strong> attribute is the name of the namespace, e.g., “Qt”.</p>
<p>The <em>optional</em> <strong>generate</strong> attribute is used to inform if you need to prepend
the given namespace into each generated class. Its default value is <strong>yes</strong>.</p>
<p>The <strong>package</strong> attribute can be used to override the package of the type system.</p>
<p>The <em>optional</em> <strong>since</strong> value is used to specify the API version of this type.</p>
</div></blockquote>
</div>
<div class="section" id="enum-type">
<h2>3.1.6. enum-type</h2>
<blockquote>
<div><p>The enum-type node maps the given enum from C++ to the target language,
and it is a child of the typesystem node. Use the reject-enum-value to
reject values.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><typesystem></span>
<span class="nt"><enum-type</span> <span class="na">name=</span><span class="s">"..."</span>
<span class="na">identified-by-value=</span><span class="s">"..."</span>
<span class="na">since=</span><span class="s">"..."</span>
<span class="na">flags=</span><span class="s">"yes | no"</span>
<span class="na">lower-bound=</span><span class="s">"..."</span>
<span class="na">upper-bound=</span><span class="s">"..."</span>
<span class="na">force-integer=</span><span class="s">"yes | no"</span>
<span class="na">extensible=</span><span class="s">"yes | no"</span> <span class="nt">/></span>
<span class="nt"></typesystem></span>
</pre></div>
</div>
<p>The <strong>name</strong> attribute is the fully qualified C++ name of the enum
(e.g.,”Qt::FillRule”). If the <em>optional</em> <strong>flags</strong> attribute is set to <em>yes</em>
(the default is <em>no</em>), the generator will expect an existing QFlags<T> for the
given enum type. The <strong>lower-bound</strong> and <strong>upper-bound</strong> attributes are used
to specify runtime bounds checking for the enum value. The value must be a
compilable target language statement, such as “QGradient.Spread.PadSpread”
(taking again Python as an example). If the <strong>force-integer</strong> attribute is
set to <em>yes</em> (the default is <em>no</em>), the generated target language code will
use the target language integers instead of enums. And finally, the
<strong>extensible</strong> attribute specifies whether the given enum can be extended
with user values (the default is <em>no</em>).</p>
<p>The <em>optional</em> <strong>since</strong> value is used to specify the API version of this type.</p>
<p>The attribute <strong>identified-by-value</strong> helps to specify anonymous enums using the
name of one of their values, which is unique for the anonymous enum scope.
Notice that the <strong>enum-type</strong> tag can either have <strong>name</strong> or <strong>identified-by-value</strong>
but not both.</p>
</div></blockquote>
</div>
<div class="section" id="reject-enum-value">
<h2>3.1.7. reject-enum-value</h2>
<blockquote>
<div><p>The reject-enum-value node rejects the enum value specified by the <strong>name</strong>
attribute, and it is a child of the enum-type node.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><enum-type></span>
<span class="nt"><reject-enum-value</span> <span class="na">name=</span><span class="s">"..."</span><span class="nt">/></span>
<span class="nt"></enum-type></span>
</pre></div>
</div>
<p>This node is used when a C++ enum implementation has several identical numeric
values, some of which are typically obsolete.</p>
</div></blockquote>
</div>
<div class="section" id="value-type">
<span id="id3"></span><h2>3.1.8. value-type</h2>
<blockquote>
<div><p>The value-type node indicates that the given C++ type is mapped onto the target
language as a value type. This means that it is an object passed by value on C++,
i.e. it is stored in the function call stack. It is a child of the <a class="reference internal" href="#typesystem"><em>typesystem</em></a> node.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><typesystem></span>
<span class="nt"><value-type</span> <span class="na">name=</span><span class="s">"..."</span> <span class="na">since=</span><span class="s">"..."</span>
<span class="na">copyable=</span><span class="s">"yes | no"</span>
<span class="na">hash-function=</span><span class="s">"..."</span>
<span class="na">stream=</span><span class="s">"yes | no"</span> <span class="nt">/></span>
<span class="nt"></typesystem></span>
</pre></div>
</div>
<p>The <strong>name</strong> attribute is the fully qualified C++ class name, such as
“QMatrix” or “QPainterPath::Element”. The <strong>copyable</strong> attribute is used to
force or not specify if this type is copyable. The <em>optional</em> <strong>hash-function</strong>
attribute informs the function name of a hash function for the type.</p>
<p>The <em>optional</em> attribute <strong>stream</strong> specifies whether this type will be able to
use externally defined operators, like QDataStream << and >>. If equals to <strong>yes</strong>,
these operators will be called as normal methods within the current class.</p>
<p>The <em>optional</em> <strong>since</strong> value is used to specify the API version of this type.</p>
</div></blockquote>
</div>
<div class="section" id="object-type">
<span id="id4"></span><h2>3.1.9. object-type</h2>
<blockquote>
<div><p>The object-type node indicates that the given C++ type is mapped onto the target
language as an object type. This means that it is an object passed by pointer on
C++ and it is stored on the heap. It is a child of the <a class="reference internal" href="#typesystem"><em>typesystem</em></a> node.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><typesystem></span>
<span class="nt"><object-type</span> <span class="na">name=</span><span class="s">"..."</span>
<span class="na">since=</span><span class="s">"..."</span>
<span class="na">copyable=</span><span class="s">"yes | no"</span>
<span class="na">hash-function=</span><span class="s">"..."</span>
<span class="na">stream=</span><span class="s">"yes | no"</span> <span class="nt">/></span>
<span class="nt"></typesystem></span>
</pre></div>
</div>
<p>The <strong>name</strong> attribute is the fully qualified C++ class name. If there is no
C++ base class, the default-superclass attribute can be used to specify a
superclass for the given type, in the generated target language API. The
<strong>copyable</strong> and <strong>hash-function</strong> attributes are the same as described for
<a class="reference internal" href="#value-type"><em>value-type</em></a>.</p>
<p>The <em>optional</em> attribute <strong>stream</strong> specifies whether this type will be able to
use externally defined operators, like QDataStream << and >>. If equals to <strong>yes</strong>,
these operators will be called as normal methods within the current class.</p>
<p>The <em>optional</em> <strong>since</strong> value is used to specify the API version of this type.</p>
</div></blockquote>
</div>
<div class="section" id="interface-type">
<h2>3.1.10. interface-type</h2>
<blockquote>
<div><p>The interface-type node indicates that the given class is replaced by an
interface pattern when mapping from C++ to the target language. Using the
interface-type node implicitly makes the given type an <a class="reference internal" href="#object-type"><em>object-type</em></a>.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><typesystem></span>
<span class="nt"><interface-type</span> <span class="na">name=</span><span class="s">"..."</span>
<span class="na">since=</span><span class="s">"..."</span>
<span class="na">package =</span><span class="s">"..."</span>
<span class="na">default-superclass =</span><span class="s">"..."</span> <span class="nt">/></span>
<span class="nt"></typesystem></span>
</pre></div>
</div>
<p>The <strong>name</strong> attribute is the fully qualified C++ class name. The <em>optional</em>
<strong>package</strong> attribute can be used to override the package of the type system.
If there is no C++ base class, the <em>optional</em> <strong>default-superclass</strong> attribute
can be used to specify a superclass in the generated target language API, for
the given class.</p>
<p>The <em>optional</em> <strong>since</strong> value is used to specify the API version of this interface.</p>
</div></blockquote>
</div>
<div class="section" id="container-type">
<span id="id5"></span><h2>3.1.11. container-type</h2>
<blockquote>
<div><p>The container-type node indicates that the given class is a container and
must be handled using one of the conversion helpers provided by attribute <strong>type</strong>.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><typesystem></span>
<span class="nt"><container-type</span> <span class="na">name=</span><span class="s">"..."</span>
<span class="na">since=</span><span class="s">"..."</span>
<span class="na">type =</span><span class="s">"..."</span> <span class="nt">/></span>
<span class="nt"></typesystem></span>
</pre></div>
</div>
<p>The <strong>name</strong> attribute is the fully qualified C++ class name. The <strong>type</strong>
attribute is used to indicate what conversion rule will be applied to the
container. It can be: <em>list</em>, <em>string-list</em>, <em>linked-list</em>, <em>vector</em>, <em>stack</em>,
<em>queue</em>, <em>set</em>, <em>map</em>, <em>multi-map</em>, <em>hash</em>, <em>multi-hash</em> or <em>pair</em>.</p>
<p>The <em>optional</em> <strong>since</strong> value is used to specify the API version of this container.</p>
</div></blockquote>
</div>
<div class="section" id="function">
<span id="id6"></span><h2>3.1.12. function</h2>
<blockquote>
<div><p>The function node indicates that the given C++ global function is mapped onto
the target language.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="nt"><typesystem></span>
<span class="nt"><function</span> <span class="na">signature=</span><span class="s">"..."</span> <span class="na">rename=</span><span class="s">"..."</span> <span class="na">since=</span><span class="s">"..."</span><span class="nt">/></span>
<span class="nt"></typesystem></span>
</pre></div>
</div>
<p>This tag has some limitations, it doesn’t support function modifications, besides you
can’t add a function overload using <a class="reference internal" href="typesystem_manipulating_objects.html#add-function"><em>add-function</em></a> tag to an existent function.
These limitation will be addressed in future versions of ApiExtractor.</p>
<p>The function tag has two <em>optional</em> attributes: <strong>since</strong>, whose value is used to specify
the API version of this function, and <strong>rename</strong>, to modify the function name.</p>
</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>
