sawfish Programming Manual

Next: , Previous: (dir), Up: (dir)

This document describes the Lisp programming interface to sawfish, an extensible X11 window manager.

For edit history, see ChangeLog file.

Next: , Previous: Top, Up: Top

1 Copying

Sawfish is copyright (C) 1999 John Harper and is released under the terms of the GNU General Public License. See the included file COPYING for the full text of the license (or see Copying).

This is free software – you are welcome to redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.

Sawfish is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Next: , Previous: Copying, Up: Top

2 Introduction

Sawfish is a lisp-extensible window manager for X11. Its aim is to allow all areas of window management (decoration, manipulation) to be customized as far as is possible, yet still remain as fast or faster than existing window managers.

Despite this extensibility its policy is very minimal compared to most window managers. It does not implement desktop backgrounds, applications docks, or other things that may be achieved through separate applications.

All high-level window management functions are implemented in Lisp for future extensibility or redefinition. Also, most received events are exported to the Lisp environment through key-bindings and hooks, similar to in Emacs. These events include pointer behavior and many internal X11 events.

Sawfish uses the librep Lisp environment (see Overview), this is a run-time library implementing a language similar to Emacs Lisp (see Overview), but with many extensions, and using lexical instead of dynamic scope. This manual assumes at least a basic knowledge of the language.

Homepage and mailing list are listed in See FAQ.

Next: , Previous: Introduction, Up: Top

3 News

This lists user-visible changes, and which releases they occurred between. For more detailed information see the ChangeLog file in the Sawfish source tree, or git log. (See the Wiki on how to access git repository.)

Each release lists incompatible changes at its top.

1.8.0 "思いやり (Omoiyari)"

1.7.0 "Frozen Flame"

1.6.3 "Hava Nagila"

1.6.2 "Mighty Disco King"

1.6.1 "Astral"

1.6.0 "Sound Of Thunder"

1.5.0 "The Hardstyle Factory"

The new release is Sawfish-1.5.0. We don't release 1.4 series for historical reason. The next will be 1.6, and 1.5.x are for bugfix branches.

1.3.5

1.3.4

1.3.3

1.3.2

1.3.1

1.3

1.2

1.1

1.0.1

0.99

0.38

0.37

0.36

0.35

0.34

0.33

0.32

0.31.1

0.31

0.30.3

0.30.2

0.30

0.29

0.28.1

0.28

0.27.2

0.27

0.26

0.25.2

0.25.1

0.25

0.24

0.23

0.22

0.21.1

0.21

0.20

0.19

0.18

0.17

0.16

0.15

0.14

0.13

0.12

0.11

0.10

0.9

0.8

0.7

0.6

0.5

0.4

0.3a

0.3

0.2

0.1

First proper release

Next: , Previous: News, Up: Top

4 Colors

Sawfish provides a primitive type allowing colors to be represented. Each color object allows a single color value to be named and passed between Lisp functions.

— Function: colorp arg

Returns t when arg is a member of the color type.

— Function: get-color name #!optional alpha

Returns the color object representing the color specified by the string name. This is according to the standard X11 color specifiers, either a named color from the rgb.txt database, or a string defining the red, green and blue components of the color, either eight or sixteen bits in hexadecimal, i.e. ‘#RRGGBB’ or ‘#RRRRGGGGBBBB’.

Optional argument alpha becomes the alpha value of the returned color. It is passed through to get-color-rgb.

Signals an error if no known color has the name name.

— Function: get-color-rgb red green blue #!optional alpha

Return the color object representing the color with RGB components as specified (each component ranging from 0 to 65535).

Optional argument alpha becomes the alpha value of the returned color. Use an integer value in the range from 0 to 65535. Integers outside that range are not supported, while non-integers such as nil are silently converted to 65535 (fully opaque).

Given a color object, it's possible to find both the actual rgb values defining the color and one of the names that X11 uses to refer to the color.

— Function: color-rgb color

Return a list of integers (red green blue alpha), the actual color values of the color represented by object COLOR. The individual values range from 0 to 65535.

— Function: color-rgb-8 color

Return a list of integers (red green blue alpha), just like color-rgb. However, the color values are scaled to fit a range from from 0 to 255.

— Function: color-name color

Return the name of the color represented by the color object color. Note that this picks one name from the set of valid names for this color; it may well be different to the name used when the color was originally allocated.

The X11 name does not include alpha information.

Where a color object is used to define the foreground color of a piece of text, the default-foreground color provides the default value used if no actual color is specified.

— Variable: default-foreground

The color used for text where no other color is defined.

Next: , Previous: Colors, Up: Top

5 Fonts

Lisp font object allows manipulation of correspondig X11 fonts.

— Function: fontp arg

Returns t if arg is a font object.

Sawfish supports three “types” of fonts: X11 old core fonts (fontsets and fontstructs), Xft fonts, and if supported, Pango fonts. In lisp, type is represented by a string, "xlfd", "Xft", or "Pango".

— Function: font-type-exists-p type

Returns true if fonts of type are available, false otherwise.

— Function: get-font-typed type name

Returns a font object which represents an X11 font. It's specified by the string name, and string type. Signals an error if the specified font is not available.

“Safe” examples are: 

          (get-font-typed "xlfd" "fixed")
          (get-font-typed "Xft" "Sans")
          (get-font-typed "Pango" "Sans")
— Function: get-font name

Return a font object representing the X11 core font (fontset or fontstruct) specified by the string name.

Signals an error if no font named name is available among the X11 core fonts.

Several functions allow the attributes associated with a font object to be found.

— Function: font-name font

Returns the name, in string, of the X11 font represented by object font.

— Function: font-type font

Returns the font's type. It is one of "xlfd", "Xft", and "Pango".

— Function: font-height font

Returns the bounding height of glyphs in the font represented by object font.

— Function: font-ascent #!optional font

Returns the ascent of glyphs rendered using the font represented by font. If no font argument is given, use the default font.

— Function: font-descent #!optional font

Returns the descent of glyphs rendered using the font represented by font. If no font argument is given, use the default font.

— Function: text-width string #!optional font

Returns the number of horizontal pixels that would be required to display the text string using font object font (or the value of the default-font variable if font is undefined).

As with colors, a default font may be specified, to be used where no other font is specified.

— Variable: default-font

Font object used when no other font has been specified.

Fonts can have Lisp properties associated with them (similar to the property lists associated with symbols). Currently these aren't actually used by the window manager.

— Function: font-put font property value

Associate the lisp object value with the property named by the symbol property of the font object font.

— Function: font-get font property

Return the value of the property named by the symbol property of the font font, or nil if no such property exists.

— Variable: fonts-are-fontsets

True if the X fonts in use are fontsets. This will be false if setlocale fails, or returns an ASCII locale, or if X doesn't support the locale.

Next: , Previous: Fonts, Up: Top

6 Images

The image type allows arbitrary 24-bit images to be manipulated by the window manager. Images may be both loaded from files, and rendered dynamically.

— Function: imagep arg

Returns t when arg is a member of the image type.

— Function: make-image file-name #!optional plist

Creates and returns an image object containing the image defined by the contents of the file named file-name (a string). The image-load-path directory provides the search path used while trying to find a directory containing the file named file-name.

All common image formats will likely be able to be loaded. But PNG, JPEG and XPM should always be supported.

Argument plist becomes the property list of the returned image.

Signals an error if file called file-name may be found, or if an image may not be constructed from the file.

— Variable: image-directory

Directory containing built-in Sawfish images. By default, this is sawfish-directory/images.

— Variable: image-load-path

A list of directory names. This defines the search path used when loading images. By default, this is ("." image-directory). Modifying image-directory does not modify image-load-path.

— Function: make-sized-image width height #!optional color

Create and return a new image, of size width, height. If color is defined it specifies the color of all pixels in the image. If undefined, all pixels will be black.

— Function: make-image-from-x-drawable id #!optional mask-id

Create and return an new image. The image is constructed by copying an X Drawable (identified by id) into a Sawfish image object. The function automatically handles depth conversion.

If mask-id is given, it identifies another X Drawable. Black pixels in this drawable indicate transparent pixels in the image object (non-black pixels have no effect on the image object).

— Function: copy-image image

Returns a newly allocated image object, an exact copy of the image object image.

— Function: image-dimensions image

Returns a cons-cell (width . height) defining the dimensions of the image represented by image.

— Function: flip-image-horizontally image

Flip the contents of image about the vertical axis. This is a mutating operation that returns the modified argument.

— Function: flip-image-vertically image

Flip the contents of image about the horizontal axis. This is a mutating operation that returns the modified argument.

— Function: flip-image-diagonally image

Flip the contents of image about an axis running from the top-left corner to the bottom-right corner of the image. This is a mutating operation that returns the modified argument.

As with many of the other types, arbitrary state may be associated with image objects.

— Function: image-put image property value

Set the property named property (a symbol) of image to value.

— Function: image-get image property

Return the property named property of image, or nil if no such property exists.

The only predefined property is the symbol tiled, used when an image is displayed in a window decoration. When set to a non-nil value the image is not scaled to the size of the decoration (the default), but is tiled across the decoration.

When images are scaled across border decorations the pixels that are actually scaled are defined by the border of the image. The border defines the outer rectangle of pixels that are left as-is, and the inner rectangle which is scaled.

— Function: image-border image

Returns a list of integers (left right top bottom), the border of the image object image.

The number associated with each edge of the image defines the number of pixels adjacent to that edge that will not be scaled.

— Function: set-image-border image left right top bottom

Sets the border of image.

The number associated with each edge of the image defines the number of pixels adjacent to that edge that will not be scaled.

The shape of the image may also be specified, this defines which pixels are treated as being transparent. Each image may define a single color as marking transparent pixels.

Image shapes are not supported under GDK Pixbuf. Sawfish will print a diagnostic message to STDERR if the function is called without being supported.

— Function: image-shape-color image

Return the color marking transparent pixels in image, or nil if no such color has been specified.

— Function: set-image-shape-color image color

Specify that color marks transparent pixels in image.

It's also possible to define color modifiers for each image. These define the transformation applied to the value of each pixel when it is displayed. Four different modifiers exist for each image, one for each color component, and one for the image as a whole.

— Function: image-modifier image type

Return the modifier defined by the symbol type of image, a list of integers (gamma brightness contrast). Each integer has a value between zero and 255 representing the weight applied to the associated attribute when rendering the image.

The four types are red, green, blue and nil (all colors). The argument must be eq to one of those symbols.

— Function: set-image-modifier image type gamma brightness contrast

Set the image modifier of image defined by type. Type may be one of the values of (not the symbols) red, green or blue.

There are also several other functions manipulating images:

— Function: bevel-image image border upwards #!optional bevel-percent

Transform the edgemost pixels of image to give it a “bevelled” effect. BORDER is an integer defining the width of the bevel. If upwards is non-nil the bevel is raised, otherwise it is lowered.

If bevel-percent is defined it specifies the height or depth of the drawn bevel. When undefined, the value of the parameter is taken from the default-bevel-percent variable.

— Variable: default-bevel-percent

Default height of drawn bevels, as a percentage. Normally 50%.

— Function: clear-image image #!optional color

Set all pixels in image to color (or black if color is undefined).

— Function: tile-image dest-image source-image

Tiles source-image into dest-image, starting from the upper-left corner, working outwards.

— Function: scale-image image width height

Return a copy of image, scaled to width by height pixels.

— Function: composite-images image1 image2 #!optional x y

Copy the contents of image2 into image1. Image2 is cropped to fit. Arguments x and y indicate the position in image1 of the top-left corner of image2. If not supplied, they default to 0.

— Function: crop-image image x y width height

Return a new image that is a rectangular section of image. The result image starts at pixel (x, y) in image, and extends over width and height pixels in image.

When the cropped image extends beyond the boundary of image, the behavior is undefined.

The following functions allow users to manipulate images on a pixel-by-pixel level. They all use a list representation for pixels: (r, g, b, a) indicating the red, green, blue and alpha components

— Function: image-ref image x y

Return a list (r, g, b, a) of the red, green, blue and alpha components of the pixel (x, y) in image.

When the pixel position extends outside the bounds of the image, the behavior is undefined.

— Function: image-set image x y pixel

Set the pixel at (x, y) in image to pixel. Pixel is a list of four numbers (r, g, b, a), the red, green, blue and alpha components.

When the pixel position extends outside the bounds of the image, the behavior is undefined.

— Function: image-map xform image

Transform each pixel in image in place by calling xform on each pixel in the image.

Xform takes a single argument, a four element list (r, g, b, a) indicating the red, green, blue and alpha components of a pixel. Xform should return the new value for the pixel it was given. The return format is the same four-element list.

Xform is allowed to return nil. In this case, image-map immediately returns an invalid object.

— Function: image-fill generator image

Set each pixel in image based on the results of calling generator.

Generator takes two arguments: the X and Y coordinates of a pixel. It returns a four element list (r, g, b, a) indicating the red, green, blue and alpha components of a pixel. This new pixel replaces the current pixel contents at (X, Y).

Generator is allowed to return nil. In this case, image-map immediately returns an invalid object.

— Function: pixmap-cache-control max

Tell Sawfish to cache no more than max pixels. Returns a four-element list indicating the current cache status: (max-cached-pixels, cached-pixels, hits, misses).

Next: , Previous: Images, Up: Top

7 Cursors

Cursors define the shape and hot-spot of the mouse pointer's image. A lisp type is provided for manipulating these objects. For pointer related functions, See Pointer Functions.

— Function: cursorp arg

Returns t if arg is a member of the cursor type.

— Function: get-cursor data

Returns the cursor object representing the cursor defined by data. If data is a symbol, it's replaced by its cursor-shape property.

Possible data values are an integer representing a glyph in the standard X11 cursor font, or a four-element vector.

The format for a vector is [image mask fg bg] where image and mask are the filenames of standard X11 bitmaps, and fg and bg are colors (or names of colors). All bitmap files are searched for using the image-load-path variable.

— Function: recolor-cursor cursor fg bg

Change the colors of the cursor object cursor to fg and bg (either color objects or the names of colors).

— Function: default-cursor #!optional cursor

Set the cursor object displayed in the root window, and in parts of window frames that have no other cursor specified, to cursor.

If called with no argument, simply return the current such cursor object.

So that the integer indices of glyphs in the X11 cursor font do not have to be remembered, the cursor-shape properties of the following symbols are automatically set:

X_cursor, arrow, based_arrow_down, based_arrow_up, boat, bogosity, bottom_left_corner, bottom_right_corner, bottom_side, bottom_tee, box_spiral, center_ptr, circle, clock, coffee_mug, cross, cross_reverse, crosshair, diamond_cross, dot, dotbox, double_arrow, draft_large, draft_small, draped_box, exchange, fleur, gobbler, gumby, hand1, hand2, heart, icon, iron_cross, left_ptr, left_side, left_tee, leftbutton, ll_angle, lr_angle, man, middlebutton, mouse, pencil, pirate, plus, question_arrow, right_ptr, right_side, right_tee, rightbutton, rtl_logo, sailboat, sb_down_arrow, sb_h_double_arrow, sb_left_arrow, sb_right_arrow, sb_up_arrow, sb_v_double_arrow, shuttle, sizing, spider, spraycan, star, target, tcross, top_left_arrow, top_left_corner, top_right_corner, top_side, top_tee, trek, ul_angle, umbrella, ur_angle, watch, xterm.

The glyphs associated with these names are shown in Appendix I, of Volume Two, Xlib Reference Manual.

Next: , Previous: Cursors, Up: Top

8 Windows

One of the most important data types in sawfish is the window type. All managed client windows have a single window object associated with them.

— Function: windowp arg

Returns t if arg is a member of the window type, and has a client window associated with it.

Since the root window is not a managed client window, it is not represented by a window object. Sometimes functions' arguments and return value treat the symbol root as the root window. Window hooks are so. But sometimes not.

Basics:

Next: , Up: Windows

8.1 Window Attributes

Many attributes are described in the related sections.

First, basic attributes, like name, class, ID, etc.

— Function: window-name window

Return the name associated with window.

— Function: window-full-name window

Return the full-name associated with window. This may or may not be the same as the normal name.

Sawfish provides functions to ensure that window names are unique.

— Function: uniquify-name proposal existing

Uniquify the string proposal against the list of strings existing. Uses the format string uniquify-name-format to generate unique names.

— Variable: uniquify-name-format

Format to create unique window names. Defaults to "%s [%d]".

— Function: uniquify-window-name window
— Command: uniquify-window-name window

Force window to have a unique title.

— Function: rename-window win name

Change the window's name to name. This works in practice, but technically ICCCM doesn't suppose window name changes.

— Function: window-class window #!optional spec

If the optional argument spec is nil, returns the class that window belongs to as a string, or nil if window has no associated class.

ICCCM class consists of “Instance” and “Class”. If spec is the symbol cons, then the cons of the form (instance . class) is returned. If spec is the symbol configurator, then the string of the form “instance/class” is returned.

— Function: window-role window

Return the window role set by NET_WM_ROLE.

— Function: window-id window

If window object window has a client window associated with, return an integer defining its xid, otherwise return nil.

— Function: root-window-id

Returns the numeric ID of the root window of the managed screen.

— Function: window-dimensions window

Returns the size of the window window in a cons cell (width . height). This does not include the frame. The size including the frame is returned by window-frame-dimensions. (see Frame Functions)

— Function: window-position window

Returns the position of the window decorated with the frame in a cons-cell (x . y).

— Function: display-window-position #!optional window

Display window's position and size in a popup. If the argument is nil or called as a command, user chooses the window by cursor and click.

This function is defined in sawfish.wm.util.display-wininfo.

— Function: get-window-wm-protocols window

Return a list of symbols defining the X11 window manager protocols supported by client window.

— Function: window-supports-wm-protocol-p window atom

Return true if window includes atom in its WM_PROTOCOLS property.

— Function: window-pid window

Returns the window process ID, or nil if not available.

Listed here are window visibility predicates: stacking-visibility, window-obscured (see Stacking Visibility), window-visible-p (see Showing and Hiding Windows), window-shaped-p (see Shading Windows), window-iconified-p (see Iconifying Windows), window-in-workspace-p (see Workspaces and Windows), window-outside-viewport-p (see Windows and Viewports).

Various predicates:

— Function: window-mapped-p window

