Devil's Pie documentation

First of all: What is Devil's Pie? From the developer's site:

A window-matching utility, inspired by Sawfish's “Matched Windows” option and the lack of the functionality in Metacity. Metacity lacking window matching is not a bad thing — Metacity is a lean window manager, and window matching does not have to be a window manager task.

Devil's Pie can be configured to detect windows as they are created, and match the window to a set of rules. If the window matches the rules, it can perform a series of actions on that window. For example, I can make all windows created by X-Chat appear on all workspaces, and the main Gkrellm1 window does not appear in the pager or task list.

With the release of version 0.13 the configuration files changed from an xml-based format to s-expressions. This wiki node represents my try at documenting the new format, as sadly there is no official documentation yet. The information I provide here was kinda extracted from the source code of Devil's Pie.

I will give a generic syntax definition for each function, followed by a Java-Representation in order to describe the defined datatypes, using the following conventions:

  • String means a valid string, e.g. “firefox-bin”.
  • int means a valid integer value, e.g. 0 or 800.
  • boolean means a boolean value, either true or false.
  • Object means a mixed type determined at runtime.

There is also a small collection of example rules with a description of what they do.

The current version of this document covers Devil's Pie from 0.13 up to 0.20.2. I do my best to update it as soon as I find time to search the codebase of current versions for changes and describe them.

General format

The configuration files consist of rules formulated in an s-expression based syntax, with ; denoting comment-lines which are not parsed, e.g.

; Move firefox to workspace 2
(if 
  (is (application_name) "firefox-bin") 
  (set_workspace 2)
)

Those files have the extension ds and usually are located at ~/.devilspie.

If I say “one rule for each file”, I really mean it: If you add more than one, the others will simply be ignored by Devil's Pie's parser (at least up to version 0.20). So be sure to make a file for each rule you want to define.

What you can do though is encapsulate several rules in one begin block, this works like a charm. Additonally, with version 0.20 Devil's Pie also seems to have support for multiple expressions per file natively, though I haven't tested this yet myself. Whether you want to use this is up to you - I prefer the “one-rule-per-file” variant for the sake of clarity ;-).

Examples

The configuration currently in use on my ThinkPad can be found here.

  • Move Firefox to workspace 2 and maximize it:
    (if
        (is (application_name) "firefox-bin")
        (begin
           (set_workspace 2)
           (maximize)
        )
    )
  • Pin the Gaim Buddylist to all workspaces, with a size of 340×630 pixels and at position (4,150):
    (if
        (and 
            (is (application_name) "gaim")
            (is (window_name) "Buddy List")
        )
        (begin
            (pin)
            (geometry "340x630+4+150")
        )
    )
  • Move Skype to workspace 1, set its size to 300×600 pixels, center it, make it “always on top” and let it skip pager and tasklist:
    (if
        (matches (application_name) "^Skype")
        (begin
            (geometry "300x600")
            (center)
            (above)
            (skip_pager)
            (skip_tasklist)
        )
    )
  • Move a gaim window that is neither the buddy list nor an IRC conversation (thanks to Andrew Conkling for this example):
    (if
        (and 
            (is (application_name) "gaim") 
            (not (is (window_name) "Buddy List"))
            (not (contains (window_name) "#"))
        )
        (geometry "+0+313")
    )
  • Remove the window decoration from all windows:
    (undecorate)
  • Combine two rules into one file:
    (begin
        (if
            (is (application_name) "firefox-bin")
            (begin
                (set_workspace 2)
                (maximize)
            )
        )
        (if
            (and 
                (is (application_name) "gaim") 
                (not (is (window_name) "Buddy List"))
                (not (contains (window_name) "#"))
            )
            (geometry "+0+313")
        )
    )

Constructs

if

(if a b)
 
(if a b c)
if (a) { 
    b; 
}
 
if (a) { 
    b; 
} else { 
    c; 
}

A conditional flow based on the boolen expression a.

Example:

  • (if (is (application_name) “firefox_bin”) (set_workspace 2)) - Moves the window to workspace 2 if the application it belongs to is Firefox.

begin

(begin a b c ...)
{
    a;
    b;
    c;
    // ...
}

A sequential execution of actions a, b, c, …

