Los archivos .hg y .ccg
Los archivos de fuentes .hg y .ccg se parecen mucho a los archivos de fuentes .h y .cc de C++, pero contienen macros adicionales, como _CLASS_GOBJECT() y _WRAP_METHOD(), desde las que gmmproc genera código fuente de C++ apropiado, generalmente en la misma posición en la cabecera. Cualquier código fuente adicional de C++ se copiará tal cual en el archivo .h o .cc correspondiente.
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/widget.h> #include <gtkmm/actionable.h> _DEFS(gtkmm,gtk) _PINCLUDE(gtkmm/private/widget_p.h) namespace Gtk { class Button : public Widget, public Actionable { _CLASS_GTKOBJECT(Button, GtkButton, GTK_BUTTON, Gtk::Widget, GtkWidget) _IMPLEMENTS_INTERFACE(Actionable) 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
Adds 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.68/proc/gmmproc -I ../../tools/m4 --defs . button . ./../gtkmm
Tenga en cuenta que se le proporcionó a gmmproc la ruta de los archivos de conversión .m4, la ruta del archivo .defs, el nombre de un archivo .hg, la carpeta de las fuentes, y la carpeta de destino.
Debe evitar incluir la cabecera de C desde su cabecera de C++, para evitar contaminar el espacio de nombres global, y para evitar exportar API pública innecesaria. Pero necesitará incluir las cabeceras de C desde su archivo .ccg.
Las macros se explican en mayor detalle en las secciones siguientes.
- G.3.1. Conversiones m4
- G.3.2. Inicializaciones de m4
- G.3.3. Macros de clases
- G.3.4. Macros de constructores
- G.3.5. Macros that suppress generation of some code
- G.3.6. Macros de métodos
- G.3.7. Otras macros
- G.3.8. Procesado de parámetros de gmmproc
- G.3.9. Tipos básicos
G.3.1. Conversiones 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/ or codegen/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 will be replaced by the parameter name when this conversion is used by 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.3.2. Inicializaciones de m4
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.3.3. Macros de clases
Las macros de clases declaran la clase en sí y su relación con el tipo de C subyacente. Generan algunos constructores internos, el miembro gobject_, «typedefs», los gobj() de acceso, registro de tipos, y el método Glib::wrap(), entre otras cosas.
Otras macros, como _WRAP_METHOD() y _WRAP_SIGNAL() sólo pueden usarse después de una llamada a una macro _CLASS_*.
- G.3.3.1. _CLASS_GOBJECT
- G.3.3.2. _CLASS_GTKOBJECT
- G.3.3.3. _CLASS_BOXEDTYPE
- G.3.3.4. _CLASS_BOXEDTYPE_STATIC
- G.3.3.5. _CLASS_OPAQUE_COPYABLE
- G.3.3.6. _CLASS_OPAQUE_REFCOUNTED
- G.3.3.7. _CLASS_GENERIC
- G.3.3.8. _CLASS_INTERFACE
G.3.3.1. _CLASS_GOBJECT
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 adjustment.hg:
_CLASS_GOBJECT(Adjustment, GtkAdjustment, GTK_ADJUSTMENT, Glib::Object, GObject)
G.3.3.2. _CLASS_GTKOBJECT
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::Widget, GtkWidget)
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::make_managed() 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.3.3.3. _CLASS_BOXEDTYPE
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)
G.3.3.4. _CLASS_BOXEDTYPE_STATIC
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)
G.3.3.5. _CLASS_OPAQUE_COPYABLE
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::VariantType:
_CLASS_OPAQUE_COPYABLE(VariantType, GVariantType, NONE, g_variant_type_copy, g_variant_type_free)
G.3.3.6. _CLASS_OPAQUE_REFCOUNTED
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 Gtk::CssSection:
_CLASS_OPAQUE_REFCOUNTED(CssSection, GtkCssSection, NONE, gtk_css_section_ref, gtk_css_section_unref)
G.3.3.7. _CLASS_GENERIC
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 Gdk::TimeCoord:
_CLASS_GENERIC(TimeCoord, GdkTimeCoord)
G.3.3.8. _CLASS_INTERFACE
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 optional parameters were once added, for the case that the interface derives from another interface, which was believed to be the case when the GInterface has another GInterface as a prerequisite. This is a misunderstanding, though. When GInterface A has GInterface B as a prerequisite, it means that every class that implements A shall also implement B. For instance, from loadableicon.hg in glibmm-2.4:
_CLASS_INTERFACE(LoadableIcon, GLoadableIcon, G_LOADABLE_ICON, GLoadableIconIface, Icon, GIcon)
G.3.4. Macros de constructores
The _CTOR_DEFAULT() and _WRAP_CTOR() macros add constructors, wrapping the specified *_new() C functions. These macros assume that the C object has properties with the same names as the function parameters, as is usually the case, so that it can supply the parameters directly to a g_object_new() call. These constructors never actually call the *_new() C functions, because gtkmm must actually instantiate derived GTypes, and the *_new() C functions are meant only as convenience functions for C programmers.
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.3.4.1. _CTOR_DEFAULT
- G.3.4.2. _WRAP_CTOR
- G.3.4.3. Escribir constructores a mano
G.3.4.2. _WRAP_CTOR
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:
- errthrow
-
This tells gmmproc that the C *_new() has a final GError** parameter which should be ignored.
G.3.4.3. Escribir constructores a mano
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.3.5. Macros that suppress generation of some code
Some macros suppress the generation of some code when they are used after a _CLASS_* macro. Some suppress the definition in the generated .cc file, others suppress both the declaration in the .h file and the definition in the .cc file.
- G.3.5.1. _CUSTOM_DEFAULT_CTOR
- G.3.5.2. _CUSTOM_CTOR_CAST
- G.3.5.3. _CUSTOM_DTOR
- G.3.5.4. _CUSTOM_MOVE_OPERATIONS
- G.3.5.5. _CUSTOM_WRAP_NEW
- G.3.5.6. _CUSTOM_WRAP_FUNCTION
- G.3.5.7. _NO_WRAP_FUNCTION
G.3.5.1. _CUSTOM_DEFAULT_CTOR
Suppresses declaration and definition of default constructor in _CLASS_BOXEDTYPE, _CLASS_BOXEDTYPE_STATIC and _CLASS_OPAQUE_COPYABLE.
G.3.5.2. _CUSTOM_CTOR_CAST
Suppresses declaration and definition of the constructor that takes a pointer to the wrapped C object in _CLASS_BOXEDTYPE and _CLASS_BOXEDTYPE_STATIC.
Suppresses definition of the constructor that takes a pointer to the wrapped C object in _CLASS_INTERFACE and _CLASS_OPAQUE_COPYABLE.
Suppresses definition of the constructor that takes a pointer to the wrapped C object and the constructor that takes construct_params in _CLASS_GOBJECT and _CLASS_GTKOBJECT.
G.3.5.4. _CUSTOM_MOVE_OPERATIONS
Suppresses declaration and definition of move constructor and move assignment operator in _CLASS_GOBJECT and _CLASS_GTKOBJECT.
Por ejemplo:
class Derived : public Glib::Object { _CLASS_GOBJECT(Derived, GDerived, G_DERIVED, Glib::Object, GObject) _CUSTOM_MOVE_OPERATIONS public: Derived(Derived&& src) noexcept; Derived& operator=(Derived&& src) noexcept; // ... };
G.3.6. Macros de métodos
- G.3.6.1. _WRAP_METHOD
- G.3.6.2. _WRAP_METHOD_DOCS_ONLY
- G.3.6.3. _IGNORE, _IGNORE_SIGNAL, _IGNORE_PROPERTY
- G.3.6.4. _WRAP_SIGNAL
- G.3.6.5. _WRAP_PROPERTY
- G.3.6.6. _WRAP_VFUNC
G.3.6.1. _WRAP_METHOD
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:
- refreturn
-
Do an extra reference() on the return value, in case the C function does not provide a reference.
- errthrow ["<exceptions>"]
-
Use the last GError** parameter of the C function to throw an exception. The optional "<exceptions>" is a comma-separated list of exceptions that can be thrown. It determines which @throws Doxygen commands are added to the documentation. Default value is Glib::Error. If you want a comma in the description of an exception, precede it by a backslash. Example: errthrow "Glib::OptionError Hello\, world, Glib::ConvertError"
- deprecated ["<text>"]
-
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.
- newin "<version>"
-
Adds a @newin Doxygen command to the documentation, or replaces the @newin command generated from the C documentation.
- ifdef <identifier>
-
Puts the generated code in #ifdef blocks.
- slot_name <parameter_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 <function_name>
-
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_callback 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.3.6.2. _WRAP_METHOD_DOCS_ONLY
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 recentinfo.hg:
_WRAP_METHOD_DOCS_ONLY(gtk_recent_info_get_applications)
There are some optional extra arguments:
- errthrow ["<exceptions>"]
-
Excludes documentation of the last GError** parameter of the C function. The optional "<exceptions>" is a comma-separated list of exceptions that can be thrown. It determines which @throws Doxygen commands are added to the documentation. Default value is Glib::Error. If you want a comma in the description of an exception, precede it by a backslash. Example: errthrow "Glib::OptionError Hello\, world, Glib::ConvertError"
- newin "<version>"
-
Adds a @newin Doxygen command to the documentation, or replaces the @newin command generated from the C documentation.
- voidreturn
-
Don't include a @return Doxygen command in the documentation. Useful if the wrapped C function returns a value, but the corresponding C++ method returns void.
G.3.6.3. _IGNORE, _IGNORE_SIGNAL, _IGNORE_PROPERTY
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() or _IGNORE_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)
G.3.6.4. _WRAP_SIGNAL
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:
- 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, and when adding a signal without a public C default handler.
- 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.
- deprecated ["<text>"]
-
Puts the generated code in #ifdef blocks. Text about the deprecation can be specified as an optional parameter.
- newin "<version>"
-
Adds a @newin Doxygen command to the documentation, or replaces the @newin command generated from the C documentation.
- ifdef <identifier>
-
Puts the generated code in #ifdef blocks.
- exception_handler <method_name>
-
Allows to use custom exception handler instead of default one. Exception might be rethrown by user-defined handler, and it will be caught by default handler.
- detail_name <parameter_name>
-
Adds a const Glib::ustring& parameter to the signal_something() method. Use it, if the signal accepts a detailed signal name, i.e. if the underlying C code registers the signal with the G_SIGNAL_DETAILED flag.
- two_signal_methods
-
Used in conjunction with the detail_name option to generate two signal_something() methods, one without a parameter and one with a parameter without a default value. With only the detail_name option one method is generated, with a parameter with default value. Use the two_signal_methods option, if it's necessary in order to preserve ABI.
G.3.6.5. _WRAP_PROPERTY
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:
- deprecated ["<text>"]
-
Puts the generated code in #ifdef blocks. Text about the deprecation can be specified as an optional parameter.
- newin "<version>"
-
Adds a @newin Doxygen command to the documentation, or replaces the @newin command generated from the C documentation.
G.3.6.6. _WRAP_VFUNC
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:
- 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.
- keep_return
-
Keep a copy of the return value in the C callback function, in case the calling C function does not expect to get its own 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 <identifier>
-
Puts the generated code in #ifdef blocks.
- slot_name <parameter_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 <function_name>
-
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_callback options respectively.
- return_value <value>
-
Defines a non-default return value.
- err_return_value <value>
-
Defines a non-default return value, used only if the C++ something_vfunc() function throws an exception which is propagated to the C callback function. If return_value is specified, but err_return_value is not, then return_value is used also when an exception is propagated.
- exception_handler <method_name>
-
Allows to use custom exception handler instead of default one. Exception might be rethrown by user-defined handler, and it will be caught by default handler.
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.
G.3.7. Otras macros
- G.3.7.1. _IMPLEMENTS_INTERFACE
- G.3.7.2. _WRAP_ENUM
- G.3.7.3. _WRAP_ENUM_DOCS_ONLY
- G.3.7.4. _WRAP_GERROR
- G.3.7.5. _MEMBER_GET / _MEMBER_SET
- G.3.7.6. _MEMBER_GET_PTR / _MEMBER_SET_PTR
- G.3.7.7. _MEMBER_GET_GOBJECT / _MEMBER_SET_GOBJECT
G.3.7.1. _IMPLEMENTS_INTERFACE
Esta macro genera código de inicialización para la interfaz.
_IMPLEMENTS_INTERFACE(C++ interface name)
For instance, from grid.hg:
_IMPLEMENTS_INTERFACE(Orientable)
There is one optional extra argument:
- ifdef <identifier>
-
Puts the generated code in #ifdef blocks.
G.3.7.2. _WRAP_ENUM
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(Orientation, GtkOrientation)
There are some optional extra arguments:
- NO_GTYPE
-
Use this option, if the enum is not a GType. This is the case when there is no *_get_type() function for the C enum, but be careful that you don't just need to include an extra header for that function. You should also file a bug against the C API, because all enums should be registered as GTypes.
If you specify NO_GTYPE, don't use that enum as the type in _WRAP_PROPERTY. It would cause a runtime error, when the generated property_*() method is called.
For example, from icontheme.hg:
_WRAP_ENUM(IconLookupFlags, GtkIconLookupFlags, NO_GTYPE)
- gtype_func <function_name>
-
Specifies the name of the *_get_type() function for the C enum. Use this parameter if gmmproc can't deduce the correct function name from the name of the C enum type.
For example, from dbusproxy.hg in glibmm:
_WRAP_ENUM(ProxyFlags, GDBusProxyFlags, gtype_func g_dbus_proxy_flags_get_type)
- CONV_TO_INT
-
"Convertible to int." Generates a plain enum (not an enum class) within a class. Such an enum is scoped like an enum class, but unlike an enum class, it can be implicitly converted to int.
For example, from dialog.hg:
_WRAP_ENUM(ResponseType, GtkResponseType, CONV_TO_INT)
- s#<from>#<to>#
-
Substitutes (part of) the name of one or more enum constants. You can add any number of substitutions.
For example, from iochannel.hg in glibmm:
_WRAP_ENUM(SeekType, GSeekType, NO_GTYPE, s#^SEEK_#SEEK_TYPE_#)
- deprecated ["<text>"]
-
Puts the generated code in #ifdef blocks. Text about the deprecation can be specified as an optional parameter.
- newin "<version>"
-
Adds a @newin Doxygen command to the documentation, or replaces the @newin command generated from the C documentation.
G.3.7.3. _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 processes the same options (though NO_GTYPE, gtype_func <function_name> and CONV_TO_INT are ignored because they make no difference when just generating the enum's documentation).
G.3.7.4. _WRAP_GERROR
This macro generates a C++ exception class, derived from Glib::Error, with a Code enum and a code() method. You must specify the desired C++ name, the name of the corresponding C enum, and the prefix for the C enum values.
Los métodos generados desde _WRAP_METHOD() podrán entonces lanzar esta excepción con la opción «errthrow».
For instance, from pixbuf.hg:
_WRAP_GERROR(PixbufError, GdkPixbufError, GDK_PIXBUF_ERROR)
_WRAP_GERROR() accepts the same optional arguments as _WRAP_ENUM() (though CONV_TO_INT is ignored because all exception class enums are plain enums within a class).
G.3.7.5. _MEMBER_GET / _MEMBER_SET
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)
G.3.7.6. _MEMBER_GET_PTR / _MEMBER_SET_PTR
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.
G.3.7.7. _MEMBER_GET_GOBJECT / _MEMBER_SET_GOBJECT
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*)
G.3.8. Procesado de parámetros de gmmproc
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.3.8.1. Reordenación de parámetros
- G.3.8.2. Procesado de parámetros opcionales
- G.3.8.3. Procesado de parámetros de salida
- G.3.8.4. String Parameter Processing
G.3.8.1. Reordenación de parámetros
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)
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.3.8.2. Procesado de parámetros opcionales
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)
G.3.8.3. Procesado de parámetros de salida
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))')
G.3.8.4. String Parameter Processing
A string-valued input parameter in a C++ method is usually a const Glib::ustring& or a const std::string&. In C code it's a const gchar*. When an empty string is converted to const gchar*, it can be converted either to nullptr or to a pointer to an empty string (with c_str()). Some parameters in some C functions accept a nullptr, and interpret it in a special way. Other parameters must not be nullptr.
The default conversion in _WRAP_METHOD() and similar macros is
- for mandatory parameters (with or without default values): empty string to empty string,
- for optional parameters (with appended {?}): empty string to nullptr.
G.3.9. Tipos básicos
Algunos de los tipos básicos que se usan en las API de C tienen alternativas mejores en C++. Por ejemplo, no hay necesidad de un tipo gboolean dado que C++ tiene el bool. La siguiente lista muestra algunos tipos comúnmente usados en API de C y en qué los puede convertir en una biblioteca envoltorio de C++
Tipo de C: gboolean
Tipo de C++: bool
Tipo de C: gint
Tipo de C++: int
Tipo de C: guint
Tipo de C++: guint
Tipo de C: gdouble
Tipo de C++: double
Tipo de C: gunichar
Tipo de C++: gunichar
Tipo de C: gchar*
Tipo de C++: Glib::ustring (or std::string for filenames)