This is the first article of the series, "Writing GNOME Panel Applets". We will go through the basic steps you need to know so you can successfully write an applet for the GNOME panel. We will finish this first article by looking at a very simple program example you can build, and going through it line by line. For a download of the latest version of GTK+ just click here

The GNOME panel plays a very important role in the GNOME desktop environment. It is a neat piece of software to which you can add menus and launchers for quick access to your favorite utilities and programs. You can also add small programs, known as applets. Applets are designed just as any other "real" program, but with the critical difference that they are not assigned to a window of their own (as with "real" Gnome applications). Instead, applets get a small area of the panel, from which they can be controlled. This means you can work with your "real" applications on the desktop, and still have access to your favorite mp3-player, system monitor, or whatever you like to have on your panel. Most people have at least two applets on their GNOME panel: the pager and the date/time applet.

In Figure 1 you can see the elements of a standard GNOME panel with labels. The elements on this panel are, from left to right, the GNOME menu, a few launchers, the pager, the task-list applet, and the date/time applet.

Writing Your First Applet Panel
Writing your own panel applet is not hard at all. Actually, developing applets is very similar to developing standard GNOME/Gtk+ programs. You see, many of Gtk+'s functions have corresponding alternatives in the applet library libpanel_applet, and this makes it very easy to go from developing usual Gnome applications to panel applets. Let's take a look at a simple example.

1:  #include <applet-widget.h>
2:  
3:  int main( int argc, char **argv ) 
4:  { 
5: 	/* Allocate memory for two GtkWidgets. */ 
6: 	GtkWidget *applet; 
7:	GtkWidget *label; 
8: 
9:	/* Set up the applet, CORBA and call gnome_init() */ 
10:	applet_widget_init( "BeOpenApplet", NULL, argc, argv, 
11:			     	NULL, 0, NULL ); 
12: 
13:	/* Create a new applet widget. */ 
14:	applet = applet_widget_new( "BeOpenApplet" ); 
15: 
16:	/* Create the text label to put in the widget. */ 
17:	label = gtk_label_new( "BeOpen" ); 
18: 
19:	/* Add the label to the applet widget. It's this */ 
20:	/* line that actually adds the text to the panel. */ 
21:	applet_widget_add( APPLET_WIDGET(applet), label ); 
22: 
23:	/* Show the applet widget and all its children. */
24:	/* Note that the only child is the label. */ 
25:	gtk_widget_show_all( applet ); 
26: 
27:	/* Call the special applet main loop. */ 
28:	applet_widget_gtk_main(); 
29: }

Now, let's go through this very simple panel applet, line by line.

On line 1, the applet-widget.h header file is included. This file holds the definitions for the AppletWidget structure, and the various functions that you can use with AppletWidget.

On lines 6 and 7, we allocate memory for two GtkWidget instances. These are used later for creating the actual applet, and for the label to put on the applet.

On line 10, we call the applet_widget_init() function. This function initializes the applet, and calls gnome_init(). It takes several arguments, but you only have to bother about the first one, "BeOpenApplet", at this point. This is the applet id, and you need this to create the AppletWidget instance. Note that applet_widget_init() has the same function as do gtk_init() and gnome_init() in customary GNOME/Gtk+ programs.

On line 14, the applet continues by creating the AppletWidget instance. This is done by using the applet_widget_new() function. Note that the applet id is passed as an argument.

On line 17, the GtkLabel instance is created by using the gtk_label_new() function. The argument represents the text you want to show. It should be said, however, that using GtkLabel instances for showng text on-screen is not applet-specific - this is often done in standard GNOME/Gtk+ programs as well.

On line 21, the label is inserted into the applet (the panel). This is done by the applet_widget_add() function. It takes two arguments: the first represents the applet into which you want to insert something, and the second represents the object you want to insert. It's this line that actually adds the text to the panel.

On line 25, we make sure that applet, and all its children are shown on-screen. This is done by calling the gtk_widget_show_all() function, and passing applet as the only argument.

Finally, on line 28, the special applet main loop is started by calling the applet_widget_gtk_main() function. Calling this function does the same as a call to gtk_main() does in normal GNOME programs.

Now, to save the example program to your hard drive, right-click on this link and choose "Save link as..." (for Internet Explorer right-click and choose "Save Target As..."). A dialog box will now appear in which you can select where on your file system the file will be saved. When you're satisfied with the options in the dialog box, click the "OK" button.

Compiling And Running A Panel Applet
As stated earlier, the AppletWidget structure and its functions are defined in a library of their own, called libpanel_applet. Therefore, to compile an applet, you need to link with this library. It's really simple though. Just open a new terminal, go to the directory where you saved the previous shown example, and then issue the following command:

gcc `gnome-config --cflags applets` `gnome-config --libs applets` lst1.c -o lst1

Of course, if you used any filename other than lst1.c, you need to change the command accordingly. This will, however, compile and link the program into an executable called lst1. If you get error messages from the compiler, make sure you have the GNOME development packages installed, and that your version of the source code looks exactly as it appears in this article.

When you have managed to compile the program correctly, you're ready to start it. How this is done depends on what you chose to call the executable. But, if you issued the compilation command exactly as shown above, you start the applet with the following command:

./lst1

Now, the applet will initialize, create the label, and then show it on the panel (of course, you need to have GNOME running for this to work). The result is also shown in Figure 2.

As you probably have guessed, this simple applet just adds the text BeOpen to the panel. It is, however, a real GNOME panel applet. It doesn't have any actual functions, but it can be moved on the panel by right-clicking on it and then choose Move on the menu that pops up.

Well, congratulations on your first GNOME panel applet! Now that you've seen how easy they are to build we hope you'll be inspired to return to the next article in our applet series as we add functionality. See you there!