diff options
author | Marcelo Lira <marcelo.lira@openbossa.org> | 2009-11-13 19:04:38 -0300 |
---|---|---|
committer | Marcelo Lira <marcelo.lira@openbossa.org> | 2009-11-13 19:04:38 -0300 |
commit | f659460ba56014b5e7d20a0f3d50b53619132add (patch) | |
tree | 8e83fa6f0709c20be3ee5ad2c1b21d99887a9987 /doc/codeinjectionsemantics.rst | |
parent | cfae5701b16e057c992f0fadc7faf20dd3e09388 (diff) |
updated code injection semantics documentation with guidelines on
how to call the wrapped C++ method/function
Diffstat (limited to 'doc/codeinjectionsemantics.rst')
-rw-r--r-- | doc/codeinjectionsemantics.rst | 43 |
1 files changed, 39 insertions, 4 deletions
diff --git a/doc/codeinjectionsemantics.rst b/doc/codeinjectionsemantics.rst index 15ba426ca..e1891188c 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 ==================================== |