Example:

  • (if (is (application_name) “firefox_bin”) (begin (set_workspace 2) (maximize))) - If the window belongs to the application Firefox, move it to workspace 2 and maximize it.

Boolean Operations

and

(and a b ...)
boolean and(boolean a, boolean b, ...)

Returns the result of and-ing the given logical expressions.

Examples:

  • (and true true) - true
  • (and true false) - false
  • (and false false) - false
  • (and true true true) - true
  • (and true false true) - false

or

(or a b ...)
boolean or(boolean a, boolean b, ...)

Returns the result of or-ing the given logical expressions.

Examples:

  • (or true true) - true
  • (or true false) - true
  • (or false false) - false
  • (or false false false) - false
  • (or false false true) - true

not

(not a)
boolean not(boolean a)

Returns the negation of the given logical expression a.

Examples:

  • (not true) - false
  • (not false) - true

String Tests

is

(is a b)
boolean is(String a, String b)

Returns true if a and b are the same.

Examples:

  • (is “foo” “foo”) - true
  • (is “foo” “bar”) - false

contains

(contains haystack needle)
boolean contains(String haystack, String needle)

Returns true if needle is a sub-string of haystack.

Examples:

  • (contains “somefoobar” “foo”) - true
  • (contains “somefoobar” “fnord”) - false

matches

(matches str pattern)
boolean matches(String str, String pattern)

Returns true if pattern matches on string. pattern is a Regular Expression.

Examples:

  • (matches “foobar” ”[o]{2}b”) - true
  • (matches “foobar” ”[0-9]+”) - false

Matchers

Matchers return certain properties of the available windows – like windowtitle, applicationame, … – and are used to formulate conditions to match certain programs and/or windows.

window_name

(window_name)
String window_name()

Returns a STRING containing the name of the window as displayed in the windows titlebar.

window_role

(window_role)
String window_role()

Returns a STRING describing the current window role of the matched window as defined by it's WM_WINDOW_ROLE hint.

application_name

(application_name)
String application_name()

Returns a STRING containing the name of a windows application.

window_workspace

(window_workspace)
int window_workspace()

Returns an INT containing the number of a windows workspace aka virtual desktop.

window_class

(window_class)
String window_class()

Returns a STRING containing the class of a window.

window_xid

(window_xid)
int window_xid()

Returns an INT containing the XID of a window.

window_property

(window_property propertyname)
String window_property(String propertyname)

Returns a STRING containing the value of the requested property of a window. See the "Application Window Properties" part of the "Extended Window Manager Hints" specification for a list of possible window properties to request.

Actions

One or more of the following actions can be applied to a set of selected windows, which can be either a subset of all windows on the screen (created by using a single matcher or a combination of matchers and the if statement) or simply all windows.

debug

(debug)
void debug()

Prints information to stdout about matched open windows, including applicationname, windowtitle, windowrole and geometry.

print

(print text)
void print(String text)

Prints the String text to stdout (without a newline at the end), useful for debugging purposes.

println

(println text)
void println(String text)

Prints the String text to stdout (with a newline at the end), useful for debugging purposes.

str

(str value)
String str(Object value)

Converts given value into a String and returns it. The value can be boolean, int, a String, an array pointer or even a timestamp which is then formatted into a date respresentation as defined by the current locale.

hex

(hex num)
String hex(int value)

Converts given value into a String containing the value's hexadecimal representation (including a 0x at it's beginning).

geometry

(geometry geo)
void geometry(String geo)

Sets the geometry of the matched window. geo must be a STRING containing a valid X-GeometryString as parsed by XParseGeometry. Excerpt from man XParseGeometry:

       By convention, X applications use a standard string to indicate window
       size and placement.  XParseGeometry makes it easier to conform to this
       standard because it allows you to parse the standard window geometry.
       Specifically, this function lets you parse strings of the form:

       [=][<width>{xX}<height>][{+-}<xoffset>{+-}<yoffset>]

Examples:

  • (geometry “400×300+0-22”)
  • (geometry “640×480”)
  • (geometry ”+10+10”)
A friendly hint from the comments, courtesy of Kai-Martin Knaak:

Dialogs and splashscreens don’t accept position and size commands. They have to be turned into normal windows with the wintype command before devilspie can direct them to some other place.

