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-window window &optional direction Command
Maximize both dimensions of window

If defined, direction may be either vertical or horizontal.

maximize-window-vertically window Command
Maximize the vertical dimension of window.

maximize-window-horizontally window Command
Maximize the horizontal dimension of window.

unmaximize-window window &optional direction Command
Restore the dimensions of window to its original, unmaximized, state.

If defined, direction may be either vertical or horizontal.

maximize-window-toggle window Command
Toggle the state of window between maximized and unmaximized.

If defined, direction may be either vertical or horizontal.

maximize-window-vertically-toggle window Command
Toggle the state of window between vertically maximized and unmaximized.

maximize-window-horizontally-toggle window Command
Toggle the state of window between horizontally maximized and unmaximized.

window-maximized-p window Function
Return t when window is in the maximized state.

window-maximized-vertically-p window Function
Return t when window is vertically maximized.

window-maximized-horizontally-p window Function
Return t when window is horizontally maximized.

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

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.

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

The sawfish-ui program can be used to invoke the GUI manually; if GNOME is being used, then the GNOME Control Center can also be used to customize certain classes.

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.

Customization options are organized into groups. Each group has a name and contains a set of related options. Currently, it is not possible for groups to contain sub-groups.

defgroup group real-name &rest keys Macro
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. Currently the only property is :widget, defining a function to create the group's UI widget.

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

defcustom variable value documentation &rest keys Macro
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.

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.
:type type
Specifies the required type of the variable. The current possibilities are boolean, number, string, file-name, program-name, font, color, frame-style, keymap and (set symbols...).

The boolean type assures a value of either nil or t, the set type allows the user to choose from one of the symbols in the list.

: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.
: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, set, 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.

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
  :range (0 . 64))

This defines a group and two customization options.

Node:Window Frames, Next:, Previous:Customization, Up:Top

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!

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

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.

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

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

frame-part-classes Variable
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, 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.

def-frame-class class alist-form &rest binding-forms ... Macro
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 withing 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.

override-frame-part-classes Variable
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:

set-frame-part-value class key value &optional override Function
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.)

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

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

frame-part-get window class attr Function
Returns the value of the attribute attr for the frame part of class class in the current frame of window.

Returns nil if no such attribute exists. If more than one frame part of class class exists then the value will be taken from the first part found.

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

Frame Functions

set-window-frame window frame-def Function
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.

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

window-framed-p window Function
Return t when window has been reparented to a frame created by the window manager.

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

window-frame-dimensions window Function
Return a cons cell (width . height) defining the dimensions of the frame associated with window. These will always be greater than or equal to the dimensions of the client window.

If window is not framed, then this function returns the same values as window-dimensions would.

window-frame-offset window Function
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.

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

Frame Types

In order to visually differentiate between different types of windows, several predefined types of window frame exist. These 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.

The type of frame that would ideally be given to a window is stored in the window's type property. It should usually be accessed through the window-type function:

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

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

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.

add-frame-style name function Function
Defines a new frame style called name (a symbol). When a frame of this style is required for a particular window, function is called with two arguments, the window itself and a symbol defining the frame type to create (see Frame Types).

If the frame style is unable to provide a frame definition of the required type, it should return the symbol nil. In which case it may subsequently be asked for a frame of a different type.

If no default frame style exists, the new style will be made the default.

default-frame-style Variable
A symbol naming the frame style to use for windows where no other style is explicitly specified.

check-frame-availability name Function
Returns t if a frame style called name exists. Will try to load such a frame from the filing system if necessary.

set-window-frame-style window style &optional type from-user Function
Sets the frame of window to the style named by the symbol style. If type is defined then it names the frame type to use, otherwise the default type for this window is used.

