Applet Registration, Installation and Build System: Panel Applet Reference Manual

Applet Registration, Installation and Build System

Simply installing the applet binary will obviously not be enough. The applet also needs to be registered to the panel. In order to do this you need to provide a Panel Applet File. Panel Applet files are ini-style text files with an extension named .panel-applet.

If you are creating an out-process applet, then you also need to provide a D-Bus service file to automatically start the binary when the panel wants to create an applet.

This chapter explains the syntax of .panel-applet files and gives the necessary information to setup the build system in order to install all the required parts of the applet on the system. For the build system part it is assumed that GNU Autotools (e.g. autoconf and automake) are used.

Panel Applet File Syntax

The .panel-applet file is a key file about the applet binary, describing the applet factory of the binary and the applet types this factory can create.

Panel Applet File Example

[Applet Factory]
Id=HelloWorldFactory
Name=Hello World Applet Factory
Description=Factory for the our example applets

[HelloWorldApplet]
Name=Hello World
Description=Factory for the Hello World example applet
Icon=hello-world-icon

File Format and well known Fields

The file must contain a Applet Factory group with the following keys:

Id (string): the identifier of the applet factory. This must be the same name that will be used as the first parameter to PANEL_APPLET_OUT_PROCESS_FACTORY() or PANEL_APPLET_IN_PROCESS_FACTORY().
InProcess (boolean, optional): whether the applet should be in-process or out-of-process. By default, the applet is out-of-process.
Location (string): the path to the applet binary. Only mandatory if InProcess is true.
Name (localized string, optional): the name of the applet factory. For example: Hello World Factory.
Description (localized string, optional): the description of the applet factory. For example: Factory for the Hello World applet example.

For each applet type, it must also contain a group named with the applet type identifier. Such a group must have the following keys:

Name (localized string): the name of the applet type. For example: Hello World.
Description (localized string, optional): the description of the applet type. For example: Hello World applet example.
Icon (string, optional): the icon name of the applet type. For example: hello-world-icon. It can also be the path to an icon, but this not recommended.

Installation

The .panel-applet file must be installed in a specific directory to be discoverable by the panel. The exact path of this directory can be queried with pkg-config:

1	pkg-config --variable=libpanel_applet_dir libpanel-applet

The path depends on how GNOME Panel was compiled and installed so it could be different depending on which Linux distribution is used. Therefore never hard-code the path in your build system but use he above command instead. Please see the Build System section for more information on how install a Panel Applet file with autotools.