Cairo-dock put at your disposal a framework dedicated to quickly writing standardized applets.
Let's see how to do.
First we can generate a fonctionnal applet with the script generate-new-applet.sh, located in the "plug-ins" folder of the sources.
Run it, answer the few questions, and after all is finished go to your new applet's folder and type sudo make install. You're done ! If you restart the dock, you will see your new applet in the config panel. You can even activate it, it will appear in the main dock.
Now all we have to do is to complete the code. 
Before we go further, let us look at the structure of your applet (let's say that its name is "truc") :
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 -> truc.conf.in, preview, readme.in, *
+--> 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 functions to initialize, stop and reload the applet.
- applet-config.c : contains the functions to load the config, reset it, and reset the datas.
- applet-notifications.c : contains the functions which are called when the applet is notified by Cairo-Dock that something interesting has happened (a click, a drop, etc)
- *.c : the others can contain everything you need (connection to a server, functions of drawings, calculations, etc...) Separating your functions into different files by familly is a good habit.
Data Folder In --./data-- we find :
- preview : a picture (png or jpg) giving a preview of the applet, around 200x200 pixels. It will be displayed in the config panel of Cairo-Dock.
- readme.in : a file giving the author of the applet (you; -)), and a short summary of this one (the text will also be displayed in the config panel of Cairo-Dock).
- truc.conf.in : the config file of the applet, which contains all the parameters that the user can change. We'll see later how to use it.
- icon.png : an icon used to represent your applet in the config panel. It is common to also use it as a default icon in the dock.
Translation Folder In ./po we have :
- Makefile.in.in : no need to care this 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/lib/cairo-dock/libcd-truc.so
- the translation files will go in /usr/share/locale/$lang/LC_MESSAGES/cd-truc.mo, where $lang = fr, jp, ...
Compilation files Don't forget to define the dependencies with other libs in configure.ac if needed, along with the version number of your applet. Also, report the files you need to install in the Makefile.am files.
Well, now start the serious things !
Using the applet framework
The variables An applet is a CairoDockModuleInstance structure. You can acces to yours through the myApplet variable.
An applet has an Icon, yours is myIcon.
The icon is located inside a CairoContainer, yours is myContainer.
This container can be either a CairoDock (yours is myDock) or a CairoDesklet (yours is myDesklet). In the first case myDock == myContainer and myDesklet == NULL, and vide versa, so they are just here for convenience.
The applet has some parameters, taken from the config file, grouped into an AppletConfig structure. Yours is myConfig.
The applet has some datas it loads at run-time, grouped into an AppletData structure. Yours is myData.
Last, an icon has an associated cairo_t drawing context, yours is myDrawContext. Note that if the applet is in Desklet mode, the context is only available after you set the desklet's renderer, that you should therefore do at first.
Single and multi-instance In Cairo-Dock, applets can be launched several times or just 1 time. For exemple you can have many instances of Clock, each one giving the time of a different country.
If you want to make your applet multi-instanciable, just add the following line to the src/Makefile.am :
-DCD_APPLET_MULTI_INSTANCE="1"
In the case of a single-instance applet, myApplet is available everywhere, as a global variable. In the case of a multi-instance applet, it is only available at init and reload, and it's up to you to pass it to all of your functions as an input parameter (you can't make it a global variable).
The notifications In Cairo-Dock, applets can interact with the dock through notifications. When something happens (the user clicks somewhere, drop a data in the dock, etc), the dock will send a notifications of the event. Everybody that has registerd to this notification will receive it.
When you register to a notification, you give a function (a callback) that will be called when the notification occurs.
Some macros exists for the most usual notifications (right/left/middle/double clicks in particular). Be careful to respect the format of the callback if you don't use the macros, they are all described in cairo-dock-notifications.h.
Init, stop and reload your applet Cairo-Dock will allocate an icon and a container for your applet, and then will let you initialize it.
So in your init function, you already have all the variables available, including myConfig.
All yo have to do here is to start your applet (launch a timer, register to notifications, etc).
The macros
The config |
English
Français
Russian
Online users :