If from-user is non-nil then the user chose this frame style for the window explicitly (i.e. it's not just the default choice for a new window).

set-frame-for-window window &optional force type Function
If window has no frame style associated with it, then chooses the default value for this window, the value of default-frame-style.

If force is non-nil then the style is always re-chosen, even if the window already has a chosen default style.

If type is non-nil it defines the frame type to give the window, otherwise the current default for the window is used.

reframe-all-windows Function
Forcibly reselect all window frame styles. Only windows with a user specified style are not changed to the current defaults.

rebuild-frames-with-style style Function
Call rebuild-frame on all windows that currently have a frame defined by frame style style (a symbol)

reframe-windows-with-style style Function
Completely recreate all window frames that are defined by the style style.

Several window properties are used while choosing frame styles:

frame-style Window Property
The user-chosen frame style of the window, or nil.

current-frame-style Window Property
The current frame style of the window.

ignored Window Property
When set, the window is not given a frame.

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

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

theme-load-path Variable
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.

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

system-theme-directory Variable
The name of the system theme directory.

Node:Removing Frame Parts, Previous:Themes, Up:Window Frames

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

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

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

Node:Workspaces, Next:, Previous:Window Frames, Up:Top

Workspaces

XXX what do I want to say here?

Node:Popup Menus, Next:, Previous:Workspaces, Up:Top

Popup Menus

Popup menus are one of the two main methods through which the user may invoke Lisp code (the other is via keymaps, see Keymaps). The popup-menu function is invoked with a list of menu item definitions and the associated Lisp function to call for each item. This starts a subprocess to display the menu, then at a later date the chosen menu item is received and evaluated.

Each menu item is specified by a list, the first element of which is a string providing the label for the menu item, the second element is a function to be called if that item is selected by the user. If this function has an interactive specification it will be invoked using the call-command function, otherwise funcall will be used. Alternatively the second element may be a lisp form to evaluate. So, for example, a single-level menu could be defined by: 

(("Item 1" function-1)
 ("Item 2" function-2)
 ()
 ("Item 3" function-3))

The null item will create a separator line in the displayed menu.

If the cdr of first element of any item is a symbol, then the rest of the item is defined by the value of the named variable. If this value is functional then the definition is found by calling the function.

Consider the following definition: 

(("Workspaces" . workspace-menu)
 ("Windows" . window-menu)
 ("Programs" . apps-menu)
 ("Customize" . custom-menu)
 ("About..." (customize 'about))
 ()
 ("Restart" restart)
 ("Quit" quit))

This is the definition of Sawfish's root menu. We can see that four submenus are created dynamically by dereferencing variables (in fact, three of this variables contain functions) (workspace-menu, window-menu, apps-menu and custom-menu).

The apps-menu variable can thus be used to redefine the applications menu. The default definition is as follows: 

(("xterm" (system "xterm &"))
 ("Emacs" (system "emacs &"))
 ("Netscape" (system "netscape &"))
 ("The GIMP" (system "gimp &"))
 ("XFIG" (system "xfig &"))
 ("GV" (system "gv &"))
 ("xcalc" (system "xcalc &")))

The system function simply executes its single argument using /bin/sh.

popup-menu spec Function
Displays a menu defined by the list of item definitions spec.

popup-window-menu Function
Display the menu listing all window operations.

popup-root-menu Function
Display the main menu.

popup-apps-menu Function
Displau the applications menu.

root-menu Variable
Contains the root menu definition.

apps-menu Variable
The variable containing the definition of the applications submenu of the root menu.

Since the overhead of starting the menu subprocess may be noticeable on some systems, it is possible to leave it running between menu requests.

menu-program-stays-running Variable
This variable defines if, and for how long, the menu subprocess is allowed to remain executing for after the last menu has completed. If nil, the program is terminated immediately, if t it is left running indefinitely, if an integer then the program will run for that many seconds (unless another menu is displayed).

Node:Events, Next:, Previous:Popup Menus, Up:Top

Events

Events refer to input events from X that the window manager receives, either for the root window, the window frames it creates, or grabbed from the client windows themselves. Each event induced by the mouse or keyboard has a Lisp representation.

Each input event is represented by a cons cell containing two integers, these integers encode the actual input event. The encoding is opaque; the only way to access an event meaningfully is via the functions provided.

eventp object Function
This function returns t if its argument is an input event.

Each event has a name, a string. This string contains zero or more modifier descriptions separated by hyphens, and then the name of the key itself. The standard X modifier names are provided, as well as three special modifiers <Meta>, <Alt> and <Hyper> that are mapped to the keysyms of the same name.

The following table lists the possible modifier prefixes:

C
The control modifier
M
The meta modifier
A
The alt modifier
S
The shift modifier
H
The hyper modifier
Modk
The standard X modifiers, for k between 1 and 5
Buttonk
The k'th mouse button is currently pressed

Note that the M and A modifiers are virtual modifiers assigned dynamically, according to the X server's xmodmap configuration. The A virtual modifier is assigned to the X modifier with either the <Alt_L> or <Alt_R> keysym assigned to it. The M virtual modifier is assigned to the X modifier with either <Meta_L> or <Meta_R> assigned to it. If either of these two virtual modifiers would be unassigned it is set identically to the other virtual modifier.

There are two special modifiers: the Any prefix matches any set of modifiers; the Release modifier matches key-release events instead of the default key-presses.

Generally keys have the same names as their X keysyms, there are several specially defined keys:

SPC, TAB, RET, ESC, BS, DEL, Up, Down, Left, Right.

Also, there are several pseudo-keys for describing mouse events:

Click1, Click2, Click3, Off, Move.

So, for example, a single click of the left mouse button with the <Meta> key held would be described as M-Button1-Click1, while pressing the <RET> key with <Shift> held would be described as S-RET.

Functions are available to convert between the name of an event and the actual event itself, and vice versa.

lookup-event event-name Function
Create and return a new input event whose name is event-name. 
(lookup-event "C-x")
    => (120 . 65540)

(lookup-event "C-M-Button1-Click1")
    => (1 . 131340)

event-name event Function
This function returns a string naming the input event event. 
(event-name (lookup-event "C-x"))
    => "C-x"

The keysyms generating the two virtual modifiers may be identified through the following variables:

meta-keysyms Variable
A list defining the names of the X keysyms generating the virtual M modifier.

alt-keysyms Variable
A list defining the names of the X keysyms generating the virtual A modifier.

hyper-keysyms Variable
A list defining the names of the X keysyms generating the virtual H modifier.

Node:Commands, Next:, Previous:Events, Up:Top

Commands

A command is a Lisp function which may be called interactively, that is, either as a result of being bound to an input event.

Commands are defined in the same way as functions (using defun), but the body forms of the command must contain an interactive declaration. This 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 form defines the argument values applied to the command when it is called interactively, it may be one of,

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.

commandp object Function
This function returns t if its argument may be called interactively. If object is a function (i.e. a symbol or a lambda-expression) it is a command if it contains an interactive declaration

The only other object which is a command is a function call form; the use of these types of commands is discouraged but they can be useful sometimes.

call-command command &optional prefix-arg Function
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.

Node:Keymaps, Next:, Previous:Commands, Up:Top

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.

keymapp arg Function
Returns t if arg may be used as a keymap.

make-keymap Function
Returns a newly-created empty keymap.

bind-keys keymap &rest bindings Function
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 the input 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)

unbind-keys keymap &rest keys Function
Removes the bindings of the events keys (these may be the names of the events or the event objects themselves) from the keymap keymap.

search-keymap event keymap Function
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
Keymaps active in the standard window frame buttons.

Node:Event Loop, Next:, Previous:Keymaps, Up:Top

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.

lookup-event-binding event Function
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:

eval-modifier-events Variable
When non-nil, key events bound to modifier keys are evaluated.

eval-key-release-events Variable
When non-nil, key-release events are evaluated.

While a command is being evaluated, information about the event that caused it may be found:

current-event Function
Return the event which caused the current command to be invoked

current-event-string Function
Returns the string which the current event would usually insert.

current-event-window Function
Return the window that received the current event, or the symbol root, or nil if no such window.

last-event Function
Return the previous event which occurred.

proxy-current-event window &optional mask propagate Function
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.

allow-events mode Function
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.

forget-button-press Function
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.

accept-x-input &optional mask Function
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).

x-events-queued Function
Returns the number of X events waiting to be handled.

Node:Miscellaneous Functions, Next:, Previous:Event Loop, Up:Top

Miscellaneous Functions

Node:Pointer Functions, Next:, Up:Miscellaneous Functions

Pointer Functions

query-pointer &optional from-server Function
Returns a cons cell (x . y) representing the current mouse pointer position, relative to the origin of the root window.

If from-server is non-nil then the position is read directly from the server, otherwise it's taken from the current event (if possible).

query-pointer-window Function
Returns the top-level window under the mouse pointer, or nil if the cursor is in the root window.

query-last-pointer Function
Returns a cons cell (x . y) representing the second most recent mouse pointer position, relative to the root window.

warp-cursor x y Function
Move the mouse pointer to position (x, y) relative to the origin of the root window.

warp-cursor-to-window window &optional x y Function
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.

Node:Grab Functions, Next:, Previous:Pointer Functions, Up:Miscellaneous Functions

Grab Functions

grab-server Function
Prevent any other clients from accessing the X server.

ungrab-server Function
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.

with-server-grabbed &rest forms Macro
Evaluate forms with the server grabbed. Releases the grab afterwards.

server-grabbed-p Function
Returns t if the X server is currently grabbed.

grab-pointer &optional window cursor Function
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 nil, or unviewable, the grab will be made on the root window.

Returns y if the grab succeeded.

ungrab-pointer Function
Release the grab on the mouse pointer.

grab-keyboard &optional window Function
Grab the keyboard and direct all keyboard events to window object window. If window is nil, or unviewable, the grab will be made on the root window.

Returns non-nil if the grab succeeded.

ungrab-keyboard Function
Release the grab on the keyboard.

Node:Display Functions, Next:, Previous:Grab Functions, Up:Miscellaneous Functions

Display Functions

screen-width Function
Return the width of the root window.

screen-height Function
Return the height of the root window.

draw-window-outline mode x y width height Function
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.

erase-window-outline mode x y width height Function
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.

display-message &optional text attributes Function
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.

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.

Node:Gradient Functions, Next:, Previous:Display Functions, Up:Miscellaneous Functions

Gradient Functions

The gradient feature allows color gradients to be drawn in images. (Evaluate (require 'gradient) to load this feature.)

draw-vertical-gradient image from to Function
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.

draw-horizontal-gradient image from to Function
Draw a horizontal color gradient in image, from left to right.

draw-diagonal-gradient image from to Function
Draw a horizontal color gradient in image, from the top-left corner to the bottom-right.

Node:Other Functions, Previous:Gradient Functions, Up:Miscellaneous Functions

Other Functions

sync-server Function
Flush all pending X requests, don't wait for them to finish.

send-client-message window type data format Function
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).

create-window parent x y width height Function
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.

x-atom symbol Function
Return the integer identifying the X atom with the same name as symbol.

x-atom-name integer Function
Return the symbol with the same name as the X atom identified by the integer integer.

Node:Standard Hooks, Next:, Previous:Miscellaneous Functions, Up:Top

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. If the 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.

call-window-hook hook window &optional args hook-type Function
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).

The following table describes all standard hooks called by Sawfish, and the arguments they are called with:

pre-command-hook
Called before each command is evaluated.
post-command-hook
Called after each command is evaluated.
unbound-key-hook
Called when an key or pointer event has been received which there is no binding for.
before-add-window-hook
add-window-hook
Called with a single window when the window is first adopted by the window manager. before-add-window-hook is called first, it should only set properties of the window.
destroy-notify-hook
Called when the window is destroyed. Note that this may be called asynchronously to the normal event loop. In general, the window manager will attempt to call this hook as soon after it knows the window has been destroyed as is possible.
map-notify-hook
unmap-notify-hook
reparent-notify-hook
enter-notify-hook
leave-notify-hook
focus-in-hook
focus-out-hook
shape-notify-hook
Called with a single window argument, analogous to the X events of the same names.
configure-request-hook
Called with two arguments (window alist) when an X ConfigureRequest event is received. alist may include items (stack . above), (stack . below), (position . coordinates), (dimensions . dimensions).
enter-frame-part-hook
leave-frame-part-hook
Called with two arguments, the window and the frame part class (see Frame Part Classes), when the pointer enters or leaves a frame part.
window-moved-hook
window-resized-hook
Called with a single window argument whenever the window is moved or resized.
visibility-notify-hook
Called with two arguments, the window, and a symbol, one of: fully-obscured, partially-obscured, unobscured.
property-notify-hook
Called with arguments (window atom-name type) where type is new-value or deleted.
client-message-hook
An or type hook. Called with arguments (window type data-array).
enter-workspace-hook
leave-workspace-hook
workspace-state-change-hook
Called with a single argument: the workspace.
add-to-workspace-hook
remove-from-workspace-hook
Called with a single argument: the window.
viewport-resized-hook
Called when the number of rows and columns in each virtual workspace is changed.
viewport-moved-hook
Called when the origin of the viewport into the virtual workspace is moved.
place-window-hook
An or type hook. Called the first a window is mapped.
window-state-change-hook
iconify-window-hook
uniconify-window-hook
shade-window-hook
unshade-window-hook
window-maximized-hook
window-unmaximized-hook
window-depth-change-hook
Called with a single window.
after-initialization-hook
Called after adopting the initial set of windows.
before-exit-hook
Called immediately before exiting.
sm-window-save-functions
sm-restore-window-hook
sm-after-restore-hook
Session management hooks, Session Management.
before-move-hook
before-resize-hook
Called before starting an interactive move or resize, with a single argument: the window.
while-moving-hook
while-resizing-hook
Called while interactively moving or resizing the window passed as the argument to the hook.
after-move-hook
after-resize-hook
Called after completion of an interactive move or resize. Called with two arguments: the window, and a list of symbols defining how the window was moved or resized.
gtkrc-changed-hook
When using the gtkrc module to load the current gtk style parameters, this hook is called when the style changes.
enter-flipper-hook
leave-flipper-hook
When viewport edge-flipping is enabled, these hooks are called as the pointer enters and leaves the pixel-wide border on the edge of the screen. They're called with a single argument, one of the symbols left, right, top, bottom defining the edge in question.

Node:Standard Properties, Next:, Previous:Standard Hooks, Up:Top

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.
avoid
When set, the window will not be covered when maximizing, or when placing using the first-fit or best-fit methods
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.
ignore-window-input-hint
When set the value of the window's input hint is ignored, i.e. the focus will be given to the window when appropriate
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.
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.

Node:Session Management, Next:, Previous:Standard Properties, Up:Top

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 function may be used:

sm-add-saved-properties &rest properties Function
Arrange for all symbols properties to be saved and loaded with the 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:

sm-window-save-functions Variable
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.)

