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: FAQ, Next: Function Index, Prev: 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 ? Well I had to choose something! And hopefully it satisfies the main requirements: * There are no other computer-related users of the name (as checked in April 2000,) * It's similar enough to the old name to hopefully carry some recognition across, * It has no tenuous relationship to window-managing. 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 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 (*note 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 (*note 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 who manages it. To subscribe, send a message to 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 : 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.  File: sawfish.info, Node: Function Index, Next: Variable Index, Prev: FAQ, Up: Top Function Index ************** * Menu: * accept-x-input: Event Loop. * add-frame-class: Removing Frame Parts. * add-frame-style: Frame Styles. * allow-events: Event Loop. * bevel-image: Images. * bind-keys: Keymaps. * call-command: Commands. * call-window-hook: Standard Hooks. * check-frame-availability: Frame Styles. * clear-image: Images. * color-name: Colors. * color-rgb: Colors. * colorp: Colors. * commandp: Commands. * copy-image: Images. * create-window: Other Functions. * current-event: Event Loop. * current-event-string: Event Loop. * current-event-window: Event Loop. * cursorp: Cursors. * customize: Customization. * def-frame-class: Frame Part Classes. * default-cursor: Cursors. * defcustom: Customization. * defgroup: Customization. * delete-window: Destroying Windows. * delete-window-safely: Destroying Windows. * delete-x-property: X Properties. * destroy-window: Destroying Windows. * display-message: Display Functions. * draw-diagonal-gradient: Gradient Functions. * draw-horizontal-gradient: Gradient Functions. * draw-vertical-gradient: Gradient Functions. * draw-window-outline: Display Functions. * erase-window-outline: Display Functions. * event-name: Events. * eventp: Events. * flip-image-diagonally: Images. * flip-image-horizontally: Images. * flip-image-vertically: Images. * font-get: Fonts. * font-height: Fonts. * font-name: Fonts. * font-put: Fonts. * fontp: Fonts. * forget-button-press: Event Loop. * frame-part-get: Frame Part Definition. * get-color: Colors. * get-color-rgb: Colors. * get-cursor: Cursors. * get-font: Fonts. * get-window-by-id: Windows. * get-window-by-name: Windows. * get-x-property: X Properties. * get-x-text-property: X Properties. * grab-keyboard: Grab Functions. * grab-pointer: Grab Functions. * grab-server: Grab Functions. * hide-window: Showing and Hiding Windows. * iconify-window: Iconifying Windows. * image-border: Images. * image-dimensions: Images. * image-get: Images. * image-modifier: Images. * image-put: Images. * image-shape-color: Images. * imagep: Images. * input-focus: Input Focus. * interactive: Commands. * keymapp: Keymaps. * last-event: Event Loop. * list-x-properties: X Properties. * lookup-event: Events. * lookup-event-binding: Event Loop. * lower-window: Window Stacking. * lower-window-depth: Window Stacking. * make-image: Images. * make-keymap: Keymaps. * make-sized-image: Images. * managed-windows: Windows. * maximize-window: Maximizing Windows. * maximize-window-horizontally: Maximizing Windows. * maximize-window-horizontally-toggle: Maximizing Windows. * maximize-window-toggle: Maximizing Windows. * maximize-window-vertically: Maximizing Windows. * maximize-window-vertically-toggle: Maximizing Windows. * move-resize-window-to: Moving and Resizing Windows. * move-selected-window: Moving and Resizing Windows. * move-window-interactively: Moving and Resizing Windows. * move-window-to: Moving and Resizing Windows. * popup-apps-menu: Popup Menus. * popup-menu: Popup Menus. * popup-root-menu: Popup Menus. * popup-window-menu: Popup Menus. * proxy-current-event: Event Loop. * query-last-pointer: Pointer Functions. * query-pointer: Pointer Functions. * query-pointer-window: Pointer Functions. * raise-lower-window: Window Stacking. * raise-window: Window Stacking. * raise-window-depth: Window Stacking. * rebuild-frame: Frame Functions. * rebuild-frames-with-style: Frame Styles. * recolor-cursor: Cursors. * reframe-all-windows: Frame Styles. * reframe-windows-with-style: Frame Styles. * remove-frame-class: Removing Frame Parts. * resize-selected-window: Moving and Resizing Windows. * resize-window-interactively: Moving and Resizing Windows. * resize-window-to: Moving and Resizing Windows. * resize-window-with-hints: Moving and Resizing Windows. * restack-windows: Window Stacking. * save-stacking-order: Window Stacking. * screen-height: Display Functions. * screen-width: Display Functions. * search-keymap: Keymaps. * send-client-message: Other Functions. * server-grabbed-p: Grab Functions. * set-frame-for-window: Frame Styles. * set-frame-part-value: Frame Part Classes. * set-image-border: Images. * set-image-modifier: Images. * set-image-shape-color: Images. * set-input-focus: Input Focus. * set-window-depth: Window Stacking. * set-window-frame: Frame Functions. * set-window-frame-style: Frame Styles. * set-x-property: X Properties. * set-x-text-property: X Properties. * shade-window: Shading Windows. * show-window: Showing and Hiding Windows. * sm-add-saved-properties: Session Management. * stack-window-above: Window Stacking. * stack-window-below: Window Stacking. * stacking-order: Window Stacking. * stacking-order-by-depth: Window Stacking. * sync-server: Other Functions. * text-width: Fonts. * tile-image: Images. * toggle-window-shaded: Shading Windows. * unbind-keys: Keymaps. * ungrab-keyboard: Grab Functions. * ungrab-pointer: Grab Functions. * ungrab-server: Grab Functions. * uniconify-window: Iconifying Windows. * unmaximize-window: Maximizing Windows. * unshade-window: Shading Windows. * warp-cursor: Pointer Functions. * warp-cursor-to-window: Pointer Functions. * window-dimensions: Window Attributes. * window-frame: Frame Functions. * window-frame-dimensions: Frame Functions. * window-frame-offset: Frame Functions. * window-framed-p: Frame Functions. * window-full-name: Window Attributes. * window-get: Window Property Lists. * window-group-id: Window Attributes. * window-icon-name: Window Attributes. * window-id: Window Attributes. * window-mapped-p: Window Attributes. * window-maximized-horizontally-p: Maximizing Windows. * window-maximized-p: Maximizing Windows. * window-maximized-vertically-p: Maximizing Windows. * window-name: Window Attributes. * window-on-top-p: Window Stacking. * window-order: Input Focus. * window-order-focus-most-recent: Input Focus. * window-order-pop: Input Focus. * window-order-push: Input Focus. * window-position: Window Attributes. * window-put: Window Property Lists. * window-shaped-p: Window Attributes. * window-size-hints: Window Attributes. * window-transient-p: Window Attributes. * window-type: Frame Types. * window-visibility: Window Attributes. * window-visible-p: Showing and Hiding Windows. * window-wants-input-p: Window Attributes. * windowp: Windows. * with-server-grabbed: Grab Functions. * x-atom: Other Functions. * x-atom-name: Other Functions. * x-events-queued: Event Loop. * x-kill-client: Destroying Windows. * x-raise-window: Window Stacking.  File: sawfish.info, Node: Variable Index, Next: Concept Index, Prev: Function Index, Up: Top Variable Index ************** * Menu: * add-to-workspace-hook: Standard Hooks. * add-window-hook: Standard Hooks. * after-initialization-hook: Standard Hooks. * after-move-hook: Standard Hooks. * after-resize-hook: Standard Hooks. * alt-keysyms: Events. * apps-menu: Popup Menus. * avoid: Standard Properties. * before-add-window-hook: Standard Hooks. * before-exit-hook: Standard Hooks. * before-move-hook: Standard Hooks. * before-resize-hook: Standard Hooks. * client-message-hook: Standard Hooks. * client-set-position: Standard Properties. * configure-request-hook: Standard Hooks. * current-frame-style <1>: Frame Styles. * current-frame-style: Standard Properties. * default-bevel-percent: Images. * default-font: Fonts. * default-foreground: Colors. * default-frame-style: Frame Styles. * depth: Standard Properties. * destroy-notify-hook: Standard Hooks. * enter-flipper-hook: Standard Hooks. * enter-frame-part-hook: Standard Hooks. * enter-notify-hook: Standard Hooks. * enter-workspace-hook: Standard Hooks. * eval-key-release-events: Event Loop. * eval-modifier-events: Event Loop. * fixed-position: Standard Properties. * focus-click-through: Standard Properties. * focus-in-hook: Standard Hooks. * focus-mode: Input Focus. * focus-out-hook: Standard Hooks. * focus-proxy-click: Input Focus. * focus-when-mapped: Standard Properties. * frame-part-classes: Frame Part Classes. * frame-style <1>: Standard Properties. * frame-style: Frame Styles. * gravity: Standard Properties. * gtkrc-changed-hook: Standard Hooks. * hide-client: Standard Properties. * hyper-keysyms: Events. * iconified: Standard Properties. * iconify-window-hook: Standard Hooks. * ignore-program-position: Standard Properties. * ignore-window-input-hint: Standard Properties. * ignored <1>: Standard Properties. * ignored: Frame Styles. * image-load-path: Images. * keymap: Standard Properties. * leave-flipper-hook: Standard Hooks. * leave-frame-part-hook: Standard Hooks. * leave-notify-hook: Standard Hooks. * leave-workspace-hook: Standard Hooks. * map-notify-hook: Standard Hooks. * menu-program-stays-running: Popup Menus. * meta-keysyms: Events. * move-outline-mode: Moving and Resizing Windows. * move-show-position: Moving and Resizing Windows. * move-snap-edges: Moving and Resizing Windows. * move-snap-epsilon: Moving and Resizing Windows. * never-focus: Standard Properties. * override-frame-part-classes: Frame Part Classes. * place-mode: Standard Properties. * place-window-hook: Standard Hooks. * placed: Standard Properties. * placement-weight: Standard Properties. * post-command-hook: Standard Hooks. * pre-command-hook: Standard Hooks. * property-notify-hook: Standard Hooks. * remove-from-workspace-hook: Standard Hooks. * removed-classes: Standard Properties. * reparent-notify-hook: Standard Hooks. * resize-outline-mode: Moving and Resizing Windows. * resize-show-position: Moving and Resizing Windows. * root-menu: Popup Menus. * shade-window-hook: Standard Hooks. * shaded: Standard Properties. * shape-notify-hook: Standard Hooks. * sm-after-restore-hook <1>: Session Management. * sm-after-restore-hook: Standard Hooks. * sm-restore-window-hook <1>: Standard Hooks. * sm-restore-window-hook: Session Management. * sm-window-save-functions <1>: Standard Hooks. * sm-window-save-functions: Session Management. * sticky: Standard Properties. * sticky-viewport: Standard Properties. * system-theme-directory: Themes. * theme-load-path: Themes. * type: Standard Properties. * unbound-key-hook: Standard Hooks. * uniconify-window-hook: Standard Hooks. * unmap-notify-hook: Standard Hooks. * unshade-window-hook: Standard Hooks. * user-theme-directory: Themes. * viewport-moved-hook: Standard Hooks. * viewport-resized-hook: Standard Hooks. * visibility-notify-hook: Standard Hooks. * while-moving-hook: Standard Hooks. * while-resizing-hook: Standard Hooks. * window-depth-change-hook: Standard Hooks. * window-maximized-hook: Standard Hooks. * window-moved-hook: Standard Hooks. * window-resized-hook: Standard Hooks. * window-state-change-hook: Standard Hooks. * window-unmaximized-hook: Standard Hooks. * workspace-state-change-hook: Standard Hooks. * workspaces: Standard Properties.  File: sawfish.info, Node: Concept Index, Prev: Variable Index, Up: Top Concept Index ************* * Menu: * Attributes, of windows: Window Attributes. * Classes, of frame parts: Frame Part Classes. * Colors: Colors. * Commands: Commands. * Copying: Copying. * Cursors: Cursors. * Customization: Customization. * Desktop workspaces: Workspaces. * Destroying windows: Destroying Windows. * Display functions: Display Functions. * Event loop: Event Loop. * Events: Events. * Focus, input: Input Focus. * Fonts: Fonts. * Frame basics: Frame Basics. * Frame functions: Frame Functions. * Frame part classes: Frame Part Classes. * Frame part definitions: Frame Part Definition. * Frame parts, removing: Removing Frame Parts. * Frame styles: Frame Styles. * Frame types: Frame Types. * Frames, of windows: Window Frames. * Functions, display: Display Functions. * Functions, grab: Grab Functions. * Functions, gradients: Gradient Functions. * Functions, other: Other Functions. * Functions, pointer: Pointer Functions. * Grab functions: Grab Functions. * Gradient functions: Gradient Functions. * Hiding and showing windows: Showing and Hiding Windows. * Hooks, standard: Standard Hooks. * Iconifying windows: Iconifying Windows. * Images: Images. * Input focus: Input Focus. * Introduction: Introduction. * Keyboard focus: Input Focus. * Keymaps: Keymaps. * Maximizing windows: Maximizing Windows. * Menus, popup: Popup Menus. * Miscellaneous functions: Miscellaneous Functions. * Moving and resizing windows: Moving and Resizing Windows. * Other functions: Other Functions. * Pointer functions: Pointer Functions. * Popup menus: Popup Menus. * Properties, X: X Properties. * Property lists, of windows: Window Property Lists. * Removing frame parts: Removing Frame Parts. * Resizing and moving windows: Moving and Resizing Windows. * Session management: Session Management. * Shading windows: Shading Windows. * Showing and hiding windows: Showing and Hiding Windows. * Stacking, of windows: Window Stacking. * Standard hooks: Standard Hooks. * Standard window properties: Standard Properties. * Styles, frame: Frame Styles. * Themes: Themes. * Window attributes: Window Attributes. * Window frames: Window Frames. * Window frames, basics: Frame Basics. * Window frames, frame part classes: Frame Part Classes. * Window frames, frame part definitions: Frame Part Definition. * Window frames, functions: Frame Functions. * Window frames, removing frame parts: Removing Frame Parts. * Window frames, styles: Frame Styles. * Window frames, themes: Themes. * Window frames, types: Frame Types. * Window properties, standard: Standard Properties. * Window property lists: Window Property Lists. * Window stacking: Window Stacking. * Windows: Windows. * Windows, attributes of: Window Attributes. * Windows, destroying: Destroying Windows. * Windows, iconifying: Iconifying Windows. * Windows, input focus: Input Focus. * Windows, maximizing: Maximizing Windows. * Windows, moving and resizing: Moving and Resizing Windows. * Windows, shading: Shading Windows. * Windows, showing and hiding: Showing and Hiding Windows. * Windows, stacking: Window Stacking. * Windows, X properties: X Properties. * Workspaces: Workspaces. * X properties: X Properties.