Los archivos .hg y .ccg

Esta macro declara un envoltorio de un tipo que deriva de GObject, pero cuyo envoltorio no deriva de 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)

Esta macro declara un envoltorio para un tipo cuyo envoltorio deriva de Gtk::Object, como un widget o un diálogo.

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

Típicamente usará esta macro cuando la clase ya derive de Gtk::Object. Por ejemplo, la usará cuando envuelva un widget de GTK+, porque Gtk::Widget deriva de Gtk::Object.

También podrá derivar clases que no sean widgets de Gtk::Object para que puedan usarse sin Glib::RefPtr. Por ejemplo, podrían instanciarse con Gtk::manage() o en la pila como una variable miembro. Esto es cómodo, pero sólo debe usarlo cuando esté seguro de que no se necesita conteo de referencias real. Se considera de utilidad para los widgets.

Esta macro declara un envoltorio para una estructura que no es GObject, registrada con 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)

Esta macro declara un envoltorio para una estructura asignable simple como GdkRectangle. Es similar a _CLASS_BOXEDTYPE, pero la estructura de C no se asigna dinámicamente.

_CLASS_BOXEDTYPE_STATIC( C++ class, C class )

For instance, for Gdk::Rectangle:

_CLASS_BOXEDTYPE_STATIC(Rectangle, GdkRectangle)

Esta macro declara un envoltorio para una estructura opaca que tiene funciones «copy» y «free». Las funciones «new», «copy» y «free» se usarán para instanciar el constructor predeterminado, copiar el constructor y el destructor.

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

Esta macro declara un envoltorio para una estructura opaca con conteo de referencias. El envoltorio de C++ no puede instanciarse directamente y sólo lo puede usar 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)

Esta macro puede usarse para envolver estructuras que no se ajustan a ninguna categoría especializada.

_CLASS_GENERIC( C++ class, C class )

For instance, for Pango::AttrIter:

_CLASS_GENERIC(AttrIter, PangoAttrIterator)

Esta macro declara un envoltorio para un tipo que deriva de 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)

Esta macro crea un constructor predeterminado sin argumentos.

Esta macro crea un constructor con argumentos, equivalente a una función de C *_new(). En realidad no llamará a la función *_new(), sino que simplemente creará un constructor equivalente con los mismos tipos de argumentos. Toma una firma de constructor de C++ y un nombre de función de C.

It also takes an optional extra argument:

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

Esta macro genera el método de C++ para envolver una función de 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 función de C (por ejemplo, gtk_entry_set_text) se describe en mayor detalle en el archivo .defs, y los archivos convert*.m4 contienen la conversión necesaria del tipo de parámetro de C++ al tipo de C. Esta macro también genera comentarios de documentación de Doxygen basados en los archivos *_docs.xml y *_docs_override.xml.

There are some optional extra arguments:

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:

Esta macro es similar a _WRAP_METHOD(), pero sólo genera la documentación de un método de C++ que envuelve una función de C. Úsela cuando debe escribir el método a mano, pero quiere usar la documentación que se crearía si el método se generara.

_WRAP_METHOD_DOCS_ONLY(C function name)

For instance, from container.hg:

_WRAP_METHOD_DOCS_ONLY(gtk_container_remove)

There are some optional extra arguments:

gmmproc will warn you on stdout about functions, signals, properties and child properties 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, signals, properties or child properties, or if you chose to hand-code some methods then you can use the _IGNORE(), _IGNORE_SIGNAL(), _IGNORE_PROPERTY() or _IGNORE_CHILD_PROPERTY() macro to make gmmproc stop complaining.

For instance, from flowbox.hg:

_IGNORE(gtk_flow_box_set_filter_func, gtk_flow_box_set_sort_func)
_IGNORE_SIGNAL(activate-cursor-child, toggle-cursor-child, move-cursor)

Esta macro genera la señal de C++ con el estilo de libsigc++ para envolver una señal GObject de C. En realidad genera un método de acceso público, como signal_clicked(), que devuelve un objeto sustituto. gmmproc usa el archivo .defs para descubrir los tipos de parámetro de C y los archivos de conversión .m4 para descubrir conversiones de tipo adecuadas.

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

For instance, from button.hg:

_WRAP_SIGNAL(void clicked(),"clicked")

