The Typesystem


The Typesystem

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.

Typesystem files

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)
>
AttributeDescription
packageA string describing the package to be used, such as "com.trolltech.qt.core"
default-superclassThe complete className of the default baseclass of all objects in Java, such as "com.trolltech.qt.QtObject"

Multiple typesystems

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"
>
AttributeDescription
nameThe filename of the typesystem to load.
generateSpecifies 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.

Global Rejections

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)
>
AttributeDescription
classThe 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-nameThe name of the function to rejected. This attribute is optional.
field-nameThe name of the field to reject. This attribute is optional.

Primitives

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)
>
AttributeDescription
nameThe name of the primitive in C++, such as "char".
java-nameThe 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-nameThe 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-conversionWhen 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.

Namespaces

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="..."
>
AttributeDescription
nameThe name of the namespace, such as "Qt"

Enums

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)
>
AttributeDescription
nameThe fully qualified C++ name of the enum, such as "Qt::FillRule".
flagsIf this attribute is set the generator will expect there to exist a QFlags<T> for the enum type.

Value Types

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="..."
>
AttributeDescription
nameThe fully qualified C++ class name, such as "QMatrix" or "QPainterPath::Element".

Object Types

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)
>
AttributeDescription
namefully qualified C++ class name, such as "QPushButton".
memory-managedSpecifies 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.

Modifying Fields

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)
/>
AttributeDescription
nameThe name of the field
writeSpecifies if the field is writable in Java, enabled by default.
readSpecifies if the field is readable in Java, enabled by default.

Modifying Functions

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="..."
>
AttributeDescription
classSpecifies 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.
signaturenormalized C++ signature, excluding return value, including potential 'const'

Removing

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>

Change Access

-------------

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>

Renaming

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-...>
AttributeDescription
toThe new name of the field or function.

Custom Constructor

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>

Custom Destructor

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>

Includes

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>
AttributeDescription
file-nameThe file to include, such as "QStringList".
locationWhere 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

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>
AttributeDescription
class
javaCode inserted into the java source code on the class level, making it possible to declare variables and functions native:
shellApplicable to modify-function nodes of class="shell". Code is injected into shell function.
shell-declaration:
shell-definition:

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

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"
>
AttributeDescription
positionAn index, starting at 1, indicating the argument foposition which this argument map applies.
meta-nameThe name used within the code injection to adress the argument at the given position

Warnings

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="..."
>
AttributeDescription
textThe warning text to suppress.
This page was updated at 17.05.2016