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

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

This is Edition 0.6 of its documentation, last updated 12 December 1999 for Sawfish version 0.19.

Node:Copying, Next:, Previous:Top, Up:Top

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.

Node:Introduction, Next:, Previous:Copying, Up:Top

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 Top), this is a run-time library implementing a language similar to Emacs Lisp (see Top), but with many extensions, and using lexical instead of dynamic scope. This manual assumes at least a basic knowledge of the language.

Node:News, Next:, Previous:Introduction, Up:Top

News

This lists the user-visible changes made to Sawfish, and which releases they occurred between. For more detailed information see the ChangeLog files in the Sawfish source tree.

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

Node:Colors, Next:, Previous:News, Up:Top

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.

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

get-color name Function
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.

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

get-color-rgb red green blue Function
Return the color object representing the color with RGB components as specified (each component ranging from 0 to 65535).

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.

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

color-name color Function
Return a string defining one of the X11 names used to specify the color represented by the color object color. Note that this may well be different to the name used when the color was originally allocated.

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.

default-foreground Variable
The color used for text where no other color is defined.

Node:Fonts, Next:, Previous:Colors, Up:Top

Fonts

As with the color type, the font type allows X11 fonts to be manipulated by Lisp code.

fontp arg Function
Returns t if arg is a font object.

get-font name Function
Return a font object representing the X11 font specified by the string

Signals an error if no font named name is available.

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

font-name font Function
Returns the name of the X11 font represented by object font (a string).

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

text-width string &optional font Function
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.

default-font Variable
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.

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

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

Node:Images, Next:, Previous:Fonts, Up:Top

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.

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

make-image file-name Function
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.

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

image-load-path Variable
A list of directory names. This defines the search path used when loading images.

make-sized-image width height &optional color Function
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.

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

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

flip-image-horizontally image Function
Flip the contents of image about the vertical axis.

flip-image-vertically image Function
Flip the contents of image about the horizontal axis.

flip-image-diagonally image Function
Flip the contents of image about an axis running from the top-left corner to the bottom-right corner of the image.

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

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

image-get image property Function
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.

image-border image Function
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.

set-image-border image left right top bottom Function
Sets the border of image.

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-shape-color image Function
Return the color marking transparent pixels in image, or nil if no such color has been specified.

set-image-shape-color image color Function
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.

image-modifier image type Function
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).

set-image-modifier image type gamma brightness contrast Function
Set the image modifier of image defined by type.

There are also several other functions manipulating images:

bevel-image image border upwards &optional bevel-percent Function
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.

default-bevel-percent Variable
Default height of drawn bevels, as a percentage.

clear-image image &optional color Function
Set all pixels in image to color (or black if color is undefined).

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

Node:Cursors, Next:, Previous:Images, Up:Top

Cursors

Cursors define the shape and hot-spot of the mouse pointer's image. A lisp type is provided for manipulating these objects.

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

get-cursor data Function
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.

If a vector the format 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.

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

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

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.

Node:Windows, Next:, Previous:Cursors, Up:Top

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.

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

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

get-window-by-id xid Function
Return a window object with id xid, or nil.

get-window-by-name name Function
Return a window object with name name, or nil.

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

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

window-put window property value Function
Set the lisp property named property (a symbol) associated with window object window to value.

window-get window property Function
Return the window property named property associated with the window object window, or nil if no such property exists.

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

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

Window Attributes

window-name window Function
Return the name associated with window.

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

window-icon-name window Function
Return the icon name associated with window.

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

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

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

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

window-group-id window Function
Return an integer defining the xid of the leader of the group that window is a member of, or nil if window is not a member of a group.

window-wants-input-p window Function
Return t when the client window associated with object window has asked for the input focus to be assigned to it when applicable (through the input field of its WM_HINTS property).

window-dimensions window Function
Returns a cons cell (width . height) defining the dimensions of the client window associated with object window.

window-position window Function
Returns a cons-cell (x . y) defining the position relative to the root window of window.

window-size-hints window Function
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.

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

