Les fichiers .hg et .ccg

Les fichiers sources .hg et .ccg ressemblent tout à fait aux fichiers sources .h et .cc du C++, mais il comportent des macros supplémentaires, telles que _CLASS_GOBJECT() et _WRAP_METHOD(), à partir desquelles gmmproc génére le code source C++ approprié, habituellement à la même position dans l'en-tête. Tout code source C++ sera copié mot pour mot dans le fichier .h ou .cc correspondant.

A .hg file will typically include some headers and then declare a class, using some macros to add API or behaviour to this class. For instance, gtkmm's button.hg looks roughly like this:

#include <gtkmm/bin.h>
#include <gtkmm/activatable.h>
_DEFS(gtkmm,gtk)
_PINCLUDE(gtkmm/private/bin_p.h)

namespace Gtk
{

class Button
  : public Bin,
    public Activatable
{
  _CLASS_GTKOBJECT(Button,GtkButton,GTK_BUTTON,Gtk::Bin,GtkBin)
  _IMPLEMENTS_INTERFACE(Activatable)
public:

  _CTOR_DEFAULT
  explicit Button(const Glib::ustring& label, bool mnemonic = false);

  _WRAP_METHOD(void set_label(const Glib::ustring& label), gtk_button_set_label)

  ...

  _WRAP_SIGNAL(void clicked(), "clicked")

  ...

  _WRAP_PROPERTY("label", Glib::ustring)
};

} // namespace Gtk

The macros in this example do the following:

_DEFS()

Specifies the destination directory for generated sources, and the name of the main .defs file that gmmproc should parse.

_PINCLUDE()

Tells gmmproc to include a header in the generated private/button_p.h file.

_CLASS_GTKOBJECT()

Tells gmmproc to add some typedefs, constructors, and standard methods to this class, as appropriate when wrapping a widget.

_IMPLEMENTS_INTERFACE()

Tells gmmproc to add initialization code for the interface.

_CTOR_DEFAULT

Add a default constructor.

_WRAP_METHOD(), _WRAP_SIGNAL(), and _WRAP_PROPERTY()

Add methods to wrap parts of the C API.

The .h and .cc files will be generated from the .hg and .ccg files by processing them with gmmproc like so, though this happens automatically when using the above build structure:

$ cd gtk/src
$ /usr/lib/glibmm-2.4/proc/gmmproc -I ../../tools/m4 --defs . button . ./../gtkmm

Notez que nous appelons gmmproc avec comme paramètre le chemin vers les fichiers .m4 convertis, le chemin vers les fichiers .defs, le nom du fichier .hg, le répertoire source et le répertoire destination.

Nous nous abstenons d'inclure le fichier d'en-tête C à partir de l'en-tête C++ pour éviter de polluer l'espace de noms global et pour éviter d'exporter des API publiques non nécessaires. Mais vous aurez besoin d'inclure les en-têtes C nécessaires à partir de votre fichier .ccg.

Les macros sont expliquées plus en détail dans les paragraphes suivants.

G.III.I. Conversions m4

The macros that you use in the .hg and .ccg files often need to know how to convert a C++ type to a C type, or vice-versa. gmmproc takes this information from an .m4 file in your tools/m4/ directory. This allows it to call a C function in the implementation of your C++ method, passing the appropriate parameters to that C functon. For instance, this tells gmmproc how to convert a GtkTreeView pointer to a Gtk::TreeView pointer:

_CONVERSION(`GtkTreeView*',`TreeView*',`Glib::wrap($3)')

$3 sera remplacé par le nom du paramètre lorsque cette conversion est utilisée par gmmproc.

Some extra macros make this easier and consistent. Look in gtkmm's .m4 files for examples. For instance:

