|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:
Source Tree structureThe 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 FolderIn ./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 FolderIn --./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 FolderIn ./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 structureThe 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, ...
--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
[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_SUB_MENU ("Label", pSubMenu, CD_APPLET_MY_MENU)
CD_APPLET_ADD_IN_MENU_WITH_DATA ("Label", fonction callback, pSubMenu, data)
Action when Middle-Click