Home Forums Wiki Doc Install Extras Screenshots IRC Projects Blog Users Groups Register
Glx-Dock / Cairo-Dock Wiki Control_your_dock_with_DBus
The latest stable release is the *3.3.2* : How to install it here.
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


This is the interface to the core of Cairo-Dock. It provides a powerful way to control your dock from a script, a terminal, or another program.
Note: There is another interface for applets, with wrappers in many languages; have a look here.


Introduction
Dbus is an Inter Process Communication tool, 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 in Bash and Python.

You need Cairo-Dock 3.4 or later.
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.
Be sure to upgrade the plug-ins too.
For version 3.3 or below, see here
For version 2.3 or below, see here

The interface
  • Cairo-Dock is present on the bus under the well-known name org.cairodock.CairoDock.
  • It stores an object on the bus, that you can grab and use to communicate with it. The path to the object is /org/cairodock/CairoDock
  • This object has 1 interface (a collection of methods and signals) named org.cairodock.CairoDock

Note: Cairo-Dock also provides other objects, associated with third-party applets; see http://doc.glx-dock.org.

So to talk to Cairo-Dock, we can use the following commands:
  • in Bash
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 arg1, arg2 are the arguments ("some text", 123, true, etc).
  • in Python
from CairoDock import CairoDock
d=CairoDock().iface
d.xxx(arg1, arg2, ...)

where xxx is the name of the method, and arg1, arg2 are the arguments.

Global methods

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 had closed it from the menu.
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.Quit


ShowDock
It will show or hide the dock, depending on the mode you specify (0 = HIDE, 1 = SHOW, 2 = TOGGLE). If you have several docks, it will show/hide all of them.
For instance, you can hide the dock with the following command:
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.ShowDock int32:0

or toggle the visibility ON/OFF with the following:
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.ShowDock int32:2

Note: it is possible to bind this command to a shortkey (with Compiz for instance). Thus, you could for instance make the dock appear each time you press the <Super> key.

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


Refering an element
Elements are refered by a query.
Ex.: to find the firefox icon(s), you can use the query "class=firefox".

You can mix several queries with "&" (and), "|" (or), and "()".
Ex.: to find the Firefox launcher only, you can use "class=firefox & type=Launcher".
to find the clock module, you can use the query "type=Module & name=clock".

You can also use a "*" to match the beginning of a string.
Ex.: to find all the launchers related to Gnome: "type=Launcher & (name=gnome* | command=gnome*)"

Add an element
The method is Add with the list of properties. The type is mandatory.
It returns the config file that has been added.

Add an icon
  • From a desktop file:
d.Add({'type':'Launcher', 'config-file':'application://vlc.desktop'})

You can also pass the complete path of the desktop file.
  • Custom launcher:
d.Add({'type':'Launcher', 'name':'Top 10', 'command':'xterm -e top', 'icon':'gtk-home.png'})

You can also define its order, class and container.
d.Add({'type':'Launcher', 'name':'my launcher', 'command':'nautilus', 'icon':'firefox', 'class':'gjiten', 'order':5, 'container':'_MainDock_'})


  • Stack icon (holding a sub-dock):
d.Add({'type':'Stack-Icon', 'name':'my sub-dock', 'icon':'folder.png'})

Now to place an icon inside:
d.Add({'type':'Launcher', 'config-file':'application://vlc.desktop', 'container':'my sub-dock'})


  • Separator:

d.Add({'type':'Separator', 'order':7.0})


Add a module
This enables a module. If several instances of the module are available (i.e. several config files in the module directory), they will all be created. If the module is already activated, it does nothing.
d.Add({'type':'Module', 'module':'clock'})


Add a module instance
This adds another instance of a given module. If the module is not yet activated, it will activate it. The module must be multi-instanciable.
d.Add({'type':'Module-Instance', 'module':'clock'})


Add a main dock
d.Add({'type':'Dock'})


Remove an element
Removes the VLC launcher.
d.Remove('type=Launcher & class=vlc')


Removes the second main dock (and all its content).
d.Remove('type=Dock & name=_MainDock_-2')


Disables the Clock module (if it was multi-instanciated, all the instances are preserved and will be created when the module is re-activated).
d.Remove('type=Module & name=clock')


Removes an instance of the Clock.
d.Remove('type=Module-Instance & config-file=clock.conf')


Reload an element
Reloading an element will read its parametres from its config file, and reload it entirely. So it should be used in conjonction with a modification of the config file.
Modify the container of the firefox launcher:
system ('sed -i "s/^Container.*/Container=_MainDock_-2/g" /home/fab/.config/cairo-dock/current_theme/launchers/01firefox.desktop' # modify the coresponding key in the config file)
d.Reload('config-file=/home/fab/.config/cairo-dock/current_theme/launchers/01firefox.desktop' # reload the icon in the dock)


Get element's properties
Gets the properties of the firefox Launcher.
d.GetProperties("'type=Launcher & class=firefox')


Print the position of each desklets.
for desklet in d.GetProperties("type=Desklet"):
print("%s: %d;%d" % (desklet['name'], desklet['x'], desklet['y'])


Act on icons

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:"module=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:"class=gnome-terminal"


SetIcon
Sets the image of an icon, overwriting the previous one.
You can refer to the image either by its name 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:"class=nautilus"


SetEmblem
Sets an emblem on an icon. The emblem is drawn directly on the icon, so if you want to remove it, you have to use SetEmblem without link image.
The image is given by its path, and the position of the emblem is fixed by an integer:
0 = UPPER_LEFT, 1 = LOWER_RIGHT, 2 = LOWER_LEFT, 3 = UPPER_RIGHT, 4 = MIDDLE
The following command draws an arrow in the lower left corner of the Nautilus launcher.
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.SetEmblem string:/usr/share/icons/gnome/32x32/actions/gtk-go-down.png int32:2 string:"class=nautilus"

d.SetEmblem("gtk-go-down.png", CairoDock.LOWER_LEFT, "class=nautilus"


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:"class=firefox"

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:"module=clock"


DemandsAttention
Makes an icon demanding your attention. It will animate, and be visible even if the dock is hidden.
The following command demands the attention of the firefox launcher.
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.DemandsAttention boolean:true string:default string:"class=firefox"


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:""


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.