<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<!-- /home/gvatteka/dev/qtjambi/4.3/scripts/../doc/src/qtjambi-generator.qdoc -->
<head>
<title>The Qt Jambi Type System</title>
<link href="classic.css" rel="stylesheet" type="text/css" />
</head>
<body>
<h1 align="center">The Qt Jambi Type System<br /><small></small></h1>
<p>The type system is used when mapping a C++ based library onto a corresponding Java library using the <a href="qtjambi-generator.html">Qt Jambi generator</tt></a>.</p>
<p>The developer can define the scope of the Java API by writing a type system specification. The specification is a handwritten XML document listing the types that will be available in the generated Java API; types that are not declared in the specification will be ignored along with everything that depends on them. In addition, it is possible to manipulate and modify the types and functions. It is even possible to use the type system specification to inject arbitrary code into the source files, such as an extra member function.</p>
<p>The type system specification is passed as an argument to the <a href="qtjambi-generator.html">generator</tt></a>.</p>
<p>Below is a complete reference guide to the various nodes of the type system. For examples of use, take a look at the type system files used to generate the Qt Jambi API. These files can be found in the <tt>generator</tt> directory of the Qt Jambi package.</p>
<ul><li><a href="#alphabetical-list">Alphabetical List</a></li>
<li><a href="#specifying-types">Specifying Types</a></li>
<ul><li><a href="#value-type-requirements">Value Type Requirements</a></li>
<li><a href="#manipulating-object-and-value-types">Manipulating Object and Value Types</a></li>
<li><a href="#manipulating-namespace-and-interface-types">Manipulating Namespace and Interface Types</a></li>
<li><a href="#manipulating-enum-types">Manipulating Enum Types</a></li>
</ul>
<li><a href="#modifying-functions">Modifying Functions</a></li>
<ul><li><a href="#modifying-arguments">Modifying Arguments</a></li>
</ul>
<li><a href="#using-code-templates">Using Code Templates</a></li>
</ul>
<p>See also: <a href="qtjambi-generatorexample.html">Qt Jambi Generator Example</tt></a></p>
<a name="alphabetical-list"></a>
<h2>Alphabetical List</h2>
<p><a href="qtjambi-typesystem.html#access">access</tt></a>, <a href="qtjambi-typesystem.html#argument-map">argument-map</tt></a>, <a href="qtjambi-typesystem.html#conversion-rule">conversion-rule</tt></a>, <a href="qtjambi-typesystem.html#custom-constructor">custom-constructor</tt></a>, <a href="qtjambi-typesystem.html#custom-destructor">custom-destructor</tt></a>, <a href="qtjambi-typesystem.html#define-ownership">define-ownership</tt></a>, <a href="qtjambi-typesystem.html#enum-type">enum-type</tt></a>, <a href="qtjambi-typesystem.html#extra-includes">extra-includes</tt></a>, <a href="qtjambi-typesystem.html#include">include</tt></a>, <a href="qtjambi-typesystem.html#inject-code">inject-code</tt></a>, <a href="qtjambi-typesystem.html#insert-template">insert-template</tt></a>, <a href="qtjambi-typesystem.html#interface-type">interface-type</tt></a>, <a href="qtjambi-typesystem.html#load-typesystem">load-typesystem (multiple type system)</tt></a>, <a href="qtjambi-typesystem.html#modify-argument">modify-argument</tt></a>, <a href="qtjambi-typesystem.html#modify-field">modify-field</tt></a>, <a href="qtjambi-typesystem.html#modify-function">modify-function</tt></a>, <a href="qtjambi-typesystem.html#namespace-type">namespace-type</tt></a>, <a href="qtjambi-typesystem.html#object-type">object-type</tt></a>, <a href="qtjambi-typesystem.html#primitive-type">primitive-type</tt></a>, <a href="qtjambi-typesystem.html#reject-enum-value">reject-enum-value</tt></a>, <a href="qtjambi-typesystem.html#rejection">rejection</tt></a>, <a href="qtjambi-typesystem.html#remove">remove</tt></a>, <a href="qtjambi-typesystem.html#remove-argument">remove-argument</tt></a>, <a href="qtjambi-typesystem.html#remove-default-expression">remove-default-expression</tt></a>, <a href="qtjambi-typesystem.html#rename">rename</tt></a>, <a href="qtjambi-typesystem.html#replace">replace</tt></a>, <a href="qtjambi-typesystem.html#replace-default-expression">replace-default-expression</tt></a>, <a href="qtjambi-typesystem.html#replace-type">replace-type</tt></a>, <a href="qtjambi-typesystem.html#suppress-warning">suppress-warning</tt></a>, <a href="qtjambi-typesystem.html#template">template</tt></a>, <a href="qtjambi-typesystem.html#typesystem">typesystem</tt></a>, <a href="qtjambi-typesystem.html#value-type">value-type</tt></a></p>
<a name="specifying-types"></a>
<h2>Specifying Types</h2>
<p align="center"><img src="images/typesystem-root.png" /></p><p><table width="100%" align="center" cellpadding="2" cellspacing="1" border="0">
<thead><tr valign="top" class="qt-style"><th>Node</th><th>Description</th></tr></thead>
<tr valign="top" class="odd"><td><b>typesystem</b> <a name="typesystem"></a></td><td>The <tt>typesystem</tt> node is the root node containing all the type system information.<pre> <typesystem package="..."
default-superclass="..." (optional)>
</typesystem></pre>
<p>The <tt>package</tt> attribute is a string describing the package to be used, e.g.,<tt>"com.trolltech.qt.core"</tt>. The optional <tt>default-superclass</tt> attribute is the complete class name of the default baseclass of all objects in Java, e.g., <tt>"com.trolltech.qt.QtJambiObject"</tt>.</p>
</td></tr>
<tr valign="top" class="even"><td><b>load-typesystem</b> <a name="load-typesystem"></a></td><td>The <tt>load-typesystem</tt> node specifies which type systems to load when mapping multiple libraries to Java or basing one library on another, and is a child of the <a href="qtjambi-typesystem.html#typesystem">typesystem</tt></a> node.<pre> <typesystem ...>
<load-typesystem name="..."
generate="yes | no">
</typesystem></pre>
<p>The <tt>name</tt> attribute is the filename of the type system to load, the <tt>generate</tt> attribute specifies whether code should be generated or not. The latter 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>
</td></tr>
<tr valign="top" class="odd"><td><b>rejection</b> <a name="rejection"></a></td><td>The <tt>rejection</tt> node rejects the given class, or the specified function or field, and is a child of the <a href="qtjambi-typesystem.html#typesystem">typesystem</tt></a> node.<pre> <typesystem ...>
<rejection class="..."
function-name="..." (optional)
field-name="..." (optional) />
</typesystem></pre>
<p>The <tt>class</tt> attribute is the C++ class name of the class to reject. Use the optional <tt>function-name</tt> or <tt>field-name</tt> attributes to reject a particular function or field. Note that the <tt>field-name</tt> and <tt>function-name</tt> cannot be specified at the same time. To remove all occurrences of a given field or function, set the <tt>class</tt> attribute to <tt>*</tt>.</p>
</td></tr>
<tr valign="top" class="even"><td><b>primitive-type</b> <a name="primitive-type"></a></td><td>The <tt>primitive-type</tt> node describes how a primitive type is mapped from C++ to Java and the Java Native Interface (JNI), and is a child of the <a href="qtjambi-typesystem.html#typesystem">typesystem</tt></a> node. Note that most primitives are already specified in the QtCore type system.<pre> <typesystem ...>
<primitive-type name="..."
java-name="..." (optional)
jni-name="..." (optional)
preferred-conversion="yes | no" (optional)>
</typesystem></pre>
<p>The <tt>name</tt> attribute is the name of the primitive in C++, the <tt>java-name</tt> attribute is the name of the primitive in Java, and the <tt>jni-name</tt> attribute is the name of the primitive in JNI. If the latter two attributes are not specified, their default value will be the same as the <tt>name</tt> attribute.</p>
<p>If the optional <tt>preferred-conversion</tt> attribute is set to "no", it indicates that this version of the primitive is not the preferred C++ equivalent of the Java type. For example, both "qint64" and "long long" become "long" in Java but we should prefer the "qint64" version. For this reason we mark "long long" with <tt>preferred-conversion="no"</tt>.</p>
</td></tr>
<tr valign="top" class="odd"><td><b>namespace-type</b> <a name="namespace-type"></a></td><td>The <tt>namespace-type</tt> node maps the given C++ namespace to Java ( note that the namespace becomes an interface in Java), and is a child of the <a href="qtjambi-typesystem.html#typesystem">typesystem</tt></a> node. Note that within namespaces, the generator only supports enums (i.e., no functions or classes).<pre> <typesystem ...>
<namespace-type name="..."
package="..." (optional)
expense-cost="..." (opt)
expense-limit="..." (opt)/>
</typesystem></pre>
<p>The <tt>name</tt> attribute is the name of the namespace, e.g., "Qt". The <tt>package</tt> attribute can be used to override the package of the type system.</p>
<a name="expense"></a><p>The <tt>expense-cost</tt> attribute specifies the memory cost of using an instance of the given type, allowing the garbage collector to optimize the memory management. The cost is specified using Java code. The <tt>expense-limit</tt> attribute specifies how much an instance's memory consumption must be before the garbage collector is activated (the memory consumption is calculated using the value of the <tt>expense-cost</tt> attribute).</p>
</td></tr>
<tr valign="top" class="even"><td><b>enum-type</b> <a name="enum-type"></a></td><td>The <tt>enum-type</tt> node maps the given enum from C++ to Java, and is a child of the <a href="qtjambi-typesystem.html#typesystem">typesystem</tt></a> node. Use the <a href="qtjambi-typesystem.html#reject-enum-value">reject-enum-value</tt></a> to reject values.<pre> <typesystem ...>
<enum-type name="..."
flags="yes | no" (optional)
lower-bound="..." (optional)
upper-bound="..." (optional)
force-integer="yes | no" (optional)
extensible="yes | no" (optional)/>
</typesystem></pre>
<p>The <tt>name</tt> attribute is the fully qualified C++ name of the enum (e.g.,"Qt::FillRule"). If the optional <tt>flags</tt> attribute is set to <tt>yes</tt> (the default is <tt>no</tt>), the generator will expect an existing QFlags<T> for the given enum type. The <tt>lower-bound</tt> and <tt>upper-bound</tt> attributes are used to specify runtime boundschecking for the enum value. The value must be a compilable java statement, such as "<a href="gui/QGradient.html"><tt>QGradient</tt></a>.Spread.PadSpread". If the <tt>force-integer</tt> attribute is set to <tt>yes</tt> (the default is <tt>no</tt>), the generated Java code will use integers instead of Java enums. And finally, the <tt>extensible</tt> attribute specifies whether the given enum can be extended with user values (the default is <tt>no</tt>).</p>
</td></tr>
<tr valign="top" class="odd"><td><b>value-type</b> <a name="value-type"></a></td><td>The <tt>value-type</tt> node indicates that the given C++ type is mapped onto Java as a value type, and is a child of the <a href="qtjambi-typesystem.html#typesystem">typesystem</tt></a> node.<pre> <typesystem ...>
<value-type name="..."
package ="..." (optional)
default-superclass ="..." (optional)
polymorphic-base="yes | no" (opt)
polymorphic-id-expression="..." (opt)
expense-cost="..." (opt)
expense-limit="..." (opt)/>
</typesystem></pre>
<p>The <tt>name</tt> attribute is the fully qualified C++ class name, such as "<a href="gui/QMatrix.html"><tt>QMatrix</tt></a>" or "QPainterPath::Element". The <tt>package</tt> attribute can be used to override the package of the type system. If there is no C++ base class, the <tt>default-superclass</tt> attribute can be used to specify a superclass for the given type, in the generated Java API.</p>
<p>The <tt>polymorphic-base</tt> and <tt>polymorphic-id-expression</tt> attributes have the same meaning as the <a href="qtjambi-typesystem.html#polymorphic">object-type</tt></a> node, and the <tt>expense-cost</tt> and <tt>expense-limit</tt> attributes have the same meaning as for the <a href="qtjambi-typesystem.html#expense">namespace-type</tt></a> node.</p>
</td></tr>
<tr valign="top" class="even"><td><b>object-type</b> <a name="object-type"></a></td><td>The <tt>object-type</tt> node indicates that the given C++ type is mapped onto Java as an object type, and is a child of the <a href="qtjambi-typesystem.html#typesystem">typesystem</tt></a> node.<pre> <typesystem ...>
<object-type name="..."
package ="..." (optional)
default-superclass ="..." (optional)
polymorphic-base="yes | no" (opt)
polymorphic-id-expression="..." (opt)
expense-cost="..." (opt)
expense-limit="..." (opt)/>
</typesystem></pre>
<p>The <tt>name</tt> attribute is the fully qualified C++ class name. The <tt>package</tt> attribute can be used to override the package of the type system. If there is no C++ base class, the <tt>default-superclass</tt> attribute can be used to specify a superclass for the given type, in the generated Java API.</p>
<a name="polymorphic"></a><p>The <tt>polymorphic-base</tt> attribute is used to specify the base class for polymorphic types that do not inherit <a href="core/QObject.html"><tt>QObject</tt></a> (like <a href="core/QEvent.html"><tt>QEvent</tt></a>), i.e. types that do not support introspection. By specifying the base class, introspection is enabled, provided that the subclasses sets the <tt>polymorphic-id-expression</tt> attribute. For example:</p>
<pre> <object-type name="QEvent" polymorphic-base="yes" />
<object-type name="QTimerEvent"
polymorphic-id-expression="%1->type() == QEvent::Timer)" /></pre>
<p>The <tt>polymorphic-id-expression</tt> attribute specifies code that determines which subclass, in a polymorphic hierarchy, an object belongs to. Instances of <tt>%1</tt> in the code will be replaced by the name of the object in question.</p>
<p>The <tt>expense-cost</tt> and <tt>expense-limit</tt> attributes have the same meaning as for the <a href="qtjambi-typesystem.html#expense">namespace-type</tt></a> node.</p>
</td></tr>
<tr valign="top" class="odd"><td><b>interface-type</b> <a name="interface-type"></a></td><td>The <tt>interface-type</tt> node indicates that the given class is replaced by an interface pattern when mapping from C++ to Java. It is used to resolve multiple base classes which is not supported by Java. Using the <tt>interface-type</tt> node implicitly makes the given type an <a href="qtjambi-typesystem.html#object-type">object type</tt></a>.<pre> <typesystem ...>
<interface-type name="..."
package ="..." (optional)
default-superclass ="..." (optional)
polymorphic-base="yes | no" (opt)
polymorphic-id-expression="..." (opt)
expense-cost="..." (opt)
expense-limit="..." (opt)/>
</typesystem></pre>
<p>The <tt>name</tt> attribute is the fully qualified C++ class name. The <tt>package</tt> attribute can be used to override the package of the type system. If there is no C++ base class, the <tt>default-superclass</tt> attribute can be used to specify a superclass in the generated Java API, for the given class.</p>
<p>The <tt>polymorphic-base</tt> and <tt>polymorphic-id-expression</tt> attributes have the same meaning as the <a href="qtjambi-typesystem.html#polymorphic">object-value</tt></a> node, and the <tt>expense-cost</tt> and <tt>expense-limit</tt> attributes have the same meaning as for the <a href="qtjambi-typesystem.html#expense">namespace-type</tt></a> node.</p>
</td></tr>
<tr valign="top" class="even"><td><b>suppress-warning</b> <a name="suppress-warning"></a></td><td>The generator will generate several warnings which may be irrelevant to the user. The <tt>suppress-warning</tt> node suppresses the specified warning, and is a child of the <a href="qtjambi-typesystem.html#typesystem">typesystem</tt></a> node.<pre> <typesystem...>
<suppress-warning text="..." />
</typesystem></pre>
<p>The <tt>text</tt> attribute is the warning text to suppress, and may contain the <tt>*</tt> wildcard (use "" to escape regular expression matching if the warning contain a regular "*").</p>
</td></tr>
<tr valign="top" class="odd"><td><b>template</b> <a name="template"></a></td><td>The <tt>template</tt> node registers a template that can be used to avoid duplicate code when extending the generated code, and is a child of the <a href="qtjambi-typesystem.html#typesystem">typesystem</tt></a> node.<pre> <typesystem>
<template name="my_template">
<span class="comment">// the code</span>
</template>
</typesystem></pre>
<p>Use the <a href="qtjambi-typesystem.html#insert-template">insert-template</tt></a> node to insert the template code (identified by the template's <tt>name</tt> attribute) into the generated code base.</p>
</td></tr>
</table></p>
<a name="value-type-requirements"></a>
<h3>Value Type Requirements</h3>
<p align="center"><img src="images/typesystem-valuetype.png" /></p><p><table width="100%" align="center" cellpadding="2" cellspacing="1" border="0">
<thead><tr valign="top" class="qt-style"><th>Node</th><th>Description</th></tr></thead>
<tr valign="top" class="odd"><td><b>custom-constructor</b> <a name="custom-constructor"></a></td><td>In Java, value types are required to have a copy constructor. If a C++ class without a copy constructor is mapped onto Java as a value type, it is possible to provide a custom constructor using the <tt>custom-constructor</tt> node which is a child of the <tt>value-type</tt> node.<pre> <value-type ...>
<custom-constructor
name="..." (optional)
param-name="..." (optional)>
<span class="comment">// code for custom constructor</span>
</custom-constructor>
</value-type></pre>
<p>The custom constructor's signature becomes:</p>
<pre> T *name(T *param-name);</pre>
<p>If not specified the name of the constructor becomes <tt><lowercase type name>_create()</tt> and the parameter name becomes <tt>copy</tt>.</p>
</td></tr>
<tr valign="top" class="even"><td><b>custom-destructor</b> <a name="custom-destructor"></a></td><td>When a custom constructor is provided using the <a href="qtjambi-typesystem.html#custom-constructor">custom-constructor</tt></a> node, it is most likely required to clean up the allocated memory. For that reason, it is also possible to provide a custom destructor using the <tt>custom-destructor</tt> node which is a child of the <tt>value-type</tt> node.<pre> <value-type ...>
<custom-destructor
name="..." (optional)
param-name="..." (optional)>
<span class="comment">// code for custom destructor</span>
</custom-destructor>
</value-type></pre>
<p>The custom destructor must have the following signature:</p>
<pre> T *name(T *param-name);</pre>
<p>If not specified the name of the destructor becomes <tt><lowercase type name>_delete()</tt> and the parameter name becomes <tt>copy</tt>.</p>
</td></tr>
<tr valign="top" class="odd"><td><b>insert-template</b></td><td>Documented in the <a href="qtjambi-typesystem.html#insert-template">Using Code Templates</tt></a> section</td></tr>
</table></p>
<a name="manipulating-object-and-value-types"></a>
<h3>Manipulating Object and Value Types</h3>
<p align="center"><img src="images/typesystem-manipulatingtypes.png" /></p><p><table width="100%" align="center" cellpadding="2" cellspacing="1" border="0">
<thead><tr valign="top" class="qt-style"><th>Node</th><th>Description</th></tr></thead>
<tr valign="top" class="odd"><td><b>inject-code</b> <a name="inject-code"></a></td><td>The <tt>inject-code</tt> node inserts the given code into the generated code for the given type or function, and is a child of the <a href="qtjambi-typesystem.html#object-type">object-type</tt></a>, <a href="qtjambi-typesystem.html#value-type">value-type</tt></a> and <a href="qtjambi-typesystem.html#modify-function">modify-function</tt></a> nodes.<pre> <value-type ...>
<inject-code class="java | native | shell | shell-declaration"
position="beginning | end">
<span class="comment">// the code</span>
</inject-code>
</value-type></pre>
<p>The <tt>class</tt> attribute specifies which module of the generated code that will be affected by the code injection. The <tt>class</tt> attribute accepts the following values:</p>
<ul>
<li><tt>java</tt>: The generated java code</li>
<li><tt>native</tt>: The generated JNI-based methods</li>
<li><tt>shell</tt>: The generated shell class</li>
<li><tt>shell-declaration</tt>: The code will be injected into the generated header file containing the shell class definition.</li>
</ul>
<p>If the position attribute is set to <tt>beginning</tt> (the default), the code is inserted at the beginning of the function. If it is set to <tt>end</tt>, the code is inserted at the end of the function.</p>
</td></tr>
<tr valign="top" class="even"><td><b>modify-field</b> <a name="modify-field"></a></td><td>The <tt>modify-field</tt> node allows you to alter the access privileges for a given C++ field when mapping it onto Java, and is a child of an <a href="qtjambi-typesystem.html#object-type">object-type</tt></a> or a <a href="qtjambi-typesystem.html#value-type">value-type</tt></a> node.<pre> <object-type ...>
<modify-field name="..."
write="true | false" (optional)
read="true | false" (optional)/>
</object-type></pre>
<p>The <tt>name</tt> attribute is the name of the field, the optional <tt>write</tt> and <tt>read</tt> attributes specify the field's access privileges in the Java API (both are set to <tt>true</tt> by default).</p>
</td></tr>
<tr valign="top" class="odd"><td><b>modify-function</b> <a name="modify-function"></a></td><td>The <tt>modify-function</tt> node allows you to modify a given C++ function when mapping it onto Java, and is a child of an <a href="qtjambi-typesystem.html#object-type">object-type</tt></a> or a <a href="qtjambi-typesystem.html#value-type">value-type</tt></a> node. Use the <a href="qtjambi-typesystem.html#modify-argument">modify-argument</tt></a> node to specify which argument the modification affects.<pre> <object-type ...>
<modify-function signature="..."
remove="all | java"
access="public | private | protected"
rename="..." >
</object-type></pre>
<p>The <tt>signature</tt> attribute is a normalized C++ signature, excluding return values but including potential <tt>const</tt> declarations.</p>
<p>The <tt>remove</tt>, <tt>access</tt> and <tt>rename</tt> attributes are optional attributes for added convenience; they serve the same purpose as the tags <a href="qtjambi-typesystem.html#remove">remove</tt></a>, <a href="qtjambi-typesystem.html#access">access</tt></a> and <a href="qtjambi-typesystem.html#rename">rename</tt></a>.</p>
</td></tr>
<tr valign="top" class="even"><td><b>include</b></td><td>Documented in the <a href="qtjambi-typesystem.html#include">Manipulating Namespace and Interface Types</tt></a> section</td></tr>
<tr valign="top" class="odd"><td><b>extra-includes</b></td><td>Documented in the <a href="qtjambi-typesystem.html#include">Manipulating Namespace and Interface Types</tt></a> section</td></tr>
<tr valign="top" class="even"><td><b>insert-template</b></td><td>Documented in the <a href="qtjambi-typesystem.html#insert-template">Using Code Templates</tt></a> section</td></tr>
</table></p>
<a name="manipulating-namespace-and-interface-types"></a>
<h3>Manipulating Namespace and Interface Types</h3>
<p align="center"><img src="images/typesystem-manipulating-namespaces-and-interfaces.png" /></p><p><table width="100%" align="center" cellpadding="2" cellspacing="1" border="0">
<thead><tr valign="top" class="qt-style"><th>Node</th><th>Description</th></tr></thead>
<tr valign="top" class="odd"><td><b>extra-includes</b> <a name="extra-includes"></a></td><td>The <tt>extra-includes</tt> node contains declarations of additional include files, and can be a child of the <a href="qtjambi-typesystem.html#interface-type">interface-type</tt></a>, <a href="qtjambi-typesystem.html#namespace-type">namespace-type</tt></a>, <a href="qtjambi-typesystem.html#value-type">value-type</tt></a> and <a href="qtjambi-typesystem.html#object-type">object-type</tt></a> nodes.<p>The generator automatically tries to read the global header for each type. But sometimes it is required to include extra files in the generated C++ code to make sure that the code compiles. These files must be listed using <a href="qtjambi-typesystem.html#include">include</tt></a> nodes witin the <tt>extra-include</tt> node:</p>
<pre> <value-type ...>
<extra-includes>
<include file-name="..." location="global | local | java"/>
</extra-includes>
</value-type></pre>
<p>The <tt>file-name</tt> attribute is the file to include, such as "<a href="porting4.html#qstringlist"><tt>QStringList</tt></a>". The <tt>location</tt> attribute is where the file is located: <tt>global</tt> means that the file is located in <tt>$INCLUDEPATH</tt> and will be included using <tt>#include <...></tt>, <tt>local</tt> means that the file is in a local directory and will be included using <tt>#include "..."</tt>. If the <tt>location</tt> is set to <tt>java</tt> then the <tt>file-name</tt> attribute is expected to contain the fully qualified name for a java class and the specified class will be imported in the generated java code.</p>
</td></tr>
<tr valign="top" class="even"><td><b>include</b> <a name="include"></a></td><td>The <tt>include</tt> node specifies the name and location of a file that must be included, and is a child of the <a href="qtjambi-typesystem.html#interface-type">interface-type</tt></a>, <a href="qtjambi-typesystem.html#namespace-type">namespace-type</tt></a>, <a href="qtjambi-typesystem.html#value-type">value-type</tt></a>, <a href="qtjambi-typesystem.html#object-type">object-type</tt></a> or <a href="qtjambi-typesystem.html#extra-includes">extra-includes</tt></a> nodes<p>The generator automatically tries to read the global header for each type. Use the <tt>include</tt> node to override this behavior, providing an alternative file. The <tt>include</tt> node can also be used to specify <a href="qtjambi-typesystem.html#extra-includes">extra include files</tt></a>.</p>
<pre> <value-type ...>
<include file-name="..."
location="global | local | java"/>
</value-type></pre>
<p>The <tt>file-name</tt> attribute is the file to include, such as "<a href="porting4.html#qstringlist"><tt>QStringList</tt></a>". The <tt>location</tt> attribute is where the file is located: <tt>global</tt> means that the file is located in <tt>$INCLUDEPATH</tt> and will be included using <tt>#include <...></tt>, <tt>local</tt> means that the file is in a local directory and will be included using <tt>#include "..."</tt>. If the <tt>location</tt> attribute is set to <tt>java</tt> in this particular case, it will be ignored.</p>
</td></tr>
</table></p>
<a name="manipulating-enum-types"></a>
<h3>Manipulating Enum Types</h3>
<p align="center"><img src="images/typesystem-manipulatingenums.png" /></p><p><table width="100%" align="center" cellpadding="2" cellspacing="1" border="0">
<thead><tr valign="top" class="qt-style"><th>Node</th><th>Description</th></tr></thead>
<tr valign="top" class="odd"><td><b>reject-enum-value</b> <a name="reject-enum-value"></a></td><td>The <tt>reject-enum-value</tt> node rejects the enum value specified by the <tt>name</tt> attribute, and is a child of the <a href="qtjambi-typesystem.html#enum-type">enum-type</tt></a> node.<pre> <enum-type ...>
<reject-enum-value name="..."/>
</enum-type></pre>
<p>This node is used when a C++ enum implementation has several identical numeric values, some of which are typically obsolete.</p>
</td></tr>
</table></p>
<a name="modifying-functions"></a>
<h2>Modifying Functions</h2>
<p align="center"><img src="images/typesystem-modifyfunction.png" /></p><p><table width="100%" align="center" cellpadding="2" cellspacing="1" border="0">
<thead><tr valign="top" class="qt-style"><th>Node</th><th>Description</th></tr></thead>
<tr valign="top" class="odd"><td><b>modify-argument</b> <a name="modify-argument"></a></td><td>The <tt>modify-argument</tt> node specifies which of the given function's arguments the modification affects, and is a child of the <a href="qtjambi-typesystem.html#modify-function">modify-function</tt></a> node. Use the <a href="qtjambi-typesystem.html#remove-argument">remove-argument</tt></a>, <a href="qtjambi-typesystem.html#replace-default-expression">replace-default-expression</tt></a>, <a href="qtjambi-typesystem.html#remove-default-expression">remove-default-expression</tt></a>, <a href="qtjambi-typesystem.html#replace-type">replace-type</tt></a>, <a href="qtjambi-typesystem.html#reference-count">reference-count</tt></a> and <a href="qtjambi-typesystem.html#define-ownership">define-ownership</tt></a> nodes to specify the details of the modification.<pre> <modify-function ...>
<modify-argument index="return | this | 1 ...>
modifications
</modify-argument>
</modify-function></pre>
<p>Set the <tt>index</tt> attribute to "1" for the first argument, "2" for the second one and so on. Alternatively, set it to "return" or "this" if you want to modify the function's return value or the object the function is called upon, respectively.</p>
</td></tr>
<tr valign="top" class="even"><td><b>remove</b> <a name="remove"></a></td><td>The <tt>remove</tt> node removes the given method from the generated Java code, and is a child of the <a href="qtjambi-typesystem.html#modify-function">modify-function</tt></a> node.<pre> <modify-function ...>
<remove class="all | java" />
</modify-function></pre>
<p>If the <tt>class</tt> attribute is set to "java", the function is only removed for the generated java code; the default value is "all".</p>
</td></tr>
<tr valign="top" class="odd"><td><b>access</b> <a name="access"></a></td><td>The <tt>access</tt> node changes the access privileges of the given function in the generated Java code, and is a child of the <a href="qtjambi-typesystem.html#modify-function">modify-function</tt></a> node.<pre> <modify-function ...>
<access modifier="public | protected | private"/>
</modify-function></pre>
</td></tr>
<tr valign="top" class="even"><td><b>rename</b> <a name="rename"></a></td><td>The <tt>rename</tt> node changes the name of the given function in the generated Java code, and is a child of the <a href="qtjambi-typesystem.html#modify-function">modify-function</tt></a> node.<pre> <modify-function...>
<rename to="..." />
</modify-function></pre>
<p>The <tt>to</tt> attribute is the new name of the function.</p>
</td></tr>
<tr valign="top" class="odd"><td><b>inject-code</b></td><td>Documented in the <a href="qtjambi-typesystem.html#inject-code">Manipulating Types</tt></a> section</td></tr>
<tr valign="top" class="even"><td><b>argument-map</b> <a name="argument-map"></a></td><td>The <tt>argument-map</tt> node maps a C++ argument name to the argument name used in the generated Java code, and is a child of the <a href="qtjambi-typesystem.html#inject-code">inject-code</tt></a> node when the latter is a child of a <a href="qtjambi-typesystem.html#modify-function">modify-function</tt></a> node.<pre> <modify-function...>
<inject-code ...>
<argument-map index="numeric value"
meta-name="string value">
</inject-code>
</modify-function></pre>
<p>The <tt>index</tt> attribute is an index, starting at 1, indicating the argument position to which this argument mapping applies. The <tt>meta-name</tt> attribute is the name used within the code injection to adress the argument at the given position.</p>
</td></tr>
</table></p>
<a name="modifying-arguments"></a>
<h3>Modifying Arguments</h3>
<p align="center"><img src="images/typesystem-modifyargument.png" /></p><p><table width="100%" align="center" cellpadding="2" cellspacing="1" border="0">
<thead><tr valign="top" class="qt-style"><th>Node</th><th>Description</th></tr></thead>
<tr valign="top" class="odd"><td><b>remove-argument</b> <a name="remove-argument"></a></td><td>The <tt>remove-argument</tt> node removes the given argument from the function's signature, and is a child of the <a href="qtjambi-typesystem.html#modify-argument">modify-argument</tt></a> node.<pre> <modify-argument ...>
<remove-argument />
</modify-argument></pre>
<p>Typically, when removing an argument, some conversion rules must be specified, e.g., when converting from Java to C++. This can be done using the <a href="qtjambi-typesystem.html#conversion-rule">conversion-rule</tt></a> node.</p>
</td></tr>
<tr valign="top" class="even"><td><b>remove-default-expression</b> <a name="remove-default-expression"></a></td><td>The <tt>remove-default-expression</tt> node disables the use of the default expression for the given argument, and is a child of the <a href="qtjambi-typesystem.html#modify-argument">modify-argument</tt></a> node.<pre> <modify-argument...>
<remove-default-expression />
</modify-argument></pre>
</td></tr>
<tr valign="top" class="odd"><td><b>replace-default-expression</b> <a name="replace-default-expression"></a></td><td>The <tt>replace-default-expression</tt> node replaces the specified argument with the expression specified by the <tt>with</tt> attribute, and is a child of the <a href="qtjambi-typesystem.html#modify-argument">modify-argument</tt></a> node.<pre> <modify-argument...>
<replace-default-expression with="..." />
</modify-argument></pre>
</td></tr>
<tr valign="top" class="even"><td><b>replace-type</b> <a name="replace-type"></a></td><td>The <tt>replace-type</tt> node replaces the type of the given argument to the one specified by the <tt>modified-type</tt> attribute, and is a child of the <a href="qtjambi-typesystem.html#modify-argument">modify-argument</tt></a> node.<pre> <modify-argument...>
<replace-type modified-type="..." />
</modify-argument></pre>
<p>If the new type is a class, the <tt>modified-type</tt> attribute must be set to the fully qualified name (including name of the package as well as the class name).</p>
<p>Typically, when changing the type of an argument, some conversion rules must be specified. This can be done using the <a href="qtjambi-typesystem.html#conversion-rule">conversion-rule</tt></a> node.</p>
</td></tr>
<tr valign="top" class="odd"><td><b>reference-count</b> <a name="reference-count"></a></td><td>The <tt>reference-count</tt> tag indicates that the function holds a reference to the argument object without assuming ownership of it.<pre> <modify-argument ...>
<reference-count action="add | add-all | remove | set | ignore"
variable-name="..."
declare-variable="..."
conditional="..."
access="public | private | protected | friendly" />
</modify-argument></pre>
<p>The <tt>action</tt> attribute specifies the action to be taken. <tt>add</tt>, <tt>add-all</tt> and <tt>remove</tt> are collection actions. They will add a single object to a list of references, add all objects in a collection to a list of references or remove a single object from a list of references. <tt>set</tt> will assign the argument to the variable containing the reference (the argument must be a collection if the variable is also used for any of the collection specific actions.) <tt>ignore</tt> will not inject any code, but will cause the method in question to be removed from the log of possible reference counting API.</p>
<p>The <tt>variable-name</tt> attribute specifies the name used for the variable that holds the reference(s).</p>
<p>The <tt>declare-variable</tt> attribute can be used to specify the fully qualified name of the class that owns the reference. This attribute is optional, and should only be specified if the variable should not be declared in the current class. The specified must be in the superclass hierarchy of the current class.</p>
<p>The <tt>conditional</tt> attribute is optional, and specifies a conditional expression which must be true in order for the action of the <tt>reference-count</tt> tag to be taken.</p>
<p>The <tt>access</tt> attribute gives the visibility of the variable. Only applicable if <tt>declare-variable</tt> is not specified. The default value of <tt>access</tt> is <tt>private</tt>.</p>
</td></tr>
<tr valign="top" class="even"><td><b>define-ownership</b> <a name="define-ownership"></a></td><td>The <tt>define-ownership</tt> tag indicates that the function changes the ownership rules of the arguemnt object. The <tt>class</tt> attribute specifies the class of function in which to inject the ownership altering code. The <tt>owner</tt> attribute specifies the new ownership of the object. It accepts the following values:<ul>
<li><tt>java</tt>: Java will assume full ownership of the object. The native resources will be deleted when the Java object is finalized.</li>
<li><tt>c++</tt>: The native code assumes full ownership of the object. The Java object will not be garbage collected.</li>
<li><tt>default</tt>: The object will get default ownership, depending on how it was created.</li>
</ul>
<pre> <modify-argument ...>
<define-ownership class="java | shell"
owner="java | c++ | default" />
</modify-argument></pre>
</td></tr>
<tr valign="top" class="odd"><td><b>conversion-rule</b> <a name="conversion-rule"></a></td><td>The <tt>conversion-rule</tt> node allows you to write customized code to convert the given argument between Java and C++, and is a child of the <a href="qtjambi-typesystem.html#modify-argument">modify-argument</tt></a> node.<pre> <modify-argument ...>
<conversion-rule class="shell | native">
<span class="comment">// the code</span>
</conversion-rule>
</modify-argument></pre>
<p>This node is typically used in combination with the <a href="qtjambi-typesystem.html#replace-type">replace-type</tt></a> and <a href="qtjambi-typesystem.html#remove-argument">remove-argument</tt></a> nodes. The given code is used instead of the generator's conversion code in the following situations (defined by the <a href="qtjambi-typesystem.html#modify-argument">modify-argument</tt></a> node's <tt>index</tt> attribute and the <tt>class</tt> attribute as well the function implementation and where the function is called from):</p>
<table align="center" cellpadding="2" cellspacing="1" border="0">
<tr valign="top" bgcolor="#a2c511">
<th>Argument Index</th>
<th>Function Class</th>
<th>Function Implementation</th>
<th>Caller Location</th>
</tr>
<tr valign="top" bgcolor="#f0f0f0">
<td>1 | 2 ...</td>
<td>shell</td>
<td>Java (overriding C++)</td>
<td>C++ </td>
</tr>
<tr valign="top" bgcolor="#e0e0e0">
<td>1 | 2 ...</td>
<td>native</td>
<td>C++</td>
<td>Java</td>
</tr>
<tr valign="top" bgcolor="#f0f0f0">
<td>return</td>
<td>shell</td>
<td>C++</td>
<td>Java</td>
</tr>
<tr valign="top" bgcolor="#e0e0e0">
<td>return </td>
<td>native</td>
<td>Java (overriding C++)</td>
<td>C++</td>
</tr>
</table>
<p>Writing <tt>%N</tt> in the code (where <tt>N</tt> is a number), will insert the name of the <i>n</i>th argument. Alternatively, <tt>%in</tt> and <tt>%out</tt> which will be replaced with the name of the conversion's input and output variable, respectively. Note the output variable must be declared explicitly, for example:</p>
<pre> <conversion-rule class="native">
bool %out = (bool) %in;
</conversion-rule></pre>
</td></tr>
<tr valign="top" class="even"><td><b>insert-template</b></td><td>Documented in the <a href="qtjambi-typesystem.html#insert-template">Using Code Templates</tt></a> section</td></tr>
<tr valign="top" class="odd"><td><b>replace-value</b> <a name="replace-value"></a></td><td>The <tt>replace-value</tt> attribute lets you replace the return statement of a function with a fixed string. This attribute can only be used for the argument at index 0, which is always the function's return value.<p>Here is an example of how to use <tt>modify-argument</tt>:</p>
<pre> <modify-argument index="0" replace-value="this"/></pre>
</td></tr>
</table></p>
<a name="using-code-templates"></a>
<h2>Using Code Templates</h2>
<p align="center"><img src="images/typesystem-templates.png" /></p><p><table width="100%" align="center" cellpadding="2" cellspacing="1" border="0">
<thead><tr valign="top" class="qt-style"><th>Node</th><th>Description</th></tr></thead>
<tr valign="top" class="odd"><td><b>insert-template</b> <a name="insert-template"></a></td><td>The <tt>insert-template</tt> node includes the code template identified by the <tt>name</tt> attribute, and can be a child of the <a href="qtjambi-typesystem.html#inject-code">inject-code</tt></a>, <a href="qtjambi-typesystem.html#conversion-rule">conversion-rule</tt></a>, <a href="qtjambi-typesystem.html#template">template</tt></a>, <a href="qtjambi-typesystem.html#custom-constructor">custom-constructor</tt></a> and <a href="qtjambi-typesystem.html#custom-destructor">custom-destructor</tt></a> nodes. For example;<pre> <inject-code class="java" position="beginning">
<insert-template name="my_template" />
</inject-code></pre>
<p>Use the <a href="qtjambi-typesystem.html#replace">replace</tt></a> node to modify the template code.</p>
</td></tr>
<tr valign="top" class="even"><td><b>replace</b> <a name="replace"></a></td><td>The <tt>replace</tt> node allows you to modify template code before inserting it into the generated code, and can be a child of the <a href="qtjambi-typesystem.html#insert-template">insert-template</tt></a> node.<pre> <insert-template name="my_template">
<replace from="..." to="..." />
</insert-template></pre>
<p>Using this node the code specified by the <tt>from</tt> attribute is altered into the code specified by the <tt>to</tt> attribute.</p>
</td></tr>
</table></p>
<p /><address><hr /><div align="center">
<table width="100%" cellspacing="0" border="0"><tr class="address">
<td width="30%">Copyright © 2007 <a href="trolltech.html">Trolltech</a></td>
<td width="40%" align="center"><a href="trademarks.html">Trademarks</a></td>
<td width="30%" align="right"><div align="right">Qt Jambi </div></td>
</tr></table></div></address></body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
a6711891ce757817bba854bf3f25205a
>
files
>
2398
