User Guide

Introduction

Welcome to the Sawfish User Guide

Welcome to the Sawfish User Guide, the starting point for all questions regarding the use and configuration of your Sawfish window manager.

You can just skim through this document and come back later for specific questions or read it straight from top to bottom; do as you prefer. In either instance you should read this introduction so that you know what this User Guide will and won't cover and what the different conventions it uses are. After that you are free to continue on your own :-)

What the User Guide aims to be

The Sawfish User Guide aims to give you a first start on how to use and configure your Sawfish window manager for your every day work. It assumes no prior knowledge of its topic and aids you with step-by-step instructions as well as examples for the most common tasks.

It's supposed to be the first point of reference for any simple Sawfish configuration question and to provide you with links to sources of further information in case you have problems.

Finally you should find some tips and tricks showing you the most useful and impressive features of Sawfish shedding light on ways to save your time and effort.

What the User Guide is not

This User Guide assumes you have a working installation of Sawfish on your computer, either compiled from the sources or via a binary package of your distributor. It will not cover the topic of how to install Sawfish. If you have trouble installing Sawfish please read the Download and Install documentation.

It will also not cover how to interact with the Sawfish Lisp environment. Its build-in Lisp interpreter is what makes Sawfish the powerful window manager that it is, so if you want to master Sawfish and make the best use of it you will have to get familiar with its Lisp capabilities. A complete discussion of this complex topic is beyond the scope of this document. I advice you to take a look at the Sawfish Programming Manual for this.

Conventions used

Type of text	Style	Example
Text appearing in the GUI	bold	OK, Cancel
Filnames	italic	~/.sawfish/custom
Key-strokes	fixed width	C-x, M-Esc, C-H-1

A quick overview of Sawfish

Philosophy

Sawfish is a lisp-extensible window manager for X11. Its aim is to allow all areas of window management (decoration, manipulation) to be customized as far as is possible, yet still remain as fast or faster than existing window managers.

Despite this extensibility its policy is very minimal compared to most window managers. It does not implement desktop backgrounds, applications docks, or other things that may be achieved through separate applications.

All high-level window management functions are implemented in Lisp for future extensibility or redefinition. Also, most received events are exported to the Lisp environment through key-bindings and hooks, similar to in Emacs. These events include pointer behavior and many internal X11 events.

Using Sawfish

Viewports and Workspaces

The concept of virtual desktop may refer to two different mechanisms.

• Workspaces: there can be multiple distinct desktops, all independent from each other. Only a single desktop can be viewed at a time. The windows can reside on each one of them (sticky windows), and windows can be sent from one desktop to the other.

• Viewports: the size of a single desktop can be higher than the screen size. In that case only a portion of the desktop is seen at a time, and that is called a viewport. If the desktop is four times the width of the screen, there are four possible viewports. The windows can appear on every viewport, and even across the border between adjacent viewports.
  • Until a patch is available which will undeprecate viewports, the only way to enable bindigs for viewports is by running (either inside sawfish-client or from within ~/.sawfishrc):

