From f659460ba56014b5e7d20a0f3d50b53619132add Mon Sep 17 00:00:00 2001 From: Marcelo Lira Date: Fri, 13 Nov 2009 19:04:38 -0300 Subject: updated code injection semantics documentation with guidelines on how to call the wrapped C++ method/function --- doc/codeinjectionsemantics.rst | 43 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 39 insertions(+), 4 deletions(-) (limited to 'doc') 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 + + + %CPPSELF.originalMethodName(); + + + +instead of + + + .. code-block:: xml + + + %CPPSELF.%FUNCTION_NAME(); + + Code Injection for Functions/Methods ==================================== -- cgit v1.2.3