Return t if the client window associated with object window is mapped. (Note that this doesn't necessarily mean that it is visible.)

— Function: window-shaped-p window

Return t if window is shaped (possibly not rectangular).

— Function: window-urgent-p window

Return t if the “Urgency” hint of the window associated with window is set.

— Function: window-wants-input-p window
— Function: window-really-wants-input-p window

See See Input Focus.

Next: , Previous: Window Attributes, Up: Windows

8.2 Getting Windows

First, functions which treat all windows.

— Function: managed-windows

Returns a list containing all managed window objects, in the order that they were adopted by the window manager (first to last).

— Function: map-windows function

Call (function window) on all existing windows. Returns the value of the last function invocation. If any function returns nil, map-windows returns nil immediately.

Functions to get specific windows.

— Function: get-window-by-id xid

Return a window object with ID xid, or nil.

— Function: get-window-by-name name #!key regex icon

Return a window object with name name, or nil. Even if multiple windows are matched, one of them is returned.

If regex is non-nil, name is treated as a regex, and matched against window names.

If icon is non-nil, window's icon name (set by NEW_WM_ICON_NAME, not EWMH _NET_WM_ICON_NAME) is searched, instead of the window's name.

— Function: get-window-by-class class #!regex

Same as the above, but the match is done against the window class. Here, the class does not include the “instance”. (See window-class in See Window Attributes.)

The option regex is boolean, not a regex, like get-window-by-name.

— Function: get-window-by-role role

Same as the above, but the match is done against the window role.

The option regex is boolean, not a regex, like get-window-by-name.

— Function: filter-windows pred

Return the list of windows (mapped or unmapped) that match the predicate function pred.

Next: , Previous: Getting Windows, Up: Windows

8.3 Window Property Lists

Many window manager extensions need to be able to associate Lisp data with individual windows. For example, the module handling iconification needs to associate a boolean value with each window—whether that window is iconified or not.

To solve this problem, Sawfish gives each window a property list. These are exactly analogous to the property lists stored with each symbol (see Property Lists); they allow values to be associated with Lisp symbols, for a particular window.

Note that these properties are different to the properties that X stores with each window, since these properties are internal to the window manager (see X Properties).

For a list of the standard window properties, see Standard Properties.

— Function: window-put window property value

Set the lisp property named property (a symbol) associated with window object window to value. Note that these are Lisp properties not X properties.

— Function: window-get window property #!optional checker

Return the window property named property (a symbol) associated with the window object window, or nil if no such property exists. Note that these are Lisp properties not X properties.

If the optional third argument checker is non-nil, then checker is returned if the requested property does not exist. This is used to distinguish the assigned value of nil from property's absence. A symbol is usually a good choice for checker.

— Function: map-window-properties function window

Call (function property value) on each of the Lisp properties bound to window. Returns the value of the last function invocation. If any function returns nil, map-window-properties returns nil immediately.

— Function: window-plist window

Returns the property list of the window window which is of the form (prop value prop value ...).

Do not attempt to change properties by modifying the property list in place. Use window-put instead.

— Function: window-remprop window property

Remove property of window. Returns t for success, nil if the property did not exist.

Next: , Previous: Window Property Lists, Up: Windows

8.4 Window Types

Some window “types” are defined. They represent the window's special nature based on the role. Defined types are “transient”, “desktop”, and “dock”.

A type is usually set by applications through hints when the window appears. Many windows do not have any types.

“Transient” windows are pop-up or dialog windows associated with a main application. They tend to have less window decorations, and are intended to last a short time only.

— Function: window-transient-p window

Returns nil if window isn't marked as a transient window. Otherwise returns an integer, the xid of the parent window.

— Function: mark-window-as-transient w

Mark that the window associated with object w is a transient window.

— Function: transient-of-p child parent

Return true if window child is directly a transient for window parent, false otherwise.

— Function: indirect-transient-of-p descendant ancestor

Return true if window descendant is (directly or indirectly) a transient for window ancestor, false otherwise.

— Function: transient-parents child #!optional indirectly

Return the list of windows that window child is a transient for. If indirectly is true, then return the list of all ancestors rather than parents.

— Function: transient-children parent #!optional indirectly

Return the list of windows that are transients for window parent. If indirectly is true, then return the list of all descendants rather than children.

— Function: transient-group window #!optional by-depth

Return the list of windows which is either a transient window for window window, or a window which window is a transient for. This always includes W. The `transient window for' relation holds for windows which are direct or indirect transients of the parent window in question.

If the by-depth argument is true, then the retrurned list is in stacking order.

— Function: map-transient-group fun window

Map the single argument function fun over all windows in the same transient group as window window.

— Function: raise-window-and-transients window

Raise window window to its highest allowed position in the stacking order. Also raise any transient windows that it has.

— Function: lower-window-and-transients window

Lower window window to its lowest allowed position in the stacking order. Also lower any transient windows that it has.

— Function: raise-lower-window-and-transients window

If window window is at its highest possible position, then lower it to its lowest possible position. Otherwise raise it as far as allowed. Also changes the level of any transient windows it has.

— Customizable: focus-windows-when-mapped

Focus on application windows when they first appear. Defaults to true, must be true or false.

— Variable: decorate-transients

Decorate dialog windows similarly to application windows. Defaults to false.

“Desktop” windows are root windows or viewport windows. They accept keys as if it is a root window. (I.e., root-window-keymap is used.) They don't have a frame.

— Function: desktop-window-p arg

Returns t if arg represents a desktop window.

— Function: mark-window-as-desktop w

Mark that the window associated with object w is a desktop window.

— Variable: desktop-window-properties

List of properties set (to true) on windows when they are marked as desktops. Defaults to 

          '(fixed-position sticky sticky-viewport)
— Variable: desktop-window-depth

The stacking depth of desktop windows. Defaults to -4.

“Dock” windows are docks or panels. They don't have frame by default.

— Function: dock-window-p arg

Returns t if arg represents a dock window.

— Function: mark-window-as-dock w

Mark that the window associated with object w is a dock window.

— Variable: dock-window-properties

List of properties set (to true) on windows when they are marked as docks. Defaults to 

          '(window-list-skip cycle-skip fixed-position focus-click-through
            avoid no-history never-iconify never-maximize sticky
            sticky-viewport placed)
— Variable: dock-window-depth

The stacking depth of dock windows. Defaults to 0.

Next: , Previous: Window Types, Up: Windows

8.5 Input Focus

The input focus defines exactly which client window will receive events generated by the keyboard.

— Function: input-focus

Returns the window object of the currently focused window, or nil if no window is focused.

— Function: set-input-focus window

Sets the focus to the client window associated with window.

If window is nil, then no window will have the focus.

— Function: window-wants-input-p window

If you're unsure, use window-really-wants-input-p function described below.

Return t when the window window wants input focus in X sense, i.e. if it has asked for the input focus to be assigned to, through the input field of its WM_HINTS property.

— Function: window-really-wants-input-p window

Like window-wants-input-p, but in addition, this function also takes into account user option provided by Sawfish, i.e. if the window has never-focus property or not.

The window manager is responsible for switching the input focus from client window to client window. Sawfish implements several focus modes that provide this behavior. Each focus mode is bound to a symbol; the implementation is bound to that symbol's focus-mode property slot.

— Variable: focus-mode

Defines the current method of using the mouse to assign the input focus. This is a symbol from the list focus-modes.

— Variable: focus-modes

A list containing all names of focus modes. The built-in values are enter-exit, enter-only, enter-click and click.

Focus mode enter-exit changes focus when the pointer enters a window or leaves the focused window. Focus mode enter-only changes focus when the pointer enters a window, but not when it leaves the focused window. Focus mode click changes focus when you click on a window. Focus mode enter-click is the union of enter-only and click, and changes focus on any of their conditions.

It is possible to add additional focus modes by defining your own handler function. The handler function must obey a “focus-mode-handler” protocol.

— Function Protocol: focus-mode-handler window event-name #!optional args

A function that implements the focus-mode-handler protocol can be used to define a focus mode. A focus-mode-handler responds to events associated with windows.

Argument window is the window that received this event.

Argument event-name is one of the following symbols:

pointer-in
pointer-out
The pointer has entered or exited the window. The handler is responsible for checking whether an entered window wants input events. The desktop never receives pointer-in or pointer-out; only normal windows do.
enter-root
leave-root
The pointer has entered or exited the desktop (which is the window argument). Normal windows never receive enter-root or leave-root.
focus-in
focus-out
The window argument has gotten or lost focus. Note that the focus-in handler is not responsible for updating the window-order list.
before-mode-change
after-mode-change
Sawfish sends these synthetic events to each window before/after changing that window's focus mode. When the global focus mode changes, all windows get these events.
add-window
Sawfish sends this event to every window immediately after mapping it. Handlers can use this to initialize window-internal data structures.
warp-if-necessary
Warp the cursor to the window if doing so would make the cursor position “consistent” with the focus mode. For example, in enter-exit mode we warp the cursor if it is not already in this window. In enter-only mode, we warp the cursor if it is in another window, but not if it is over the desktop—a window would not lose focus when the cursor moved from it to the desktop.

This event is implemented via warp-cursor-to-window, so Sawfish will not warp unless warp-to-window-enabled is true.

focus-revert
The focused window has disappeared (the window argument is not used here). The focus mode may react by setting focus to some other window. If a focused transient window disappears, focus normally reverts to the window that the disappearing window was transient for. focus-revert is not invoked in that case.

The protocol allows for any number of additional arguments, but does not define any. Any handler function must be prepared to receive and ignore them.

Unsupported events may be ignored. The return value of this function is ignored.

— Function: define-focus-mode name fun

Defines a new focus mode called name (a symbol). The focus-mode handler fun implements this focus mode.

See the documentation for focus-mode-handler for more information.

— Function: set-focus-mode window mode

Set the focus mode of window window to mode. This triggers before-mode-change and after-mode-change focus-mode events on window.

— Function: warp-pointer-if-necessary window

Generate a warp-if-necessary event and sends it to the window's focus function.

Various functions call warp-pointer-if-necessary if they move the focused window out from underneath the pointer.

— Variable: focus-click-through

When in click focus mode, the focus-assigning click is only passed through to the client window if this variable is t (the default).

This option may be set on a per-window basis by setting the focus-click-through property of the window (using the window-put function).

— Variable: focus-within-click-event

When true, the current command is being called from within a click-to-focus button press event.

This is a fluid object, not an ordinary variable.

Sawfish also maintains the order in which windows were recently focused.

— Function: window-order #!optional workspace allow-iconified all-viewports

Return a list of windows, in most-recently-focused order.

If workspace is an integer, then only windows on that workspace are included, otherwise all workspaces are searched.

If allow-iconified is non-nil, iconified windows are included. If all-viewports is non-nil, then all viewports of the workspace(s) are scanned.

— Function: window-order-push window

Push window object window onto the top of the focus stack.

— Function: window-order-pop window

Remove window object window from the focus stack.

— Function: window-order-most-recent #!optional windows

Return the most-recently focused window in the current workspace. If the optional argument windows is given, it must be a list of windows. In that case, the function will return the most-recently focused window from that list.

— Function: window-order-focus-most-recent

Focus the most-recently-focused window of the current workspace.

— Variable: focus-dont-push

When true, focusing a window doesn't change it's position in the stack of most-recently focused windows.

Other focus related functions:

— Function: window-in-cycle-p window &keyword ignore-cycle-skip

Returns t if the window window should be included when cycling between windows. Desktop windows and those with the cycle-skip property should normally not be included.

When t, the ignore-cycle-skip keyword argument forces the function to include windows with the cycle-skip property.

— Function: focus-push-map window keymap
— Function: focus-pop-map window

Maintain a two-element keymap stack for window.

focus-push-map makes keymap current for window, but saves the existing keymap. We can restore this existing keymap with focus-pop-map.

These functions are intended to support click-to-focus. They enforce certain sanity rules: pushing into a two-element stack will only overwrite the top element, while popping a one-element stack has no effect.

— Function: autoload-focus-mode name func

MISSING. This does not seem to be used anywhere, and its behavior is unclear.

— Function: select-window

Waits for the user to left-click on a window, and returns that window. The mouse cursor changes shape, and all normal input events are suppressed until a window is selected. For root window, nil is returned.

— Variable: select-window-cursor-shape

The cursor shape to use when selecting a window. Defaults to crosshair.

Next: , Previous: Input Focus, Up: Windows

8.6 X Properties

The X window system associates properties with windows (these are totally separate to the properties that sawfish associates with window objects, see Window Property Lists). Most inter-client communication is performed through manipulation of these properties.

All functions defined below, that operate on X properties, accept their window parameter as either a window object (denoting the associated client window), the numeric xid of a window, or the symbol root denoting the root window.

Sawfish represents X atoms (both the names and data types of X properties) as symbols. There is an exact correspondence between the names of atoms and the name of the symbol representing them. For example, the X atom ‘STRING’ is represented by the lisp symbol STRING.

— Function: list-x-properties window

Return a list of symbols defining the X properties set on window.

— Function: delete-x-property window property

Deletes the X property named property (a symbol) associated with window.

— Function: get-x-property window property

Returns a list (type format data) representing the X property property of window. If no such property exists, return nil.

type is the atom defining the type of the property. format is an integer, either 8, 16 or 32, defining the number of bits in each of the data items. data is an array, either a string for an 8-bit format property, or a vector of integers otherwise.

If type is ATOM and format is 32, then data will be a vector of symbols, representing the atoms read.

— Function: set-x-property window property data type format

Set the X property property of window to the array data, either a string or a vector of integers.

type is a symbol representing the atom defining the type of the property; format is either 8, 16 or 32 defining the number of bits in the data values.

If type is ATOM and format is 32, then any symbols in data will be converted to their numeric X atoms.

The standard X property formats don't allow for an array of strings to be stored, so these are often encoded as the strings concatenated, separated by zero characters. These are usually called text properties. Sawfish has two functions for manipulating them:

— Function: get-x-text-property window property

Similar to get-x-property, but returns either nil or a vector of strings.

— Function: set-x-text-property window property data

Sets the X text property property of window to the array of strings data.

It's also possible to detect when the value of any property associated with a managed window changes, using the property-notify-hook. See Standard Hooks. The following convenience function takes advantage of this hook:

— Function: call-after-property-changed prop fun

Arrange for function fun to be called with arguments ‘(window property state)’ when the X11 property named prop (a symbol) changes. Prop may also be a list of property names to monitor.

Next: , Previous: X Properties, Up: Windows

8.7 Window Groups

Sawfish provides extra tools and commands for dealing with ICCCM groups. Most “normal” groups work the same way as they do in the ICCCM standard: windows have a group property that is set to the X window ID of the group leader. These are “group IDs”, and they are always positive integers. In addition, Sawfish allows group IDs to be:

negative integers
These are anonymous user-defined groups.
symbols
These are named user-defined groups. Named user-defined groups are saved as part of window properties when saving sessions.
— Function: window-group-id window

If window is part of a group, return the X window id of the leader of that group. Otherwise return nil.

— Function: window-group-ids

Return the list of all group ids.

There may be certain named groups that always exist, whether or not any window belongs to them.

— Variable: peristent-group-ids

A list of symbols naming groups that always exist.

In any case, a window is limited to belonging to one group, and always belongs to one group.

Next: , Previous: Window Groups, Up: Window Groups

8.7.1 Assigning Windows to Groups

It is possible to change the group of a window in Sawfish. Use add-window-to-group, or if necessary you can set the window's group property explicitly.

— Function: add-window-to-group window group-id

Place window in group group-id, replacing any previous group membership. If group-id is nil, then Sawfish returns the window to whatever group membership was supplied by ICCCM.

— Function: add-window-to-new-group window

Place window into a new group, which will have window as its sole member. This is an anonymous user-defined group. The new group ID is returned.

The Sawfish group assignment never overrides the ICCCM group assignment, just suppresses it. The window-actual-group-id function implements this overriding.

— Function: window-actual-group-id window

Return the (Sawfish) group ID for window. This is, in order of preference:

This means that a window is, at the very least, part of its own group.

Each of the following functions operates on the “actual group ID” as returned by the above function.

— Function: windows-by-group group-id #!optional by-depth

Return the list of windows in the group with id group-id. If by-depth is non-nil, then return the windows in order of stacking, from topmost to bottommost.

— Function: windows-in-group w #!optional by-depth

Return the list of windows in the same group as window w. If by-depth is non-nil, then return the windows in order of stacking, from topmost to bottommost.

— Function: map-window-group fun w

Map the single argument function fun over all windows in the same group as window w. Note that fun needs to operate using side-effects, rather than returning values.

— Function: map-other-window-groups fun w

Map the single argument function fun over all windows not in the same group as window w. Note that fun needs to operate using side-effects, rather than returning values.

— Function: window-group-menu #!optional w

Return a menu definition suitable for popup-menu. This menu will allow the user to assign the window w into any group of a managed window, or into a brand new group. The window's current group is checked or otherwise marked.

Previous: Assigning Windows to Groups, Up: Window Groups

8.7.2 Operations on Groups

Most of the window manipulation functions that operate on windows are also available for window groups. Each of these functions takes a window as argument; the affected group is that window's group.

— Function: iconify-group w
— Function: uniconify-group w
— Function: iconify-transient-group w
— Function: uniconify-transient-group w

These operate like their single-window counterparts. They work by temporarily rebinding iconify-group-mode and uniconify-group-mode.

— Function: make-group-sticky w
— Function: make-group-unsticky w

These operate like their single-window counterparts.

— Function: toggle-group-sticky w

If window w is sticky, all windows in its group have their stickyness removed. Otherwise all windows in its group become sticky.

— Function: send-group-to-workspace w workspace
— Function: send-group-to-next-workspace w count
— Function: send-group-to-previous-workspace w count

These operate like their single-window counterparts.

— Function: send-group-to-current-workspace w

All windows in the group of w are moved from their existing workspaces to the nearest workspace that w is in. Sticky windows are not affected. If the window had the input focus and it is visible after the move, it retains the input focus.

— Function: move-group-to-current-viewport w
— Function: move-group-viewport w
— Function: move-group-left w
— Function: move-group-right w
— Function: move-group-up w
— Function: move-group-down w

These operate like their single-window counterparts.

— Function: raise-group w
— Function: lower-group w
— Function: raise-lower-group w
— Function: raise-group-depth w
— Function: lower-group-depth w

These operate like their single-window counterparts.

— Function: set-group-frame-style w style

This operates like its single-window counterpart.

Next: , Previous: Window Groups, Up: Windows

8.8 Activating Window

When user wants to use a window, displaying, focusing, raising, etc, are necessary. Functions in this section do such jobs.

— Function: display-window window

Roughly speaking, do everything necessary to make window ready for user.

The operations are done in the following order. If the window is iconified, it gets un-iconified. The workspace and the viewport in which the window lies is selected. Unshade if necessary. (See unshade-selected-windows variable below.) Then call the activate-window function described below.

It is defined in sawfish.wm.util.display-window module.

— Function: activate-window window

Raise, focus, warp pointer if necessary, and mark the window as the top of window order. Don't focus if the window doesn't allow that operation.

— Customizable: unshade-selected-windows

When non-nil, unshade windows when selected.

Next: , Previous: Activating Window, Up: Windows

8.9 Window Stacking

The stacking order of the display defines the order in which windows are shown, from topmost to bottommost. It's Sawfish that maintains this list. Raising or lowering windows changes their positions in this list.

Next: , Previous: Window Stacking, Up: Window Stacking

8.9.1 Stacking Order

— Function: stacking-order

Return a list of window objects defining the current stacking order of all client windows, from top-most to bottom-most.

— Function: mapped-stacking-order

Similar to stacking-order, but only returns windows that are mapped.

— Function: restack-windows list

Restack all client windows specified in the list of window objects list in the order they occur in the list (from top to bottom). The stacking order of any unspecified windows isn't affected.

Sawfish allows the stacking order to be managed as a sequence of layers, with windows being assigned a particular depth within the order. For any given window with depth d, it will be above all windows with depth less than d, and below all windows with depth greater than d. It may be above or below any other windows with depth d.

The depth property of each window is used to store this depth. A depth of zero is “normal”, with negative depths stacked below, and positive depths stacked above this normal level.

— Function: stacking-order-by-depth depth

Similar to stacking-order, but only returns windows with depth depth.

— Function: window-depth window

Returns the depth of window.

— Function: set-window-depth window depth

Sets the stacking depth of window to depth, then restacks the windows to reflect this change.

Functions to change stacking order.

— Function: window-on-top-p window

Returns t if window is at the top of its stacking depth.

— Function: stack-window-below below above

Change stacking order of window below so that it is immediately below window above. This function alone does not raise / lower windows.

— Function: stack-window-above above below

Change stacking order of window above so that it is immediately above window below. This function alone does not raise / lower windows.

— Macro: save-stacking-order &rest forms

Evaluate forms in an implicit progn, then restore the original window stacking order, returning the value of the progn.

— Function: restack-window w

Assuming that the current stacking order is in a consistent state except, possibly, for the position of window w, restore the consistent state including window w. This is achieved by raising or lowering window W as appropriate.

Next: , Previous: Stacking Order, Up: Window Stacking

8.9.2 Stacking Visibility

There're functions which tell how the window is covered by others.

— Function: stacking-visibility window

Returns unobscured if window is unobscured, fully-obscured if one or more windows completely obscure window, or partially-obscured if one or more window partially obscure window.

Deciding between fully and partially obscured can be expensive. If window-obscured satisfies your needs, use that in preference to stacking-visibility.

— Function: window-obscured window

Returns nil if window is unobscured, t if window is completely obscured by exactly one other window, or a list of windows that partially obscure window.

If a list of partially obscuring windows is returned, taken together they may or may not fully obscure window.

— Obsolete Function: window-visibility window

Returns a symbol defining the current visibility of window. Possible returned symbols are fully-obscured, partially-obscured or unobscured.

window-visibility is deprecated. It is unreliable when using the Composite extention, as every window is reported unobscured. Use window-obscured and stacking-visibility instead.

Previous: Stacking Visibility, Up: Window Stacking

8.9.3 Raising and Lowering Windows

Over time, Sawfish has accumulated several subtle variations of functions for raising and lowering windows. One set of functions operates on single windows. Notice how the function name and command name for each pair differs slightly.

— Function: lower-window window
— Command: lower-single-window window

Lower window to the bottom of its stacking depth.

— Function: raise-window window
— Command: raise-single-window window

Raise window to the top of its stacking depth.

— Function: raise-lower-window window
— Command: raise-lower-single-window window

If window is the highest in its stacking level, lower it to the bottom of this level, otherwise raise it to the top of its level.

— Function: x-raise-window win ref
— Function: x-lower-window win ref

Raise / lower window win so that it is above / below window ref. If ref is undefined, win is put at the top / bottom of the stacking order.

Another set of functions supports operating on multiple windows simultaneously. You have to import sawfish.wm.util.stacking to use them. Again, the function name and command name for each pair is different.

— Function: lower-window* window
— Command: lower-window window

Lower window and possibly associated windows to the bottom of their stacking depths.

— Function: raise-window* window
— Command: raise-window window

Raise window and possibly associated windows to the top of their stacking depth.

— Function: raise-lower-window* window
— Command: raise-lower-window window

If window is the highest in its stacking level, lower it and possibly associated windows to the bottom of their level, otherwise raise them to the top of their level.

— Customizable: user-raise-type

This user option indicates which windows the lower-window*, raise-window* and raise-lower-window* functions affect. This variable can be

none
Only the specific argument window is affected.
transients
The specific argument window and all of its transients are affected. This is the default.
group
The specific argument window and all windows in its group are affected.

Sawfish has more general operations that raising a window to the top or lowering it to the bottom. It can place a window relative to one or more other managed windows.

— Function: raise-windows w order
— Function: lower-windows w order
— Function: raise-lower-windows w order

Raise (or lower) all windows in order, such that items earlier in the list are higher (or lower) than later items. The window w is special, always being the highest or lowest window, even if appears in the middle of order.

For raise-lower-windows, if w would be raised or lowered, then all the other windows are also raised or lowered.

There are also functions (and associated commands) to change a window's depth.

— Function: lower-window-depth window
— Command: lower-window-depth window

Decrement the stacking depth of window.

— Function: raise-window-depth window
— Command: raise-window-depth window

Increment the stacking depth of window.

Sawfish provides special support for “click-to-focus” mode, where you may or may not want to raise the window or pass the click to the underlying application.

— Function: raise-and-pass-through-click w

Raise the window that received the current event with maybe-raise-window. Then replay any pointer events that invoked the command.

— Function: raise-and-pass-through-click-if-focused w

Raise the window that received the current event (if it's focused) with maybe-raise-window. Then replay any pointer events that invoked the command.

— Function: raise-or-pass-through-click w

If the window that received the current event is not on top, raise it with maybe-raise-window. Otherwise replay any pointer events that invoked the command, sending them to the window.

When the above commands are called interactively, Sawfish will try to invoke them on the window that received the current event. Failing that, Sawfish will invoke them on the currently focused window.

Next: , Previous: Window Stacking, Up: Windows

8.10 Moving and Resizing Windows

As noted above (see Window Attributes), the window-dimensions and window-position functions return the current configuration of a window.

— Function: move-window-to window x y

Move the top-left corner of the window frame of window to (x, y).

— Function: resize-window-to window width height

Set the dimensions of the client window associated with object window to (width, height).

— Function: move-resize-window-to window x y width height

Move the top-left corner of the window frame of window to (x, y), and set the dimensions of the frame to (width, height).

— Function: resize-window-with-hints window cols rows #!optional hints
— Function: resize-window-with-hints* window width height #!optional hints

Resize the window window respecting the hints (see below). For the first function, the dimensions are cols columns and rows rows. For the second function, the dimensions are width pixels and height pixels.

The hints parameters is either the size hints alist to use, or nil in which case the window-size-hints function is used to retrieve the window's hints.

Hints can specify minimum or maximum value of each dimension, and also increase step, as far as these two functions are concerned.

— Function: window-size-hints window

Return an alist defining the size-hints structure specified by the client window associated with window. Possible keys in the alist are min-height, max-height, min-width, max-width, height-inc, width-inc, min-aspect, max-aspect, base-height, base-width, user-position, program-position, user-size, program-size, window-gravity, border-size.

Usually, however, it is left to the user to configure windows. The following functions may be called interactively: their sole argument is then either the window that received the current event or the currently focused window.

Sawfish honors the min-aspect and max-aspect window hints when interactively resizing a window.

— Function: move-window-interactively window
— Command: move-window-interactively window

Move window interactively using the mouse. Releasing any mouse button places the window at its current position.

— Function: resize-window-interactively window
— Command: resize-window-interactively window

Resize window interactively using the mouse. Releasing any mouse button places the window at its current position.

Note that this function selects the edge or edges of the window to move from the current position of the mouse when the resizing begins. The window is divided into a three-by-three grid; the rectangle containing the mouse pointer gives the direction to resize in. If the pointer is in the central rectangle the bottom and right edges are moved.

— Command: resize-window-to-preset-size
— Command: resize-window-to-preset-height
— Command: resize-window-to-preset-width

For these commands, first you specify a window dimension(s) in the configurator. The focused window will be resized to that preset size on invocation.

— Command: resize-window-prompt window

You're prompted to enter the new window size, and the window will be resized.

— Function: move-selected-window
— Command: move-selected-window

Wait for the user to select a window using the mouse, then interactively move that window.

— Function: resize-selected-window
— Command: resize-selected-window

Wait for the user to select a window with the mouse, then interactively resize that window.

— Command: double-window-size window
— Command: halve-window-size window

Double / halve the size of window in both direction, i.e. the area will be 4 or 1/4 times.

Sawfish supports increasing the windows size until it touches another window. This is called “grow”. “Shrink” achieves the opposite, i.e. it decreases the windows size, until it does no longer overlap any other window. More precisely, the grow can be done repeatedly, each time until the edge meets another edge, and shrink is done so that it overlaps with one less window.

— Function: grow-window-up window #!optional arg
— Function: grow-window-down window #!optional arg
— Function: grow-window-left window #!optional arg
— Function: grow-window-right window #!optional arg

Grows window upwards / downwards / left / right until it touches another window. If that edge is beyond the screen edge, it is brought back in. With a universal prefix arg, maximize in that direction instead. With a numeric prefix arg, grow by that many increments specified by window or pixels instead.

There are commands, too, with the same name.

— Function: shrink-window-up window
— Function: shrink-window-down window
— Function: shrink-window-left window
— Function: shrink-window-right window

Shrinks window by moving one edge upwards / downwards / left / right until it intersects with one window less than before. (So, in shrink-window-up for example, the lower edge is moved.)

Window won't be made smaller than the minimum size, or shrink-window-minimum-size. More precisely, size truncation may make the window smaller than these values.

There are commands, too, with the same name.

Moving counterparts, instead of resizing of “grow” and “shrink”, are “pack” and “yank”. So, “pack” moves until the window touches another, and “yank” moves until the overlap reduces.

— Function: pack-window-up window #!optional arg
— Function: pack-window-down #!optional arg
— Function: pack-window-left window #!optional arg
— Function: pack-window-right window #!optional arg

Moves window upwards / downwards / left /right until it touches another window. If that edge is beyond the screen edge, it is moved back in. With a universal prefix arg, move in that direction maximally instead. With a numeric prefix arg, move by that many pixels instead.

There are commands, too, with the same name.

— Function: yank-window-up window
— Function: yank-window-down window
— Function: yank-window-left window
— Function: yank-window-right window

Yanks window upwards / downwards / left / right until it overlaps with one less window than before.

There are commands, too, with the same name.

Grow, pack, shrink and yank behavior can be customized through the following variables:

— Variable: grow-is-maximize

Whether growing is considered to be maximization. The default value is t.

— Variable: pack-warp-pointer

Whether and how to move the pointer, either always maybe or never. The default value is maybe

maybe means that the pointer is moved along with the window, if the pointer was within the window area before packing. always warps the pointer to the center of the window if it isn't already in the window, then does like maybe. never means not to warp the pointer.

— Variable: grow-pack-bump-obscured

Whether to bump into fully obscured windows. The default value is nil.

— Variable: grow-pack-bump-other-depth

Whether to bump into windows on a different depth, either always maybe or never. The default value is always.

maybe means only avoided windows (see Avoided Windows).

— Variable: grow-pack-bump-ignored

Whether to bump into ignored windows. The default value is t.

— Variable: shrink-window-minimum-size

The minimum height or width to which a window may be shrunk. The default value is 10.

— Variable: yank-window-minimum-visible

The minimum amount of window left visible, if yanked over the screen edge. The default value is 10.

— Function: move-window-center window
— Command: move-window-center window

Place window in the middle of the screen (frame-size is respected while calculating position)

The interactive move and resize behavior can be customized through the following variables:

— Variable: move-outline-mode

A symbol defining the visual method of interactively moving windows. Current options include box for a wire-frame grid, and opaque for full redisplay.

— Variable: resize-outline-mode

A symbol defining the visual method of interactively resizing windows. Current options include box for a wire-frame grid, and opaque for full redisplay.

— Variable: move-show-position

When non-nil, the current window position is shown in the center of the screen.

— Variable: resize-show-position

When non-nil, the window size is shown in the center of the screen.

When you move a window and it comes close to another, sawfish adjusts its position so that its edge fits to the other, or “snaps”. (It may be dubbed as “interactive tiling”.) Snapping also takes place agaisnt screen boundary.

— Variable: move-snap-epsilon

The distance in pixels before snapping together two edges. The bigger the value, the more adhesive windows get.

Windows have a “gravity” property, which affect how they are placed in particular positions.

— Function: window-gravity window #!optional hints

Returns the gravity of window. The order of precedence is Sawfish gravity window property, explicit hints argument, X window size hints. The default gravity when nothing else is specified is north-west (specified by ICCCM).

Next: , Previous: Moving and Resizing Windows, Up: Windows

8.11 Showing and Hiding Windows

Sawfish provides two low-level functions for (un)withdrawing client windows from the display. These are used to implement both workspaces (see Workspaces) and iconification (see Iconifying Windows).

— Function: hide-window window

Prevent object window from being displayed.

This function is low-level and mainly for internal use. You should probably use iconify-window. (see Iconifying Windows)

— Function: show-window window

Ensure that window is visible, (provided that it has been mapped, and is within the screen boundary).

This function is low-level and mainly for internal use. For interactive use, you should probably use display-window. (see Activating Window)

— Function: window-visible-p window

Returns t if object window has not been hidden by the hide-window function.

Next: , Previous: Showing and Hiding Windows, Up: Windows

8.12 Destroying Windows

There are several methods through which X11 client windows may be removed from the display. These differ in the level “politeness” they show the window and its owning application.

— Function: delete-window window
— Command: delete-window window

Delete window, i.e. send a WM_DELETE_WINDOW client-message if possible, or just kill the associated X11 client if not. window may be a window object or a numeric window id.

— Function: delete-window-safely window
— Command: delete-window-safely window

If the application owning window supports it, send a WM_DELETE_WINDOW message to window. Otherwise just emit a beep.

— Function: destroy-window window
— Command: destroy-window window

Destroy window without giving the owning application any warning. window may be a window object or a numeric window id.

— Function: x-kill-client window
— Command: kill-client window

Force a close down of the X11 client that created the window specified by window (a window object, or numeric id).

When a managed window is destroyed, the destroy-notify-hook will subsequently be invoked (see Standard Hooks).

Next: , Previous: Destroying Windows, Up: Windows

8.13 Shading Windows

Many window managers allow a window to be shaded; when in this state only the title bar of the window is visible.

— Function: window-shaded-p window

Returns true when window is shaded, false otherwise.

— Function: shade-window window
— Command: shade-window window

Arrange for only the title bar of window to be visible.

— Function: unshade-window window
— Command: unshade-window window

If the window is shaded, restore it to it's original state.

— Function: toggle-window-shade window
— Command: toggle-window-shaded window

Toggle the shaded state of the window.

— Variable: raise-windows-when-unshaded nil

When true, raise windows when they are unshaded. Defaults to false.

The shaded property of a window is set to t when the window is shaded. If a window is added with this property already set, then the window will appear in its shaded state.

Next: , Previous: Shading Windows, Up: Windows

8.14 Maximizing Windows

The dimensions of a window may be temporarily maximized, stretching as far as possible within the screen in one or two dimensions.

If you have multiple monitors, maximization is done within a head, unless stated explicitly that it's xinerama.

— Function: window-maximizable-p window #!optional direcion hints

Return t when window is maximizable. The window property never-maximize prevents maximization.

If defined, direction is a symbol, either vertical or horizontal, and maximization will only occur for that direction.

The optional argument hints overrides the window's hints.

— Function: window-maximized-p window

Return t when window is maximized in any direction.

— Function: window-maximized-vertically-p window

Return t when window is vertically maximized, regardless if it's horizontally maximized or not.

— Function: window-maximized-horizontally-p window

Return t when window is horizontally maximized, regardless if it's vertically maximized or not.

Next: , Previous: Maximizing Windows, Up: Maximizing Windows

8.14.1 Basic Maximizations

Ordinary maximization occurs on the current screen, and possibly rounding down to fit character sizes.

— Function: maximize-window window #!optional direction only-1d
— Command: maximize-window window

Maximize both dimensions of window on the screen.

If defined, direction is a symbol, either vertical or horizontal, and maximization will only occur for that direction.

The optional argument only-1d is for internal use. Don't use it.

— Function: maximize-window-vertically window
— Command: maximize-window-vertically window
— Function: maximize-window-horizontally window
— Command: maximize-window-horizontally Windows

Maximize the vertical or horizontal dimension of window in the screen.

— Function: maximize-window-toggle window #!optional direction
— Command: maximize-window-toggle window

Toggle the state of window between maximized and unmaximized in the screen.

If defined, direction is a symbol, either vertical or horizontal, and maximization will only occur for that direction.

— Function: maximize-window-vertically-toggle window
— Command: maximize-window-vertically-toggle window

Toggle the state of window between vertically maximized and unmaximized in the screen.

— Function: maximize-window-horizontally-toggle window
— Command: maximize-window-horizontally-toggle window

Toggle the state of window between horizontally maximized and unmaximized in the screen.

— Customizable: move-lock-when-maximized

When true (the default), Sawfish will not allow the user to manually resize maximized windows. It will also prevent the user from moving the windows along their maximized axes.

For example, a vertically maximized window is vertically locked, so a user can slide it left and right, but cannot move it up or down.

If you set this to nil and resize a maximized window, then you can't unmaximize it any more.

— Function: window-locked-vertically-p window

Return t when window is vertically locked.

— Function: frame-part-movable-p window part

Return t if the part of window can be moved.

part is one of the symbols: top-border, bottom-border, left-border, right-border, top-left-corner, top-right-corner, bottom-left-corner, bottom-right-corner, or title

— Variable: maximize-raises

When true (the default), maximizing a window raises it as well.

— Variable: maximize-always-expands

In general, if a window's dimension is larger than the screen size, maximizing that dimension can actually shrink it to fit into the screen. When this variable is true (default false), maximizing a window's dimension will never shrink it.

Next: , Previous: Basic Maximizations, Up: Maximizing Windows

8.14.2 Maximizing Without Overlap

It is possible to maximize a window where it gets only large enough not to overlap with other windows.

— Variable: maximize-avoid-avoided

When true (the default), maximized window does not cover avoided windows. (see Avoided Windows)

The “fill” category of maximizing commands provides a convenient way to maximize without overlap to any other windows, except “ignored” ones. (see Ignored Windows)

In addition, they don't shrink the window even if it is already bigger than the screen size.

— Function: maximize-fill-window window #!optional direction
— Command: maximize-fill-window window

Maximize both dimensions of window without overlapping other windows.

If defined, direction is a symbol, either vertical or horizontal, and maximization will only occur for that direction.

— Function: maximize-fill-window-vertically window
— Command: maximize-fill-window-vertically window

Maximize the vertical dimension of window in the screen without overlapping other windows.

— Function: maximize-fill-window-horizontally window
— Command: maximize-fill-window-horizontally window

Maximize the horizontal dimension of window in the screen without overlapping other windows.

— Function: maximize-fill-window-toggle window
— Command: maximize-fill-window-toggle window

Toggle the state of window between maximized and unmaximized in the screen without overlapping other windows.

If defined, direction is a symbol, either vertical or horizontal, and maximization will only occur for that direction.

— Function: maximize-fill-window-vertically-toggle window
— Command: maximize-fill-window-vertically-toggle window

Toggle the state of window between vertically maximized and unmaximized in the screen without overlapping other windows.

— Function: maximize-fill-window-horizontally-toggle window
— Command: maximize-fill-window-horizontally-toggle window

Toggle the state of window between horizontally maximized and unmaximized in the screen without overlapping other windows.

— Variable: maximize-ignore-when-filling

For “filling” maximization, “ignored” windows are ignored when true (the default). (see Ignored Windows)

Next: , Previous: Maximizing Without Overlap, Up: Maximizing Windows

8.14.3 Maximizing Without Borders

The “fullscreen” and “fullxinerama” categories of maximizing commands maximize the window to some extent and remove all the window's decorations. If necessary, Sawfish will pad the bottom and right window edges to make the window fill the complete extent. (This is usually required for terminal windows, for example.)

The “fullscreen” category maximizes the window to the current screen.

— Function: maximize-window-fullscreen window state
— Command: maximize-window-fullscreen window

Maximize both dimensions of window on the screen, removing window decorations and making the window edges flush with the screen sides.

If state nil, it unmaximizes. Else, it maximizes. If called as a command, it always maximizes.

— Function: maximize-window-fullscreen-toggle window
— Command: maximize-window-fullscreen-toggle window

Toggle the state of window between maximized and unmaximized in the screen, removing window decorations and making the window edges flush with the screen sides.

The “fullxinerama” category maximizes the window to the entire Xinerama display.

— Function: maximize-window-fullxinerama window state
— Command: maximize-window-fullxinerama window

Maximize both dimensions of window across all Xinerama screens, removing window decorations and making the window edges flush with the screen sides.

If state nil, it unmaximizes. Else, it maximizes. If called as a command, it always maximizes.

— Function: maximize-window-fullxinerama-toggle window
— Command: maximize-window-fullxinerama-toggle window

Toggle the state of window between maximized and unmaximized across all Xinerama screeens, removing window decorations and making the window edges flush with the screen sides.

Previous: Maximizing Without Borders, Up: Maximizing Windows

8.14.4 Unmaximizing

One command restores windows from all the different types of maximization.

— Function: unmaximize-window window #!optional direction
— Command: unmaximize-window window

Restore the position and dimensions of window to their original, unmaximized, states.

If the window is maximized for example vertically but not horizontally, then only vertical position and dimension are restored.

If defined, direction is a symbol, either vertical or horizontal, and unmaximization will only occur for that direction.

— Function: window-unmaximized-position window

Returns a cons-cell (x . y) indicating the position that the window would unmaximize to.

If the window is maximized for example vertically but not horizontally, then y is the y coordinate before maximization, but x is the window's current x coordinate.

— Function: window-unmaximized-dimensions window

Returns a cons-cell (w . h) indicating the dimensions that window would unmaximize to.

If the window is maximized for example vertically but not horizontally, then y is the height before maximization, but x is the window's current width.

— Function: maximize-discard window #!optional direction

Don't treat window as maximized any more, keeping the size and the position. You'll be able to move and resize, but won't be able to unmaximize.

If the optional argument `direction' is `vertical' or `horizontal', then only that direction is unmaximized.

When window is not maximized, nothing happens.

Next: , Previous: Maximizing Windows, Up: Windows

8.15 Cycling Between Windows

Sawfish provides two categories of commands for cycling between windows. The first category cycles between windows in an order that is essentially fixed. The second category cycles between windows in a dynamic order.

Next: , Previous: Cycling Between Windows, Up: Cycling Between Windows

8.15.1 Fixed Window Cycles

These commands organize the set of mangaged windows into loops. A loop may consist of all windows in a workspace, or it may consist of all windows anywhere. The positions of windows in this loop do not change, except when a new window is managed or unmanaged.

— Function: next-workspace-window
— Function: previous-workspace-window

Switch focus to the “next” or “previous” window in the current workspace.

— Function: next-window
— Function: previous-window

Switch focus to the “next” or “previous” window in this workspace. If this function reaches the “end” of the windows in this workspace, it switches to the next workspace and displays the first window there.

Previous: Fixed Window Cycles, Up: Cycling Between Windows

8.15.2 Dynamic Window Cycles

These commands implement something much close to Microsoft Windows' <Alt-TAB> mechanism, working with a stack of recently used windows.

— Function: cycle-windows
— Function: cycle-windows-backwards

Cycle through all cycleable windows.

— Function: cycle-group
— Function: cycle-group-backwards

Cycle through all windows inside the same group. This is somewhat comparable to the <Control-TAB> behavior of Windows OS.

— Function: cycle-among-groups
— Function: cycle-among-groups-backwards

Cycle through windows at the top of each group.

— Function: cycle-prefix
— Function: cycle-prefix-backwards

Cycle through all windows whose titles match that of the initial window (up to, but not including, the first colon).

— Function: cycle-class
— Function: cycle-class-backwards

Cycle through all windows whose classes match that of the initial window.

— Function: cycle-dock
— Function: cycle-dock-backwards

Cycle through all windows in the dock, even those with the cycle-skip property.

Each of these cycling commands may include windows that are not visible on-screen.

— Variable: cycle-include-iconified

If true, Sawfish includes iconified windows when cycling. Defaults to true.

— Variable: cycle-all-workspaces

If true, Sawfish includes windows on all workspaces when cycling. Defaults to false.

— Variable: cycle-all-viewports

If true, Sawfish includes windows on all viewports when cycling. Defaults to false.

It is possible to configure the cycling to get more feedback during the process.

— Variable: cycle-show-window-names

If true, Sawfish displays window names and icons while cycling through windows. Defaults to true.

— Variable: cycle-raise-windows t

If true, Sawfish raises windows while they're temporarily selected during cycling, and invokes warp-pointer-if-necessary. Defaults to true.

It is also possible for you to define your own stacking cycle commands, or even to alter the window stack to suit your tastes.

— Function: define-cycle-command name body &rest rest

Create a command that will not cause the current cycle operation to abort before execution.

All arguments are passed to define-command.

— Function: define-cycle-command-pair forward-name reverse-name selector &rest rest

Create a pair of commands for cycling through windows. The command named forward-name cycles forwards, while the command named reverse-name cycles backwards.

Selector is called when initializing the cycle environment, it should return the list of windows to cycle through, or the symbol `t' to denote all cyclable windows.

Any extra arguments are passed to each call to define-command.

— Function: window-order #!optional workspace allow-iconified all-viewports

Return managed windows in most-recently used order.

If workspace is non-nil, then only managed windows in that workspace will be returned.

If allow-iconified is non-nil, then iconified windows will be returned instead of ignored.

If all-viewports is non-nil, then windows in all viewports will be returned, instead of just the current viewport.

— Function: window-order-push w

Push window w onto the top of the cycle stack.

— Function: window-order-pop w

Remove window w from the cycle stack.

— Function: window-order-most-recent &key windows

Return the most-recently focused window in the current workspace. If the windows argument is given it should be a list of windows, in this case the function will restrict its search to the elements of this list.

— Function: window-order-focus-most-recent

Switch input focus to the most-recently focused window in the current workspace.

Next: , Previous: Cycling Between Windows, Up: Windows

8.16 Window Rules by Matching

Sawfish can trigger actions particular to each window. More precisely, if the window's properties match to the user set rule, then it is executed when the window appears. Check is done in before-add-window-hook. (see Standard Hooks)

These rules can easily be set by configurater GUI, but there're functions to manipulate them. They're defined in sawfish.wm.ext.match-window.

— Function: add-window-matcher rules actions

Let us see an example first: 

          (add-window-matcher '((WM_NAME . "^root$")
                                (WM_CLASS . "^XTerm/xterm$"))
                              '((ignore-program-position . t)
                                (maximize . vertical)))

