summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorMarcelo Lira <marcelo.lira@openbossa.org>2009-11-13 19:04:38 -0300
committerMarcelo Lira <marcelo.lira@openbossa.org>2009-11-13 19:04:38 -0300
commitf659460ba56014b5e7d20a0f3d50b53619132add (patch)
tree8e83fa6f0709c20be3ee5ad2c1b21d99887a9987 /doc
parentcfae5701b16e057c992f0fadc7faf20dd3e09388 (diff)
downloadshiboken-f659460ba56014b5e7d20a0f3d50b53619132add.tar.gz
shiboken-f659460ba56014b5e7d20a0f3d50b53619132add.tar.xz
shiboken-f659460ba56014b5e7d20a0f3d50b53619132add.zip
updated code injection semantics documentation with guidelines on
how to call the wrapped C++ method/function
Diffstat (limited to 'doc')
-rw-r--r--doc/codeinjectionsemantics.rst43
1 files changed, 39 insertions, 4 deletions
diff --git a/doc/codeinjectionsemantics.rst b/doc/codeinjectionsemantics.rst
index 15ba426c..e1891188 100644
--- a/doc/codeinjectionsemantics.rst
+++ b/doc/codeinjectionsemantics.rst
@@ -123,16 +123,20 @@ Below is the example C++ class for whom wrapper code will be generated.
};
From the C++ class, |project| will generate a ``injectcode_wrapper.cpp`` file
-with the binding code. The next section will use a simplified version of its
-contents with the injection spots marked.
+with the binding code. The next section will use a simplified version of the
+generated wrapper code with the injection spots marked with comments.
-Noteworthy Situations
----------------------
+Noteworthy Cases
+----------------
The type system description system gives the binding developer a lot of
flexibility, which is power, which comes with responsibility. Some modifications
to the wrapped API will not be complete without some code injection.
+
+Removing arguments and setting a default values for them
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
A simple case is when a function have one argument removed, as when the C++
method ``METHOD(ARG)`` is modified to be used from Python as ``METHOD()``;
of course the binding developer must provide some guidelines to the generator
@@ -140,12 +144,43 @@ on what to do to call it. The most common solution is to remove the argument and
set a default value for it at the same time, so the original C++ method could be
called without problems.
+Removing arguments and calling the method with your own hands
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
If the argument is removed and no default value is provided, the generator will
not write any call to the method and expect the ``modify-function - target/beginning``
code injection to call the original C++ method on its own terms. If even this
custom code is not provided the generator will put an ``#error`` clause to
prevent compilation of erroneus binding code.
+Calling the method with your own hands always!
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If your custom code to be injected contains a call to the wrapped C++ method,
+it surely means that you don't want the generator to write another call to the
+same method. As expected |project| will detect the user written call on the code
+injection and will not write its own call, but for this to work properly the
+binding developer must use the template variable ``%FUNCTION_NAME`` instead
+of writing the actual name of the wrapped method/function.
+
+In other words, use
+
+ .. code-block:: xml
+
+ <inject-code class="target" position="beginning | end">
+ %CPPSELF.originalMethodName();
+ </inject-code>
+
+
+instead of
+
+
+ .. code-block:: xml
+
+ <inject-code class="target" position="beginning | end">
+ %CPPSELF.%FUNCTION_NAME();
+ </inject-code>
+
Code Injection for Functions/Methods
====================================