diff options
Diffstat (limited to 'sources/shiboken6/doc/typesystem_specifying_types.rst')
| -rw-r--r-- | sources/shiboken6/doc/typesystem_specifying_types.rst | 1066 |
1 files changed, 705 insertions, 361 deletions
diff --git a/sources/shiboken6/doc/typesystem_specifying_types.rst b/sources/shiboken6/doc/typesystem_specifying_types.rst index b299c94ee..f65b79bb4 100644 --- a/sources/shiboken6/doc/typesystem_specifying_types.rst +++ b/sources/shiboken6/doc/typesystem_specifying_types.rst @@ -1,8 +1,6 @@ Specifying Types ---------------- -.. _typesystem: - Including Snippets ^^^^^^^^^^^^^^^^^^ @@ -27,517 +25,863 @@ 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: + typesystem ^^^^^^^^^^ - This is the root node containing all the type system information. It can - have a number of attributes, described below. +This is the root node containing all the type system information. +It may contain :ref:`add-function`, :ref:`container-type`, +:ref:`custom-type`, :ref:`enum-type`, :ref:`extra-includes`, :ref:`function`, +:ref:`load-typesystem`, :ref:`namespace`, :ref:`object-type`, +:ref:`opaque-container`, +:ref:`primitive-type`, :ref:`rejection`, :ref:`smart-pointer-type`, +:ref:`suppress-warning`, :ref:`template`, :ref:`system_include`, +:ref:`typedef-type` or :ref:`value-type` child nodes. - .. code-block:: xml +It can have a number of attributes, described below. - <typesystem package="..." default-superclass="..." allow-thread="..." - exception-handling="..." snake-case="yes | no | both" > - </typesystem> +.. code-block:: xml + + <typesystem package="..." + submodule-of="..." + allow-thread="..." + exception-handling="..." + snake-case="yes | no | both" + namespace-begin="..." + namespace-end="..." > + </typesystem> + +The **package** attribute is a string describing the package to be used, +e.g. "QtCore". + +The *optional* **submodule-of** attribute specifies the name of a module to +which the module is added as a sub-module. This requires adapting the +installation directory of the module accordingly. - 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 :ref:`modify-function`). - The *optional* attributes **allow-thread** and **exception-handling** - specify the default handling for the corresponding function modification - (see :ref:`modify-function`). +The *optional* **snake-case** attribute specifies whether function +and field names will be automatically changed to the snake case +style that is common in Python (for example, ``snakeCase`` will be +changed to ``snake_case``). - The *optional* **snake-case** attribute specifies whether function - and field names will be automatically changed to the snake case - style that is common in Python (for example, ``snakeCase`` will be - changed to ``snake_case``). +The value ``both`` means that the function or field will be exposed +under both its original name and the snake case version. There are +limitations to this though: - The value ``both`` means that the function or field will be exposed - under both its original name and the snake case version. There are - limitations to this though: +- When overriding a virtual function of a C++ class in Python, + the snake case name must be used. - - When overriding a virtual function of a C++ class in Python, - the snake case name must be used. +- When static and non-static overloads of a class member function + exist (as is the case for example for ``QFileInfo::exists()``), + the snake case name must be used. - - When static and non-static overloads of a class member function - exist (as is the case for example for ``QFileInfo::exists()``), - the snake case name must be used. +The *optional* **namespace-begin** and **namespace-end** attributes will be +generated around the forward declarations in the module header. This is +intended for libraries which can optionally use inline namespaces +to allow for linking several versions of them together. +For example, for *Qt*, one would specify ``QT_BEGIN_NAMESPACE``, +``QT_END_NAMESPACE``, respectively. + +.. _load-typesystem: 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. +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 :ref:`typesystem` node. - .. code-block:: xml +.. code-block:: xml - <typesystem> - <load-typesystem name="..." generate="yes | no" /> - </typesystem> + <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. +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. +Most libraries will be based on both the QtCore and QtGui modules, in which +case code generation for these libraries will be disabled. +.. _rejection: rejection ^^^^^^^^^ - The rejection node rejects the given class, or the specified function or - field, and it is a child of the typesystem node. +The ``rejection`` node rejects the given class, or the specified function +or field, and it is a child of the :ref:`typesystem` node. - .. code-block:: xml +.. code-block:: xml - <typesystem> - <rejection class="..." - function-name="..." - field-name="..." /> - </typesystem> + <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** or **field-name** attributes to reject a particular - function or field. Note that the **field-name** and **function-name** cannot - be specified at the same time. To remove all occurrences of a given field or - function, set the class attribute to \*. +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: 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. +The ``primitive-type`` node describes how a primitive type is mapped from C++ to +the target language, and is a child of the :ref:`typesystem` node. It may +contain :ref:`conversion-rule` child nodes. Note that most primitives are +already specified in the QtCore typesystem (see :ref:`primitive-cpp-types`). - .. code-block:: xml +.. code-block:: xml - <typesystem> - <primitive-type name="..." - since="..." - until="..." - target-name="..." - default-constructor="..." - preferred-conversion="yes | no" /> - view-on="..." - </typesystem> + <typesystem> + <primitive-type name="..." + since="..." + until="..." + target-lang-api-name="..." + default-constructor="..." + preferred-conversion="yes | no" + view-on="..." /> + </typesystem> + +The **name** attribute is the name of the primitive in C++. + +The optional **target-lang-api-name** attribute is the name of the +primitive type in the target language, defaulting to 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 **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*. - - The *optional* **view-on** attribute specifies that the type is a view - class like std::string_view or QStringView which has a constructor - accepting another type like std::string or QString. Since typically - no values can be assigned to view classes, no target-to-native conversion - can be generated for them. Instead, an instance of the viewed class should - be instantiated and passed to functions using the view class - for argument types. +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*. + +The *optional* **view-on** attribute specifies that the type is a view +class like std::string_view or QStringView which has a constructor +accepting another type like std::string or QString. Since typically +no values can be assigned to view classes, no target-to-native conversion +can be generated for them. Instead, an instance of the viewed class should +be instantiated and passed to functions using the view class +for argument types. + +See :ref:`predefined_templates` for built-in templates for standard type +conversion rules. .. _namespace: 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). +The ``namespace-type`` node maps the given C++ namespace to the target +language, and it is a child of the :ref:`typesystem` node or other +``namespace-type`` nodes. It may contain :ref:`add-function`, +:ref:`declare-function`, :ref:`enum-type`, :ref:`extra-includes`, +:ref:`include-element`, :ref:`modify-function`, ``namespace-type``, +:ref:`object-type`, :ref:`smart-pointer-type`, :ref:`typedef-type` or :ref:`value-type` +child nodes. - .. code-block:: xml +.. code-block:: xml - <typesystem> - <namespace-type name="..." - visible="true | auto | false" - generate="yes | no" - generate-using="yes | no" - package="..." - since="..." - revision="..." /> - </typesystem> + <typesystem> + <namespace-type name="..." + visible="true | auto | false" + generate="yes | no" + generate-using="yes | no" + package="..." + since="..." + extends = "..." + files = "..." + 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 **name** attribute is the name of the namespace, e.g., "Qt". +The detection of inline namespaces requires shiboken to be built +using LLVM 9.0. - 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 *optional* **generate** is a legacy attribute. Specifying +**no** is equivalent to **visible="false"**. - The detection of inline namespaces requires shiboken to be built - using LLVM 9.0. +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 *optional* **generate** is a legacy attribute. Specifying - **no** is equivalent to **visible="false"**. +The **package** attribute can be used to override the package of the type system. - 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 *optional* **since** value is used to specify the API version of this type. - The **package** attribute can be used to override the package of the type system. +The **revision** attribute can be used to specify a revision for each type, easing the +production of ABI compatible bindings. - The *optional* **since** value is used to specify the API version of this type. +The *optional* **extends** attribute specifies the module name where the given +namespace first occurs in case of a namespace spanning several modules. For +example, in Qt, the namespace ``Qt`` first occurs in the ``QtCore`` module and +is further populated in the ``QtGui`` module. ``QtGui.Qt`` will then be +generated extending ``QtCore.Qt`` if **extends** is specified. - The **revision** attribute can be used to specify a revision for each type, easing the - production of ABI compatible bindings. +The *optional* **file** attribute specifies a regular expression matching the +include files whose contents are to be associated with the current module in +case of a namespace spanning several modules. + +.. _enum-type: 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. - - .. code-block:: xml - - <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 ``enum-type`` node maps the given enum from C++ to the target language, +and it is a child of the :ref:`typesystem` node. Use +:ref:`reject-enum-value` child nodes to reject values. + +.. code-block:: xml + + <typesystem> + <enum-type name="..." + identified-by-value="..." + class="yes | no" + since="..." + flags="yes | no" + flags-revision="..." + cpp-type = "..." + doc-file = "..." + python-type = "IntEnum | IntFlag" + 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 **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* **python-type** attribute specifies the underlying +Python type. - The *optional* **since** value is used to specify the API version of this type. +The *optional* **cpp-type** attribute specifies a C++ to be used for +casting values. This can be useful for large values triggering MSVC +signedness issues. - 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 *optional* **doc-file** attribute specifies the base name of the C++ or +``.qdoc`` file indicated by ``\relates`` or ``\headerfile`` in ``qdoc``, to +which the documentation of the enumeration is to be added and displayed in the +case its a global enumeration. This attribute is for ``qdoc`` only. - The **revision** attribute can be used to specify a revision for each type, easing the - production of ABI compatible bindings. +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. +The **flags-revision** attribute has the same purposes of **revision** attribute but +is used for the QFlag related to this enum. +.. _reject-enum-value: 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. +The ``reject-enum-value`` node rejects the enum value specified by the +**name** attribute, and it is a child of the :ref:`enum-type` node. - .. code-block:: xml +.. code-block:: xml - <enum-type> - <reject-enum-value name="..."/> - </enum-type> + <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. +This node is used when a C++ enum implementation has several identical numeric +values, some of which are typically obsolete. .. _value-type: 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 :ref:`typesystem` node. - - .. code-block:: xml - - <typesystem> - <value-type name="..." since="..." - copyable="yes | no" - allow-thread="..." - disable-wrapper="yes | no" - exception-handling="..." - hash-function="..." - stream="yes | no" - default-constructor="..." - revision="..." - snake-case="yes | no | both" /> - </typesystem> +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 :ref:`typesystem` +node or other type nodes and may contain :ref:`add-function`, :ref:`add-pymethoddef`, +:ref:`configuration-element`, :ref:`declare-function`, :ref:`conversion-rule`, +:ref:`enum-type`, :ref:`extra-includes`, :ref:`include-element`, :ref:`modify-function`, +:ref:`object-type`, :ref:`smart-pointer-type`, :ref:`typedef-type` or further +``value-type`` child nodes. - 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. +.. code-block:: xml - 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. + <typesystem> + <value-type name="..." since="..." + copyable="yes | no" + allow-thread="..." + disable-wrapper="yes | no" + exception-handling="..." + generate-functions="..." + isNull ="yes | no" + operator-bool="yes | no" + hash-function="..." + private="yes | no" + qt-register-metatype = "yes | no | base" + stream="yes | no" + default-constructor="..." + revision="..." + snake-case="yes | no | both" /> + </typesystem> - The *optional* **since** value is used to specify the API version of this type. +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* **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 *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. - For the *optional* **disable-wrapper** attribute, see :ref:`object-type`. +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* **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 *optional* attributes **allow-thread** and **exception-handling** - specify the default handling for the corresponding function modification - (see :ref:`modify-function`). +For the *optional* **disable-wrapper** and **generate-functions** +attributes, see :ref:`object-type`. - The *optional* **snake-case** attribute allows for overriding the value - specified on the **typesystem** element. +For the *optional* **private** attribute, see :ref:`private_types`. -.. _object-type: +The *optional* **qt-register-metatype** attribute determines whether +a Qt meta type registration is generated for ``name``. By +default, this is generated for non-abstract, default-constructible +types for usage in signals and slots. +The value ``base`` means that the registration will be generated for the +class in question but not for inheriting classes. This allows for +restricting the registration to base classes of type hierarchies. -object-type -^^^^^^^^^^^ +The **revision** attribute can be used to specify a revision for each type, easing the +production of ABI compatible bindings. - 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 :ref:`typesystem` node. - - .. code-block:: xml - - <typesystem> - <object-type name="..." - since="..." - copyable="yes | no" - allow-thread="..." - disable-wrapper="yes | no" - exception-handling="..." - force-abstract="yes | no" - hash-function="..." - stream="yes | no" - revision="..." - snake-case="yes | no | both" /> - </typesystem> +The *optional* attributes **allow-thread** and **exception-handling** +specify the default handling for the corresponding function modification +(see :ref:`modify-function`). - 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 - :ref:`value-type`. +The *optional* **snake-case** attribute allows for overriding the value +specified on the **typesystem** element. - The *optional* **force-abstract** attribute forces the class to be - abstract, disabling its instantiation. The generator will normally detect - this automatically unless the class inherits from an abstract base class - that is not in the type system. +The *optional* **isNull** and **operator-bool** attributes can be used +to override the command line setting for generating bool casts +(see :ref:`bool-cast`). - The *optional* **disable-wrapper** attribute disables the generation of a - **C++ Wrapper** (see :ref:`codegenerationterminology`). This will - effectively disable overriding virtuals methods in Python for the class. - It can be used when the class cannot be instantiated from Python and - its virtual methods pose some problem for the code generator (by returning - references, or using a default value that cannot be generated for a - parameter, or similar). +.. _object-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. +object-type +^^^^^^^^^^^ - The *optional* **since** value is used to specify the API version of this 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 :ref:`typesystem` node +or other type nodes and may contain :ref:`add-function`, :ref:`add-pymethoddef`, +:ref:`configuration-element`, :ref:`declare-function`, :ref:`enum-type`, +:ref:`extra-includes`, :ref:`include-element`, :ref:`modify-function`, +``object-type``, :ref:`smart-pointer-type`, :ref:`typedef-type` or +:ref:`value-type` child nodes. - The **revision** attribute can be used to specify a revision for each type, easing the - production of ABI compatible bindings. +.. code-block:: xml - The *optional* attributes **allow-thread** and **exception-handling** - specify the default handling for the corresponding function modification - (see :ref:`modify-function`). + <typesystem> + <object-type name="..." + since="..." + copyable="yes | no" + allow-thread="..." + disable-wrapper="yes | no" + exception-handling="..." + generate-functions="..." + force-abstract="yes | no" + hash-function="..." + isNull ="yes | no" + operator-bool="yes | no" + parent-management="yes | no" + polymorphic-id-expression="..." + polymorphic-name-function="..." + polymorphic-base="yes | no" + private="yes | no" + qt-metaobject="yes | no" + qt-register-metatype = "yes | no | base" + stream="yes | no" + revision="..." + snake-case="yes | no | both" /> + </typesystem> - The *optional* **snake-case** attribute allows for overriding the value - specified on the **typesystem** element. +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 +:ref:`value-type`. + +The *optional* **force-abstract** attribute forces the class to be +abstract, disabling its instantiation. The generator will normally detect +this automatically unless the class inherits from an abstract base class +that is not in the type system. + +The *optional* **disable-wrapper** attribute disables the generation of a +**C++ Wrapper** (see :ref:`codegenerationterminology`). This will +effectively disable overriding virtuals methods in Python for the class. +It can be used when the class cannot be instantiated from Python and +its virtual methods pose some problem for the code generator (by returning +references, or using a default value that cannot be generated for a +parameter, or similar). + +For the *optional* **private** attribute, see :ref:`private_types`. + +The *optional* **qt-metaobject** attribute specifies whether +the special Qt virtual functions ``metaObject()``, +``metaCall()``, and ``metaCast()`` are generated. For classes +using dynamic meta objects, for example, ``QDBusInterface``, +it can be turned off. + +The *optional* **qt-register-metatype** attribute determines whether +a Qt meta type registration is generated for ``name *``. By +default, this is only generated for non-QObject types for usage +in signals and slots. +The value ``base`` means that the registration will be generated for the +class in question but not for inheriting classes. This allows for +restricting the registration to base classes of type hierarchies. + +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 :ref:`modify-function`). + +The *optional* **generate-functions** specifies a semicolon-separated +list of function names or minimal signatures to be generated. +This allows for restricting the functions for which bindings are generated. +This also applies to virtual functions; so, all abstract functions +need to be listed to prevent non-compiling code to be generated. +If nothing is specified, bindings for all suitable functions are +generated. Note that special functions (constructors, etc), +cannot be specified. + +The *optional* **snake-case** attribute allows for overriding the value +specified on the **typesystem** element. + +The *optional* **isNull** and **operator-bool** attributes can be used +to override the command line setting for generating bool casts +(see :ref:`bool-cast`). + +The *optional* **parent-management** attribute specifies that the class is +used for building object trees consisting of parents and children, for +example, user interfaces like the ``QWidget`` classes. For those classes, +the heuristics enabled by :ref:`ownership-parent-heuristics` and +:ref:`return-value-heuristics` are applied to automatically set parent +relationships. Compatibility note: In shiboken 6, when no class of the +type system has this attribute set, the heuristics will be applied +to all classes. In shiboken 7, it will be mandatory to set the +attribute. + +For the *optional* **polymorphic-id-expression**, **polymorphic-name-function** +and **polymorphic-base** attributes, see :ref:`typediscovery-attributes`. interface-type ^^^^^^^^^^^^^^ - This type is deprecated and no longer has any effect. Use object-type instead. +This type is deprecated and no longer has any effect. Use object-type instead. .. _container-type: 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**. +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**. +It is a child of the :ref:`typesystem` node and may contain +:ref:`conversion-rule` child nodes. - .. code-block:: xml +.. code-block:: xml + + <typesystem> + <container-type name="..." + since="..." + type ="..." + opaque-containers ="..." /> + </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 one of: *list*, *set*, *map*, *multi-map* or *pair*. + +Some types were deprecated in 6.2: *string-list*, *linked-list*, *vector*, +*stack* and *queue* are equivalent to *list*. *hash* and *multi-hash* +are equivalent to *map* and *multi-map*, respectively. + +The *optional* **opaque-containers** attribute specifies a semi-colon separated +list of mappings from instantiations to a type name for +:ref:`opaque-containers`: + +.. code-block:: xml + + <typesystem> + <container-type name="std::array" + opaque-containers ="int,3:IntArray3;float,4:FloatArray4"> - <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. - The *optional* **since** value is used to specify the API version of this container. +Some common standard containers are :ref:`built-in <builtin-cpp-container-types>`, +and there are also a number of useful +:ref:`predefined conversion templates <predefined_templates>`. + +.. _opaque-container: + +opaque-container +^^^^^^^^^^^^^^^^ + +The ``opaque-container`` element can be used to add further instantiations +of :ref:`opaque containers <opaque-containers>` to existing container types +(built-in or specified by :ref:`container-type` in included modules). +It is a child of the :ref:`typesystem` node. + +.. code-block:: xml + + <typesystem> + <oqaque-container name="..." opaque-containers ="..." /> + </typesystem> + +For the **name** and **opaque-containers** attributes, +see :ref:`container-type`. + +.. _typedef-type: 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. +The ``typedef-type`` node 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. +It is a child of the :ref:`typesystem` node or other type nodes. - .. code-block:: xml +.. code-block:: xml - <typesystem> - <typedef-type name="..." - source="..." - since="..." /> - </typesystem> + <typesystem> + <typedef-type name="..." + source="..." + since="..." /> + </typesystem> - The **source** attribute is the source. Example: +The **source** attribute is the source. Example: - .. code-block:: xml +.. code-block:: xml - <namespace-type name='std'> - <value-type name='optional' generate='no'/>\n" - </namespace-type> - <typedef-type name="IntOptional" source="std::optional<int>"/> + <namespace-type name='std'> + <value-type name='optional' generate='no'/>\n" + </namespace-type> + <typedef-type name="IntOptional" source="std::optional<int>"/> - is equivalent to +is equivalent to - .. code-block:: c++ +.. code-block:: c++ - typedef std::optional<int> IntOptional; + typedef std::optional<int> IntOptional; - The *optional* **since** value is used to specify the API version of this type. +The *optional* **since** value is used to specify the API version of this type. .. _custom-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. +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. +It is a child of the :ref:`typesystem` node. - .. code-block:: xml +.. code-block:: xml - <typesystem> - <custom-type name="..." /> - </typesystem> + <typesystem> + <custom-type name="..." + check-function="..." /> + </typesystem> - The **name** attribute is the name of the custom type, e.g., "PyObject". +The **name** attribute is the name of the custom type, e.g., "PyObject". + +The *optional* **check-function** attribute can be used to specify a +boolean check function that verifies if the PyObject is of the given type +in the function overload decisor. While shiboken knows common check +functions like ``PyLong_Check()`` or ``PyType_Check()``, it might be useful +to provide one for function arguments modified to be custom types +handled by injected code (see :ref:`replace-type`). + +See :ref:`cpython-types` for built-in types. .. _smart-pointer-type: 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. - - .. code-block:: xml - - <typesystem> - <smart-pointer-type name="..." - since="..." - type="..." - getter="..." - ref-count-method="..." - instantiations="..."/> - </typesystem> +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, the usage is limited to function return values. +**ref-count-method** specifies the name of the method used to do reference counting. +It is a child of the :ref:`typesystem` node or other type nodes. + +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. + +.. code-block:: xml + + <typesystem> + <smart-pointer-type name="..." + since="..." + type="shared | handle | value-handle | unique" + getter="..." + ref-count-method="..." + value-check-method="..." + null-check-method="..." + reset-method="..." + instantiations="..."/> + </typesystem> + + +The *optional* attribute **value-check-method** specifies a method +that can be used to check whether the pointer has a value. + +The *optional* attribute **null-check-method** specifies a method +that can be used to check for ``nullptr``. + +The *optional* attribute **reset-method** specifies a method +that can be used to clear the pointer. + +The *optional* instantiations attribute specifies a comma-separated +list of instantiation types. When left empty, all instantiations +found in the code will be generated. The type name might optionally +be followed an equal sign and the Python type name, for example +``instantiations="int=IntPtr,double=DoublePtr"``. +It is also possible to specify a namespace delimited by ``::``. + +The *optional* attribute **type** specifies the type: + +*shared* + A standard shared pointer. +*handle* + A basic pointer handle which has a getter function and an + ``operator->``. +*value-handle* + A handle which has a getter function returning a value + (``T`` instead of ``T *`` as for the other types). + It can be used for ``std::optional``. +*unique* + A standard, unique pointer (``std::unique_ptr``) or a similar + movable pointer. + Specifying the ``reset-method`` attribute is required for this work. + +The example below shows an entry for a ``std::shared_ptr``: + +.. code-block:: xml + + <system-include file-name="memory"/> + + <namespace-type name="std"> + <include file-name="memory" location="global"/> + <modify-function signature="^.*$" remove="all"/> + <enum-type name="pointer_safety"/> + <smart-pointer-type name="shared_ptr" type="shared" getter="get" + ref-count-method="use_count" + instantiations="Integer"> + <include file-name="memory" location="global"/> + </smart-pointer-type> + </namespace-type> + +If the smart pointer is the only relevant class from namespace ``std``, +it can also be hidden: + +.. code-block:: xml + + <namespace-type name="std" visible="no"> + <smart-pointer-type name="shared_ptr" type="shared" getter="get" + ref-count-method="use_count" + instantiations="Integer"> + <include file-name="memory" location="global"/> + </smart-pointer-type> + </namespace-type> + +First, shiboken is told to actually parse the system include files +containing the class definition using the :ref:`system_include` +element. For the ``namespace-type`` and ``smart-pointer-type``, the +standard include files are given to override the internal implementation +header ``shared_ptr.h``. +This creates some wrapper sources which need to be added to the +``CMakeLists.txt`` of the module. .. _function: function ^^^^^^^^ - The function node indicates that the given C++ global function is mapped onto - the target language. +The ``function`` node indicates that the given C++ global function is mapped +onto the target language. It is a child of the :ref:`typesystem` node +and may contain a :ref:`modify-function` child node. - .. code-block:: xml +.. code-block:: xml - <typesystem> - <function signature="..." rename="..." since="..." snake-case="yes | no | both" /> - </typesystem> + <typesystem> + <function signature="..." rename="..." since="..." + allow-thread="true | auto | false" + doc-file = "..." + exception-handling="off | auto-off | auto-on | on" + overload-number="number" + snake-case="yes | no | both" /> + </typesystem> - This tag has some limitations, it doesn't support function modifications, besides you - can't add a function overload using :ref:`add-function` tag to an existent function. - These limitation will be addressed in future versions of ApiExtractor. +There is a limitation; you cannot add a function overload using +the :ref:`add-function` tag to an existent function. - 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. +The *optional* **since** attribute is used to specify the API version in which +the function was introduced. - The *optional* **snake-case** attribute allows for overriding the value - specified on the **typesystem** element. +The *optional* **rename** attribute is used to modify the function name. + +The *optional* **doc-file** attribute specifies the base name of the C++ or +``.qdoc`` file indicated by ``\relates`` or ``\headerfile`` in ``qdoc``, to +which the documentation of the function is to be added and displayed in the +case its a global function. This attribute is for ``qdoc`` only. + +For the *optional* attributes **allow-thread**, **exception-handling**, +**overload-number** and **snake-case**, see :ref:`modify-function`. .. _system_include: 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. +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. +It is a child of the :ref:`typesystem` node. - .. code-block:: xml +.. code-block:: xml - <typesystem> - <system-include file-name="memory"/> - <system-include file-name="/usr/include/Qt/"/> - </typesystem> + <typesystem> + <system-include file-name="memory"/> + <system-include file-name="/usr/include/Qt/"/> + </typesystem> + +.. _conditional_processing: + +Conditional Processing +^^^^^^^^^^^^^^^^^^^^^^ + +Simple processing instructions are provided for including or excluding +sections depending on the presence of keywords. The syntax is: + +.. code-block:: xml + + <?if keyword !excluded_keyword ?> + ... + <?endif?> + +There are predefined keywords indicating the operating system (``windows``, +``unix`` and ``darwin``). + +The language level passed to the ``language-level`` command line option +is reflected as ``c++11``, ``c++14``, ``c++17`` or ``c++20``. + +The class names passed to the +:ref:`--drop-type-entries <drop-type-entries>` command line option +are also predefined, prefixed by ``no_``. This allows for example +for enclosing added functions referring to those classes within +``<?if !no_ClassName?>``, ``<?endif?>``. + +Other keywords can be specified using the +:ref:`--keywords <conditional_keywords>` command line option. + +.. _private_types: + +Defining Entities +^^^^^^^^^^^^^^^^^ + +It is possible to define entities using a simple processing instruction: + +.. code-block:: xml + + <?entity name value?> + <text>&name;</text> + +This allows for defining function signatures depending on platform +in conjunction with :ref:`conditional_processing`. + +Private Types +^^^^^^^^^^^^^ + +Marking :ref:`object-type` or :ref:`value-type` entries as private causes a +separate, private module header besides the public module header to be +generated for them. + +This can be used for classes that are not referenced in dependent modules +and helps to prevent the propagation of for example private C++ headers +required for them. |