
wmx -- another window manager
=============================

wmx is another window manager for X.  It is based on wm2 and provides
a similarly unusual style of window decoration; but in place of wm2's
minimal functionality, it offers many of the features of more
conventional managers in the most simplistic implementations
imaginable.  wmx is, however, still barely configurable except by
editing the source and recompiling the code.


This release
============

This is the fifth release, dating from January 1999.


Building wmx
============

You will need a Unix machine, X libraries and a C++ compiler such as
gcc.  You will also need a mouse, preferably with three buttons.  Your
X server and libraries must be R4 or newer and must support the Shape
extension.  If you want to use frame background-pixmaps (see "Pixmaps"
below), you will need the Xpm header and library.  wmx does NOT
support multi-screen displays, because I don't have anything to test
multi-screen code on.

wmx makes relatively heavy demands on the performance of your X
server, because of the use of shaped windows, but it shouldn't place
too much of a load on other aspects of your system.

Inspect the file Config.h.  This lists everything that can be usefully
configured before building, with comments to tell you what means what.
Change the settings to something that looks suitable now, and ensure
that CONFIG_NASTY_FONT is set to something which is unlikely not to be
found.

Edit the Makefile to suit the requirements of your system, and run
"make".  This should build wmx.  On certain systems you may need to
edit the source to overcome problems with the location of non-POSIX
functions such as putenv(), select() and signal() -- check Manager.C
for the putenv() prototype, Events.C for a select #define, and
General.h for the SIGNAL_CALLBACK_TYPE macro.


Using wmx
=========

To run wmx, make sure you're not already running a window manager,
make sure the DISPLAY variable is correctly set and the X server is
running, and then execute the file "wmx".  There are no command-line
options or X resources, and there is no start-up file.  If your X
server doesn't support the Shape extension, wmx will exit (and will
never work on your server); if it can't find the required fonts or
allocate the required colours, it will also exit (but you should be
able to fix this by changing the definitions in Config.h and
recompiling).

Available window manipulations are:

 -- To focus a window: depends on the focus policy you selected
    in Config.h before compiling.  See "Focus policy", below.

 -- To raise a window: click on its tab or frame, unless you have
    auto-raise on focus set in Config.h.

 -- To move a window: make sure it's in focus, then click and drag
    on its tab.

 -- To hide a window: make sure it's in focus, then click on the
    button at the top of its tab.

 -- To recover a hidden window: hold down left button on the root
    window for the root menu, and choose the window you want.

 -- To start a new xterm: use the first item on the left-button root
    menu ("New"), unless you've disabled it in Config.h.

 -- To delete a window: make sure it's in focus, click on the
    button on the tab, hold the mouse button for at least a
    second and a half until the cursor changes to a cross, then
    release.  (I know, it's not very easy.  On the other hand,
    things like Windows-95 tend to obscure the fact that most
    windows already have a perfectly good Close option.  If the
    default delay doesn't suit you, change it in Config.h and
    recompile.)

 -- To resize a window: make sure it's in focus, then click and
    drag on its bottom-right corner.  For a constrained resize,
    click and drag on the bottom-left or top-right corner of
    the enclosing window frame.

 -- To flip around amongst the windows on-screen: click with the right
    mouse button on the root window or on any window's frame or tab.

 -- To switch between desktops (or "Channels"): click with the middle
    mouse button towards the top-right corner of the root window.  A
    big green number will be displayed showing which channel you are
    currently on.  Click again before this number disappears to change
    to the next channel.  If you click with the left button after the
    first middle-button click, you will move down a channel instead
    of up.

 -- To move a window from one channel to another: click with the
    middle mouse button on its frame, and then repeat until you
    reach the channel you want to move it to.

 -- To start a new application of your choice: use the middle mouse
    button on the root window, anywhere other than the top-right
    corner of the root window.  If you have any executable programs in
    your $HOME/.wmx directory -- or other directory named in
    CONFIG_COMMAND_MENU -- they will be listed on a menu and you can
    choose one to be started up.  (You can add and remove programs
    while wmx is running.)  REMEMBER, $HOME/.wmx IS A DIRECTORY, not
    a file, so please don't write to me asking what the file format is.

 -- To exit from wmx: move the mouse pointer to the very edge of the
    screen at the extreme lower-right corner, and click left button on
    the root window for the root menu.  The menu should have an extra
    option labelled "Exit wmx"; select this.

All move and resize operations are opaque.


Keyboard controls
=================

