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.

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

The new configuration files consist of one rule for each file, e.g.

(if 
  (is (application_name) "firefox-bin") 
  (set_workspace 2)
)

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

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

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

(and a b)

boolean and(boolean a, boolean b)

Returns the result of and-ing the logical expressions a and b.

Examples:

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

(or a b)

boolean or(boolean a, boolean b)

Returns the result of or-ing the logical expressions a and b.

Examples:

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

(not a)

boolean not(boolean a)

Returns the negation of the given logical expression a.

Examples:

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

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

String window_name()

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

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

String application_name()

Returns a STRING containing the name of an application.

Once a window has been selected using a single matcher or a combination of matchers, on or more of the following actions can be applied to it.

(debug)

void debug()

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

(print text)

void print(String text)

Prints the String text to stdout, useful for debugging purposes.

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

(fullscreen)

void fullscreen()

Sets the matched window into fullscreen mode.

(focus)

void focus()

Gives focus to the matched window.

(center)

void center()

Centers the matched window on the screen.

(maximize)

void maximize()

Maximizes the matched window horizontally and vertically.

(maximze_vertically)

void maximize_vertically()

Maximizes the matched window vertically.

(maximize_horizontally)

void maximize_horizontally()

Maximizes the matched window horizontally.

(minimize)

void minimize()

Minimizes the matched window.

(shade)

void shade()

Shades aka “rolls up” the matched window.

(unshade)

void unshade()

Unshades aka “rolls down” the matched window.

(close)

void close()

Closes the matched window.

(pin)

void pin()

Pins aka “sticks” the matched window, making it visible on all workspaces.

(unpin)

void unpin()

Unpins the matched window.

(set_workspace num)

void set_workspace_num(int num)

Moves the matched window to workspace number num.

Example:

• (set_workspace 1)

(skip_pager)

void skip_pager()

Stops the matched window from being shown in the pager.

(skip_tasklist)

void skip_tasklist()

Stops the matched window from being shown in the tasklist.

(above)

void above()

Makes the matched window be always on top.

(below)

void below()

Makes the matched window stay under all other windows.

(undecorate)

void undecorate()

Removes the window manager decoration from the matched window.

(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”)