rules is an alist, and each value is matched using regex. Allowed keys are any of WM_NAME, WM_CLASS, WM_ICON_NAME, WM_WINDOW_ROLE, WM_CLIENT_MACHINE, WM_COMMAND, and WM_LOCALE_NAME. Values to the keys are strings. Windows are selected if all of these rules match.

actions is an alist. For possible keys and values, see lisp/sawfish/wm/ext/match-window.jl.

Check for invalid arguments are not done.

— Function: remove-window-matcher rules props

Opposite of add-window-matcher, but unlike it, props are list of properties. Example: 

          (remove-window-matcher '((WM_NAME . "^root$"))
                                 '(place-mode ignore-program-position))

The best place to use add-window-matcher is in ~/.sawfish/rc. It's because rules modified by these commands are not necessarily saved, depending on how you run the configurator.

The rules are stored in variable match-window-profile. Use the above functions to modify its value. It is not recommended to directly manipulate it.

Next: , Previous: Window Rules by Matching, Up: Windows

8.17 Animating Windows

Sawfish provides certain window animation capabilities. They have been described as “lame”, so they are off by default.

— Variable: default-window-animator

The animation mode when an window is iconified. The default is none.

You can set the animation mode for each window from the configurator “Window Rules”, or via window property. (see Standard Properties)

Here are listed functions to define and invoke animator.

— Function: define-window-animator name fun

Define a window animator called name (a symbol) that is managed by function fun. fun is called as ‘(fun window op [action])’ when it should change the state of an animation sequence. Op may be one of the symbols start, stop.

— Function: autoload-window-animator name struct

Construct an autoloader for window animator name from structure struct.

— Function: run-window-animator window action

Invoke an animation for action action on window. Action may be one of the symbols start, stop.

— Function: record-window-animator window animator

Note that window currently has an animation running, being controlled by animator function animator.

Next: , Previous: Animating Windows, Up: Windows

8.18 Iconifying Windows

X defines an iconic state for windows, often windows in this state are displayed as small icons. Sawfish does not display these icons. Use softwares called “trayers” and / or “pagers” for such things.

— Function: iconify-window window
— Command: iconify-window window

Iconify the window associated with object window.

— Function: uniconify-window window
— Command: uniconify-window window

Return the window associated with window from its iconified state.

— Function: toggle-window-iconified window
— Command: toggle-window-iconified window

Minimize the window associated with window, or restore it if it is already minimized.

— Function: iconify-workspace-windows
— Command: iconify-workspace-windows

Minimize all windows in the current workspace.

A window's iconic state may be tested through examination of its iconified property—when t the window is iconified. But it is preferable to use explicit testing functions instead:

— Function: window-iconified-p window

Returns true if the window associated with window is iconified, false otherwise.

— Function: window-iconifiable-p window

Returns true if the window associated with window can be iconified, false otherwise. Some reasons a window might not be iconifiable are: it has a never-iconify property; it is already iconified; it is not a desktop window; or it is marked ignored and iconify-ignored is not true.

— Variable: iconify-ignored nil

Unmanaged (ignored) windows may be iconified. Defaults to nil.

Sawfish allows you to control certain behaviors when restoring minimized windows.

— Variable: focus-windows-on-uniconify

Windows are focused after being unminimized. Defaults to false.

— Variable: raise-windows-on-uniconify

Windows are raised after being unminimized. Defaults to true.

— Variable: uniconify-to-current-workspace

Move windows to the current workspace when they are unminimized. Defaults to true.

When iconifying, it is possible to force other windows to iconify.

— Customizable: iconify-group-mode
— Customizable: uniconify-group-mode

Policy for performing chains of minimizations or restorations. When a particular window is minimized or restored, it can cause other windows to be minimized or restored at the same time. Their allowed values are set to the following list. By default, both variables are bound to the symbol transients. but they are not required to have the same value.

none
No additional windows are minimized or restored.
transients
All transient windows associated with the target window are minimized or restored.
group
All windows in the target window's group are minimized or restored.

Finally, it's possible to get the icon that would normally be displayed for an iconified window.

— Function: window-icon-image window

Return an image object representing the icon currently associated with window, or nil if there is no such image.

— Function: window-icon-name window

Return the icon name associated with window.

When a window has a property iconify-on-leave set to non-nil, it gets iconified when the mouse pointer leaves it. It can be set from the configurator. 

     ;; Example:
     ;; ( add-window-matcher '( ( WM_CLASS . "^Konsole/konsole$" ) )
     ;;   '( ( iconify-on-leave . t ) ) )

Next: , Previous: Iconifying Windows, Up: Windows

8.19 Window Stickiness

Windows normally exist in a single workspace and a single viewport into that workspace. When changing workspace or viewport, the current windows disappear. This is sometimes not the correct policy; there are certain windows that should “follow” the user from window to window. These are typically windows that are not bound to a particular activity. The most common example is a dashboard window for calling other applications. Another example might be a diagnostic program such as a load monitory.

Each window has “stickiness” flags that govern this behavior. One flag controls stickiness across workspaces: sticky windows will appear in every workspace automatically. The other flag similarly governs stickiness across viewports. A window is “sticky” if either of these flags are set.

Sticky windows are often ignored, so they lack window decorations, and avoided so other windows do not cover them up.

— Function: window-sticky-p/workspace window
— Function: window-sticky-p/viewport window
— Function: window-sticky-p window

Returns true if window is sticky across a particular environment (workspaces, viewports, or either), false otherwise.

— Function: make-window-sticky/workspace window
— Function: make-window-sticky/viewport window
— Function: make-window-sticky window

Make the window sticky across some environment (workspaces, viewports, or both).

— Function: make-window-unsticky/workspace window
— Function: make-window-unsticky/viewport window
— Function: make-window-unsticky window

Make the window unsticky across some environment (workspaces, viewports or both).

— Function: toggle-window-sticky window

If window-sticky-p would report true for window, make window unsticky for all environments. Otherwise make it sticky for all environments.

Next: , Previous: Window Stickiness, Up: Windows

8.20 Ignored Windows

Sawfish has a general concept of “ignored” windows; the user does not interact normally with those windows. The concept is actually defined by five different window properties:

ignored
The window does not receive frames.
never-focus
The window never receives the input focus.
cycle-skip
The window is ignored while window cycling.
window-list-skip
The window will not be included in the window list.
task-list-skip
The window will not be included in the task list.

A monitor application such as “xload” might have all five of these flags set.

Rather than directly manipulating the window properties, it is better to use the following access functions:

— Function: window-ignored-p window

Returns true if the window has the ignored property, false otherwise.

— Function: make-window-ignored window
— Command: make-window-ignored window

Ignore the window window.

— Function: make-window-not-ignored window
— Command: make-window-not-ignored window

Unignore the window window.

— Function: toggle-window-ignored window
— Command: toggle-window-ignored window

If window-ignored-p would return true for window, make it unignored. Otherwise make it ignored.

The remaining flags only have toggle functions implemented right now:

— Function: toggle-window-never-focus window
— Function: toggle-window-cycle-skip window
— Function: toggle-window-list-skip window
— Function: toggle-task-list-skip window

Toggle the appropriate flag on window. They have the same name commands.

All five of the flags are available through the window menu's “Toggle” entry.

Previous: Ignored Windows, Up: Windows

8.21 Avoided Windows

“Avoided” windows are kept unobscured by other windows wherever possible. It is involved in window placement (see Window Placement) and maximization (see Maximizing Windows). Most placement modes will attempt to place a new window avoiding overlap with them. Windows can be maximized avoiding overlap to avoided windows.

In this context, windows are categorized into three: windows with avoid property, those with ignored property (see Ignored Windows), and the others.

It is possible to avoid overlap only with avoided windows, and also is possible not to avoid overlap only with ignored windows.

Remember that the window with avoid property is avoided by other windows. Thus property name avoid should have been named “avoided”. On the other hand, related functions and variables are named correctly, and no special care is necessary.

— Variable: dont-avoid-ignored

When non-nil (the default), ignored windows aren't avoided.

— Variable: avoid-by-default

When non-nil, any windows are avoided. Defaults to nil.

— Function: window-avoided-p window

Returns t if window is avoided by other windows. It is determined in the following order:

  1. A window with avoid property is always avoided.
  2. A window with ignored property is always not avoided unless dont-avoid-ignored is non-nil.
  3. Otherwise, avoid-by-default determines if it should be avoided.

— Function: avoided-windows #!optional window

Returns a list of all windows that are avoided. If window is defined, then it is excluded from the returned list.

Next: , Previous: Windows, Up: Top

9 Customization

Sawfish provides two levels of configuration:

  1. customization: setting variables to change the behavior of existing features of the window manager, and,
  2. extensibility: the ability to add entirely new features to the window manager through the creation of new Lisp modules.

Obviously the first of these requires a lot less specialized knowledge than the second. But even then, the user has to edit startup files containing the Lisp forms setting the variables. To remove this need for hand-editing, Sawfish has a specialized system allowing all customizations to be made through a GUI, and then automatically reloaded each time that the window manager is started.

— Function: customize #!optional group
— Command: customize

Invoke the user-customization GUI. group defines the class of customization variables to configure, or all classes if group is undefined.

There also exists commands like customize:appearance, i.e. for each top-level customization group, the command to customize only it and its subgroups.

The sawfish-config program can be used to invoke the GUI manually.

In order to provide these customization options however, an extra requirement is placed on the Lisp programmer. Instead of just using the defvar special form to declare variables, the defcustom macro must be used. This augments the variable with extra information for the GUI, including such things as its required data type.

Next: , Previous: Customization, Up: Customization

9.1 Defgroup and Defcustom

Customization options are organized into groups. Each group has a name and contains a set of related options. Groups can be assigned to parent groups using the :group parameter during construction.

— Macro: defgroup group real-name &rest keys

Declares a new customization group whose name is defined by the symbol group. The string real-name is the title of the group as seen by the user.

keys is a list, defining the properties of the group. The members of the list are grouped into pairs of elements, the first element names the property, the second defines its value.

:group group
Specifies the parent customization group of this group. The value of this key is not evaluated.
:require struct
Before displaying the customization UI for this group, require the structure struct. This guarantees that all customizable variables will be known at display time. The value of this key is not evaluated.
:layout symbol
Use a particular UI widget to display this group. The value is a symbol, one of:
single
Holds a single customizable item.
vbox
Holds any number of customizable items, arranging them vertically. This is the default.
hbox
Holds any number of customizable items, arranging them horizontally.
frame
Embed the items in a vbox in a frame.
keymaps
Use a special UI widget for customizing keymaps.

The value of this key is not evaluated.

This macro also creates an interactive function named customize:group allowing the GUI to be invoked to configure the new group.

While defgroup is a macro, there is a corresponding custom-declare-group function.

— Macro: defcustom variable value documentation &rest keys

The first three arguments are analogous to the defvar special form, they declare a special variable stored in the symbol variable, whose value is set to value if the variable is currently unbound, with a documentation string documentation.

In the configurator, gtk widget appears left to the docstring. But if the docstring ends with “\\w” (literally in the source; the first backslash for escaping the second), then the widget is put right to the text. This feature is supported by only some widgets.

All other parameters are key-value pairs as with defgroup. The possible pairs are as follows:

:group group
Specifies the customization group that this variable is a member of. This is a list of symbols, indicating a series of nested groups, e.g., (workspace edge-flip). A variable in a top-level customization group can also be specified as a plain symbol, e.g., workspace. The value of this key is not evaluated.
:type type
Specifies the required type of the variable. The current possibilities are:
(symbol [option ...])
A symbol. The UI looks for a symbol property :options and interprets it as the list of valid symbols to select from. The option arguments allow you to define a list at eval time. It is also possible to change this list at run time by changing the custom symbol's :options property; see the access functions custom-add-options and custom-set-options for more information.
(choice option ...)
One of the option elements. Each option is a symbol. Unlike the symbol type, there is no expectation that this list will change at run-time.
string
An arbitrary string.
(number [[min] max]
Integer number. Two additional arguments specify the minimum and maximum allowed values for the integer. One additional argument specified the maximum allowed value; the minimum defaults to zero. Zero additional arguments implies no minimum nor maximum.
boolean
True (t) or false (nil) value.
color
A color.
font
A font name.
file
A file name.
program
A file name that must be an executable program.
command
A Sawfish command.
event
A Sawfish event.
keymap
A Sawfish keymap.
frame-style
The name of a defined Sawfish frame style.
icon
An X icon.
modifier-list
A list of X modifier keys.

Except where specified, the values of these keys are not evaluated.

:require feature
Denotes that the feature feature must be loaded if the variable is set to a non-nil value by user customizations. This is necessary because customization options are loaded on startup, possibly before the modules that define them. The value of this key is not evaluated.
:allow-nil bool
Specifies whether the variable may be nil, instead of a member of its actual type. This is only supported by the string, symbol, font and color types.
:set function
Specifies that the variable must be set by calling function instead of the default custom-set-variable. The function should accept three arguments: (variable value #!optional require).

The usual action of this function is to translate the value into the correct type, then call custom-set-variable. This translation is necessary since many of the UI widgets accept strings representing more complex types (i.e. a color's name, instead of the actual object)

:get function
Provides a function for reading the current value of the variable. Should return a value that's acceptable to the UI widget associated with the variable. Called with a single argument, the symbol containing the variable.
:before-set function
:after-set function
Functions called both immediately before and after setting the value of the variable. Called with a single parameter: the variable itself.
:range (min . max)
The allowed range for numeric variables. If min is nil the the default minimum allowed value is zero; if max is nil then the default maximum is unbounded. This is obsolete, since the :number type now supports range declarations. The value of this key is not evaluated.
:tooltop string
A tooltip that appears when the user's mouse hovers over the widget item.
:depends symbol
This widget item is only settable when the symbol-value for symbol is non-nil.

While defcustom is a macro, there is a corresponding custom-declare-variable function.

Note that where necessary the types themselves define default :set, :get and :widget values that may be overridden by values in the defcustom call. Usually, however, this will not be necessary.

Consider the following example: 

     (defgroup move "Move/Resize")
     
     (defcustom move-outline-mode 'opaque
       "The method of drawing windows being moved interactively."
       :type (set opaque box)
       :group move)
     
     (defcustom move-snap-epsilon 8
       "Proximity in pixels before snapping to a window edge."
       :group move
       :type (number 0 64))

This defines a group and two customization options.

There are two special accessor functions to make it easier to deal with lists of allowed symbols.

— Function: custom-add-option variable option

Add symbol value option to the list of symbols that can be stored in variable. The new option goes on the end of the list.

— Function: custom-get-options variable

Return the list of symbols that can be stored in variable.

Next: , Previous: Defgroup and Defcustom, Up: Customization

9.2 Customization Files

— Variable: custom-user-file

User configuration settings are stored in the file referenced by this variable. While this file contains valid Rep forms, users should not edit it directly: Sawfish will overwrite the file's contents each time a customization is made through the GUI.

By default, this variable is set to "~/.sawfish/custom". The --custom-file command-line option sets it to a different file on program startup.

— Variable: custom-default-file

Default customization settings are stored in the file referenced by this variable. These settings are only applied if the user has no personal settings. By default, this variable is set to "sawfish/wm/custom-defaults.jl" relative to the sawfish-lisp-lib-directory directory.

— Function: custom-load-user-file

If the file referenced by custom-user-file exists, load it. Otherwise if custom-default-file is non-nil, interpret it as a filename and load it.

Previous: Customization Files, Up: Customization

9.3 Customized Variable Status

To get information about a customizable variable, you can use the following functions.

— Function: variable-customized-p symbol

Returns true if symbol has been customized by the user, false otherwise.

— Function: variable-declared-p symbol
— Function: variable-default-value symbol

The variable-declared-p function returns true if the variable named symbol has a default value declared for it, false otherwise. The variable-default-value function returns the default value of that variable, or nil if no such default value exists.

— Function: variable-type symbol

Returns the customizable type of the variable named symbol.

Next: , Previous: Customization, Up: Top

10 Window Frames

Perhaps one of the most important features of a window manager is its ability to decorate client windows, typically seen as an added border, and then to allow the window to be manipulated through user input on the border.

Sawfish provides an extremely flexible method of decorating windows, the look and feel of the border may be specified completely. Also, no limits are placed on which windows are given which borders, if necessary a completely different border could be dynamically created for each window!

Next: , Up: Window Frames

10.1 Frame Basics

The frame of a client window is defined as all decorations added by the window manager. Usually these decorations will be immediately adjacent to the outer edges of the window, but there is no requirement to use this model.

In Sawfish, each window frame is constructed from a list of frame parts, conceptually rectangular objects with a specified position relative to the edges of the client window. When shaped images are used to define frame parts, they are still thought of as being rectangular, just with some pixels missing from the display.

Each frame part has a list of attributes associated with it, these include items defining the background of the part (i.e. a color or an image), and items defining the foreground of the part (i.e. probably some kind of text, with a color, font, etc...). Non-visual attributes may also be defined, such as, for example, the keymap mapping events occurring in the part to Lisp commands to execute (see Keymaps).

So a window frame is defined in Lisp as a list of frame part definitions (see Frame Part Definition). These frame parts are added to the client window (in the order they are defined, so later frame parts are above earlier parts at the same position), to produce the entire window frame.

Next: , Previous: Frame Basics, Up: Window Frames

10.2 Frame Part Classes

Although one of the aims of Sawfish is to provide as much flexibility as possible, this can sometimes be detrimental to the overall experience. For example, it would be easier for the user if all themes use consistent keymaps and cursor images in conceptually similar parts of window frames. That is, it would be better if all close buttons had the same mouse button bindings and the same mouse cursor displayed when the pointer is over them.

To achieve this, Sawfish defines a number of classes of frame parts, each with several default attributes. When defining a window frame, the definitions of each part then specifies which class it is a member of, and inherits the associated default attributes (provided that it hasn't explicitly specified values for these attributes).

— Variable: frame-part-classes

This variable is an association list, associating symbols naming frame part classes with an association list of default attributes for that class.

The names of the pre-defined classes are as follows, their meanings should be self-explanatory:

title, menu-button, close-button, iconify-button, maximize-button, sticky-button, lock-button, rename-button, move-resize-button, raise-lower-button, top-border, left-border, right-border, bottom-border, top-left-corner, top-right-corner, bottom-left-corner, bottom-right-corner.

Extra classes can be created by adding to frame-part-classes. However, it's likely that more than one theme may need to use the same class, and that the user may then wish to customize any extra keymaps used. The def-frame-class macro should be used to add new classes, since it handles these situations.

— Macro: def-frame-class class alist-form &rest binding-forms ...

Creates a new frame part class named by the symbol CLASS.

The ALIST-FORM is evaluated to give an association list defining attributes for the class. Each key-value pairs is only set if no existing value exists for that key.

If binding-forms are given, they will be evaluated when no keymap already exists for the class. A keymap will be created, and stored in the variable named ‘class-name’. This variable may then be used within the binding-forms.

So to define a hypothetical shade-button class, the following might be used: 

     (def-frame-class shade-button '((cursor . left_ptr))
       (bind-keys shade-button-keymap
         "Button1-Off" 'toggle-window-shaded))

In some cases it might be valuable to be able to override pre-defined frame part properties. For example, it might be your preference that text in window title bars is always blue.

— Function: define-frame-class class alist-form #!optional with-keymap

Creates a new frame part class named by the symbol class.

Unlike def-frame-class, the trailing argument is just a boolean flag. This flag only indicates whether to create a keymap for the class. Any bindings have to be established through a separate call to bind-keys.

The function returns t if it was able to create and bind the empty keymap, nil otherwise. This allows us to check for errors.

— Variable: override-frame-part-classes

Similar to frame-part-classes except that the properties take precedence over values defined both in that variable and in the frame style itself.

The following function may be used to simplify the customization of these two variables:

— Function: set-frame-part-value class key value #!optional override

Associate value with property key for all frame parts of class class.

If override is non-nil, then the setting is installed in the override-frame-part-classes variable, otherwise it's stored in the frame-part-classes variable.

The following example would override the colors of all title bars: 

     (set-frame-part-value 'title 'background
                           '("black" "white" "green" "blue") t)

(See the next section for details about what is actually being set here.)

Next: , Previous: Frame Part Classes, Up: Window Frames

10.3 Frame Part Definitions

Each frame part is defined as an association list (or alist), a list of cons cells, the car of each cell defines the attribute, the cdr defines the value given to that attribute. So, for example, the alist ((foo . 1) (bar . 2)) specifies two attributes: foo with value 1, and bar with value 2. See Association Lists.

The attributes that may be defined are as follows:

(class . class)
Specifies the frame part class of the part.
(background . data)
(background . (normal focused highlighted clicked))
Specifies the background of the part. May be a color, an image, or a string naming a color. If a single element, then it is used for all states of the part, otherwise if a list, then each of the four elements defines the background for that particular state.

If an image is used it will be scaled to the size of the frame part, unless it's tiled property is set, in which case it will be tiled across the frame part.

(foreground . data)
(foreground . (normal focused highlighted clicked))
Specifies a foreground color or image for the frame part, either for all states, or for each individual state.

Unlike the background attribute, by default images are not scaled when used to define the foreground of a frame part.

(scale-foreground . value)
When value is non-nil, the foreground image of the frame part will be scaled to the size of the part.
(font . font)
(font . (normal focused highlighted clicked))
Specifies the font(s) of the part.
(text . value)
Specifies the string to draw in the foreground of the frame part (unless the foreground property is an image). Either a string, or a function, that will be called each time that the part is refreshed, that will return the string to draw.
(x-justify . value)
Defines the horizontal position of the foreground contents of the part (i.e. the text or foreground image). May be one of the symbols left, right or center, or a number. If a number it defines the number of pixels from the left edge if positive, or the right edge if negative.
(y-justify . value)
Similar to x-justify, but the accepted symbols are top, bottom or center instead.
(renderer . function)
This attribute may be used instead of the background attribute. When the part needs to be drawn function will be called with an image in which to render the background, and the current state of the part, a symbol focused, highlighted, clicked, or nil (for the normal state).
(render-scale . value)
This attribute causes the size of the image used with the renderer property to be reduced by a factor of value, an integer.
(left-edge . value)
Defines the position of the left edge of the part, in relation to the left edge of the client window.
(right-edge . value)
Defines the position of the right edge of the part, in relation to the right edge of the client window.
(top-edge . value)
Defines the position of the top edge of the part, in relation to the top edge of the client window.
(bottom-edge . value)
Defines the position of the bottom edge of the part, in relation to the bottom edge of the client window.
(width . value)
Defines the width of the frame part.
(height . value)
Defines the height of the frame part.
(border-width . value)
(border-color . value)
Defines the border width and color. A “border” if present surrounds the window and all other frame parts. Both width and color are applied to the whole window instead of current frame part. (Thus they should be properties of window, not frame parts. Sorry.)
(keymap . value)
Defines the keymap to use when evaluating events originating in this frame part.
(cursor . cursor)
Defines the cursor to display when the mouse is in this part. May be either a cursor object, or the argument to get-cursor to create the required cursor object.
(removable . value)
When specified and value is non-nil, this frame part may be removed from the frame without being detrimental to the overall appearance of the frame. This is only important for button classes, which may sometimes be removed at the request of the client window.
(below-client . value)
When specified and value is non-nil, then this frame part will be displayed beneath the client window. The default action is for frame parts to be stacked above the client window.
(hidden . value)
When specified and value is non-nil, don't display this frame part.

The values specified for the background, foreground, render-scale, font, left-edge, right-edge, top-edge, bottom-edge, width, height, border-color, cursor, below-client and hidden attributes may actually be functions. In which case the function will be called (with a single argument, the window object) when the frame is constructed, the value returned will be used as the actual value of the attribute.

The coordinate system used for specifying the part's position is relative to the window edge that the position is defined against. Positive values count in from the window edge towards the center of the window, while negative values count out from the edge, away from the center of the window.

Consider the following example, a solid black title bar that is twenty pixels high, directly above the client window: 

     `((background . "black")
       (foreground . "white")
       (text . ,window-name)
       (x-justify . 30)
       (y-justify . center)
       (left-edge . 0)
       (right-edge . 0)
       (top-edge . -20)
       (height . 20)
       (class . title))

The backquote operator is used since the definition is only mostly constant, the comma operator inserts the value of the window-name variable (a function giving the name of a window) into the definition; see Backquoting).

This function is then used to dynamically specify the string drawn in the foreground. The window manager will automatically refresh the foreground of all frame parts of a window whenever any X property of that window changes.

Given a framed window, and a particular frame part class, it is possible to retrieve the values of individual attributes from the complete list of definitions (including inherited or overrided definitions).

— Function: frame-part-get part property

Returns the value of the property property for the frame part object part. Returns nil if no such attribute exists.

— Function: frame-part-put part prop value

Set the property prop of frame part part to value.

— Function: frame-part-state part

Return the current state for frame part part, one of the symbols focused, highlighted, clicked, inactive-highlighted, inactive-clicked, or nil if the part is inactive.

Next: , Previous: Frame Part Definition, Up: Window Frames

10.4 Frame Functions

— Function: set-window-frame window frame-def

Sets the frame of the client window associated with the object window to that defined by the list of frame part definitions frame-def. If the window is mapped the old frame will be destroyed and a new frame constructed.

— Function: window-frame window

Return the list of frame part definitions defining the frame associated with window.

— Function: window-framed-p window

Return t when window has been reparented to a frame created by the window manager.

— Function: refresh-window window

Refresh all the frame parts belonging to window.

— Function: rebuild-frame window

Recreates the window frame associated with window, from the previously defined frame definition. All frame parts are reinitialized and recalibrated.

— Function: window-frame-dimensions window

Return the size of the window window including the frame, in a cons cell (width . height).

The size excluding the frame is returned by window-dimensions. (see Window Attributes)

— Function: window-frame-offset window

Return a cons cell (x . y) defining the offset from the origin of the client window associated with window to the origin of its frame. That is, their values are negative integers.

— Function: window-border-width window

Return the width of the border of the window that window manages.

— Function: clicked-frame-part

Return a pointer to the frame part object that was clicked on as part of the current event. Returns nil if no frame part was clicked on.

— Function: frame-part-dimensions part

Return a cons cell (width . height) of dimensions for frame part part.

— Function: frame-part-position part

Return a cons cell (x . x) of the relative position of frame part part against its window's frame origin.

— Function: window-frame-id win

Returns the numeric id of the framing window associated with object window. Returns nil if the client window has no frame.

— Function: frame-part-window part

Return the window object associated with this frame part.

— Function: frame-part-x-window part

Return the X11 window ID associated with this frame part.

— Function: frame-draw-mutex lock

If lock equals to t, frame part redraws will be delayed. The redraws will take place once the function is called with lock set to nil.

Returns the previous value.

— Function: frame-state-mutex lock

If lock is non-nil, the state of frame parts will not be altered at pointer enter and leave events.

Returns the previous value.

— Function: map-frame-parts function window

Call (function part) on each the frame parts of window and return nil. If any function returns nil, map-frame-parts returns nil immediately.

— Function: rebuild-frame-part part

Build a new copy of the frame part part and install the copy in the owning window, replacing the old part.

— Function: refresh-frame-part part

The frame part part will be redrawn at the next opportunity.

Next: , Previous: Frame Functions, Up: Window Frames

10.5 Frame Types

In order to visually differentiate between different types of windows, several predefined types of window frame exist.

— Function: window-type window

Returns a symbol naming the frame type currently associated with window.

These frame types currently include the following:

default
The normal frame type. Includes all decorations, both borders and the title bar.
transient
The frame for a transient window. This usually does not include a title bar, but does have all four borders.
shaped
Shaped windows are normally decorated with only a title-bar, since their boundary is not rectangular it makes no sense to surround them with a rectangular border.
shaped-transient
A combination of the shaped and transient types, normally just a very small title border with no text.
shaded
A shaded window (normally just the title bar).
shaded-transient
A shaded transient window.
unframed
No frame at all, just the client window itself. The predefined nil-frame variable contains a null frame that may be used for this frame type.
— Function: define-frame-type-mapper fun

Function fun maps from {window, frame-type} to frame-type.

Each time we want to determine a window's frame-type (shaded, transient, etc.), we calculate an initial frame type with window-type and run the results through each frame type mapper in sequence (most recent to oldest). The frame type returned from the final mapper function is “the” frame type.

This sequence of mappers allows us to override window frame types based on window properties. For example, any shaded window has to have shaded or shaded-transient type, regardless of what its normal type is.

— Function: window-type-add-border type
— Function: window-type-add-title type
— Function: window-type-remove-border type
— Function: window-type-remove-title type

Given a window type of type, return the closest matching window type with the given property change. For example: 

          (window-type-add-title 'unframed)
          ⇒ 'shaped

This is because shaped windows normally have title bars but not borders, while unframed windows normally have neither.

— Function: frame-type-menu window

Returns a list of frame types, suitable for use by the graphical customizer. The frame type of window is automatically checked.

We provide a function to simplify monitoring of window changes to certain window states. This monitoring runs on top of the window-state-change-hook.

— Function: call-after-state-changed states fun

Arrange for function fun to be called with arguments ‘(window changed-states)’ when one of the states defined by the list of symbols states has been changed. States may also be a single symbol.

Next: , Previous: Frame Types, Up: Window Frames

10.6 Frame Styles

Frame styles are used to encapsulate frames of the different types that have a single visual appearance. Each frame style associates a name with a function that creates a frame definition for a particular window and frame type combination.

Several window properties are used while choosing frame styles:

— Window Property: frame-style

The user-chosen frame style of the window. If nil, Sawfish will use the default frame style.

— Window Property: current-frame-style

The current frame style of the window. This is not set explicitly; window update functions will change it behind the scenes.

— Window Property: ignored

When set, the window is not given a frame.

— Function: reload-frame-style name

Reloads the frame style name from disk if it is already known to the system. All windows with that style are reframed.

— Function: update-frame-font-color

Reloads the frame font colors, if use-custom-font-color is true. Use frame-font-active-color and frame-font-inactive-color to modify the frame font colors.

Next: , Previous: Frame Styles, Up: Window Frames

10.7 Themes

Themes and frame styles are currently almost synonymous, the slight difference being that themes provide a mechanism for loading frame styles from the filing system as they are required. Although it is possible that themes may include other user-interface settings in a later version, at the moment it seems unlikely.

When a frame style is requested, if it is not already available (i.e. if the add-frame-style function hasn't been called for that style) then the window manager will attempt to load a theme of the same name from the filing system.

Each theme is stored in a directory; this directory must have the same name as the name of the theme itself. Within this directory there must be a Lisp script named theme.jl or theme.jlc. This script will be evaluated, it should provide a frame style of the same name as the theme (by calling add-frame-style).

While the theme script is evaluating the image-load-path variable is set to include the theme directory as its first element. This ensures that any image files stored in the directory can be loaded using the make-image function.

Since rep has no module system, any global variables defined within the theme must be prefixed by the name of the theme to ensure their uniqueness. For example, in the theme foo, a variable bar would actually be called foo:bar.

In most cases however, rep's lexical scoping can be used to avoid declaring any global variables or functions, the only usual exception is when declaring customization options with defcustom; these must be globally visible.

Since themes are generally passed around very casually, sawfish evaluates all theme code in a very restricted environment; the idea being that themes should only be able to affect the look of the window manager. Despite this, it is still possible for malicious themes to lock, and possibly crash, the window manager; in the first case sending a SIGINT signal may unblock it. Hopefully themes are unable to affect the rest of the user's environment, but there are no guarantees...

— Variable: theme-load-path

A list of directory names, provides the search path for locating theme directories. By default this includes the user's theme directory and the system theme directory.

— Variable: user-theme-directory

The name of the user's theme directory, by default ~/.sawfish/themes.

— Variable: system-theme-directory

The name of the directory holding themes from the current Sawfish version, by default 

          (expand-file-name "../themes" sawfish-lisp-lib-directory)
— Variable: site-theme-directory

The name of the directory holding system-wide themes, by default 

          (expand-file-name "../../themes" sawfish-lisp-lib-directory)
— Variable: theme-update-interval

Number of seconds between checking if theme files have been modified. Default 60.

— Variable: themes-are-gaoled

If t, non-nil themes are assumed to be malicious. They will be evaluated in a restricted environment.

— Variable: frame-type-fallback-alist

Frame type fallbacks. This is an alist whose elements are (required-type . fallback-type). When REQUIRED-TYPE is not supported by the current theme, then FALLBACK-TYPE is used instead."

Previous: Themes, Up: Window Frames

10.8 Removing Frame Parts

It is often useful to be able to disable certain parts of a window's frame. For example, a window may hint to the window manager that it doesn't want a maximize button. Sawfish allows all parts of a particular class to be disabled or enabled on a window by window basis. However, not all frame styles will support this (it depends on the frame part's removable property, Frame Part Definition).

— Function: add-frame-class window class

Enable all frame parts that are a member of class in window.

— Function: frame-class-removed-p window class

Returns t if the frame part class has been removed from window, nil otherwise.

— Function: remove-frame-class window class

Disable all frame parts that are a member of class in window where possible.

Next: , Previous: Window Frames, Up: Top

11 Viewports

Sawfish can have a virtual desktop which is larger than the computer's screen size. This is done through the use of “viewport”.

Viewport can be thought of as a screen-sized hole through which you can view a portion of the virtual desktop. The entire virtual desktop consists of the grid of “cells” whose size is that of the physical screen. Viewport moves around, and sits on a cell.

In Sawfish, the word “viewport” is sometimes used to mean the entire larger-than-normal desktop. This is natural, but a confusion and not technically correct. When focused to enlargement, “large desktop” is the correct nomenclature, but simply calling it the “workspace” or the “virtual desktop” are correct too.

The word “viewport” is also used to mean the cell on which the viewport is set, like “Go to the next viewport.”

— Variable: viewport-dimensions

The dimension of the virtual destkop. This is a cons cell (columns . rows). Defaults to (1 . 1). The number of viewport cells in the virtual desktop is columns times rows.

If viewport-boundary-mode is dynamic (see Dynamic Viewport) then this variable is set by Sawfish to the current size of the current workspace and should not be set by the user.

— Function: set-number-of-viewports width height

Change viewport-dimensions to have the value (width . height). If viewport-boundary-mode is dynamic then this sets the minimum dimensions of the virtual workspace (see Dynamic Viewport) rather than setting the dimensions directly.

Next: , Previous: Viewports, Up: Viewports

11.1 Viewport Functions

Each cell is labeled with the index (col, row), and the top-left cell is (0, 0). Indices are never negative.

Sawfish implements viewport as follows. On a cell change, windows in previous cells are removed, and windows in the current cell appear. Windows that span two or more cells will appear in each cell, appropriately displaced.

— Function: screen-viewport

Returns the currently displayed viewport as a pair (x . y).

— Function: set-screen-viewport col row

Change the viewport to visit cell (col, row).

— Function: move-viewport right down

Move the viewport to see the cell right columns right and down rows down. Either argument may be zero or negative.

— Customizable: viewport-boundary-mode

Decides how to act when you call set-screen-viewport and you try to go outside of the virtual desktop. (Its size is specified by viewport-dimensions.) Defaults to stop.

When set to stop, it stops at the boundary of the virtual desktop.

When set to wrap-around, it behaves as if the leftmost viewport and the rightmost are connected. Same for the top and bottom.

If it is set to dynamic, then the workspace size changes automatically. For details, see See Dynamic Viewport.

— Function: viewport-honor-workspace-edges

Returns whether or not the display is permitted to move past the current workspace boundaries. It returns true if viewport-boundary-mode is not set to dynamic.

— Function: viewport-at x y

Returns a cons cell consisting of (column . row) of the viewport containing the specified x and y coordinates. The coordinates are specified relative to the current viewport, so (viewport-at 0 0) is equivalent to (screen-viewport).

— Function: viewport-offset-coord viewport

Returns the offset from the current viewport to viewport which is specified as (column . row). The return value is the cons cell (x . y). The values are in pixel, and are negative if it lies at left or above the current viewport.

viewport can be outside of the workspace. (The check is not done.) If viewport is nil it is understood as the current viewport, i.e., (0 . 0) will be returned.

There are lower-level functions which move viewport by pixel, not by multiples of the physical screen dimensions.

Note that use of these breaks the traditional behavior and user interface of Sawfish. Though they are useful, simultaneous use of these functions and other functions may cause weird results.

— Function: set-viewport x y

Change the position of the viewport, such that location (x, y) is at the top-left of the display. So (set-viewport 0 -5) will shift the viewport up five pixels.

— Customizable: scroll-viewport-steps

When you move the viewport, the bigger this value, the more smoothly the screen is scrolled. It is the number of steps for scrolling.

The default value 1 means the change is instantaneous, and no scroll is done. The upper limit for customization is 50.

This variable is used for set-viewport. All interactive commands defined by Sawfish call this function, so this variable is important for the user.

Next: , Previous: Viewport Functions, Up: Viewports

11.2 Dynamic Viewport

“Dynamic viewport” is enabled by setting viewport-boundary-mode to the symbol dynamic. It has two features.

Normally, the viewport cannot move beyond the limits set by viewport-dimensions, but this limitation is removed in dynamic viewport. The viewport is allowed to go as far as you wish.

In addition, workspace is automatically resized, both enlarged and shrinked, so that it contains the current viewport and all windows. (Precisely speaking, it takes the minimum such size.) The size is set when you move the viewport, and also at Sawfish startup. Each workspace has its own size independent of the others.

Even in dynamic viewport, the top-left cell is always (0, 0), and the cell indices are never negative.

The dynamic viewport is still an experimental feature, and its specification may change.

— Customizable: viewport-minimum-dimensions

This is only useful if dynamic viewport is enabled. viewport-dimensions will never be set to less than viewport-minimum-dimensions, unless it is a change requested by the user, either by using the configuration interface or by calling set-number-of-viewports.

If setting viewport-minimum-dimensions by hand (not by the customization interface) be sure to call viewport-minimum-size-changed after doing so to ensure that the new minimum dimensions immediately go into effect.

If set-number-of-viewports is called to set the viewport dimensions viewport-minimum-dimensions will be set to the same value. Also, if (using the configuration interface) you set the viewport dimensions to less than viewport-minimum-dimensions then viewport-minimum-dimensions will be adjusted to match. This way those who are not using dynamic viewports do not need to worry about viewport-minimum-dimensions.

Under dynamic viewport, viewport-dimensions is the current size of the current workspace, and does not have the meaning as a user option.

Next: , Previous: Dynamic Viewport, Up: Viewports

11.3 Smooth Viewport

“Infinite desktop” is an intuitive, nice feature. Just move the mouse, for example to right, very far. As the pointer hits the screen edge, the viewport moves as if it is dragged by mouse motion. Viewport moves around by any amount, not limited to by a step of the physical screen size.

To enable infinite desktop, put the following in your ~/.sawfish/rc: 

     (require 'sawfish.wm.ext.infinite-desktop)

Options can be set from the configurator, under Workspace section.

Infinite desktop behavior differs noticeably from the usual viewport which lies on grid cells. For example, it does not make sense to ask in which viewport a window lies. The design is not complete yet, and may change in future. There may be some bugs.

It is called “infinite desktop” by historical reason, but in fact you can limit the entire desktop size as you like.

Previous: Smooth Viewport, Up: Viewports

11.4 Windows and Viewports

— Function: window-viewport window

Returns a cons cell (col . row) of the viewport holding the top-left corner of window.

— Function: window-outside-viewport-p window #!optional viewport

Returns true if window is completely outside the current viewport in any direction. If viewport is specified check against that viewport rather than the current one.

— Function: window-absolute-position window

Returns the coordinates of the window as if the window's viewport is selected. The return value is the cons cell (x . y).

— Function: set-window-viewport window col row

Move window to the cell at (col, row). The relative position of the window within the cells is preserved.

— Function: move-window-viewport window col-delta row-delta

Move window to the cell col-delta positions across and row-delta positions down from its current cell. The relative position of the window with its cells its preserved.

— Function: move-window-to-current-viewport window

Move window from its existing viewport to the current viewport. The window's relative position in the existing viewport is preserved after the move.

— Function: move-viewport-to-window window

Move the viewport to a cell that shows window window. For a window that spans multiple cells, this function will pick the cell showing the window's top-left corner.

— Customizable: uniconify-to-current-viewport

When true, windows uniconify to the current viewport, rather than to the viewport they were iconified on. Defaults to true.

Next: , Previous: Viewports, Up: Top

12 Workspaces

Workspaces provide another way for users to organize their windows in Sawfish. Unlike viewports, workspaces don't have geometric relationship with each other.

The word “virtual desktop” is sometimes used instead of “workspace”.

Next: , Previous: Workspaces, Up: Workspaces

12.1 Workspace Intervals

While the stack of workspaces conceptually goes from negative infinity to positive infinity, we normally present only the first non-empty workspace through the last non-empty workspace to the user. The non-empty interval is occasionally re-normalized to start with zero.

We typically refer to workspaces with lower IDs being to the “left” of workspaces with higher IDs, as if on a number line.

— Variable: current-workspace

The ID of the currently active workspace. This is an integer. The “default” workspace has ID 0.

— Function: workspace-limits

Returns a pair (first-index . last-index) defining the subset of the workspace continuum that is “interesting” to the user (typically, all those that have ever been explicitly created).

— Function: workspace-id-to-logical space-id #!optional limits

Takes an absolute workspace ID and returns its position in the interval of “interesting” workspaces. If limits is provided, it must be a pair (first-index . last-index) like that returned by workspace-limits. If it is not provided, the function uses the result of workspace-limits directly.

— Function: workspace-id-from-logical offset #!optional limits

Takes an offset position into an interval of “interesting” workspaces, and returns the workspace ID at that position. If limits is provided, it must be a pair (first-index . last-index) like that returned by workspace-limits. If it is not provided, the function uses the result of workspace-limits directly.

— Function: popup-workspace-list

Display the menu containing the list of all workspaces.

— Function: workspace-menu

Returns a list of workspaces, suitable for display in a menu.

— Customizable: workspace-names

A list of workspace names. When displaying the workspace menu, the first N workspaces use the corresponding list elements as their display names (where N is the length of the list). Normally they get the display name ‘space N’ for some value of N.

Next: , Previous: Workspace Intervals, Up: Workspaces

12.2 Workspace Manipulation

Sawfish has various functions to create, rearrage and delete workspaces. Windows in a deleted workspace are not lost; they are moved to another workspace.

— Function: select-workspace space &key dont-focus force

Activate workspace space, making it current.

By default in enter and click focus modes, the most recently used window will receive focus. The caller can disable this behavior by passing a true dont-focus keyword argument.

If the force keyword argument is true, we will go through the activation process even if space already is current.

— Function: select-workspace-from-first count

Select the workspace in position count from the list of “interesting” workspaces.

— Function: select-workspace-and-viewport space col row

Select workspace space and then switch to viewport (col, row) in that workspace.

— Function: insert-workspace #!optional before

Insert a new workspace, returning its index. The new index appears before the workspace indicated by before, or the current workspace if before is nil.

— Function: insert-workspace-after

Create a new workspace following the current workspace.

— Function: insert-workspace-before

Create a new workspace preceeding the current workspace.

— Function: move-workspace space count

Move the workspace space count positions forward, or count positions backwards if count is negative.

— Function: move-workspace-forwards #!optional count

Move the current workspace one place to the right (or count places to the right if count is defined).

— Function: move-workspace-backwards #!optional count

Move the current workspace one place to the left (or count places to the left if count is defined).

— Function: next-workspace count
— Function: previous-workspace count

Switch from the current workspace (index i) to the workspace i+count. The previous-workspace function is identical to (next-workspace (- count)).

These functions do not have default values for their count arguments.

— Function: remove-workspace #!optional index

Remove workspace index (or the current workspace if index is nil). All windows in that workspace are moved to the next workspace index+1. This will change the set of “interesting” workspaces.

— Function: merge-next-workspace

Delete the current workspace. Its member windows are relocated to the next workspace.

— Function: merge-previous-workspace

Delete the current workspace. Its member windows are relocated to the previous workspace.

— Function: set-number-of-workspaces wanted

Add or remove workspaces until the number of “interesting” workspaces is equal to wanted.

When adding workspaces, the new workspaces get indices higher than any existing indices. When removing workspaces, the lowest workspaces are always chosen for removal (their windows are merged into the new lowest-index workspace).

— Variable: lock-first-workspace

When true, preserve the outermost empty workspaces in the pager. Don't quietly remove them when they become empty. Defaults to true.

Next: , Previous: Workspace Manipulation, Up: Workspaces

12.3 Workspaces and Windows

Workspaces do not need to have windows assigned to them, but most operations with workspaces involve adding and removing windows.

— Function: all-workspaces

Returns a list of indices for all workspaces that contain windows. Sticky windows appear in the current workspace.

— Function: workspace-empty-p space

Returns true if workspace space contains zero (non-sticky) windows.

— Function: delete-empty-workspaces

Delete any workspaces that don't contain any windows.

— Variable: workspace-boundary-mode

How to act when passing the first or last workspace, one of stop, wrap-around or keep-going. Defaults to stop.

Each window can be a member of any (positive) number of workspaces; their workspaces property contains a list of workspace ids. Sticky windows appear on all workspaces, and have their sticky property set (with a null workspaces property). If Sawfish begins managing a window with its workspaces property set, then the window is added to those workspaces automatically.

— Function: window-in-workspace-p window space

Returns true if window is a member of workspace space, false otherwise.

— Function: window-appears-in-workspace-p window space

Returns true if window appears in workspace space, false otherwise. To appear, window has to be visible, but it can either be assigned to the workspace or be sticky.

— Function: windows-share-workspace-p window1 window2

Returns true if window1 and window2 are members of at least one common workspace.

— Function: nearest-workspace-with-window window space

Returns the nearest workspace to space that contains window.

— Function: workspace-windows #!optional space include-iconified

Returns a list of all windows that are members of the current workspace (or space if it is not nil). The list normally does not contain iconified windows, but they can by included by specifying a true include-iconified argument.

— Function: popup-window-menu

Display the menu of all managed windows.

— Function: move-window-to-workspace window old new #!optional was-focused

Move window from workspace old to workspace new.

We need the old workspace as an explicit argument because a window can be in more than one workspace. The function does the right thing if the window already appears in workspace new.

If was-focused is true and the window is visible, it gets the input focus in the new workspace.

— Function: copy-window-to-workspace window old new #!optional was-focused

Arrange it so window appears in both old and new workspaces.

If was-focused is true and the window is visible, it gets the input focus in the new workspace.

— Function: send-to-next-workspace window count #!optional copy select

Move the window count workspaces to the right. Count does not default to one.

The window is normally removed from the current workspace (if it is in that workspace), or from the first workspace it belongs to. Supplying a true copy argument causes Sawfish to copy the window instead.

If select is true, then we switch to the destination workspace. If the moved window had input focus before the move, it will have input focus after the move as well.

— Function: send-to-previous-workspace window count #!optional copy select

Move the window count workspaces to the left. Count does not default to one.

The window is normally removed from the current workspace (if it is in that workspace), or from the first workspace it belongs to. Supplying a true copy argument causes Sawfish to copy the window instead.

If select is true, then we switch to the destination workspace. If the moved window had input focus before the move, it will have input focus after the move as well.

This is identical to (send-to-next-workspace window count copy select).

— Function: copy-to-next-workspace window count select

Copy the window count workspaces to the left. Count does not default to one.

If select is true, then we switch to the destination workspace. If the moved window had input focus before the move, it will have input focus after the move as well.

This is identical to (send-to-next-workspace window count t select).

— Function: copy-to-previous-workspace window count #!optional select

Copy the window count workspaces to the right. Count does not default to one.

If select is true, then we switch to the destination workspace. If the moved window had input focus before the move, it will have input focus after the move as well.

This is identical to (send-to-previous-workspace window count t select).

— Function: send-window-to-workspace-from-first window count #!optional copy select

Move window to the workspace at position count in the “interesting” list.

The window is normally removed from the current workspace (if it is in that workspace), or from the first workspace it belongs to. Supplying a true copy argument causes Sawfish to copy the window instead.

If select is true, then we switch to the destination workspace. If the moved window had input focus before the move, it will have input focus after the move as well.

— Variable: workspace-send-boundary-mode

How to act when passing the first or last workspace, while moving a window. One of stop, keep-going, wrap-around. Defaults to stop.

— Function: delete-window-instance window

Remove the copy of window on the current workspace. If this is the last instance remaining, then delete the actual window. Note that this behavior differs from the merging that happens when you delete a workspace.

— Function: map-window-workspaces fun window

Map function fun over all workspaces containing window.

When a window appears on more than one workspace, some of its properties may be swapped in and out on demand when the current workspace is changed.

— Variable: workspace-local-properties

Window properties whose values may differ on differnet workspaces. Defaults to the empty list.

— Variable: add-swapped-properties props

Add all properties in the list props to workspace-local-properties.

It is possible to hide all “normal” windows across workspaces. “Normal” in this case excludes desktop windows and dock windows, but includes sticky and ignored windows. The hidden windows are no longer considered “viewable” according to window-viewable-p.

— Function: show-desktop

Hide all windows except the desktop and dock windows.

— Function: hide-desktop

Undo the effects of the show-desktop command.

— Function: showing-desktop-p

Return true if non-desktop and non-dock windows are hidden, false otherwise.

Previous: Workspaces and Windows, Up: Workspaces

12.4 EdgeActions

EdgeActions is a centralized way to control the behaviour of the screen-borders and -corners, which offers high customizability.

It consists of the following modules: sawfish.wm.edge.subrs -, which contains the C-subroutines, sawfish.wm.edge.utils - a set of utility functions, sawfish.wm.edge.actions - infrastucture module, sawfish.wm.edge.flip - edge-fliping functions, sawfish.wm.edge.hot-spots - hot-spot functions and sawfish.wm.edge.viewport-drag - functions for dragging the viewport.

12.5 EdgeAction Internals

C-Subroutines (sawfish.wm.edge.subrs):

— Function: create-flippers

Create the flipper-window, which is -to put it plainly- your screen-border. Actions are performed when the flipper-window is activated. Technically it's one window, but from users point of view it consists of 8 parts (4 borders plus 4 corners).

— Function: destroy-flippers

Destroy the flipper-window.

— Function: recreate-flippers

Recreate the flipper-window, this is done automatically, when the resolution changes, to ensure EdgeActions stays working properly.

— HOOK: enter-flipper-hook

This hook is called when the flipper-window is entered.

— HOOK: leave-flipper-hook

This hook is called when the flipper-window is left.

Utils (sawfish.wm.edge.utils):

— Function: activate-flippers t

A wrapper-functions around recreate-flippers and destroy-flippers, which additionally adds (respectively removes) the required hook-functions.

— Customizable: hot-spots-corner-length 50

Length in px (in both x and y direction) wich is used for the hot-spot corners. All remaining pixels represent the borders.

— Function: get-active-corner

This function returns the corner of the flipper-window which was entered, or nil.

— Function: get-active-border

This function returns the border of the flipper-window which was entered, or nil.

Infrastructure (sawfish.wm.edge.actions):

— Customizable: left-right-edge-action 'none/hot-spot

Action to perform for the left and right screen-edges when they are hit by the pointer, either flip-workspace, flip-viewport, viewport-drag or none/hot-spot.

— Customizable: left-right-edge-move-action 'none

Action to perform for the left and right screen-edges when a window is dragged over them, either flip-workspace, flip-viewport, viewport-drag or none.

— Customizable: top-bottom-edge-action 'none/hot-spot

Action to perform for the top and buttom screen-edges when they are hit by the pointer, either flip-workspace, flip-viewport, viewport-drag or none/hot-spot.

— Customizable: top-bottom-edge-move-action 'none

Action to perform for the top and bottom screen-edges when a window is dragged over them, either flip-workspace, flip-viewport, viewport-drag or none.

— Function: activate-edges t

This function calls activate-flippers and adds the required hook-functions to be able to perform user-actions on the edges.

— Function: edge-action-call func edge

This function calls the desired user-action func for the screen-edge edge.

— Function: edge-action-hook-func

This hook-function is responsible to either call hot-spot-invoke (if a corner was activated) or to call edge-action-call to perform an action, when the edge was activated using the pointer.

— Function: edge-action-move-hook-func

This hook-function is responsible to call edge-action-call to perfom an action, if the edge was activated while dragging a window over it. Hot-Spots is not supported when doing so.

EdgeFlip (sawfish.wm.edge.flip):

This is the traditional EdgeFlip. When a window or the pointer hits the screen-edge, the screen is shifted by either one Viewport or one Workspace in that direction. The pointer is warped accordingly (to keep in logical position).

— Customizable: edge-flip-delay 250

"Delay (in milliseconds) of flipping of viewport / workspace."

— Function: edge-flip-invoke edge type

This function invokes edge-fliping. edge (a symbol) is the screen-edge that is active (left, right, top, bottom), type is either workspace or viewport.

ViewportDrag (sawfish.wm.edge.viewport-drag):

iViewportDrag (formerly Infinite-Desktop) is a mechanic, that shifts the Viewport accordingly to which screen edge was activated. This way the Viewport becomes virtually "infinite", regardless of the physical size (thus the old name).

— Customizable: viewport-drag-distance 64

Amount to drag the viewport (in pixel) each time the pointer hits the screen edge.

— Customizable: viewport-drag-cursor-distance 32

"Amount to pull back the cursor (in pixel) after dragging the viewport." Recommended is half of viewport-drag-distance.

— Function: viewport-drag edge

This function invokes viewport-dragging. edge is the screen-edge that is active (left, right, top, bottom) (a symbol).

HotSpots (sawfish.wm.edge.hot-spots):

HotSpots is a mechanic, which allows for practically everything to be done when a screen edge or a corner is activated. the corners are defined via hot-spots-corner-length. Only HotSpots responds to the corners.

That way your screen-edge is actually split into 12: 4 corners, two times 4 edges (as explained above actions are split for when while moving a window and for when activating the edges using the pointer). Corners are not recognized for for while moving a window.

HotSpots only allows functions to be used as actions, though practically everything can be done this way. If the arguement is not a function, an error is thrown, to in form the user.

— Customizable: hot-spot-delay

Delay (in milliseconds) before activating a hot-spot.

— Customizable: left-edge-function nil

The function launched when hitting the left-edge.

— Customizable: top-left-corner-function nil

The function launched when hitting the top-left-corner.

— Customizable: top-edge-function nil

The function launched when hitting the top-edge.

— Customizable: top-right-corner-function nil

The function launched when hitting the top-right-corner.

— Customizable: right-edge-function nil

The function launched when hitting the bottom-edge.

— Customizable: bottom-right-corner-function nil

The function launched when hitting the bottom-right-corner.

— Customizable: bottom-edge-function nil

The function launched when hitting the bottom-edge.

— Customizable: top-left-corner-function nil

The function launched when hitting the bottom-left-corner.

— Function: hot-spot-invoke spot

This function invokes the hot-spot. spot (a symbol) is either left, top-left, top, top-right, right, bottom-right, bottom or bottom-left.

Example configuration (~/.sawfishrc):

Note: this is just an example, not all functions in it may be availabe on your system. 

     ( defvar-setq edge-flip-delay 250 )
     ( defvar-setq hot-spot-delay 125 )
     
     ( defvar-setq top-left-corner-function
       ( lambda () ( tile-windows ) ) )
     
     ( defvar-setq top-right-corner-function
       ( lambda () ( pager-unhide ) ) )
     
     ( defvar-setq  bottom-right-corner-function
       ( lambda () ( show-desktop ) ) )
     
     ( defvar-setq bottom-left-corner-function
       ( lambda () ( raise-window ( get-window-by-role "panel_" #:regex t ) ) ) )
     
     ( defvar-setq top-edge-function
       ( lambda () ( jump-or-exec "Konsole" "konsole" #:match-class t ) ) )
     
     ( defvar-setq bottom-edge-function
       ( lambda () ( jump-or-exec "Dolphin" "dolphin" #:match-class t ) ) )
     
     ;; actions when pointer hits edge
     ( defvar-setq left-right-edge-action 'flip-viewport )
     ( defvar-setq top-bottom-edge-action 'none/hot-spot )
     
     ;; actions while moving window hits edge
     ( defvar-setq left-right-edge-move-action 'flip-workspace )
     ( defvar-setq top-bottom-edge-move-action 'none )

Next: , Previous: Workspaces, Up: Top

13 RandR and Xinerama

Sawfish supports multiple monitors displaying a single logical screen. Partial support of RandR is done.

— Function: has-randr-p

Returns t if RandR is supported.

Next: , Up: RandR and Xinerama

13.1 Multi-head Environment

Functions which provide information on monitor geometries are available. On the other hand, few user interface functions take them into account, so for example, windows often appear across multiple monitors.

Currently, monitor geometries are taken from Xinerama only. RandR support in this regard is yet to be done.

A “head” means each physical monitor. When there're multiple heads, the word “screen” means the entire screen which is the combination of all heads. For example the function screen-width returns the width of the “screen” in this sense. A viewport contains the entire screen. The only exception is maximizations which are done within a head, unless stated explicitly that it's xinerama.

— Function: find-head x y

Return a ID for the display head that point (x, y) is in. The return value is an integer; the default head has ID zero. Returns nil if it cannot determine the head from x and y.

— Function: head-count

Return the number of display heads on the machine.

— Function: head-dimensions id

Return the cons cell (width . height) of the dimensions of the display head indicated by id. Id must be a non-negative integer. Without Xinerama support, id must be zero and the function returns the screen size.

— Function: head-offset id

Return the cons cell (x . y) of the dimensions of the display head indicated by id. Id must be a non-negative integer. Without Xinerama support, id must be zero and the function returns (0 . 0).

— Function: pointer-head

Return the ID of the head containing the mouse pointer.

— Function: current-head #!optional window

Return the ID of the head containing the window with input focus. If window is supplied and a window, return the head containing that window. If window is supplied and nil, return (pointer-head).

— Function: window-head-any-viewport window

Like current-head, this will return the ID of the head containing the specified window. But unlike current-head, window-head-any-viewport returns the head that the window would be in if its viewport were the visible viewport.

— Function: current-head-dimensions #!optional window

Return a cons-cell defining the size in pixels of the current head (that containing the window window, or the pointer if window is false). Returns the screen dimensions if no such head can be identified.

— Function: current-head-offset #!optional window

Return a cons-cell defining the origin of the current head (that containing the window window, or the pointer if window is false). Returns '(0 . 0) if no such head can be identified.

Previous: Multi-head Environment, Up: RandR and Xinerama

13.2 Screen Change Notification

If some changes happen to the screen, hot-plugging, removal, or resolution change, then you can receive the notification.

One way is to use configure-notify-hook.(see X Hooks) Then the window argument is set to the symbol root. The other way is to use randr-change-notify-hook below. Both are called, but there's no guarantee of the order.

Notice that both may be called several times for one change. For example, “xrandr” command invocation from shell triggers three calls of both hooks in an author's environment.

— Hook: randr-change-notify-hook

Called when screen configuration changes, via RandR extension support. When RandR is not supported, then this hook will never be called.

Next: , Previous: RandR and Xinerama, Up: Top

14 Window Placement

Sawfish supports multiple ways of placing new windows on the display. There is a “current” placement mode for normal windows, and another mode for transient windows.

— Variable: place-window-mode

A symbol indicating the method of placing normal windows. This defaults to top-left.

— Variable: place-transient-mode

A symbol indicating the method of placing transient windows. This defaults to centered-on-parent.

— Function: placement-mode name

Return the placement mode object corresponding to name.

— Variable: placement-modes

List of names of all placement modes. Sawfish 1.3 ships with the following placement modes:

In all of these placement modes, the mode is responsible for taking the window object as an argument, and manipulating its position with, e.g., move-window-to.

The window to be placed avoids overlapping with already existing “avoided” windows (see Avoided Windows), unless the position is explicitly specified by coordinates, or placement mode interactively is used.

— Variable: stagger-placement-step

In stagger placement mode, the distance down and to the right from the previously placed window to the new one. This is measured in pixels.

There are two circumstances in which Sawfish will place a window: either the window has just been created, or Sawfish has begun managing the window's display. In the latter case, the window will have the placed property.

— Variable: ignore-program-positions

When t, program position size hints are not considered when placing windows.

You can define your own placement modes.

— Function: define-placement-mode name fun &keywords for-normal for-dialogs

Define a new window placement mode called name (a symbol). The function fun will be called with a single argument when a window should be placed using this mode. The single argument is the window to be placed.

If the for-normal keyword is t, then this placement mode is marked as valid for place-window-mode. The same applies to for-dialogs and place-transient-mode.

— Function: autoload-placement-mode name module-name &keywords for-normal for-dialogs

Define placement mode name (a symbol) to be loaded from structure structure-name (a symbol) when first referenced. The keyword-args are passed along to the call to define-placement-mode that creates the placement mode.

Next: , Previous: Window Placement, Up: Top

15 Popup Menus

Sawfish provides popup menus. Each line of a popup menu is either an action or the parent of a submenu. Together with key and mouse bindings, popup menus offer a command invocation method to users.

Next: , Previous: Popup Menus, Up: Popup Menus

15.1 Ready-made Popups

First let's see popup menus available out-of-box. There are root menu, window operation menu, window list menu, applications menu, and others.

The root menu is obviously the most important one. Many things can be done from the root menu, including other menus invocation. By default, you can call the root menu by middle-clicking the background screen, i.e., anywhere outside of all windows.

The window operation menu is what the name describes. You can call it from window's frames like buttons or the title bar, depending on themes.

The window list menu lets you choose a window. When selected, that window is shown, raised, and focused.

The applications menu lets you invoke softwares. Many options are available, and it's explained in the next section. (see Applications Menu)

Popup menu invocation functions can be called from keyboard or mouse.

— Function: popup-root-menu

Display the main menu.

— Function: popup-window-ops-menu

Display the window operation menu. This has several bindings by default. In particular, clicking on a window's menu button displays this menu.

— Function: popup-window-list-menu

Display the menu containing the list of all open windows.

— Function: popup-apps-menu

Popup the applications menu.

Here are popup menu options.

— Variable: menus-include-shortcuts

When true, menu items also display the key-binding. Defaults to false.

The actual creation of a popup menu is performed by an auxiliary process. By default, it stays after menu use is done, and reused at the next menu invocation.

— Variable: menu-program-stays-running

Defines if and how long the menu program stays alive after the last menu has completed. If nil, the program is terminated immediately. This means each time the popup menu is invoked, menu program is executed.

If it's t it is left running indefinitely, if an integer then the program may last for that many seconds.

You can modify menus. See Popup Definitions.

Next: , Previous: Ready-made Popups, Up: Popup Menus

15.2 Applications Menu

The applications menu lets you invoke installed applications. Sawfish generates applications menu from *.desktop files (usually found in /usr/share/applications/) at Sawfish startup.

Functions in this section are defined in the module sawfish.wm.ext.apps-menu.

Next: , Previous: Applications Menu, Up: Applications Menu

15.2.1 Applications Menu Variables

— Variable: apps-menu-autogen

If non-nil, the applications menu is automatically generated from the variable user-apps-menu and *.desktop files, and stored in the variable apps-menu. Default is t.

If you set the applications menu manually to the variable apps-menu, then it won't happen anyway.

— Variable: desktop-cat-alist

Defines categorization of applications. For example, if a *.desktop file's category has an entry “X-Desktop”, it'll be classified as “Desktop” by Sawfish default.

If another option apps-menu-associate-categories is set to nil, then the original value defined in *.desktop is respected.

If you want to customize this variable, see the file lisp/sawfish/wm/ext/apps-menu.jl for the default value.

— Variable: apps-menu-associate-categories

See the above. Default is t.

— Variable: apps-menu-filter

The filter to use while generating the apps-menu. For the details, see See Desktop File Processing.

It can be a symbol default, some, or a function.

The default filters include fdo-toplevel-filter fdo-nodisplay-filter fdo-hidden-filter fdo-onlyshowin-filter and fdo-notshowin-filter. This is the default value.

The some filter only uses fdo-notshowin-filter and fdo-onlyshowin-filter.

Or if it is set to nil, no filtering is done.

— Variable: desktop-directory

List of directories to look for *.desktop files. Default is ("/usr/share/applications").

— Variable: kde-desktop-directories

KDE specific directories where *.desktop files are stored.

— Variable: apps-menu-alphabetize

Sort the generated applications menu alphabetically. Defaults is t.

— Variable: apps-menu-lang

Human language for applications menu generation, in string, like “en” for English. Default is set from the locale.

You can prepend anything to the applications menu, by setting the variable user-apps-menu. An example definition: 

     (("_xterm" (system "xterm &"))
      ("Emacs" (system "emacs &"))
      ("Firefox" (system "firefox &"))
      ("The _GIMP" (system "gimp &"))
      () ; Seperation horizontal bar
      ) ;; Auto generated menu will follow.

The system function simply executes its single argument using /bin/sh. The underscore defines the keyboard shortcut.

If you set value to apps-menu, Sawfish doesn't generate applications menu from *.desktop files.

— Variable: apps-menu

The variable containing the definition of the applications menu. By default, Sawfish automatically sets this.

If you set this variable manually, it is exclusively used, and Sawfish doesn't generate its applications menu.

— Variable: user-apps-menu

Your own applications menu entries. In the applications menu, this is followed by auto generated applications menu.

Next: , Previous: Applications Menu Variables, Up: Applications Menu

15.2.2 Applications Menu Functions

— Function: popup-apps-menu

Display the applications menu.

— Function: update-apps-menu

Set apps-menu to user-apps-menu, and if apps-menu-autogen is non-nil, append the auto generated one.

— Function: generate-apps-menu

Return the applications menu (a list), generated from *.desktop files which can be set to apps-menu.

Here're functions to process each desktop file. See also the next section. (see Desktop File Processing)

— Function: parse-fdo-file file

Parse an *.desktop file file list. Returns (group1 (key1 . value1) ... group2 (keyA . valueA) ...)

— Function: fdo-filter-record fdo-list filter

Let filter process a desktop file entry fdo-list, and return the result.

If filter is a function, it's executed with the argument fdo-list. If it's a symbol default or some, then fdo-default-filter or fdo-some-filter is exectuted, respectively. If filter is not defined, will return the input fdo-list.

This can be useful for testing filters, and is also used internally.

Previous: Applications Menu Functions, Up: Applications Menu

15.2.3 Desktop File Processing

In this section it is shown how Sawfish processes desktop file entries while building the applications menu. Each entry passes through many filters, and they're what you may want to customize.

Desktop file entries are expressed as a list. Here is an example of emacs.desktop file before any filters are performed: 

     ("Desktop Entry"
     	   ("Name" . "Emacs Text Editor")
     	   ("Name[de]" . "Emacs Texteditor")
     	   ("GenericName" . "Text Editor")
     	   ("Comment" . "Edit text")
     	   ("Exec" . "emacs %f")
     	   ("Icon" . "emacs-icon")
     	   ("Type" . "Application")
     	   ("Terminal" . "false")
     	   ("Categories" . "Development;TextEditor;")
     	   ("StartupWMClass" . "Emacs"))

It then gets split into two lists. The original “Categories” key contains several values, and each of new entries has “Category” key which contains only one of the original categories. 

     ("Desktop Entry"
     	   ("Name" . "Emacs Text Editor")
     	   ("Name[de]" . "Emacs Texteditor")
     	   ("GenericName" . "Text Editor")
     	   ("Comment" . "Edit text")
     	   ("Exec" . "emacs %f")
     	   ("Icon" . "emacs-icon")
     	   ("Type" . "Application")
     	   ("Terminal" . "false")
     	   ("Categories" . "Development;TextEditor;")
     	   ("Cateogry" . "Development") ; Look here
     	   ("StartupWMClass" . "Emacs"))
     
     ("Desktop Entry"
     	   ("Name" . "Emacs Text Editor")
     	   ("Name[de]" . "Emacs Texteditor")
     	   ("GenericName" . "Text Editor")
     	   ("Comment" . "Edit text")
     	   ("Exec" . "emacs %f")
     	   ("Icon" . "emacs-icon")
     	   ("Type" . "Application")
     	   ("Terminal" . "false")
     	   ("Categories" . "Development;TextEditor;")
     	   ("Cateogry" . "TextEditor") ; Look here
     	   ("StartupWMClass" . "Emacs"))

This is the entry list format that is used in all of the later filters. All filtering functions should accept such an entry list as its argument, and all filtering functions should either return nil or an entry list. If fdo-associate-categories is t then the “Category” key will be changed to the main category that will eventually show up in the apps-menu. The keys that are used by the applications menu are currently,

Filters

Filters are functions, either pre-defined or user-defined, which take one argument, a desktop file entry. You can set your filter to the apps-menu-filter variable.

Here we show an example user-defined filter, and all pre-defined filters, which are also available to user codes. 

     ;; This will move emacs to the ``util'' category, in addition to the
     ;; operations done by default filter.
     (setq apps-menu-filter
           (lambda (ent)
     	(let ((ent (fdo-default-filter ent)))
     	  (when ent
     	    (cond ((string-match "[Ee]macs" (cdr (assoc "Name" ent)) nil t)
     		   (rplacd (assoc "Category" ent) "util")))
     	    ent))))

The pre-defined filters: 

     (define (fdo-nodisplay-filter fdol)
       "Return the desktop-file-list if NoDisplay is False, or if NoDisplay is
     not present in the desktop-file-list"
       (if (assoc "NoDisplay" fdol)
           ;; [Ff] means match to "false"
           (if (string-match "[Ff]" (cdr (assoc "NoDisplay" fdol)))
           	  fdol)
         fdol))
     
     (define (fdo-hidden-filter fdol)
       "Return the desktop-file-list if Hidden is False, or if Hidden is
     not present in the desktop-file-list"
       (if (assoc "Hidden" fdol)
           (if (string-match "[Ff]" (string-downcase (cdr (assoc "OnlyShowIn" fdol))))
     	  fdol)
         fdol))
     
     (define (fdo-onlyshowin-filter fdol)
       "Return the desktop-file-list if OnlyShowIn matches `desktop-environment',
     or if OnlyShowIn is not present in the desktop-file-list"
       (if (assoc "OnlyShowIn" fdol)
           (if (string-match desktop-environment (string-downcase (cdr (assoc "OnlyShowIn" fdol))))
     	  fdol)
         fdol))
     
     (define (fdo-notshowin-filter fdol)
       "Return the desktop-file-list if NotShowIn does not match `desktop-environment',
     or if NotShowIn is not present in the desktop-file-list"
       (if (assoc "NotShowIn" fdol)
           (if (not (string-match desktop-environment (string-downcase (cdr (assoc "NotShowIn" fdol)))))
     	  fdol)
         fdol))
     
     (define (fdo-associate-categories-filter fdol)
       "If `apps-menu-associate-categories' is true, filter the
     desktop-entry through `fdo-associate-categories'."
       (when fdol
         (if apps-menu-associate-categories
     	(associate-categories fdol)
           fdol)))
     
     (define (fdo-toplevel-filter fdol)
       "Return the desktop-file-list if the `Category' is of the
     Top-Level variety."
       (when fdol
         (if (not (equal "Top-Level" (cdr (assoc "Category" fdol))))
     	fdol)))
     
     (define (fdo-default-filter fdol)
       "The default fdo-filter, combines the above."
       (fdo-toplevel-filter
        (fdo-hidden-filter
         (fdo-notshowin-filter
          (fdo-onlyshowin-filter
           (fdo-nodisplay-filter fdol))))))
     
     (setq apps-menu-filter fdo-default-filter)

Previous: Applications Menu, Up: Popup Menus

15.3 Popup Definitions

Sawfish comes with ready-made popup menus. This section describes how you can modify them.

An entire popup menu is specified by a list. Each element corresponds to a menu item, in the displayed order from top to bottom. Example: 

     (("Item _1" command-1)   ;; list for a command.
      ("Item _2" . submenu-2) ;; cons for a submenu.
      ()                      ;; nil makes a seperator line
      ("_xterm" (system "xterm &")) ;; lisp expression is possible too.

Each menu item is typically specified by a list with two elements. The first is the name; it's a string, and displayed in the menu. An underscore (_) before a character defines an accelerator, or a shortcut key.

The second element specifies the action to take. Possible choices are:

Command
If it's a command name (a symbol), then that command is invoked. In the window operation menu, if that command takes a window as the argument, it's passed.
Lisp expression
If it's a lisp expression, then it's evaluated inside of the user module.
Function
If it's a function (a closure or a subr), then it's invoked with no argument.

If an item is nil (instead of a list with two elements), then it's printed as a seperator line.

An item can invoke a submenu. In this case, the item is a cons. The car is the printed name. The cdr is a symbol which is the name of a variable. That variable specifies another menu's contents. Or the variable refers to a function, it's invoked, and the return value is used. Notice that this variable has to be special, or dynamically scoped, so that its value can be seen inside of the involved module.

It's possible to pass a list with more than two elements as an item, but it is not explained. (Read the code and please tell us the usage.)

Let's see one more example: 

     (("Workspaces" . workspace-menu)
      ("Windows" . window-menu)
      ("Programs" . apps-menu)
      ("Customize" . custom-menu)
      ("About..." (customize 'about))
      () ; Separation horizontal bar.
      ("Restart" restart)
      ("Quit" quit))

This is the old definition of Sawfish's root menu. We can see that four submenus are created by seeing the value of variables. They contain functions, and they're invoked.

— Function: popup-menu spec

Displays a menu defined by the list of item definitions spec.

— Variable: root-menu

Contains the root menu definition.

— Variable: window-ops-menu

The variable containing the definition of all window operations.

Popup menu is made by making a seperate process.

— Variable: menu-program

Location of the program implementing Sawfish's menu interface.

Mainly for developers, one more esoteric thing, “toggle menu”, is explained.

— Variable: window-ops-toggle-menu

The toggle type submenu of window operations, like “sticky” or “shaded”. By selecting items in this menu, a user can turn the flags on and off for a given window.

— Function: add-window-menu-toggle label command #!optional predicate

Add an item to window-ops-toggle-menu. The command is a function (or a symbol pointing to a function) that gets run when the menu item is selected.

If predicate is non-nil, it must be a function taking a window as argument. If predicate return true, the menu item will have a check mark next to it.

Next: , Previous: Popup Menus, Up: Top

16 Events

Lisp “event” object is a representation of input, regardless of actual or expected. If it's a keypress for example, it tells which key with which modifiers are pressed, and that's all. Please do not confuse it with X or other's event which is generated only after keypress or other “event”.

Each X input event induced by the mouse or the keyboard has a Lisp representation. X input events that Sawfish receives are either for the root window, the window frames it creates, or grabbed from the client windows themselves.

Sawfish can respond to X events other than input, most often via hooks. (see Standard Hooks)

— Function: eventp object

This function returns t if its argument is an event.

Next: , Previous: Events, Up: Events

16.1 Event Name Representation

Each event has a string representation, called its “name”. Names consist of zero or more modifiers, followed by a key or mouse action indicator. Modifiers are separated from succeeding elements by hyphens ‘-’. For example, hitting <x> while holding down the <Control> and <Meta> keys would generate an event named <Control-Meta-x>. This notation is designed to closely match Emacs Lisp's notation.

Functions are available to convert between the name of an event and the event object itself, and vice versa.

— Function: lookup-event event-name

Create and return a new input event whose name is event-name. 

          (lookup-event "C-x")
              ⇒ (120 . 65540) ;; Internally, event is a pair of integers.
          
          (lookup-event "C-M-Button1-Click1")
              ⇒ (1 . 131340)
— Function: event-name event

This function returns a string naming the input event event. 

          (event-name (lookup-event "C-x"))
              ⇒ "C-x"

Next: , Previous: Event Name Representation, Up: Events

16.2 Event Modifiers

Sawfish event modifiers are copied directly from the standard X modifiers:

The standard X modifier names are provided, as well as four special modifiers <Meta>, <Alt> <Hyper> and <Super> that are mapped to the keysyms of the same name.

The following table lists the possible modifier prefixes:

<Control>
<C>
The control modifier
<Meta>
<M>
The meta modifier
<Alt>
<A>
The alt modifier
<Shift>
<S>
The shift modifier
<Hyper>
<H>
The hyper modifier
<Super>
<s>
The super modifier; note that this is a lowercase s, in order to distiguish from shift
<Modk>
The standard X modifiers, for k between 1 and 5
<Any>
A special modifier that matches any set of modifiers in events, including no modifier. See Event Matching.
<Release>
A special modifier that matches key release events, not the default key press events. Mouse events never have <Release> modifiers; they have separate actions instead. See Event Actions.

You have to set the variable eval-key-release-events to non-nil to use this modifier.

<Buttonk>
The k'th mouse button is currently pressed.
<W>
A placeholder “window manager” modifier that can be bound to a real modifier on the fly. See wm-modifier below.

The default Sawfish bindings use the <Meta> modifier. For convenience, if no X keysym generates <Meta>, Sawfish will treat the first defined modifier of <Alt>, <Hyper> and <Super> (in that order) as <Meta>. The mapping from keysyms to modifiers is exposed in the following variables:

— Variable: meta-keysyms

A list defining the names of the X keysyms generating the virtual ‘Meta’ or ‘M’ modifier.

— Variable: alt-keysyms

A list defining the names of the X keysyms generating the virtual ‘Alt’ or ‘A’ modifier.

— Variable: hyper-keysyms

A list defining the names of the X keysyms generating the virtual ‘Hyper’ or ‘H’ modifier.

— Variable: super-keysyms

A list defining the names of the X keysyms generating the virtual ‘Super’ modifier.

There are two functions to manipulate the placeholder “window manager” (<W>) modifier. Unfortunately, these are low-level functions that operate on integer encodings.

— Function: wm-modifier

Return the current value (an integer) of the placeholder “window manager” (<W>) modifier.

— Customizable: wm-modifier-value

An integer encoding zero or more modifier keys that form the placeholder “window manager” (<W>) modifier. Setting this value through the customization UI automatically calls set-wm-modifier.

— Function: set-wm-modifier modifiers

Set the value of the placeholder “window manager” (<W>) modifier to modifiers (an integer).

Next: , Previous: Event Modifiers, Up: Events

16.3 Event Actions

Sawfish recognizes keyboard actions and mouse actions.

Key Press
Key Release
Keys pressed on the keyboard generate one or more key press events, followed by a key release event. Bindings normally recognize key press events only. To recognize key releases, add a <Release> modifier to the bound event.

Generally keys have the same names as their X keysyms. The following unusual names are worth listing: ‘SPC’, ‘TAB’, ‘RET’, ‘ESC’, ‘BS’, ‘DEL’, ‘Up’, ‘Down’, ‘Left’, ‘Right’.

For example, pressing the <Delete> key while <Control> is held down generates a Control-DEL event, while releasing the <a> key while <Hyper> is held down generates a H-Release-a event.

Button Clicks
Button presses generate <Click> actions. If Sawfish receives several clicks in close succession (less than multi-click-delay milliseconds between clicks), the second and third events are <Click2> and <Click3>, respectively. Any further clicks are simple <Click> events. For consistency, <Click1> is a synonym for <Click>.
Button Releases
Once the button has been released from a <ClickN> action, Sawfish receives a corresponding <OffN> action. The actions <Off> and <Off1> are synonyms.
Pointer Motion
Pointer motion generates <Move> actions. The action does not indicate anything about the pointer position; use e.g., query-last-pointer to find that information.

For example, a single click of the left mouse button with the <Meta> key held would be described as M-Button1-Click1. After triple-clicking with the <Alt> key held down, Sawfish will receive a Alt-Off3 event.

— Variable: multi-click-delay

An integer indicating the maximum number of milliseconds between successive clicks. Defaults to 250 milliseconds at startup; if nil, Sawfish uses 250 milliseconds.

Next: , Previous: Event Actions, Up: Events

16.4 Event Matching

There is a special function that matches event objects. If the actions of two event objects are not identical, the events do not match. If they are identical, then the events match if the modifiers are identical, or if one of the modifiers is <Any>. See Event Modifiers.

— Function: event-match ev1 ev2

Returns t if events ev1 and ev2 match, nil otherwise.

Previous: Event Matching, Up: Events

16.5 Synthetic Events

It is possible to create an event inside Sawfish that mimics a real keyboard or mouse event.

— Function: synthesize-event event window #!optional propagate

Generate a synthetic key press or button press and send it to the X window bound to the window object. Pass the symbol root for the root window. This press is automatically followed by the appropriate release event.

The current pointer position becomes the position of the event.

Event is either an event object, or the string representation of an event (such as "A-f" or "C-M-Button3-Click2"). Strings are parsed into event objects before any work is done. See Event Name Representation.

If propagate is true, the event will propagate up the window ancestor chain until it is handled.

Next: , Previous: Events, Up: Top

17 Commands

A command is roughly speaking a lisp function which can be called from key or mouse input. But it may be preferable for example to pass the currently focused window as the argument, and such mechanism is prepared. So Sawfish distinguishes the notion of commands from functions.

Formally stated, a command is an association of the name to a function, and a way to pass the arguments, and so on.

The name space of commands are independent of that of bindings (which includes functions.)

— Variable: customize-command-classes

In configurator "binding" section, show commands of these classes. It is a list. Possible keys are default, advanced, viewport, and deprecated.

The default value is (default).

Next: , Up: Commands

17.1 Command Definition

— Function: define-command name fun #!key spec type doc class

Define a command called name (a symbol). The function fun will be called to execute the command.

spec defines how the arguments are passed by the interactive call of the command. See Interactive Calling Specification.

doc is the documentation string associated with the command. If it's lacking, that of the function fun will be looked up.

Other arguments are mostly for internal use.

type specifies arguments, too. These arguments are statically set in “Bindings” section of the configurator. If type is set, then a lisp expression like (command-name arg1 arg2...) is bound to the key, in contrast to the usual case where command name is bound. (The precise doc is lacking.)

class is a symbol which annotates the command, for example advanced. Users can choose which commands are shown in the configurator according to class. See the documetation of customize-command-classes (see Commands.)

— Function: define-command-to-screen name fun #!key spec type doc class

As define-command, but any printed output of fun is sent to the screen, i.e. standard-output is redirected.

— Function: autoload-command name module #!key spec type doc class

Record that loading the module called module (a symbol) will provde a command called name.

The keyword values have the same meanings as for define-command. Defining those properties as part of the autoload provides useful feedback to the user without having to do loading.

Next: , Previous: Command Definition, Up: Commands

17.2 Old-style Command Definition

GNU Emacs-like command definition is a deprecated, old-syntax, but still supported. There command definition is included in function definition. The first form in the function body must be an interactive declaration which marks that the function may be called interactively and tells the call-command function how to compute the argument values to apply to the command.

The interactive declaration looks like a call to the special form interactive, in actual fact this special form always returns nil and has no side-effects. The only effect of this form is to show the call-command function that the function definition may be called interactively. The second element of the declaration form (after the interactive symbol) defines how the argument values applied to the command are computed.

The structure of an interactive declaration, then, is: 

     (interactive [calling-spec])

When a command is defined this is how it includes the interactive declaration: 

     (defun some-command (arg1)
       "Optional documentation string."
       (interactive ...)
       ...

The calling-spec is defined in See Interactive Calling Specification.

Next: , Previous: Old-style Command Definition, Up: Commands

17.3 Interactive Calling Specification

The spec argument to interactive or define-command defines the argument values applied to the command when it is called interactively. It may be one of:

nil or undefined
No arguments are given to the command.
A string
It consists of zero or more lines (each separated by a newline character). Each line defines how to compute one argument value. The first one or two characters of each line is a prefix defining exactly how to compute the argument, the rest of the line is an optional argument which some prefixes may use. See below for a list of prefixes. A null line produces an argument value of nil.
Anything else
The form is evaluated and expected to return a list of arguments to apply to the command.

The currently available prefixes are,

‘e’
The event which caused this command to be invoked.
‘E’
The event which caused this command, cooked into a string.
‘p’
The prefix argument as a number, this will be 1 if no prefix argument has been entered.
‘P’
The raw prefix argument.
‘t’
The symbol t.
‘%f’
The window which currently has the input focus, or nil if no window is focused.
‘%w’
The result of calling the current-event-window function.
‘%W’
The result of calling the current-event-window function, or if this returns nil or root, the currently focused window.

Next: , Previous: Interactive Calling Specification, Up: Commands

17.4 Operations on Commands

We can extract certain information about commands.

— Function: commandp symbol

Returns t if symbol is a command name.

— Function: command-documentation name

Return the documentation for the command name. It returns the first documentation found by looking at (in order): the documentation property of the command; the doc file entry associated with the doc key property; or the documentation for the function with the same name.

— Function: command-spec name
— Function: command-type name
— Function: command-class name

Return the specification, type or class (respectively) of the named command.

— Function: report-commands #!optional type all

Returns the list of commands. Each element is the symbol of a command name, and they're sorted alphabetically.

The optional argument type is for internal use. when it's non-nil, (command-name #:type type-param) is returned for commands with “type”, instead of a symbol.

If the optional argument all is nil, returns commands only user wants, i.e. those specified by customize-command-class are included. Else, all commands are returned.

Previous: Operations on Commands, Up: Commands

17.5 Invoking Commands

When a command is to be invoked, the call-command function is used. This builds a list of argument values to apply to the command (using its interactive declaration) then calls the command.

— Function: call-command command #!optional prefix-arg

This function calls the command command interactively. See the documentation of commandp above for what constitutes a command.

If the prefix-argument is non-nil it defines the value of the current-prefix-arg variable for this command, normally the value of this variable would be taken from the global prefix-arg variable.

There is a corresponding call-command command that prompts for a command to execute.

— Function: apply-command name &rest args

Call the function underlying the command name, passing in args as the arguments. This is useful for calling a command in a non-interactive context.

— Variable: current-prefix-arg

When invoking an interactive command, this is set to the current prefix argument.

— Variable: this-command

The command currently being called. The value is only set during command call, and nil anytime else.

— Variable: last-command

The command previously called, or ‘nil’ if there is no such command.

See Command Hooks, for hooks run before and after commands.

Next: , Previous: Commands, Up: Top

18 Keymaps

Keymaps are used to associate events with commands. When an event occurs, the associated command is found and evaluated. A keymap is simply a list whose first element is the symbol keymap.

— Function: keymapp arg

Returns t if arg may be used as a keymap.

— Function: make-keymap

Returns a newly-created empty keymap.

— Function: bind-keys keymap &rest bindings

Installs zero or more key bindings into the keymap keymap, then returns keymap.

Each binding is defined by two elements in the list of bindings, the first defines the name of an event (or the event itself) and the second defines the command to be associated with the event.

For example to bind two keys in the keymap keymap; the event C-f to the command foo and the event C-b to the command bar the following form would be used, 

          (bind-keys keymap
           "C-f" 'foo
           "C-b" 'bar)

Currently, multiple keystrokes can't be bound with a single bind-keys call. Instead, bind an event to another keymap.

— Function: unbind-keys keymap &rest keys

Removes the bindings of the events keys (these may be the names of the events or the event objects themselves) from the keymap keymap.

Functions bind-keys and unbind-keys do not affect the bindings of existing windows, because keymaps are set on a window when the window is created and begins to be managed by Sawfish. Update can be done by following functions.

— Function: grab-keymap keymap
— Function: ungrab-keymap keymap

All bindings stored in keymap get into / out of effect of all windows, including root, but not of frame parts.

Notice that ungrab-keymap has to be called BEFORE you change the keymap.

If the window foo has its own keymap rather than window-keymap, then it is not affected by (grab-keymap window-keymap).

— Function: search-keymap event keymap

Search for a binding of the event event in keymap. If a binding is found a cons cell (command . event) is returned.

There are several pre-defined keymaps that are always available:

global-keymap
Keymap containing bindings active anywhere.
window-keymap
Keymap containing bindings active when a client window is focused.
root-window-keymap
Keymap containing bindings active when the pointer is in the root window.
title-keymap
border-keymap
Keymaps active in the title and borders of window frames.
close-button-keymap
iconify-button-keymap
maximize-button-keymap
menu-button-keymap
shade-button-keymap
sticky-button-keymap
lock-button-keymap
rename-button-keymap
move-resize-button-keymap
raise-lower-button-keymap
Keymaps active in the standard window frame buttons.
override-keymap
Must be a keymap, a symbol, or nil. If it is a keymap, this becomes the keymap in which all lookups occur (overriding the window, root and global keymaps). If it is a symbol, Sawfish finds the symbol's value and tries again. If it is nil, Sawfish behaves normally.

Next: , Previous: Keymaps, Up: Top

19 Event Loop

The event loop reads all X events received on any of the windows that Sawfish is aware off. Many of these events invoke hooks, as described in Standard Hooks. Keyboard and pointer events are translated to their Lisp equivalents (see Events) and then used to scan all active keymaps for a binding. If a binding is found, the associated command is invoked through the call-command function.

The active keymaps are determined as follows:

Note that for ButtonRelease events, the frame part's keymap is only searched if the pointer is actually within the frame part when the release event occurs.

If no binding may be found in any of the active keymaps, then the unbound-key-hook hook is called. This is an or type hook—the first function that returns non-nil will terminate the hook call.

— Function: lookup-event-binding event

Perform the usual binding lookup for the event object object. Returns the command found, or nil if no binding exists.

By default, both key-release events, and events that are bound to modifier keys (e.g. <Control_L>), are ignored. However, this behavior may be changed:

— Variable: eval-modifier-events

When non-nil, key events bound to modifier keys are evaluated.

— Variable: eval-key-release-events

When non-nil, key-release events are evaluated.

While a command is being evaluated, information about the event that caused it may be found:

— Function: current-event

Return the event which caused the current command to be invoked

— Function: current-event-string

Returns the string which the current event would usually insert.

— Function: current-event-window #!optional win

Extract the owning window of the current X event (this is a window object, or the symbol root for the root window, or nil if there is no window or no event). This is stored internally as the current event window, and returned.

If the optional argument win is a window, then it will be returned as the current event window.

— Function: last-event

Return the previous event which occurred.

— Function: proxy-current-event window #!optional mask propagate

Send the current X event to window, either a window object, a numeric window id, or the symbol root. If a ButtonPress event the pointer grab will be released first.

Mask may be an integer defining the X event mask to pass to the XSendEvent function. If not defined, a mask is chosen that would usually be used to select the type of event being proxied.

Propagate is a flag (nil/non-nil) passed directly to an underlying XSendEvent call. (And if someone would like to explain what that means, please do so ...

— Function: allow-events mode

This is a wrapper for the XAllowEvents function. The mode parameter may be one of the following symbols: async-pointer, async-keyboard, sync-pointer, sync-keyboard, replay-pointer, replay-keyboard, async-both, sync-both.

Events that have to be grabbed to be received (i.e. all bindings in the global-keymap and the window-keymap) are grabbed synchronously. This means that no more events will be received until either the command returns, or allow-events is called.

This is normally not important, but if the command expects to receive further events it must call allow-events. See the interactive move and resize functions for an example.

— Function: forget-button-press

Cause the next button press to be treated as a single click event, no matter how soon it occurs after the prevous button-press event.

— Function: accept-x-input #!optional mask

Handle any X events received. If mask is non-nil then only events matching this numeric value are handled (see the X header files for details).

— Function: x-events-queued

Returns the number of X events waiting to be handled.

Next: , Previous: Event Loop, Up: Top

20 Miscellaneous Functions

Next: , Up: Miscellaneous Functions

20.1 Pointer Functions

— Function: query-pointer #!optional from-server

Returns a cons cell (x . y) representing the current mouse pointer position, relative to the origin of the root window.

If there is a mouse update current event, the position is read directly from that event. Otherwise it is read from the server. If from-server is non-nil then the position is read directly from the server in any case.

— Function: query-pointer-window

Returns the top-level window under the mouse pointer, or nil if the cursor is in the root window.

— Function: query-last-pointer

Returns a cons cell (x . y) representing the second most recent mouse pointer position, relative to the root window.

— Function: query-button-press-pointer

Returns (mouse-x . mouse-y) representing the mouse position relative to the root window at the last button-press event.

Use this function to track the displacement of the pointer during a drag.

— Function: query-button-press-window

Returns the window that the mouse was in when the button was pressed.

— Function: warp-cursor x y

Move the mouse pointer to position (x, y) relative to the origin of the root window.

— Function: warp-cursor-to-window window #!optional x y

Move the mouse pointer to position (x, y) relative to the client window associated with object window.

If x and y are nil, then they are taken as the top-left corner of the window's frame.

If warp-to-window-enabled is nil, this function does nothing.

— Variable: warp-to-window-offset

Offset (%) from window edges when warping pointer. A negative number means outside the left window edge.

— Variable: warp-to-window-enabled

When false, disable warping the cursor to windows.

— Variable: pointer-motion-threshold

If set to an integer value, a pointer must move by this many pixels on either axis before Sawfish considers it to have moved. If the pointer has not moved by this amount, Sawfish will ignore MotionNotify events from X. The variable defaults to 2 pixels. If not an integer, Sawfish assumes a threshold of 0 pixels.

Sawfish provides functions to move the pointer relative to the current positions. They're named “move-cursor”, and defined in sawfish.wm.commands.move-cursor.

— Function: move-cursor right down

Move the cursor right pixels to the right across the screen, and down pixels down the screen. The cursor stops at the edge of the screen (although in multi-head environments, this may not be at the edge of the display).

There are also more specialized cursor movement functions. All of them are commands, too.

— Function: move-cursor-left-fine
— Function: move-cursor-right-fine
— Function: move-cursor-up-fine
— Function: move-cursor-down-fine
— Function: move-cursor-northwest-fine
— Function: move-cursor-northeast-fine
— Function: move-cursor-southwest-fine
— Function: move-cursor-southeast-fine

Move the cursor 1 pixel in the indicated direction.

— Function: move-cursor-left
— Function: move-cursor-right
— Function: move-cursor-up
— Function: move-cursor-down
— Function: move-cursor-northwest
— Function: move-cursor-northeast
— Function: move-cursor-southwest
— Function: move-cursor-southeast

Move the cursor move-cursor-increment pixels in the indicated direction. move-cursor-northeast is equal to the northward move cobmined with the eastward.

— Function: move-cursor-center

Move the cursor to the center of the screen.

— Variable: move-cursor-increment 16

The move-cursor-DIRECTION functions move this cursor this many pixels at a time.

Next: , Previous: Pointer Functions, Up: Miscellaneous Functions

20.2 Grab Functions

— Function: grab-server

Prevent any other clients from accessing the X server.

— Function: ungrab-server

After a call to grab-server this will allow other clients to access the X server again.

Note that calls to grab-server and ungrab-server nest.

— Macro: with-server-grabbed &rest forms

Evaluate forms with the server grabbed. Releases the grab afterwards.

— Function: call-with-server-ungrabbed thunk

Return the result of calling the zero-parameter function thunk. If the server is currently grabbed, ungrab it first, restoring the original grab status after the call to thunk returns.

— Function: server-grabbed-p

Returns t if the X server is currently grabbed.

— Function: grab-pointer #!optional window cursor ptr-sync kbd-sync confine-to

Grab the mouse pointer and direct all pointer events to window object window. If cursor is defined and a cursor object, display this while the pointer is grabbed.

If window is a window object corresponding to a visible window, the grab will be made on its frame.

If window is an integer, it specifies the window ID of the grab window.

Otherwise the grab will be made on the root window. This includes window corresponding to a non-viewable window.

Confine-to, if non-nil, is a visible window to confine the pointer to. It is interpreted similarly to the rules for window, except that the “otherwise” case is to not confine the pointer.

If the window id of a non-viewable window was specified for either window of confine-to, the grab will be made on the root window without confining the pointer.

If ptr-sync or kbd-sync is non-nil, the pointer or keyboard will be frozen, i.e., the device will not produce events until either the grab is released or events are re-enabled using allow-events.

Returns non-nil if the grab succeeded.

— Function: ungrab-pointer

Release the grab on the mouse pointer.

— Function: grab-keyboard #!optional window ptr-sync kbd-sync

Grab the keyboard and direct all keyboard events to window object window.

If window is a window object corresponding to a visible window, the grab will be made on its frame.

If window is an integer, it specifies the window ID of the grab window.

Otherwise the grab will be made on the root window. This includes window corresponding to a non-viewable window.

If ptr-sync or kbd-sync is non-nil, the pointer or keyboard will be frozen, i.e., the device will not produce events until either the grab is released or events are re-enabled using allow-events.

Returns non-nil if the grab succeeded.

— Function: ungrab-keyboard

Release the grab on the keyboard.

— Function: call-with-keyboard-grabbed thunk

Call the zero-parameter function thunk with the keyboard grabbed. If unable to grab the keyboard then thunk won't be called.

Next: , Previous: Grab Functions, Up: Miscellaneous Functions

20.3 Display Functions

— Function: screen-width

Return the width of the root window.

— Function: screen-height

Return the height of the root window.

— Function: screen-dimensions

Return the screen dimensions in pixels as a cons cell (width . height).

— Function: draw-window-outline mode x y width height

Draw an outline of a window of dimensions (width, height) at position (x, y) relative to the root window.

mode is a symbol defining the type of outline drawn, currently it may only be box for a 3x3 grid.

Use the erase-window-outline to erase the grid. Also note that since these functions draw directly on the root window the server should be grabbed until the outline is erased.

— Function: erase-window-outline mode x y width height

Erase a previously drawn outline of a window of dimensions (width, height) at position (x, y) relative to the root window.

mode is a symbol defining the type of outline drawn, currently it may only be box for a 3x3 grid.

— Function: display-message #!optional text attributes

Display the string text in a window on the screen. If text is nil then any string previously displayed is removed. Returns the numeric id of the window displaying the message, or nil if no message is displayed.

The window is placed on top of X client windows, and basically at the center of the screen. The window remains until another call of this function, or the user clicks on it.

attributes is an alist specifying how the string should be displayed; each element of the list is a cons cell (attr . value) associating an attribute attr (a symbol) with it's value.

Possible attributes currently include:

font
The font to use
foreground
The color (or color name) to draw the text with
background
The color (or color name) to draw the background with
x-justify
The justification method for multi-line strings. One of the symbols left, right, or center
spacing
The number of extra pixels of vertical spacing to leave between text lines.
position
A cons cell defining the coordinates at which to display the message window. The cell is (x . y). x and y are integers or nil (for centered display). If negative they count in from the left and bottom edges respectively.
head
The head on which to center the message when a position is not specified or given as nil. If not provided defaults to the head containing the window that has the input focus.

Tip: Don't call this function during initialization. Instead, use after-initialization-hook to defer. Otherwise the message window is covered by X client windows.

Next: , Previous: Display Functions, Up: Miscellaneous Functions

20.4 Rectangle Functions

Rectangles define a region of the display. A rectangle is a list of values: (left top right bottom [weight]). left and top are the x and y coordinates of the upper left corner, right and bottom are the coordinates for the lower right corner. weight is an integer. The bulk of the rectangle management functions are in sawfish.wm.util.rects.

— Function: rect-left rect

The x-axis value of the left side of the rectangle. Equivalent to car

— Function: rect-top rect

The y-axis value of the top of the rectangle. Equivalent to cadr

— Function: rect-right rect

The x-axis value of the right side of the rectangle. Equivalent to caddr

— Function: rect-bottom rect

The y-axis value of the bottom of the rectangle. Equivalent to cadddr

— Function: rect-obscured r by

Check whether the rectangle r is wholly or partially contained in rectangle by. Returns one of the symbols unobscured, partially-obscured, or fully-obscured.

— Function: rect-minus r s #!optional tail

Return a list of rectangles whose union is the part of rectangle r not contained in rectangle s. If tail is given, the result is prepended to it.

— Function: rectangles-from-grid x-points y-poinst #!optional pred

The two lists of integers x-points and y-points define a rectangular grid. Return the complete list of rectangles formed by the intersections of the grid.

If pred is defined it is called for each rectangle and only those for which it returns t are added to the returned list.

Assumes that x-points and y-points are both sorted smallest->largest.

— Function: rectangles-from-windows windows #!optional weight-fun

Returns a list of rectangle objects representing the list of window objects windows.

If weight-fun is defined, it is a function to call on each window to return the weight for that window. If not defined, the window's weight property is used instead.

— Function: grid-from-rectangles rects #!optional with-root

Given a list of rectangles rects return a cons cell (x-points . y-points) defining the grid they represent.

If with-root is non-nil, then add the root window boundaries to the grid.

— Function: rectangle-area rect

Returns the area of the specified rectangle.

— Function: rectangle-from-coords point dims

Return the rectangle object with origin point and dimensions dims.

— Function: rectangle-corners

Return a list of four cons cells representing the coordinates of the corners of the rectangle rect.

— Function: rectangle-center rect

Returns a cons cell of the (approximate, to the nearest integer) coordinates of the center of the rectangle rect.

— Function: rectangle-center* point dims

The same as rectangle-center except that the rectangle is specified via the x,y coordinates point and the dimensions dims.

— Function: rectangle-union rect1 rect2

Gives the smallest rectangle containing both rect1 and rect2. The weight of the resulting rectangle is the weight of rect1.

— Function: rectangle-intersection rect1 rect2

Gives the intersection of the two rectangles rect1 and rect2. The weigth of the resultant rectangle is the weight of rect1. Returns nil if there the two rectangles do not intersect.

— Function: rect-1d-overlap a-1 a-2 b-1 b-2

a-1 to a-2 indicates one line segment and b-1 to b-2 indicates another. Returns the overlap between the two line segments.

— Function: rect-2d-overlap dims point rect

Returns the overlap between two rectangles, one with dimensions dims and upper-left corner at point; the other is defined by rect.

— Function: rect-2d-overlap* rect1 rect2

Like rect-2d-overlap, except that the rectangles are rect1 and rect2.

— Function: rect-total-overlap dims point rects

Returns the total area of the overlap between a rectangle defined by dims and point, and the list of rectangles rects when placed at point.

— Function: rect-wholly-within-rect outer inner

Returns t if inner is completely within the boundaries of outer.

— Function: rect-wholly-visible-p

Returns t if rect is completely inside the screen boundaries.

— Function: rectangle-heads

Returns the number of screen heads that the rectangle rect appears on.

These functions are found in sawfish.wm.viewport:

— Function: rect-within-viewport-p rect #!optional viewport

Return t if rect is entirely inside the screen boundaries for some viewport, regardless of whether it is the current viewport, or even if the viewport currently exists. If viewport is specified check only against that viewport.

— Function: rect-within-head-p rect #!optional head

Return t if rect is entirely within some head on some viewport. If head is provided rect must be within that head on some viewport.

Next: , Previous: Rectangle Functions, Up: Miscellaneous Functions

20.5 Gradient Functions

The gradient feature allows color gradients to be drawn in images. Import gradient or sawfish.wm.util.gradient to use this feature.

— Function: draw-vertical-gradient image from to

Draw a vertical color gradient in image. The color at the top of the image will be from, the color at the bottom to, with a smooth transition between.

— Function: draw-horizontal-gradient image from to

Draw a horizontal color gradient in image, from left to right. The color at the left of the image will be from, the color at the right to, with a smooth transition between.

— Function: draw-diagonal-gradient image from to

Draw a horizontal color gradient in image, from the top-left corner to the bottom-right. The color at the top-left of the image will be from, the color at the bottom-right to, with a smooth transition between.

Next: , Previous: Gradient Functions, Up: Miscellaneous Functions

20.6 Sawfish Invocation Functions

— Variable: sawfish-version

The version number of the running Sawfish.

— Variable: sawfish-directory

The home directory for Sawfish files. For example: "/usr/share/sawfish". You can override it with the environment variable SAWFISHDIR.

— Variable: sawfish-exec-directory

The directory for architechture-specific Sawfish executables. For example: "/usr/lib/sawfish/1.3/i386-pc-linux-gnu". You can override it with the environment variable SAWFISHEXECDIR.

— Variable: sawfish-lisp-lib-directory

The top-level directory for Sawfish lisp files. For example: "/usr/share/sawfish/1.3/lisp". You can override it with the environment variable SAWFISHLISPDIR.

— Variable: sawfish-locale-directory

The system directory where Sawfish can find locale files. This is not part of the Sawfish distribution. For example: "/usr/share/locale".

— Variable: sawfish-site-lisp-directory

The top-level directory for site-specific Sawfish lisp files. For example: "/usr/share/sawfish/site-lisp". You can override it with the environment variable SAWFISHSITELISPDIR.

— Variable: sawfish-user-lisp-directory

The list of user's sawfish lisp directories. The default value is ($HOME/.sawfish/lisp). It is prepended to load-path, so that files under these directories are searched prior to sawfish-lisp-lib-directory.

You can override the value with environment variable SAWFISH_USER_LISP_DIR. Paths are seperated by colon, like the PATH environmental variable. Example: ~/.sawfish/lisp-test:~/.sawfish/lisp.

— Function: quit
— Function: restart

Quits and restart Sawfish.

Restart does exec (3), replacing the current process. All command line arguments are used again, except that session management related ones are updated.

There also exist same name commands.

— Function: exit-type

If Sawfish is shutting down, this function returns one of the strings "user-quit", "user-restart" or "session-quit". If Sawfish is not shutting down, it returns nil.

— Function: poweroff action

A function for rebooting, halting, suspending and hibernating your machine. Normally this is only used when running outside of GNOME or KDE; they provied their own versions of functions.

action is a symbol, and each invokes the shell command defined by the variable as follows:

action variable
reboot reboot-command
halt halt-command
suspend suspend-command
hibernate hibernate-command

When action is reboot or halt, before-exit-hook is called, and delete-windows is applied to each window to ensure we safely quit the current session.

— Variable: want-poweroff-menu

If you don't use GNOME, KDE, nor XFCE, power off related actions are added under the root menu -> “Sessions”.

Previous: Sawfish Invocation Functions, Up: Miscellaneous Functions

20.7 Other Functions

— Function: sync-server

Flush all pending X requests, don't wait for them to finish.

— Function: send-client-message window type data format

Send an X ClientMessage event to window (a window object, the symbol root or a numeric xid).

The event will be of the type type (a symbol), contain the array of integers data (i.e. a vector or a string), and will be transferred as format sized quantities (8, 16 or 32).

— Function: create-window parent x y width height

Create an unmapped window that is a child of parent (a window object, an integer window id, or the symbol root), with the specified dimensions.

Returns the window id of the new window.

— Function: x-atom symbol

Return the integer identifying the X atom with the same name as symbol.

— Function: x-atom-name integer

Return the symbol with the same name as the X atom identified by the integer integer.

— Variable: canonical-display-name

A string containing the canonical name of the X display. This includes the full host name and the screen number. For example: "foo.bar.com:0.0".

— Variable: display-name

A string containing the name of the X display, exactly as passed to Sawfish. For example: ":0", or "foo:0.0".

— Variable: saved-command-line-args

Holds a list of all of the command line arguments (including the executable name), except options related to session mangement.

— Function: call-with-error-handler thunk

Call the zero-parameter function thunk. If an error occurs, trap it and pass its car and cdr to error-handler-function.

— Function: load-module name

Ensure that module name has been loaded. This does not import its bindings or make them accessible.

— Function: eval-in form struct-name

Evaluates form in the structure named by struct-name. Compare this with eval, which takes a structure object as its second parameter, not a structure name.

— Variable: *user-module*

*user-module* is the default module for human interaction with Sawfish.

— Function: user-eval form
— Function: user-require feature

user-eval evaluates form in *user-module*. user-require evaluates (require feature) in *user-module*.

— Function: quote-menu-item string

Escape any ‘_’ characters in string such that the result can be used as the label of a menu item.

— Function: make-directory-recursively dir

Create directory dir. Any missing parent directories will also be created.

— Function: locate-file filename dirs

Search for a file filename in any of the directories named by the list of strings dirs.

— Function: clamp x lower upper

Return x clamped between lower and upper. If x is less than lower, return lower; if it is larger than upper return upper. Otherwise return x.

— Function: clamp* x w lower upper

Return the interval (x, x+w) clamped between lower and upper. If x is less than lower, return lower. If x+w is larger than upper, return upper-w; this is a value of x that satisfies the upper bound, although it may violate the lower bound. Otherwise return x.

— Function: uniquify-list lst

Remove all duplicates values from lst, using eq. The order of elements is not preserved.

— Command: run-shell-command

Executes a shell command. This is a wrapper for system function, so in lisp code, use it instead. (see Shell Commands.)

— Command: no-operation

Does nothing.

Next: , Previous: Miscellaneous Functions, Up: Top

21 External Applications

In this chapter relation to external applications is described. See also See Applications Menu, which is a popup to execute applications.

Next: , Up: External Applications

21.1 Application Invocation

See also the lisp function system which invokes a command from a shell. (see Shell Commands)

— Function: jump-or-exec regex prog #!key match-class onfocused

Jump to a window, or if it doesn't exist, start a program. Main use of this function is as a binding to keys. Defined in the module sawfish.wm.commands.jump-or-exec.

Window is searched by matching the name with a regex regex. If booleanmatch-class is non-nil, the value of regex is matched with window's WM_CLASS. When no window matches, action specified by prog is taken.

If prog is a string, then it should be a program name, and executed from a shell in the background. (I.e. Sawfish adds ”&”.) Otherwise, it should be one of a function, command name, or lisp expression. The function is called without any argument. The lisp expression will be evaluated in the user module.

If the optional argument onfocused is non-nil, it defines the action when the window is already focused, in the same manner as prog, but the function will receive the focused windows as the argument. This can't be a string. 

          ;; Examples:
          
          ;; Jump to a window named "Geany". When not found, invoke "geany"
          ;; from a shell.
          (bind-keys global-keymap "W-F10"
            '(jump-or-exec "Geany" "geany"))
          
          ;; Jump to a window with the class "Gnome-run-dialog".
          (bind-keys global-keymap "W-F2"
            '(jump-or-exec "Gnome-run-dialog" "/usr/local/bin/gnome-run-dialog" #:match-class t ))
— Function: toggle-or-exec regex prog #!key match-class

This function adds to jump-or-exec by turning a window to “quake”-like "toggle-windows". That means, if this function is invoked on a matching window, that window will be iconified. Else it works in the same way as jump-or-exec.

You may also want to use a window property iconify-on-leave. (see Iconifying Windows.) 

          ;; Examples:
          
          ;; Application "dolphin", matched by its name (i.e. WM_NAME.)
          ;; Press "Home" key, and
          ;; * if no instance of dolphin is running, it's invoked.
          ;; * if one is there, the focus jumps to it.
          ;; * if it's already focused, it will be iconified.
          ;;
          ;;  ( bind-keys global-keymap "Home"
          ;;    `( toggle-or-exec "Dolphin" "dolphin ~" )
          
          ;; "konsole", matched by its window-class (= WM_CLASS).
          ;;  ( bind-keys global-keymap "F12"
          ;;    `( toggle-or-exec "Konsole" "konsole" #:match-class t )

Previous: Application Invocation, Up: External Applications

21.2 Common Applications

There're some functions and variables for invocation of external applications. They're defined in sawfish.wm.commands.launcher module.

— Customizable: xterm-program

The program launched by the xterm function. Interpreted by shell.

— Function: xterm #!optional command
— Command: xterm

Start a new terminal specified the option xterm-program.

Optional argument COMMAND is passed to the terminal with -e option, so for most terminals, including xterm, it can contain arguments to be passed.

— Customizable: browser-program

The program launched by the browser function. Interpreted by shell.

— Function: browser #!optional url
— Command: browser

Start a new browser instance. Visit URL if supplied.

Sawfish detects some desktop environments.

— Variable: desktop-environment

Running desktop environment, detected by Sawfish. Possible values are "kde", "gnome", "xfce", or "none".

Next: , Previous: External Applications, Up: Top

22 Standard Hooks

Sawfish provides many hooks to allow extension of previously defined functions. Also, many X events are exported to the Lisp environment via the hooks mechanism. For more details on the hooks mechanism see Normal Hooks.

As well as using the standard call-hook function, sawfish also provides the call-window-hook function. This is used to invoke hooks which refer to a single window. Such hook is called “window hook”. If a window hook has a local value defined in the window's property list then this value is used, before the default value defined by the actual variable.

— Function: call-window-hook hook window #!optional args hook-type

Call hook for window with further arguments args. See call-hook for a description of hook-type. Each function in the hook is called with arguments (window . args).

Root window is represented by the symbol root.

The available hooks are listed below.

Next: , Previous: Standard Hooks, Up: Standard Hooks

22.1 Command Hooks

The hook functions are passed one argument which is the command name.

— Hook: pre-command-hook

Called before invocation of each command. You can modify this-command here. In particular, if it's set to nil in this hook, then the command won't be executed.

— Hook: post-command-hook

Called after each command is evaluated.

Next: , Previous: Command Hooks, Up: Standard Hooks

22.2 Key Hooks

— Hook: unbound-key-hook

Called when an key or pointer event has been received which there is no binding for. The hook functions return no arguments. This is an or-type hookk—the first function that returns non-nil will terminate the hook call.

Under normal circumstances, an unbound key release causes a throw to top-level. Adding any function to this hook suppresses that behavior.

Next: , Previous: Key Hooks, Up: Standard Hooks

22.3 Window Construction Hooks

— Window Hook: before-add-window-hook
— Window Hook: add-window-hook

Called when the window is first adopted by the window manager. This occurs before the window is created, installed or placed. At this early stage, the only safe action is to set properties of the window (with window-put).

add-window-hook is a deprecated hook, replaced by before-add-window-hook. It is called immediately after before-add-window-hook.

— Window Hook: after-add-window-hook

Called when the window is first adopted by the window manager. This occurs after the window has been created, installed and placed.

— Window Hook: after-framing-hook

Called after a window gets a frame assigned, or after a window's frame is rebuilt.

Next: , Previous: Window Construction Hooks, Up: Standard Hooks

22.4 Window Destruction Hooks

— Window Hook: destroy-notify-hook

Called when the window is destroyed. Note that this may be called asynchronously to the normal event loop. In general, once the window manager knows the window has been destroyed, it will attempt to call this hook as soon as possible.

Next: , Previous: Window Destruction Hooks, Up: Standard Hooks

22.5 Window Mapping Hooks

— Window Hook: map-notify-hook
— Window Hook: unmap-notify-hook
— Window Hook: reparent-notify-hook
— Window Hook: shape-notify-hook

Called with a window is mapped, unmapped, reparented, or has its shape changed, respectively.

Note that iconifying and uniconifying windows triggers unmapping and mapping, respectively.

— Window Hook: iconify-window-hook
— Window Hook: uniconify-window-hook
— Window Hook: shade-window-hook
— Window Hook: unshade-window-hook
— Window Hook: window-maximized-hook
— Window Hook: window-unmaximized-hook
— Window Hook: window-depth-change-hook

Called when a window is iconified, uniconified, shaded, unshaded, maximized, unmaximized, or has its depth changed, respectively.

— Window Hook: visibility-notify-hook

Called when a window's visibility changes. In addition to the window, the hook is called one one of the symbols fully-obscured, partially-obscured, or unobscured.

— Window Hook: place-window-hook

Called the first time a window is mapped, or if the window does not have a true placed property. This is an or-type hook—the first function that returns non-nil will terminate the hook call.

Next: , Previous: Window Mapping Hooks, Up: Standard Hooks

22.6 Window Motion Hooks

— Window Hook: window-moved-hook
— Window Hook: window-resized-hook

Called whenever the window is moved or resized.

This hook is called inside the move-window-to and move-resize-window-to functions, so any operation that moves the window will trigger this hook. The window motion does not have to be interactive.

Note that outline window sizing and movement does not use move-window-to or move-resize-window-to, except at the very end of the operation.

Compare with while-moving-hook and while-resizing-hook.

— Window Hook: before-move-hook
— Window Hook: before-resize-hook

Called before starting an interactive move or resize.

— Window Hook: while-moving-hook
— Window Hook: while-resizing-hook

Called during every pointer motion event during a move or resize. This includes outline window motion. The calls take place before the window or its outline are actually moved.

Compare with window-moved-hook and window-resized-hook.

— Window Hook: after-move-hook
— Window Hook: after-resize-hook

Called after completion of an interactive move or resize. In addition to the window, the hook is called with a list of symbols indicating how the window was moved or resized: horizontal and vertical for movement, right, left, bottom and top for resizing.

— Window Hook: before-slide-hook

Called before a window move when using key binding.

— Hook: after-restacking-hook

Called after any window restacking operation, including (but possibly not limited to restack-windows, x-raise-window and x-lower-window. The hook functions take no arguments.

Next: , Previous: Window Motion Hooks, Up: Standard Hooks

22.7 Window Cycling Hooks

— Window Hook: after-cycle-step-hook

Called after each step of window cycling. (See Cycling Between Windows.)

Next: , Previous: Window Cycling Hooks, Up: Standard Hooks

22.8 X Hooks

— Window Hook: configure-request-hook

Called when an X ConfigureRequest event is received. In addition to the window, the hook is called with an association list of configure request properties. This alist may contain items (stack . above), (stack . below), (position . coordinates), and (dimensions . dimensions).

— Window Hook: configure-notify-hook

Called when an X ConfigureNotify event is received, i.e. when window configuration request is complete.

— Window Hook: property-notify-hook

Called whenever an X window property (not a Sawfish window property) changes. In addition to the window, the hook is called with the atom name and one of the symbols new-value or deleted.

— Window Hook: window-state-change-hook

Called whenever certain window manager hints change for a window. Currently only urgency is monitored. The hint is an additional argument to the hook.

Next: , Previous: X Hooks, Up: Standard Hooks

22.9 Pointer Motion Hooks

— Window Hook: enter-notify-hook
— Window Hook: enter-frame-part-hook
— Window Hook: leave-notify-hook
— Window Hook: leave-frame-part-hook

Called when the pointer enters or leaves a window, respectively.

If the window was part of a frame, then enter-frame-part-hook or leave-frame-part-hook is called with three arguments: the window, the frame part class (see Frame Part Classes), and mode. mode is one of the symbols normal, grab or ungrab.

Otherwise enter-notify-hook or leave-notify-hook is called with two arguments: the window and mode.

Entering the root window is reported, too. In that case, the symbol root is returned in place of a window object.

— Window Hook: focus-in-hook
— Window Hook: focus-out-hook

Called when a window gains or loses focus, respectively. The hook function receives two arguments: the window that received / lost focus, and mode. mode is one of the symbols normal, grab, ungrab or while-grabbed.

If your focus-mode is set to enter-exit, your window focus is tightly bound to your pointer position; focus-related hooks and enter/leave hooks will be called in lockstep. For other values of focus-mode, Sawfish will trigger fewer focus-related hook calls than enter/leave hook calls.

This hook is never called for the root window, because the root window never gets nor loses focus.

Next: , Previous: Pointer Motion Hooks, Up: Standard Hooks

22.10 Workspace and Viewport Hooks

— Hook: enter-workspace-hook
— Hook: leave-workspace-hook

Called when switching from one workspace to another. This includes switching caused by adding or removing a workspace. The hook is called with a list containing the workspace in question.

— Window Hook: add-to-workspace-hook
— Window Hook: remove-from-workspace-hook

Called when a window is added or removed from a workspace. In addition to the window, the hook is called with a list containing the workspace being changed. If the window is in multiple workspaces, then removing triggers remove-from-workspace-hook for each workspace.

— Hook: workspace-state-change-hook

Called when any aspect of the workspaces change, including adding a workspace, removing a workspace, moving a workspace, inserting or removing a window from a workspace, etc. This hook is called with no arguments, so you should use one of the more specific hooks if possible.

— Hook: viewport-resized-hook

Hook called when the number of rows and columns in each workspace is changed.

— Hook: viewport-moved-hook

Called when the origin of the viewport into the workspace is moved.

— Hook: enter-flipper-hook
— Hook: leave-flipper-hook

See See EdgeActions.

Next: , Previous: Workspace and Viewport Hooks, Up: Standard Hooks

22.11 Startup and Shutdown Hooks

— Hook: after-initialization-hook

Called after adopting the initial set of windows.

— Window Hook: remove-window-hook

Called on each window as Sawfish shuts down (possibly for a restart). The hook functions take no arguments.

— Hook: before-exit-hook

Called immediately before exiting.

— Hook: sm-window-save-functions
— Hook: sm-restore-window-hook
— Hook: sm-after-restore-hook

Session management hooks, Session Management.

Previous: Startup and Shutdown Hooks, Up: Standard Hooks

22.12 Other Hooks

— Hook: gtkrc-changed-hook

When using the gtkrc module to load the current gtk style parameters, this hook is called when the style changes.

— Window Hook: client-message-hook

Called with arguments (window type data-array). This is an or-type hook—the first function that returns non-nil will terminate the hook call.

Next: , Previous: Standard Hooks, Up: Top

23 Standard Window Properties

As described in an earlier section of this manual, each window has a property list, which may be used to associate arbitrary lisp data with symbolic keys (see Window Property Lists). The following table documents a subset of the keys currently used.

ignored
When set, the window is ignored in many operations. See Ignored Windows.
avoid
When set, the window will not be covered by other windows when they are maximized or newly placed. See Avoided Windows.
workspaces
A list of integers defining the workspaces that the window is a member of, or nil if the window is sticky. See Workspaces.
sticky
Whether the window should appear on all workspaces.
sticky-viewport
When set, the window will appear in all viewports of its workspace.
keymap
An optional, window-local, keymap. See Keymaps.
focus-click-through
When set, and click-to-focus mode is enabled, the click that focuses a window is passed through to the client window.
never-focus
When set the window will never be given the input focus
focus-when-mapped
Focus the window when it is mapped on to the display.
ignore-program-position
When set the window's program-position property is ignored, use this with windows that set this hint incorrectly.
place-mode
When set, the placement mode to be used with this window.
placement-weight
When set, the weight assigned to the pixels in this window when doing fitted window placement.
type
The frame-type of the window, or nil. See Frame Types.
frame-style
The frame style explicitly chosen by the user, or unset. See Frame Styles.
current-frame-style
The frame style currently used for the window. See Frame Styles.
removed-classes
A list of frame part classes removed from the decorations of this window. See Removing Frame Parts.
shaded
Is the window shaded? See Shading Windows.
hide-client
Is the client window visible within its frame. Used to implement window shading.
depth
An integer, the layer that the window is a member of. Layer zero is the depth of “normal” windows, negative depths are below this level, while positive depths are above. See Window Stacking.
placed
Has the window been placed in a position yet? The place-window-hook is only called when this is unset.
iconified
Is the window iconified? See Iconifying Windows.
iconify-on-leave
Iconify this window then the mouse pointer leaves. See Iconifying Windows.
gravity
When set, overrides the window gravity field of the window's size hints. May be one of the symbols: north-west, north, north-east, west, center, east, south-west, south, south-east.
fixed-position
When set, the user is not allowed to change the position of this window.
client-set-position
When set, the program owning the window has manually moved the window after it was mapped.
animator
Animator when iconified. (see Animating Windows)

Next: , Previous: Standard Properties, Up: Top

24 Session Management

Sawfish has fully integrated support for the X session management protocols. Also, this support is extensible to allow all Lisp modules to save and reload their own window state.

There are two methods of doing this. If the module only wants to save and restore the values of properties in each window's property list (i.e. those values set via window-put), then the following functions may be used:

— Function: sm-add-saved-properties &rest properties
— Function: sm-add-restored-properties &rest properties

Arrange for all symbols properties to be saved or restored with the session.

— Variable: sm-saved-window-properties
— Variable: sm-restored-window-properties

Lists of properties (symbols) to be saved or restored with each session.

If a Lisp module chooses to use this method it may add a function to the add-window-hook to act on the reloaded properties when the session is reloaded.

For more complex window properties that can't be saved straight from the window's plist two hooks are available:

— Variable: sm-window-save-functions

A list of functions, each of which is called when the state of each window is saved. Each function is called with a single argument (the window) and should return a list of alist elements that will be saved in the state file. (As such, only values with valid read syntaxes may be included.)

— Variable: sm-restore-window-hook

List of functions called when the state of a window is restored. Each is called with arguments (window alist), where alist defines the state saved for the window.

Each function should look for the properties it saved, and then take any action dependent on the values.

The following hook is also called.

— Variable: sm-after-restore-hook

Hook called after loading a saved session.

— Variable: sm-save-directory

The directory that will contain all Sawfish sessions. It must be a string. By default it is "~/.sawfish/sessions".

— Variable: sm-sloppy-id-matching

When loading sessions, the algorithm that matches saved session data to running clients requires that if one has a session id, then so must the other, and they must match. Setting this variable to true turns that feature off, allowing some broken clients to be session managed. Defaults to false.

Next: , Previous: Session Management, Up: Top

25 Low-level X Interface

Next: , Previous: Low-level X Interface, Up: Low-level X Interface

25.1 X Server

— Function: x-server-timestamp #!optional from-server store

Return a recent X server timestamp as an integer.

If from-server is non-nil, the timestamp is read directly from the server; otherwise the most recent timestamp seen by the window manager (i.e., from an event) is returned.

If store is true, this becomes the most recent timestamp seen by the window manager.

Next: , Previous: X Server, Up: Low-level X Interface

25.2 X Windows

— Function: x-create-window (x . y) (width . height) bw attrs #!optional event-handler

Create a new X window at (x, y) with dimensions (width, height) and border width bw. Attrs is an alist mapping attribute names to values. Allowed attribute names are background and border-color.

— Function: x-configure-window window attrs

Reconfigure the window associated with window. Attrs is an alist mapping attribute names to values. Allowed attribute names are x, y, width, height and border-width.

— Function: x-destroy-window window

Destroy the X window window.

— Function: x-map-window window #!optional unraised

Map the window associated with window to the display. If unraised is not specified, the window will be mapped at the top of the window stack.

— Function: x-unmap-window window

Unmap the window associated with window.

— Function: x-window-id window

Return the X window ID (an integer) associated with window.

— Function: x-window-p obj

Return t if obj is associated with an X window object.

— Function: x-change-window-attributes window attrs

Set attributes of the window associated with window. Attrs is an alist mapping attribute names (symbols) to values. Allowed attribute names are background and border-color.

Next: , Previous: X Windows, Up: Low-level X Interface

25.3 X Selections

These functions are defined in sawfish.wm.util.selection.

— Function: x-get-selection sel

Return the string corresponding to the current value of the X11 selection defined by sel, or nil if the selection currently has no value. Sel should be one of PRIMARY, SECONDARY or CLIPBOARD.

— Function: x-selection-active-p sel

Returns t if the X11 selection defined by the symbol sel is available for reading. Sel should be one of PRIMARY, SECONDARY or CLIPBOARD.

Next: , Previous: X Selections, Up: Low-level X Interface

25.4 X Keysyms

— Function: x-keysym-name ks

Return the Lisp symbol naming the X11 keysym represented by the integer ks.

— Function: x-lookup-keysym name

Return the X11 keysym (an integer) named by the Lisp symbol name.

Next: , Previous: X Keysyms, Up: Low-level X Interface

25.5 X Bitmaps and Pixmaps

— Function: x-bitmap-p

Return t if arg is an X-bitmap object.

— Function: x-create-bitmap (width . height)

Create a bitmap of size widthxheight.

— Function: x-create-pixmap (width . height)

Create a pixmap of size widthxheight.

— Function: x-destroy-drawable drawable

Destroy the X drawable drawable.

— Function: x-drawable-height drawable
— Function: x-drawable-width drawable

Return the height / width in pixels of drawable.

— Function: x-drawable-id drawable

Return the X11 drawable-ID (an integer) associated with drawable.

— Function: x-drawable-p obj

Return t if obj is an X drawable object.

— Function: x-grab-image-from-drawable drawable mask

Return a new image object copied from drawable. Mask is a stencil mask for the image; black pixels in mask become transparent in the returned image.

— Function: x-pixmap-p obj

Return t if obj is an X pixmap object.

Next: , Previous: X Bitmaps and Pixmaps, Up: Low-level X Interface

25.6 X Drawing

— Function: x-clear-window window

Clear the window associated with window to its background color.

— Function: x-copy-area window gc (x . y) (width . height) (dest-x . dest-y)

Copy a region of window with top-left corner (x, y) and dimensions (width, height) to the position (dest-x, dest-y) using gc.

— Function: x-create-gc window attrs

Create a new GC for the specified window window. Attrs is an alist mapping attributes to values. Allowed attribute names are foreground, background, line-width, line-style, cap-style, join-style, fill-style, fill-rule, arc-mode, tile, stipple, ts-x-origin, ts-y-origin, clip-mask, clip-x-origin, clip-y-origin and function.

— Function: x-change-gc gc attrs

Sets attributes of the X Graphical Context. Attrs is an association list of attribute names and values. Allowed attribute names are foreground, background, line-width, line-style, cap-style, join-style, fill-style, fill-rule, arc-mode, tile, stipple, ts-x-origin, ts-y-origin, clip-mask, clip-x-origin, clip-y-origin and function.

— Function: x-create-root-xor-gc

Create a graphics context specialized for XOR-ing onto the root window. This is used for drawing outlines for window movement.

— Function: x-destroy-gc gc

Destroy the X graphics context gc.

— Function: x-draw-arc window gc (x . y) (width . height) (angle1 . angle2)

Draw a single circular or elliptical arc in window using the graphics context gc. The center of the circle or ellipse is the center of an imaginary rectangle at (x, y). The major and minor axes are the (width, height) of that rectangle. The arc sweeps from angle1 to angle2; positive angles are rotated counter-clockwise from zero, and negative angles are rotated clockwise from zero.

— Function: x-draw-image image window (x . y) #!optional (width . height)

Render the image object image in window at position (x, y). If width and height are defined the image is first scaled to these dimensions; otherwise it is drawn using its natural dimensions.

— Function: x-draw-line window gc (x1 . y1) (x2 . y2)

Draw a line from (x1, y1) to (x2, y2) in window using the graphics context gc.

— Function: x-draw-rectangle window gc (x . y) (width . height)

Draw a rectangle with its top-left corner at (x, y) and dimensions (width, height) in window using the graphics context gc.

— Function: x-fill-arc window gc (x . y) (width . height) (angle1 . angle2)

Draw a single filled circular or elliptical arc in window using the graphics context gc. The center of the circle or ellipse is the center of an imaginary rectangle at (x, y). The major and minor axes are the (width, height) of that rectangle. The arc sweeps from angle1 to angle2; positive angles are rotated counter-clockwise from zero, and negative angles are rotated clockwise from zero.

— Function: x-fill-polygon window gc points #!optional draw-mode

Draw a single filled polygon in window using the graphics context gc. Points is a list of (x, y) pairs that defines the polygon vertices.

Draw-mode is a hint to the X server on how to draw the polygon; if supplied, it should be one of the symbols convex or non-convex. The default mode is “Convex”.

— Function: x-fill-rectangle window gc (x . y) (width . height)

Draw a filled rectangle with its top-left corner at (x, y) and dimensions (width, height) in window using the graphics context gc.

— Function: x-gc-p obj

Returns t if obj is an X GraphicsContext object.

— Function: x-gc-set-dashes gc pixels-list #!optional offset

Set the dash style of graphics context gc to the value of pixels-list. Pixels-list is a list of cons cells ((pixels-on . pixels-off) ...) indicating runs of on and off pixels in a dash segment. If offset is given, this should be an integer indicating the number of pixels to offset the dashes.

— Function: x-window-back-buffer window

Return the X object ID (an integer) for the back buffer associated with window. If no such back buffer exists, the function will attempt to create one.

If the function is unable to find or create a back buffer (possibly because the X server does not support them), it returns the window's own ID.

— Function: x-window-swap-buffers window

Swap the fore and back buffers of the window associated with window. If the X server does not support double buffers, the function quietly does nothing.

Two functions to draw strings are there. If you need to write a message like display-message use x-draw-string. If you need to write on the root-window directly, use x-draw-text.

— Function: x-draw-string window gc (x . y) string #!optional font

Draw the specified string at (x, y) in window using the graphics context gc. If font is specified use that font. See also x-draw-text.

— Function: x-draw-text window gc (x . y) string

Draw the specified string at (x, y) in window using the graphics context gc. See also x-draw-string.

Previous: X Drawing, Up: Low-level X Interface

25.7 Available X Symbols

The following symbols can be used where X window attributes are expected:

border-width
border-color
expose
convex
non-convex
line-width
line-style
cap-style
join-style
fill-style
fill-rule
arc-mode
tile
stipple
ts-x-origin
ts-y-origin
clip-mask
clip-x-origin
clip-y-origin

The following symbols can be used where X window attribute values are expected:

line-solid
line-on-off-dash
line-double-dash
cap-not-last
cap-butt
cap-round
cap-projecting
join-miter
join-round
join-bevel
fill-solid
fill-tiled
fill-stippled
fill-opaque-stippled
even-odd-rule
winding-rule
arc-chord
arc-pie-slice
function
clear
and
and-reverse
copy
and-inverted
no-op
xor
or
nor
equiv
invert
or-reverse
copy-inverted
or-inverted
nand
set

Next: , Previous: Low-level X Interface, Up: Top

26 Frequently Asked Questions

See also http:://sawfish.wikia.com/wiki/Tips.

  1. How can I get information on Sawfish?
  2. How do I read the Info manual?
  3. I installed Sawfish but it's not working! All I see when I start X is the default stipple background: no programs, no menus, no pager.

    This is exactly what it's supposed to do, but first try middle-click (by default) on the background. This invokes the menu. (If you have a two-button mouse, try clicking both buttons simultaneously).

    Why this is so? Because Sawfish is minimal - Sawfish is a window manager and as such is not responsible for setting the background, starting programs or displaying a pager — these can all be done using separate applications (e.g. by using a desktop environment such as GNOME).

  4. How do I customize Sawfish?

    There're two ways, by the configurator GUI and by preparing lisp code. The GUI can be run by middle-clicking background -> “Customize”. Most customizations similar to other window managers can be done through GUI.

    For customizations by lisp, first understand that in the startup, files ~/.sawfish/custom, .sawfishrc are read in this order.

    ~/.sawfish/custom
    This file is created and edited by the configurator GUI, and stores customizations. It shouldn't really be edited manually.
    ~/.sawfish/rc or ~/.sawfishrc
    This is the file you edit. It is a hand written lisp code, and almost all explicit customizations should be done here.

    Choose the filename either ~/.sawfish/rc or ~/.sawfishrc. The former is recommended, because the directory ~/.sawfish is anyway created to store custom, and you can also put other lisp scripts, like user-contributed codes there.

    Sawfish < 1.6 reads sawfish-defaults by default only if ~/.sawfishrc lacks, but now it is always read.

  5. How can I start an application from Sawfish?
  6. How do I make clicking on a window raise the window?

    Bind the event Button1-Click1 in the window-keymap to the raise-window-and-pass-through-click command

  7. How do I redefine the ‘Applications’ menu?

    See the ‘Popup Menus’ node in the Info manual (see Popup Menus)

  8. How do I compile Lisp files?

    Use the shell command: 

              sawfish --batch -l compiler -f compile-batch files...

    where files... are the names of the files you want to compile. They will normally have .jl suffixes, the compiler will create associated files with .jlc suffixes containing the compiled Lisp code.

    Remember that always the latest code is read, i.e., if the source is newer than the byte compiled file, the source is used, unlike emacs.

  9. How do I create a new theme?

    See the ‘Window Frames’ node of the Info manual (see Window Frames)

    Basically though, create a directory ~/.sawfish/themes/foo where foo is the name of your theme. Then copy any images into this directory and create a file theme.jl that will be loaded to initialize the theme

  10. How do I port an Enlightenment theme to Sawfish?

    There's no automatic translation available. Get the images used in the window border, then write a theme.jl file telling the window manager how they are used to form a window frame

    See the themes/brushed-metal directory for an example, and the Info manual for the documentation

  11. Are there any other themes available?

    Yes, there are plenty actually. Most of them reside over at freshmeat: http://themes.freshmeat.net/browse/926/. You can also take a look at the Themes section on the Sawfish website: http://sawfish.wikia.com/wiki/Themes.

  12. Why don't GTK themes work with Sawfish?

    There was a problem with older versions of the gtk-engines package preventing engine based themes working with several interpreted languages. Get the latest gtk-engines from ftp://ftp.gnome.org/

  13. Sound support.

    Here we explain sound support which can't be set via Configurator.

    You can add sound files under ~/.sawfish/sounds/. This path can be changed with audio-load-path variable. See the file OPTIONS for the format.

    The program to play sounds is set by play-sample-program. If you want to pass arguments or redirect the output, prepare a wrapper script, for example something like following: 

              #!/bin/sh
          
          # No need of backgrounding.
          mplayer -volume 30 "$1" &>/dev/null
  14. What's this sawfish-client program?

    This allows you to connect to a window manager process and evaluate arbitrary Lisp forms. Do ‘sawfish-client -?’ for more details (‘sawfish-client -’ for a read-eval-print loop)

    By default you can only connect from the host running the wm (through a unix-domain socket). To enable the network based server, evaluate the lisp form (server-net-init).

    Note however that this connects through the X server, meaning that anyone who can open windows on your display can also execute any Lisp code on the host running the window manager (and by extension, execute any program).

    So don't run the net server with X access control disabled (unless you're not connected to a network).

  15. How do I restart Sawfish?

    From a shell lauch the following command: sawfish-client -q -f restart

  16. Shutdown privilege.

    The Sawfish root-menu has a “session” sub-menu which allows you to shutdown your machine. If you use GNOME or KDE, no additional work is required. But if you use Sawfish standalone, the user needs the privilege to execute shutdown command.

    You can do it, for example, with sudo combined with user group shutdown: 

              $ groupadd shutdown      # add a new group called "shutdown"
          $ adduser john shutdown  # add user "john" to the "shutdown" group
          $ visudo                 # add the group "shutdown" to sudoers
          
          # add the following:
          %shutdown ALL=(root) NOPASSWD: /sbin/shutdown

    That's it, now everyone in the shutdown group can do it!

  17. I have multiple heads. Is it possible to switch workspace per head?

    You have to devise a trick, because the strict answer is no. There's “sticky-head” script which partly achives it on the wiki, but it's still incomplete: http://sawfish.wikia.com/wiki/Sticky-head

    Technically, Sawfish's workspace implements “virtual desktop” specified in the window manager standard (ewmh), which has to be at least the size of the X screen, so the workspace has to containt all heads. “Per head workspace” has to be implemented as a new mechanism on top of workspace.

  18. How can I hide the mouse pointer when idle?

    Install “unclutter”.

  19. Why don't you use GUILE or other languages?

    (Current Sawfish community's attitude.)

    We can't afford it. We're understaffed.

    (Written by John Harper.)

    Mainly because I'm lazy; I had already written rep, and therefore understood it completely, whereas I have never used GUILE. Also, rep has some features not available in GUILE (byte-code compilation, autoloading, built-in event-loop, ...)

    But before you flame me: yes I do think scheme is a more elegant language.

  20. Will you add feature x?

    Possibly. But only if it can be written in Lisp, or doesn't conflict with the overall design aims.

    These aims are to build a lightweight, generally applicable, set of core window management functions, then write all high-level functionality as Lisp extensions

  21. Will you add background setting?

    No. This can easily be done by a separate application (e.g. with the GNOME hints, simply monitor property _WIN_WORKSPACE on the root window).

  22. Why does Sawfish look weird/crash on Solaris?

    Sawfish works stably on Solaris, but you may need to do two things:

    1. Disable use of MIT-SHM by Imlib (run the program imlib_config, the MIT-SHM option is on the ‘Rendering’ page)
    2. Recompile GTK+ using the ‘--disable-xim’ option to configure
  23. Why don't some windows ever get focused?

    Because that window doesn't accept it. Technically, windows ask to receive focus by setting their WM_HINTS property appropriately; for example if I xprop a gnome-terminal: 

              WM_HINTS(WM_HINTS):
                          Client accepts input or input focus: True
                          Initial state is Normal State.
                          window id # of group leader: 0x5c00001
  24. Why doesn't the GNOME desk-guide / tasklist show the true state of my desktop?

    It seems that there is a problem with these applets that only occurs after restarting Sawfish - they seem to lose track of the current window states.

    The simplest way to correct this is to execute the following shell commands: 

              $ save-session
          $ killall panel

    (assuming you have a session manager to restart the panel afterwards!)

  25. What do these ‘bytecode-error’ messages mean?

    It means that you're trying to execute Lisp code that was compiled for an outdated version of the Lisp virtual machine. Recompile any Lisp files that you have installed locally.

  26. Historical question: Why is it now called Sawfish?

    Because the old name (‘Sawmill’) was already being used by another company, who were in the process of registering it as a trademark.

    The rename should be mostly painless, all old binaries still work for the time being, but will be phased out over time (final phasing out started around 1.5.0). Where before you would execute a program called sawmill*, replace it by sawfish*. E.g. sawmill becomes sawfish, and sawmill-client becomes sawfish-client.

    Your ~/.sawmill directory will automatically be renamed ~/.sawfish unless it would overwrite an existing file. Only user configuration ~/.sawfish[/]rc will be checked currently, ~/.sawmillrc is not used anymore (it was also read up to version 1.3.5).

    My apologies for any inconvenience caused.

  27. Historical question: But why Sawfish, and not <insert your favourite alternative>?

    Well I had to choose something! And hopefully it satisfies the main requirements:

    Incidentally, there was no meaning to the name “Sawmill”, the author grepped /usr/dict/words for something containing “wm”.

Next: , Previous: FAQ, Up: Top

Function Index

Next: , Previous: Function Index, Up: Top

Variable Index

Previous: Variable Index, Up: Top

Concept Index

Table of Contents