   This is Edition 0.6, last updated 12 December 1999, of `The sawfish
Programming Manual', for sawfish, Version 0.19.

   Copyright 1999 John Harper.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Frame Functions
===============

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

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

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

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

 - Function: window-frame-dimensions window
     Return 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.

 - Function: window-frame-offset window
     Return a cons cell `(X . Y)' defining the offset from the origin
     of the client window associated with WINDOW to the origin of its
     frame.

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:

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

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.

 - Function: add-frame-style name 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.

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

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

 - Function: set-window-frame-style window style &optional type
          from-user
     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).

 - Function: set-frame-for-window window &optional force type
     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.

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

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

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

   Several window properties are used while choosing frame styles:

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

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

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

Themes
======

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

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

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

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

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

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

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

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

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

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

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, see Frame Part Definition).

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

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

Workspaces
**********

   XXX what do I want to say here?

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'). Note that these must be
special variables, i.e. initially declared using the `defvar' special
form.

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

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

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

 - Function: popup-root-menu
     Display the main menu.

 - Function: popup-apps-menu
     Displau the applications menu.

 - Variable: root-menu
     Contains the root menu definition.

 - Variable: apps-menu
     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.

 - Variable: menu-program-stays-running
     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).

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.

 - Function: eventp object
     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.

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

 - Function: event-name event
     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:

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

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

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

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,

   * `nil' or undefined (i.e. `(interactive)'); no arguments are given
     to the command, this type of interactive declaration just shows
     that the function may be called interactively.

   * A string; zero or more lines (each separated by a newline
     character), each line defines how to compute one argument value.
     The first one or two characters of each line is a prefix defining
     exactly how to compute the argument, the rest of the line is an
     optional argument which some prefixes may use.

     The currently available prefixes are,

    `e'
          The event which caused this command to be invoked.

    `E'
          The event which caused this command, cooked into a string.

    `p'
          The prefix argument as a number, this will be 1 if no prefix
          argument has been entered.

    `P'
          The raw prefix argument.

    `t'
          The symbol `t'.

    `%f'
          The window which currently has the input focus, or `nil' if no
          window is focused.

    `%w'
          The result of calling the `current-event-window' function.

    `%W'
          The result of calling the `current-event-window' function, or
          if this returns `nil' or `root', the currently focused window.

     A null line produces an argument value of `nil'.

   * Anything else; the form is evaluated and expected to return a
     _list_ of arguments to apply to the command.

   When a command is to be invoked, the `call-command' function is
used. This builds a list of argument values to apply to the command
(using its interactive declaration) then calls the command.

 - Function: commandp OBJECT
     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.

 - Function: call-command command &optional prefix-arg
     This function calls the command COMMAND interactively. See the
     documentation of `commandp' above for what constitutes a command.

     If the PREFIX-ARGUMENT is non-nil it defines the value of the
     `current-prefix-arg' variable for this command, normally the value
     of this variable would be taken from the global `prefix-arg'
     variable.

Keymaps
*******

   Keymaps are used to associate events with commands. When an event
occurs, the associated command is found and evaluated. A keymap is
simply a list whose first element is the symbol `keymap'.

 - Function: keymapp arg
     Returns `t' if ARG may be used as a keymap.

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

 - Function: bind-keys keymap &rest bindings
     Installs zero or more key bindings into the keymap KEYMAP, then
     returns KEYMAP.

     Each binding is defined by two elements in the list of BINDINGS,
     the first defines the name of 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)

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

 - Function: search-keymap event keymap
     Search for a binding of the event EVENT in KEYMAP. If a binding is
     found a cons cell `(COMMAND . EVENT)' is returned.

   There are several pre-defined keymaps that are always available:

`global-keymap'
     Keymap containing bindings active anywhere.

`window-keymap'
     Keymap containing bindings active when a client window is focused.

`root-window-keymap'
     Keymap containing bindings active when the pointer is in the root
     window.

`title-keymap'
`border-keymap'
     Keymaps active in the title and borders of window frames.

`close-button-keymap'
`iconify-button-keymap'
`maximize-button-keymap'
`menu-button-keymap'
     Keymaps active in the standard window frame buttons.

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:

   * If the variable `override-keymap' is non-nil, then this is the
     only keymap searched

   * Otherwise three keymaps are searched:

       1. the `keymap' property of the currently "clicked" frame part
          if there is one,

       2. the `keymap' property of the currently focused window

       3. the contents of the variable `global-keymap'.

   Note that for `ButtonRelease' events, the frame part's keymap is
only searched if the pointer is actually within the frame part when the
release event occurs.

   If no binding may be found in any of the active keymaps, then the
