<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Appendix I. Optional API</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="index.html" title="Programming with gtkmm">
<link rel="prev" href="sec-wrapping-documentation.html" title="Documentation">
<link rel="next" href="sec-gtkmm-optional-api.html" title="Optional API when building gtkmm">
</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">Appendix I. Optional API</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="sec-wrapping-documentation.html"><img src="icons/prev.png" alt="Prev"></a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="sec-gtkmm-optional-api.html"><img src="icons/next.png" alt="Next"></a>
</td>
</tr>
</table>
<hr>
</div>
<div class="appendix" title="Appendix I. Optional API">
<div class="titlepage"><div><div><h2 class="title">
<a name="chapter-optional-api"></a>Appendix I. Optional API</h2></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<ul>
<li><span class="sect1"><a href="chapter-optional-api.html#sec-glibmm-optional-api">Optional API when building glibmm</a></span></li>
<li><span class="sect1"><a href="sec-gtkmm-optional-api.html">Optional API when building gtkmm</a></span></li>
</ul>
</div>
<p>The gtkmm API is meant to be easy and convenient. However, some of these
conveniences are not worth the overhead on reduced resources devices, such
as the Nokia 770 internet tablet. For instance, with regular gtkmm you can
implement a signal handler by deriving the class and overriding its virtual
<code class="methodname">on_thesignalname()</code> method. But that additional API
increases code size. And in the case of virtual methods, it increases
per-object memory size, and demands that the linker loads the method's
symbol even if you don't use it. Therefore, gtkmm can be built with a
reduced API. In general, the optional API is rarely used, and there are
slightly less convenient alternatives for all of the optional API.</p>
<p>When gtkmm has been built with optional API disabled, macros will be
undefined, indicating that the API is not available. If you attempt to
compile an application that uses this optional API, against a version of
gtkmm that has disabled that API, you will see compiler warnings about
missing functions.</p>
<p>The following sections describe the available configure options used to
disable optional API. Most developers will rarely need to provide these
configure options, because they will rarely build glibmm or gtkmm,
preferring to use official packages or installers. However, if you are
developing for an embedded device, you might need to be aware of these
options.</p>
<div class="sect1" title="Optional API when building glibmm">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="sec-glibmm-optional-api"></a>Optional API when building glibmm</h2></div></div></div>
<div class="sect2" title="--enable-deprecated-api=no">
<div class="titlepage"><div><div><h3 class="title">
<a name="glibmm-enable-deprecated"></a>--enable-deprecated-api=no</h3></div></div></div>
<p>
When enable-deprecated-api is disabled, no deprecated classes or methods
will be available in glibmm. For instance, the <code class="code">Date::set_time(GTime
time)</code> method overload will not be provided. The reference
documentation contains a <a class="ulink" href="http://library.gnome.org/devel/glibmm/unstable/deprecated.html" target="_top">full list of
deprecated glibmm API</a>.</p>
<p>If deprecated glibmm API is available, the
<code class="varname">GLIBMM_DISABLE_DEPRECATED</code> macro will not be
defined.</p>
</div>
<div class="sect2" title="--enable-api-exceptions=no">
<div class="titlepage"><div><div><h3 class="title">
<a name="glibmm-enable-exceptions"></a>--enable-api-exceptions=no</h3></div></div></div>
<p>
When enable-api-exceptions is disabled, no exceptions will be used in the glibmm
or gtkmm API, and no exceptions will be thrown. This allows applications to be
built without support for exceptions. For intance, the <span class="command"><strong>g++
-fno-exceptions</strong></span> option may be used. Where a method would normally
throw an exception, that method will instead take an additional
<code class="code">std::auto_ptr<Glib::Error>&</code> output parameter. If you are
not using exceptions then you should check whether this parameter was set and
handle any error appropriately.</p>
<p>If exceptions are not available, the
<code class="varname">GLIBMM_EXCEPTIONS_ENABLED</code> macro will not be
defined.</p>
</div>
<div class="sect2" title="--enable-api-properties=no">
<div class="titlepage"><div><div><h3 class="title">
<a name="glibmm-enable-properties"></a>--enable-api-properties=no</h3></div></div></div>
<p>
When enable-api-properties is disabled, no property accessors will be available in the glibmm or gtkmm API. For instance, the <code class="methodname">Gtk::Button::property_label()</code> method will not be available. "getter" and "setter" methods, such as <code class="methodname">Gtk::Button::set_label()</code> will still be available.</p>
<p>When you really need to set or get the property value directly, for instance when using the <code class="classname">Gtk::CellRenderer</code> API, you can use the alternative <code class="methodname">set_property()</code> and <code class="methodname">get_property()</code> methods. For instance:</p>
<p>
</p>
<pre class="programlisting">
#ifdef GLIBMM_PROPERTIES_ENABLED
m_cellrenderer.property_editable() = true;
#else
m_cellrenderer.set_property("editable", true);
#endif
</pre>
<p>
</p>
<p>If property accessors are not available, the
<code class="varname">GLIBMM_PROPERTIES_ENABLED</code> macro will not be
defined.</p>
</div>
<div class="sect2" title="--enable-api-vfuncs=no">
<div class="titlepage"><div><div><h3 class="title">
<a name="glibmm-enable-vfuncs"></a>--enable-api-vfuncs=no</h3></div></div></div>
<p>
When enable-api-exceptions is disabled, no <code class="methodname">_vfunc</code>
virtual methods will be available in the glibmm or gtkmm API. These methods
allow the developer to override some low-level behaviour of the underlying
GTK+ objects, and they are therefore rarely used. For instance,
<code class="methodname">Gtk::Frame::compute_child_allocation_vfunc()</code> will not
be available.</p>
<p>However, if you really need to override a <code class="methodname">_vfunc</code>, for
instance when implementing a custom <code class="classname">Gtk::TreeModel</code>,
you may directly access the underlying GObject via the
<code class="methodname">gobj()</code> method.</p>
<p>If vfuncs are not available, the <code class="varname">GLIBMM_VFUNCS_ENABLED</code>
macro will not be defined.</p>
</div>
<div class="sect2" title="--enable-api-default-signal-handlers=no">
<div class="titlepage"><div><div><h3 class="title">
<a name="glibmm-enable-default-signal-handlers"></a>--enable-api-default-signal-handlers=no</h3></div></div></div>
<p>
When enable-api-exceptions is disabled, no virtual signal handler methods will
be available in the glibmm or gtkmm API. For instance, the
<code class="methodname">Gtk::Button::on_clicked()</code> method will not be provided.
Instead you must connect a signal handler by using the
<code class="methodname">signal_clicked()</code> accessor. This option offers a
considerable code size and per-object memory reduction.</p>
<p>Note, however, that the compiler will not complain if you attempt to
override a default signal handler when they are not supported by <span class="application">gtkmm</span>,
because the compiler cannot know that you expected to override a virtual
method.</p>
<p>If default signal handlers are not available, the
<code class="varname">GLIBMM_DEFAULT_SIGNAL_HANDLERS_ENABLED</code> macro will not be
defined.</p>
</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-documentation.html"><img src="icons/prev.png" alt="Prev"></a> </td>
<td width="20%" align="center"> </td>
<td width="40%" align="right"> <a accesskey="n" href="sec-gtkmm-optional-api.html"><img src="icons/next.png" alt="Next"></a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Documentation </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"> Optional API when building gtkmm</td>
</tr>
</table>
</div>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
345aa895e80053137c21f8693106c3a0
>
files
>
28
