Cairo-Dock  3.3.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Cairo-Dock's API documentation.

Introduction

Installation

Main structures

External Modules

Advanced functionnalities


Introduction

This documentation presents the core library of Cairo-Dock: libgldi (GL Desktop Interface).

It is useful if you want to write a plug-in, add new features in the core, or just love C.
Note: to write applets in any language very easily, see http://doc.glx-dock.org.

It has a decentralized conception and is built of several modules: internal modules (Managers) and external modules (Modules) that can extend it.
It also has an Objects architecture.


Installation

The installation is very easy and uses cmake. In a terminal, copy-paste the following commands :

### grab the sources of the core
mkdir CD && cd CD
bzr checkout --lightweight lp:cairo-dock-core
### compil the dock and install it
cd cairo-dock-core
cmake CMakeLists.txt -DCMAKE_INSTALL_PREFIX=/usr
make
sudo make install
### grab the sources of the plug-ins
cd ..
bzr checkout --lightweight lp:cairo-dock-plug-ins
### compil the stable plug-ins and install them
cmake CMakeLists.txt -DCMAKE_INSTALL_PREFIX=/usr
make
sudo make install

To install unstable plug-ins, add -Denable-xxx=yes to the cmake command, where xxx is the lower-case name of the applet.


Main structures

Objects

Any element in libgldi is a _GldiObject.
An Object is created by an ObjectManager, which defines the properties and notifications of its children.
It has a reference counter, can be deleted from the current theme, and can be reloaded.
An Object can cast notifications; notifications are broadcasted on its ObjectManager.
An ObjectManager can inherit from another ObjectManager; in this case, all methods of the parent ObjectManagers are called recursively, and likewise all notifications on an Object are casted recursively to all parent ObjectManagers.

See _GldiObject and cairo-dock-object.h for more details.

Managers

The core is divided in several internal modules, called Managers.
Each Manager manages a set of parameters and objects (for instance, the Dock Manager manages the list of all Docks and their parameters).

See _GldiManager and cairo-dock-manager.h for more details.

Containers

Containers are generic animated windows. They can hold Icons and support cairo/OpenGL drawing.

See _GldiContainer and cairo-dock-container.h for more details.

Icons

Icons are elements inside a Container on which the user can interact. For instance, a Launcher is an Icon that launches a program on left-click.

See _Icon and cairo-dock-icon-factory.h for more details.

Dock

Docks are a kind of Container that sits on a border of the screen.

See _CairoDock and cairo-dock-dock-factory.h for more details.

Desklet

Desklets are a kind of Container that stays on the desktop and holds one or many icons.

See _CairoDesklet and cairo-dock-desklet-factory.h for more details.

Dialog

Dialogs are a kind of Container that holds no icon, but rather point to an icon, and are used to display some information or interact with the user.

See _CairoDialog and cairo-dock-dialog-factory.h for more details.

Modules

A Module is an Object representing a plug-in for libgldi.
It defines a set of properties and an interface for init/stop/reload.
A Module that adds an Icon is called an "applet".

See _GldiModule and cairo-dock-module-manager.h for more details.

Note: the cairo-dock-plug-ins project is a set of modules in the form of loadable libraries (.so files).
the cairo-dock-plug-ins-extra project is a set of modules in the form of scripts (Python or any language) that interact on the core through Dbus.

Module-Instances