By popular request, there are now some keyboard controls available.
The key combinations are configurable in Config.h, and the particular
modifier used depends on your X server (the default of Mod1
corresponds to Alt on most).  The default bindings are:

 -- To raise the focused window in the stacking order: Alt/cursor-Up

 -- To lower the focused window: Alt/cursor-Down

 -- To flip through the windows on screen: Alt/Tab (equivalent to
    clicking the right mouse-button on the focused window's frame)

 -- To hide the focused window: Alt/Return

 -- To delete the focused window: Alt/Delete

 -- To expand the focused window to the full height of the screen:
    Alt/PageUp

 -- To contract the focused window after expanding it: Alt/PageDown

 -- To switch channels: Alt/cursor-Left and Alt/cursor-Right

 -- To switch directly to channel number N, provided there is
    a channel N (i.e. some client has been created there already):
    Alt plus F-key N.  Thus for channel 2 press Alt/F2 and so on.

And new in the fifth release:

 -- To make the currently focused window "sticky", so it appears on
    all channels: Alt/Pause.  Repeat to unstick the window.

 -- To pop up a keyboard-powered client menu: Alt/Menu.  (On my PC,
    Menu is bound to the rightmost Windows-95-specific key.)  You
    can then use cursor-Up and cursor-Down, Return, and Escape to
    choose, select or cancel from the menu.

If you have NumLock switched on, the key controls might not work.


Focus policy
============

Config.h contains settings for focus policy.  There are three things
you can define to either True or False: CONFIG_CLICK_TO_FOCUS,
CONFIG_RAISE_ON_FOCUS and CONFIG_AUTO_RAISE.  The first two are
connected: together they define a focus policy.  The third is a
separate focus policy on its own and will only work if the first two
are both False.  CONFIG_AUTO_RAISE differs from
(!CONFIG_CLICK_TO_FOCUS && CONFIG_RAISE_ON_FOCUS) only in that it
provides a short delay before raising each window.  The delay is also
definable.


Skeletal feedback
=================

If you have CONFIG_MAD_FEEDBACK set to True in Config.h, you will get
some natty feedback effects when using the left-button root menu (the
Client menu).  Each window selected on the menu will be indicated with
a half-frame at the correct position on the screen, to make it easier
to distinguish between windows with similar names on the menu.  If you
have CONFIG_FEEDBACK_DELAY set to zero or more, then the window itself
will be shown on the screen after a delay.  You can use this to
speculatively see what a hidden window is showing, without having to
restore it and hide it again.


Dynamic configuration
=====================

This release allows a certain degree of configuration at runtime.

(I know, I'm sorry.)

The configuration is held as the target of a symbolic link residing at
~/.wmx/options (or in whichever directory the CONFIG_COMMAND_MENU is
found).  This target should be a string of the form a:b/c:d/e:f etc,
to set option a to value b, option c to value d, e to f and so on.
The available options are currently "menu" (full or part), "new" (on
or off), "keyboard" (on or off), "feedback" (on or off), and "focus"
(click, raise, delay-raise or follow).  "focus:delay-raise" may be
optionally followed by a comma and then a delay time in ms.

For example,

  amyl > ~ > ls -l ~/.wmx/options
  lrwxrwxrwx   1 cannam   cannam         39 Jan 12 10:16 /home/cannam/.wmx/options -> menu:full/new:off/focus:delay-raise,100
  amyl > ~ > 

The real problem with this scheme is that it makes Config.h harder to
read, because the defaults for the dynamically configurable options
are now held in Config.C instead.


Pixmaps
=======

wmx allows you to specify a background pixmap for the window frames.
If you set CONFIG_USE_PIXMAPS to True in Config.h and supply a file
./background.xpm which contains an Xpm pixmap called "background", wmx
will use this to colour in the frames.  If you also set
CONFIG_USE_PIXMAP_MENUS, the root menus will be filled in with the
background too.

An especially unpleasant example file, cribbed and modified from
http://home.netscape.com/assist/net_sites/bg/marble/greenred_marble.gif,
is included, although you're advised to find your own.


Decoration-free windows
=======================

wmx does not support borderless or undecorated windows, but there
is a friendly utility by Vadim Kolontsov, called "xnodecor", that you
can use to circumvent this limitation if you want.  See

  http://sb.123.org/xnodecor.html

xnodecor gives you absolutely stationary, sticky, fixed borderless
windows for applications such as clocks that you feel you will never
want to move or remove.


xterm
=====

Some versions of xterm and rxvt run badly with wmx.  If you use xterm
and find that it refreshes the window excessively slowly, you might
like to try experimenting with a different terminal emulation program.
I think it might help to ensure that the scrollbar is on the
right-hand side of the rxvt window and is thick enough that wmx's
resize handle doesn't obscure any of the text area.


Credits
=======

wmx was written by Chris Cannam, recycling a lot of code and structure
from "9wm" by David Hogan.

The sideways tabs on the window frames were Andy Green's idea.

Alan Richardson's "xvertext" font-rotation routines are used for
the window tabs.

Kazushi (Jam) Marukawa provided all the internationalisation
code, which I think is currently only tested for Japanese; see
README.contrib for his notes and copyright notice.

Jeremy Fitzhardinge provided the original application-menu code.

The dynamic configuration code is mostly due to Stefan `Sec' Zehl.

This release contains code and bug fixes provided by Eric Marsden,
Lasse Rasinen, Bill Spitzak, Jacques Garrigue, Stefan `Sec' Zehl,
Sven Oliver Moll, Martin Andrews and, well, probably several others.

If you want to hack the code into something else for your own
amusement, please go ahead.  Feel free to modify and redistribute, as
long as you retain the original copyrights as appropriate.


Mailing list
============

There is a mailing list for discussion of wm2 and wmx, hosted by
majordomo at 42.org.  To subscribe, send email to majordomo@42.org
with "subscribe wmx" in the body of the mail.  The list is archived on
the web at http://ml.42.org/wmx/.


Chris Cannam, cannam@all-day-breakfast.com
January 1999
