

uwm Users Manual

by Christian Ruppert

\tableofcontents



1 Introduction

1.1 A users' manual for a window manager?

Hmmm, now that uwm is more and more growing up I think it is time for
some kind of a users manual for all you guys out there who are wondering
how and why to use this strange thing which is so different to anything
you have ever seen before. In fact I decided to write this manual
when I got a mail from our project leader Jan in which he was complaining
that a window is always moved in the stacking position it has been
before moving it. I realized that uwm is so different that it is almost
impossible to find out all its features and use its full power without
any advice.

1.2 The idea of uwm

Well, the idea of uwm is very simple: Make work under X more productive
and (after a little bit of training) more intuitive. Developing uwm
I did (and still do) not try to copy the look and feel of other window
managers for the ude-wm just because everyone knows this. If I wanted
to do this it would have been much easier to make fvwm fit to our
needs. What I wanted to do was just using my impressions of other
different GUIs and my experience working with them to create a more
practical and agreeable one. And once you are used to the title bar-less
layout of uwm you will not want to miss it anymore (I hope).

When you read the following you might want to try most of it at the
same time since it is not very easy to learn or even to imagine how
uwm will react to a user's input if you only read this documentation.
Oh, and you will need a three-button-mouse to use the full power of
uwm (although uwm can now also be used with a two-button-mouse and
Emulate3Buttons).

2 Basic window operations

2.1 moving windows

To move a window under uwm just hold down the middle mouse button somewhere
on the desired window's border while dragging the window to the destination
point and then release the button. While dragging (with the middle
button pressed) you can raise the dragged window by clicking with
the left button as well as lower it by clicking with the right button.

2.2 resizing windows

To resize a window just hold down the right mouse button somewhere
on its border and move the mouse and the appearing rubber band around
until size and position are o.k. before you release the button again.
While doing this several action can be taken: The window can be risen
by pressing the middle button once, it will be restored to its original
size by pressing the button once again and re-risen by pressing the
button for a third time etc. The other way round a risen window's
size can be restored by pressing the middle button once, it will be
re-risen when you press it a second time and so on. Pressing the left
button while resizing a window with the mouse pointer directly south
or north of the window will restore the windows original width, pressing
it exactly right or left of the window will restore its original height.

2.3 the left mouse button

Pressing the left mouse button on a window's border will first of all
raise the window to the top of the stack and then display a menu of
hexagonal icons which replaces the title bar icons known from other
window managers. This is one of uwm's main advantages: You do not
have to dig out an almost completely covered window's title-bar -
just to close it for example. The menu will disappear again when you
release the button so you have to press the button, select an icon
and release the button above the selected icon to take the desired
action. Possible actions are (starting with the top icon and continuing
clockwise):

* close window

* kill program (when this icon is highlighted another icon will appear
  on the right side as a security request. To kill a window you have
  to select this icon)

* menu

* auto rise / restore size

* lower window

* iconify window

If the mouse button is released without one of the icons selected the
window is simply raised to the top.

The item ``menu'' will start a menu which will enable you to sticky
a window or to move it directly to another workspace.

If the middle-button is pressed and released again while the window-menu
is active, uwm will switch to the previous workspace and take the
active window there. This can be done repeatedly. If the right button
is pressed the window is taken to the next workspace instead.

3 other operations

3.1 The Window and Workspace Menu

If you click the middle mouse button outside any window the window/workspace
menu will appear. If you have more than one workspace you'll find
a list of your workspaces there (plus an extra item for sticky windows
which are displayed on any workspace). Each item has a sub menu containing
a list of the windows currently on the corresponding workspace. Next
to each item of the sub menus there is a little switch which is switched
on in case the window is visible and switched off if the window is
iconified. To de-iconify a window just select its Item. Same thing
to raise and activate an already displayed window. If the selected
window is not on the active workspace uwm will switch to the workspace
it can be found on before de-iconifying or activating it.

To switch to a workspace without raising or de-iconifying a window
(or even without any windows on it), just release the mouse button
above the item of the main menu which opens the sub menu with the
windows without moving the pointer into the sub menu.

In case there is only one workspace there is no need for a menu for
the workspaces and a menu containing all windows on the screen (plus
iconified) is directly displayed.

3.2 The application-menu

Clicking down the right mouse button somewhere outside any window will
make an application-menu appear that can be used to call any programs
you have installed. Simply hold down the button, select the desired
program and release the button. To cancel the menu simply release
the button somewhere outside of the menu.

3.3 Configuring uwm

At the moment uwm-configuration can only be done by editing the corresponding
text-files. A graphical configuration program will be available as
soon as I got the desktop-server running (I hope very soon).

3.3.1 General configuration

Please set the environment variable UDEdir to the directory ude is
installed to. uwm will thank you for this.

General uwm-configuration can be done by changing the file $UDEdir/config/uwmrc
in the which should be quite self-explaining. You can keep a personal
copy or version of all configuration files in your home-directory
in \~{ }/.ude/config which will be used instead of your systems default
files in the ude-directory. You can also have your private language
files in /.ude/language.

You may use environment variables in filenames and shell commands.

