[gtkmm-documentation] Wrapping Section: Describe gmmproc's new parameter processing caps.

[José Alburquerque <jaalburqu src gnome org>]

commit 1d46fa9fbe20de7bcaefaf294dd5ff26f6092d46
Author: José Alburquerque <jaalburqu svn gnome org>
Date:   Sun Jun 12 19:06:56 2011 -0400

    Wrapping Section: Describe gmmproc's new parameter processing caps.
    
    	* docs/tutorial/C/gtkmm-tutorial-in.xml: Describe gmmproc's new
    	capabilities to allow optional parameters, reorder the parameters and
    	include optional output parameters when wrapping constructors and
    	methods.
    
    	Bug #651523.

 ChangeLog                             |   11 +++
 docs/tutorial/C/gtkmm-tutorial-in.xml |  127 +++++++++++++++++++++++++++++++++
 2 files changed, 138 insertions(+), 0 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 1670cec..de70584 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2011-06-12  José Alburquerque  <jaalburqu svn gnome org>
+
+	Wrapping Section: Describe gmmproc's new parameter processing caps.
+
+	* docs/tutorial/C/gtkmm-tutorial-in.xml: Describe gmmproc's new
+	capabilities to allow optional parameters, reorder the parameters and
+	include optional output parameters when wrapping constructors and
+	methods.
+
+	Bug #651523.
+
 2011-06-04  Murray Cumming  <murrayc murrayc com>
 
 	Dialogs chapter: get_vbox() returns a Box, not a VBox.
