Gtk – 4.0: Using GTK on Apple macOS
Description: Reference for Gtk-4.0: Using GTK on Apple macOS

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

## Menus

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. In addition, some default keyboard shortcuts are registered.

Name | Action | Shortcut
--- | --- | ---
Undo | `text.undo` | `⌘`-`z`
Redo | `text.redo` | `⌘`-`Shift`-`z`
Cut | `clipboard.cut` | `⌘`-`x`
Copy | `clipboard.copy` | `⌘`-`c`
Paste | `clipboard.paste` | `⌘`-`v`
Select All | `selection.select-all` | `⌘`-`a`

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.

The application menu shortcuts registered with GTK are:

Name | Action | Shortcut
--- | --- | ---
Settings | `app.preferences` | `⌘`-`,`
Quit | `app.quit` | `⌘`-`q`

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.

### Window menu

The Window menu is special in macOS: it provides a list of open windows and has options for moving and resizing windows. To automatically add those options to the Window menu, add the property `gtk-macos-special` with value `window-submenu`:

    <submenu>
      <attribute name="label" translatable="yes">_Window</attribute>
      <attribute name="gtk-macos-special">window-submenu</attribute>
    </submenu>

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

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.

## Vulkan support

GTK can be compiled with Vulkan support on macOS, via MoltenVK.

The macOS version links with the Vulkan loader library, and not with the vulkan library (MoltenVK) directly.

### Homebrew

Install the following packages to enable Vulkan support:

    brew install vulkan-loader shaderc molten-vk

### Vulkan SDK

Download the Vulkan SDK for macOS from LunarG. Set it up according to their instructions. Pay special attention to the environment variables that need to be set: `VULKAN_SDK`, `DYLD_LIBRARY_PATH`, `VK_ICD_FILENAMES`, and `VK_LAYER_PATH`. You can also use the provided `setup-env.sh` script in the SDK root folder.

## Publishing

GTK provides no means to package GTK applications (create a `.app`s out of them).

However, we can provide a few pointers.

GTK uses an OpenGL surface for drawing. On laptops with 2 GPU’s it will take the heavy (Radeon) GPU by default. If your app is not heavy on graphics, it may be better to use the more energy efficient built-in GPU instead. This can be configured by adding the following to the app’s `Info.plist`:

    <plist version="1.0">
      <dict>
        ...
        <key>NSSupportsAutomaticGraphicsSwitching</key>
        <true/>
        ...
      </dict>
    </plist>