Launchers

elementary.io Blog Human Interface Guidelines Contributor Guide
Search…
Launchers
Adding Badges, Progress Bars, and Quick Lists
Applications can show additional information in the dock as well as the application menu. This makes the application feel more integrated into the system and give user it's status at a glance. See HIG for Dock integration for what you should do and what you shouldn't.
For this integration you can use the Granite.Services.Application API. Since it uses the same D-Bus path as the Unity Launcher API, the API can work across many different distributions as it is widely supported by third party applications.
Current API support:
Service
Badge Counter
Progress Bar
Actions
Applications Menu
✔️ Yes
✖️ No
✔️ Yes
Dock
✔️ Yes
✔️ Yes
✔️ Yes
Setting Up
Before writing any code, you must add the library Granite to your build system. We already installed this library during The Basic Setup when we installed elementary-sdk. Open your meson.build file and add the new dependency to the executable method.
executable(
    meson.project_name(),
    'src/Application.vala',
    dependencies: [
        dependency('gtk+-3.0'),
        dependency('granite', version: '>=5.2.4') # 5.2.4 is the first release to support the Launcher API
    ],
    install: true
)
Your app must also be a Gtk.Application with a correctly set application_id as we previously set up in Hello World.
Though we haven't made any changes to our source code yet, change into your build directory and run ninja to build your project. It should still build without any errors. If you do encounter errors, double check your changes and resolve them before continuing.
Once you've set up granite in your build system and created a new Gtk.Application with an application_id, it's time to write some code.
Badges
Showing a badge in the dock and Applications Menu with the number 12 can be done with the following lines:
Granite.Services.Application.set_badge_visible.begin (true);
Granite.Services.Application.set_badge.begin (12);
Keep in mind you have to set the set_badge_visible property to true, and use an int64 type for the set_badge property. The suffix .begin is required here since these are asynchronous methods.
Progress Bars
The same goes for showing a progress bar, here we show a progress bar showing 20% progress:
Granite.Services.Application.set_progress_visible.begin (true);
Granite.Services.Application.set_progress.begin (0.2f);
As you can see, the method set_progress takes a double value type and is a range between 0 and 1: from 0% to 100%. As with badges, Don't forget that set_progress_visible must be true and .begin is required for asynchronous methods.
Actions
Actions are specific functions your app can perform without already being open; think of them as alternate and more specific entry points into your app. Actions appear in the context menu of your app icon in the Applications Menu and Dock, and are searchable by name from the Applications Menu.
Adding actions to a .desktop file does not involve writing any code or using any external dependencies, though your app needs a way to distinguish between actions, e.g. with command line flags.
Actions must first be declared in a new Actions line in your app's .desktop file. This line should contain a ; separated list of unique action names:
[Desktop Entry]
Name=Hello Again
[...]
Actions=ActionID;
Then below, add the action itself using the same unique ID:
[Desktop Action ActionID]
Name=The name of the action
Icon=com.github.myteam.myapp.action-id
Exec=com.github.myteam.myapp --action-id
The Icon line is optional and should be an icon which represents the action that will be performed. The Exec line is required and should be your app's executable name and any command line argument required to trigger the action.
The action name should not include your app's name, as it will always be displayed alongside your app. The action icon should also not be your app icon, as it may be shown in the menu for your app icon, or badged on top of the app icon.
Let's take a look at an example of an action that opens a new window of an app:
[Desktop Entry]
Name=App Name
Exec=com.github.yourusername.yourrepositoryname
...
Actions=NewWindow;
​
[Desktop Action NewWindow]
Name=New Window
Exec=com.github.yourusername.yourrepositoryname -n
Note that just adding -n or any other argument will not automatically make your app open a new window; your app must handle and interpret command line arguments. The GLib.Application API provides many examples and an extensive documentation on how to handle these arguments, particularly the command_line signal.
See the freedesktop.org Additional applications actions section for a detailed description of what keys are supported and what they do.
Last modified 4mo ago
Export as PDF
Copy link
Edit on GitHub
Outline