Chapter 5. Changes in gtkmm-4.0 and glibmm-2.68

Table of Contents

Deprecations in gtkmm 4.10

gtkmm-4.0 is a new version of the gtkmm API that installs in parallel with the older gtkmm-2.4 and gtkmm-3.0 APIs. The last version of the gtkmm-3.0 API is gtkmm 3.24. gtkmm 4 has no major fundamental differences to gtkmm 3 but does make several changes (both small and large ones) that were not possible while maintaining binary compatibility. If you never used the gtkmm-3.0 API then you can safely ignore this chapter.

gtkmm 4's library is called libgtkmm-4.0 rather than libgtkmm-3.0 and installs its headers in a similarly-versioned directory, so your pkg-config check should ask for gtkmm-4.0 rather than gtkmm-3.0.

gtkmm-4.0 is used in combination with glibmm-2.68, which sets the global locale for your program. The older glibmm-2.4 does not do that, and gtkmm-3.0 does it only to some extent. What this means is briefly that if your gtkmm-3.0 program contains a call to std::locale::global(std::locale("")), you can probably remove it. If you don't want glibmm or gtkmm to set the global locale for you, you should add a call to Glib::set_init_to_users_preferred_locale(false) before any call to Glib::init() or Gtk::Application::create(). See the glibmm reference.

There are lots and lots of differences between gtkmm-3.0 and gtkmm-4.0. The following lists are not complete.

There are some important behavioural changes, to which you must adapt when migrating:

Whereas in gtkmm-3.0, destruction of a non-managed C++ widget wrapper caused the wrapped GtkWidget to be destroyed, changes in GTK4 mean that in gtkmm-4.0 this canʼt always be the case. GTK4 has no uniform way to remove a widget from a parent, as GTK3 did with Gtk::Container::remove(), so gtkmm-4.0 canʼt do the removal for you as gtkmm-3.0 did. Hence, if a non-managed C++ widget instance is destructed while the widget is a child of another, gtkmm-4.0 wonʼt remove it from the parent, the parent retains a ref that stops the child being disposed, and the GtkWidget stays alive. The end result is that to destroy a non-managed widget with its C++ wrapper you must first remove it from its parent (however that parent allows) so the C++ wrapperʼs dtor can drop the final reference.

Some new classes were added in gtkmm 4 and glibmm 2.68:

Glib::ExtraClassInit and Gtk::Snapshot: These classes are needed only for writing custom widgets. See the Custom Widgets section.
Gtk::EventControllerKey, Gtk::EventControllerMotion, Gtk::EventControllerScroll and Gtk::GestureStylus
Gdk::Paintable, Gdk::Texture, Gtk::Picture and Gtk::WidgetPaintable
Gdk::Window has been renamed to Gdk::Surface. (Gtk::Window keeps its name.)
Gdk::DrawContext and Gdk::CairoContext are new. Gdk::DrawingContext has been removed.
Gtk::Clipboard has been replaced by the new Gdk::Clipboard.
Gdk::DragContext has been split into Gdk::Drag and Gdk::Drop.

There have also been several changes to the API, which you will probably encounter when porting code that used gtkmm-3.0 and glibmm-2.4. Here is a short list:

A C++17 compiler is required.
Gtk::Button, Gtk::ToolButton, Gtk::MenuItem and Gtk::Switch implement the Gtk::Actionable interface instead of the removed Gtk::Activatable interface.
Gtk::FontButton implements the Gtk::FontChooser interface.
Gtk::Widget: The get_preferred_*_vfunc()s have been replaced by measure_vfunc(). This change only affects custom widgets.
sigc::slots use the sigc::slot<R(Args...)> syntax. Example: sigc::slot<void(int, int)> instead of sigc::slot<void, int, int>.
Gtk::DrawingArea uses a draw function instead of the draw signal.
Glib::ArrayHandle, Glib::StringArrayHandle, Glib::ListHandle and Glib::SListHandle have been removed. They were used in glibmm-2.4, but not used in gtkmm-3.0. If you've ever used these classes, replace them with a standard C++ container, such as std::vector.
Gtk::Container has been removed.
Gtk::Widget::show_all() has been removed. The default value of Gtk::Widget::property_visible() has been changed from false to true.
All event signals have been removed from Gtk::Widget. In most cases you can use one of the subclasses of Gtk::EventController as a replacement. For instance, use Gtk::GestureMultiPress instead of signal_button_press_event() and signal_button_release_event(), and Gtk::EventControllerKey instead of signal_key_press_event() and signal_key_release_event().
Glib::RefPtr is an alias for std::shared_ptr. If you make your own Glib::ObjectBase-derived classes with create() methods that return a Glib::RefPtr, you must use Glib::make_refptr_for_instance() in your create() methods.
Gtk::Box::pack_start() and Gtk::Box::pack_end() have been removed. Use the new Gtk::Box methods append(), prepend(), insert_child_after() and insert_child_at_start().
Gtk::ButtonBox has been removed.
Gtk::RadioButton and Gtk::RadioButtonGroup have been removed. Use Gtk::CheckButton or Gtk::ToggleButton with set_group().

All deprecated API was removed in gtkmm 4.0 and glibmm 2.68, though there will be new deprecations in future versions.

As a first step to porting your source code to gtkmm-4.0 you should probably ensure that your application builds with the deprecated gtkmm-3.0 and glibmm-2.4 API disabled, by defining the macros GTKMM_DISABLE_DEPRECATED, GDKMM_DISABLE_DEPRECATED, GLIBMM_DISABLE_DEPRECATED and GIOMM_DISABLE_DEPRECATED. There are some autotools macros that can help with this by defining them optionally at build time. See the Porting from gtkmm-2.4 to gtkmm-3.0 wiki page for more details.

Deprecations in gtkmm 4.10

Many classes are deprecated since gtkmm 4.10. They can still be used in gtkmm4 applications, provided GTKMM_DISABLE_DEPRECATED and GDKMM_DISABLE_DEPRECATED are not defined. There are also many new classes in gtkmm 4.10, which replace some of the deprecated classes. Some example programs in this tutorial use classes deprecated since gtkmm 4.10. Some other programs use classes available since gtkmm 4.10.

Deprecated classes: AppChooser, AppChooserButton, AppChooserDialog, AppChooserWidget, CellArea, CellAreaBox, CellAreaContext, CellLayout, CellRenderer, CellRendererAccel, CellRendererCombo, CellRendererPixbuf, CellRendererProgress, CellRendererSpin, CellRendererSpinner, CellRendererText, CellRendererToggle, CellView, ComboBox, ComboBoxText, EntryCompletion, IconView, ListStore, ListViewText, StyleContext, TreeDragDest, TreeDragSource, TreeIter and other classes in treeiter.h, TreeModel, TreeModelFilter, TreeModelSort, TreePath, TreeRowReference, TreeSelection, TreeSortable, TreeStore, TreeView, TreeViewColumn, namespace CellRenderer_Generation, namespace TreeView_Private, ColorButton, ColorChooser, ColorChooserDialog, FileChooser, FileChooserDialog, FileChooserNative, FileChooserWidget, FontButton, FontChooser, FontChooserDialog, FontChooserWidget, MessageDialog, TreeModelColumn, TreeModelColumnRecord, InfoBar, Assistant, AssistantPage, LockButton, Statusbar, VolumeButton.

New classes and enums: AlertDialog, ColorDialog, ColorDialogButton, ColumnViewSorter, FileDialog, FontDialog, FontDialogButton, FileLauncher, UriLauncher, ATContext, enums DialogError, FontLevel, Collation.

In most cases there are replacements for the deprecated classes. See the reference documentation.