Las señales generalmente tienen punteros de funciones en la estructura de GTK, con un valor de enum correspondiente y un g_signal_new() en el archivo .c.

There are some optional extra arguments:

Esta macro genera el método de C++ que envuelve una propiedad GObject de C. Debe especificar el nombre de la propiedad y el tipo de C++ que quiere para la propiedad. gmmproc usa el archivo .defs para descubrir el tipo de C y el archivo de conversión .m4 para descubrir conversiones de tipo apropiadas.

_WRAP_PROPERTY(C property name, C++ type)

For instance, from button.hg:

_WRAP_PROPERTY("label", Glib::ustring)

There are some optional extra arguments:

Esta macro genera el método de C++ que envuelve una función virtual de C.

_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. Conversions can also be written in the .hg file. Virtual functions often require special conversions that are best kept local to the .hg file where they are used.

There are some optional extra arguments:

Una regla para la cual puede haber excepciones: si la función virtual de C devuelve un puntero a un objeto derivado de GObject, es decir un objeto cuyas referencias se cuentan, entonces la función virtual de C++ deberá devolver un objeto Glib::RefPtr<>. Se requiere uno de los argumentos adicionales refreturn o refreturn_ctype.

This macro generates the C++ method to wrap a GtkContainer child property. (See GtkContainer for more information about child properties). Similarly to _WRAP_PROPERTY, you must specify the property name and the wanted C++ type for the property. gmmproc uses the .defs file to discover the C type and the .m4 convert files to discover appropriate type conversions.

_WRAP_CHILD_PROPERTY(C child property name, C++ type)

For instance, from notebook.hg:

_WRAP_CHILD_PROPERTY("tab-expand", bool)

_WRAP_CHILD_PROPERTY() accepts the same optional arguments as _WRAP_PROPERTY().

Esta macro genera código de inicialización para la interfaz.

_IMPLEMENTS_INTERFACE(C++ interface name)

For instance, from button.hg:

_IMPLEMENTS_INTERFACE(Activatable)

There is one optional extra argument:

Esta macro genera una enum de C++ para envolver una enum de C. Debe especificar el nombre de C++ que quiere y el nombre de la enum de C subyacente.

For instance, from enums.hg:

_WRAP_ENUM(WindowType, GtkWindowType)

Si la enum no es un GType, debe pasar un tercer parámetro «NO_GTYPE». Este es el caso cuando no hay una función *_get_type() para la enum de C, pero tenga cuidado: no sólo necesita incluir una cabecera adicional para esa función, también debe enviar un informe de error de la API de C porque todas las enums deben registrarse como GTypes.

_WRAP_ENUM() accepts the optional newin parameter. See _WRAP_METHOD().

For example, from icontheme.hg:

_WRAP_ENUM(IconLookupFlags, GtkIconLookupFlags, NO_GTYPE)

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

Esta macro genera una clase de excepción de C++, derivada de Glib::Error, con una enum Code y un método code(). Debe especificar el nombre de C++ que quiere, el nombre de la enum de C correspondiente, y el prefijo de los valores de la enum de C.

Los métodos generados desde _WRAP_METHOD() podrán entonces lanzar esta excepción con la opción «errthrow».

_WRAP_GERROR() accepts the optional newin parameter. See _WRAP_METHOD().

For instance, from pixbuf.hg:

_WRAP_GERROR(PixbufError, GdkPixbufError, GDK_PIXBUF_ERROR)

Use estas macros si está envolviendo una estructura simple o un tipo en caja que proporciona acceso directo a sus miembros de datos, para crear métodos de acceso y modificación para estos.

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

Use estas macros para proporcionar métodos de acceso y modificación para un miembro de datos que es de tipo puntero automáticamente. Para la función de acceso, creará dos métodos, uno constante y otro no constante.

_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 estas macros para proporcionar métodos de acceso y modificación para un miembro de datos que es de tipo GObject que debe referenciarse antes de devolverse.

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

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

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

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

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

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

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

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

        _WRAP_METHOD(bool get_cell_rect(const TreeModel::Path& path, const
        CellRenderer& cell, Gdk::Rectangle& rect{>>}) const,
        gtk_icon_view_get_cell_rect)
      

        _INITIALIZATION(`Gdk::Rectangle&',`GdkRectangle', `$3 =
        Glib::wrap(&($4))')