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

Home

History

Language

en English

fr Français

ru Russian

Support Us

Flattr this

Cairo-Dockon

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:

Applet Structure

Source Tree structure
The source tree structure 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 files names 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.

Sources Folder
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...)

Data Folder
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 alsa be used in the config panel of Cairo-Dock)
- truc.conf : the config file of the applet, which contains all the parameters that the user can change

Translation Folder
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 files list where one finds messages to be translated.
- *.po : files containing the translations of each message.

Installation Tree structure
The installation tree structure is very simple :
- the contents of the folder "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 definitions:
- 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-truc").
- MY_APPLET_DOCK_VERSION : Version of the dock used when the applet was compiled (for example "1.4.7").

Le code de base
init
[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
[b]CD_APPLET_INIT_END[/b]

[b]CD_APPLET_STOP_BEGIN[/b]
- Unsubscribe from notifications.
- reset variables, free all used ressources.
[b]CD_APPLET_STOP_END[/b]


config
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_CONFIG_END


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

CD_APPLET_ON_CLICK_BEGIN
Action when Left-Click.
CD_APPLET_ON_CLICK_END

CD_APPLET_ON_BUILD_MENU_BEGIN
CD_APPLET_ADD_SUB_MENU ("Label", pSubMenu, CD_APPLET_MY_MENU)
CD_APPLET_ADD_IN_MENU_WITH_DATA ("Label", fonction callback, pSubMenu, data)
...
CD_APPLET_ADD_ABOUT_IN_MENU (pSubMenu)
CD_APPLET_ON_BUILD_MENU_END

CD_APPLET_ON_MIDDLE_CLICK_BEGIN
Action when Middle-Click
CD_APPLET_ON_MIDDLE_CLICK_END


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.