Home Forums Wiki Doc Install Extras Screenshots Source Code Projects Blog Users Groups Register
Glx-Dock / Cairo-Dock Wiki Write an applet
The latest stable release is the *3.4.0* : How to install it here.
Note: We just switched from BZR to Git on Github! (only to host the code and your future pull requests)
Information : The version displayed on this page is not the latest available.
History View code

Glx-Dock / Cairo-Dock




en English

fr Français

ru Russian

Support Us

Flattr this


Write an applet

Cairo-dock put at your disposal a framework dedicated to quickly writing standardized applets.

Let's say that one wants to write an applet (let us call it “truc”):

Let's go in the repertory “plug-ins” of the sources.
Inside is a [i]generate-new-applet.sh[/i] script.
Launch it and answer some questions. At this point you have a functional applet !
To go further, let us look at the 3 important points:

Structure of the applet

Tree structure of the sources
The tree structure of the sources is basic and can be copied from any existing applet:

truc ---> configure.ac, Makefile.am
+--> src -> applet-init.c/h, applet-config.c/h, applet-notifications.c/h, *.c/h
+--> data -> trick.conf.in, preview.png, readme, *
+--> po -> Makefile.in.in, LINGUAS, POTFILES.in, *.po

The names of the files are not imposed, but respecting these conventions will make it possible to immediately find your way around for any applets even the one you don't know about.

Repertory of the sources
In ./src, we have :

- applet-init.c : contains the function to initialize the applet, and the function to stop it.
- applet-config.c : contains the function which reads the config file.
- applet-notifications.c : contains the functions which are called when the applet is notified by Cairo-Dock that something interesting has happened.
- *.c : the others can contain everything you need (connection to a server, functions of drawings, calculations, etc...)

Repertory of the data
In --./data-- we find :
- preview.png : a picture giving a preview of the applet (posted in the config panel of Cairo-Dock beside the list of applets)
- readme : a file giving the author of the applet (you; -)), and a short summary of this one (the text will be also posted in config panel of Cairo-Dock)
- truc.conf : the config file of the applet, which contains all the parameters that the user can change

Repertory of the translations
In ./po we have :
- Makefile.in.in : to begin with take a pre existing one.
- LINGUAS : the list of the available languages.
- POTFILES.in : the list of the files where one finds messages to be translated.
- *.po : files containing the translations of each message.

Tree structure of the installation
The tree structure of the installation is very simple :
- the contents of the repertory "data" will be copied in /usr/share/cairo-dock/plug-ins/truc
- the plug-in itself will be in /usr/share/cairo-dock/plug-ins/libcd-truc.so
- the translation files will go in /usr/share/locale/$lang/LC_MESSAGES/cd-truc.mo, where $lang = fr, jp, ...

Compilation files

--As above take existing ones and replace with your applet names wherever necessary.--

configure.ac contains several macros specific to autoconf/automake as well as variables definition:
- AC_INIT : Carefully define the version number of the applet, the name of the author of the applet (you!) and the name of the plugins (to avoid potential conflict with an existing library on your system, prefix the name with 'cd-' : cd-truc)
- GETTEXT_PACKAGE : Usually you will enter the name of the applet ('cd-truc'), this will create a translation file 'cd-truc.mo'

- pkgdatadir : overwrite the default value with one given by Cairo-Dock so that it installs in its own directory
- PKG_CHECK_MODULES : list here all your module dependancies.
- AC_CONFIG_FILES : list here all the files that will be generated during the configure (Makefile and others)

Le src/Makefile.am define the macros linked to the applets file:
- MY_APPLET_SHARE_DATA_DIR : The directory where the applet data will be installed (typically "/usr/share/cairo-dock/plug-ins/truc").
- MY_APPLET_README_FILE : Name of the file containing a short intro to the applet (typically "readme").
- MY_APPLET_PREVIEW_FILE : Name of the file containing a preview applet (typically "preview.png").
- MY_APPLET_CONF_FILE : Name of the applet config file (typically "truc.conf").
- MY_APPLET_USER_DATA_DIR : Name of the directory from the user point of view inside ~/.cairo-dock/current_theme/plug-ins (typically "truc").
- MY_APPLET_VERSION : applet version(for example "1.2.3").
- MY_APPLET_GETTEXT_DOMAIN : name of the translation domain (typically "cd-thing").
- MY_APPLET_DOCK_VERSION : Version of the dock used when the applet was compiled (for example "1.4.7").

Le code de base
[b]CD_APPLET_DEFINITION[/b] : "name of the applet", minimal version of the dock to use).

[b]CD_APPLET_INIT_BEGIN[/b] (error) ---> Read configuration file.
- Subscribe to useful notifications
- definition of the variable and useful structures

- Unsubscribe from notifications.
- reset variables, free all used ressources.

CD_APPLET_CONFIG_BEGIN ("Default label name" ou NULL, "default icon" ou NULL)
parametres = CD_CONFIG_GET_xxx ("group name", "key name", default value);

CD_APPLET_ABOUT (_D("Brief description of the applet and name of the author"))

Action when Left-Click.

CD_APPLET_ADD_IN_MENU_WITH_DATA ("Label", fonction callback, pSubMenu, data)

Action when Middle-Click

Glx-Dock / Cairo-Dock Wiki Write an applet Top

Online users :

Powered by ElementSpeak © 2007 Adrien Pilleboue, 2009-2013 Matthieu Baerts.
Dock based on CSS Dock Menu (Ndesign) with jQuery. Icons by zgegball
Cairo-Dock is a free software under GNU-GPL3 licence. First stable version created by Fabounet.
Many thanks to TuxFamily for the web Hosting and Mav for the domain name.