Specifying Types

Including Snippets

There might be repetitive XML code, for example function modifications that need to be done on classes that are not related by type inheritance. It is possible to split out such snippets and include them via an entity reference.

<typesystem>
    <object-type name="A">
        &common_function_modifications;
    </object-type>
    <object-type name="B">
        &common_function_modifications;
    </object-type>
</typesystem>

The entity name is interpreted as file name (with suffix xml) appended and resolved in the type system paths passed as command line argument.

Note that this is not a standard externally parsed entity due to the limitations of the underlying parser.

typesystem

This is the root node containing all the type system information. It can have a number of attributes, described below.

<typesystem package="..." default-superclass="..." allow-thread="..." exception-handling="...">
</typesystem>

The package attribute is a string describing the package to be used, e.g. “QtCore”. The optional default-superclass attribute is the canonical C++ base class name of all objects, e.g., “object”.

The optional attributes allow-thread and exception-handling specify the default handling for the corresponding function modification (see modify-function).

load-typesystem

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.

<typesystem>
    <load-typesystem name="..." generate="yes | no" />
</typesystem>

The name attribute is the filename of the typesystem to load, the generate 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.

Most libraries will be based on both the QtCore and QtGui modules, in which case code generation for these libraries will be disabled.

rejection

The rejection node rejects the given class, or the specified function or field, and it is a child of the typesystem node.

<typesystem>
    <rejection class="..."
        function-name="..."
        argument-type="..."
        field-name="..." />
</typesystem>

The class attribute is the C++ class name of the class to reject. Use the optional function-name, argument-type, or field-name attributes to reject a particular function, function with arguments of a particular type, or a field. Note that the field-name and function-name/argument-type cannot be specified at the same time. To remove all occurrences of a given field or function, set the class attribute to *.

primitive-type

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.

<typesystem>
    <primitive-type name="..."
        since="..."
        until="..."
        target-name="..."
        default-constructor="..."
        preferred-conversion="yes | no" />
</typesystem>

The name attribute is the name of the primitive in C++, the optional, target-name 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 name attribute.

The optional since value is used to specify the API version in which the type was introduced.

Similarly, the optional until value can be used to specify the API version in which the type will be obsoleted.

If the optional preferred-conversion attribute is set to no, 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”.

The optional default-constructor specifies the minimal constructor call to build one value of the primitive-type. This is not needed when the primitive-type may be built with a default constructor (the one without arguments).

The optional preferred-conversion 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 preferred-conversion 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 ApiExtractor.

namespace-type

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).

<typesystem>
    <namespace-type name="..."
        visible="true | auto | false"
        generate="yes | no"
        generate-using="yes | no"
        package="..."
        since="..."
        revision="..." />
</typesystem>

The name attribute is the name of the namespace, e.g., “Qt”.

The optional visible attribute is used specify whether the namespace is visible in the target language name. Its default value is auto. It means that normal namespaces are visible, but inline namespaces (as introduced in C++ 11) will not be visible.

The detection of inline namespaces requires shiboken to be built using LLVM 9.0.

The optional generate is a legacy attribute. Specifying no is equivalent to visible=”false”.

The optional generate-using attribute specifies whether using namespace is generated into the wrapper code for classes within the namespace (default: yes). This ensures for example that not fully qualified enumeration values of default argument values compile. However, in rare cases, it might cause ambiguities and can then be turned off.

The package attribute can be used to override the package of the type system.

The optional since value is used to specify the API version of this type.

The revision attribute can be used to specify a revision for each type, easing the production of ABI compatible bindings.

enum-type

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.

<typesystem>
    <enum-type name="..."
        identified-by-value="..."
        class="yes | no"
        since="..."
        flags="yes | no"
        flags-revision="..."
        lower-bound="..."
        upper-bound="..."
        force-integer="yes | no"
        extensible="yes | no"
        revision="..." />
</typesystem>

The name attribute is the fully qualified C++ name of the enum (e.g.,”Qt::FillRule”). If the optional flags attribute is set to yes (the default is no), the generator will expect an existing QFlags<T> for the given enum type. The lower-bound and upper-bound 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 force-integer attribute is set to yes (the default is no), the generated target language code will use the target language integers instead of enums. And finally, the extensible attribute specifies whether the given enum can be extended with user values (the default is no).

The optional since value is used to specify the API version of this type.

The attribute identified-by-value helps to specify anonymous enums using the name of one of their values, which is unique for the anonymous enum scope. Notice that the enum-type tag can either have name or identified-by-value but not both.

The revision attribute can be used to specify a revision for each type, easing the production of ABI compatible bindings.

The flags-revision attribute has the same purposes of revision attribute but is used for the QFlag related to this enum.

reject-enum-value

The reject-enum-value node rejects the enum value specified by the name attribute, and it is a child of the enum-type node.

<enum-type>
    <reject-enum-value name="..."/>
</enum-type>

