Status Icon Migration: Application Design Guidelines

These guidelines are intended for application developers who currently use a status icon or are considering using one. For a full set of application design guidelines, please see the GNOME Human Interface Guidelines.

General status icon guidelines

There are effective alternatives for all the traditional uses of status icons, and these can be used to design fantastic applications. Status icons also have certain issues associated with them. Status icons therefore shouldn't be necessary and should be avoided if possible.

Additionally, from 3.26 status icons will not be shown by default in GNOME. This means that, even if an application does use a status icon, it might not be visible or accessible. It is therefore important to ensure that applications can be successfully used with our without the status icon.

The rest of this page provides a set of simple guidelines that allow any application to be used without a status icon. Applications that continue to use a status icon should also follow these additional steps:

• Ensure that all application functionality can be accessed from the application's windows, and that no actions or options are only in the status icon menu.
• Don't refer to the status icon in your user interface. This includes references to "minimize to tray" behavior.

Primary windows

Every application should always have a primary window and this window should always be raised when the application is launched. This is important, as it ensures consistent and predictable behavior. The GNOME Human Interface Guidelines provide more information on this.

Notifications

GNOME 3 has a powerful and effective notification system. This has a notifications list, so users can see a history of the notifications that have been shown, and each notification can have actions attached to it. This notifications system is the recommended way to inform users about events, and effectively replaces the use of status icons in many cases.

The GNOME Human Interface Guidelines include guidelines about how to effectively use notifications. It is particularly important to set a default action on each notification, so that your application's window is shown when a user clicks on a notification.

Notifications should also be used even when an application uses a status icon.

Use specialised integration APIs

GNOME 3 supports several APIs which particular types of application can use to provide functionality that was previously provided by status icons:

• Media controls: media player applications can use MPRIS to show media playback controls in the time dropdown.

Running in the background

In some cases it is appropriate for an application to continue to run after all its windows have been closed. This can include chat and messaging applications, reader applications that alert users about new content, or scheduling or organisation apps that show reminders. Status icons have traditionally been used for this purpose. However, they are not necessary.

Applications that want to continue to run after their windows have been closed should simply continue to run. However, they should only do so if they genuinely run in the background and don't have a noticeable impact on the user's experience. Applications that use a noticeable amount of system resources shouldn't run in the background.

Notifications should be the only way that an application interacts with the user while it runs in the background: the application shouldn't show anything else on screen, and no audio should be played, including notification sounds or audio playback (running in the background isn't recommended for music player applications for this reason).

Chat applications might want to ask the user to confirm whether they should run in the background when their final window is closed. This clarifies that the user won't be logged out of the chat service.

Checking if the environment supports status icons

To ease the transition, if you need to check if the environment your app is running on has support for status icons and act accordingly, the following steps are needed:

1. If you use libappindicator you can check if the D-Bus name org.kde.StatusNotifierWatcher is owned. If so then appindicators are supported in the environment.

2. If the previous check says the D-Bus name is not present or you don't use libappindicator you can check if tray support is present. You can use the API's provided by GTK+ or Qt directly or you can use Xlib to check like this C example here.