1 User Documentation for Sawfish 1.5.0
**************************************

  1. Introduction

     If you know the basics of X11, you can skip to the next section.

       1. What is that X11 thing?

          In the 80s at MIT a graphical system for computers was
          developed. Some of the idea behind it was to be
          multiplattform, have network transparency and provide the
          means to have graphics, but not enforce rules like how things
          should look or behave. The solution found was creating a
          protocol (think "language") that defined how programs and
          computers should communicate to each other to do request and
          provide the results.

          As time passed, different versions of the protocol were done,
          up to the 11th. Of this 11th version there have been multiple
          releases, so you can see references to X11R5; the latest
          being X11R7. Other names you can see when refering to the
          protocol or to the systems that implements it are the full
          name, X Window System (singular window, not windows), or even
          just the X letter alone.

          On other fronts, the global result of X11 and the
          applications that run on it is like many other graphics
          systems for computers: you have pointers controlled by
          devices such as mouses or tablets, keyboards to input text,
          monitors to show things such as windows, icons, menus. And
          you can probably have multiple items of each, even accross
          different computers. The X11 flexibility obtained by
          definining the language but not the rules have allowed it to
          survive for to decades, and at the same time evolve to
          include new concepts.

       2. What is a Window Manager?

          As we said, X11 provides the means to have graphics, but
          leaves to others tasks such as how things have to look or
          behave. A Window Manager (WM for short) is a special type of
          program that runs on X11 and which main tasks are organizing
          windows of other programs.

          If you ever run X11 without a WM, programs will show their
          windows without any decoration and placement on the screen
          would leave a lot to be desired. You probably will be unable
          to move windows, for example.

          Window Managers, such as Sawfish, take care of all that,
          provide decorations to windows (title bars, side and bottom
          frame, etc), decide where to place them, in which order they
          should overlap, when they should move or resize, what window
          will receive your keypresses, etc.

       3. Why Sawfish?

          Sawfish is a very fast and extensible Window Manager.

          Powerfull key bindings: virtually every function can be bound
          to keys or mouse buttons or combinations of them. If you
          want, you can run without touching the mouse for a long time.

          Hooks: many events like moving or changing workspace (more on
          this later) can trigger extra functions to make the behavior
          fit your needs. So when you change workspace, you can trigger
          a wallpaper change by putting the right function call in the
          hook that is triggered by change workspace action.

          Window matching: for each new window Sawfish can assign
          different behaviours as they are created. For example you can
          set some windows to always appear like if they were glued to
          your monitor, above any other window, like in the case of
          taskbars.

          Flexible theming: Sawfish allows very different themes to be
          created and a variety is already available. You can even run
          different themes at the same time.
          http://sawfish.wikia.com/wiki/Themes

          Extensibility: Sawfish can load 3rd party scripts easily and
          a whole bunch is just waiting to be discovered by you.
          http://sawfish.wikia.com/wiki/Scripts

       4. What are those Mouse Button 2?

          You probably know about Shift or Control keys, that you can
          press at the same time than others to get different results,
          like Shift and "a" to get uppercase A. X11 inherits some
          extra modifier keys from past computers that had really
          special keyboards like the Space Cadet keyboard. In modern
          keyboards unused keys can emit these key symbols, or even
          multiple symbols from the same key.

          The avaliable extra key symbols you will see are Meta (pretty
          common to be in Alt key... probably emiting Alt symbol at the
          same time) and Hyper & Super (both typically assigned to the
          keys with logos). Hyper and Meta can be shortened to H and M,
          as well as C for Control, A for Alt and S for Shift.

          Mouse buttons in X11 are also named, allowing different
          hardware to be used easily as applications only have to
          support and document things like Mouse Button number 1, no
          matter if the mouse is configured for right hand, left
          hand... or is a tablet with a pen. Sometimes you will see the
          names shortened to MB1, MB2, etc. The typical configuration
          for a right handed mouse is MB1 left button, MB2 center
          button or press wheel, MB3 rigth button, with wheel rotation
          creating virtual presses and releases of MB4 and MB5 with
          every fraction of turn.

          For futher reading, please refer to the documentation of your
          X system, specially xev and xmodmap programs.


  2. Basic Window Managing Functions

       1. Window-Menu

          The window-menu is a menu which offers you an easy way to
          modify the current window.

          You can access it by left-click on the menu button, or
          middle-click on the close or iconify button

       2. Iconify

          To iconify a window means to display a small icon, or
          task-list entry representing the window, instead of
          displaying the whole one, You may know that feature as
          "Minimize", which is a different term, having the same
          meaning.

          You can iconify a window by left-click on the iconify button.

       3. Uniconify

          To uniconify a window means to restore a previously iconified
          window, to it's prior state.

          You can uniconify a window by left-click on it's dock-icon or
          task-list entry.

       4. Maximize

          To maximize a window means to make it as big as possible, but
          without overlapping panel or dock windows, which may be there.

          You can maximize a window by left-click on the maximize
          button.

       5. Unmaximize

          To unmaximize a window means to restore it to the size it got
          before it has been maximized (therefore only maximized
          windows can be unmaximized).

          You can unmaximize a window by left-click on the maximize
          button, on a maximized window.

       6. Delete Window

          To delete a window simply means to close it, any transient
          (sub-windows, belonging to that main-window) will be deleted,
          too.

          You can delete a window by left-click on the close button.

       7. Shade Window

          To shade a window means to only display the titlebar.

          You can shade a window by double-left-click on the titlebar
          or left-click on the shade button

       8. Unshade Window

          To unshade a window means to restore a previously shaded
          window.

          You can unshade a window by double-left-click on the titlebar
          or left-click on the shade button, of a shaded window.

       9. Raise Window

          To raise a window means to put it above other windows.

          To raise a window press ALT + UP (Arrow Up Key).

      10. Lower Window

          To lower a window means to put it below other windows.

          To lower a window press ALT + DOWN (Arrow Down Key).

      11. Cycle Windows

          To cycle trough windows simply means that you'll look trough
          all windows and as you stop the currently cycled window will
          be the new active window.

          You can cycle trough windows by keeping ALT pressed and press
          TAB one time for each window to cycle.

          There's also the possibility to cycle backwards, but that is
          not bound to any keybinding by default.


  3. Organizing Windows

     Sawfish offers multiple means to organize windows, most can work at
     the same time than others, as you need.

       1. Workspaces

          Workspaces are virtual surfaces where to place windows. They
          are also called (Virtual) Desktops in other WMs. You must
          have at least one.

          Windows can be in one or more workspaces at the same time,
          with different positions in each.

       2. Viewports

          Workspaces can be bigger than your monitor, here is where the
          concept of Viewport comes into play, it gives you a view into
          this bigger space. All Workspaces must share the same size,
          though, like if they were cut all at once.

          You can move the Viewport around, and you will see how
          windows that go out of the right side of the screen will
          appear from the left, if you moved your viewport to the
          right. It is a continous surface. The scrolling can be in
          full monitor increments or partial.

       3. Layers

          Sometimes you want to keep some windows above all other
          windows. Or maybe below them. Sawfish does this by means of
          Layers. A window in a layer will always appear in a given
          depth, above lower valued layers, but below.

          Default level is 0, windows below are in negative levels, and
          windows above are in positive levels. Many WMs support just
          three layers, Sawfish by default assigns them the numbers -2,
          0 and 2.

       4. Tabs