• Immutable Page
  • Info
  • Attachments

Dbus

plugin-dbus.png

Package

Compiz Plugins

Category

Utility

The Dbus plugin provides a means of interacting with Compiz through the D-Bus message passing interface.

These interactions include the ability to list the options offered by any enabled plugin, get the current values of and set new values for those options, and trigger actions.

D-Bus Session

The Dbus plugin is most effective in an environment with a valid D-Bus session. This means that a dbus-daemon process should be running and that a DBUS_SESSION_BUS_ADDRESS variable should be set in the environment.

A common way to ensure that such an environment is available is to include this check in a script that is executed when the user logs in:

# Avoid relying on autolaunch to improvise D-Bus sessions for each process
if test -z "$DBUS_SESSION_BUS_ADDRESS" ; then
    eval `dbus-launch --sh-syntax --exit-with-session`
fi

Destination Objects

In Compiz, the name of a destination object is /org/freedesktop/compiz/ followed by the name of the plugin, the screen number of the option, and the option name.

For example, /org/freedesktop/compiz/cube/screen0/skydome_image refers to the skydome image set for the Desktop Cube plugin, which applies to each screen individually (screen0 in this case).

{i} Most users will only have one set of screens connected to their X session. If you aren't sure whether an option is categorised under allscreens or screen0, feel free to try both.

Methods

There are four ways through which a user can interact with Compiz using D-Bus. Each of these methods is described below.

  • org.freedesktop.compiz.list

    • list every option available in a certain plugin on a given screen
    • returns a list of option names as strings
  • org.freedesktop.compiz.get

    • get the current value of a specific option in a certain plugin on a given screen
    • returns an option's value and its datatype
  • org.freedesktop.compiz.set

    • assign a new value to a specific option in a certain plugin on a given screen
    • the value to be assigned and its datatype must be included with the method call
  • org.freedesktop.compiz.activate

    • trigger an action associated with a keyboard, mouse, or screen edge binding
    • the X ID of the rood window and any additional parameters expected by the action must be included with the method call

{i} For the list and get methods, dbus-send must be run with the --print-reply parameter in order for the reply from Compiz to be shown.

The dbus-send Utility

dbus-send is a command line utility that allows users to interact with D-Bus services. The basic syntax for using dbus-send to communicate with Compiz is as follows:

dbus-send [--print-reply] --type=method_call --dest=org.freedesktop.compiz /org/freedesktop/compiz/destination_object org.freedesktop.compiz.method [additional parameters]

Destination objects and methods available for interacting with Compiz are described in their respective sections above. Examples of additional parameters may be found in Examples section below.

Examples

Listing every option available in the Desktop Cube plugin on screen0:

dbus-send --print-reply --type=method_call --dest=org.freedesktop.compiz /org/freedesktop/compiz/cube/screen0 org.freedesktop.compiz.list


Finding the current skydome image set for the Desktop Cube plugin on screen0:

dbus-send --print-reply --type=method_call --dest=org.freedesktop.compiz /org/freedesktop/compiz/cube/screen0/skydome_image org.freedesktop.compiz.get


Setting a new skydome image for the Desktop Cube plugin on screen0:

dbus-send --print-reply --type=method_call --dest=org.freedesktop.compiz /org/freedesktop/compiz/cube/screen0/skydome_image org.freedesktop.compiz.set string:"/path/to/new/image"


Using the Water plugin to draw a ripple starting at pixel coordinates (320, 240):

dbus-send --type=method_call --dest=org.freedesktop.compiz /org/freedesktop/compiz/water/allscreens/point org.freedesktop.compiz.activate string:'root' int32:`xwininfo -root | grep id: | awk '{ print $4 }'` string:'amplitude' double:1 string:'x' int32:320 string:'y' int32:240


Using the Switcher plugin to advance to the next window without just flipping back and forth between the same two windows:

dbus-send --type=method_call --dest=org.freedesktop.compiz /org/freedesktop/compiz/switcher/allscreens/next org.freedesktop.compiz.activate string:'root' int32:`xwininfo -root | grep id: | awk '{ print $4 }'`


Using the Scale plugin to show only windows with the string "Konsole" somewhere in their title:

dbus-send --type=method_call --dest=org.freedesktop.compiz /org/freedesktop/compiz/scale/allscreens/initiate_all org.freedesktop.compiz.activate string:'root' int32:`xwininfo -root | grep id: | awk '{ print $4 }'` string:"match" string:'title=.*Konsole.*'


List the array of images set for the Wallpaper plugin on screen0:

dbus-send --print-reply --type=method_call --dest=org.freedesktop.compiz /org/freedesktop/compiz/wallpaper/screen0/bg_image org.freedesktop.compiz.get


Setting a new image list for the Wallpaper plugin on screen0:

dbus-send --print-reply --type=method_call --dest=org.freedesktop.compiz /org/freedesktop/compiz/wallpaper/screen0/bg_image org.freedesktop.compiz.set array:string:"/path/to/new/image1","/path/to/new/image2","/path/to/new/image3"

Dbus Helper Script

A python script called 'compiz-dbus-send.py' originally written by crdlb helps simplify dbus commands. Attached is a slightly modified version. See the original here.

Download: compiz-send.py

Examples

Listing available plugins:

% compiz-send.py 
Available methods:
[...]
<node name="3d"/>
<node name="addhelper"/>
<node name="animation"/>
<node name="animationaddon"/>
<node name="annotate"/>
[...]

Listing the properties/methods available in the Viewport Switcher plugin:

% compiz-send.py vpswitch
begin_key
switch_to_1_key
switch_to_2_key
switch_to_3_key
switch_to_4_key
switch_to_5_key
[...]

Switching to the third workspace:

% compiz-send.py vpswitch switch_to_3_key

Combined with xdotool

DBus can be combined with xdotool to further automate your environment. The following script can be bound to a key binding. If no Firefox is running, it will switch to workspace 3 and start Firefox. If Firefox was already running but not focused, it will switch back to workspace 3 and focus it. If Firefox is already focused, it will open a new tab.

# get id
win=$(xdotool search --onlyvisible --class firefox | head -1)

if [ "x$win" = x ]; then
    # start
    compiz-send vpswitch switch_to_3_key
    gxmessage -center -timeout 2 -nofocus -buttons "" -borderless "loading firefox..."&
    exec ~/.bin/firefox "$*"
else
    if [ $win = $(xdotool getwindowfocus) ]; then
        # send it a key
        sleep 0.2; xdotool key --clearmodifiers --window $win Ctrl+t
    else
        # switch to it
        xdotool windowactivate $win
    fi
fi

Plugins/Dbus (last edited 2012-07-20 06:13:44 by Soreau)