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.
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 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.
1 2 3 4 5 6 7 8 9 |
[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 |
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).
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()
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()