Differences

This shows you the differences between two versions of the page.

Link to this comparison view

panelappletdevelopment [2015/10/03 14:54]
 panelappletdevelopment [2015/10/03 14:54] (current)
Line 1: Line 1:
 +====== 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:
 +
 +<​code>​
 +cd <​ede-src>/​ede-panel/​applets
 +mkdir cool-applet
 +</​code>​
 +
 +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:
 +
 +<​code>​
 +...
 +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 ;
 +</​code>​
 +
 +Now, inside applet folder (''<​ede-src>/​ede-panel/​applets/​cool-applet''​),​ create Jamfile with the following content:
 +
 +<​code>​
 +SubDir TOP ede-panel applets cool-applet ;
 +PanelApplet cool-applet : CoolApplet.cpp ;
 +</​code>​
 +
 +''​%%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:
 +
 +<code cpp>
 +#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"
 +)
 +</​code>​
 +
 +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:
 +
 +<code cpp>
 +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 */
 +)
 +</​code>​
 +
 +====== 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
  

Trace:

Print/export