Manipulating Object and Value Types¶
The code can be embedded into XML (be careful to use the correct XML entities for characters like ‘<’, ‘>’, ‘&’):<value-type> <inject-code class="native | target | target-declaration" position="beginning | end" since="..."> // the code </inject-code> </value-type>
or obtained from an external file:<value-type> <inject-code class="native | target | target-declaration" position="beginning | end" since="..." file="external_source.cpp" snippet="label"/> </value-type>
classattribute specifies which module of the generated code that will be affected by the code injection. The
classattribute accepts the following values:
native: The c++ code
target: The binding code
target-declaration: The code will be injected into the generated header file containing the c++ wrapper class definition.
file: The file name
snippet: The snippet label (optional)
positionattribute is set to beginning (the default), the code is inserted at the beginning of the function. If it is set to end, the code is inserted at the end of the function.
sinceattribute specify the API version where this code was injected.
snippetlabel is given, the code between annotations of the form// @snippet label ... // @snippet label
will be extracted.
<object-type> <modify-field name="..." write="true | false" read="true | false" /> </object-type>
nameattribute is the name of the field, the optional
readattributes specify the field’s access privileges in the target language API (both are set to true by default). The
removeattribute is an optional attribute, which can mark the field to be discarded on generation; it has the same purpose of the deprecated tag remove.
The modify-function node allows you to modify a given C++ function when mapping it onto the target language, and it is a child of an object-type or a value-type node. Use the modify-argument node to specify which argument the modification affects.<object-type> <modify-function signature="..." since="..." remove="all | c++" access="public | private | protected" allow-thread="true | auto | false" exception-handling="off | auto-off | auto-on | on" rename="..." /> </object-type>
signatureattribute is a normalized C++ signature, excluding return values but including potential const declarations.
sinceattribute specify the API version when this function was modified.
allow-threadattribute specifies whether a function should be wrapped into
Py_END_ALLOW_THREADS, that is, temporarily release the GIL (global interpreter lock). Doing so is required for any thread-related function (wait operations), functions that might call a virtual function (potentially reimplemented in Python), and recommended for lengthy I/O operations or similar. It has performance costs, though. The value
automeans that it will be turned off for functions for which it is deemed to be safe, for example, simple getters. The attribute defaults to
exception-handlingattribute specifies whether to generate exception handling code (nest the function call into try / catch statements). It accepts the following values:
no, false: Do not generate exception handling code
auto-off: Generate exception handling code for functions declaring a non-empty
auto-on: Generate exception handling code unless function declares
yes, true: Always generate exception handling code
The add-function node allows you to add a given function onto the target language, and it is a child of an object-type or value-type nodes if the function is supposed to be a method, or namespace-type and Including Snippets if the function is supposed to be a function inside a namespace or a global function.
Typically when adding a function some code must be injected to provide the function logic. This can be done using the inject-code node.<object-type> <add-function signature="..." return-type="..." access="public | protected" static="yes | no" since="..."/> </object-type>
return-typeattribute defaults to void, the
accessto public and the
staticone to no.
sinceattribute specify the API version when this function was added.
Within the signature, names for the function parameters can be specified by enclosing them within the delimiter @:void foo(int @parameter1@,float)
The conversion-rule node allows you to write customized code to convert the given argument between the target language and C++, and is a child of the value-type, object-type, primitive-type and container-type nodes.
The code pointed by the file attribute is very tied to the generator using APIExtractor, so it don’t follow any rules, but the generator rules..<value-type name="Foo"> <convertion-rule file="my_converter_implementation.h" since="..."/> </value-type>
sinceattribute specify the API version when this conversion rule became valid.
You can also use the conversion-rule node to specify how the conversion of a single function argument should be done in a function.
snippetattributes are also supported (see inject-code nodes).
© 2020 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.