diff --git a/docs/tutorial/C/gtkmm-tutorial-in.xml b/docs/tutorial/C/gtkmm-tutorial-in.xml
index 1c4c3e0..8b0738a 100644
--- a/docs/tutorial/C/gtkmm-tutorial-in.xml
+++ b/docs/tutorial/C/gtkmm-tutorial-in.xml
@@ -8506,6 +8506,35 @@ _CONVERSION(`const Glib::RefPtr&lt;Printer&gt;&amp;',`GtkPrinter*',__CONVERT_REF
 </para>
 </sect2>
 
+<sect2 id="gmmproc-m4-initializations">
+<title>m4 Initializations</title>
+<para>
+  Often when wrapping methods, it is desirable to store the return of the C
+  function in what is called an output parameter.  In this case, the C++ method
+  returns <type>void</type> but an output parameter in which to store the value
+  of the C function is included in the argument list of the C++ method.
+  gmmproc allows such functionality, but appropriate inizialization macros must
+  be included to tell gmmproc how to initialize the C++ parameter from the
+  return of the C function.
+</para>
+<para>
+  For example, if there was a C function that returned a
+  <type>GtkWidget*</type> and for some reason, instead of having the C++ method
+  also return the widget, it was desirable to have the C++ method place the
+  widget in a specified output parameter, an initialization macro such as the
+  following would be necessary:
+<programlisting>
+  _INITIALIZATION(`Gtk::Widget&amp;',`GtkWidget*',`$3 = Glib::wrap($4)')
+</programlisting>
+</para>
+
+<para>
+  <literal>$3</literal> will be replaced by the output parameter name of the
+  C++ method and <literal>$4</literal> will be replaced by the return of the C
+  function when this initialization is used by gmmproc.
+</para>
+</sect2>
+
 
 <sect2 id="gmmproc-class-macros">
 <title>Class macros</title>
@@ -8677,6 +8706,44 @@ public:
   constructor with the same argument types. It takes a C++ constructor
   signature, and a C function name.
 </para>
+<para>
+  When wrapping constructors, it is possible for gmmproc to generate
+  convenience overloads of the wrapped constructors if the C function has
+  parameters that are optional (ie. the C API allows null for those
+  parameters).  For instance, to specify if a parameter is optional, the
+  <function>_WRAP_CTOR()</function> macro would look something like the
+  following: 
+  <programlisting>
+    _WRAP_CTOR(ToolButton(Widget&amp; icon_widget, const Glib::ustring&amp; label{?}, gtk_tool_button_new)
+  </programlisting>
+  The <literal>{?}</literal> following the name of the
+  <parameter>label</parameter> parameter means that that parameter is optional.
+  In this case, gmmproc will generate an extra constructor without that
+  parameter.
+</para>
+<para>
+  It is also possible to have the order of the parameters of the constructor
+  different from that of the C function by using gmmproc's C++ to C parameter
+  mapping functionality.   Using this functionality, it is possible to map a
+  C++ parameter to a C paramter by specifying the C parameter name.  For
+  instance, assuming that the declaration of the
+  <function>gtk_tool_button_new()</function> function is the following:
+  <programlisting>
+    GtkToolItem* gtk_tool_button_new(GtkWidget* icon_widget, const gchar* label);
+  </programlisting>
+  The parameters of the wrapped constructor could be reordered using the
+  following:
+  <programlisting>
+    WRAP_CTOR(ToolButton(const Glib::ustring&amp; label{label}, Widget&amp; icon_widget{icon_widget}), gtk_tool_button_new)
+  </programlisting>
+  The <literal>{param_name}</literal> following each of the names of the
+  parameters tells gmmproc to map those C++ parameters to the C parameters with
+  the given names.  Since the C++ parameter names correspond to the C ones, the
+  above could be re-written as:
+  <programlisting>
+    WRAP_CTOR(ToolButton(const Glib::ustring&amp; label{.}, Widget&amp; icon_widget{.}), gtk_tool_button_new)
+  </programlisting>
+</para>
 </sect3>
 
 <sect3 id="gmmproc-ctor-manual">
@@ -8751,6 +8818,66 @@ _WRAP_METHOD(void set_text(const Glib::ustring&amp; text), gtk_entry_set_text)
     </varlistentry>
 </variablelist>
 </para>
+<para>
+  As with <function>_WRAP_CTOR()</function> it is possible to specify if there
+  are any optional parameters.  If that is the case, gmmproc will generate
+  convenience overload methods without those parameters.  For example:
+  <programlisting>
+    WRAP_METHOD(void get_preferred_size(Requisition&amp; minimum_size, Requisition&amp; natural_size{?}) const, gtk_widget_get_preferred_size)
+  </programlisting>
+  Would indicate that the <parameter>natural_size</parameter> is optional
+  because its name ends with <literal>{?}</literal>.  In this case, gmmproc
+  would generate a method overload without that parameter.
+</para>
+<para>
+  Also, as with <function>_WRAP_CTOR()</function>, it is also possible to
+  reorder the parameters of the C++ method by using gmmproc's C++ to C
+  parameter mapping functionality.  Using this functionality, it is possible to
+  map a C++ parameter to a C paramter by specifying the C parameter name.  For
+  example, if the <function>gtk_widget_set_device_events()</function>
+  declaration is the following:
+  <programlisting>
+    void gtk_widget_set_device_events(GtkWidget* widget, GdkDevice* device, GdkEventMask events);
+  </programlisting>
+  Something like the following would change the order of the parameters in the
+  C++ method:
+  <programlisting>
+    _WRAP_METHOD(void set_device_events(Gdk::EventMask events{events}, const Glib::RefPtr&lt;const Gdk::Device&gt;&amp; device{device}), gtk_widget_set_device_events)
+  </programlisting>
+  The <literal>{param_name}</literal> following each of the names of the
+  parameters tells gmmproc to map those C++ parameters to the C parameters with
+  the given names.  Since the C++ parameter names correspond to the C ones, the
+  above could be re-written as:
+  <programlisting>
+    _WRAP_METHOD(void set_device_events(Gdk::EventMask events{.}, const Glib::RefPtr&lt;const Gdk::Device&gt;&amp; device{.}), gtk_widget_set_device_events)
+  </programlisting>
+</para>
+<para>
+  With <function>_WRAP_METHOD()</function> it is also possible to include an
+  output parameter in the C++ method declaration in which the return of the C
+  function would be placed and to have the C++ method return <type>void</type>.
+  To do that, simply include the output parameter declaration in the C++ method
+  declaration appending a <literal>{RET}</literal> to the output parameter
+  name.  For example, if <function>gtk_widget_get_request_mode()</function> is
+  declared as the following:
+  <programlisting>
+    GtkSizeRequestMode gtk_widget_get_request_mode(GtkWidget* widget);
+  </programlisting>
+  And having the C++ method set an output parameter is desired instead of
+  returning a <type>SizeRequestMode</type>, something like the following could
+  be used:
+  <programlisting>
+    _WRAP_METHOD(void get_request_mode(SizeRequestMode&amp; mode{RET}) const, gtk_widget_get_request_mode)
+  </programlisting>
+  the <literal>{RET}</literal> appended to the name of the
+  <parameter>mode</parameter> output parameter tells gmmproc to place the
+  return of the C function in that output parameter.  In this case, however, a
+  necessary initialization macro like the following would also have to be
+  specified:
+  <programlisting>
+    _INITIALIZATION(`SizeRequestMode&amp;',`GtkSizeRequestMode',`$3 = (SizeRequestMode)($4)')
+  </programlisting>
+</para>
 <para>Though it's usually obvious what C++ types should be used in the C++ method, here are some hints:
 <itemizedlist>
     <listitem><para>Objects used via <classname>RefPtr</classname>: Pass the