Contents

Tray

This page describes how to create, configure, and show a tray item in the system tray on macOS and notification area on Windows.

You can create in your application multiple tray items, each with its own icon, title, and menu. On macOS and Ubuntu the tray item is shown in the system tray located in the top right corner of your screen. On Windows it is shown in the notification area that is usually located in the bottom right corner of your screen.

The tray items are shared between all windows of your application, and you can manipulate them whether a window is visible or not. The tray items is a great way to let users run your application in the background and let them re-open the window easily.

Creating a tray item

To create and show a tray item, use the following approach:

auto tray = Tray::create(app);
tray->setImage(app->getPath(PathKey::kAppResources) + "/image.png");

This method creates and shows a tray item with the image located in the application resources directory.

The tray item is a native resource that must be released when it is no longer needed. If you don’t need to show the tray item anymore, you can hide and destroy it using the following approach:

tray->destroy();

All created tray items are automatically destroyed when the application is closed.

Tray image

Usually the tray item shows an image that is associated with your application. To set the tray image, use the Tray::setImage() method that accepts the absolute path to the image file. For example:

tray->setImage("absolute/path/to/image.png");

We recommend that you always put the tray image into the application resources directory and use the following approach to get an absolute path to the image file relative to the application resources directory:

tray->setImage(app->getPath(PathKey::kAppResources) + "/image.png");

All the files and directories from the application resources directory will be copied to the application bundle. This approach allows you to use the same code on all platforms. You will always know where the image file is located, and you don’t need to worry about the absolute path to the image file on different platforms.

High resolution image

The tray item can display a high resolution image on high resolution displays. To do this, you need to provide a high resolution image file. The high resolution image file must have the same name as the regular image file, but with the @2x suffix.

For example, if the regular image file is image.png, then the high resolution image file must be image@2x.png.

If you need to support displays with different DPI densities at the same time, you can provide multiple high resolution image files with the same file name except the DPI suffixes located in the same folder. For example:

src-cpp/
|-- resources/
|   `-- image.png
|   `-- image@1.5x.png
|   `-- image@2x.png

In your application code, you can set the tray image using the path to the basic image.png file:

tray->setImage(app->getPath(PathKey::kAppResources) + "/image.png");

Molybden, will load other high resolution image files automatically depending on the DPI density of the display.

The following DPI suffixes are supported:

  • @1x - 100% DPI density.
  • @1.25x - 125% DPI density.
  • @1.5x - 150% DPI density.
  • @1.75x - 175% DPI density.
  • @2x - 200% DPI density.

Template image

On macOS, you can use a template image for the tray item. The template image is a monochrome image that is used to create a color image that is displayed in the system tray. The template image is usually black and transparent. The black color is replaced with the system tray color.

Tray image macOS dark Tray image macOS light

To mark an image as a template image, you need to add the Template suffix to the image file name. For example, if the regular image file is image.png, then the template image file must be imageTemplate.png.

You can use the DPI suffixes for the template image file too. For example:

src-cpp/
|-- resources/
|   `-- imageTemplate.png
|   `-- imageTemplate@2x.png

Tray title

On macOS the tray item can show an image, a title, or both an image and title.

To set the tray title, use the Tray::setTitle() method that accepts a string value. For example:

tray->setTitle("MyApp");

The title will be displayed next to the tray image if the image is set.

Tray image and title

If the image is not set, only the title will be displayed.

Tray title

Tray tooltip

The tray item can show a tooltip when the user hovers the mouse over the tray item. To set the tray tooltip, use the Tray::setTooltip() method that accepts a string value. For example:

tray->setTooltip("MyApp");

Tray menu

The tray item can show a menu when the user clicks the tray item. To set the tray menu, use the Tray::setMenu() method that accepts a menu object. You can add the standard menu or custom menu items to the tray menu. For example:

tray->setMenu(CustomMenu::create({
    menu::Item("New Window", [app](const CustomMenuItemActionArgs& args) {
         auto browser = Browser::create(app);
         browser->loadUrl("teamdev.com/molybden");
         browser->show();
     }),
     menu::Separator(),
     menu::MacQuitApp()
}));

Here’s how the tray menu will look like on macOS:

Tray menu macOS

Tray events

In some cases you might not need to show a tray manu when user clicks the tray item. Instead, you might want to perform some other action. For example, you might want to show the application window when user clicks the tray item. To do this, you can register an event listener to get notifications when the user clicks the tray item. For example:

tray->onClicked += [](const TrayClicked& event) {
  // Show application window here.
};

Important: the event will be invoked only if the tray item doesn’t have a menu.

On this page
Top