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

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

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:

1. `Glib::ExtraClassInit` and `Gtk::Snapshot`: These classes are needed only for writing custom widgets. See the Custom Widgets section.
2. `Gtk::EventControllerKey`, `Gtk::EventControllerMotion`, `Gtk::EventControllerScroll` and `Gtk::GestureStylus`
3. `Gdk::Paintable`, `Gdk::Texture`, `Gtk::Picture` and `Gtk::WidgetPaintable`
4. `Gdk::Window` has been renamed to `Gdk::Surface`. (`Gtk::Window` keeps its name.)
5. `Gdk::DrawContext` and `Gdk::CairoContext` are new. `Gdk::DrawingContext` has been removed.
6. `Gtk::Clipboard` has been replaced by the new `Gdk::Clipboard`.
7. `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:

1. A C++17 compiler is required.
2. `Gtk::Button`, `Gtk::ToolButton`, `Gtk::MenuItem` and `Gtk::Switch` implement the `Gtk::Actionable` interface instead of the removed `Gtk::Activatable` interface.
3. `Gtk::FontButton` implements the `Gtk::FontChooser` interface.
4. `Gtk::Widget`: The `get_preferred_*_vfunc()`s have been replaced by `measure_vfunc()`. This change only affects custom widgets.
5. `sigc::slot`s use the `sigc::slot<R(Args...)>` syntax. Example: `sigc::slot<void(int, int)>` instead of `sigc::slot<void, int, int>`.
6. `Gtk::DrawingArea` uses a draw function instead of the draw signal.
7. `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`.
8. `Gtk::Container` has been removed.
9. `Gtk::Widget::show_all()` has been removed. The default value of `Gtk::Widget::property_visible()` has been changed from `false` to `true`.
10. 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()`.
11. `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.
12. `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()`.
13. `Gtk::ButtonBox` has been removed.
14. `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.

See also Migrating from GTK 3.x to GTK 4.

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

Chapter 4. Changes in gtkmm 3 |  | Chapter 6. Buttons