|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 sourcesThe 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 sourcesIn ./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 dataIn --./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 translationsIn ./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 installationThe 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, ...
--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 : nom du domaine de traduction de l'applet (typiquement "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
CD_APPLET_DEFINITION : "name of the applet", minimal version of the dock to use).
CD_APPLET_INIT_BEGIN (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