The .hg and .ccg files
| Appendix H. Wrapping C Libraries |

## The .hg and .ccg files

The .hg and .ccg source files are very much like .h anc .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 behaviour to this class. For instance, gtkmm's button.hg looks roughly like this:

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

    namespace Gtk
    {

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

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

      _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 directry for generated sources, and the name of the main .defs file that gmmproc should parse.
- _PINCLUDE(): Tells gmmproc to include a header from 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 GtkObject-derived type.
- _WRAP_METHOD(), _WRAP_SIGNAL(), and _WRAP_PROPERTY() add methods to wrap parts of the C API.

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

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

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

### Class macros

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 _SIGNAL() may only be used after a call to a _CLASS_* macro.

#### _CLASS_GOBJECT

This macro declares a wrapper for a type that is derived from GObject, but which is not derived from GtkObject.

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

#### _CLASS_GTKOBJECT

This macro declares a wrapper for a type that is derived from GtkObject, such as a widget or dialog.

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

For instance, from button.hg:

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

#### _CLASS_BOXEDTYPE

This macro declares a wrapper for a non-GObject struct, registed with g_boxed_type_register_static().

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

For instance, for Gdk::Color:

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

#### _CLASS_BOXEDTYPE_STATIC

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)

#### _CLASS_OPAQUE_COPYABLE

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, for Gdk::Region:

    _CLASS_OPAQUE_COPYABLE(Region, GdkRegion, gdk_region_new, gdk_region_copy, gdk_region_destroy)

#### _CLASS_OPAQUE_REFCOUNTED

This macro declares a wrapper for a reference-counted opaque struct. The C++ wrapper can not be directly instantiated and can only be used with Glib::RefPtr.

`_CLASS_OPAQUE_COPYABLE( 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)

#### _CLASS_GENERIC

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 Pango::AttrIter:

    _CLASS_GENERIC(AttrIter, PangoAttrIterator)

### Method macros

#### _WRAP_METHOD

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:

- refreturn: Do an extra reference() on the return value, in case the C function does not provide a reference.
- errthrow: Use the last GError* parameter of the C function to throw an exception.
- deprecated: Puts the generated code in #ifdef blocks.
- constversion: Just call the non-const version of the same function, instead of generating almost duplicate code.

#### _WRAP_METHOD_DOCS_ONLY

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( C++ method signature, C function name)`

For instance, from container.hg:

    _WRAP_METHOD_DOCS_ONLY(gtk_container_remove)

#### _IGNORE()

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

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

For instance, from buttonbox.hg:

    _IGNORE(gtk_button_box_set_spacing, gtk_button_box_get_spacing,

#### _WRAP_SIGNAL

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:

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

#### _WRAP_PROPERTY

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)

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

There are some optional extra arguments:

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

### Other macros

#### _WRAP_ENUM()

This macro generates a C++ enum, usually in a C++ namespace, to wrap a C enum from the globabl namespace. You must specify the desired C++ name and the name of the underlying C enum.

For instance, from widget.hg:

    _WRAP_ENUM(WindowType, GdkWindowType)

Generating the .defs files. |  | Hand-coded source files