fullscreen

(fullscreen)
void fullscreen()

Sets the matched window into fullscreen mode.

focus

(focus)
void focus()

Gives focus to the matched window.

center

(center)
void center()

Centers the matched window on the screen.

maximize

(maximize)
void maximize()

Maximizes the matched window horizontally and vertically.

maximize_vertically

(maximze_vertically)
void maximize_vertically()

Maximizes the matched window vertically.

maximize_horizontally

(maximize_horizontally)
void maximize_horizontally()

Maximizes the matched window horizontally.

unmaximize

(unmaximize)
void unmaximize()

Unmaximizes the matched window horizontally.

minimize

(minimize)
void minimize()

Minimizes the matched window.

unminimize

(unminimize)
void unminimize()

Unminimizes the matched window.

shade

(shade)
void shade()

Shades aka “rolls up” the matched window.

unshade

(unshade)
void unshade()

Unshades aka “rolls down” the matched window.

close

(close)
void close()

Closes the matched window.

pin

(pin)
void pin()

Pins the matched window, making it visible on all workspaces.

unpin

(unpin)
void unpin()

Unpins the matched window.

stick

(stick)
void stick()

Sticks the matched window, making it visible on all viewports.

unstick

(unstick)
void unstick()

Unsticks the matched window.

set_workspace

(set_workspace num)
void set_workspace(int num)

Moves the matched window to workspace number num (counting from 1).

Example:

  • (set_workspace 1)

set_viewport

(set_viewport num)
void set_viewport(int num)

Moves the matched window to viewport number num (counting from 1).

Example:

  • (set_viewport 2)

skip_pager

(skip_pager)
void skip_pager()

Stops the matched window from being shown in the pager.

skip_tasklist

(skip_tasklist)
void skip_tasklist()

Stops the matched window from being shown in the tasklist.

above

(above)
void above()

Makes the matched window be always on top.

below

(below)
void below()

Makes the matched window stay under all other windows.

undecorate

(undecorate)
void undecorate()

Removes the window manager decoration from the matched window.

wintype

(wintype type)
void wintype(String type)

Sets the window type of the matched window. type can be one of the following values: “normal”, “dialog”, “menu”, “toolbar”, “splashscreen”, “utility”, “dock”, “desktop”.

See the _NET_WM_WINDOW_TYPE part of the "Extended Window Manager Hints" specification for more details on what exactly this can do.1)

Examples:

  • (wintype “normal”)
  • (wintype “toolbar”)

opacity

(opacity percent)
boolean opacity(int percent)

Sets the opacity of the matched window to the given percentage. Returns true upon success.

spawn_sync

(spawn_sync command)
(spawn_sync command1 command2 ...)
String spawn_sync(String command)
String spawn_sync(String[] command)

Executes the given command (given as either one String or a list of multiple Strings) in the foreground and returns its output as a String.

spawn_async

(spawn_async command)
(spawn_async command1 command2 ...)
boolean spawn_async(String command)
boolean spawn_async(String[] command)

Executes the given command (given as either one String or a list of multiple Strings) in the background and returns true upon successful command start.

See also

1) Big thanks go out to Lenix, who provided me with above link and explained the whole windowtype thing to me :-)

Discussion

P4p3rDr4g0nP4p3rDr4g0n, 2011/02/25 11:38

Can you recommend a good book on the subject? www.konyv-konyvek.hu

ahmedahmed, 2011/03/17 01:39

hi

I tried to do the examples after installation but nothing is happening !

TomTom, 2011/07/15 17:12

is there some way to resize a window to some proportion of the viewable area? to simulate the compiz grid plugin or winsplit revolution on windows?

BoozaaBoozaa, 2011/08/22 20:22

You must start the daemon.

You can use a gtk ui : http://code.google.com/p/gdevilspie/downloads/list

Simply install it with “sudo python setup.py install”

JohnJohn, 2011/08/31 17:41

Hi

Just wondering, atm i have a command to minimize an application to tray however due to this when the daemon is on i then cannot open the minimised app. Is there a way to tell it to only minimise for the first time?

Regards,

You could leave a comment if you were logged in.
linux/devilspie.txt · Last modified: 2010/05/16 21:45 by foosel