This is Info file sawfish.info, produced by Makeinfo version 1.68 from the input file sawmill.texi. START-INFO-DIR-ENTRY * sawfish: (sawfish). sawfish programming manual END-INFO-DIR-ENTRY 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.  File: sawfish.info, Node: Frame Functions, Next: Frame Types, Prev: Frame Part Definition, Up: Window Frames 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.  File: sawfish.info, Node: Frame Types, Next: Frame Styles, Prev: 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: - Function: window-type WINDOW Returns a symbol naming the frame type currently associated with WINDOW.  File: sawfish.info, Node: Frame Styles, Next: Themes, Prev: 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. - 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 (*note 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.  File: sawfish.info, Node: Themes, Next: Removing Frame Parts, Prev: 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... - 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.  File: sawfish.info, Node: Removing Frame Parts, Prev: 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, *Note 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.  File: sawfish.info, Node: Workspaces, Next: Popup Menus, Prev: Window Frames, Up: Top Workspaces ********** XXX what do I want to say here?  File: sawfish.info, Node: Popup Menus, Next: Events, Prev: 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, *note 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'. - 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).  File: sawfish.info, Node: Events, Next: Commands, Prev: 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. - 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 , and 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 or keysym assigned to it. The `M' virtual modifier is assigned to the X modifier with either or 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 key held would be described as `M-Button1-Click1', while pressing the key with 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.  File: sawfish.info, Node: Commands, Next: Keymaps, Prev: 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, * `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.  File: sawfish.info, Node: Keymaps, Next: Event Loop, Prev: 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'. - 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.  File: sawfish.info, Node: Event Loop, Next: Miscellaneous Functions, Prev: 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 *Note Standard Hooks::. Keyboard and pointer events are translated to their Lisp equivalents (*note 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. ), 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.  File: sawfish.info, Node: Miscellaneous Functions, Next: Standard Hooks, Prev: Event Loop, Up: Top Miscellaneous Functions *********************** * Menu: * Pointer Functions:: * Grab Functions:: * Display Functions:: * Gradient Functions:: * Other Functions::  File: sawfish.info, Node: Pointer Functions, Next: Grab Functions, Up: 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.  File: sawfish.info, Node: Grab Functions, Next: Display Functions, Prev: Pointer Functions, Up: Miscellaneous Functions 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.  File: sawfish.info, Node: Display Functions, Next: Gradient Functions, Prev: Grab Functions, Up: Miscellaneous Functions 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.  File: sawfish.info, Node: Gradient Functions, Next: Other Functions, Prev: 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.) - 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.  File: sawfish.info, Node: Other Functions, Prev: Gradient Functions, Up: Miscellaneous Functions 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.  File: sawfish.info, Node: Standard Hooks, Next: Standard Properties, Prev: 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 *Note Normal Hooks: (librep)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. - 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 (*note 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, *Note 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.  File: sawfish.info, Node: Standard Properties, Next: Session Management, Prev: 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 (*note 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. *Note 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. *Note 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'. *Note Frame Types::. `frame-style' The frame style explicitly chosen by the user, or unset. *Note Frame Styles::. `current-frame-style' The frame style currently used for the window. *Note Frame Styles::. `removed-classes' A list of frame part classes removed from the decorations of this window. *Note Removing Frame Parts::. `shaded' Is the window shaded? *Note 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. *Note 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? *Note 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.  File: sawfish.info, Node: Session Management, Next: FAQ, Prev: 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: - 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.