.TH olwm "" "" "X Utility"
.PC "OPEN LOOK window manager"
\fBolwm [\fIoptions\^\fB]
.PP
.HS
.IC \fB\-2d\fR
Use two-dimensional look
.IC \fB\-3d\fR
Use three-dimensional look
.IC \fB\-background\fR
Specify the background color
.IC \fB\-bordercolor\fR
Specify the border color
.IC \fB\-click\fR
Use click-to-focus mode
.IC "\fB\-depth \fIdepth\fR"
The depth of the visual in which
.B olwm
is to run
.IC "\fB\-display \fIdisplay-string\fR"
The name of the display to manage
.IC \fB\-follow\fR
Use focus-follows-mouse mode
.IC "\fB\-font \fIfont-name\fR"
Set the font for window titles
.IC \fB\-foreground\fR
Specify the foreground color
.IC \fB\-multi\fR
Manage windows on all screens that a display supports
.IC "\fB\-name \fIresource-name\fR"
Use
.I resource-name
to look up resources in the resource data base
.IC \fB\-single\fR
Manage windows for a single screen only, using the default screen
for the specified display
.IP "\fB\-syncpid \fIprocess-id\fR"
Send
.B SIGALRM
to
.I process-id
when
.B olwm
has completed its initialization
.IC "\fB\-syncsignal \fIsignal\fR"
Send
.I signal
instead of
.B SIGALRM
.IC "\fB\-visual \fIvisual-class\fR"
Specify the class of the visual in which
.B olwm
is to run
.IC "\fB\-xrm \fIresource-string\fR"
Specify resources on the command-line
.HE
.B olwm
is a window manager for the X Window System that implements
parts of the \*(OL graphical user interface.
.SH "Using olwm"
To invoke
.B olwm
as your X window manager, edit the
.B xinitrc
file you are using (either
.B $HOME/.xinitrc
or
.BR /usr/X11/lib/xinit/xinitrc ,
depending on how you have set up your system).
Replace its last command, which usually reads
.BR twm ,
with the command
.BR olwm .
Then invoke X as usual.
.PP
.B olwm
has many features.
However, the rest of this section describes the features that you will use
most often.
If you have used any sort of graphical interface, you will find that
.B olwm
is easy to learn and use.
.PP
When
.B olwm
comes up, the screen will appear something like the following:
.PH 1 1 \*(XD/olwm.eps
The windows you actually see will depend upon the contents of your
.B xinitrc
file.
Please note that the above image was taken from
.B olwm
using the monochrome server.
.B olwm
displays the same objects, regardless of the server you run it under;
however, under the color server
.B olwm
uses a three-dimensional design that is much more attractive.
.PP
At the top of each window is a
.IR "title bar" ,
which gives the name of the program being run in that window.
.B olwm
highlights the title bar of the window that is receiving input.
To move a window, click the left-mouse button on the title bar
and drag the mouse.
.PP
At the left of the title bar is a small button, which is marked with
an inverted triangle.
Clicking on that button iconifies the window.
.PP
At the corner of each window is a small object that resembles the corner
on a window frame.
This corner object controls the size of the window.
To resize a window, move the mouse cursor to one of those objects, press
the left-mouse button, and drag the mouse.
Note that when you resize a window,
.B olwm
does
.I not
always resize the objects within that window.
The objects within a window are under the control of the application being
run within that window, and in most instances they will not be resized.
.PP
If you move the mouse cursor to the background of the screen and then
click the right-mouse button,
.B olwm
displays its
.IR "Workspace Menu" .
You can change the contents of this menu by editing the file
.BR /usr/X11/lib/openwin-menu .
Exact directions on how to do so are given later in this article.
.PP
To the left of the menu's title bar is a small object that resembles
an old-fashioned push-pin.
If you click on that object,
.B olwm
``pins'' the menu to the screen \(em that is, the menu remains in view
until you click again again on the push-pin.
Note that in the figure shown above, the menu is pinned to the screen,
as shown by the fact that the push-pin is inserted into the menu.
.PP
As you can see, some of the menu's entries are marked with a small triangle;
this indicates that that menu entry invokes a sub-menu.
To see an entry's sub-menu, click the entry's triangle.
Some sub-menus can also be pinned to the screen; whether they can be
depends upon how they are described in file
.BR openwin-menu ;
how to do this is described below.
.PP
If you click the right-mouse button within a window,
.B olwm
displays a menu that displays commands for manipulating a window.
This menu is not shown above.
.PP
Finally, the small picture at the top of the screen is an
.IR icon .
Some programs (such as the X application
.BR sunclock ,
which is shown here) provide bit-mapped images to be used as icons.
If this is so and the program is installed properly,
.B olwm
displays the bit-mapped image when you iconify that program.
You cannot resize an icon, but you can move it:
to do so, just move the mouse cursor into the icon's window, press the
left-mouse button, and drag the mouse.
.\" ========================================================================
.SH "Command-line Options"
.B olwm
recognizes the following command-line options.
Most have analogues within the resource data base, which they override:
.IP \fB\-2d\fR
Use two-dimensional look.
This is the default for monochrome systems.
.IP \fB\-3d\fR
Use three-dimensional look.
This is the default for color systems.
This option is ignored for monochrome systems.
.IP \fB\-bd\fR
.IS \fB\-bordercolor\fR
Specify the color of a window's border.
See the description of the resource
.BR BorderColor ,
below.
.IP \fB\-bg\fR
.IS \fB\-background\fR
Specify the background color.
See the description of the resource
.BR Background ,
below.
.IP \fB\-c\fR
.IS \fB\-click\fR
Use click-to-focus mode:
that is, to redirect the keyboard's input into a window, click on it.
This is the default.
.IP "\fB\-depth \fIdepth\fR"
The depth of the visual in which
.B olwm
is to run.
See the discussion in the section \fIScreen Resources\fR, below.
.IP "\fB\-display \fIdisplay-string\fR"
The name of the display to manage.
This overrides the environmental variable
.BR DISPLAY ,
if it is set.
In addition,
.B olwm
exports
.I display-string
to its environment, so processes forked from
.B olwm
inherit it.
.IP \fB\-f\fR
.IS \fB\-follow\fR
Use focus-follows-mouse mode;
that is, to redirect the keyboard's input into a window, move the
mouse cursor into it.
The default is click-to-focus mode.
.IP \fB\-fg\fR
.IS \fB\-foreground\fR
Specify the foreground color.
See the description of the resource
.BR ForegroundColor .
.IP "\fB\-fn \fIfont-name\fR"
.IS "\fB\-font \fIfont-name\fR"
Set the font for window titles.
.IP \fB\-multi\fR
Manage windows on every screen that a display supports.
This is the default.
.IP "\fB\-name \fIresource-name\fR"
Use
.I resource-name
to look up resources in the resource data base.
.IP \fB\-single\fR
Manage windows for a single screen only, using the default screen
for the specified display.
This overrides the
.B \-multi
option.
.IP "\fB\-syncpid \fIprocess-id\fR"
When
.B olwm
completes its initialization, it sends a signal
(by default, \fBSIGALRM\fR) to
.IR process-id .
The signal will be sent only if this option is present.
This is useful for running
.B olwm
from shell scripts (such as
.BR .xinitrc )
in such a way that the script waits for
.B olwm
to finish its initialization while leaving
.B olwm
as a child process of the shell script.
This can be done using the following
.B sh
construct:
.DM
	sleep 15 & pid=$!
	olwm \-syncpid $pid &
	wait $pid
.DE
.IP "\fB\-syncsignal \fIsignal\fR"
Send
.I signal
instead of
.BR SIGALRM .
The signal is specified as a number, not symbolically; that is,
use `1' instead of
.BR SIGHUP .
.IP "\fB\-visual \fIvisual-class\fR"
Run
.B olwm
in the visual mode
.IR visual-class .
See the discussion in the \fIScreen Resources\fR, below.
.IP "\fB\-xrm \fIresource-string\fR"
Specify resources on the command-line.
Resources specified here override resources found in resource files.
.\" ========================================================================
.SH "Debugging Options"
The following options are strictly for debugging.
They are not recommended for general use.
.I
Do not use these options unless you know what you are doing.
.R
.IP \fB\-all\fR
Print a message for every event received.
.IP \fB\-debug\fR
Equivalent to turning on all debugging options.
.IP \fB\-orphans\fR
Print orphaned events.
.I "Orphaned events"
are those associated with a window or frame that has no entry in
the frame hash table,
or those that are not handled by the various event handlers.
.IP \fB\-synchronize\fR
Run the window manager in synchronous mode.
.\" ========================================================================
.SH "Internationalization Options"
The following options help to internationalize
.BR olwm .
Note that \*(CO does not yet support locales.
For details on what a locale is, see the discussion in the following
section:
.IP "\fB\-basiclocale \fIlocale-name\fR"
Set the basic category of the locale.
This category is the base for other locale categories;
therefore, it restricts what can be put into other locale categories.
For details, seeing the following sections on handling locales.
.IP "\fB\-displaylang \fIlocale-name\fR"
Specify the locale category for \*(OL's display language.
This category affects the contents of the workspace menu,
window menu, and notice messages.
.IP "\fB\-numeric \fIlocale-name\fR"
Specify \*(OL's locale category for numeric formatting.
This category affects the format of any message that contains numbers.
.\" ========================================================================
.SH "Locale Handling"
A
.I locale
is the set of rules that govern how data are presented
in a given part of the world.
For example, in the United States it is the custom to display a date with
the month first, then the day of the month, and finally the year; whereas
in much of Europe the custom is to give the day first, then the month,
and finally the year.
When you set a locale, you instruct
.B olwm
to follow the rules used within that locale.
Note that \*(CO does not yet support locales.
.PP
The \*(OL international extensions define the following
locale categories:
.IP "\fBBasic Locale\fR"
This is the basic setting for the entire locale mechanism.
This category specifies how \*(OL handles internal characters.
.IP "\fBDate Format\fR"
This category specifies the format of date and time.
This category does not affect
.BR olwm ,
because the window manager does not display date-and-time information.
.IP "\fBDisplay Language\fR"
This category specifies the language used to display menus,
notice messages, and error messages.
.IP "\fBInput Language\fR"
This category specifies the language used to input text.
This category does not affect
.BR olwm ,
because the window manager does not accept text input from the keyboard.
.IP "\fBNumeric Format\fR"
This category specifies how \*(OL displays numbers.
.PP
Because the Basic Locale defines how \*(OL handles characters,
\*(OL places the following restrictions on how you can combine settings
of locale categories:
.IP \fB1.\fR 0.3i
If the Basic Locale is set to anything other than the
.B C
locale, all other locale categories must be set either to the
.B C
locale or to the same locale as the Basic Locale.
.IP \fB2.\fR
If the Basic Locale is set to the
.B C
locale, all other locale categories must be set to the
.B C
locale as well.
.PP
You can use the following methods to set locale categories.
They are listed in order of priority:
.IP \fB1.\fR 0.3i
Command-line options (e.g.,
.BR \-basiclocale ).
.IP \fB2.\fR
The resource data base, as set by the command
.BR xrdb .
.IP \fB3.\fR
The function
.BR setlocale() .
.PP
If you do not use command-line options to set locales,
.B olwm
picks up the new locale settings from the
workspace property (thus reflecting changes to the resource data base)
and resets the locale dynamically (for example, to change the
language of the workspace and window menus).
It unpins all pinned workspace menus as locales are being altered.
.\" ========================================================================
.SH "Input Focus"
Only one window at a time can receive input from the keyboard.
.B olwm
has two ways by which you can move the focus of input from one window
to another:
.IP \fB1.\fR 0.3i
``Click-to-focus'' mode (also known as ``click-to-type'' mode).
You must click on the window in order to focus the input into it.
While input is focused into a given window, the mouse cursor can be anywhere
on the screen but keystrokes still go into that window.
You can simultaneously set the input focus
onto a given window and raise that window to the foreground
by moving the mouse cursor into that window's title bar or border and
clicking the left-mouse button.
.IP \fB2.\fR
``Focus-follows-mouse'' mode.
In this mode,
.B olwm
focuses the input into the window in which the mouse cursor
is currently positioned.
To switch the input focus from one window to another, simply move the
mouse cursor to the other window; you do not have to click a mouse button.
Note, however, that to move the focus amongst subwindows of a single
top-level window, you must click in the subwindow,
or you must use focus-transfer function keys
(if the application offers them).
.PP
Neither mode of shifting the focus has inherent advantages.
Choose the one you prefer.
The window manager
.B twm
by default uses focus-follow-mode for moving the input focus.
.BR olwm ,
however, by default uses click-to-focus mode.
To change this default behavior,
you can use the command-line option
.BR \-follow ,
or modify
.BR olwm 's
resource data base.
.\" ========================================================================
.SH "Mouse Buttons"
\*(OL defines three mouse-button functions:
.BR SELECT ,
.BR ADJUST ,
and
.BR MENU .
The exact behavior of each function depends upon the object that is
under the mouse cursor.
.PP
These functions are mapped to mouse buttons 1, 2, and 3, respectively \(em
that is, to the left, center, and right mouse buttons.
If your mouse has only two buttons, insert the instruction
.B emulate3buttons
into the mouse-control section of file
.BR /usr/X11/lib/Xconfig .
With this instruction, the X server lets you mimic the second (center)
mouse button by pressing the left and right buttons simultaneously.
This technique is called mouse-button
.IR chording .
For details, see the installation section of your manual for X Windows for
\*(CO.
.\" ========================================================================
.SH "Manipulating Windows and Icons"
The following describes how to use the mouse to manipulate windows and icons.
.IP "\fIWindow Title Bar and Borders\fR"
Clicking
.B SELECT
(the left mouse button)
on a window's title bar or border
selects that window, raises it to the foreground, and
deselects all other windows and icons.
When it is in click-focus mode,
.B olwm
also focuses keyboard input into this window.
If you press the left-mouse button and drag the mouse,
.B olwm
moves the window without raising it or refocusing input.
If you select a window,
.B olwm
moves it and all other selected windows simultaneously;
otherwise, it moves
just that window, and does not select it.
.IP
If you hold down the
.K Ctrl
key while you are moving a window,
.B olwm
constrains motion to either vertical or horizontal, depending upon
whether you have moved the mouse cursor
farther in a vertical or horizontal direction.
Double-clicking the left-mouse button while within
a window is the same as selecting the
.K Full_Size
or
.K Restore_Size
menu item.
.IP
.\" My examination of olwm shows that the man page's entry is wrong.
.\" I changed it. - fwb, 11/26/93
Clicking
.B ADJUST
(the center-mouse button)
selects a window if it is not already selected.
If the window is already selected, then clicking this button has no effect.
.IP
Pressing
.B MENU
(the right-mouse button) when the cursor is in the window bar or border
brings up the window menu.
For details, see the section entitled
.IR "Window Menu" ,
below.
.IP
If you press the
.K Alt
key, the mouse-button functions become accessible anywhere over the window,
not just over the title bar and borders.
You can change this modifier; see the description of the resource
.B WMGrab
in the section entitled
.IR "Modifier Customization" ,
below.
.IP "\fIResize Corners\fR"
Each corner of each window has a small object on it that looks like a
holder for a photograph.
It is called a
.IR "resize corner" .
To resize a window, move the mouse cursor to a resize corner,
press the left-mouse button, then drag the corner to a new location.
When you release the mouse button,
.B olwm
resizes the window.
If you hold down the
.K Ctrl
key while you are dragging,
.B olwm
only resizes
vertically or horizontally, depending upon whether you have moved the mouse
further horizontally or vertically.
.IP "\fIWindow Button\fR"
The
.I "Window Button"
is the small box near the left end of the title bar;
it holds a downward-pointing triangle.
If you move the mouse cursor to this button and press
.B SELECT
(the left-mouse button),
.B olwm
closes the window and replaces it with an icon.
(Icons are discussed below.)
To restore the window to the screen, click the left-mouse button on the icon.
To change the window menu's default action, hold down the
.K Ctrl
key while you manipulate the window menu.
.IP \fIPushpin\fR
\*(OL pop-up windows have a pushpin instead of a window button.
If the pushpin is out of its hole,
pressing a command button within the window causes
the window to be taken down (or ``dismissed'') after the command is executed.
If you click
.B SELECT
on the pushpin, it moves into its hole.
This, in effect, ``pins'' the menu to the screen:
pressing a command button executes the command but does not dismiss the window.
Clicking
.B SELECT
over the pin pulls it out of its hole.
This dismisses the window without executing any command.
Some windows come up with the pin already in the hole.
.IP \fIIcons\fR
An icon is a small picture that represent a closed window.
You can use
.B SELECT
and
.B ADJUST
to move and select an icon, just you do for an open window.
A similar version of the Window Menu is available on an icon by pressing
.BR MENU .
To open the window that the icon represents, move the mouse cursor to the
icon and double click
.BR SELECT .
You cannot resize an icon.
.\" ========================================================================
.SH "Nonrectangular Windows"
The X11 Non-Rectangular Window Shape Extension (commonly referred to simply
as the ``shape extension'') allows a window to have an arbitrary shape.
.B olwm
handles these windows by giving them no decoration whatsoever.
Shaped windows can be manipulated by using the modifier
.B WMGrab
with the mouse buttons.
This modifier by default is linked to the
.K Alt
key.
For details, see the section
.IR "Modifier Customization" ,
below.
You can move, resize, close, or open
shaped windows just as you do rectangular windows.
Unlike rectangular windows, however,
the resize corners of a shaped window
float at the corners of the window's bounding rectangle.
.\" ========================================================================
.SH "Selections on the Workspace"
If you wish, you can bind together a group of windows or icons, and manipulate
them as if they were one.
.II "Workspace"
.II "root window"
To do so, click the left- or center-mouse button over the
.I Workspace
(that is, the area of the screen outside of all windows and icons \(em
also called the ``root window'').
Pressing either
.B SELECT
or
.B ADJUST
and dragging the mouse defines a rubber-band rectangle.
When you release the mouse button, you can manipulate as one
the set of windows and icons enclosed that this rectangle encloses.
If you created the rectangle using
.BR SELECT ,
you select the windows and icons within the rectangle and de-select
all other objects.
If, however, you used
.B ADJUST
to create the rectangle,
.B olwm
toggles the selection state of all objects within the rectangle;
all other windows and icons that are already selected remain selected.
.\" ========================================================================
.SH "Workspace Menu"
Pressing the
.B MENU
(right-mouse) button over the workspace brings up the Workspace Menu.
It consists of a number of buttons; to select a button, move the mouse
cursor to it and click the
.B SELECT
button.
You can edit this menu to change its contents (how to do so is described
below); however, it typically contains the following items:
.IP \fK(Programs)\fR
This button invokes a sub-menu that lets you invoke an application.
Its default sub-menu contains all of the programs in the OpenWindows DeskSet.
However, you can customize this menu to contain more
programs and to contain nested submenus.
For further information, see the section entitled
.IR "Menu Customization" ,
below.
.IP \fK(Utilities)\fR
This button invokes a sub-menu that contains several utility
functions for the workspace, including
.B Refresh
(redisplay all windows on the screen),
.BR "Lock Screen" ,
and
.BR "Save Workspace" .
.IP \fK(Properties...)\fR
This button invokes the
.B "Workspace Properties"
window, which allows you to view and customize settings of the
OpenWindows environment.
.\".IP "\fK(Help...)\fR"
.\"Brings up the table of contents of the Help Handbooks.
.\".IP "\fK(Desktop_Intro...)\fR"
.\"Brings up a tutorial introduction to the Sun Desktop.
.IP \fK(Exit)\fR
Shut down all applications and exit from
.BR olwm .
.B olwm
asks you to confirm your decision before it shuts itself down.
.\" ========================================================================
.SH "Window Menu"
The window menu of most windows has the following items.
(The current locale sets the language in which the items appear.)
.IP \fBClose\fR
Close the window to an icon.
Any \*(OL pop-up windows are closed into this icon as well.
They reappear when you reopen the icon.
This item is labelled
.B Open
if you bring up the menu on an icon.
.IP "\fBFull Size\fR"
Expand the window to the full height of the screen.
If this has already done, the button is labelled
.BR "Normal Size" ,
and it restores the window to whatever size it was before you invoked
.BR "Full Size" .
If the application has specified a maximum size for the window,
.B olwm
uses this size for
.B "Full Size"
instead of the full screen height.
.IP \fBMove\fR
Invoke the keyboard-based form of moving the window.
This item appears only if \*(OL Mouseless Mode is enabled.
.IP \fBResize\fR
Invoke the keyboard-based form of resizing the window.
This item appears only if \*(OL Mouseless Mode is enabled.
.IP \fBBack\fR
Drop the window to the background, i.e, behind all other windows
that overlap it.
.IP \fBRefresh\fR
Clear and redisplay the window.
.IP \fBQuit\fR
Kill the program that is running in the window and remove the window.
If the application uses the protocol
.BR WM_DELETE_WINDOW ,
.B olwm
sends the ClientMessage
.B WM_DELETE_WINDOW
instead of killing that window.
Note that killing a window (as opposed to closing it) often leaves system
memory littered with debris.
You are much better off killing that window's process with the command
.BR "kill \-1" .
.IP 
\*(OL pop-up windows (as opposed to base windows) have a smaller window menu.
It lacks the items
.BR Close ,
.BR "Full Size" ,
and
.BR Quit ,
but it has two new items:
.IP \fBDismiss\fR
Dismiss this window.
This button has a submenu with two items:
.BR "This Window" ,
which dismisses just this window, and
.BR "All Pop-ups" ,
which dismisses all pop-up windows that this application owns.
.IP \fBOwner?\fR
This raises and flashes the title bar of the base window that ``owns''
this pop-up window.
.\" ========================================================================
.SH "Menu-Customization Files"
You can customize
.BR olwm 's
Workspace Menu by putting a menu description into a file that
.B olwm
reads.
When it starts up,
.B olwm
first looks for the file named by the environmental variable
.BR OLWMMENU .
If this variable does not exist, or if the file is not readable,
.B olwm
then reads file
.BR $HOME/.openwin-menu .
If this file is not present or is unreadable,
.B olwm
reads the system's default menu file
.BR /usr/X11/lib/openwin-menu .
Finally, if it cannot find the default menu file,
.B olwm
use a minimal, built-in menu.
.PP
The menu file that is read can also be
modified by the locale setting for the display language.
The locale name is used as a suffix for the file name.
If a localized menu file is found,
it is used in preference to the non-localized menu file.
For example, if the display language local is ``japanese,'' the file
.B .openwin-menu.japanese
takes precedence over the file
.BR .openwin-menu .
.PP
.B olwm
automatically re-reads its menu file whenever the menu file changes.
This lets you make many small changes to a menu file, and try out the
modified menu after each change.
The automatic re-reading can be controlled with the resource
.BR AutoReReadMenuFile .
.PP
If
.B olwm
encounters a syntax error when it read a menu file,
it prints a message onto the standard-error device,
and the reading of this menu file is considered to have failed.
.B olwm
then attempts to read the next file in the sequence as described above.
.\" ========================================================================
.SH "Menu-Specification Syntax"
The menu specification language has a number of keywords,
all of which are in all upper-case letters.
The keywords are
.I not
translated into the language specified by locale settings:
keywords are always in English.
.PP
Each line usually holds one menu button.
There are three fields on each line:
a label, the optional keyword
.BR DEFAULT ,
and a command.
The label is either one word or a string enclosed between quotation marks.
This is the label that appears in the menu button.
If the optional keyword
.B DEFAULT
appears next, this menu item becomes the default item for this menu.
The rest of the line (excluding leading whitespace) is considered to
be a command.
It is executed by sending it to the shell
.BR sh .
.B olwm
passes all shell metacharacters to the shell unchanged.
A line that contains only the keyword
.B SEPARATOR
will add extra space before the next item.
.PP
To specify a sub-menu, use the keyword
.B MENU
in place of a command.
.B olwm
adds a button to the current menu;
clicking or dragging on this button bring up the sub-menu.
Subsequent lines in the menu file define buttons for the sub-menu,
up to a line that holds the keyword
.BR END .
The label of the
.B MENU
line must match the label on the
.B END
line; otherwise,
.B olwm
signals an error.
Sub-menus can be nested arbitrarily, bracketed by
.B MENU
and
.B END
lines with matching labels.
To make a sub-menu pinnable, add the keyword
.B PIN
after the keyword
.B END
on the line that ends the sub-menu definition.
.PP
A sub-menu can be specified in a different file by putting the
path name of the file after the keyword
.BR MENU .
In this case, the file so named is assumed to contain lines that
specify menu buttons.
The sub-menu
file need not have any
.B MENU
or
.B END
lines (unless it has sub-menus itself).
The current file need not have a matching
.B END
line if the sub-menu is read from another file.
.PP
By default, the label in a menu button is used as the title of the submenu.
This can be overridden by specifying a line that has the keyword
.B TITLE
in the command field.
.B olwm
uses the label from this line as the sub-menu's title.
This line can appear anywhere in the sub-menu definition.
It does not add an item to the menu.
.PP
The following keywords can be used in the command field of a menu item.
They specify functions that are internal to
.BR olwm ;
these are not invoked through
.BR sh .
.IP \fBBACK_SELN\fR
Drop the selected windows and icons into the background.
.IP \fBEXIT\fR
Kill all applications and exit from the window manager after getting
confirmation from the user.
This is useful for exiting the entire window system.
.IP \fBEXIT_NO_CONFIRM\fR
Like
.BR EXIT ,
but skips the confirmation notice.
.IP \fBFLIPDRAG\fR
Toggle the state of the resource
.BR DragWindow .
.IP \fBFLIPFOCUS\fR
Toggle the state of the resource
.BR SetInput .
.IP \fBFULL_RESTORE_SIZE_SELN\fR
Toggle the full-sized/normal-sized states of the selected windows and icons.
.IP \fBNOP\fR
No operation:
do nothing.
.IP \fBOPEN_CLOSE_SELN\fR
Toggle the opened/closed states of the selected windows and icons.
.\".IP \fBPOSTSCRIPT\fR
.\"Open up a connection to NeWS using
.\".BR psh (1)
.\"and send the rest of the line to it.
.IP \fBPROPERTIES\fR
Bring up Workspace Properties menu.
.IP \fBQUIT_SELN\fR
Quit the selected windows and icons.
.IP \fBREFRESH\fR
Repaint all windows on the screen.
.IP \fBREREAD_MENU_FILE\fR
Force
.B olwm
to re-read immediately the customization file for the workspace's menu.
.B olwm
searches for a menu file (as described in the section entitled
.IR "Menu Customization" ,
below) and uses the first valid file it finds.
.IP \fBRESTART\fR
Restart the window manager by issuing an
.B exec()
on
.BR argv .
If you are running the default
.B xinit
script (i.e.,
.BR /usr/X11/lib/xinit/xinitrc ),
this will cause the server to shut down; however, if you have
modified your
.B xinit
script so that another application is invoked last (e.g.,
.BR xterm ),
restarting
.B olwm
should not affect any running applications or cause the server to shut down.
For details, see the entry for
.B xinit
in manual for X Windows for \*(CO.
.IP \fBSAVE_WORKSPACE\fR
Take a snapshot of the set of currently running
applications, and write the command lines so obtained into file
.BR $HOME/.openwin-init.
This instruction runs the command
.DM
	owplaces -silent -multi -script -output $HOME/.openwin-init
.DE
.IP \fBWMEXIT\fR
Exit the window manager without killing any applications.
As noted above, if you are running the default
.B xinit
script, this action will shut down the X server.
Note too that if any
.B xterm
or
.B xvt
windows are open when you shut down the X server, the entries for those
windows in file
.B /etc/utmp
will not be removed.
This may create problems later with system accounting and when you attempt
to shut down the system.
.PP
The following gives an example root menu.
.DM
.ta 0.5i 3.5i
	"Workspace Menu"	TITLE
	SEPARATOR
	"Programs" MENU
	    "Terminal Window"	exec "xterm -ls"
	    "VT100 Window"	exec "xvt -geometry 80x25"
	    "Text Editor"	exec "xterm -ls -e me"
	    "Clipboard"	exec xclipboard
	    "Clock"	exec "xclock -chime -refresh 1"
.sp \n(pDu
	    "Calculator" MENU
		"HP 10-C"	exec "xcalc -rpn"
		"TI-30"	exec xcalc
	    "Calculator" END
.sp \n(pDu
	    "Mailbox"	exec xbiff
	    "System Load"	exec xload
	"Programs" END PIN
.DE
.DM
.ta 0.5i 3.5i
	"Utilities" MENU
	    "Utilities"	TITLE
	    "Refresh"	REFRESH
	    "Reread Menu"	REREAD_MENU_FILE
	    "Magnify"	exec xmag
	"Utilities" END
.DE
.DM
.ta 0.5i 3.5i
	"Demos" MENU
	    "Maze"	exec maze
	    "Xeyes"	exec xeyes
	    "Xlogo"	exec xlogo
	"Demos" END PIN
.DE
.DM
.ta 0.5i 3.5i
	"Games" MENU
	    "Puzzle"	exec puzzle
	    "Xgas"	exec xgas
	    "Xtetris"	exec xtetris
	"Games" END PIN
.DE
.DM
.ta 0.5i 3.5i
	"Restart..."	RESTART
	"Exit..."	EXIT
.DE
.\" ========================================================================
.SH "Color-Map Installation"
.B olwm
handles color-map installation for windows whose color maps
differ from the default map.
There are two modes for focusing on a given color map:
.I color-follows-mouse
and
.IR color-locked .
They resemble the corresponding modes for focusing keyboard input;
however, the mode for focusing the color map can
be completely independent of the mode for focusing input.
The mode in which the system starts up is determined by the resource
.BR ColorFocusLocked ,
which is described below in the section entitled
.IR Resources .
.PP
.B olwm
tracks the set of windows that are eligible to have their color maps installed.
This set includes all top-level windows of clients.
If a client names a window in the property
.BR WM_COLORMAP_WINDOWS ,
.B olwm
also tracks that window.
.PP
In color-follows-mouse mode,
.B olwm
tracks the location of the mouse cursor and automatically installs the
color map of the eligible window that lies under the cursor.
Thus, you can install the color map of a particular window simply by moving
the mouse cursor into it.
.B olwm
restores the default color map when you move the mouse cursor
to the window frame or the workspace.
.PP
In this color-follows-mouse mode,
.B olwm
tracks the property
.B WM_COLORMAP_WINDOWS
for each application, but only to change the set of eligible windows.
A change to one of these properties installs a color map
only if the window under the mouse cursor has been made eligible by the change.
In this mode, the color map is not focused onto any window;
you entirely control installation of color maps.
.PP
In color-locked mode, the color map is focused onto a particular window.
Moving the mouse cursor does not install or un-install color maps.
If a client program changes the contents of its property
.B WM_COLORMAP_WINDOWS
on the top-level window that has the color-map focus,
.B olwm
responds by installing the color map of the first window that this property
names.
In this way, the application whose window has the color-map focus
controls installation of color maps.
.PP
According to the ICCCM, if
.B WM_COLORMAP_WINDOWS
does not include the top-level window,
.B olwm
assumes it occurs first in the list.
If you want your program to request color-map installation via changes to
.BR WM_COLORMAP_WINDOWS ,
you must make sure that the top-level window appears
somewhere in this property.
Otherwise,
.B olwm
always installs the color map of the top-level window.
.PP
You can use any of several method to focus the color map onto a given window:
.IP \(bu 0.3i
You can press the
.K Color-Lock
key while the mouse cursor is over the window.
.IP \(bu
If you (or an application) have set the resource
.BR AutoColorFocus ,
.B olwm
automatically gives a new window the color-map focus.
.IP \(bu
If you have set the resource
.BR ColorTracksInputFocus ,
the color-map focus is always given to the window that has the input focus.
.PP
In addition to focusing the color map, the
.K Color-Lock
key has some additional effects.
When you press this key,
if the mouse cursor is within a subwindow named in the property
.BR WM_COLORMAP_WINDOWS ,
.B olwm
installs that subwindow's color map.
If the mouse cursor is not within a window named in
.BR WM_COLORMAP_WINDOWS ,
or if the cursor is over the window's title bar or border,
.B olwm
installs the color map of the first window named in
.BR WM_COLORMAP_WINDOWS .
You can use
.K Color-Lock
to install the color map of a subwindow no
matter where it is listed within
.BR WM_COLORMAP_WINDOWS .
If there is no
.B WM_COLORMAP_WINDOWS
property, pressing
.K Color-Lock
simply installs the color map of the top-level window.
.PP
If you press
.K Color-Lock
while the mouse cursor is over the workspace (i.e., the area that lies
outside all application windows \(em also called the ``root window''),
.B olwm
installs the default color map,
and the window that has the color-map focus loses it.
The color map is focused onto the root window.
.PP
To revert to color-follows-mouse mode, press the key
.KR Color-Unlock .
The window with the color-map focus loses it.
.\" ========================================================================
.\".SH "Spot Help"
.\".B olwm
.\"provides help for frames, icons, the Workspace and Window menus,
.\"window buttons, resize corners, pushpins, and the Workspace itself.
.\"This is done via a separate slave program,
.\".BR olwmslave (1) .
.\"The slave program is forked automatically when
.\".B olwm
.\"starts up.  The forking of the slave program can be controlled by the
.\".B RunSlaveProcess
.\"resource.
.\" ========================================================================
.\".SH "Multiple Screens"
.\"By default,
.\".B olwm
.\"manages windows on all screens of the display server.
.\"Most operations are unchanged from single-screen operation.
.\"A window exists on a particular screen for its entire lifetime.
.\"The window cannot be moved from one screen
.\"to another, nor can it be resized to cross a screen boundary.
.\"Windows invoked from the Workspace menu will appear on the same screen as the
.\"menu.
.\"Spot help will appear on the same screen as the pointer
.\"when the Help key is pressed.
.\".PP
.\"Previous releases required modifications to the user's .xinitrc
.\"script to start multiple instances of
.\".BR olwm ,
.\"one for each screen.
.\"These modifications are no longer necessary.
.\"The default
.\".B Xinitrc
.\"(which contains a single invocation of
.\".BR olwm )
.\"works for both single- and multiple-screen situations.
.\" ========================================================================
.SH "Global Resources"
Global resources in
.B olwm
consist of two resource components.
The first resource component is the name of the window manager itself;
normally this is
.BR olwm .
(This is the last element of the full path name given in
.BR argv[0] .)
To alter this name, use the command-line argument
.BR \-name .
The second resource component names the global attribute being set.
It should be one of the names from the list given below.
Thus, to set the attribute
.BR AutoColorFocus ,
use
.B olwm.AutoColorFocus
as the resource specification.
.\".PP
.\"Some resources are also interpreted by
.\".B XView
.\"and are set by the Workspace Properties program
.\"(see
.\".BR props ).
.\"For these resources,
.\".B olwm
.\"also accepts the string
.\".B OpenWindows
.\"as the first resource component.
.\"These resources are marked with an asterisk `*'.
.PP
To specify colors,
use the formats parsed by the Xlib function
.BR XParseColor() .
Common formats are color names
and explicit red, green, and blue values in hexadecimal, preceded by a `#'.
For example, a bright magenta is specified with "#ff00ff".
For details, see the entry for the X utility
.B showrgb
in the manual for X Windows for \*(CO.
.PP
Boolean values can be specified with the words
``true'', ``false'', ``on'', ``off'', ``yes'', ``no'',
`1', `0', `t', and ``nil''.
.PP
.B olwm
recognizes the following global resources.
The word in
.B bold
names the resource; the entry in Roman gives its type;
and the word in
.I italics
gives its default value:
.IP "\fBAutoColorFocus \fR(Boolean) \fIfalse\fR"
Focus the color map onto each new window when the window opens.
For details, see the section entitled
.IR "Color-Map Installation" ,
above.
.IP "\fBAutoInputFocus \fR(Boolean) \fIfalse\fR"
Focus keyboard input into each new window when the window opens.
.IP "\fBAutoRaise \fR(boolean) \fIfalse\fR"
Automatically raise a window to the foreground when it receives the
keyboard focus.
This is useful when you run
.B olwm
in click-to-focus mode if you always like to type into the topmost window.
It also is useful in focus-follow-mouse mode when the resource
.B AutoRaiseDelay
is set to a reasonable value.
.IP "\fBAutoRaiseDelay \fR(integer) \fI0\fR"
The number of microseconds to delay between a window's receiving the
focus and
.BR olwm 's
raising it to the foreground.
This has an effect only the resource
.B AutoRaise
is set to
.BR true .
.IP "\fBAutoReReadMenuFile \fR(boolean) \fItrue\fR"
Specify whether to re-read the menu file whenever that file changes.
.IP "\fBBackground \fR(color) \fIwhite\fR"
Set the background color.
This is used for the background of masked icons.
Note that this color is not used for the backgrounds of icon windows.
Note, too, that this resource is distinct from the resource
.BR WindowColor .
.IP "\fBBasicLocale \fR(locale name)\fR"
Set the basic \*(OL locale category.
For details, see the section entitled
.IR "Locale Handling" ,
above.
.IP "\fBBeep \fR(enumeration) \fIalways\fR"
Set the circumstances under which
.B olwm
should beep.
The permissible values are as follows:
.RS
.IP \fBalways\fR
.B olwm
will beep whenever it is appropriate.
.IP \fBnever\fR
.B olwm
never beeps.
.IP \fBnotices\fR
.B olwm
beeps only when a notice appears,
.RE
.IP "\fBBorderColor \fR(color) \fIblack\fR"
The color used for window and icon borders.
.IP "\fBButtonFont \fR(font name) \fILucida-Sans\fR"
The font used in buttons within menus and notices.
.IP "\fBClickMoveThreshold \fR(integer) \fI5\fR"
Set the mode threshold for a menu.
If the mouse moves more than this number of pixels
while the menu button is down,
.B olwm
opens the menu in press-drag-release mode;
otherwise, it opens the menu in click-move-click mode.
.IP "\fBColorTracksInputFocus \fR(boolean) \fIfalse\fR"
If this resource is set to
.BR true ,
then
.B olwm
focuses the color-map focus onto the window that receives the input focus.
For details, see the section entitled
.BR "Color-Map Installation" ,
above.
.IP "\fBColorFocusLocked \fR(boolean) \fIfalse\fR"
Give the initial state of the color-map focus.
If it is set to
.BR true ,
.B olwm
locks the default color map into the hardware.
If
.BR false ,
the color map of the window under the mouse is kept installed.
For details, see the section entitled
.BR "Color-Map Installation" ,
above.
.IP "\fBCursorFont \fR(font name)\fR"
The font to be used for cursors.
It is not useful to change this
unless you have an alternate cursor font with the same encoding
as the \*(OL cursor font.
The default value is:
.DM
	\-sun\-open look cursor\-*\-*\-*\-*\-*\-120\-*\-*\-*\-*\-*\-*.
.DE
.IP "\fBDefaultIconImage \fR(filename)"
The file that contains a bitmap to be used as the default icon image.
By default, this is not set.
.IP "\fBDefaultIconMask \fR(filename)"
The file that contain a bitmap to be used as the default icon mask.
By default, this is not set.
.IP "\fBDefaultTitle \fR(string) \fINo Name\fR"
The string to display in the title bar of a window that has not
provided a string in the property
.BR WM_NAME .
.IP "\fBDisplayLang \fR(locale name)"
The display-language \*(OL locale category.
By default, this is not set.
For details, see the section entitled
.BR "Locale Handling" ,
above.
.IP "\fBDragRightDistance \fR(integer) \fI100\fR"
When the mouse cursor is over a menu item, this resource
sets the number of pixels that you must drag the mouse to the right
in order to bring up a submenu.
.\"The submenu always comes up when you move over the menu
.\"mark (the right-pointing triangle), regardless of the drag-right distance.
.IP "\fBDragThreshold \fR(integer) \fI5\fR"
The number of pixels the mouse must move while a mouse button is down for
.B olwm
to classify the action as a drag instead of a click.
.IP "\fBDragWindow \fR(boolean) \fIfalse\fR"
If this is set to
.BR true ,
.B olwm
moves the entire image of the window when you drag it.
If
.BR false ,
.B olwm
moves just an outline of the window.
The former is prettier; the latter is faster.
.IP "\fBEdgeMoveThreshold \fR(integer) \fI10\fR"
When you move a window or an icon,
.B olwm
pauses when the window or icon touches the edge of the screen.
This allows you to easily position the window right against
the edge of the screen.
If you move farther, the window or icon continue to move past the edge.
.II hysteresis
The name for this action is
The amount of ``hysteresis''; and it is set by this resource.
To prevent windows from ever lapping off the screen,
set this resource to an extremely large value (say, 10,000);
to disable this feature entirely, set this resource to zero.
.IP "\fBFlashCount \fR(integer) \fI6\fR"
The number of times the title bar is flashed when the menu item
.B Owners?
is activated.
.IP "\fBFlashTime \fR(integer) \fI100,000\fR"
The number of microseconds for which the title bar is flashed when you
active the menu item
.BR Owner? .
.IP "\fBFocusLenience \fR(boolean) \fIfalse\fR"
If this is set to
.BR true ,
.B olwm
does not enforce the ICCCM requirement that windows must have the input hint
set in order to receive the input focus.
This option is useful when you run
clients that are not ICCCM-compliant, such as many X11R3-based clients.
.IP "\fBForeground \fR(color) \fIblack\fR"
The foreground color.
This color is used mainly for the text of window and icon titles, and in menus.
.IP "\fBGlyphFont \fR(font name)"
The glyph font used for drawing \*(OL graphics.
Changing this font is useful mainly for changing its size.
Specifying a different font, such as a
text font, will result in undesirable behavior.
The default is:
.DM
	\-sun\-open look glyph\-*\-*\-*\-*\-*\-120\-*\-*\-*\-*\-*\-*
.DE
.IP "\fBIconFlashCount \fR(integer) \fI3\fR"
The number of times to flash the open/close ``zoom'' lines.
.IP "\fBIconFlashOffTime \fR(integer) \fI1\fR"
The amount of time to pause while open/close ``zoom'' lines are not visible.
.IP "\fBIconFlashOnTime \fR(integer) \fI20,000\fR"
The amount of time to pause while open/close ``zoom'' lines are visible.
.IP "\fBIconFont \fR(font name) \fILucida-Sans\fR"
The font used for icon names.
.IP "\fBIconLocation \fR(enumeration) \fItop\fR"
Where to locate an icon by default.
This can be one of the following:
.DS
.ta 0.5i 1.75i
	\fBtop-lr\fR	Top, from left to right
	\fBtop-rl\fR	Top, from right to left
	\fBleft-bt\fR	Left margin, from top to bottom
	\fBleft-tb\fR	Left margin, from bottom to top
	\fBright-bt\fR	Right margin, from bottom to top
	\fBright-tb\fR	Right margin, from top to bottom
.DE
.IP
The words
.BR top ,
.BR bottom ,
.BR left ,
and
.B ight
are synonyms for, respectively,
.BR top-lr ,
.BR bottom-lr ,
.BR left-tb ,
and
.BR right-tb . 
.IP "\fBInvertFocusHighlighting \fR(boolean) \fIfalse\fR"
When
.B olwm
is in click-to-focus mode, the input focus is normally indicated by a solid
rectangle in the title bar.
When it is in focus-follows-mouse, the focus normally
is indicated with two lines in the title bar.
If this resource is
.BR true ,
these conventions are reversed.
.IP "\fBKeepTransientsAbove \fR(boolean) \fItrue\fR"
This specifies whether
.B olwm
should attempt to keep transient windows above their owner window.
.IP "\fBKeyboardCommands \fR(enumeration) \fIBasic\fR"
This resource sets the what keys are available from the keyboard.
The legal values are as follows:
.RS
.IP \fBSunView1\fR
Keys
.B Open
and
.B Front
are active.
.IP \fBBasic\fR
Keys
.BR Open ,
.BR Front ,
.BR Help ,
and the color-map keys are active.
.IP \fBFull\fR
All \*(OL Mouseless commands are active.
For details, see the section entitled \fBKey Binding\fR, below.
.IP "\fBMinimalDecor \fR(list of strings)\fR"
This resource lists the windows to be decorated minimally.
Such windows receive only a thin border and resize corners, with no
title bar or window button.
The value should be a white space-separated list of strings.
Each string should specify a class of applications or an instance
name, as passed in the property
.BR WM_CLASS .
Most applications set this property based on the name of the
executable (i.e., \fBargv[0]\fR).
.IP
For example, to specify that the clock
and the calculator should be decorated minimally,
Use the following resource:
.DM
	olwm.MinimalDecor: calctool clock
.DE
.IP
Many applications allow you to override the value of the property
.B WM_CLASS
by using the option
.B \-name
the command line.
.IP
By default, this is not set.
.IP "\fBMouseChordTimeout \fR(integer) \fI5\fR"
The number of milliseconds that
.B olwm
waits for second mouse event after it has received the first event.
This help it to distinguish a chord of mouse buttons (i.e., when mimicing the
center button on a two-button mouse) from two separate button events.
.IP "\fBMultiClickTimeout \fR(integer) \fI5\fR"
The tenths of a second that differentiates a double-click
from two single clicks.
.IP "\fBNumeric \fR(locale)\fR"
The numeric-format \*(OL locale category.
For details, see the section entitled
.BR "Locale Handling" ,
above.
By default, this is not set.
.IP "\fBPaintWorkspace \fR(boolean) \fItrue\fR"
If
.BR true ,
.B olwm
uses the resource
.B WorkspaceColor
to set the background color for the workspace (i.e, the root window).
.II xsetroot
If
.BR false ,
.B olwm
does not change the root window's background;
this is useful if you preferto set your own workspace color with
.B xsetroot
or a similar program.
.IP "\fBPPositionCompat \fR(boolean) \fIfalse\fR"
This resource
turns on backward compatibility for older applications that have a habit of
always setting the flag
.B PPosition
within the property
.BR WM_NORMAL_HINTS ,
even when they have not set a position.
This most often occurs with X11R3-based clients.
Without backward compatibility, these windows always appear
in the upper-left corner of the screen.
With backward compatibility, these
windows are positioned according to the default \*(OL window
placement policy, along the diagonal of the screen.
This option does not
affect windows that have had their geometry specified on the command line.
.IP "\fBPopupJumpCursor \fR(boolean) \fItrue\fR"
This resource
specifies whether to move the cursor automatically into pop-up windows.
.IP "\fBRaiseOnActivate \fR(boolean) \fItrue\fR"
This resource specifies whether to raise a window when it is activated via a
.B Mouseless
command.
.IP "\fBRefreshRecursively \fR(boolean) \fItrue\fR"
This resource determines the behavior of the
.B Refresh
menu items that appear on the window and workspace menus.
If its value is
.BR true ,
.B olwm
walks the window hierarchy and sends exposure events to each window.
This is useful for refreshing windows that have backing store.
If its value is
.BR false ,
.B olwm
maps a window and then unmap it;
this causes all windows underneath that do not have backing store
to get exposures.
.IP
When this feature is on, the
.B Refresh
operation generates a large amount of client-server traffic.
It may be useful to turn this feature off if the connection transport has low
bandwidth or long latency.
.IP "\fBReverseVideo \fR(boolean) \fIfalse\fR"
If
.BR true ,
.B olwm
reverses the sense of black and white on monochrome screens.
This is ignored on color servers.
.IP "\fBRubberBandThickness \fR(integer) \fI1\fR"
This sets the thickness of the ``rubber-band'' line that
.B olwm
draws when it resizes a window,
when you select a group of windows by dragging a
rectangle on the root window,
or you move a window and the value of the
.B DragWindow
resource is false.
.IP "\fBRunSlaveProcess \fR(boolean) \fItrue\fR"
If this resource is
.BR false ,
.B olwm
does not invoke
.BR olwmslave
at startup time.
If the slave process is not running, Spot Help is not
available on objects that
.B olwm
owns, such as pushpins and resize corners.
.IP "\fBSaveWorkspaceTimeout \fR(integer) \fI30\fR"
This resource sets the
number of seconds to wait while the Save Workspace operation is in progress.
If not all applications have responded within this time,
.B olwm
regards the operation as having failed.
.IP "\fBSelectDisplaysMenu \fR(boolean) \fIfalse\fR"
If
.BR true ,
pressing the
.B SELECT
mouse button brings up a menu item's
submenu (if any), instead of executing the submenu's default action.
.IP "\fBSelectionFuzz \fR(integer) \fI1\fR"
This sets the number of pixels of ``fuzz'' to be used when
you select windows and icons by dragging a rectangle on the root window.
.B olwm
considers the object to fall within the selection
rectangle if it falls outside by ``fuzz'' or fewer pixels.
.IP "\fBSelectToggleStacking \fR(boolean) \fIfalse\fR"
If this resource is
.BR true ,
double-clicking on a window pushes it into the background instead of
zooming it to its full size.
.IP "\fBSelectWindows \fR(boolean) \fItrue\fR"
If this resource is
.BR false ,
the
.B SELECT
mouse button does not select windows and icons.
Its other functions are unaffected.
You can still use the
.B ADJUST
mouse button to select windows and icons.
.IP "\fBServerGrabs \fR(boolean) \fItrue\fR"
This resource controls whether
.B olwm
grabs the server while menus and notices are up.
.IP "\fBSetInput \fR(enumeration) \fIselect\fR"
This resource controls the input focus mode.
If its value is
.BR select ,
.B olwm
uses click-to-focus.
If its value is
.BR followmouse ,
.B olwm
uses focus-follows-mouse.
.IP "\fBShowMoveGeometry \fR(boolean) \fIfalse\fR"
This resource indicates whether
.B olwm
shows the geometry box while it moves windows and icons.
.IP "\fBShowResizeGeometry \fR(boolean) \fIfalse\fR"
This resource Indicates whether
.B olwm
shows the geometry box while it resizes windows.
.IP "\fBSnapToGrid \fR(boolean) \fIfalse\fR"
This resource determines whether
.B olwm
snaps icons to a grid when you move them.
.IP "\fBTextFont \fR(font name) \fILucida-Sans\fR"
This sets the font to use in the text of notices.
.IP "\fBTitleFont \fR(font name) \fILucida-Sans Bold\fR"
This resource sets the font used in the title bars atop windows and menus.
.IP "\fBTransientsSaveUnder \fR(boolean) \fItrue\fR"
This resource
specifies whether to turn on the save-under attribute of transient windows.
.IP "\fBTransientsTitled \fR(boolean) \fItrue\fR"
This resource
specifies whether transient windows should have title bars.
Normally, a transient window has a title bar and resize corners,
but no window button or pushpin.
.IP "\fBUse3D \fR(boolean) \fItrue\fR"
This resource
specifies whether to use three-dimensional \*(OL.
If false, the three-dimensional appearance is never used.
If true
.B olwm
uses the three-dimensional unless the display hardware cannot support it.
Note that the three-dimensional look can be used only with the color server.
.IP "\fBUse3DFrames \fR(boolean) \fIfalse\fR"
This resource
specifies whether to use a three-dimensional appearance on the frame borders.
If
.BR true ,
.B olwm
gives the frames a three-dimensional appearance;
otherwise, it gives them the same thick border as the two-dimensional
format.
Some users prefer the appearance of three-dimensional frames,
but with them it is more difficult to distinguish selected from
unselected windows.
.IP \fBUse3DResize \fR(boolean) \fIfalse\fR"
This resource specifies whether to use two-dimensional or three-dimensional
resize corners.
If it is
.BR true ,
.B olwm
uses the three-dimensional corners; if it is
.BR false ,
.B olwm
uses two-dimensional corners.
.IP "\fBWindowColor \fR(color) \fI#ccc\fR"
This specify the color of windows.
This is the ``BG1'' color for three-dimensional \*(OL, which it
for the backgrounds of windows, menus, and notices.
.B olwm
creates the three-dimensional effect by using
highlight and shadow colors derived from this color.
The default specifies a 20% gray value.
.IP "\fBWorkspaceColor \fR(color) \fI#40a0c0\fR"
This gives the color to which
.B olwm
sets the root window upon startup.
To turn off this behavior, see the description of the
.B PaintWorkspace
resource.
.\" ========================================================================
.SH "Screen Resources"
In addition to the global resources described above,
.B olwm
also uses screen-specific resources.  
.PP
The first component of the resource specification
is the name of the command under which you invoke
.BR olwm :
usually, this is ``olwm''.
The second component is the screen number appended to the string `screen'.
The third component of the resource name is the name of the resource itself.
For example, the resource specification
.DM
	olwm.screen1.ReverseVideo: true
.DE
.PP
turns on reverse-videoing on screen number 1.
To affect all screens, you can use wildcard characters.
For example, the specification
.DM
	olwm*ReverseVideo: true
.DE
.PP
turns on reverse-videoing for all of the screens that
.B olwm
manages.
.PP
The following resources are available both globally and on a per-screen basis.
A screen-specific resource overrides the corresponding global
setting for that screen.
Note that screen specific settings for
.B WorkspaceColor
and
.B WindowColor
affect
.B olwm
only;
this may cause clashes with
.B XView
clients that only use the global setting:
.DM
	Background
	BorderColor
	Foreground
	ReverseVideo
	WindowColor
	WorkspaceColor
.DE
.PP
The following resources let you select visuals other than the screen's default.
Available visuals may be listed with the command
.BR xdpyinfo .
.IP "\fBDepth \fR(integer) \fInone\fR"
This resource
specifies the visual depth to be used when searching for visuals.
.IP "\fBVisual \fR(enumeration) \fInone\fR"
This resource
specifies the visual class to use when searching for visuals.
Valid visual classes are
.BR StaticGray ,
.BR GrayScale ,
.BR StaticColor ,
.BR PseudoColor ,
.BR TrueColor ,
and
.BR DirectColor .
Note that these names are case-sensitive.
.IP "\fBVisualID \fR(id) \fInone\fR"
This resource
specifies the visual identifier to be used.
Note that specifying a visual by its identifier
is not portable, as identifiers can vary from
server to server and even from one invocation of a server to the next.
.\" ========================================================================
.SH "Mouseless Operation"
.B olwm
implements \*(OL Mouseless operation.
This mode binds functions to keystrokes,
so that you can use
.B olwm
without recourse to a mouse or other pointing device.
Some Mouseless functions are also useful for ``cross-over'' users,
who may want to use them to accelerate mouse-based operations.
.II accelerator
For this reason, these keystrokes often are called ``accelerators''.
.PP
You can navigate from window to window using the
.BR "Next Application" ,
.BR "Previous Application" ,
.BR "Next Window" ,
and
.B "Previous Window"
functions, which are bound, respectively, to the keystrokes
.BR <alt-N> ,
.BR <alt-shift-N> ,
.BR <alt-W> ,
and
.BR <alt-shift-W> .
(A complete table of key bindings is given below.)
.PP
You can bring up the window menu and the workspace menu
by pressing, respectively,
.B <alt-M>
and
.BR <alt><shift>M .
Once a menu is up, you can navigate through it by pressing the arrow keys
or by pressing the first letter of the menu item you want.
To execute the current item, press \*(RT.
To cancel the menu, press
.BR <esc> .
.PP
You can also use Mouseless functions to move and resize windows.
To invoke the
.B Move
function, press
.BR <alt-F6> ;
then use the arrow keys to move the window in the desired direction.
You can also hold down the
.B <ctrl>
key to ``jump'' the window by a larger distance each time you press
an arrow key.
To invoke
.BR Resize ,
press
.BR <alt-F7> .
In Resize mode, the first
arrow key selects the edge you are moving, and subsequent arrow keys move
that edge.
For example, to shrink a window from the right (that is, to move
its right edge to the left) press
.B <alt-F7>
to invoke resizing on the current window,
then press the \*(LA key to move the edge to the left.
As in
.B Move
mode, you can hold down the
.B <ctrl>
key to ``jump'' the edge by a greater increment.
Press \*(RT to accept the new size or location;
press
.B <esc>
to abort the move or resize operation.
.\" ========================================================================
.SH "Key Bindings"
Key bindings are specified through resources.
There is one resource per function; the value of a function's resource
is the key (or keys) to which that function is bound.
.PP
A resource's value consists of a comma-separated list of key specifications.
Each specification, in turn, consists of a key symbol optionally
followed by modifier symbols;
the modifier symbols are separated by `+' signs.
For example, to bind a function to
.BR <F2> ,
.BR <ctrl-F2> ,
and <alt-shift-F4> ,
sets its resource to the value:
.DM
	F2,F3+Control,F4+Shift+Alt
.DE
.PP
You can use as a modifier
any key symbol whose key is in the modifier mapping.
You can also use
the following as aliases for common modifier key symbols:
.BR Shift ,
.BR Lock ,
.BR Control ,
.BR Ctrl ,
.BR Ctl ,
.BR Meta ,
.BR Alt ,
.BR Super ,
and
.BR Hyper .
.PP
Resource names begin with the name of the command by which you invoked
.B olwm
(usually ``olwm''),
followed by
.BR KeyboardCommand ,
followed by a resource name.
(Note that
.B KeyboardCommand
is singular; do not confuse it with the
.B KeyboardCommands
resource.)
For example, the
resource specification for setting the
.B Stop
function typically is:
.DM
	olwm.KeyboardCommand.Stop
.DE
.PP
The following list names every command that can be bound to a key,
plus the default key or keys to which it is bound.
Items marked with an asterisk `*'
involve a keyboard grab.
Other items are active only while
.B olwm
is in a mode, such as when a menu is up.
Note that most of the functions that
require grabs are active only when the
.B KeyboardCommands
resource is set to
.BR Full .
See the description of this resource in the section on Global Resources,
above.
.IP "\fBStop \fI(L1, Escape)\fR"
Abort the current mode or action.
.IP "\fBDefaultAction \fI(Return, Meta-Return, Enter)\fR"
Execute the default action for the current menu or notice.
.IP "\fBSelect \fI(space)\fR"
Select the current button.
.IP "\fBAdjust \fI(Alt-Insert)\fR"
Toggle the selected state of the current object.
.IP "\fBMenu \fI(Alt-Space)\fR"
Bring up a menu on the current object.
.IP "\fBInputFocusHelp \fI(?, Control-?)\fR"
Bring up Help on the object with the input focus.
.IP "\fBUp \fI(up-arrow)\fR"
Move up one item.
.IP "\fBDown \fI(down-arrow)\fR"
Move down one item.
.IP "\fBLeft \fI(left-arrow)\fR"
Move left one item.
.IP "\fBRight \fI(right-arrow)\fR"
Move right one item.
.IP "\fBJumpUp \fI(Control up-arrow)\fR"
Move up ten items.
.IP "\fBJumpDown \fI(Control down-arrow)\fR"
Move down ten items.
.IP "\fBJumpLeft \fI(Control left-arrow)\fR"
Move left ten items.
.IP "\fBJumpRight \fI(Control right-arrow)\fR"
Move right ten items.
.IP "\fBRowStart \fI(Home, R7)\fR"
Move to the start of the current row.
.IP "\fBRowEnd \fI(End, R13)\fR"
Move to the end of the current row.
.IP "\fBDataStart \fI(Control-Home)\fR"
Move to the start of the data.
.IP "\fBDataEnd \fI(Control-End)\fR"
Move to the end of the data.
.IP "\fBFirstControl \fI(Control-[)\fR"
Move to the first item.
.IP "\fBLastControl \fI(Control-])\fR"
Move to the last item.
.IP "\fBNextElement \fI(Tab, Control-Tab)\fR"
Move to the next item.
.IP "\fBPreviousElement \fI(Shift-Tab, Control-Shift-Tab)\fR"
Move to the previous item.
.IP "\fBOpen \fI(Alt-L7)\fR *"
Open the object with the input focus.
.IP "\fBHelp \fI(Help)\fR *"
Bring up Spot Help on the object under the pointer.
.IP "\fBLockColormap \fI(Control-L2)\fR *"
Install the color map of the subwindow under the pointer, and give the
color map focus to the top-level window containing the pointer.
For details,
see the section on color-map installation, above.
.IP "\fBUnlockColormap \fI(Control-L4)\fR *"
Revert to color-follows-mouse mode, and unset color map focus.
For details,
see the section on color-map installation, above.
.IP "\fBFront \fI(Alt-L5)\fR *"
Bring the object with the input focus to the front.
.IP "\fBFocusToPointer \fI(Alt-Shift-j)\fR *"
Set the focus to the window under the pointer.
.IP "\fBNextApp \fI(Alt-n)\fR *"
Move the focus to the next base window.
Windows are ordered clockwise, starting at the top.
Icons come after all windows, also in clockwise order.
Order proceeds from the last icon on a screen to the first window
of the next screen.
After the last screen, the order wraps back around to the first screen.
.IP "\fBPreviousApp \fI(Alt-Shift-n)\fR *"
Move the focus to the previous base window.
See the description of
.BR NextApp ,
immediately above, for details about the window traversal order.
.IP "\fBToggleInput \fI(Alt-T)\fR *"
Move the input focus to the previous window that had the input focus.
.IP "\fBNextWindow \fI(Alt-W)\fR *"
Move to the next window in the family of windows consisting of a base window
and a set of pop-up windows.
Windows are ordered clockwise, starting at the top of the screen.
.IP "\fBPreviousWindow \fI(Alt-Shift-w)\fR *"
Move to the previous window in the family of windows consisting of a base
window and a set of pop-up windows.
Windows are ordered clockwise, starting at the top of the screen.
.IP "\fBTogglePin \fI(Meta-Insert)\fR *"
Toggle the state of the pin of the window with the input focus.
.IP "\fBSuspendMouseless \fI(Alt-z)\fR *"
Temporarily suspend all key grabs associated with Mouseless operation.
.IP "\fBResumeMouseless \fI(Alt-Shift-z)\fR *"
Resume grabs after temporary suspension.
.IP "\fBQuoteNextKey \fI(Alt-q)\fR *"
Pass the next key sequence to the application with the focus;
ignore all grabs.
.IP "\fBRefresh \fI(Alt-F8)\fR *"
Repaint the window with the focus.
.IP "\fBBack \fI(Alt-F5)\fR *"
Move the focus window behind other windows.
.IP "\fBOpenClose \fI(Alt-F2)\fR *"
Toggle the open/close state of the window with the focus.
.IP "\fBFullRestore \fI(Alt-F3)\fR *"
Toggle the full-sized/normal-sized state of the window with the focus.
.IP "\fBQuit \fI(Alt-F9)\fR *"
Quit the window with the focus.
.IP "\fBOwner \fI(Alt-F10)\fR *"
Flash the owner of the pop-up window with the focus.
.IP "\fBWorkspaceMenu \fI(Alt-Shift-M)\fR *"
Bring up the workspace menu.
.IP "\fBWindowMenu \fI(Alt-m)\fR *"
Bring up the window menu on the window with the focus.
.IP "\fBMove \fI(Alt-F6)\fR *"
Move the window with the focus.
.IP "\fBResize \fI(Alt-F7)\fR *"
Resize the window with the focus.
.IP "\fBOpenClosePointer \fI(L7)\fR *"
Toggle the open/close state of the window or icon under the pointer.
.IP "\fBRaiseLower \fI(L5)\fR *"
Raise the window under the pointer if obscured by other windows.
Otherwise, lower the window if it obscures other windows.
.\" ========================================================================
.SH "Modifier Customization"
.B olwm
alters the operation of certain mouse-based functions based on the
state of modifier keys.
It uses resources to control the relationship between the alteration
and the associated modifier keys.
The name of each resource is prefixed with the name of the command by
which you invoked
.BR olwm
(usually ``olwm''),
followed by the word
.BR Modifier ,
followed by a resource from the list below.
For example, the following the resource specification
binds the
.B Reduce
modifier:
.DM
	olwm.Modifier.Reduce
.DE
.PP
The value of each resource is a comma-separated list of modifier key
symbols.
The following list names each resource that can be modified, gives
its default modifier, and describes what it does.
.IP "\fBConstrain \fI(Control)\fR"
Constrain a move or resize operation to be only horizontal or vertical.
.IP "\fBIgnore \fI(Lock, NumLock, mod5, Mode_switch)\fR"
The set of modifiers to be ignored when processing mouse events.
This resource should contain the set of locking modifiers,
so that mouse actions are still interpreted properly even while
locking modifiers are in effect.
.IP "\fBInvert \fI(Shift)\fR"
When moving windows, temporarily invert the sense of the
.B DragWindow
resource.
When resizing a window, temporarily move the window as long as
this modifier is held down.
Return to resizing when the modifier is released.
.IP "\fBReduce \fI(Meta)\fR"
When moving windows, reduce the amount of mouse motion by a factor of ten.
.IP "\fBSetDefault \fI(Control)\fR"
Sets the default item for a menu.
.IP "\fBWMGrab \fI(Alt)\fR"
This modifier allows access to the mouse-button functions
anywhere over the window, not just over the window's title bar and border.
.\" ========================================================================
.SH "Environmental Variables"
.B olwm
reads the following environmental variables:
.IP "\fBDISPLAY\fR"
The X11 server to which to connect.
.IP \fBLANG\fR
.IS \fBLC_CTYPE\fR
.IS \fBLC_MESSAGE\fR
.IS \fBLC_TIME\fR
These name the locale to use when other methods of locale
announcement are not available.
For details, see the section on locale handling, above.
.IP \fBOLWMMENU\fR
This names the file that holds the Workspace Menu.
.\" ========================================================================
.SH Files
.B olwm
uses the following files:
.IP \fB$HOME/.openwin-menu\fI.locale\fR
This holds your personalized window menu for
.IR locale .
.IP "\fB$HOME/.openwin-menu\fR"
This holds your personalized window menu.
If this file does not exist,
.B olwm
uses the contents of
.BR /usr/X11/lib/openwin-menu .
.IP \fB$OPENWINHOME/lib/openwin-menu\fI.locale\fR
This file the default menu for
.IR locale .
By default,
.B $OPENWINHOME
is
.BR /usr/X11/lib .
.IP \fB$OPENWINHOME/lib/openwin-menu\fR
Contains the default Workspace Menu specification.
By default,
.B $OPENWINHOME
is
.BR /usr/X11/lib .
.IP \fB$HOME/.openwin-init\fR
.B olwm
writes into this file
the command lines obtained during the
.B "Save Workspace"
operation.
.\" ========================================================================
.SH "See Also"
.B
fvwm,
fwm,
olvwm,
twm,
X applications
.R
.PP
Rosenthal, David S.H.:
\fIInter-Client Communication Conventions Manual for X11.\fR
Boston, Massachusetts Institute of Technology, 1989.
This document is commonly known as the ``ICCCM''.
It is the X Consortium Standard that specifies conventions to which all X11
clients must adhere.
.PP
Sun Microsystems, Incorporated:
\fI\*(OL Graphical User Interface Functional Specification.\fR
Englewood Cliffs, NJ, Addison-Wesley Publishing Company, Incorporated, 1989,
ISBN 0-201-52365-5.
.PP
Unix Systems Laboratories:
\fI\*(OL Graphical User Interface
International Extensions Functional Specification.\fR
Draft 1.1 (May 10, 1990).
.\" ========================================================================
.SH Notes
The resource names do not follow any classing structure.
There is no general way to specify resources on a per-client basis.
.PP
There is no way to reconfigure the mouse buttons.
This makes it impossible to use
.B olwm
on a system that has a one-button mouse with no provision for simulating
a second or third mouse button.
.PP
The
.B Exit
menu item on the Workspace Menu does not really shut down the server.
It kills off all clients being managed by the window manager,
then exits the window manager itself.
This works properly if some outside agent such as
.B xinit
or
.B xdm
is waiting for the window manager or a client to exit.
The outside agent will take care of shutting down the server or
reinitializing it.
If you have started up the server a different way, this option may not work.
Instead, the server will be left running with no clients and no window manager
running, and you will have to login from elsewhere to kill the server.
An alternative is to add the following entry to the root menu:
.DM
	Exit	POSTSCRIPT shutdownserver
.DE
.PP
This shuts down the server immediately, with no confirmation whatsoever.
.PP
.B olwm
is fairly simplistic about how it manages its keyboard bindings.
For example, if you bind a function to
.BR <ctrl-F2> ,
.B olwm
grabs F2 with the
.B <ctrl>
modifier and with all combinations of the
.B <Lock>
and
.B <NumLock>
modifiers.
If another locking modifier is in effect,
.BR olwm 's
passive grab will not be activated, and thus the function will not work.
.PP
.B olwm
cannot manage multiple locales at one time;
therefore, all clients should be running in the same locale.
The
.B C
locale is the exception.
Applications using the
.B C
locale (such as non-internationalized applications) can be mixed with
applications that use one other locale.
.PP
.B olwm
does not handle different sizes of the glyph fonts well.
Each locale can define a different size for the default font
(for example, the default glyph font size is 12 for the
.B C
locale and is 14 for the
.B japanese
locale).
.B olwm
does not re-position the window decorations after switching locale;
therefore, the window decorations may appear to be wrong.
To remedy this problem partially,
.B olwm
does not change the font when the locale switches from a
non-\fBC\fR locale to the
.B C
locale
(fonts for non-\fBC\fR locales are always supersets of the font for
.B C
locale).
.PP
There is no input focus feedback for nonrectangular windows.
The title string of nonrectangular windows cannot be displayed.
.PP
.B olwm
does not dynamically track screen-specific resources.
Only changes to global resources are applied.
.PP
The interaction of the
.BR AutoColorFocus ,
.BR ColorFocusLocked ,
and
.B ColorTracksInputFocus
resources and the color locking and unlocking keys is overly complex.
.PP
.II "Munk, Udo"
.B olwm
was ported to \*(CO by Udo Munk.
.PP
Please see the file
.B LEGAL_NOTICE
that is included with the source code to
.B olwm
for copyright information.
