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.
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(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.
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.
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
1: from 0% to 100%. As with badges, Don't forget that
set_progress_visible must be
.begin is required for asynchronous methods.
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 actionIcon=com.github.myteam.myapp.action-idExec=com.github.myteam.myapp --action-id
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.
Let's take a look at an example of an action that opens a new window of an app:
[Desktop Entry]Name=App NameExec=com.github.yourusername.yourrepositoryname...Actions=NewWindow;[Desktop Action NewWindow]Name=New WindowExec=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.