(setq customize-command-classes '(default viewport deprecated))

Customizing Sawfish

Themes

To install a theme, you need to install the theme into a directory included into the theme-load-path. You can customize such a variable in your sawfish RC file, for example setting it with:

(setq theme-load-path
     (append (list
              "~/share/sawfish/themes"
              "~/.sawfish/themes")
             theme-load-path))

In this way you'll be able to install themes on your home, without the need for special permissions to write in administrative directories.

For example to install a theme into /usr/share/sawfish/themes, you could simply copy the theme compressed archive or you can decompress the theme archive into the /usr/share/sawfish/themes directory. The supported archive formats are .zip, tar.gz and tar.bz2. If you download the theme BlueBox, you will get a tar archive called "BlueBox.tar.gz".

To install the compressed archive, in a terminal as root, run the command

cp BlueBox.tar.gz /usr/share/sawfish/themes

If instead you want to install a decompressed archive, go to the directory where you saved the tar archive, and run the command

tar -xzvf BlueBox.tar.gz

You will have a directory called "BlueBox". As root, run the command

mv BlueBox /usr/share/sawfish/themes

And then using your sawfish customization, choose the theme.

Key and mouse bindings

What are bindings?

Whenever you interact with Sawfish in one way or another it usually involves some kind of binding: Whether it's dragging a window across the screen with your mouse, switching workspaces or closing a window via a combination of keys. All of this follows the same general scheme: You, the user, perform some kind of action – clicking, moving the mouse, pressing a key – to which Sawfish responds in a particular (and hopefully desired) fashion. This association between user performed inputs and Sawfish behavior is called binding.

Most window managers today provide a way to customize bindings. While it's usually possible to bind keys to launch applications and perform simple and common operations like minimizing a window, mouse events are often predefined and can't be changed at all. Sawfish on the other hand allows for full customization of bindings. Even if you don't notice it, every reaction to your inputs is specified by a binding and can be altered.

But bindings in Sawfish are specified by more than just a user input. You obviously don't want one action to have the same effect in every situation. Clicking on a window title should have a different effect than clicking on the root window. That's why you can define contexts for your bindings. Depending on the context, your actions have different outcomes. Clicking on the title of a window might raise it, while clicking on the window itself could raise and focus it. And clicking on the root window would pop up the application menu.

Customizing bindings

To customize your mouse and key bindings launch the Sawfish Configurator and switch to the "Bindings" tab.

Here you have a list of all the bindings defined for the context selected in the "Context" box. There are eleven different contexts you an specify bindings for. Their meanings are as followed:

• Global: Bindings that have no particular context and should by active anywhere.
• Window: Bindings that are active when a window is focused.
• Root window: Bindings that are active when the pointer is in the root window.
• Title: Bindings that are active in window titles.
• Border: Bindings that are active in borders of window frames.
• Close button: Bindings that are active in the close button.
• Iconify button: Bindings that are active in the iconify button.
• Maximize button: Bindings that are active in the maximize button.
• Menu button: Bindings that are active in the menu button.
• Shade button: Bindings that are active in the shade button.
• Cycle: Bindings that are active when cycling through windows.

Of those contexts only Global, Window, Root window and Cycle work with key-only bindings. When a window is focused there is no other way to determine a user input is supposed to invoke, for example, the Close button binding than clicking on the close button. The same is true for Title, Border, Iconify button, Maximize button, Menu button and Shade button bindings.

Also note that Global bindings are over-written by more specific bindings.

Sample Keybinding Configuration

W = Alt C = Control, M = whatever is set as "Modifier key(s) used for default shortcuts" in the config tool, (Not used in this example, but possible: H = Hyper, Super, S = Shift, ...)

( bind-keys global-keymap "W-TAB" 'cycle-windows )
( bind-keys global-keymap "C-TAB" 'cycle-windows-backwards )
( bind-keys global-keymap "W-C-i" 'iconify-window )
( bind-keys global-keymap "W-C-m" 'maximize-window )
( bind-keys global-keymap "W-C-w" 'unmaximize-window )
( bind-keys global-keymap "W-C-h" 'maximize-window-horizontally-toggle )
( bind-keys global-keymap "W-C-v" 'maximize-window-vertically-toggle )
( bind-keys global-keymap "W-C-f" 'maximize-window-fullscrren-toggle )
( bind-keys global-keymap "W-C-s" 'shade-window )
( bind-keys global-keymap "W-C-u" 'unshade-window )
( bind-keys global-keymap "W-C-e" 'display-errors )
( bind-keys global-keymap "W-F4" 'delete-window-safely )
( bind-keys global-keymap "W-C-KP_Up" 'grow-window-up )
( bind-keys global-keymap "W-C-KP_Right" 'grow-window-right )
( bind-keys global-keymap "W-C-KP_Down" 'grow-window-down )
( bind-keys global-keymap "W-C-KP_Left" 'grow-window-left )
( bind-keys global-keymap "W-C-Up" 'move-viewport-up )
( bind-keys global-keymap "W-C-Right" 'move-viewport-right )
( bind-keys global-keymap "W-C-Down" 'move-viewport-down )
( bind-keys global-keymap "W-C-Left" 'move-viewport-left )
( bind-keys global-keymap "W-C-q" 'quit )
( bind-keys global-keymap "W-C-b" 'restart )
( bind-keys global-keymap "W-C-p" 'show-programmer-manual )

Sample Configuration

Here's an Example Configuration:

( You will find all scripts for this configuration at this Wiki -> Scripts )

An overview of (almost) all Sawfish-Options can be found in the OPTIONS file found in the tarball.

; Defaults

( require 'sawmill-defaults )

; Alternative prompt.jl

( require 'prompt2 )

; Show Viewport options in Sawfish-UI

( require 'sawfish.wm.viewport )
( define-special-variable customize-command-classes '(default viewport) )

; 3 times 3 Viewports per Workspace

( setq viewport-dimensions '(3 . 3) )

; Enable Edge Fliping

( require 'sawfish.wm.ext.edge-flip )

; Edge Fliping Type (workspace or viewport)

( define-special-variable edge-flip-type 'workspace )

; Edge Fliping Delay (in milliseconds)

( define-special-variable edge-flip-delay 100 )

; Draw a wireframe on Move/Resize

( define-special-variable move-outline-mode 'box )
( define-special-variable resize-outline-mode 'box )

; Window History [Remember Size/Position of Windows]

( require 'sawfish.wm.ext.window-history )

; Display Sawfish Session Uptime

( require 'uptime )

; Make unfocused Windows Transparent (need: xcompmgr, transset)

( require 'native-focus-transparency )

; Transparency of unfocused Windows

( define-special-variable out-of-focus-trans '0x25000000 )

; Transparency of focused Windows

( define-special-variable in-focus-trans '0x00000000 )

; Warp the pointer to newly un-iconfied windows

( setq warp-to-window-enabled t )

; Warp to the middle of the Window

( setq warp-to-window-offset '(50 . 50) )

; Warp the pointer also when cycling through windows

( require 'sawfish.wm.commands.x-cycle )

(eval-in
  `(let
       ((old-raise-window* raise-window*))
     (define (raise-window* win)
       (warp-cursor-to-window win)
       (old-raise-window* win)))
  'sawfish.wm.commands.x-cycle)

; Animated Window Move

( require 'animated-move )

; Fluxbox like Tabs (New Version)

( require 'tab )
( require 'tabgroup )
( require 'tab-keymap )
( require 'marks )

; Undo Redo Window Manager Actions like in an Editor

( require 'multi-level-undo )

; Window Gravity

;( define-special-variable configure-auto-gravity t )

; Placing Mode

;( define-special-variable place-window-mode 'best-fit )

; window focusing across workspaces

(require 'sawfish.wm.util.stacking)

(define (enter-workspace-focus)
  (when (input-focus)
    (raise-window* (input-focus))))

(add-hook 'enter-workspace-hook enter-workspace-focus)

Sawfish and the desktop

Sawfish and GNOME

Sawfish used to be the default window manager for Gnome, so it still has a good level of integration with it (first of all, it uses the GTK widgets, essential component of the Gnome project). Actually Gnome uses by default another window manager, namely Metacity.

The easiest way to make Gnome use Sawfish as its window manager is to add Sawfish to the list of autostarted Applications:

 System -> Preferences -> Sessions (or run: gnome-session-properties)

select the "Current Session" tab, *to remove* the current window manager from the list, start sawfish and set its "style" property to "Restart".

Sawfish then should be launched during the next Gnome restart.

Sawfish and KDE

To use sawfish inside KDE you have to set $KDEWM environmental variable just before the startkde command, like this:

export KDEWM=/usr/bin/sawfish

For example following code could be put inside your ~/.kde/env/startsawfish.sh file

#!/bin/sh
export KDEWM=/usr/bin/sawfish

Then KDE will work together along with sawfish.

Other Desktop Environments

For XFCE4 the following ~/.xsession or ~/.xinitrc file can be used:

xscreensaver -no-splash &
sawfish &
xfce-mcs-manager
xfce4-panel &
exec xfdesktop