Panel Applet Library Reference Manual: Making the Applet Visible to the Panel

Making the Applet Visible to the Panel

Simply installing the applet binary will obviously not be enough to make this applet working in the panel. Two files should be installed for this:

a .panel-applet file so that the panel knows that the applet.
a D-Bus service file to autostart the binary when the panel wants to create an applet.

Panel Applet File

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

Example

[Applet Factory]
Id=HelloWorldFactory
Name=Hello World Applet Factory
Description=Factory for the window navigation related applets

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

Format

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. You can fetch this directory during configure withe following code:

LIBPANEL_APPLET_DIR=`$PKG_CONFIG --variable=libpanel_applet_dir libpanel-applet`
AC_SUBST(LIBPANEL_APPLET_DIR)

D-Bus Service File

The communication between the panel and the applet factory is done over D-Bus. When creating an applet, the panel will send a message to the D-Bus service of the applet factory. If the D-Bus service is not running yet, it must be started automatically. We use D-Bus activation for this, which requires install a standard D-Bus service file. Please refer to the D-Bus documentation for more information about D-Bus service files.

This is only needed for out-of-process applets, because in-process applets do no need to have their binary autostarted for obvious reasons.