A Module-Instance is an actual instance of a Module.
It holds a set of parameters and data (amongst them the Applet-Icon if it's an applet).
A Module can have several instances.

See _GldiModuleInstance and cairo-dock-module-instance-manager.h for more details.

Drawing with cairo/opengl

libgldi defines _CairoDockImageBuffer, a generic Image that works for both cairo and OpenGL.
See cairo-dock-image-buffer.h for more details.

It is possible to add small images above Icons; they are called _CairoOverlay.
For instance quick-info and progress-bars are Overlays.
See cairo-dock-overlay.h for more details.

Windows management

libgldi keeps track of all the currently existing windows, with all their properties, and notifies everybody of any change. It is used for the Taskbar.
Each window has a corresponding _GldiWindowActor object.
See cairo-dock-windows-manager.h for more details.


External Modules

Create a new applet

Go to the "plug-ins" folder, and run the generate-applet.sh script. Answer the few questions, and you're done!
The script creates a <module-name> folder, with src and data sub-folders, which contain the following:

  • data/icon.png: the default icon of your applet
  • data/preview.jpg: a preview of your applet, around 200x200 pixels
  • data/<module-name>.conf.in: the config file of your applet
  • src/applet-init.c: contains the init, stop and reload methods, as well as the definition of your applet.
  • src/applet-config.c: container the get_config and reset_config methods
  • src/applet-notifications.c: contains the callbacks of your applet (ie, the code that is called on events, for instance on click on the icon)
  • src/applet-struct.h: contains the structures (Config, Data, and any other you may need)

Note: when adding a new file, don't forget to add it in the CMakeLists.txt.
when changing something in the config file, don't forget to update the version number of the applet, in the main CMakeLists.txt.
when changing anything, don't forget to install (sudo make install)

First steps

Edit the file src/applet-inic.c; the macro CD_APPLET_DEFINITION is a convenient way to define an applet: just fill its name, its category, a brief description, and your name.

In the section CD_APPLET_INIT_BEGIN/CD_APPLET_INIT_END, write the code that will run on startup.

In the section CD_APPLET_STOP_BEGIN/CD_APPLET_STOP_END, write the code that will run when the applet is deactivated: remove any timer, destroy any allocated ressources, unregister notifications, etc.

In the section CD_APPLET_RELOAD_BEGIN/CD_APPLET_RELOAD_END section, write the code that will run when the applet is reloaded; this can happen in 2 cases:

  • when the configuration is changed (CD_APPLET_MY_CONFIG_CHANGED is TRUE, for instance when the user edits the applet)
  • when something else changed (CD_APPLET_MY_CONFIG_CHANGED is FALSE, for instance when the icon theme is changed, or the icon size is changed); in this case, most of the time you have nothing to do, except if you loaded some ressources yourself.

Edit the file src/applet-config.c; In the section CD_APPLET_GET_CONFIG_BEGIN/CD_APPLET_GET_CONFIG_END, get all your config parameters (don't forget to define them in applet-struct.h).

In the section CD_APPLET_RESET_CONFIG_BEGIN/CD_APPLET_RESET_CONFIG_END, free any config parameter that was allocated (for instance, strings).

Edit the file src/applet-notifications.c;

In the section CD_APPLET_ON_CLICK_BEGIN/CD_APPLET_ON_CLICK_END, write the code that will run when the user clicks on the icon (or an icon of the sub-dock).

There are other similar sections available:

To register to an event, use one of the following convenient macro during the init:

Note: don't forget to unregister during the stop.

Go further

A lot of useful macros are provided in cairo-dock-applet-facility.h to make your life easier.

The applet instance is myApplet, and it holds the following:

  • myIcon : this is your icon !
  • myContainer : the container your icon belongs to (a Dock or a Desklet). For convenience, the following 2 parameters are available.
  • myDock : if your container is a dock, myDock = myContainer, otherwise it is NULL.
  • myDesklet : if your container is a desklet, myDesklet = myContainer, otherwise it is NULL.
  • myConfig : the structure holding all the parameters you get in your config file. You have to define it in applet-struct.h.
  • myData : the structure holding all the ressources loaded at run-time. You have to define it in applet-struct.h.
  • myDrawContext : a cairo context, if you need to draw on the icon with the libcairo.
  • To get values contained inside your conf file, you can use the following :
    CD_CONFIG_GET_BOOLEAN & cie
  • To build your menu, you can use the following :
    CD_APPLET_ADD_SUB_MENU & cie
  • To directly set an image on your icon, you can use the following :
    CD_APPLET_SET_IMAGE_ON_MY_ICON & cie
  • To modify the label of your icon, you can use the following :
    CD_APPLET_SET_NAME_FOR_MY_ICON & cie
  • To set a quick-info on your icon, you can use the following :
    CD_APPLET_SET_QUICK_INFO_ON_MY_ICON & cie
  • To create a surface that fits your icon from an image, you can use the following :
    CD_APPLET_LOAD_SURFACE_FOR_MY_APPLET & cie
  • To trigger the refresh of your icon or container after you drew something, you can use the following :
    CD_APPLET_REDRAW_MY_ICON & CAIRO_DOCK_REDRAW_MY_CONTAINER

How can I take advantage of the OpenGL ?

There are 3 cases :

  • your applet just has a static icon; there is nothing to take into account, the common functions to set an image or a surface on an icon already handle the texture mapping.
  • you draw dynamically on your icon with libcairo (using myDrawContext), but you don't want to bother with OpenGL; all you have to do is to call /ref cairo_dock_update_icon_texture to update your icon's texture after you drawn your surface. This can be done for occasional drawings, like Switcher redrawing its icon each time a window is moved.
  • you draw your icon differently whether the dock is in OpenGL mode or not; in this case, you just need to put all the OpenGL commands into a CD_APPLET_START_DRAWING_MY_ICON/CD_APPLET_FINISH_DRAWING_MY_ICON section inside your code.

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.

How can I animate my applet to make it more lively ?

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.

I have heavy treatments to do, how can I make them without slowing the dock ?

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 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.

Key binding

You can bind an action to a shortkey with the following macro: CD_APPLET_BIND_KEY.
For instance, the GMenu applet displays the menu on ctrl+F1.
You get a GldiShortkey that you simply destroy when the applet stops (with gldi_object_unref).

See cairo-dock-keybinder.h for more details.

I need more than one icon, how can I easily get more ?

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.


Advanced functionnalities

How can I make my own widgets in the config panel ?

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.

How can my applet control the window of an application ?

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.

How can I render some numerical values on my 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.

How can I make my applet multi-instanciable ?

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:

add_definitions (-DCD_APPLET_MULTI_INSTANCE="1")

.

How can I draw anywhere on the dock, not only on my icon ?

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.