|
|
| 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:
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.
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 d.Add({'type':'Launcher', 'config-file':'application://vlc.desktop'})
You can also pass the complete path of the desktop file.
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'})
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
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:"" |
|
English
Français
Russian
Online users :