Integration

Older Gtk applications that aren't based around GApplication can be adapted to use the macOS menu bar and to integrate with the Dock using GtkOSXApplication. The Gtk API that GtkOSXApplication uses is deprecated in Gtk3 and has been removed from Gtk4. Since macOS integration is available directly in Gtk using GApplication GtkOSXApplication will not be updated for the new menu API and is deprecated. Application maintainers are strongly encouraged to redesign their programs around GApplication, particularly before migrating to Gtk4.

Naming Note: Gtk-mac-integration reflects an old Carbon implementation that has been removed as Apple has removed most of the public Carbon API. It was called ige-mac-integration before being moved to Gnome from Github, and you will find older repositories on Github still using that name.

Documentation

GtkOSXApplication is fully documented via gtk-doc. To build the documentation in your installation, pass --enable-gtk-doc to configure. A current copy of the documentation can also be found here.

You'll find a test program at src/test-integration.c which exercises most of the features of each interface (depending on macro settings at the top of the file) which you can study.

Localization

GtkOSXApplication adds two menus, the Application menu (the one on the left with the application's name for a title) and optionally the Window menu, which include some standard menu items. Localization of these items is provided by gettext as usual for Gnome libraries.

Python

Apple Events

GtkOSXApplication provides a signal, NSApplicationOpenFile, to which you can connect to allow opening files from Finder.

Gedit has implemented an Application Delegate which handles the OpenFiles message from LaunchServices. This approach handles the file opening directly instead of emitting a signal; on the other hand, it requires more code in the application.

Menu Accelerators

Use the <Primary> descriptor in place of <Control> for accelerators and bindings. This will map the accelerator to Command on OSX and to Control for anything else. Otherwise, you can load an accelerator map with the OSX standard key codes. A template map file is provided in data/template_accel_map; you'll need to edit it to match the accel paths in your application. Instructions are in the comments.

It may be easier to insert gtk_accel_map_save("path")} at the point where you would put gtk_accel_map_load("path"), compile, and run once. That will give you a template accel-map file that you can edit (just replace every instance of <ctrl> with <primary> and uncomment the changed lines: The file format is based on Scheme, so the leading ';' is the comment token).

Support

Bugs and other issues should be reported on the gtk-mac-integration issue tracker; propose updates and fixes as merge requests at gtk-mac-integration merge requests. Support questions, general suggestions, and so on can be posted to discussion area at the maintainer's Github repo.