Using GTK on Apple macOS [src]

The Apple macOS port of GTK is an implementation of GDK (and therefore GTK) on top of the Quartz API.

Currently, the macOS port does not use any additional commandline options or environment variables.

For up-to-date information on building, installation, and bundling, see the GTK website.

By default a GTK app shows an app menu and an edit menu. To make menu actions work well with native windows, such as a file dialog, the most common edit commands are treated special:

  • text.undo
  • text.redo
  • clipboard.cut
  • clipboard.copy
  • clipboard.paste
  • selection.select-all

Those actions map to their respective macOS counterparts. The actions are enabled in GTK if the action is available on the focused widget and is enabled.

To extend the macOS system menu, add application and window actions to the application with Application.set_accels_for_action(). The menubar can be configured via Application.set_menubar(). Those actions can then be activated from the menu.

Native window controls

By default, GTK applications use common window decorators (close/minimize/maximize) on all platforms. They show as grey rounded buttons on the top-right corner of the window.

Since GTK 4.18, GtkHeaderBar has the option to use native window controls. The controls are positioned in their normal place: the top-left corner. This feature can be enabled by setting the property use-native-controls to TRUE on a GtkHeaderBar. The property decoration-layout can be used to enable/disable buttons.

The GTK demo application with macOS native window controls

Native window controls are an opt-in feature. If you want a more macOS native experience for your app, it’s up to you to make sure all windows have native controls. You’ll need to pay special attention in case of split header bars, since only the leftmost header bar should support the native window controls.

Window decorators only work for normal, toplevel windows.

Important

Native window controls are drawn on top of the window, and are not controlled by GTK. It’s up to you, the application developer, to make sure the header bar that “contain” the native window controls, and occupy the space below the window controls.

Content types

While GTK uses MIME types, macOS uses Unified Type descriptors. GTK maps MIME to UTI types.

If you create a macOS app for your application, you can provide custom UTI/MIME types mappings in the Information Property List for your application.