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 http://www.glx-dock.org/ww_page.php?p=Documentation&lang=en.

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 the Installation page. Be sure to upgrade the plug-ins too.

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

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

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.

Note: you will need to ensure that the Python interface of Cairo-Dock is in your PYTHONPATH. It is installed under {prefix}/share/cairo-dock/plug-ins/Dbus/ where {prefix} is your installation prefix (typically /usr if you installed using your package manager). So you would start Python by e.g. PYTHONPATH=/usr/share/cairo-dock/plug-ins/Dbus/ python3

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

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

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

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

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*)

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

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})

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'})

This adds another instance of a given module. If the module is not yet activated, it will activate it. The module must be multi-instantiable.

d.Add({'type':'Module-Instance', 'module':'clock'})

d.Add({'type':'Dock'})

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')

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)

Gets the properties of the firefox Launcher.

d.GetProperties("'type=Launcher & class=firefox')

E.g. print the position of each desklets.

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

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"

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"

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"

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"

or

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

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"

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"

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