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

The purpose of this tutorial :
Dbus is a 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 its name, path and its interface.
For Cairo-Dock, the name is <i>org.cairodock.CairoDock</i>, the path is <i>/org/cairodock/CairoDock</i>, and it has a unique interface <i>org.cairodock.CairoDock</i>.

  • The interface is a collection of message (also called methods), each of them having one or several arguments.

  • 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 <i>dbus-send</i>. 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, bool, 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.
For instance, you may make some modification to the Dustbin's conf file (using <i>sed</i>), 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 bool: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 bool: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 <i>VLC</i> launcher (the path may vary depending on your distribution, and if VLC is installed or not).
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.LoadLauncherFromFile string:/usr/share/applications/desktop/vlc.desktop


  • CreateLauncherFromScratch
It will create a 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).
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}.
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:deault 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 :
  • 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.
This allows to write complete applets that are loaded into the dock from another process.
First we'll see how to register a new applet, and then we'll see these signals.

  • 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.png, 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 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.png" file should also exist in this folder (to be used as the default icon), as well as a "preview" file (to be displayed in the config panel, but this one can be done later).

Ok we have a new applet; so now let's see how to react on events.
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 with some parameters. Each of the signals sends the module's name as the first parameter, possibly followed by some other parameters.

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

  • on_middle_click_icon
Signal received when the user middle-clicks on the icon.
We receive : the module's name.

  • on_scroll_icon
Signal received when the user scroll on the icon.
We receive : the module's name, and 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-click on the icon.
We receive : the module's name.
You can then 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 module's name, and the received text or url.

  • on_reload_module

Signal received when the module is reloaded.
We receive : the module's name, and a boolean that is true if the .conf file has changed and false if it was juste reloaded because of a resize.

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.