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


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 2.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 the old version of this doc (for Cairo-Dock version 2.1, 2.2 and 2.3), please have a look 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: Actually Cairo-Dock provides other objects, associated with remote 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.

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


ReloadModule
Reloads a given module, as if you entered its config window and applied. This also works for internal modules (Taskbar, Dialogs, Icons, etc).
You can use it after making some modification in its config 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


ActivateModule
Activate or deactivate a module, as you would do from the config window. This does not work for internal modules.
If a module has several instances, all of them will be (de)instanciated.
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.ActivateModule string:dustbin boolean:true


Act on icons

Query an icon
Icons are refered by a query.
Ex.: to find the firefox icon(s), you can use the query "class=firefox".
to find the clock applet, you can use the query "module=clock".

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

You can 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 properties you can query on are:
  • type type of the icon, amongst TYPE_LAUNCHER ("Launcher"), TYPE_APPLICATION ("Application"), TYPE_APPLET ("Applet"), TYPE_SEPARATOR ("Separator"), TYPE_CONTAINER ("Container"), TYPE_CLASS_CONTAINER ("Class-Container"), TYPE_OTHER ("Other")
  • name name (label) of the icon
  • command command launched on click
  • class class of the corresponding program, by default Cairo-Dock will guess it automatically
  • container name of the container it belongs to
  • Xid ID of the window it is bound to (the one you get from a xwininfo, in hexa, octal or decimal)
  • config-file config file of the icon in the current theme
  • module for an applet, the name of its module
  • position relative position amongst the other icons of the container, starting from 0

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 SetIcon with the original 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:""


Add/Remove/Reload icons

