• Plugins
• Dbus

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

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

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

(Full discussion at http://forum.compiz-fusion.org/showthread.php?t=2191 )

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

(Full discussion at http://forum.compiz-fusion.org/showthread.php?t=2797 )

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.*'

(Full discussion at http://forum.compiz-fusion.org/showthread.php?t=5754 )