This is an old revision of the document!


Panel Applet Development

This tutorial will show you how to write new panel (ede-panel) applet and integrate it with the rest of code and installation procedure. Tutorial also assumes how you downloaded and extracted EDE source code, as panel applets can't be built without it.

Directory structure

All panel applets exists inside '<ede-src>/ede-panel/applets'. For quick look, you can see demo applet already provided.

Our applet will be called 'cool-applet' so we will make subfolder inside applets folder, as:

cd <ede-src>/ede-panel/applets
mkdir cool-applet

Before we continue, make sure to append entry in Jamfile (<ede-src>/ede-panel/applets/Jamfile), stored inside applets folder so your applet can be compiled when ede-panel is built. This entry can look like:

...
SubInclude TOP ede-panel applets quick-launch ;
SubInclude TOP ede-panel applets start-menu ;
SubInclude TOP ede-panel applets system-tray ;
SubInclude TOP ede-panel applets taskbar ;

# your applet
SubInclude TOP ede-panel applets cool-applet ;

Now, inside applet folder (<ede-src>/ede-panel/applets/cool-applet), create Jamfile with the following content:

SubDir TOP ede-panel applets cool-applet ;
PanelApplet cool-applet : CoolApplet.cpp ;

SubDir rule will tell jam how to find correct path to applet folder and custom PanelApplet rule will do the real job: compile applet source and create cool-applet.so file, a shared library loaded by ede-panel.

:!: PanelApplet rule will automatically append .so extension; if you explicitly append it, you will end up with cool-applet.so.so file.

Applet content

Now we can start writing applet itself. Create CoolApplet.cpp file and put this content:

#include "Applet.h"
 
#include <FL/Fl_Button.H>
#include <edelib/MessageBox.h>
 
EDELIB_NS_USE(message)
 
static void applet_cb(Fl_Widget*, void*) {
    message("Hola from applet");
}
 
class CoolApplet : public Fl_Button {
public:
    CoolApplet() : Fl_Button(0, 0, 90, 25, "!") {
       callback(applet_cb);
    }
};
 
EDE_PANEL_APPLET_EXPORT (
 CoolApplet, 
 EDE_PANEL_APPLET_OPTION_ALIGN_RIGHT,
 "My first cool applet",
 "0.1",
 "empty",
 "Your Name"
)

By including Applet.h (it exists in ede-panel folder, but jam rule PanelApplet will correctly set include path so you don't have to explicitly tell where it is) you will gain access to facility for creating applets. If you look carefully, applets are nothing more than plain FLTK widgets, loaded on runtime and shown on panel.

Next lines shouldn't be strange: EdelibBasics and HandlingEvents already gave you insight what is happening behind EDELIB_NS_USE and callbacks. However, you should notice how we are creating widget with default coordinates and size: panel will use empty constructor to create applet objects so make sure you have it, or strange runtime errors can happen.

In our example, we are using 0, 0 for X and Y position and 90, 25 for width and height: panel is using simple layout engine so it doesn't need coordinates to store applet. Also, width and height can be changed as panel grows or shrinks, so your applet should be aware of possible resizing, especially if you draw custom graphics inside applet.

Important part of every applet is 'EDE_PANEL_APPLET_EXPORT'. This macro will create needed routines so panel knows how to load applet and what to load with additional metadata like author, version and icon for applet dialog (which isn't completed yet).

Arguments are:

EDE_PANEL_APPLET_EXPORT (
 CoolApplet,                           /* applet class, must be FLTK or edelib widget */
 EDE_PANEL_APPLET_OPTION_ALIGN_RIGHT,  /* layout options, explained below */
 "My first cool applet",               /* applet description */
 "0.1",                                /* applet version as C string */
 "empty",                              /* icon for applet, read from icon theme */
 "Your Name"                           /* author name */
)

Applet class

Applet class can be any class that inherits Fl_Widget at some point of inheritance chain. For example, applet class can inherit Fl_Button, Fl_Group or Fl_Box but you are not limited to these. However, be aware how big class can impact on panel memory usage.

Layout options

Applet on panel can be aligned left or right, and is placed in stacking order. This means first loaded applet which have EDE_PANEL_APPLET_OPTION_ALIGN_LEFT will be the left most, the comes second with that option and etc. The same applies for applets with EDE_PANEL_APPLET_OPTION_ALIGN_RIGHT, but from right side.

Also you can specify how panel will resize applet; by adding EDE_PANEL_APPLET_OPTION_RESIZABLE_H option, applet will fill all empty panel width space. By default, applets are not resizable and will be drawn to exact bounds given in applet code.

All applet options are OR-able, so to align it right and make resizable by width you will use EDE_PANEL_APPLET_OPTION_ALIGN_RIGHT | EDE_PANEL_APPLET_OPTION_RESIZABLE_H.

The following are options you can use:

  • EDE_PANEL_APPLET_OPTION_ALIGN_RIGHT - align applet to the right side
  • EDE_PANEL_APPLET_OPTION_ALIGN_LEFT - align applet to the left size
  • EDE_PANEL_APPLET_OPTION_RESIZABLE_H - resize it horizontally
  • EDE_PANEL_APPLET_OPTION_RESIZABLE_V - resize it vertically
Print/export