Below is given a complete reference to the nodes in the typesystem. In addition to this, it might be helpful to look at the typesystem files used to generate Qt, typesystem_gui.xml, typesystem_core.xml and build_all.xml for examples of use.
Each type system consists of three files: typesystem_<module>-common.xml, typesystem_<module>-java.xml and typesystem_<module>-java.java. When running the ant task, the first two will be merged into a single file called typesystem_<module>.xml. Make sure you edit the correct files, because if you edit the merged file, your changes will be overwritten the next time you run the ant build (read: do anything).
The reason the type system is split up this way, is that the “common” file should contain data which is not specific to any particular target language, and could thus be used for generating e.g. QtScript or Python bindings. Anything which is particular to Java and the JNI binding layer (like Java code injections etc.) needs to go into the Java-specific XML-file.The typesystem_<module>-java.java file contains snippets of Java code which are injected into the generated classes in Qt Jambi. It has been formatted to be viewable in a Java editor and get correct highlighting. This is simply a convenience to make maintaining the code snippets easier, as you can also put the code directly into the XML files.
Typesystem master node
The typesystem node is the root node that contains all the typesystem information.
<typesystem package="..." default-superclass="..." (optional) >
|package||A string describing the package to be used, such as "com.trolltech.qt.core"|
|default-superclass||The complete className of the default baseclass of all objects in Java, such as "com.trolltech.qt.QtObject"|
When mapping multiple libraries to Java or basing one library on another library, it is possible to use the <load-typesystem> node. This node can be specified as a child of the <typesystem> node.
<load-typesystem name="..." generate="yes | no" >
|name||The filename of the typesystem to load.|
|generate||Specifies wether code should be generated or not. yes: The code is generated no: No code is generated. This is needed when basing one library on another for the generator to be able to understand inheritance hierarchies, primitive mapping and parameter types in functions etc.. Most libraries will be based on both QtCore and QtGui, in which case generation for these will be disabled.|
The rejection nodes are specified as children of the typesystem node. The are used to reject an entire class, or specific functions or fields. One should not specify both field-name and function-name at the same time.
<rejection class="..." function-name="..." (optional) field-name="..." (optional) >
|class||The C++ classname of the class to reject. This name can be "*" in combination with a field or function to remove for instance all functions named "d_func".|
|function-name||The name of the function to rejected. This attribute is optional.|
|field-name||The name of the field to reject. This attribute is optional.|
The primitive nodes are specified as children of the typesystem node and are used to describe how a primitive type maps from C++ to Java and the JNI interface. Most primitives are already specified in the QtCore typesystem so users willn not have to add existing ones.
<primitive-type name="..." java-name="..." (optional) jni-name="..." (optional) preferred-conversion="no" (optional) >
|name||The name of the primitive in C++, such as "char".|
|java-name||The name of the primitive in Java, such as "byte". If this value is not specified it will be the same as the name attribute.|
|jni-name||The name of the primitive in JNI, such as "jbyte". If this value is not specified it will be the same as the name attribute.|
|preferred-conversion||When this attribute is specified to "no" it indicatest that this version of the primitive is not the preferred C++ equivalent of the Java type. For instance both "qint64" and "long long" becomes "long" in Java but we should prefer the "qint64" version, hence we mark "long long" with this attribute.|
The namespace nodes are specified as children of the typesystem node and are used to enable a namespace to be mapped to Java. The generator only supports enums in namespaces, no functions or classes. A C++ namespace becomes an interface in Java.
<namespace-type name="..." >
|name||The name of the namespace, such as "Qt"|
The enum nodes are used to enable a specific enum within a class. Enums and flags are converted to ints in Java. Enums are disabled by default.
<enum-type name="..." flags="yes | no" (optional) >
|name||The fully qualified C++ name of the enum, such as "Qt::FillRule".|
|flags||If this attribute is set the generator will expect there to exist a QFlags<T> for the enum type.|
The value type nodes are specified as children of the typesystem node and are used to specify that a C++ type is mapped into Java as a value type.
<value-type name="..." >
|name||The fully qualified C++ class name, such as "QMatrix" or "QPainterPath::Element".|
The value type nodes are specified as children of the typesystem node and are used to specifye that a C++ type is mapped into Java as an object type.
<object-type name="..." memory-managed="yes | no" (optional) >
|name||fully qualified C++ class name, such as "QPushButton".|
|memory-managed||Specifies if the type, due to its use pattern should still be memory managed by Java, even though it is an object type, such as QFile.|
The field modification nodes are specified as children of a <object-type> or <value-type> node and will affect fields for this type.
<modify-field name="..." write="true | false" (optional) read="true | false" (optional) />
|name||The name of the field|
|write||Specifies if the field is writable in Java, enabled by default.|
|read||Specifies if the field is readable in Java, enabled by default.|
The function modification nodes are specified as children of a <object-type> or <value-type> node and will affect functions for this type. The <remove>, <access>, <rename>, <inject-code> nodes are used to specify the details of the modification.
<modify-function class="shell" (optional) signature="..." >
|class||Specifies in which part of the generated code the modification should apply. This is only relevant for code injections, otherwise leave out. shell: Virtual functions are reimplemented in a special subclass, called the shell class. Specifying the "shell" value for the class attribute will inject code into this reimplemented function.|
|signature||normalized C++ signature, excluding return value, including potential 'const'|
The remove node can be specified as a child of a <modify-function> node and will remove this function from the generated code.
<modify-function ...> <remove /> </modify-function>
The change access node can be specified as a child of a <modify-function> node and will change the access rights of this function in java.
<modify-function ...> <access modifier="public | protected | private"/> </modify-function>
The rename node can be specified as child of a <modify-function> node and will change the name of that function.
<modify-...> >rename to="..." /> </modify-...>
|to||The new name of the field or function.|
Value types are required to have a copy constructor because of their use pattern in the generated code, but not all classes have this. In these cases we specify a custom constructor that provides the code for making a copy of the object. A custom constructor has a signature like this:
T *customConstructor(T *copy);
The custon constructor nodes can be specified as a child of <value-type> nodes.
<custom-constructor> // code for custom constructor </custom-constructor>
When a custom constructor is provided we are most likely required to clean up the memory allocated in the custom construcotr. This is done in the custom destructor. The custom destructor has the following signature:
void customDestructor(T *copy);
<custom-destructor> // code for custom destructor </custom-destructor>
By default, the generator assumes that for each type, such as QPainter, there exists a globally accessible header accessible with "#include <QPainter>". If this is not the case it is possible to rename the include with with an include node. The include node can be specified as a child of the <primitive-type>, <value-type> or <object-type> nodes.
<...-type> <include file-name="..." location="global | local"/> </...-type>
It is some times required to include extra files in the generated C++ code to make sure that the generated code compiles. The <extra-includes> node can be specified as a child of the <value-type> or <object-type> nodes. A list of <include> nodes is specified inside the <extra-includes> node.
<extra-includes> <include file-name="..." location="global | local"/> </extra-includes>
|file-name||The file to include, such as "QStringList".|
|location||Where the file is located. global: The file is in located $INCLUDEPATH and will be included using #include <...> local: The file is in local directory and will be included using: #include "..."|
Code injections can be inserted to an <object-type>, <value-type> or a <modify-function> node.
<inject-code class="java | native | shell | shell-declaration | shell-definition" position="beginning | end" > // the code </inject-code>
|java||Code inserted into the java source code on the class level, making it possible to declare variables and functions native:|
|shell||Applicable to modify-function nodes of class="shell". Code is injected into shell function.|
position attribute: beginning: (the default), code is inserted at the beginning of the function. end: code is inserted at the end of the function
Argument mapping can be inserted into code injections to map an argument name to the argument name actually used in the generated code.
<argument-map position="numeric value" meta-name="string value" >
|position||An index, starting at 1, indicating the argument foposition which this argument map applies.|
|meta-name||The name used within the code injection to adress the argument at the given position|
The generator will generate several warnings, many of which can be determined as irrelevant by the user. It is then possible to suppress warnings, using the <suppress-warning> node which can be specified as a child of the typesystem node.
<suppress-warning text="..." >
|text||The warning text to suppress.|