diff options
Diffstat (limited to 'sources/shiboken2/doc/typesystem_arguments.rst')
| -rw-r--r-- | sources/shiboken2/doc/typesystem_arguments.rst | 206 |
1 files changed, 0 insertions, 206 deletions
diff --git a/sources/shiboken2/doc/typesystem_arguments.rst b/sources/shiboken2/doc/typesystem_arguments.rst deleted file mode 100644 index 28a5c80bc..000000000 --- a/sources/shiboken2/doc/typesystem_arguments.rst +++ /dev/null @@ -1,206 +0,0 @@ -.. _modifying-arguments: - -Modifying Arguments -------------------- - -.. _conversionrule: - -conversion-rule -^^^^^^^^^^^^^^^ - - The conversion-rule node allows you to write customized code to convert - the given argument between the target language and C++, and it is a child of the modify-argument node: - - .. code-block:: xml - - <modify-argument index="2"> - <!-- for the second argument of the function --> - <conversion-rule class="target | native"> - // the code - </conversion-rule> - </modify-argument> - - This node is typically used in combination with the replace-type and - remove-argument nodes. The given code is used instead of the generator's - conversion code. - - Writing %N in the code (where N is a number), will insert the name of the - nth argument. Alternatively, %in and %out which will be replaced with the - name of the conversion's input and output variable, respectively. Note the - output variable must be declared explicitly, for example: - - .. code-block:: xml - - <conversion-rule class="native"> - bool %out = (bool) %in; - </conversion-rule> - - .. note:: You can also use the conversion-rule node to specify :ref:`a conversion code which will be used instead of the generator's conversion code everywhere for a given type <conversion-rule-on-types>`. - -.. _remove-argument: - -remove-argument -^^^^^^^^^^^^^^^ - - The remove-argument node removes the given argument from the function's - signature, and it is a child of the modify-argument node. - - .. code-block:: xml - - <modify-argument> - <remove-argument /> - </modify-argument> - -.. _rename-to: - -rename to -^^^^^^^^^ - - The 'rename to' node is used to rename a argument and use this new name in the generated code. - - .. code-block:: xml - - <modify-argument> - <rename to='...' /> - </modify-argument> - -.. _remove-default-expression: - -remove-default-expression -^^^^^^^^^^^^^^^^^^^^^^^^^ - - The remove-default-expression node disables the use of the default expression - for the given argument, and it is a child of the modify-argument node. - - .. code-block:: xml - - <modify-argument...> - <remove-default-expression /> - </modify-argument> - -.. _replace-default-expression: - -replace-default-expression -^^^^^^^^^^^^^^^^^^^^^^^^^^ - - The replace-default-expression node replaces the specified argument with the - expression specified by the ``with`` attribute, and it is a child of the - modify-argument node. - - .. code-block:: xml - - <modify-argument> - <replace-default-expression with="..." /> - </modify-argument> - -.. _replace-type: - -replace-type -^^^^^^^^^^^^ - - The replace-type node replaces the type of the given argument to the one - specified by the ``modified-type`` attribute, and it is a child of the - modify-argument node. - - .. code-block:: xml - - <modify-argument> - <replace-type modified-type="..." /> - </modify-argument> - - If the new type is a class, the ``modified-type`` attribute must be set to - the fully qualified name (including name of the package as well as the class - name). - -.. _define-ownership: - -define-ownership -^^^^^^^^^^^^^^^^ - - The define-ownership tag indicates that the function changes the ownership - rules of the argument object. The ``class`` attribute specifies the class of - function where to inject the ownership altering code. The ``owner`` attribute - specifies the new ownership of the object. It accepts the following values: - - * target: the target language will assume full ownership of the object. - The native resources will be deleted when the target language - object is finalized. - * c++: The native code assumes full ownership of the object. The target - language object will not be garbage collected. - * default: The object will get default ownership, depending on how it - was created. - - .. code-block:: xml - - <modify-argument> - <define-ownership class="target | native" - owner="target | c++ | default" /> - </modify-argument> - -.. _reference-count: - -reference-count -^^^^^^^^^^^^^^^ - - The reference-count tag dictates how an argument should be handled by the - target language reference counting system (if there is any), it also indicates - the kind of relationship the class owning the function being modified has with - the argument. For instance, in a model/view relation a view receiving a model - as argument for a **setModel** method should increment the model's reference - counting, since the model should be kept alive as much as the view lives. - Remember that out hypothetical view could not become parent of the model, - since the said model could be used by other views as well. - The ``action`` attribute specifies what should be done to the argument - reference counting when the modified method is called. It accepts the - following values: - - * add: increments the argument reference counter. - * add-all: increments the reference counter for each item in a collection. - * remove: decrements the argument reference counter. - * set: will assign the argument to the variable containing the reference. - * ignore: does nothing with the argument reference counter - (sounds worthless, but could be used in situations - where the reference counter increase is mandatory - by default). - - .. code-block:: xml - - <modify-argument> - <reference-count action="add|add-all|remove|set|ignore" variable-name="..." /> - </modify-argument> - - - The variable-name attribute specifies the name used for the variable that - holds the reference(s). - -.. _replace-value: - -replace-value -^^^^^^^^^^^^^ - - The ``replace-value`` attribute lets you replace the return statement of a - function with a fixed string. This attribute can only be used for the - argument at ``index`` 0, which is always the function's return value. - - .. code-block:: xml - - <modify-argument index="0" replace-value="this"/> - -.. _parent: - -parent -^^^^^^ - - The parent node lets you define the argument parent which will - take ownership of argument and will destroy the C++ child object when the - parent is destroyed. - - .. code-block:: xml - - <modify-argument index="1"> - <parent index="this" action="add | remove" /> - </modify-argument> - - In the ``index`` argument you must specify the parent argument. The action - *add* creates a parent link between objects, while *remove* will undo the - parentage relationship. |