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


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

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::slots 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.