For details about the file-formats please take a look at the example-files
shipped with your distribution, all options are explained there, a
GUI-program to modify the config files will be available when there
is enough desktop-functionality added into uwm/ude so that it can
be included into the desktop and can be taken as an example about
how to write ude programs.

3.3.2 Changing the application menu

The file for the menu is defined in the uwm-main-configuration file
config/uwmrc. In case no file is found for any reason uwm will give
you a simple xterm in the application-menu so that you can do at least
minimum work if something goes wrong. The paths uwm will search for
the specified file are first \~{ }/.ude/config, in case the file is
not found there it will look into $UDEdir/config. In case there is
still no file found the given path will be interpreted as it is. The
name in the example uwmrc is appmenu.

To use quotes in quoted expressions type \'' instead of '', if you want
to use a backslash type \\.

You can use environment variables in shell commands and filenames.

There are five keywords for the menu-configuration-file:

ITEM ``name'':``command''; will add an item called ``name'' that
  will execute ``command'' to the menu or sub menu it belongs to.
  ``command'' can be a complete shell command with the name of the
  program and several command-line-options. Both ``name'' and ``command''
  have to be quoted.

SUBMENU ``name'' { } will add a sub menu called ``name'' to the menu
  or sub menu it belongs to. All items and submenues belonging to
  this sub menu must be placed between the braces. ``name'' must be
  quoted.

LINE; will add a separation line to the menu it belongs to.

FILE ``filename''; Will replace itself by the given file which also
  has to be a menu-file. This will enable you to include several files
  into one menu-file. The search-algorithm is the same as for menu-file
  specified in uwmrc. New Items are not stupidly added to a menu but
  merged into it i.e. if there's e.g. a global configuration file
  loaded adding an item ``gimp'' to the sub menu ``graphics'' this
  will only be done if there is no item named ``gimp'' in this sub
  menu yet. Please be aware that the position of the FILE command
  in the hierarchy of the menus takes effect on where the file and
  its items are added.

PIPE ''command''; Is very similar to FILE, except that ``command'''s
  output to stdout is used instead of the file. This will e.g. enable
  you to write a script (or use the provided one, take a look at dirtomenu
  in directory extras/tools, thanx to Adam Sampson for this) which
  will search a directory for files of a special program and add menu
  items to invoke the program with the filenames as parameter. There's
  almost no limit to the use of this option. However at the moment
  the option is not available on systems with a missing popen()-function
  in their libc. If you have interesting scripts or programs for this
  which you think can be included into the distribution, don't hesitate
  to send them to us.

ITEM, FILE and LINE - lines have to be terminated by a semicolon. Everything
that should be put into the main menu simply has to be written into
the file, submenues are braced. There is an example-file, so simply
take a look at it in case there are more questions (I am sure there
are!).

3.3.3 The StartScript-option

In uwmrc you can define a shell-script or a command-line of a program
which is to be executed when uwm is started (StartScript=). There
have been changes with this option: Since it now also supports command
lines for usual shell-commands you have to mark your script as executables
(use chmod) and they have to start with #!/shellpath/shellcommand
of the desired shell, e.g. #!/bin/sh. 

If the line Shell Script=... is missing in uwmrc there will be no script
or program executed. uwm will first look for the defined script in
your private \~{ }/ude/config-directory, then in the system-ude/config-directory
and then in the command-path. If there are several scripts matching
in these paths only the first one which is found will be executed.
If there are several StartScript=...-lines found in uwmrc only the
last one is used.

3.4 The WM-Menu

Pressing the left mouse button somewhere in the root-window will make
the window-manager-menu appear. 

If you press any other mouse-button while the WM-menu is active and
no item is selected uwm will switch to the next or previous workspace
depending on which button is pressed. Using this repeatedly you can
'zap' through your workspaces.

3.4.1 The 'Quit ude' sub menu

Just what it's supposed to be, you have to select 'yes' in the sub
menu to really quit. this is the only security-request at the moment,
so take a little care.

3.4.2 The 'restart ude' sub menu

With this you can restart uwm, e.g. to start a new version after an
update or to reread the configuration files. You can choose whether
you want the StartScript to be executed again when ude is restarted
or not.

3.5 Keyboard shortcuts

There are a few keystrokes hard-coded into uwm:

+----------------+------------------------------------------------+
|Keystroke       | uwm's reaction                                 |
+----------------+------------------------------------------------+
+----------------+------------------------------------------------+
|Ctrl-Alt-Up     | activate previous window visible on workspace. |
+----------------+------------------------------------------------+
|Ctrl-Alt-Down   | activate next window visible on workspace.     |
+----------------+------------------------------------------------+
|Ctrl-Alt-Right  | switch to next workspace.                      |
+----------------+------------------------------------------------+
|Ctrl-Alt-Left   | switch to previous workspace.                  |
+----------------+------------------------------------------------+
|Ctrl-Alt-PgUp   | Raise active window.                           |
+----------------+------------------------------------------------+
|Ctrl-Alt-PgDown | Lower active window.                           |
+----------------+------------------------------------------------+
|Ctrl-Alt-End    | Iconify active window.                         |
+----------------+------------------------------------------------+


One day I'll make them configurable...

3.6 other

there will be various other operations implemented in uwm, lots of
them are already prepared, but most of them are not finished yet,
so you still have to wait a little bit.