Node:Input Focus, Next:, Previous:Window Attributes, Up:Windows

Input Focus

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

input-focus Function
Returns the window object of the currently focused window, or nil if no window is focused.

set-input-focus window Function
Sets the focus to the client window associated with window.

focus-mode Variable
Defines the current method of using the mouse to assign the input focus. Possible values are enter-exit, enter-only and click.

focus-proxy-click Variable
When in click-to-focus mode, the focus-assigning click is only passed through to the client window if this variable is non-nil.

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

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

window-order &optional workspace allow-iconified all-viewports Function
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.

window-order-push window Function
Push window object window onto the top of the focus stack.

window-order-pop window Function
Remove window object window from the focus stack.

window-order-focus-most-recent Function
Focus the most-recently-focused window on the current viewport of the current workspace.

Node:X Properties, Next:, Previous:Input Focus, Up:Windows

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.

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

delete-x-property window property Function
Deletes the X property named property (a symbol) associated with window.

get-x-property window property Function
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.

set-x-property window property data type format Function
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:

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

set-x-text-property window property data Function
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.

Node:Window Stacking, Next:, Previous:X Properties, Up:Windows

Window Stacking

The stacking order of the display defines the order in which windows are shown, from topmost to bottommost.

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

restack-windows list Function
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.

x-raise-window window Function
Raise the client window associated with object window to the top of the display.

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.

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

set-window-depth window depth Function
Set the stacking depth of window to depth, then restacks the windows to reflect this change.

window-on-top-p window Function
Returns t if window is at the top of its stacking depth.

stack-window-below below above Function
Change stacking order of window below so that it is immediately below window above.

stack-window-above above below Function
Change stacking order of window above so that it is immediately above window below.

save-stacking-order &rest forms Macro
Evaluate forms in an implicit progn, then restore the original window stacking order, returning the value of the progn.

For the following functions, when called interactively they all operate on the window that received the current event, or alternatively the currently focused window.

lower-window window Command
Lower window to the bottom of its stacking depth.

raise-window window Command
Raise window to the top of its stacking depth.

raise-lower-window window Command
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.

lower-window-depth window Command
Decrement the stacking depth of window.

raise-window-depth window Command
Increment the stacking depth of window.

Node:Moving and Resizing Windows, Next:, Previous:Window Stacking, Up:Windows

Moving and Resizing Windows

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

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

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

move-resize-window-to window x y width height Function
A combination of the previous two functions.

resize-window-with-hints window cols rows &optional hints Function
Resize the window associated with object window so that it has cols columns and rows rows. 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.

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.

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

resize-window-interactively window Command
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.

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

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

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

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

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

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

resize-show-position Variable
When non-nil, the window size is shown in the center of the screen.

move-snap-edges Variable
When non-nil, the window position is "snapped" to edges of other windows within close proximity.

move-snap-epsilon Variable
The distance in pixels before snapping together two edges.

Node:Showing and Hiding Windows, Next:, Previous:Moving and Resizing Windows, Up:Windows

Showing and Hiding Windows

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

hide-window window Function
Prevent object window from being displayed.

show-window window Function
Ensure that window (if it has been mapped, and is within the screen boundary) is visible.

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

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

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.

delete-window window Command
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.

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

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

x-kill-client window Function
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).

Node:Shading Windows, Next:, Previous:Destroying Windows, Up:Windows

Shading Windows

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

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

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

toggle-window-shaded Command
Toggle the shaded state of the window.

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.

Node:Iconifying Windows, Next:, Previous:Shading Windows, Up:Windows

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, instead iconified windows are shown slightly differently in the menu of all windows.

iconify-window window Command
Iconify the window associated with object window.

uniconify-window window Command
Return the window associated with window from its iconified state.

A window's iconic state may be tested through examination of its iconified property--when t the window is iconified.

Node:Maximizing Windows, Previous:Iconifying Windows, Up:Windows

Maximizing Windows

The dimensions of a window may be temporarily maximized.

maximize