`unbound-key-hook' hook is called. This is an `or' type hook--the first
function that returns non-nil will terminate the hook call.

 - Function: lookup-event-binding event
     Perform the usual binding lookup for the event object OBJECT.
     Returns the command found, or `nil' if no binding exists.

   By default, both key-release events, and events that are bound to
modifier keys (e.g. <Control_L>), are ignored. However, this behavior
may be changed:

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

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

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

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

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

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

 - Function: last-event
     Return the previous event which occurred.

 - Function: proxy-current-event window &optional mask propagate
     Send the current X event to WINDOW, either a window object, a
     numeric window id, or the symbol `root'. If a `ButtonPress' event
     the pointer grab will be released first.

     MASK may be an integer defining the X event mask to pass to the
     `XSendEvent' function. If not defined, a mask is chosen that would
     usually be used to select the type of event being proxied.

 - Function: allow-events mode
     This is a wrapper for the `XAllowEvents' function. The MODE
     parameter may be one of the following symbols: `async-pointer',
     `async-keyboard', `sync-pointer', `sync-keyboard',
     `replay-pointer', `replay-keyboard', `async-both', `sync-both'.

     Events that have to be grabbed to be received (i.e. all bindings
     in the `global-keymap' and the `window-keymap') are grabbed
     synchronously. This means that no more events will be received
     until either the command returns, or `allow-events' is called.

     This is normally not important, but if the command expects to
     receive further events it must call `allow-events'. See the
     interactive move and resize functions for an example.

 - Function: forget-button-press
     Cause the next button press to be treated as a single click event,
     no matter how soon it occurs after the prevous button-press event.

 - Function: accept-x-input &optional mask
     Handle any X events received. If MASK is non-nil then only events
     matching this numeric value are handled (see the X header files for
     details).

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

Miscellaneous Functions
***********************

Pointer Functions
=================

 - Function: query-pointer &optional from-server
     Returns a cons cell `(X . Y)' representing the current mouse
     pointer position, relative to the origin of the root window.

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

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

 - Function: query-last-pointer
     Returns a cons cell `(X . Y)' representing the second most recent
     mouse pointer position, relative to the root window.

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

 - Function: warp-cursor-to-window window &optional x y
     Move the mouse pointer to position (X, Y) relative to the client
     window associated with object WINDOW.

     If X and Y are `nil', then they are taken as the top-left corner
     of the window's frame.

Grab Functions
==============

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

 - Function: ungrab-server
     After a call to `grab-server' this will allow other clients to
     access the X server again.

     Note that calls to `grab-server' and `ungrab-server' _nest_.

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

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

 - Function: grab-pointer &optional window cursor
     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.

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

 - Function: grab-keyboard &optional window
     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.

 - Function: ungrab-keyboard
     Release the grab on the keyboard.

Display Functions
=================

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

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

 - Function: draw-window-outline mode x y width height
     Draw an outline of a window of dimensions (WIDTH, HEIGHT) at
     position (X, Y) relative to the root window.

     MODE is a symbol defining the type of outline drawn, currently it
     may only be `box' for a 3x3 grid.

     Use the `erase-window-outline' to erase the grid. Also note that
     since these functions draw directly on the root window the server
     should be grabbed until the outline is erased.

 - Function: erase-window-outline mode x y width height
     Erase a previously drawn outline of a window of dimensions (WIDTH,
     HEIGHT) at position (X, Y) relative to the root window.

     MODE is a symbol defining the type of outline drawn, currently it
     may only be `box' for a 3x3 grid.

 - Function: display-message &optional text attributes
     Display the string TEXT in a window on the screen. If TEXT is
     `nil' then any string previously displayed is removed. Returns the
     numeric id of the window displaying the message, or `nil' if no
     message is displayed.

     ATTRIBUTES is an alist specifying how the string should be
     displayed; each element of the list is a cons cell `(ATTR .
     VALUE)' associating an attribute ATTR (a symbol) with it's value.

     Possible attributes currently include:

    `font'
          The font to use

    `foreground'
          The color (or color name) to draw the text with

    `background'
          The color (or color name) to draw the background with

    `x-justify'
          The justification method for multi-line strings. One of the
          symbols `left', `right', or `center'

    `spacing'
          The number of extra pixels of vertical spacing to leave
          between text lines.

    `position'
          A cons cell defining the coordinates at which to display the
          message window. The cell is `(X . Y)'. X and Y are integers
          or `nil' (for centered display). If negative they count in
          from the left and bottom edges respectively.

    `head'
          The head on which to center the message when a position is
          not specified or given as nil.  If not provided defaults to
          the head containing the window that has the input focus.

Gradient Functions
==================

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

 - Function: draw-vertical-gradient image from to
     Draw a vertical color gradient in IMAGE. The color at the top of
     the image will be FROM, the color at the bottom TO, with a smooth
     transition between.

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

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

Other Functions
===============

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

 - Function: send-client-message window type data format
     Send an X `ClientMessage' event to WINDOW (a window object, the
     symbol `root' or a numeric xid).

     The event will be of the type TYPE (a symbol), contain the array
     of integers DATA (i.e. a vector or a string), and will be
     transferred as FORMAT sized quantities (8, 16 or 32).

 - Function: create-window parent x y width height
     Create an unmapped window that is a child of PARENT (a window
     object, an integer window id, or the symbol `root'), with the
     specified dimensions.

     Returns the window id of the new window.

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

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

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

   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.

 - Function: call-window-hook hook window &optional args hook-type
     Call HOOK for WINDOW with further arguments ARGS. See `call-hook'
     for a description of HOOK-TYPE. Each function in the hook is
     called with arguments `(WINDOW . ARGS)'.

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

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.

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:

 - Function: sm-add-saved-properties &rest properties
     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:

 - Variable: sm-window-save-functions
     A list of functions, each of which is called when the state of each
     window is saved. Each function is called with a single argument
     (the window) and should return a list of alist elements that will
     be saved in the state file. (As such, only values with valid read
     syntaxes may be included.)

 - Variable: sm-restore-window-hook
     List of functions called when the state of a window is restored.
     Each is called with arguments `(WINDOW ALIST)', where ALIST
     defines the state saved for the window.

     Each function should look for the properties it saved, and then
     take any action dependent on the values.

   The following hook is also called.

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