<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>The .hg and .ccg files</title>
<link rel="stylesheet" href="style.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.1">
<link rel="home" href="index.html" title="Programming with gtkmm">
<link rel="up" href="chapter-wrapping-c-libraries.html" title="Appendix H. Wrapping C Libraries with gmmproc">
<link rel="prev" href="sec-wrapping-defs-files.html" title="Generating the .defs files.">
<link rel="next" href="sec-wrapping-hand-coded-files.html" title="Hand-coded source files">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">The .hg and .ccg files</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="sec-wrapping-defs-files.html"><img src="icons/prev.png" alt="Prev"></a> </td>
<th width="60%" align="center">Appendix H. Wrapping C Libraries with gmmproc</th>
<td width="20%" align="right"> <a accesskey="n" href="sec-wrapping-hand-coded-files.html"><img src="icons/next.png" alt="Next"></a>
</td>
</tr>
</table>
<hr>
</div>
<div class="sect1" title="The .hg and .ccg files">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="sec-wrapping-hg-files"></a>The .hg and .ccg files</h2></div></div></div>
<p>The .hg and .ccg source files are very much like
.h anc .cc C++ source files, but they contain extra macros, such as
<code class="function">_CLASS_GOBJECT()</code> and
<code class="function">_WRAP_METHOD()</code>, from which
<span class="command"><strong>gmmproc</strong></span> 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.</p>
<p>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 <code class="filename">button.hg</code> looks
roughly like this:
</p>
<pre class="programlisting">
#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
</pre>
<p>
</p>
<p>The macros in this example do the following:
</p>
<div class="variablelist"><dl>
<dt><span class="term"><code class="function">_DEFS()</code></span></dt>
<dd><p>Specifies the destination directry for generated sources, and the name of the main .defs file that <span class="command"><strong>gmmproc</strong></span> should parse.</p></dd>
<dt><span class="term"><code class="function">_PINCLUDE()</code></span></dt>
<dd><p>Tells <span class="command"><strong>gmmproc</strong></span> to include a header from the generated private/button_p.h file.</p></dd>
<dt><span class="term"><code class="function">_CLASS_GTKOBJECT()</code></span></dt>
<dd><p>Tells <span class="command"><strong>gmmproc</strong></span> to add some typedefs, constructors, and standard methods to this class, as appropriate when wrapping a GtkObject-derived type.</p></dd>
<dt><span class="term"><code class="function">_WRAP_METHOD()</code>,
<code class="function">_WRAP_SIGNAL()</code>, and
<code class="function">_WRAP_PROPERTY()</code></span></dt>
<dd><p>Add methods to wrap parts of the C API.</p></dd>
</dl></div>
<p>
</p>
<p>The .h and .cc files will be generated from the .hg and .ccg files by
processing them with <span class="command"><strong>gmmproc</strong></span> like so, though this happens
automatically when using the above build structure:
</p>
<pre class="programlisting">
$ cd gtk/src
$ /usr/lib/glibmm-2.4/proc/gmmproc -I ../../tools/m4 --defs . button . ./../gtkmm
</pre>
<p>
</p>
<p>Notice that we provided <span class="command"><strong>gmmproc</strong></span> 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.</p>
<p>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.</p>
<p>The macros are explained in more detail in the following sections.</p>
<div class="sect2" title="m4 Conversions">
<div class="titlepage"><div><div><h3 class="title">
<a name="gmmproc-m4-conversions"></a>m4 Conversions</h3></div></div></div>
<p>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 <code class="literal">tools/m4/</code> 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:
</p>
<pre class="programlisting">
_CONVERSION(`GtkTreeView*',`TreeView*',`Glib::wrap($3)')
</pre>
<p>
</p>
<p><code class="literal">$3</code> will be replaced by the parameter name when this
conversion is used by gmmproc.
</p>
<p>
Some extra macros make this easier and consistent. Look in gtkmm's .m4 files
for examples. For instance:
</p>
<pre class="programlisting">
_CONVERSION(`PrintSettings&',`GtkPrintSettings*',__FR2P)
_CONVERSION(`const PrintSettings&',`GtkPrintSettings*',__FCR2P)
_CONVERSION(`const Glib::RefPtr<Printer>&',`GtkPrinter*',__CONVERT_REFPTR_TO_P($3))
</pre>
<p>
</p>
</div>
<div class="sect2" title="Class macros">
<div class="titlepage"><div><div><h3 class="title">
<a name="gmmproc-class-macros"></a>Class macros</h3></div></div></div>
<p>The class macro declares the class itself and its relationship with the
underlying C type. It generates some internal constructors, the member
<code class="varname">gobject_</code>, typedefs, the <code class="function">gobj()</code>
accessors, type registration, and the <code class="function">Glib::wrap()</code>
method, among other things.</p>
<p>Other macros, such as <code class="function">_WRAP_METHOD()</code> and
<code class="function">_SIGNAL()</code> may only be used after a call to a
<code class="function">_CLASS_*</code> macro.</p>
<div class="sect3" title="_CLASS_GOBJECT">
<div class="titlepage"><div><div><h4 class="title">
<a name="gmmproc-class-gobject"></a>_CLASS_GOBJECT</h4></div></div></div>
<p>This macro declares a wrapper for a type that is derived from
<code class="classname">GObject</code>, but which is not derived from
<code class="classname">GtkObject</code>.</p>
<p><code class="function">_CLASS_GOBJECT( C++ class, C class, C casting macro, C++ base class, C base class )</code></p>
<p>For instance, from <code class="filename">accelgroup.hg</code>:
</p>
<pre class="programlisting">
_CLASS_GOBJECT(AccelGroup, GtkAccelGroup, GTK_ACCEL_GROUP, Glib::Object, GObject)
</pre>
<p>
</p>
</div>
<div class="sect3" title="_CLASS_GTKOBJECT">
<div class="titlepage"><div><div><h4 class="title">
<a name="gmmproc-class-gtkobject"></a>_CLASS_GTKOBJECT</h4></div></div></div>
<p>This macro declares a wrapper for a type that is derived from
<code class="classname">GtkObject</code>, such as a widget or dialog.</p>
<p><code class="function">_CLASS_GTKOBJECT( C++ class, C class, C casting macro, C++ base class, C base class )</code></p>
<p>For instance, from <code class="filename">button.hg</code>:
</p>
<pre class="programlisting">
_CLASS_GTKOBJECT(Button, GtkButton, GTK_BUTTON, Gtk::Bin, GtkBin)
</pre>
<p>
</p>
</div>
<div class="sect3" title="_CLASS_BOXEDTYPE">
<div class="titlepage"><div><div><h4 class="title">
<a name="gmmproc-class-boxedtype"></a>_CLASS_BOXEDTYPE</h4></div></div></div>
<p>This macro declares a wrapper for a non-<code class="classname">GObject</code>
struct, registered with
<code class="function">g_boxed_type_register_static()</code>.</p>
<p><code class="function">_CLASS_BOXEDTYPE( C++ class, C class, new function, copy function, free function )</code></p>
<p>For instance, for <code class="classname">Gdk::Color</code>:
</p>
<pre class="programlisting">
_CLASS_BOXEDTYPE(Color, GdkColor, NONE, gdk_color_copy, gdk_color_free)
</pre>
<p>
</p>
</div>
<div class="sect3" title="_CLASS_BOXEDTYPE_STATIC">
<div class="titlepage"><div><div><h4 class="title">
<a name="gmmproc-class-boxedtype-static"></a>_CLASS_BOXEDTYPE_STATIC</h4></div></div></div>
<p>This macro declares a wrapper for a simple assignable struct such as
<code class="classname">GdkRectangle</code>. It is similar to
<code class="function">_CLASS_BOXEDTYPE</code>, but the C struct is not allocated
dynamically.</p>
<p><code class="function">_CLASS_BOXEDTYPE_STATIC( C++ class, C class )</code></p>
<p>For instance, for <code class="classname">Gdk::Rectangle</code>:
</p>
<pre class="programlisting">
_CLASS_BOXEDTYPE_STATIC(Rectangle, GdkRectangle)
</pre>
<p>
</p>
</div>
<div class="sect3" title="_CLASS_OPAQUE_COPYABLE">
<div class="titlepage"><div><div><h4 class="title">
<a name="gmmproc-class-opaque-copyable"></a>_CLASS_OPAQUE_COPYABLE</h4></div></div></div>
<p>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.</p>
<p><code class="function">_CLASS_OPAQUE_COPYABLE( C++ class, C class, new function, copy function, free function )</code></p>
<p>For instance, for <code class="classname">Gdk::Region</code>:
</p>
<pre class="programlisting">
_CLASS_OPAQUE_COPYABLE(Region, GdkRegion, gdk_region_new, gdk_region_copy, gdk_region_destroy)
</pre>
<p>
</p>
</div>
<div class="sect3" title="_CLASS_OPAQUE_REFCOUNTED">
<div class="titlepage"><div><div><h4 class="title">
<a name="gmmproc-class-opaque-refcounted"></a>_CLASS_OPAQUE_REFCOUNTED</h4></div></div></div>
<p>This macro declares a wrapper for a reference-counted opaque struct. The
C++ wrapper cannot be directly instantiated and can only be used with
<code class="classname">Glib::RefPtr</code>.</p>
<p><code class="function">_CLASS_OPAQUE_COPYABLE( C++ class, C class, new function, ref function, unref function )</code></p>
<p>For instance, for <code class="classname">Pango::Coverage</code>:
</p>
<pre class="programlisting">
_CLASS_OPAQUE_REFCOUNTED(Coverage, PangoCoverage, pango_coverage_new, pango_coverage_ref, pango_coverage_unref)
</pre>
<p>
</p>
</div>
<div class="sect3" title="_CLASS_GENERIC">
<div class="titlepage"><div><div><h4 class="title">
<a name="gmmproc-class-generic"></a>_CLASS_GENERIC</h4></div></div></div>
<p>This macro can be used to wrap structs which don't fit into any
specialized category.</p>
<p><code class="function">_CLASS_GENERIC( C++ class, C class )</code></p>
<p>For instance, for <code class="classname">Pango::AttrIter</code>:
</p>
<pre class="programlisting">
_CLASS_GENERIC(AttrIter, PangoAttrIterator)
</pre>
<p>
</p>
</div>
<div class="sect3" title="_CLASS_INTERFACE">
<div class="titlepage"><div><div><h4 class="title">
<a name="gmmproc-class-interface"></a>_CLASS_INTERFACE</h4></div></div></div>
<p>This macro declares a wrapper for a type that is derived from
<code class="classname">GObject</code>, but which is not derived from
<code class="classname">GtkObject</code>.
</p>
<p><code class="function">_CLASS_INTERFACE( C++ class, C class, C casting macro, C interface struct, Base C++ class (optional), Base C class (optional) )</code></p>
<p>
For instance, from <code class="filename">celleditable.hg</code>:
</p>
<pre class="programlisting">
_CLASS_INTERFACE(CellEditable, GtkCellEditable, GTK_CELL_EDITABLE, GtkCellEditableIface)
</pre>
<p>
</p>
<p>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 prerequisitite.
For instance, from <code class="filename">loadableicon.hg</code>:
</p>
<pre class="programlisting">
_CLASS_INTERFACE(LoadableIcon, GLoadableIcon, G_LOADABLE_ICON, GLoadableIconIface, Icon, GIcon)
</pre>
<p>
</p>
</div>
</div>
<div class="sect2" title="Constructor macros">
<div class="titlepage"><div><div><h3 class="title">
<a name="gmmproc-constructor-macros"></a>Constructor macros</h3></div></div></div>
<p>The <code class="function">_CTOR_DEFAULT()</code> and
<code class="function">_WRAP_CTOR()</code> macros add constructors, wrapping the
specified <code class="function">*_new()</code> 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
<code class="function">g_object_new()</code> call. These constructors never actually
call the <code class="function">*_new()</code> C functions,
because gtkmm must actually instantiate derived GTypes, and the
<code class="function">*_new()</code> C functions are meant only as convenience
functions for C programmers.</p>
<p>When using <code class="function">_CLASS_GOBJECT()</code>, the constructors should
be protected (rather than public) and each constructor should have a
corresponding <code class="function">_WRAP_CREATE()</code> in the public section.
This prevents the class from being instantiated without using a
<code class="classname">RefPtr</code>. For instance:
</p>
<pre class="programlisting">
class ActionGroup : public Glib::Object
{
_CLASS_GOBJECT(ActionGroup, GtkActionGroup, GTK_ACTION_GROUP, Glib::Object, GObject)
protected:
_WRAP_CTOR(ActionGroup(const Glib::ustring& name = Glib::ustring()), gtk_action_group_new)
public:
_WRAP_CREATE(const Glib::ustring& name = Glib::ustring())
</pre>
<p>
</p>
<div class="sect3" title="_CTOR_DEFAULT">
<div class="titlepage"><div><div><h4 class="title">
<a name="gmmproc-ctor-default"></a>_CTOR_DEFAULT</h4></div></div></div>
<p>This macro creates a default constructor with no arguments.
</p>
</div>
<div class="sect3" title="_WRAP_CTOR">
<div class="titlepage"><div><div><h4 class="title">
<a name="gmmproc-wrap-ctor"></a>_WRAP_CTOR</h4></div></div></div>
<p>This macro creates a constructor with arguments, equivalent to a
<code class="function">*_new()</code> C function. It won't actually call the
<code class="function">*_new()</code> function, but will simply create an equivalent
constructor with the same argument types. It takes a C++ constructor
signature, and a C function name.
</p>
</div>
<div class="sect3" title="Hand-coding constructors">
<div class="titlepage"><div><div><h4 class="title">
<a name="gmmproc-ctor-manual"></a>Hand-coding constructors</h4></div></div></div>
<p>When a constructor must be partly hand written because, for instance, the
<code class="function">*_new()</code> C function's parameters do not correspond
directly to object properties, or because the <code class="function">*_new()</code> C
function does more than call <code class="function">g_object_new()</code>, the
<code class="function">_CONSTRUCT()</code> macro may be used in the
.ccg file to save some work. The <code class="function">_CONSTRUCT</code> macro takes
a series of property names and values. For instance, from
<code class="filename">button.ccg</code>:
</p>
<pre class="programlisting">
Button::Button(const Glib::ustring& label, bool mnemonic)
:
_CONSTRUCT("label", label.c_str(), "use_underline", gboolean(mnemonic))
{}
</pre>
<p>
</p>
</div>
</div>
<div class="sect2" title="Method macros">
<div class="titlepage"><div><div><h3 class="title">
<a name="gmmproc-method-macros"></a>Method macros</h3></div></div></div>
<div class="sect3" title="_WRAP_METHOD">
<div class="titlepage"><div><div><h4 class="title">
<a name="gmmproc-wrap-method"></a>_WRAP_METHOD</h4></div></div></div>
<p>This macro generates the C++ method to wrap a C function.</p>
<p><code class="function">_WRAP_METHOD( C++ method signature, C function name)</code></p>
<p>For instance, from <code class="filename">entry.hg</code>:
</p>
<pre class="programlisting">
_WRAP_METHOD(void set_text(const Glib::ustring& text), gtk_entry_set_text)
</pre>
<p>
</p>
<p>The C function (e.g. <code class="function">gtk_entry_set_text</code>) is described
more fully in the .defs file, and the <code class="filename">convert*.m4</code> 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 <code class="filename">*_docs.xml</code> and
<code class="filename">*_docs_override.xml</code> files.</p>
<p>There are some optional extra arguments:
</p>
<div class="variablelist"><dl>
<dt><span class="term">refreturn</span></dt>
<dd><p>Do an extra reference() on the return value, in case the C
function does not provide a reference.</p></dd>
<dt><span class="term">errthrow</span></dt>
<dd><p>Use the last GError* parameter of the C function to
throw an exception.</p></dd>
<dt><span class="term">deprecated</span></dt>
<dd><p>Puts the generated code in #ifdef blocks. Text about the
deprecation can be specified as an optional
parameter.</p></dd>
<dt><span class="term">constversion</span></dt>
<dd><p>Just call the non-const version of the same function,
instead of generating almost duplicate code.</p></dd>
</dl></div>
<p>
</p>
<p>Though it's usually obvious what C++ types should be used in the C++ method, here are some hints:
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<li class="listitem"><p>Objects used via <code class="classname">RefPtr</code>: Pass the
<code class="classname">RefPtr</code> as a const reference. For instance,
<code class="code">const Glib::RefPtr<Gtk::Action>&
action</code>.</p></li>
<li class="listitem"><p>Const Objects used via <code class="classname">RefPtr</code>: If the
object should not be changed by the function, then make sure that
the object is const, even if the <code class="classname">RefPtr</code> is
already const. For instance, <code class="code">const Glib::RefPtr<const
Gtk::Action>& action</code>.</p></li>
<li class="listitem"><p>Wrapping <code class="classname">GList*</code> and
<code class="classname">GSList*</code> 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 an appropriate intermediate type, such as
<code class="classname">Glib::ListHandle</code> or
<code class="classname">Glib::SListHandle</code>. These are templates, so you
can specify the item type. For instance, <code class="code">Glib::ListHandle<
Glib::RefPtr<Action> ></code>. Existing typedefs exist for some common
list types. You may need to define a Traits type to specify how the C
and C++ types should be converted.</p></li>
<li class="listitem">
<p>Wrapping <code class="classname">GList*</code> and
<code class="classname">GSList*</code> 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:
</p>
<pre class="programlisting">#m4 _CONVERSION(`GSList*', `Glib::SListHandle<Widget*>', `$2($3, Glib::OWNERSHIP_NONE)')</pre>
</li>
</ul></div>
<p>
</p>
</div>
<div class="sect3" title="_WRAP_METHOD_DOCS_ONLY">
<div class="titlepage"><div><div><h4 class="title">
<a name="gmmproc-wrap-method-docs-only"></a>_WRAP_METHOD_DOCS_ONLY</h4></div></div></div>
<p>This macro is like <code class="function">_WRAP_METHOD()</code>, 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.</p>
<p><code class="function">_WRAP_METHOD_DOCS_ONLY(C function name)</code></p>
<p>For instance, from <code class="filename">container.hg</code>:
</p>
<pre class="programlisting">
_WRAP_METHOD_DOCS_ONLY(gtk_container_remove)
</pre>
<p>
</p>
</div>
<div class="sect3" title="_IGNORE()">
<div class="titlepage"><div><div><h4 class="title">
<a name="gmmproc-ignore"></a>_IGNORE()</h4></div></div></div>
<p><span class="command"><strong>gmmproc</strong></span> 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
<span class="command"><strong>gmmproc</strong></span> stop complaining.</p>
<p><code class="function">_IGNORE(C function name 1, C function name2, etc)</code></p>
<p>For instance, from <code class="filename">buttonbox.hg</code>:
</p>
<pre class="programlisting">
_IGNORE(gtk_button_box_set_spacing, gtk_button_box_get_spacing,
</pre>
<p>
</p>
</div>
<div class="sect3" title="_WRAP_SIGNAL">
<div class="titlepage"><div><div><h4 class="title">
<a name="gmmproc-wrap-signal"></a>_WRAP_SIGNAL</h4></div></div></div>
<p>This macro generates the C++ libsigc++-style signal to wrap a C GObject
signal. It actually generates a public accessor method, such as
<code class="function">signal_clicked()</code>, which returns a proxy object.
<span class="command"><strong>gmmproc</strong></span> uses the .defs file to discover the C parameter
types and the .m4 convert files to discover appropriate type
conversions.</p>
<p><code class="function">_WRAP_SIGNAL( C++ signal handler signature, C signal name)</code></p>
<p>For instance, from <code class="filename">button.hg</code>:
</p>
<pre class="programlisting">
_WRAP_SIGNAL(void clicked(),"clicked")
</pre>
<p>
</p>
<p>Signals usually have function pointers in the GTK struct, with a
corresponding enum value. and a <code class="function">g_signal_new()</code> in the
.c file.</p>
<p>There are some optional extra arguments:
</p>
<div class="variablelist"><dl>
<dt><span class="term">no_default_handler</span></dt>
<dd><p>Do not generate an <code class="function">on_something()</code> 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.</p></dd>
</dl></div>
<p>
</p>
</div>
<div class="sect3" title="_WRAP_PROPERTY">
<div class="titlepage"><div><div><h4 class="title">
<a name="gmmproc-wrap-property"></a>_WRAP_PROPERTY</h4></div></div></div>
<p>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. <span class="command"><strong>gmmproc</strong></span>
uses the .defs file to discover the C type and the .m4 convert files to
discover appropriate type conversions.</p>
<p><code class="function">_WRAP_PROPERTY(C property name, C++ type)</code></p>
<p>For instance, from <code class="filename">button.hg</code>:
</p>
<pre class="programlisting">
_WRAP_PROPERTY("label", Glib::ustring)
</pre>
<p>
</p>
</div>
</div>
<div class="sect2" title="Other macros">
<div class="titlepage"><div><div><h3 class="title">
<a name="gmmproc-other-macros"></a>Other macros</h3></div></div></div>
<div class="sect3" title="_WRAP_ENUM">
<div class="titlepage"><div><div><h4 class="title">
<a name="gmmproc-wrap-enum"></a>_WRAP_ENUM</h4></div></div></div>
<p>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.</p>
<p>For instance, from <code class="filename">widget.hg</code>:
</p>
<pre class="programlisting">
_WRAP_ENUM(WindowType, GdkWindowType)
</pre>
<p>
</p>
<p>If the enum is not a <code class="classname">GType</code>, you must pass a third parameter NO_GTYPE.
This is the case when there is no <code class="function">*_get_type()</code> 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 regeistered as GTypes.</p>
<p>For example:
</p>
<pre class="programlisting">
_WRAP_ENUM(IconLookupFlags, GtkIconLookupFlags)
</pre>
<p>
</p>
</div>
<div class="sect3" title="_WRAP_GERROR">
<div class="titlepage"><div><div><h4 class="title">
<a name="gmmproc-wrap-gerror"></a>_WRAP_GERROR</h4></div></div></div>
<p>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.</p>
<p>This exception can then be thrown by methods which are generated from _WRAP_METHOD() with the errthrow option.</p>
<p>For instance, from <code class="filename">pixbuf.hg</code>:
</p>
<pre class="programlisting">
_WRAP_GERROR(PixbufError, GdkPixbufError, GDK_PIXBUF_ERROR)
</pre>
<p>
</p>
</div>
<div class="sect3" title="_MEMBER_GET / _MEMBER_SET">
<div class="titlepage"><div><div><h4 class="title">
<a name="gmmproc-member-set-get"></a>_MEMBER_GET / _MEMBER_SET</h4></div></div></div>
<p>
Use these macro 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.
</p>
<p><code class="function">_MEMBER_GET(C++ name, C name, C++ type, C type)</code></p>
<p><code class="function">_MEMBER_SET(C++ name, C name, C++ type, C type)</code></p>
<p>
For example, in <code class="filename">rectangle.hg</code>:
</p>
<pre class="programlisting">_MEMBER_GET(x, x, int, int)</pre>
<p>
</p>
</div>
<div class="sect3" title="_MEMBER_GET_PTR / _MEMBER_SET_PTR">
<div class="titlepage"><div><div><h4 class="title">
<a name="gmmproc-member-get-set-ptr"></a>_MEMBER_GET_PTR / _MEMBER_SET_PTR</h4></div></div></div>
<p>
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.
</p>
<p><code class="function">_MEMBER_GET_PTR(C++ name, C name, C++ type, C type)</code></p>
<p><code class="function">_MEMBER_SET_PTR(C++ name, C name, C++ type, C type)</code></p>
<p>For example, in <code class="filename">dialog.hg</code>:
</p>
<pre class="programlisting">
_MEMBER_GET_PTR(vbox, vbox, VBox*, GtkWidget*)
</pre>
<p>
</p>
</div>
<div class="sect3" title="_MEMBER_GET_GOBJECT / _MEMBER_SET_GOBJECT">
<div class="titlepage"><div><div><h4 class="title">
<a name="gmmproc-member-get-set-gobject"></a>_MEMBER_GET_GOBJECT / _MEMBER_SET_GOBJECT</h4></div></div></div>
<p>
Use this macro to provide getters and setters for a data member that is a
<code class="classname">GObject</code> type that must be referenced before being
returned.
</p>
<p><code class="function">_MEMBER_GET_GOBJECT(C++ name, C name, C++ type, C type)</code></p>
<p><code class="function">_MEMBER_SET_GOBJECT(C++ name, C name, C++ type, C type)</code></p>
<p>For example, in <code class="filename">progress.hg</code>:
</p>
<pre class="programlisting">
_MEMBER_GET_GOBJECT(offscreen_pixmap, offscreen_pixmap, Gdk::Pixmap, GdkPixmap*)
</pre>
<p>
</p>
</div>
</div>
<div class="sect2" title="Basic Types">
<div class="titlepage"><div><div><h3 class="title">
<a name="gmmproc-basic-types"></a>Basic Types</h3></div></div></div>
<p>Some of the basic types that are used in C APIs have better alternatives
in C++. For example, there's no need for a <span class="type">gboolean</span> type since
C++ has <span class="type">bool</span>. The following list shows some commonly-used
types in C APIs and what you might convert them to in a C++ wrapper library.
</p>
<div class="segmentedlist" title="Basic Type equivalents">
<div class="title"><strong><span class="title">Basic Type equivalents</span></strong></div>
<table border="0">
<thead><tr class="segtitle">
<th>C type</th>
<th>C++ type</th>
</tr></thead>
<tbody>
<tr class="seglistitem">
<td class="seg"><span class="type">gboolean</span></td>
<td class="seg"><span class="type">bool</span></td>
</tr>
<tr class="seglistitem">
<td class="seg"><span class="type">gint</span></td>
<td class="seg"><span class="type">int</span></td>
</tr>
<tr class="seglistitem">
<td class="seg"><span class="type">guint</span></td>
<td class="seg"><span class="type">guint</span></td>
</tr>
<tr class="seglistitem">
<td class="seg"><span class="type">gdouble</span></td>
<td class="seg"><span class="type">double</span></td>
</tr>
<tr class="seglistitem">
<td class="seg"><span class="type">gunichar</span></td>
<td class="seg"><span class="type">gunichar</span></td>
</tr>
<tr class="seglistitem">
<td class="seg"><span class="type">gchar*</span></td>
<td class="seg">
<code class="classname">Glib::ustring</code> (or <code class="classname">std::string</code> for filenames)</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="sec-wrapping-defs-files.html"><img src="icons/prev.png" alt="Prev"></a> </td>
<td width="20%" align="center"><a accesskey="u" href="chapter-wrapping-c-libraries.html"><img src="icons/up.png" alt="Up"></a></td>
<td width="40%" align="right"> <a accesskey="n" href="sec-wrapping-hand-coded-files.html"><img src="icons/next.png" alt="Next"></a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Generating the .defs files. </td>
<td width="20%" align="center"><a accesskey="h" href="index.html"><img src="icons/home.png" alt="Home"></a></td>
<td width="40%" align="right" valign="top"> Hand-coded source files</td>
</tr>
</table>
</div>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
345aa895e80053137c21f8693106c3a0
>
files
>
205