AddLauncher
Adds a launcher into the current theme, a the given position and in the given dock, as if you dropped it from the Applications Menu into the dock
The launcher is specified by its desktop file; you can either pass the path to it, or an app URI (application://xxx.desktop)
If the position is not specified, the launcher is added after the other launchers.
If the dock name is not specified, the first main dock is used.
It returns the config file that has been added to the current theme.
Ex.: add a VLC launcher
dbus-send --print-reply --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.AddLauncher string:"application://vlc.desktop" double:0 string:""
where 0 is the position.
d.AddLauncher('application://vlc.desktop', 0, '') # returns '01vlc.desktop'


AddTemporaryIcon
Adds a temporary launcher, that is to say a launcher that is not stored in the current theme (after restarting the dock, it will not exist).
You can define the following properties:
  • type desired type amongst TYPE_LAUNCHER ("Launcher"), TYPE_SEPARATOR ("Separator"), TYPE_CONTAINER ("Container"); "Launcher" by default
  • icon name of an icon or path to an image
  • name label of the icon
  • container name of the container (by default, the first main dock)
  • quick-info quick-info (Null by default)
  • command command launched on click
  • class class of the corresponding program, by default Cairo-Dock will guess it automatically. Set it to "none" to skip the taskbar.
  • position relative position amongst the other icons of the container, starting from 0 (by default, at the end).
  • order absolute position
Ex.: add an VLC launcher that opens the Videos folders, until the dock is stopped.
python -c 'import dbus; print dbus.Bus().call_blocking(
"org.cairodock.CairoDock",
"/org/cairodock/CairoDock",
"org.cairodock.CairoDock",
"AddTemporaryIcon",
"a{sv}",
({"icon": "vlc", "name": "Video Player", "position": dbus.Int32(1), "command": "vlc ~/Videos"},))'
(we have to use Python because it seems it's currently not possible to send a dict of {String, Variant} with dbus-send)
d.AddTemporaryIcon({'icon':'vlc', 'name':'video player', 'position':2, 'command':'vlc ~/Videos'})


ReloadIcon
Reloads an icon as if you entered its config window and applied.
Most of the time, you will want to query the icon on its config file (since you probably just modified it, and it will ensure you reload the correct icon).
Ex.: reload the VLC launcher:
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.ReloadIcon string:"config-file=01vlc.desktop"

d.ReloadIcon('config-file=01vlc.desktop')

Ex.: reload the first instance of the Clock applet:
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.ReloadIcon string:"config-file=clock.conf"

d.ReloadIcon('config-file=clock.conf')


RemoveIcon
Removes an icon as if you did it from the menu.
Querying the icon on its config file will ensure you delete the correct icon. But for temporary launchers for instance, it can be interesting to query on the command.
Ex.: remove the first instance of the Clock applet:
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.RemoveIcon string:"config-file=clock.conf"

d.RemoveIcon('config-file=clock.conf')

Ex.: remove the temporary VLC launcher we added previously:
dbus-send --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.RemoveIcon string:"class=Vlc"

d.RemoveIcon('vlc ~/Videos')


Get properties

GetIconProperties
Get all the properties about one or several icons, given by a query.
Ex.: get the properties of all the icons of the main dock:
dbus-send --print-reply --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.GetIconProperties string:"container=_MainDock_"

Ex.: get the properties of the firefox icon(s):
dbus-send --print-reply --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.GetIconProperties string:"class=firefox"

The properties are currently:
  • type TYPE_LAUNCHER ("Launcher"), TYPE_APPLICATION ("Application"), TYPE_APPLET ("Applet"), TYPE_SEPARATOR ("Separator"), TYPE_CONTAINER ("Container"), TYPE_CLASS_CONTAINER ("Class-Container"), TYPE_OTHER ("Other")
  • config-file config file of the icon, stored in the current theme
  • name name/label
  • module for an applet, the name of its module
  • command command launched on click
  • class class of the corresponding program
  • icon name of an icon or path to an image
  • quick-info the quick-info currently displayed
  • Xid ID of the window it is bound to (the one you get from a xwininfo, in hexa, octal or decimal)
  • module module name, if the icon is an instance of a module
  • position relative position amongst the other icons of the container, starting from 0
  • container name of the container it belongs to
  • order absolute position

GetContainerProperties
Get all the properties about a given container (dock or desklet), or all containers if no container is specified (empty string or "any").
dbus-send --print-reply --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.GetContainerProperties string:_MainDock_

The properties are currently:
  • x x coordinate of the top-left corner of the container's window, with (0,0) = top-left screen corner.
  • y y coordinate of the top-left corner of the container's window.
  • width width of the container
  • height height of the container
  • orientation BOTTOM = 0, TOP = 1, RIGHT = 2, LEFT = 3
  • type DOCK = "Dock" or DESKLET = "Desklet"
  • name name of the container; for a desklet, it's the name of the applet.
  • is-sub-dock True iif it's a sub-dock.
  • nb-icons number of icons in the container

GetModuleProperties
Get all the properties about a given module, or all modules (listed in alphabetical order) if no module is specified (empty string or "any").
dbus-send --print-reply --session --dest=org.cairodock.CairoDock /org/cairodock/CairoDock org.cairodock.CairoDock.GetModuleProperties string:clock

The properties are currently:
  • name name of the module
  • type type of the applet (a logical "or" between CAN_DOCK (1) and CAN_DESKLET (2); 0 means it's a plug-in, with no icon).
  • category category (CATEGORY_BEHAVIOR=0, CATEGORY_THEME, CATEGORY_APPLET_FILES, CATEGORY_APPLET_INTERNET, CATEGORY_APPLET_DESKTOP, CATEGORY_APPLET_ACCESSORY, CATEGORY_APPLET_SYSTEM, CATEGORY_APPLET_FUN)
  • title title of the module, used to be displayed to the user.
  • icon path of the module's icon
  • preview path of a preview image
  • description translated description
  • author author
  • is-multi-instance whether the module can be instanciated several times.
  • instances an array of the config file of each instance of the module.


Glx-Dock / Cairo-Dock Wiki Control_your_dock_with_DBus Top

Online users : Willmore,

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.