_CONVERSION(`PrintSettings&',`GtkPrintSettings*',__FR2P)
_CONVERSION(`const PrintSettings&',`GtkPrintSettings*',__FCR2P)
_CONVERSION(`const Glib::RefPtr<Printer>&',`GtkPrinter*',__CONVERT_REFPTR_TO_P($3))

G.III.II. m4 Initializations

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 void 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 initialization macros must be included to tell gmmproc how to initialize the C++ parameter from the return of the C function.

For example, if there was a C function that returned a GtkWidget* 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:

_INITIALIZATION(`Gtk::Widget&',`GtkWidget*',`$3 = Glib::wrap($4)')

$3 will be replaced by the output parameter name of the C++ method and $4 will be replaced by the return of the C function when this initialization is used by gmmproc. For convenience, $1 will also be replaced by the C++ type without the ampersand (&) and $2 will be replaced by the C type.

G.III.III. Macros de classes

La macro de classe déclare la classe elle-même et ses relations avec le type C sous-jacent. Elle génère certains constructeurs internes, la variable membre gobject_, des définitions de types, les mécanismes d'accès aux gobj(), l'enregistrement du type et la fonction membre Glib::wrap(), entre autres choses.

Other macros, such as _WRAP_METHOD() and _WRAP_SIGNAL() may only be used after a call to a _CLASS_* macro.

G.III.III.I. _CLASS_GOBJECT

This macro declares a wrapper for a type that is derived from GObject, but whose wrapper is not derived from Gtk::Object.

_CLASS_GOBJECT( C++ class, C class, C casting macro, C++ base class, C base class )

For instance, from accelgroup.hg:

_CLASS_GOBJECT(AccelGroup, GtkAccelGroup, GTK_ACCEL_GROUP, Glib::Object, GObject)

G.III.III.II. _CLASS_GTKOBJECT

This macro declares a wrapper for a type whose wrapper is derived from Gtk::Object, such as a widget or dialog.

_CLASS_GTKOBJECT( C++ class, C class, C casting macro, C++ base class, C base class )

For instance, from button.hg:

_CLASS_GTKOBJECT(Button, GtkButton, GTK_BUTTON, Gtk::Bin, GtkBin)

You will typically use this macro when the class already derives from Gtk::Object. For instance, you will use it when wrapping a GTK+ Widget, because Gtk::Widget derives from Gtk::Object.

You might also derive non-widget classes from Gtk::Object so they can be used without Glib::RefPtr. For instance, they could then be instantiated with Gtk::manage() or on the stack as a member variable. This is convenient, but you should use this only when you are sure that true reference-counting is not needed. We consider it useful for widgets.

G.III.III.III. _CLASS_BOXEDTYPE

Cette macro déclare un habillage pour une structure non-GObject, enregistrée avec g_boxed_type_register_static().

_CLASS_BOXEDTYPE( C++ class, C class, new function, copy function, free function )

For instance, from Gdk::RGBA:

_CLASS_BOXEDTYPE(RGBA, GdkRGBA, NONE, gdk_rgba_copy, gdk_rgba_free)

G.III.III.IV. _CLASS_BOXEDTYPE_STATIC

Cette macro déclare un habillage pour une simple structure assignable comme un GdkRectangle. Elle est semblable à _CLASS_BOXEDTYPE, mais la structure C n'est pas allouée dynamiquement.

_CLASS_BOXEDTYPE_STATIC( C++ class, C class )

For instance, for Gdk::Rectangle:

_CLASS_BOXEDTYPE_STATIC(Rectangle, GdkRectangle)

G.III.III.V. _CLASS_OPAQUE_COPYABLE

Cette macro déclare un habillage pour une structure opaque possédant des fonctions de copie et de libération. Les fonctions new, copy et free seront utilisées pour instancier le constructeur par défaut, le constructeur de copie et le destructeur.

_CLASS_OPAQUE_COPYABLE( C++ class, C class, new function, copy function, free function )

For instance, from Glib::Checksum:

_CLASS_OPAQUE_COPYABLE(Checksum, GChecksum, NONE, g_checksum_copy, g_checksum_free)

G.III.III.VI. _CLASS_OPAQUE_REFCOUNTED

Cette macro déclare un habillage pour une structure opaque à décompte de références. L'habillage C++ ne peut pas être directement instancié et ne peut être utilisé qu'avec un pointeur intelligent Glib::RefPtr.

_CLASS_OPAQUE_REFCOUNTED( C++ class, C class, new function, ref function, unref function )

For instance, for Pango::Coverage:

_CLASS_OPAQUE_REFCOUNTED(Coverage, PangoCoverage, pango_coverage_new, pango_coverage_ref, pango_coverage_unref)

G.III.III.VII. _CLASS_GENERIC

Cette macro peut être utilisée pour habiller les structures n'entrant pas dans une catégorie particulière.

_CLASS_GENERIC( C++ class, C class )

For instance, for Pango::AttrIter:

_CLASS_GENERIC(AttrIter, PangoAttrIterator)

G.III.III.VIII. _CLASS_INTERFACE

This macro declares a wrapper for a type that is derived from GTypeInterface.

_CLASS_INTERFACE( C++ class, C class, C casting macro, C interface struct, Base C++ class (optional), Base C class (optional) )

For instance, from celleditable.hg:

_CLASS_INTERFACE(CellEditable, GtkCellEditable, GTK_CELL_EDITABLE, GtkCellEditableIface)

Two extra parameters are optional, for the case that the interface derives from another interface, which should be the case when the GInterface has another GInterface as a prerequisite. For instance, from loadableicon.hg:

_CLASS_INTERFACE(LoadableIcon, GLoadableIcon, G_LOADABLE_ICON, GLoadableIconIface, Icon, GIcon)

G.III.IV. Macros de constructeurs

Les macros _CTOR_DEFAULT() et _WRAP_CTOR() ajoutent des constructeurs, habillant les fonctions C *_new() spécifiées. Ces macros supposent que l'objet C a des propriétés de même nom que les paramètres de la fonction, ce qui est habituellement le cas ; ainsi il peut fournir les paramètres directement pour l'appel de g_object_new(). Ces constructeurs en réalité n'appellent jamais les fonctions C *_new(), car gtkmm doit en fait instancier des types GTypes dérivés et les fonctions C *_new() ne sont conçues que comme fonctions de commodité pour les programmeurs C.

When using _CLASS_GOBJECT(), the constructors should be protected (rather than public) and each constructor should have a corresponding _WRAP_CREATE() in the public section. This prevents the class from being instantiated without using a RefPtr. For instance:

class TextMark : public Glib::Object
{
  _CLASS_GOBJECT(TextMark, GtkTextMark, GTK_TEXT_MARK, Glib::Object, GObject)

protected:
  _WRAP_CTOR(TextMark(const Glib::ustring& name, bool left_gravity = true), gtk_text_mark_new)

public:
  _WRAP_CREATE(const Glib::ustring& name, bool left_gravity = true)

G.III.IV.I. _CTOR_DEFAULT

Cette macro crée un constructeur par défaut sans paramètre.

G.III.IV.II. _WRAP_CTOR

Cette macro crée un constructeur avec paramètres, équivalent à la fonction C *_new(). Elle n'appelle pas réellement la fonction *_new(), mais elle crée simplement un constructeur équivalent avec les mêmes types de paramètres. Elle prend en paramètres la signature d'un constructeur C++ et un nom de fonction C.

It also takes an optional extra argument:

errthrow

This tells gmmproc that the C *_new() has a final GError** parameter which should be ignored.

G.III.IV.III. Constructeurs codés à la main

When a constructor must be partly hand written because, for instance, the *_new() C function's parameters do not correspond directly to object properties, or because the *_new() C function does more than call g_object_new(), the _CONSTRUCT() macro may be used in the .ccg file to save some work. The _CONSTRUCT macro takes a series of property names and values. For instance, from button.ccg:

Button::Button(const Glib::ustring& label, bool mnemonic)
:
  _CONSTRUCT("label", label.c_str(), "use_underline", gboolean(mnemonic))
{}

G.III.V. Macros pour fonctions membres

G.III.V.I. _WRAP_METHOD

Cette macro génère une fonction membre C++ habillant une fonction C.

_WRAP_METHOD( C++ method signature, C function name)

For instance, from entry.hg:

_WRAP_METHOD(void set_text(const Glib::ustring& text), gtk_entry_set_text)

La fonction C (par exemple, gtk_entry_set_text) est décrite plus précisément dans les fichiers .defs et les fichiers convert*.m4 contiennent la conversion nécessaire des types de paramètres C++ vers les paramètres de type C. Cette macro génère également des commentaires pour la documentation doxygen à partir des fichiers *_docs.xml et *_docs_override.xml.

There are some optional extra arguments:

refreturn

Do an extra reference() on the return value, in case the C function does not provide a reference.

errthrow

Use the last GError** parameter of the C function to throw an exception.

deprecated

Puts the generated code in #ifdef blocks. Text about the deprecation can be specified as an optional parameter.

constversion

Just call the non-const version of the same function, instead of generating almost duplicate code.

ifdef

Puts the generated code in #ifdef blocks.

slot_name

Specifies the name of the slot parameter of the method, if it has one. This enables gmmproc to generate code to copy the slot and pass the copy on to the C function in its final gpointer user_data parameter. The slot_callback option must also be used to specify the name of the glue callback function to also pass on to the C function.

slot_callback

Used in conjunction with the slot_name option to specify the name of the glue callback function that handles extracting the slot and then calling it. The address of this callback is also passed on to the C function that the method wraps.

no_slot_copy

Tells gmmproc not to pass a copy of the slot to the C function, if the method has one. Instead the slot itself is passed. The slot parameter name and the glue callback function must have been specified with the slot_name and slot_callbback options respectively.

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:

  • Objects used via RefPtr: Pass the RefPtr as a const reference. For instance, const Glib::RefPtr<Gtk::FileFilter>& filter.
  • Const Objects used via RefPtr: If the object should not be changed by the function, then make sure that the object is const, even if the RefPtr is already const. For instance, const Glib::RefPtr<const Gtk::FileFilter>& filter.
  • Wrapping GList* and GSList* parameters: First, you need to discover what objects are contained in the list's data field for each item, usually by reading the documentation for the C function. The list can then be wrapped by a std::vector type. For instance, std::vector< Glib::RefPtr<Gdk::Pixbuf> >. You may need to define a Traits type to specify how the C and C++ types should be converted.
  • Wrapping GList* and GSList* return types: You must discover whether the caller should free the list and whether it should release the items in the list, again by reading the documentation of the C function. With this information you can choose the ownership (none, shallow or deep) for the m4 conversion rule, which you should probably put directly into the .hg file because the ownership depends on the function rather than the type. For instance:
    #m4 _CONVERSION(`GSList*',`std::vector<Widget*>',`Glib::SListHandler<Widget*>::slist_to_vector($3, Glib::OWNERSHIP_SHALLOW)')

G.III.V.II. _WRAP_METHOD_DOCS_ONLY

Cette macro est comparable à la macro _WRAP_METHOD(), mais elle ne génère la documentation que dans le cas d'une fonction membre C++ habillant une fonction C. Utilisez-la si vous devez coder à la main la fonction membre, mais vous voulez utiliser la documentation qui serait générée si la fonction membre était générée.

_WRAP_METHOD_DOCS_ONLY(C function name)

For instance, from container.hg:

_WRAP_METHOD_DOCS_ONLY(gtk_container_remove)

G.III.V.III. _IGNORE / _IGNORE_SIGNAL

gmmproc will warn you on stdout about functions and signals that you have forgotten to wrap, helping to ensure that you are wrapping the complete API. But if you don't want to wrap some functions or signals, or if you chose to hand-code some methods then you can use the _IGNORE() or _IGNORE_SIGNAL() macro to make gmmproc stop complaining.

_IGNORE(C function name 1, C function name2, etc)

_IGNORE_SIGNAL(C signal name 1, C signal name2, etc)

For instance, from buttonbox.hg:

_IGNORE(gtk_button_box_set_spacing, gtk_button_box_get_spacing)

G.III.V.IV. _WRAP_SIGNAL

Cette macro génère le signal C++ de style libsigc++ habillant un signal C GObject. Il génère en fait un mécanisme d'accès public, comme signal_clicked(), qui renvoie un objet mandataire. gmmproc utilise le fichier .defs pour découvrir le type des paramètres du C et les fichiers de conversion .m4 pour découvrir les types de conversion appropriés.

_WRAP_SIGNAL( C++ signal handler signature, C signal name)

For instance, from button.hg:

_WRAP_SIGNAL(void clicked(),"clicked")

Signals usually have function pointers in the GTK struct, with a corresponding enum value and a g_signal_new() in the .c file.

There are some optional extra arguments:

no_default_handler

Do not generate an on_something() virtual method to allow easy overriding of the default signal handler. Use this when adding a signal with a default signal handler would break the ABI by increasing the size of the class's virtual function table.

custom_default_handler

Generate a declaration of the on_something() virtual method in the .h file, but do not generate a definition in the .cc file. Use this when you must generate the definition by hand.

custom_c_callback

Do not generate a C callback function for the signal. Use this when you must generate the callback function by hand.

refreturn

Do an extra reference() on the return value of the on_something() virtual method, in case the C function does not provide a reference.

ifdef

Puts the generated code in #ifdef blocks.

G.III.V.V. _WRAP_PROPERTY

Cette macro génère une fonction membre C++ habillant une propriété d'un GObject C. Vous devez indiquer le nom de la propriété et le type C++ souhaité pour la propriété. gmmproc utilise le fichier .defs pour connaître le type C et les fichiers de conversion .m4 pour découvrir les types appropriés de conversion.

_WRAP_PROPERTY(C property name, C++ type)

For instance, from button.hg:

_WRAP_PROPERTY("label", Glib::ustring)

G.III.V.VI. _WRAP_VFUNC

This macro generates the C++ method to wrap a virtual C function.

_WRAP_VFUNC( C++ method signature, C function name)

For instance, from widget.hg:

_WRAP_VFUNC(SizeRequestMode get_request_mode() const, get_request_mode)

The C function (e.g. get_request_mode) is described more fully in the *_vfuncs.defs file, and the convert*.m4 files contain the necessary conversion from the C++ parameter type to the C parameter type.

There are some optional extra arguments:

refreturn

Do an extra reference() on the return value of the something_vfunc() function, in case the virtual C function does not provide a reference.

refreturn_ctype

Do an extra reference() on the return value of an overridden something_vfunc() function in the C callback function, in case the calling C function expects it to provide a reference.

errthrow

Use the last GError** parameter of the C virtual function (if there is one) to throw an exception.

custom_vfunc

Do not generate a definition of the vfunc in the .cc file. Use this when you must generate the vfunc by hand.

custom_vfunc_callback

Do not generate a C callback function for the vfunc. Use this when you must generate the callback function by hand.

ifdef

Puts the generated code in #ifdef blocks.

slot_name

Specifies the name of the slot parameter of the method, if it has one. This enables gmmproc to generate code to copy the slot and pass the copy on to the C function in its final gpointer user_data parameter. The slot_callback option must also be used to specify the name of the glue callback function to also pass on to the C function.

slot_callback

Used in conjunction with the slot_name option to specify the name of the glue callback function that handles extracting the slot and then calling it. The address of this callback is also passed on to the C function that the method wraps.

no_slot_copy

Tells gmmproc not to pass a copy of the slot to the C function, if the method has one. Instead the slot itself is passed. The slot parameter name and the glue callback function must have been specified with the slot_name and slot_callbback options respectively.

A rule to which there may be exceptions: If the virtual C function returns a pointer to an object derived from GObject, i.e. a reference-counted object, then the virtual C++ function shall return a Glib::RefPtr<> object. One of the extra arguments refreturn or refreturn_ctype is required.

G.III.VI. Autres macros :

G.III.VI.I. _IMPLEMENTS_INTERFACE

This macro generates initialization code for the interface.

_IMPLEMENTS_INTERFACE(C++ interface name)

For instance, from button.hg:

_IMPLEMENTS_INTERFACE(Activatable)

There is one optional extra argument:

ifdef

Puts the generated code in #ifdef blocks.

G.III.VI.II. _WRAP_ENUM

Cette macro génère une énumération C++ pour habiller une énumération C. Vous devez préciser le nom C++ et le nom de l'énumération C subjacente.

For instance, from enums.hg:

_WRAP_ENUM(WindowType, GtkWindowType)

Si l'énumération n'est pas du type GType, vous devrez passer comme troisième paramètre NO_GTYPE. C'est le cas lorsqu'il n'existe pas de fonction *_get_type() pour l'énumération C ; mais, faites attention au fait qu'il n'est pas suffisant d'inclure un en-tête supplémentaire pour cette fonction. Vous devez également faire un rapport d'anomalie concernant l'API C étant donné que toutes les énumérations doivent être enregistrées en tant que GTypes.

For example, from icontheme.hg:

_WRAP_ENUM(IconLookupFlags, GtkIconLookupFlags, NO_GTYPE)

G.III.VI.III. _WRAP_ENUM_DOCS_ONLY

This macro just generates a Doxygen documentationn block for the enum. This is useful for enums that can't be wrapped with _WRAP_ENUM() because they are complexly defined (maybe using C macros) but including the generated enum documentation is still desired. It is used with the same syntax as _WRAP_ENUM() and also process the same options (though NO_GTYPE is just ignored because it makes no difference when just generating the enum's documentation).

G.III.VI.IV. _WRAP_GERROR

Cette macro génère une classe d'exception C++, dérivée de Glib::Error, avec un Code enum et une fonction membre code(). Vous devez préciser le nom C++ souhaité, le nom de l'énumération correspondante C et le préfixe pour les valeurs d'énumération C.

Cette exception peut alors être déclenchée par des fonctions membres générées par _WRAP_METHOD() avec l'option errthrow.

For instance, from pixbuf.hg:

_WRAP_GERROR(PixbufError, GdkPixbufError, GDK_PIXBUF_ERROR)

G.III.VI.V. _MEMBER_GET / _MEMBER_SET

Si vous habillez une simple structure ou un type de boîte qui autorise un accès direct à ses données membres, utilisez ces macros pour créer les obtenteurs (get) et mutateurs (set) des données membres.

_MEMBER_GET(C++ name, C name, C++ type, C type)

_MEMBER_SET(C++ name, C name, C++ type, C type)

For example, in rectangle.hg:

_MEMBER_GET(x, x, int, int)

G.III.VI.VI. _MEMBER_GET_PTR / _MEMBER_SET_PTR

Utilisez ces macros pour créer automatiquement des obtenteurs (get) et des mutateurs (set) pour une donnée membre du type pointeur. Pour le mécanisme d'obtention, elle créera deux fonctions membres, une qualifiée const et une non-const.

_MEMBER_GET_PTR(C++ name, C name, C++ type, C type)

_MEMBER_SET_PTR(C++ name, C name, C++ type, C type)

For example, for Pango::Analysis in item.hg:

// _MEMBER_GET_PTR(engine_lang, lang_engine, EngineLang*, PangoEngineLang*)
// It's just a comment. It's difficult to find a real-world example.

G.III.VI.VII. _MEMBER_GET_GOBJECT / _MEMBER_SET_GOBJECT

Use these macros to provide getters and setters for a data member that is a GObject type that must be referenced before being returned.

_MEMBER_GET_GOBJECT(C++ name, C name, C++ type, C type)

_MEMBER_SET_GOBJECT(C++ name, C name, C++ type, C type)

For example, in Pangomm, layoutline.hg:

_MEMBER_GET_GOBJECT(layout, layout, Pango::Layout, PangoLayout*)

G.III.VII. gmmproc Parameter Processing

gmmproc allows processing the parameters in a method signature for the macros that process method signatures (like _WRAP_METHOD(), _WRAP_CTOR() and _WRAP_CREATE()) in a variety of ways:

G.III.VII.I. Parameter Reordering

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 Gtk::Widget class:

        void gtk_widget_set_device_events(GtkWidget* widget, GdkDevice* device,
        GdkEventMask events);
      
However, changing the order of the C++ method's two parameters is necessary. Something like the following would wrap the function as a C++ method with a different order for the two parameters:
        _WRAP_METHOD(void set_device_events(Gdk::EventMask events{events},
        const Glib::RefPtr<const Gdk::Device>& device{device}),
        gtk_widget_set_device_events)
      
The {c_param_name} following the method parameter names tells gmmproc to map the C++ parameter to the specified C parameter within the {}. Since the C++ parameter names correspond to the C ones, the above could be re-written as:
        _WRAP_METHOD(void set_device_events(Gdk::EventMask events{.}, const
        Glib::RefPtr<const Gdk::Device>& device{.}),
        gtk_widget_set_device_events)
      

Please note that when reordering parameters for a _WRAP_SIGNAL() method signature, the C parameter names would always be p0, p1, etc. because the generate_extra_defs utility uses those parameter names no matter what the C API's parameter names may be. It's how the utility is written presently.

G.III.VII.II. Optional Parameter Processing

For all macros processing method signatures except _WRAP_SIGNAL() and _WRAP_VFUNC() 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 *_new() function were being wrapped as a constructor in the Gtk::ToolButton class:

        GtkToolItem* gtk_tool_button_new(GtkWidget* icon_widget, const gchar*
        label);
      
Also, say that the C API allowed NULL for the function's label parameter so that that parameter is optional. It would be possible to have gmmproc generate the original constructor (with all the parameters) along with an additional constructor without that optional parameter by appending a {?} to the parameter name like so:
        _WRAP_CTOR(ToolButton(Widget& icon_widget, const Glib::ustring&
        label{?}), gtk_tool_button_new)
      
In this case, two constructors would be generated: One with the optional parameter and one without it.

G.III.VII.III. Output Parameter Processing

With _WRAP_METHOD() it is also possible for the return of the wrapped C function (if it has one) to be placed in an output parameter 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 in the C++ method parameter list appending a {OUT} to the output parameter name. For example, if gtk_widget_get_request_mode() is declared as the following:

        GtkSizeRequestMode gtk_widget_get_request_mode(GtkWidget* widget);
      
And having the C++ method set an output parameter is desired instead of returning a SizeRequestMode, something like the following could be used:
        _WRAP_METHOD(void get_request_mode(SizeRequestMode& mode{OUT})
        const, gtk_widget_get_request_mode)
      
The {OUT} appended to the name of the mode 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:
        _INITIALIZATION(`SizeRequestMode&',`GtkSizeRequestMode',`$3 =
        (SizeRequestMode)($4)')
      
Which could also be written as:
        _INITIALIZATION(`SizeRequestMode&',`GtkSizeRequestMode',`$3 =
        ($1)($4)')
      

_WRAP_METHOD() 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 rect:

        gboolean gtk_icon_view_get_cell_rect(GtkIconView* icon_view,
        GtkTreePath* path, GtkCellRenderer* cell, GdkRectangle* rect);
      
To have gmmproc place the value returned in the C++ rect output parameter, something like the following _WRAP_METHOD() directive could be used:
        _WRAP_METHOD(bool get_cell_rect(const TreeModel::Path& path, const
        CellRenderer& cell, Gdk::Rectangle& rect{>>}) const,
        gtk_icon_view_get_cell_rect)
      
The {>>} following the rect parameter name indicates that the C++ output parameter should be set from the value returned in the C parameter from the C function. gmmproc 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 _INITIALIZATION() describing how to set a Gdk::Rectangle& from a GdkRectangle* such as the following:
        _INITIALIZATION(`Gdk::Rectangle&',`GdkRectangle', `$3 =
        Glib::wrap(&($4))')
      

G.III.VIII. Types de base

Certains types de base utilisés dans les API C possèdent une meilleure typologie en C++. Par exemple, il n'est pas nécessaire d'avoir un type gboolean puisque le C++ dispose du type bool. La liste suivante montre quelques types couramment utilisés dans les API C, types que vous pouvez convertir dans la bibliothèque d'habillage C++.

Équivalents des types de base

Types C: gboolean

Types C++: bool

Types C: gint

Types C++: int

Types C: guint

Types C++: guint

Types C: gdouble

Types C++: double

Types C: gunichar

Types C++: gunichar

Types C: gchar*

Types C++: Glib::ustring (or std::string for filenames)