diff options
author | Hugo Lima <hugo.lima@openbossa.org> | 2009-10-17 13:41:44 -0300 |
---|---|---|
committer | Hugo Lima <hugo.lima@openbossa.org> | 2009-10-17 13:41:44 -0300 |
commit | 51168e70b530c6920411680d5e6dde7aeaba164c (patch) | |
tree | 96d90b12ee2115030d7d86724e703ad612b595e3 /doc/typesystem_specifying_types.rst | |
parent | 705b3f37e76b59d020d24b76600a8b21d319326d (diff) |
- Typesystem documentation broken in smaller parts, so it's more redable now (IMO).
- Added cross referencing for nodes cited along the documentation.
- Added documentation for the new and not implemented yet, add-function tag.
Diffstat (limited to 'doc/typesystem_specifying_types.rst')
-rw-r--r-- | doc/typesystem_specifying_types.rst | 224 |
1 files changed, 224 insertions, 0 deletions
diff --git a/doc/typesystem_specifying_types.rst b/doc/typesystem_specifying_types.rst new file mode 100644 index 000000000..9535a6aee --- /dev/null +++ b/doc/typesystem_specifying_types.rst @@ -0,0 +1,224 @@ +Specifying Types +---------------- + +.. _typesystem: + +typesystem +^^^^^^^^^^ + + This is the root node containing all the type system information. It can + have a number of attributes, described below. + + .. code-block:: xml + + <typesystem package="..." default-superclass="..."> + </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". + +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. + + .. code-block:: xml + + <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. + + .. code-block:: xml + + <typesystem> + <rejection class="..." + function-name="..." + 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 \*. You can use an empty class field + to denote a global function. + + +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. + + .. code-block:: xml + + <typesystem> + <primitive-type name="..." + target-name="..." + preferred-conversion="yes | no" /> + </typesystem> + + The **name** attribute is the name of the primitive in C++, the optimal + **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. + + 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". + +.. _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). + + .. code-block:: xml + + <typesystem> + <namespace-type name="..." + package="..." /> + </typesystem> + + The **name** attribute is the name of the namespace, e.g., "Qt". The **package** + attribute can be used to override the package of the type system. + +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="..." + flags="yes | no" + lower-bound="..." + upper-bound="..." + force-integer="yes | no" + extensible="yes | no" /> + </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*). + + +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. + + .. code-block:: xml + + <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: + +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="..." + copyable="yes | no" + hash-function="..." /> + </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. + + +.. _object-type: + +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 :ref:`typesystem` node. + + .. code-block:: xml + + <typesystem> + <object-type name="..." + copyable="yes | no" + hash-function="..." /> + </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 + :ref:`value-type`. + + +interface-type +^^^^^^^^^^^^^^ + + The interface-type node indicates that the given class is replaced by an + interface pattern when mapping from C++ to the target language. Using the + interface-type node implicitly makes the given type an :ref:`object type`. + + .. code-block:: xml + + <typesystem> + <interface-type name="..." + package ="..." + default-superclass ="..." /> + </typesystem> + + The **name** attribute is the fully qualified C++ class name. The *optional* + **package** attribute can be used to override the package of the type system. + If there is no C++ base class, the *optional* **default-superclass** attribute + can be used to specify a superclass in the generated target language API, for + the given class. |