This node is used when a C++ enum implementation has several identical numeric values, some of which are typically obsolete.

value-type

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 Including Snippets node.

<typesystem>
    <value-type  name="..." since="..."
     copyable="yes | no"
     allow-thread="..."
     exception-handling="..."
     hash-function="..."
     stream="yes | no"
     default-constructor="..."
     revision="..." />
</typesystem>

The name attribute is the fully qualified C++ class name, such as “QMatrix” or “QPainterPath::Element”. The copyable attribute is used to force or not specify if this type is copyable. The optional hash-function attribute informs the function name of a hash function for the type.

The optional attribute stream specifies whether this type will be able to use externally defined operators, like QDataStream << and >>. If equals to yes, these operators will be called as normal methods within the current class.

The optional since value is used to specify the API version of this type.

The optional default-constructor specifies the minimal constructor call to build one instance of the value-type. This is not needed when the value-type may be built with a default constructor (the one without arguments). Usually a code generator may guess a minimal constructor for a value-type based on its constructor signatures, thus default-constructor is used only in very odd cases.

The revision attribute can be used to specify a revision for each type, easing the production of ABI compatible bindings.

The optional attributes allow-thread and exception-handling specify the default handling for the corresponding function modification (see modify-function).

object-type

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 Including Snippets node.

<typesystem>
    <object-type name="..."
     since="..."
     copyable="yes | no"
     allow-thread="..."
     exception-handling="..."
     hash-function="..."
     stream="yes | no"
     revision="..." />
</typesystem>

The name 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 copyable and hash-function attributes are the same as described for value-type.

The optional attribute stream specifies whether this type will be able to use externally defined operators, like QDataStream << and >>. If equals to yes, these operators will be called as normal methods within the current class.

The optional since value is used to specify the API version of this type.

The revision attribute can be used to specify a revision for each type, easing the production of ABI compatible bindings.

The optional attributes allow-thread and exception-handling specify the default handling for the corresponding function modification (see modify-function).

interface-type

This type is deprecated and no longer has any effect. Use object-type instead.

container-type

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 type.

<typesystem>
    <container-type name="..."
        since="..."
        type ="..." />
</typesystem>

The name attribute is the fully qualified C++ class name. The type attribute is used to indicate what conversion rule will be applied to the container. It can be: list, string-list, linked-list, vector, stack, queue, set, map, multi-map, hash, multi-hash or pair.

The optional since value is used to specify the API version of this container.

typedef-type

The typedef-type allows for specifying typedefs in the typesystem. They are mostly equivalent to spelling out the typedef in the included header, which is often complicated when trying to wrap libraries whose source code cannot be easily extended.

<typesystem>
    <typedef-type name="..."
        source="..."
        since="..." />
</typesystem>

The source attribute is the source. Example:

<namespace-type name='std'>
    <value-type name='optional' generate='no'/>\n"
</namespace-type>
<typedef-type name="IntOptional" source="std::optional&lt;int&gt;"/>

is equivalent to

typedef std::optional<int> IntOptional;

The optional since value is used to specify the API version of this type.

custom-type

The custom-type node simply makes the parser aware of the existence of a target language type, thus avoiding errors when trying to find a type used in function signatures and other places. The proper handling of the custom type is meant to be done by a generator using the APIExractor.

<typesystem>
    <custom-type name="..." />
</typesystem>

The name attribute is the name of the custom type, e.g., “PyObject”.

smart-pointer-type

The smart pointer type node indicates that the given class is a smart pointer and requires inserting calls to getter to access the pointeee. Currently, only the type shared is supported and the usage is limited to function return values. ref-count-method specifies the name of the method used to do reference counting.

The optional attribute instantiations specifies for which instantiations of the smart pointer wrappers will be generated (comma-separated list). By default, this will happen for all instantiations found by code parsing. This might be a problem when linking different modules, since wrappers for the same instantiation might be generated into different modules, which then clash. Providing an instantiations list makes it possible to specify which wrappers will be generated into specific modules.

<typesystem>
    <smart-pointer-type name="..."
        since="..."
        type="..."
        getter="..."
        ref-count-method="..."
        instantiations="..."/>
    </typesystem>

function

The function node indicates that the given C++ global function is mapped onto the target language.

<typesystem>
    <function signature="..." rename="..." since="..."/>
</typesystem>

This tag has some limitations, it doesn’t support function modifications, besides you can’t add a function overload using add-function tag to an existent function. These limitation will be addressed in future versions of ApiExtractor.

The function tag has two optional attributes: since, whose value is used to specify the API version of this function, and rename, to modify the function name.

system-include

The optional system-include specifies the name of a system include file or a system include path (indicated by a trailing slash) to be parsed. Normally, include files considered to be system include files are skipped by the C++ code parser. Its primary use case is exposing classes from the STL library.

<typesystem>
    <system-include file-name="memory"/>
    <system-include file-name="/usr/include/Qt/"/>
</typesystem>