Home Forums Wiki Doc Install Extras Screenshots Source Code Projects Blog Users Groups Register
Glx-Dock / Cairo-Dock Wiki Control_your_dock_with_DBus
The latest stable release is the *3.4.0* : How to install it here.
Note: We just switched from BZR to Git on Github! (only to host the code and your future pull requests)
Information : The version displayed on this page is not the latest available.
History View code

Glx-Dock / Cairo-Dock

Home

History

Language

en English

fr Français

ru Russian

Support Us

Flattr this

Cairo-Dockon

Control_your_dock_with_DBus

Control your dock with DBus

The purpose of this tutorial
Dbus is an Inter Process Communication program, that is to say, it lets you send and receive messages to any application that is connected to DBus.
Cairo-Dock comes with a powerful DBus interface. Here we'll fully describe it and provide many useful exemples to show how you can control your dock from a script or a terminal.

First Step
This tutorial is made for Cairo-Dock 2.1.x or later. If your version is older, it is strongly recommended to upgrade, because the dock improves itself at each new version.
To get the latest version, use our repository, or grab the packages on LaunchPad, or install from the sources. This is fully explained on our wiki (http://wiki.glx-dock.org).
Be sure to install the plug-ins too.

You need to activate the "DBus" plug-in in the config panel of the dock. In the config panel of the plug-in, be sure that all the operations are allowed, for the exemples.

The interface :
  • Several programs are connected to the bus; to talk to one program in particular, you have to specify the name of its service on the bus. For Cairo-Dock, the name is :
    org.cairodock.CairoDock
  • Each program loads some remote objects on the bus, that other applis can grab and use to communicate with the program. These remote objects are stored at a given path. Cairo-Dock stores 1 main object at the path
    /org/cairodock/CairoDock
  • Each object has one or several interface(s). An interface is a collection of methods (messages you can send to the program) and signals (messages the program will send you). The main object has a unique interface, named
    org.cairodock.CairoDock

Note : Actually Cairo-Dock provides other objects, associated with remote applets. We'll see that in the last part of this tutorial.

  • We'll give our exemples in bash, so that you can try them by simply copy-paste the commands inside a terminal.
  • The command to send a message on the bus is :
    dbus-send
    .
  • To talk to Cairo-Dock, we use the following command :
    dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.xxx type1:arg1 type2:arg2 ...
    where xxx is the name of the message to send, followed by the arguments : type is the type of an argument (string, int32, boolean, etc), and arg is the argument ("some text", 123, true, etc).


Act on the dock :

Reboot
It will completely reload the current theme, as if you had quitted and restarted the dock.
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.Reboot


Quit
It will quit the dock, as if you killed it but in a more proper way.
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.Quit


ReloadModule
It will reload a given module, as if you entered its config panel and applied.
You can use it after making some modification in its conf file, for instance.
Thus, you may make some modification to the Dustbin's conf file (using sed), and then apply the modifications with the following command :
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.ReloadModule string:dustbin


ShowDock
It will show or hide the dock, depending on the argument you specify (if you have several docks, it will show/hide all of them).
For instance, you may quick-hide the dock with the following command :
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.ShowDock boolean:false


ShowDesklet
It will toggle the visibility of the desklets, like a "show-desktop" would do, but only for the desklets' windows.
The argument lets you specify if you also want to show the desklets placed on the Compiz Widget Layer.
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.ShowDesklet boolean:true


LoadLauncherFromFile
It will load a desktop file, creating a new launcher into the dock.
It takes the path to the desktop file as parameter.
The following command creates a Nautilus launcher (the path may vary depending on your distribution, and if Nautilus is installed or not).
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.LoadLauncherFromFile string:/usr/share/applications/nautilus.desktop

The icon will appear into the dock, but only until the dock restarts (and will not be editable); if you want to make it permanent, you have to copy before the desktop file into the launcher directory of the dock :
cp /usr/share/applications/nautilus.desktop ~/.config/cairo-dock/current_theme/launchers


CreateLauncherFromScratch
It will create a temporary launcher from scratch : you specify the image, name, and command of the launcher, plus the name of the dock where it should be placed (or "none" to place it inside the main dock).
If you want to make it permanent, you have to create a .desktop file, filled with the vales you want, and copy it into ~/.config/cairo-dock/current_theme/launchers.
The following command creates a launcher named "my launcher", with the icon "/path/to/image", and the command "xterm -e 'echo pouet'", and place it inside the main dock.
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.CreateLauncherFromScratch string:"/path/to/image" string:"my launcher" string:"xterm -e 'echo pouet'" string:none


Act on the icons
Icons are refered by their name and/or their command, or by the module's name in the case of an applet.
Each of the following methods takes 3 strings as their last arguments, which are {icons's name; icon's command; module's name} (in this order).
This should allow you to point the icon you want. Let the other strings to "none" or "any".
For exemple, to find the firefox launcher, you can use the strings {"any"; "firefox"; "none"} to say : the icon with the command "firefox", with any label, and no module.
To find the Dustbin applet, you can use the strings {"any"; "none"; "dustbin"} to say : the icon with any label, no command, and the module "dustbin".
The case is not taken into account.

SetQuickInfo
Sets the quick-info on a given icon (this is a small text displayed on the icon).
The following command write "123" on the dustbin applet, overwriting the number of files in the Trash if it was displayed.
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.SetQuickInfo string:123 string:none string:none string:dustbin


SetLabel
Sets the label of an icon (its name), overwriting the previous one.
The following command sets the name "Fabounet" on the gnome-terminal launcher.
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.SetLabel string:"Fabounet" string:any string:gnome-terminal string:none


SetIcon
Sets the image of an icon, overwriting the previous one.
You can refer to the image by either its name if it's an image from a icon theme, or by a path.
The following command sets the image of Firefox on the Nautilus launcher.
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.SetIcon string:firefox-3.0 string:none string:nautilus string:none


Animate
Animates an icon, with a given animation and for a given number of rounds.
The following command launches the default animation on the firefox launcher for 2 rounds.
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.Animate string:default int32:2 string:any string:firefox string:none

The following command will make the Clock applet burn for 1 or 2 minutes, or until you fly over it with the mouse.
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.Animate string:fire int32:60 string:none string:none string:clock


ShowDialog
Pops up a dialog bubble with a message on a given icon and for a given duration (in seconds). If the icon is not found, it displays the message as a general message. The dialog can be closed by clicking on it.
The following command will pop up a dialog saying "Cairo-Dock is great !" for 5 seconds, which is perfectly true
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.ShowDialog string:"Cairo-Dock is great \!" int32:5 string:none string:none string:none


Write a DBus applet
There is a second interface, named
org.cairodock.CairoDock.applet
. It contains methods and signals to interact on a distant applet (that is to say, an applet that has been loaded from outside of the dock).
This allows to write complete applets that are loaded into the dock from another process.
This is done in 3 simple steps :
  • register a new module and activate it => this will create an applet inside the dock (or inside a desklet)
  • grab the remote object associated with the applet => this will let us use the interface on this applet
  • connect to the signals to listen for events on the applet (clic, reload, etc), and use methods to act on it (change the image, animate the icon, etc)

RegisterNewModule
This method lets you register a new module; to define the module, you just pass as arguments :
  • a name (different from any other module, it will identify it, for instance "dustbin" is the name of the Dustbin applet).
  • the category it will be placed into (from 0 to 5, but you'll probably want to use : 2 for an accessory, 3 for a desktop applet, and 4 for a controler).
  • a short description, which also explain briefly how the applet works.
  • a path to its data files (the .conf, icon, preview, etc)
An icon will then be created and inserted into its container, according to the current .conf file.

NB : the .conf file must exist in the data files path, and should be filled with some default parameters so that the applet is usable immediately. Its name must be xxx.conf, where xxx is the name of the applet, and it should contain at least the groups "Icon" and "Desklet", as any other applet (you can just copy the logout.conf from the Logout applet to start with).
An "icon" file should also exist in this folder (to be used as the default icon, it can be of any format), as well as a "preview" file (to be displayed in the config panel, but this one can be done later).

The following command will register a module called "demo".
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.RegisterNewModule string:"demo" int32:2 string:"This is a distant applet\n by Fabounet" string:"$HOME/demo"

This module will be an accessory, and its files are located in $HOME/demo. Additionally, the following files should exist :
  • $HOME/demo/demo.conf
  • $HOME/demo/icon
  • $HOME/demo/preview


Grab the object
When our module is registerd, Cairo-Dock creates a remote object on the bus. It is stored at
/org/cairodock/CairoDock/name-of-the-applet

So in our exemple, the path is : /org/cairodock/CairoDock/demo.
This object has a unique interface, named
org.cairodock.CairoDock.applet

So in bash, we can access this interface with the following command :
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock/demo org.cairodock.CairoDock.applet.xxx type1:arg1 type2:arg2 ...
where xxx is the name of the message to send, followed by the arguments : type is the type of an argument (string, int32, boolean, etc), and arg is the argument ("some text", 123, true, etc).

Ok we have a new applet inside the dock, and its corresponding remote object on the bus; now let's see how to act on it.

Act on the applet
The followinf methods are provided by the interface to act on the applet; they look like the ones to act on any icon, but they target the icon of your applet only.

SetQuickInfo
Sets the quick-info on our icon (this is a small text displayed on the icon).
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock/demo org.cairodock.CairoDock.applet.SetQuickInfo string:123


SetLabel
Sets the label of our icon (its name), overwriting the previous one.
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock/demo org.cairodock.CairoDock.applet.SetLabel string:"Fabounet"


SetIcon
Sets the image of our icon, overwriting the previous one.
You can refer to the image by either its name if it's an image from a icon theme, or by a path.
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock/demo org.cairodock.CairoDock.applet.SetIcon string:firefox-3.0


Animate
Animates our icon, with a given animation and for a given number of rounds.
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock/demo org.cairodock.CairoDock.applet.Animate string:default int32:2

dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock/demo org.cairodock.CairoDock.applet.Animate string:fire int32:60


ShowDialog
Pops up a dialog bubble on our icon, with a given message and for a given duration (in seconds). The dialog can be closed by clicking on it.
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock/demo org.cairodock.CairoDock.applet.ShowDialog string:"Cairo-Dock is great \!" int32:5


Great, we can make our applet live inside the dock !
Now what we want to do is to be notified when the user clicks on the icon or such things. We'll have to connect to some signals; then each time the corresponding event occurs, the signal will be broadcasted to us, possibly with some parameters.

Signals
The DBus interface contains some signals, that is to say Cairo-Dock will emit a signal when some event occurs inside the dock.
You can register to these actions, and thus be notified of the events.
You can then react to these events, as if you were inside the dock.

on_click_icon
Signal received when the user clicks on the icon.
We receive : an integer that says if some special key were activated (Ctrl, Shift or Super).

on_middle_click_icon
Signal received when the user middle-clicks on the icon.
No argument.

on_scroll_icon
Signal received when the user scrolls on the icon.
We receive : a boolean that is true if the user scrolled up, and false if the user scrolled bottom.

on_build_menu
Signal received when the user right-clicks on the icon.
No argument.
You can populate the menu thanks to the PopulateMenu method, which takes a NULL-terminated list of strings as parameter.

on_drop_data
Signal received when the user drops something on the icon.
We receive : the received text or url.

on_reload_module
Signal received when the module is reloaded.
We receive : a boolean that is true if the config has changed and false if it was just a reload because of a resize.

on_init_module
Signal received when the module is started (the first time the module is started, or if the user deactivates and then reactivates the module).
No argument.

on_stop_module
Signal received when the module is stopped (because the dock is closed or because the user has deactivated the module).
No argument.

Conclusion :
The remote control interface of Cairo-Dock allows you to interact on the dock, modify the icons, and even write new applets without needing to dig into the C API of the dock. You can use it anywhere, inside a program, a script, or even a terminal, and with the language of your choice.

I hope this little guide was helpful. If you have any comment/suggestion, feel free to write me at fabounet (at) users [dot] berlios -dot- de, or pay us a visit at http://glx-dock.org !

Fabounet.


Glx-Dock / Cairo-Dock Wiki Control_your_dock_with_DBus Top

Online users :

Powered by ElementSpeak © 2007 Adrien Pilleboue, 2009-2013 Matthieu Baerts.
Dock based on CSS Dock Menu (Ndesign) with jQuery. Icons by zgegball
Cairo-Dock is a free software under GNU-GPL3 licence. First stable version created by Fabounet.
Many thanks to TuxFamily for the web Hosting and Mav for the domain name.