The .hg and .ccg source files are very much like
.h and .cc C++ source files, but they contain extra macros, such as
_CLASS_GOBJECT()
and
_WRAP_METHOD()
, from which
gmmproc generates appropriate C++ source code,
usually at the same position in the header. Any additional C++ source
code will be copied verbatim into the corresponding
.h or .cc file.
A .hg file will typically include some headers
and then declare a class, using some macros to add API or behavior 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
Notice that we provided gmmproc with the path to the .m4 convert files, the path to the .defs file, the name of a .hg file, the source directory, and the destination directory.
You should avoid including the C header from your C++ header, to avoid polluting the global namespace, and to avoid exporting unnecessary public API. But you will need to include the necessary C headers from your .ccg file.
The macros are explained in more detail in the following sections.
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 function. 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))
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.
The class macro declares the class itself and its relationship with the
underlying C type. It generates some internal constructors, the member
gobject_
, typedefs, the gobj()
accessors, type registration, and the Glib::wrap()
method, among other things.
Other macros, such as _WRAP_METHOD()
and
_WRAP_SIGNAL()
may only be used after a call to a
_CLASS_*
macro.
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 adjustment.hg
:
_CLASS_GOBJECT(Adjustment, GtkAdjustment, GTK_ADJUSTMENT, 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 )
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.
This macro declares a wrapper for a non-GObject
struct, registered with
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)
This macro declares a wrapper for a simple assignable struct such as
GdkRectangle
. It is similar to
_CLASS_BOXEDTYPE
, but the C struct is not allocated
dynamically.
_CLASS_BOXEDTYPE_STATIC( C++ class, C class )
For instance, for Gdk::Rectangle
:
_CLASS_BOXEDTYPE_STATIC(Rectangle, GdkRectangle)
This macro declares a wrapper for an opaque struct that has copy and free functions. The new, copy and free functions will be used to instantiate the default constructor, copy constructor and 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)
This macro declares a wrapper for a reference-counted opaque struct. The
C++ wrapper cannot be directly instantiated and can only be used with
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)
This macro can be used to wrap structs which don't fit into any specialized category.
_CLASS_GENERIC( C++ class, C class )
For instance, for Gdk::TimeCoord
:
_CLASS_GENERIC(TimeCoord, GdkTimeCoord)
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 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)
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)
This macro creates a constructor with arguments, equivalent to a
*_new()
C function. It won't actually call the
*_new()
function, but will simply create an equivalent
constructor with the same argument types. It takes a C++ constructor
signature, and a C function name.
It also takes an optional extra argument:
This tells gmmproc that the C *_new()
has
a final GError** parameter which should be ignored.
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))
{}
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.
Suppresses declaration and definition of default constructor in
_CLASS_BOXEDTYPE
, _CLASS_BOXEDTYPE_STATIC
and _CLASS_OPAQUE_COPYABLE
.
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
.
Suppresses declaration and definition of move constructor and move
assignment operator in _CLASS_GOBJECT
and
_CLASS_GTKOBJECT
.
For example:
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;
// ...
};
Suppresses definition of Glib::wrap()
function in
_CLASS_GOBJECT
and _CLASS_GTKOBJECT
.
This macro generates the C++ method to wrap a C function.
_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)
The C function (e.g. gtk_entry_set_text
) is described
more fully in the .defs file, and the convert*.m4
files
contain the necessary conversion from the C++ parameter type to the C
parameter type. This macro also generates doxygen documentation comments
based on the *_docs.xml
and
*_docs_override.xml
files.
There are some optional extra arguments:
Do an extra reference()
on the return value,
in case the C function does not provide a reference.
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"
Puts the generated code in #ifdef blocks. Text about the deprecation can be specified as an optional parameter.
Puts the generated code in the .cc file in a G_GNUC_BEGIN_IGNORE_DEPRECATIONS / G_GNUC_END_IGNORE_DEPRECATIONS block. (Only in glibmm >= 2.70.1)
Just call the non-const version of the same function, instead of generating almost duplicate code.
Adds a @newin Doxygen command to the documentation, or replaces the @newin command generated from the C documentation.
Puts the generated code in #ifdef blocks.
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.
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.
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)')
This macro is like _WRAP_METHOD()
, but it generates
only the documentation for a C++ method that wraps a C function. Use this
when you must hand-code the method, but you want to use the documentation
that would be generated if the method was generated.
_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:
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"
Adds a @newin Doxygen command to the documentation, or replaces the @newin command generated from the C documentation.
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.
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.
_IGNORE(C function name 1, C function name 2, etc)
_IGNORE_SIGNAL(C signal name 1, C signal name 2, etc)
_IGNORE_PROPERTY(C property name 1, C property name 2, etc)
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)
This macro generates the C++ libsigc++-style signal to wrap a C GObject
signal. It actually generates a public accessor method, such as
signal_clicked()
, which returns a proxy object.
gmmproc uses the .defs file to discover the C parameter
types and the .m4 convert files to discover appropriate type
conversions.
_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:
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.
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.
Do not generate a C callback function for the signal. Use this when you must generate the callback function by hand.
Do an extra reference()
on the return value
of the on_something()
virtual method, in
case the C function does not provide a reference.
Puts the generated code in #ifdef blocks. Text about the deprecation can be specified as an optional parameter.
Adds a @newin Doxygen command to the documentation, or replaces the @newin command generated from the C documentation.
Puts the generated code in #ifdef blocks.
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.
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.
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.
This macro generates the C++ method to wrap a C GObject 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_PROPERTY(C property name, C++ type)
For instance, from button.hg
:
_WRAP_PROPERTY("label", Glib::ustring)
There are some optional extra arguments:
Puts the generated code in #ifdef blocks. Text about the deprecation can be specified as an optional parameter.
Adds a @newin Doxygen command to the documentation, or replaces the @newin command generated from the C documentation.
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. 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:
Do an extra reference()
on the return value
of the something_vfunc()
function,
in case the virtual C function does not provide a reference.
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 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.
Use the last GError** parameter of the C virtual function (if there is one) to throw an exception.
Do not generate a definition of the vfunc in the
.cc
file. Use this when you must generate
the vfunc by hand.
Do not generate a C callback function for the vfunc. Use this when you must generate the callback function by hand.
Puts the generated code in #ifdef blocks.
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.
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.
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.
Defines a non-default return 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.
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.
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)
For instance, from grid.hg
:
_IMPLEMENTS_INTERFACE(Orientable)
There is one optional extra argument:
Puts the generated code in #ifdef blocks.
This macro generates a C++ enum to wrap a C enum. You must specify the desired C++ name and the name of the underlying C enum.
For instance, from enums.hg
:
_WRAP_ENUM(Orientation, GtkOrientation)
There are some optional extra arguments:
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)
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)
"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)
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_#)
Puts the generated code in #ifdef blocks. Text about the deprecation can be specified as an optional parameter.
Adds a @newin Doxygen command to the documentation, or replaces the @newin command generated from the C documentation.
This macro just generates a Doxygen documentation 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).
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.
This exception can then be thrown by methods which are generated from _WRAP_METHOD() with the errthrow option.
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).
Use these macros if you're wrapping a simple struct or boxed type that provides direct access to its data members, to create getters and setters for the data members.
_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 these macros to automatically provide getters and setters for a data member that is a pointer type. For the getter function, it will create two methods, one const and one 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*)
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:
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)
Warning | |
---|---|
Please note that when reordering parameters for a
|
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.
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
out_mime_type
:
GInputStream* gdk_clipboard_read_finish(GdkClipboard* clipboard,
GAsyncResult* result, const char** out_mime_type, GError** error)
To have gmmproc place the value returned in the C++
out_mime_type
output parameter, something like the
following _WRAP_METHOD()
macro could be used:
_WRAP_METHOD(Glib::RefPtr<Gio::InputStream> read_finish(
const Glib::RefPtr<Gio::AsyncResult>& result,
Glib::ustring& out_mime_type{>>}), gdk_clipboard_read_finish, errthrow)
The {>>}
following the out_mime_type
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
Glib::ustring&
from a
const char**
such as the following:
_INITIALIZATION(`Glib::ustring&',`const char*',`$3 = Glib::convert_const_gchar_ptr_to_ustring($4)')
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
.
If the default conversion is not the best conversion, append {NULL}
to a mandatory parameter or {?!NULL}
to an optional
parameter (!NULL
= not NULL
). If you
append both a C parameter name and NULL
, separate them
with a space: {c_param_name NULL}
.
Some of the basic types that are used in C APIs have better alternatives in C++. For example, there's no need for a gboolean type since C++ has bool. The following list shows some commonly-used types in C APIs and what you might convert them to in a C++ wrapper library.
C type | C++ type |
---|---|
gboolean | bool |
gint | int |
guint | guint |
gdouble | double |
gunichar | gunichar |
gchar* |
Glib::ustring (or std::string for filenames) |