Concepts: Panel Applet Reference Manual

## Concepts

In order to write an applet it is important to understand the relationships between GNOME Panel and your applets. For example, how are applets registered to the GNOME Panel? How does the GNOME Panel instantiate an applet?

On a typical desktop there can be multiple GNOME Panels and each GNOME Panel can have several instances of your applet. These different instances are created by an applet factory which must be registered to the GNOME Panel. Additionally, in order to identify your applet and instantiate the correct applet, each applet is identified by an applet type.

## Applet Registration

To make your applets and the applet factory known to GNOME Panel - so that it can show your applet in the list of applets of the "Add to Panel" dialog - and to add applets to the panel, you must create a Panel Applet File. Panel Applet files are introduced in more detail later in this document. However it is important for applet authors to understand the relationship between the panel applet file, the applet factory, and the applet type. Therefore this section contains a short example of a Panel Applet file.

### Panel Applet Files

Panel Applet files are `ini`-file formatted files that contain the necessary information about your factory and your applet types. The following example listing shows a simple Panel Applet file.

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

                           [HelloWorldApplet]
                           Name=Hello World
                           Description=The Hello World example applet
                           Icon=hello-world-icon

### Applet Types

The applet type is the identifier representing a type of applets to the panel. It is a simple string, like `HelloWorldApplet` and is unique per applet factory.

In the example listing above the applet type can be found in the second section title (e.g. `[HelloWorldApplet]`, but without the square brackets).

### Applet Factory

The applet factory is an implementation detail that is mostly hidden by the Panel Applet Library, but it still appears in a few places such as:

- The `PANEL_APPLET_OUT_PROCESS_FACTORY()` macro, which is used to build out process applets. It gets the factory id passed as its first parameter.

- The `PANEL_APPLET_IN_PROCESS_FACTORY()` macro, which is used to build in process applets. It gets the factory id passed as its first parameter.

- A Panel Applet file, which is used to register applet types and the applet factory to the GNOME Panel. It must contain the same applet factory id as used in the above two macros.

  By default applets are out-process, if you have used the `PANEL_APPLET_IN_PROCESS_FACTORY`, then you must add: `InProces=true` to the `[Applet Factory]` section.

The applet factory is the object that will create a new applet instance when the panel requests a new applet to be created. It is identified with a simple string id, for example `HelloWorldFactory`.

In the example listing above the applet factory id can be found in the `ID`-field of the `[Applet Factory]` section.

The requests the applet factory will receive from the GNOME Panel specify which type of applet should be created. This is what makes it possible to have more than one applet type in one applet binary. In most cases, however, the applet factory will be specific to only one applet type.

There is only one applet factory per applet binary, and it is always running before any applet instance is created by the applet binary. The applet factory is created via one of these two macros:

- `PANEL_APPLET_OUT_PROCESS_FACTORY()`

- `PANEL_APPLET_IN_PROCESS_FACTORY()`