Editing User Guide

{{Documentation}}

If you can't find what you want to know, then ask at the {{ML}} (recommended) or write in [[Your voice]] page.

= 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 [http://svn.gnome.org/viewcvs/sawfish/trunk/INSTALL?view=markup 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. We advise you to take a look at the [[Programming#Sawfish_Programming_Manual|Sawfish Programming Manual]] for this.

=== Conventions used ===

{|
!Type of text
!Style
!Example
|-
|Text appearing in the GUI
|'''bold'''
|'''OK''', '''Cancel'''
|-
|Filenames
|''italic''
|''~/.sawfish/custom''
|-
|Key-strokes
|<tt>fixed width</tt>
|<tt>C-x</tt>, <tt>M-Esc</tt>, <tt>C-H-1</tt>
|}

== 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 Emacs. These events include pointer behavior and many
internal X11 events.

=== History ===

= 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, put the archive, like "BlueBox.tar.gz", under <code>~/.sawfish/themes/</code>. Then use the configurator to choose one.

You can customize the theme installation location with '<code>theme-load-path</code>', for example as:

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

By default, <code>theme-load-path</code>'s value is:
<code>"~/.sawfish/themes" "/usr/share/sawfish/themes" "/usr/share/sawfish/1.x.y/themes"</code>. Search is done in this order. Supported archives are tar, with gz, bz2, and Z compression.
It is also possible to unpack the archive, and put each theme under their own directory. For example, theme "BlueBox" should be put under <code>~/.sawfish/themes/BlueBox/</code>.

=== Instruction for beginners ===
To install the compressed archive, in a terminal as root, run the command

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

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

 tar xvf BlueBox.tar.gz

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

 mv BlueBox /usr/share/sawfish/themes

== 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 &ndash; clicking, moving the mouse, pressing a key &ndash; 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.


[[Image:Sawfish-ui_Bindings.png|center|Bindings configurator.]]


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 follow:

* '''Global:''' Bindings that have no particular context and are active anywhere.
* '''Window:''' Bindings that are active on the currently focused window.
* '''Root window:''' Bindings that are active when the pointer is in the root window (aka "Desktop").
* '''Title:''' Bindings that are active in window titles.
* '''Border:''' Bindings that are active in borders of window frames.
* '''Close button:''' Bindings that are valid for the close button.
* '''Iconify button:''' Bindings that are used for the iconify button.
* '''Maximize button:''' Bindings that are used for the maximize button.
* '''Menu button:''' Bindings that are used for the menu button.
* '''Shade button:''' Bindings that are used for the shade button.
* '''Sticky button:''' Bindings that are used for the sticky button.
* '''Lock button:''' Bindings that are used for the lock button.
* '''Rename button:''' Bindings that are used for the rename button.
* '''Move resize button:''' Bindings that are used for the move-resize button.
* '''Raise lower button:''' Bindings that are used for the raise-lower button.
* '''Prompt:''' Bindings that are used for prompts.
* '''Cycle:''' Bindings that are active when cycling through windows.


Of those contexts, only '''Global''', '''Window''', '''Root window''', '''Prompt''' 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''' and all button bindings.

Also note that '''Global''' bindings are overwritten by more specific bindings, eg:

<pre>
(bind-keys window-keymap "A-F4" 'destroy-window-safely)
</pre>

will override

<pre>
(bind-keys global-keymap "A-F4" '(system "true &"))
</pre>


[[Image:Sawfish-ui_Bindings-edit.png|center|Dialog for editing bindings.]]

=== Sample Keybinding Configuration ===

* W = WM-Modifier (check "Modifier key(s) used for default shortcuts" in SawfishConfig)
* C = Control,
* H = Hyper, 
* M = Meta,
* Super,
* S = Shift,
** be sure to check out the file KEYBINDINGS in the sourcetree!

<pre>
( bind-keys global-keymap
  "F1"      '( system "true &" )
  "W-F3"    '( system "sawfish-config &" )
  "C-W-e"   'display-errors
  "C-W-n"   'restart
  "C-W-q"   'quit
  "C-W-a"   'view-clipboard
  "W-TAB"   'cycle-windows
  "C-TAB"   'cycle-windows-backwards
  "C-W-t"   '( system "eject -T /dev/scd0 &" )
  "W-Menu"  'popup-window-menu
  "C-Menu"  'popup-root-menu
  "S-Menu"  'popup-apps-menu
  "C-W-x"   '( system "xkill &" )
  "C-W-d"   'show-desktop
  "C-S-d"   'hide-desktop
  "C-S-i"   'iconify-all-windows
  "C-S-q"   'close-all-windows
  "Print"   '( system "import -border window.png &" )
  "C-Print" '( system "import -window root root.png &" )
  "W-F2"    `( jump-or-exec "Gnome-run-dialog" "gnome-run-dialog" t )
  "W-F6"    `( jump-or-exec "Geeqie" "geeqie" nil )
  "W-F7"    `( jump-or-exec "Iceweasel" "iceweasel" t )
  "W-F8"    `( jump-or-exec "Exaile" "exaile" t )
  "W-F9"    `( jump-or-exec "Synaptic" "gksu -u root synaptic" nil )
  "W-F10"   `( jump-or-exec "Geany" "geany" t )
  "W-F11"   `( jump-or-exec "Glade-3" "glade-3" t )
  "Home"    `( jump-or-exec "Nautilus" "nautilus --no-desktop ~" t ) )
</pre>

== Matching windows ==

== Sample Configuration ==

An example sawfishrc:

<pre>
;; Window Matchers

( add-window-matcher '( ( WM_CLASS . "^Pager/pager$" ) )
       '( ( position . south-east )
          ( fixed-positon . t )
          ( never-maximize . t )
          ( never-iconify . t )
          ( frame-type . none )
          ( cycle-skip . t )
          ( window-list-skip . t )
          ( sticky . t )
          ( sticky-viewport . t )
          ( depth .  -12 ) ) )

;; Application Keymacros

( define apps-keymap ( make-keymap ) )
( bind-keys global-keymap "W-e" apps-keymap )

( bind-keys apps-keymap
  "c" `( jump-or-exec "Claws-Mail" "claws-mail" t )
  "g" `( jump-or-exec "GPRename" "gprename" nil )
  "m" `( jump-or-exec "MPlayer" "mplayer" nil )
  "o" `( jump-or-exec "Gtkorphan" "gksu -u root gtkorphan" t )
  "s" `( jump-or-exec "Screenlets-manager.py" "screenlets-manager" t )
  "t" `( jump-or-exec "Flush" "flush" nil )
  "z" '( system "gksu -u root /etc/init.d/network-manager restart &" )
  "u" '( system "gksu -u root /etc/init.d/privoxy restart &" ) )

;; Animation [Yep, Sawfish Maintainers also are Human Beeings]

( define-special-variable default-window-animator 'wireframe )
( define-special-variable anim-outline-icon-coords '( 0 . 0 ) )
( define-special-variable anim-outline-steps 45 )
( define-special-variable anim-outline-delay 15 )
( define-special-variable move-outline-mode 'cross )
( define-special-variable resize-outline-mode 'elliptical )

;; Look'n'Feel

;( define-special-variable default-frame-style 'Zami-like-saw )
( define-special-variable decorate-transients t )
( define-special-variable use-custom-font-color nil )
( define-special-variable frame-font-active-color "white" )
( define-special-variable frame-font-inactive-color "grey85" )

;; Cycling

( define-special-variable cycle-all-workspaces t )
( define-special-variable cycle-all-viewports t )
( define-special-variable cycle-raise-windows nil )
</pre>

= Sawfish and the desktop =

== Sawfish and GNOME ==

Once upon a time Sawfish was the default GNOME WM. It was replaced by MetaCity (which will be replaced by Mutter).

With Sawfish 1.6.0 the majority of the GNOME-Integration was removed in favour of desktop-independent functions.   
Integration is provided for the root-menu and default-applications as well as SawfishConfig being callable from the   
GNOME ControlCenter.

=== GNOME <= 2.22 ===

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

=== GNOME >= 2.24 ===

'''A)'''

Open the gconf-editor > navigate to /desktop/gnome/session/required_components/windowmanager and set the value to: sawfish

'''B)'''

If that doesn't work open the gconf-editor > search for keys (not schemas) called "windowmanger" or "window_manager" and      
replace metacity with sawfish, afterwards start the session-properties and add gnome-wm to the list of applications to start.

Sawfish then should be launched during the next Gnome restart.

'''C) '''Adding a GNOME/Sawfish desktop manager menu entry (probably Ubuntu >=''' '''11.10)

(Tested with lightdm, should work for GDM too problably)

<u>Note:</u> All the following has been put in a bash script: [[Sawfish_gnome_dm_setup]]

Sources:

*http://permalink.gmane.org/gmane.comp.window-managers.sawfish/9276
*https://wiki.archlinux.org/index.php/Xmonad#GNOME_3_and_xmonad
*http://askubuntu.com/a/78123/48734
With root, create the file /usr/share/gnome-session/sessions/sawfish.session with:
 [GNOME Session]
 Name=Sawfish/GNOME
 RequiredComponents=gnome-settings-daemon;gnome-panel;
 RequiredProviders=windowmanager;
 DefaultProvider-windowmanager=sawfish
 DefaultProvider-notifications=notification-osd

Create the file /usr/share/applications/sawfish.desktop with:
 [Desktop Entry]
 Type=Application
 Encoding=UTF-8
 Name=Sawfish
 Exec=bash -c 'sawfish&'
 NoDisplay=true
 X-GNOME-WMName=Sawfish
 X-GNOME-Autostart-Phase=WindowManager
 X-GNOME-Provides=windowmanager
 X-GNOME-Autostart-Notify=false
The Exec line is a bit strange but this may avoid sawfish to wait 30s before starting up.

Create the file /usr/share/xsessions/gnome-sawfish.desktop with:
 [Desktop Entry]
 Name=GNOME with Sawfish
 Comment=Gnome with the Sawfish window manager
 TryExec=/usr/bin/gnome-session
 Exec=gnome-session-sawfish
 Type=XSession
Because of a bug somewhere, you need to create the file /usr/bin/gnome-session-sawfish with:
 #! /bin/sh
 exec gnome-session --session sawfish "$@"
and make it runnable:
 # chmod +x /usr/bin/gnome-session-sawfish
Finally, gnome-panel may also wait 30s before starting up (probably because of some problem somewhere), so you can force it to start faster by adding the following line around the top of your .sawfish/rc file:
 (system "(sleep 3 && gnome-panel)&")


'''D)'''

An effective and simple solution is also to add "sawfish --replace" to the list of startup applications (i.e., GNOME starts with a different window manager, like Metacity or Compiz, which then gets replaced by Sawfish).

== Sawfish and KDE ==

Sawfish does of course work with KDE, too. Any Sawfish version will work with KDE3. For KDE4 you should use Sawfish 1.6.0,
as several focus-handling issues with KDE4 applications have been fixed. Also KDE4 integration for the root-menu, default-applications
and SawfishConfig have been added.

=== KDE 3.x ===

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

<pre>
export KDEWM=/usr/bin/sawfish
</pre>

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

<pre>
#!/bin/sh
export KDEWM=/usr/bin/sawfish
</pre>

=== KDE 4.x ===

==== Sawfish < 1.6.0 ====

create the following sawfish.desktop file:

<pre>
[Desktop Entry]
Name=Sawfish
Exec=sawfish
TryExec=sawfish
X-KDE-WindowManagerConfigure=sawfish-config
#X-KDE-WindowManagerRestartArgument=--replace
</pre>

run the following command to get a directory to save the file in:

<pre>
kde4-config --install data
</pre>

choose one of the listed directories and append '''/ksmserver/windowmanagers/''' to it, example:

<pre>
/usr/share/kde4/apps/ksmserver/windowmanagers/sawfish.desktop
</pre>

==== Sawfish >= 1.6.0 ====

a working sawfish.desktop file is provided from this version on. To choose Sawfish, simply go to:

systemsettings > personal > default applications > window manager

and choose sawfish from the combobox provided.

Then KDE will work together along with sawfish.

== Other Desktop Environments ==
For XFCE4 the following <code>~/.xsession</code> or <code>~/.xinitrc</code> file can be used:
<pre>
xscreensaver -no-splash &
sawfish &
xfce-mcs-manager
xfce4-panel &
exec xfdesktop
</pre>

= See also =
* [[Tips]]
[[Category:Documentation]]