|
Cairo-Dock
3.1.99.rc2
|
|
Cairo-Dock
3.1.99.rc2
|
This documentation is divided into 3 parts :
It is useful if you want to write a complex plug-in or add new features in the core (or if you just love C); to write simple applets in any language, see http://doc.glx-dock.org.
Cairo-Dock has a decentralized conception : it has a minimalistic core, and lets external modules extend its functionnalities.
This is a strong design, because it allows to extend functionnalities easily without having to hack into the core, which makes the project more stable and allows developpers to use high-level functions only, that are very tested and optimized.
Thus, Cairo-Dock itself has no animation, but has a convenient notification system that allows external plug-ins to animate icons when they want.
The core itself is a library made of several modules. Each module is made on the same model:
In this document, we will focus on the notification system and the plug-ins framework. Part 1 will be seen briefly, and part 2 will be let to your curiosity. This should be enough to quickly be able to write a lot of applets.
The installation is very easy and uses cmake. In a terminal, copy-paste the following commands :
To install unstable plug-ins, add -Denable-xxx=yes to the cmake command, where xxx is the lower-case name of the applet.
See _CairoContainer for the definition of a Container, and cairo-dock-container.h for a complete description of the Container class.
See _Icon for the definition of an Icon, and cairo-dock-icon-factory.h for a complete description of the Icon class.
See _CairoDock for the definition of a Dock, and cairo-dock-dock-factory.h for a complete description of the Dock class.
See _CairoDesklet for the definition of a Desklet, and cairo-dock-desklet.h for a complete description of the Desklet class.
See _CairoDialog for the definition of a Dialog, and cairo-dock-dialogs.h for a complete description of the Dialog class.
See _CairoFlyingContainer for the definition of a Flying Container, and cairo-dock-flying-container.h for a complete description of the FlyingContainer class.
Modules are compiled .so files (that is to say, library) that are plugged into the dock at run-time. Therefore, they can use any function used by the dock, and have a total interaction freedom on the dock. The advantage is that applets can do anything, in fact they are extensions of the dock itself. The drawback is that a buggy applet can make the dock unstable.
A module has an interface and a visit card :
Modules can be instanciated several times; each time they are, an instance is created. This instance will hold all the data used by the module: the icon and its container, the config structure and its conf file, the data structure and a slot to plug data into containers and icons. All these parameters are optionnal; a module that has an icon is also called an applet.
When instanciating a module, CD will check the presence of an "Icon" group in the conf file. If there is one, it will create an icon accordingly and insert it into its container. If there is a "Desklet" group, the module is considered as detachable, and can be placed into a desklet. Here we will focus on applets, that is to say, we will have an icon and a container (dock or desklet).
Easy ! just go to the "plug-ins" folder, and run the generate-applet.sh script. Answer the few questions, and you're done ! Don't forget to install the plug-in each time you modify it (sudo make install in your applet's folder). You can see that the script has created for you the architecture of your applet :
As we saw, a module must fill a visit card and an interface, to be acecpted by the dock. This is done very easily by the CD_APPLET_DEFINITION macro. All you have to give is the name of the applet, its category, a brief description/manual (very important !), and your name.
Once you have finished your applet, don't forget to make a nice preview (~200x200 pixels) and a nice default icon, and place them in the data folder.
We saw that when our applet is activated, an instance is created. It is called myApplet, and it will hold the following :
The framework defines different sections, and all you have to do is to fill them :
When something happens, Cairo-Dock notifies everybody about it, including itself. An applet can register to any notification (see cairo-dock-notifications.h) before or after the dock, to be notified of the event of its choice. When you are notified, the function you registered for this event will be called; it must match the notification prototype as defined in cairo-dock-notifications.h.
For instance if you want to know when the user clicks on your icon, you will register to the NOTIFICATION_CLICK_ICON notification.
To register to a notification, you have the cairo_dock_register_notification_on_object function. Always unregister when your applet is stopped, to avoid being notified when you shouldn't, with the function cairo_dock_remove_notification_func_on_object.
For convenience, there are macros to register to the most common events:
Then you just have to fill the corresponding sections:
A lot of useful macros are provided in cairo-dock-applet-facility.h to make your life easier :
There are 3 cases :
There are also a lot of convenient functions you can use to draw in OpenGL. See cairo-dock-draw-opengl.h for loading and drawing textures and paths, and cairo-dock-particle-system.h for an easy way to draw particle systems.
If you want to animate your icon easily, to signal some action (like Music-Player when a new song starts), you can simply request for one of the registered animations with CD_APPLET_ANIMATE_MY_ICON and stop it with CD_APPLET_STOP_ANIMATING_MY_ICON. You just need to specify the name of the animation (like "rotate" or "pulse") and the number of time it will be played.
But you can also make your own animation, like Clock of Cairo-Penguin. You will have to integrate yourself into the rendering loop of your container. Don't panic, here again, Cairo-Dock helps you !
First you will register to the "update container" notification, with a simple call to CD_APPLET_REGISTER_FOR_UPDATE_ICON_SLOW_EVENT or CD_APPLET_REGISTER_FOR_UPDATE_ICON_EVENT, depending on the refresh frequency you need : ~10Hz or ~33Hz. A high frequency needs of course more CPU, and most of the time the slow frequancy is enough.
Then you will just put all your code in a CD_APPLET_ON_UPDATE_ICON_BEGIN/CD_APPLET_ON_UPDATE_ICON_END section. That's all ! In this section, do what you want, like redrawing your icon, possibly incrementing a counter to know until where you went, etc. See the previous paragraph to draw on your icon. Inside the rendering loop, you can skip an iteration with CD_APPLET_SKIP_UPDATE_ICON, and quit the loop with CD_APPLET_STOP_UPDATE_ICON or CD_APPLET_PAUSE_UPDATE_ICON (don't forget to quit the loop when you're done, otherwise your container may continue to redraw itself, which means a needless CPU load).
To know the size allocated to your icon, use the convenient CD_APPLET_GET_MY_ICON_EXTENT.
Say for instance you want to download a file on the Net, it is likely to take some amount of time, during which the dock will be frozen, waiting for you. To avoid such a situation, Cairo-Dock defines Tasks. They are perform their job asynchronously, and can be periodic. See cairo-dock-task.h for a quick explanation on how a Task works.
You create a Task with cairo_dock_new_task, launch it with cairo_dock_launch_task, and either cancel it with cairo_dock_discard_task or destroy it with cairo_dock_free_task.
In dock mode, your icon can have a sub-dock; in desklet mode, you can load a list of icons into your desklet. Cairo-Dock provides a convenient macro to quickly load a list of icons in both cases : CD_APPLET_LOAD_MY_ICONS_LIST to load a list of icons and CD_APPLET_DELETE_MY_ICONS_LIST to destroy it. Thus you don't need to know in which mode you are, neither to care about loading the icons, freeing them, or anything.
You can get the list of icons with CD_APPLET_MY_ICONS_LIST and to their container with CD_APPLET_MY_ICONS_LIST_CONTAINER.
Cairo-Dock can build itself the config panel of your applet from the config file. Moreover, it can do the opposite : update the conf file from the config panel. However, it is limited to the widgets it knows, and there are some cases it is not enough. Because of that, Cairo-Dock offers 2 hooks in the process of building/reading the config panel : when defining your applet in the CD_APPLET_DEFINE_BEGIN/CD_APPLET_DEFINE_END section, add to the interface the 2 functions pInterface->load_custom_widget and pInterface->save_custom_widget. They will be respectively called when the config panel of your applet is raised, and when it is validated.
If you want to modify the content of an existing widget, you can grab it with cairo_dock_gui_find_group_key_widget_in_list. To add your custom widgets, insert in the conf file an empty widget (with the prefix '_'), then grab it and pack some GtkWidget inside. If you want to dynamically alter the config panel (like having a "new" button that would make appear new widgets on click), you can add in the conf file the new widgets, and then call cairo_dock_reload_current_module_widget to reload the config panel. See the AlsaMixer or Weather applets for an easy example, and Clock or Mail for a more advanced example.
Say your applet launches an external application that has its own window. It is logical to make your applet control this application, rather than letting the Taskbar do. All you need to do is to call the macro CD_APPLET_MANAGE_APPLICATION, indicating which application you wish to manage (you need to enter the class of the application, as you can get from "xprop | grep CLASS"). Your applet will then behave like a launcher that has stolen the appli icon.
Cairo-Dock offers a powerful and versatile architecture for this case : _CairoDataRenderer. A DataRenderer is a generic way to render a set of values on an icon; there are several implementations of this class : Gauge, CairoDockGraph, Bar, and it is quite easy to implement a new kind of DataRenderer.
Each kind of renderer has a set of attributes that you can use to customize it; you just need to call the CD_APPLET_ADD_DATA_RENDERER_ON_MY_ICON macro with the attributes, and you're done ! Then, each time you want to render some new values, simply call CD_APPLET_RENDER_NEW_DATA_ON_MY_ICON with the new values.
When your applet is reloaded, you have to reload the DataRenderer as well, using the convenient CD_APPLET_RELOAD_MY_DATA_RENDERER macro. If you don't specify attributes to it, it will simply reload the current DataRenderer, otherwise it will load the new attributes; the previous data are not lost, which is useful in the case of Graph for instance.
You can remove it at any time with CD_APPLET_REMOVE_MY_DATA_RENDERER.
Applets can be launched several times, an instance will be created each time. To ensure your applet can be instanciated several times, you just need to pass myApplet to any function that uses one of its fields (myData, myIcon, etc). Then, to indicate Cairo-Dock that your applet is multi-instanciable, you'll have to define the macro CD_APPLET_MULTI_INSTANCE in each file. A convenient way to do that is to define it in the CMakeLists.txt by adding the following line:
.
Say you want to draw directly on your container, like CairoPenguin or ShowMouse do. This can be achieved easily by registering to the NOTIFICATION_RENDER notification. You will then be notified eash time a Dock or a Desklet is drawn. Register AFTER so that you will draw after the view.
1.8.3.1 
