Comment on page
Adding Badges, Progress Bars, and launching Actions
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.
Though we haven't made any changes to our source code yet, change into your build directory and run
ninjato 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
granitein your build system and created a new
application_id, it's time to write some code.
Showing a badge in the dock and Applications Menu with the number
12can be done with the following lines:
Keep in mind you have to set the
set_badge_visibleproperty to true, and use an int64 type for the
set_badgeproperty. The suffix
.beginis required here since these are asynchronous methods.
The same goes for showing a progress bar, here we show a progress bar showing 20% progress:
As you can see, the method
doublevalue type and is a range between
1: from 0% to 100%. As with badges, Don't forget that
.beginis 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.
Your app needs to support D-Bus activation in order to use actions as entry points. This does not require any changes to the application source code. All that is needed is a service file which is not unlike the
.desktopfile that you are already familiar with. Create a new
.servicefile in the
To install the service add the following to your
# Install D-Bus service, so that application can be started by D-Bus
'data' / 'myapp.service',
install_dir: get_option('datadir') / 'dbus-1' / 'services',
rename: meson.project_name() + '.service',
Lastly, update the
.desktopfile by adding the
DBusActivatableline to the
You can use any action defined in the
appnamespace, i.e. registered with
GLib.Application, as an entry point for your application. Implementing actions is covered in-depth in the actions section. They must also be declared in a new
Actionsline in your app's
.desktopfile. This line should contain a
;separated list of action names:
Then use a dedicated group, named after the unique action name, to define the details of each action:
[Desktop Action my-action]
Name=My Great Action
The action name used in
.desktopfile, both in Desktop Entry and later in Desktop Action groups, needs to match exactly the name used to register the action with
GLib.Applicationin the source code.
Iconline is optional and should be an icon which represents the action that will be performed. The
Execline should be specified, but is used only for backwards compatibility in case your app ever runs in an environment without D-Bus activation support.
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.