GNOME.org
 

[gtkmm-documentation] Appendix G: Add a gmmproc parameter processing section.

commit e33e773a0ab672bf7ba41bdb4f2c6b08659ed6fd
Author: José Alburquerque <jaalburquerque gmail com>
Date:   Sun Jun 30 17:14:02 2013 -0400

    Appendix G: Add a gmmproc parameter processing section.
    
        * docs/tutorial/C/gtkmm-tutorial-in.xml: Add a separate section in the
        "The .hg and .ccg files" section of the wrapping appendix describing
        the different options available to process the parameters of method
        signatures in macros that process them because these options can be
        used in macros that process method signatures in general such as
        _WRAP_SIGNAL() and not just _WRAP_METHOD(), _WRAP_CTOR() and
        _WRAP_CREATE().  Remove the same explanations from the _WRAP_METHOD()
        and _WRAP_CTOR() documentation so that there is no duplication of
        documentation.

 docs/tutorial/C/gtkmm-tutorial-in.xml |  285 +++++++++++++++++----------------
 1 files changed, 145 insertions(+), 140 deletions(-)
---
diff --git a/docs/tutorial/C/gtkmm-tutorial-in.xml b/docs/tutorial/C/gtkmm-tutorial-in.xml
index 06800d2..511531b 100644
--- a/docs/tutorial/C/gtkmm-tutorial-in.xml
+++ b/docs/tutorial/C/gtkmm-tutorial-in.xml
@@ -9219,50 +9219,6 @@ public:
     </varlistentry>
   </variablelist>
 </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 parameter 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>
-<para>
-  This same optional parameter syntax and parameter reordering is available for
-  <function>_WRAP_CREATE()</function>.  Additional
-  <function>create()</function> overloads would be generated by gmmproc without
-  the specified optional parameters.
-</para>
 </sect3>
 
 <sect3 id="gmmproc-ctor-manual">
