Les fichiers .hg et .ccg

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 )

Par exemple, à partir de accelgroup.hg :

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

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 )

Par exemple, à partir de 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.

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 )

Par exemple, pour Gdk::Color :

_CLASS_BOXEDTYPE(Color, GdkColor, NONE, gdk_color_copy, gdk_color_free)

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 )

Par exemple, pour Gdk::Rectangle :

_CLASS_BOXEDTYPE_STATIC(Rectangle, GdkRectangle)

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 stockitem.hg:

_CLASS_OPAQUE_COPYABLE(StockItem, GtkStockItem, NONE, gtk_stock_item_copy, gtk_stock_item_free)

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 )

Par exemple, pour Pango::Coverage :

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

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 )

Par exemple, pour Pango::AttrIter :

_CLASS_GENERIC(AttrIter, PangoAttrIterator)

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) )

Par exemple, pour celleditable.hg :

_CLASS_INTERFACE(CellEditable, GtkCellEditable, GTK_CELL_EDITABLE, GtkCellEditableIface)

Deux paramètres sont optionnels, dans le cas où l'interface dérive d'une autre interface, ce qui doit être le cas quand la GInterface a une autre GInterface prérequise. Par exemple, pour loadableicon.hg :

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

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

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.

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 _WRAP_CTOR() macro would look something like the following:

_WRAP_CTOR(ToolButton(Widget& icon_widget, const Glib::ustring& label{?}), gtk_tool_button_new)

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 gtk_tool_button_new() function is the following:

GtkToolItem* gtk_tool_button_new(GtkWidget* icon_widget, const gchar* label);

_WRAP_CTOR(ToolButton(const Glib::ustring& label{label}, Widget& icon_widget{icon_widget}), gtk_tool_button_new)

_WRAP_CTOR(ToolButton(const Glib::ustring& label{.}, Widget& icon_widget{.}), gtk_tool_button_new)

This same optional parameter syntax and parameter reordering is available for _WRAP_CREATE(). Additional create() overloads would be generated by gmmproc without the specified optional parameters.

Quand un constructeur doit être partiellement écrit à la main parce que, par exemple, les paramètres de la fonction C *_new() ne correspondent pas directement aux propriétés de l'objet ou parce que la fonction C *_new() fait plus qu'appeler g_object_new(), la macro _CONSTRUCT() peut s'utiliser dans le fichier .ccg pour s'économiser un peu de travail. La macro _CONSTRUCT prend comme paramètres une série de noms de propriétés et de valeurs. Par exemple, pour button.ccg :

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

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

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

Par exemple, pour 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.

Il y a quelques paramètres optionnels supplémentaires :

As with _WRAP_CTOR() 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:

_WRAP_METHOD(void get_preferred_size(Requisition& minimum_size, Requisition& natural_size{?}) const, gtk_widget_get_preferred_size)

Also, as with _WRAP_CTOR(), 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 gtk_widget_set_device_events() declaration is the following:

void gtk_widget_set_device_events(GtkWidget* widget, GdkDevice* device, GdkEventMask events);

_WRAP_METHOD(void set_device_events(Gdk::EventMask events{events}, const Glib::RefPtr<const Gdk::Device>& device{device}), gtk_widget_set_device_events)

_WRAP_METHOD(void set_device_events(Gdk::EventMask events{.}, const Glib::RefPtr<const Gdk::Device>& device{.}), gtk_widget_set_device_events)

With _WRAP_METHOD() 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 void. To do that, simply include the output parameter declaration in the C++ method declaration 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);

_WRAP_METHOD(void get_request_mode(SizeRequestMode& mode{OUT}) const, gtk_widget_get_request_mode)

_INITIALIZATION(`SizeRequestMode&',`GtkSizeRequestMode',`$3 = (SizeRequestMode)($4)')

_INITIALIZATION(`SizeRequestMode&',`GtkSizeRequestMode',`$3 = ($1)($4)')

Même s'il est généralement évident que les types C++ devraient être utilisés dans les fonctions membres C++, voici quelques astuces :

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)

Par exemple, pour container.hg :

_WRAP_METHOD_DOCS_ONLY(gtk_container_remove)

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)

Par exemple, pour buttonbox.hg :

_IGNORE(gtk_button_box_set_spacing, gtk_button_box_get_spacing)

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)

Par exemple, à partir de button.hg :

_WRAP_SIGNAL(void clicked(),"clicked")

Les signaux ont généralement des pointeurs de fonction dans la structure GTK, avec une valeur d'énumération correspondante, et une fonction g_signal_new() dans le fichier .c.

Il y a quelques paramètres optionnels supplémentaires :

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)

Par exemple, à partir de button.hg :

_WRAP_PROPERTY("label", Glib::ustring)

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

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

Par exemple, pour 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.

Il y a quelques paramètres optionnels supplémentaires :

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.

This macro generates initialization code for the interface.

_IMPLEMENTS_INTERFACE(C++ interface name)

Par exemple, à partir de button.hg :

_IMPLEMENTS_INTERFACE(Activatable)

There is one optional extra argument:

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.

Par exemple, pour widget.hg :

_WRAP_ENUM(WindowType, GdkWindowType)

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)

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.

Par exemple, pour pixbuf.hg :

_WRAP_GERROR(PixbufError, GdkPixbufError, GDK_PIXBUF_ERROR)

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)

Par exemple, dans rectangle.hg :

_MEMBER_GET(x, x, int, int)

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.

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*)