Appendix H. Optional API

## Appendix H. Optional API

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 `on_thesignalname()` 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.

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.

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.

## Optional API when building glibmm

### --enable-deprecated-api=no

When enable-deprecated-api is disabled, no deprecated classes or methods will be available in glibmm. For instance, the `Date::set_time(GTime time)` method overload will not be provided. The reference documentation contains a full list of deprecated glibmm API.

If deprecated glibmm API is available, the `GLIBMM_DISABLE_DEPRECATED` macro will not be defined.

### --enable-api-exceptions=no

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 g++ -fno-exceptions option may be used. Where a method would normally throw an exception, that method will instead take an additional `std::auto_ptr<Glib::Error>&` output parameter. If you are not using exceptions then you should check whether this parameter was set and handle any error appropriately.

If exceptions are not available, the `GLIBMM_EXCEPTIONS_ENABLED` macro will not be defined.

### --enable-api-properties=no

When enable-api-properties is disabled, no property accessors will be available in the glibmm or gtkmm API. For instance, the `Gtk::Button::property_label()` method will not be available. "getter" and "setter" methods, such as `Gtk::Button::set_label()` will still be available.

When you really need to set or get the property value directly, for instance when using the `Gtk::CellRenderer` API, you can use the alternative `set_property()` and `get_property()` methods. For instance:

    #ifdef GLIBMM_PROPERTIES_ENABLED
      m_cellrenderer.property_editable() = true;
    #else
      m_cellrenderer.set_property("editable", true);
    #endif

If property accessors are not available, the `GLIBMM_PROPERTIES_ENABLED` macro will not be defined.

### --enable-api-vfuncs=no

When enable-api-exceptions is disabled, no `_vfunc` 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, `Gtk::Frame::compute_child_allocation_vfunc()` will not be available.

However, if you really need to override a `_vfunc`, for instance when implementing a custom `Gtk::TreeModel`, you may directly access the underlying GObject via the `gobj()` method.

If vfuncs are not available, the `GLIBMM_VFUNCS_ENABLED` macro will not be defined.

### --enable-api-default-signal-handlers=no

When enable-api-exceptions is disabled, no virtual signal handler methods will be available in the glibmm or gtkmm API. For instance, the `Gtk::Button::on_clicked()` method will not be provided. Instead you must connect a signal handler by using the `signal_clicked()` accessor. This option offers a considerable code size and per-object memory reduction.

Note, however, that the compiler will not complain if you attempt to override a default signal handler when they are not supported by gtkmm, because the compiler cannot know that you expected to override a virtual method.

If default signal handlers are not available, the `GLIBMM_DEFAULT_SIGNAL_HANDLERS_ENABLED` macro will not be defined.

Documentation |  | Optional API when building gtkmm