@@ -9375,102 +9331,6 @@ _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> 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 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 parameter 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>{OUT}</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{OUT}) const, gtk_widget_get_request_mode)
-</programlisting>
-  the <literal>{OUT}</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>
-  Which could also be written as:
-<programlisting>
-_INITIALIZATION(`SizeRequestMode&amp;',`GtkSizeRequestMode',`$3 = ($1)($4)')
-</programlisting>
-</para>
-<para>
-  <function>_WRAP_METHOD()</function> also supports setting C++ output
-  parameters from C output parameters if the C function being wrapped has any.
-  Suppose, for example, that we want to wrap the following C function that
-  returns a value in its C output parameter <parameter>rect</parameter>:
-  <programlisting>
-    gboolean gtk_icon_view_get_cell_rect(GtkIconView* icon_view, GtkTreePath*
-    path, GtkCellRenderer* cell, GdkRectangle* rect);
-  </programlisting>
-  To have <command>gmmproc</command> place the value returned in the C++
-  <parameter>rect</parameter> output parameter once the C function returns,
-  something like the following <function>_WRAP_METHOD()</function> directive
-  could be used:
-  <programlisting>
-    _WRAP_METHOD(bool get_cell_rect(const TreeModel::Path&amp; path, const
-    CellRenderer&amp; cell, Gdk::Rectangle&amp; rect{>>}) const,
-    gtk_icon_view_get_cell_rect)
-  </programlisting>
-  The <literal>{>>}</literal> following the <parameter>rect</parameter>
-  parameter name indicates that the C++ output parameter should be set from the
-  value returned in the C parameter from the C function.
-  <command>gmmproc</command> will generate a declaration of a temporary
-  variable in which to store the value of the C output parameter and a statement
-  that sets the C++ output parameter from the temporary variable.  In this case
-  it may be necessary to have an <function>_INITIALIZATION()</function>
-  describing how to set a <classname>Gdk::Rectangle&amp;</classname> from a
-  <classname>GdkRectangle*</classname> such as the following:
-  <programlisting>
-    _INITIALIZATION(`Gdk::Rectangle&amp;',`GdkRectangle', `$3 =
-    Glib::wrap(&amp;($4))')
-  </programlisting>
-</para>
 <para>Selecting which C++ types should be used is also important when wrapping
   C API.  Though it's usually obvious what C++ types should be used in the C++
   method, here are some hints:
@@ -9799,6 +9659,151 @@ _MEMBER_GET_GOBJECT(layout, layout, Pango::Layout, PangoLayout*)
   </para>
 </sect3>
 </sect2>
+
+<sect2 id="gmmproc-parameter-processing">
+  <title>gmmproc Parameter Processing</title>
+  <para><command>gmmproc</command> allows processing the parameters in a method
+    signature for the macros that process method signatures (like
+    <function>_WRAP_METHOD()</function> <function>_WRP_CTOR()</function> and
+    <function>_WRAP_CREATE()</function>) in a variety of ways:
+  </para>
+
+  <sect3 id="gmmproc-parameter-reordering">
+    <title>Parameter Reordering</title>
+    <para>
+      For all the macros that process method signatures, it is possible to
+      specify a different order for the C++ parameters than the existing order
+      in the C function, virtual function or signal.  For example, say that the
+      following C function were being wrapped as a C++ method for the
+      <classname>Gtk::Widget</classname> class:
+      <programlisting>
+        void gtk_widget_set_device_events(GtkWidget* widget, GdkDevice* device,
+        GdkEventMask events);
+      </programlisting>
+      However, changing the order of the C++ method's two parameters is
+      necessary.  Something like the following would wrap the function as C++
+      method with a different order for the two parameters:
+      <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>{c_param_name}</literal> following the method parameter
+      names tells <command>gmmproc</command> to map the C++ parameter to the
+      specified C parameter within the <literal>{}</literal>.  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>
+  </sect3>
+
+  <sect3 id="gmmproc-optional-parameter-processing">
+    <title>Optional Parameter Processing</title>
+    <para>
+      For all macros processing method signatures except
+      <function>_WRAP_SIGNAL()</function> and
+      <function>_WRAP_VFUNC()</function> it is also possible to make the
+      parameters optional so that extra C++ methods are generated without the
+      specified optional parameter.  For example, say that the following
+      <function>*_new()</function> function were being wrapped as a constructor
+      in the <classname>Gtk::ToolButton</classname> class:
+      <programlisting>
+        GtkToolItem* gtk_tool_button_new(GtkWidget* icon_widget, const gchar*
+        label);
+      </programlisting>
+      Also, say that the C API allowed NULL for the function's
+      <parameter>label</parameter> paramter so that that parameter is optional.
+      It would be possible to have <command>gmmproc</command> generate the
+      original constructor (with all the parameters) along with an additional
+      constructor without that optional parameter by appending a
+      <literal>{?}</literal> to the parameter name like so:
+      <programlisting>
+        _WRAP_CTOR(ToolButton(Widget&amp; icon_widget, const Glib::ustring&amp;
+        label{?}), gtk_tool_button_new)
+      </programlisting>
+      In this case, two constructors would be generated: One with the optional
+      parameter and one without it.
+    </para>
+  </sect3>
+
+  <sect3 id="gmmproc-output-parameters">
+    <title>Output Parameter Processing</title>
+    <para>
+      With <function>_WRAP_METHOD()</function> it is also possible for the
+      return of the wrapped C function (if it has one) to be placed in output
+      paramter of the C++ method instead of having the C++ method also return a
+      value like the C function does.  To do that, simply include the output
+      parameter declaration in the C++ method declaration appending a
+      <literal>{OUT}</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{OUT})
+        const, gtk_widget_get_request_mode)
+      </programlisting>
+      The <literal>{OUT}</literal> appended to the name of the
+      <parameter>mode</parameter> output parameter tells
+      <command>gmmproc</command> 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>
+      Which could also be written as:
+      <programlisting>
+        _INITIALIZATION(`SizeRequestMode&amp;',`GtkSizeRequestMode',`$3 =
+        ($1)($4)')
+      </programlisting>
+    </para>
+    <para>
+      <function>_WRAP_METHOD()</function> also supports setting C++ output
+      parameters from C output parameters if the C function being wrapped has
+      any.  Suppose, for example, that we want to wrap the following C function
+      that returns a value in its C output parameter
+      <parameter>rect</parameter>:
+      <programlisting>
+        gboolean gtk_icon_view_get_cell_rect(GtkIconView* icon_view,
+        GtkTreePath* path, GtkCellRenderer* cell, GdkRectangle* rect);
+      </programlisting>
+      To have <command>gmmproc</command> place the value returned in the C++
+      <parameter>rect</parameter> output parameter once the C function returns,
+      something like the following <function>_WRAP_METHOD()</function>
+      directive could be used:
+      <programlisting>
+        _WRAP_METHOD(bool get_cell_rect(const TreeModel::Path&amp; path, const
+        CellRenderer&amp; cell, Gdk::Rectangle&amp; rect{>>}) const,
+        gtk_icon_view_get_cell_rect)
+      </programlisting>
+      The <literal>{>>}</literal> following the <parameter>rect</parameter>
+      parameter name indicates that the C++ output parameter should be set from
+      the value returned in the C parameter from the C function.
+      <command>gmmproc</command> will generate a declaration of a temporary
+      variable in which to store the value of the C output parameter and a
+      statement that sets the C++ output parameter from the temporary variable.
+      In this case it may be necessary to have an
+      <function>_INITIALIZATION()</function> describing how to set a
+      <classname>Gdk::Rectangle&amp;</classname> from a
+      <classname>GdkRectangle*</classname> such as the following:
+      <programlisting>
+        _INITIALIZATION(`Gdk::Rectangle&amp;',`GdkRectangle', `$3 =
+        Glib::wrap(&amp;($4))')
+      </programlisting>
+    </para>
+  </sect3>
+
+</sect2>
+
 <sect2 id="gmmproc-basic-types">
   <title>Basic Types</title>
   <para>Some of the basic types that are used in C APIs have better alternatives
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]