sm-restore-window-hook Variable
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.

sm-after-restore-hook Variable
Hook called after loading a saved session.

Node:FAQ, Next:, Previous:Session Management, Up:Top

Frequently Asked Questions

  1. 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. 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. Both ~/.sawfishrc and ~/.sawmillrc will be checked currently (though only one will be actually loaded).

    My apologies for any inconvenience caused.

  2. But why Sawfish, and not <insert your favourite alternative>?

    Well I had to choose something! And hopefully it satisfies the main requirements:

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

    The default menu binding is somewhat obscure; you must middle-click on the background to bring up the menus. (If you have a two-button mouse, try clicking both buttons simultaneously)

    If, after reading this, you still think that sawfish isn't working, please send mail describing the problem to the sawfish mailing list sawmill@aarg.net

  4. How do I add customizations?

    There are several files controlling this:

    ~/.sawfishrc
    Hand written lisp code, loaded at startup. This is where almost all explicit customization should be done.
    sawmill-defaults
    This lisp library is only loaded if there's no .sawfishrc file.
    ~/.sawfish/custom
    This stores customizations created by the configuration tool; it shouldn't really be edited manually.

    This file is loaded after sawmill-defaults, but before .sawfishrc.

  5. I created .sawfishrc, now things have changed?

    If a ~/.sawfishrc file exists, it prevents sawmill-defaults from being loaded. But it's sawmill-defaults that loads some of the common window manager features, so add the line 

    (require 'sawmill-defaults)

    to your .sawfishrc file if you want to start with all the standard features loaded.

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

  7. How do I bind a key to execute a shell command?

    Bind a key to the run-shell-command command; remember to enter the shell command you want to execute in the string entry in the Edit binding dialog window.

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

  9. How do I redefine the Applications menu?

    See the Popup Menus node in the Info manual (see Popup Menus)

  10. How do I read the Info manual?

    Either execute the command info sawfish, or enter the Info mode within Emacs (C-h i) and type g (sawfish) RET.

    If you're using GNOME, then try executing gnome-help-browser info:sawfish.

  11. 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 initialise the theme

    The configuration tool will display the contents of a file called README in the directory (but make it 80-column text, and only a few lines)

    Recent versions of sawfish include a program sawfish-themer that allows simple themes to be created using a GTK+ interface. Ian McKellar has created GimpMill:

    GimpMill is a GIMP plugin written in Python using James Henstrige's really cool Python GIMP bindings. It allows the construction of Sawmill themes within The GIMP - extending the GIMP interface to allow theme creation like the GAP extends it to allow animation creation.

    GimpMill is available from <http://www.yakk.net/projects.gimpmill.html>

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

  13. Are there any other themes available?

    Thanks to those nice people at themes.org, there's now <http://sawmill.themes.org/> for your theming pleasure

  14. 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/>

  15. Why don't you use GUILE?

    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

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

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

  18. Is there a sawfish mailing list?

    Yes, thanks to Erik Arneson erik@starseed.com who manages it.

    To subscribe, send a message to majordomo@aarg.net with subscribe sawmill in the body.

    The list is archived at <http://inanna.starseed.com/sawmill>.

  19. Is there a sawfish IRC channel?

    From Ryan Pavlik rpav@mythosource.org:

    Sawmill has an irc channel too! It's on EFNet, and called (of all crazy things), #sawmill. So break out your irc clients, or hop on over if you're already addicted. Theme, lisp, general sawmill, and most other random discussion welcome.

    If you need an EFNet server, check www.efnet.net for a listing.

  20. 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
  21. Why don't some windows ever get focused?

    If you don't have the option `give focus to windows even when they haven't asked for it' checked (group Focus/Advanced), then windows that don't ask for focus don't get it.

    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

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

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

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

Node:Function Index, Next:, Previous:FAQ, Up:Top

Function Index

Node:Variable Index, Next:, Previous:Function Index, Up:Top

Variable Index

Node:Concept Index, Previous:Variable Index, Up:Top

Concept Index

Table of Contents