tlastran@esunix.UUCP (Tom LaStrange) (04/08/88)
This is the manual page for the window manager I've been working
on. Please look over it and if you find that I am missing some
features of uwm that you like, or if I don't have some features
that you would like to see, drop me a line.
--
Tom LaStrange
Evans & Sutherland Computer Corporation
UUCP Address: {ihnp4,seismo}!utah-cs!utah-gr!uplherc!esunix!tlastran
Alternate: {ihnp4,decvax}!decwrl!esunix!tlastran
--------------- cut here --------------------
.de EX \"Begin example
.ne 5
.if n .sp 1
.if t .sp .5
.nf
.in +.5i
..
.de EE
.fi
.in -.5i
.if n .sp 1
.if t .sp .5
..
.TH TWM 1 "6 April 1988" "X Version 11"
.SH NAME
.PP
twm - a window manager for X11 (Tom's Window Manager)
.PP
.SH SYNTAX
.PP
\fBtwm \fP[-display \fIdisplay\fP]
.PP
.SH DESCRIPTION
.PP
The \fItwm\fP program is a window manager client
application of the window
server.
.PP
The \fItwm\fP program was written to try and incorporate some of the
desirable features of both the \fBwm\fP and \fBuwm\fP window managers.
\fITwm\fP puts a title bar on and re-parents each window.
The title bar contains the
window's name and three "buttons". When a pointer button press event
is detected in any of these title bar "buttons" a certain action is
performed. The left-most title bar button that looks like a window pane
causes the window to be iconified. The right-most title bar button with
the right-angles is the re-size button. The resize function is identical
to the window resize function of the \fBwm\fP window manager. The other
title bar button is supposed to represent a keyboard, a button click here
causes the input focus to be directed to this window until the \fBf.focus\fP
function is executed or another window is selected to get input focus.
The title bar has the additional feature of becoming highlighted if the
window has the input focus.
.PP
When \fItwm\fP is invoked, it attempts to read a \fItwm\fP startup file.
The name of the \fItwm\fP startup file is:
.sp
$HOME/.twmrc\fP
.PP
The \fItwm\fP startup file can be thought of as having three logical
sections: the variables section, the buttons section, and the menus
section. The variables section must come first, followed by either the
buttons section or the menus section.
.PP
All variables and keywords may be
entered in any combination of upper and lower case letters. Title
functions and Root functions must be entered in lower case. A
pound sign (#) character in the startup file indicates a comment
which is terminated by the newline character. A \fIstring\fP in
the startup file is a series of characters enclosed by double quotes.
.PP
.SH VARIABLES SECTION
.PP
Variables must be entered first, at the top of the startup
file. Variables are initialized once when \fItwm\fP begins
execution, they will not be effected when a \fBf.twmrc\fP
function is executed.
.IP "\fBBorderWidth\fP \fIpixels\fP" 20
This variable specifies the width in pixels of of the border surrounding all
windows. The default is 2.
.IP "\fBIconFont\fP \fIstring\fP" 20
This variable names the font to be displayed within icons. The default
is "8x13".
.IP "\fBMenuFont\fP \fIstring\fP" 20
This variable names the font to be displayed within menus. The default
is "8x13".
.IP "\fBTitleFont\fP \fIstring\fP" 20
This variable names the font to be displayed within
the window title bar. Note that the title bar is only 17 pixels in height,
so the largest practical font would be something like "9x15". The default
is "8x13".
.IP "\fBReverseVideo\fP" 20
This variable causes \fItwm\fP to display white characters
on a black background,
rather than black characters on white.
.IP "\fBUnknownIcon\fP \fIstring\fP" 20
This variable specifies the file name of a bitmap format file to be
used as the default icon. This bitmap will be used for the icon of all
clients which do not provide an icon bitmap. The default is to use
no bitmap.
.IP "\fBWarpCursor\fP" 20
This variable causes the pointer cursor to be warped to a window which
is being deiconified. The default is to not warp the cursor.
.PP
.SH BUTTONS SECTION
.PP
The buttons section of the startup file contains definitions of functions
to perform when pointer buttons are pressed. There are two classes of functions
that can be tied to a pointer button: Title functions, which will be
executed if a pointer button is pressed while the pointer is in
the title bar of a window; and Root functions, which will be executed
while the pointer is in the root window or if the client program is
not processing pointer button events.
.PP
Title functions are assigned as follows:
.IP "\fBTitleButton\fP\fIn\fP \fIt.function\fP" 20
\fBTitleButton\fP is a startup file keyword. The \fIn\fP following
\fBTitleButton\fP can be a number between 1 and 5 to indicate which pointer
button the function is to be tied to. \fIt.function\fP may be any one of the
following title functions.
.PP
.SH Title Functions
.PP
.IP \fBt.lower\fP 20
This function lowers the window to the bottom of the stacking order.
.IP \fBt.move\fP 20
This function causes a grid to appear over the window which can be moved
to where you want the window to be moved. Double clicking the pointer
button tied to this function causes a constrained move function to be
executed. The pointer will be warped to the center of the grid.
Moving the pointer to one of the grid lines will cause the window
to begin moving in either an up-down motion or a left-right motion
depending on which grid line the pointer was moved across.
.IP \fBt.nop\fP 20
This function does nothing.
.IP \fBt.raise\fP 20
This function raises the window to the top of the stacking order.
.PP
The defaults for title functions are as follows:
.PP
.IP
\fBTitleButton1 t.raise\fP
.IP
\fBTitleButton2 t.move\fP
.IP
\fBTitleButton3 t.lower\fP
.IP
\fBTitleButton4 t.nop\fP
.IP
\fBTitleButton5 t.nop\fP
.PP
Root functions are assigned either to a pointer button or a menu entry.
The \fBf.title\fP function is the only one that doesn't really make
sense to use as just a button function. It was designed to be used in
a pull-down menu. Root functions are assigned to pointer buttons
as follows:
.PP
.IP "\fBButton\fP\fIn\fP \fIfunction\fP" 20
\fBButton\fP is a startup file keyword. The \fIn\fP following
\fBButton\fP can be a number between 1 and 5 to indicate which pointer
button the function is to be tied to. \fIfunction\fP may be any one of the
following root functions.
.PP
.SH Root Functions
.PP
.IP "\fB!\fP \fIstring\fP" 20
This function causes \fIstring\fP to be sent to /bin/sh for execution.
.IP "\fB^\fP \fIstring\fP" 20
This function causes \fIstring\fP followed by a new line character
to be placed in the window server's cut buffer.
.IP "\fBf.circledown\fP" 20
This function causes the top window that is obscuring another window to
drop to the bottom of the stack of windows.
.IP "\fBf.circleup\fP" 20
This function raises the lowest window that is obscured by other windows.
.IP "\fBf.file\fP \fIstring\fP" 20
This function assumes \fIstring\fP is a file name. This file is read into
the window server's cut buffer.
.IP "\fBf.focus\fP" 20
This function assigns input focus to the root window.
.IP "\fBf.menu\fP \fIstring\fP" 20
This function assigns the pull-down menu named \fIstring\fP to a pointer
button. If this function is used as an entry in a pull-down menu a
pull-right menu will be assigned to the menu entry.
.IP "\fBf.nop\fP" 20
This function does nothing.
.IP "\fBf.quit\fP" 20
This function causes \fItwm\fP to exit.
.IP "\fBf.refresh\fP" 20
This function causes all windows to be refreshed.
.IP "\fBf.title\fP \fIstring\fP" 20
This function is to be used as an entry in a pull-down menu. It centers
\fIstring\fP in a menu entry and outlines it with a border. This function
may be used more than once in a pull-down menu.
.IP "\fBf.twmrc\fP" 20
This function causes the \fI$HOME/.twmrc\fP file to be re-read. This
function is intended to be used only to re-build pull-down menus. None
of the \fItwm\fP variables are changed.
.IP "\fBf.version\fI" 20
This function causes the \fItwm\fP version window to be displayed. This
window will be displayed until a pointer button is pressed or the
pointer is moved from one window to another.
.PP
.SH MENUS SECTION
.PP
The menus section is where pull-down menus are defined. Entries in
menus consist of Root functions as described in the Buttons Section.
The syntax to define a menu is:
.EX 0
\fBMenu\fP "\fImenu name\fP"
{
\fIstring\fP \fIfunction\fP
\fIstring\fP \fIfunction\fP
.
.
\fIstring\fP \fIfunction\fP
}
.EE
.PP
The \fImenu name\fP should be an identical string to one being
used with an \fBf.menu\fP Root function.
Note that the \fImenu name\fP is case sensative. The \fIstring\fP portion
of each menu entry will be the text which will appear in the menu.
The \fIfunction\fP portion of the menu entry is one of the Root functions
described in the previous section.
.PP
.SH SPECIAL FEATURES
.PP
Since the X11 xterm does not provide an icon, \fItwm\fP can provide
a reasonable looking one for you. When \fItwm\fP is framing a
window it looks at the name of the window to determine if it should
add an appropriate icon for xterm windows. The names it looks for are:
.EX 0
xterm
yterm
console
login
.EE
If \fItwm\fP finds any of the above names as the first part of the window
name, the \fItwm\fP xterm icon bitmap is assigned as the bitmap
to display when the window is iconified.
.PP
If the window name begins with the string "xterm_", only the portion of the
name following the "xterm_" will be displayed as the window name in the
title bar. For example: an xterm started with "-T xterm_iguana" would
display the name "iguana" in the title bar.
.PP
.SH EXAMPLES
.PP
The following is an example \fItwm\fP startup file:
.EX 0
#**********************************************************************
#
# .twmrc
#
#**********************************************************************
WarpCursor
UnknownIcon "/usr/ias_soft/tlastrange/.icon"
BorderWidth 2
TitleFont "8x13"
MenuFont "8x13"
IconFont "8x13"
Button1 f.menu "button1"
Button2 f.menu "button2"
Button3 f.menu "button3"
Button4 f.nop
Button5 f.nop
TitleButton1 t.raise
TitleButton2 t.move
TitleButton3 t.lower
TitleButton4 t.nop
TitleButton5 t.nop
menu "button1"
{
"Sun Systems" f.title
"iguana" !"xterm -T xterm_iguana =80x24+100+100 -e rlogin iguana &"
"worm" !"xterm -T xterm_worm =80x24+100+100 &"
"shiva" !"xterm -T xterm_shiva =80x24+200+200 -e rlogin shiva &"
"tegus" !"xterm -T xterm_tegus =80x24+200+200 -e rlogin tegus &"
"Vax Systems" f.title
"shade" !"xterm -T xterm_shade =80x24+200+200 -e rlogin shade &"
"bilbo" !"xterm -T xterm_bilbo =80x24+250+250 -e rlogin bilbo &"
"frodo" !"xterm -T xterm_frodo =80x24+300+300 -e rlogin frodo &"
"esunix" !"xterm -T xterm_esunix =80x24+350+350 -e rlogin esunix &"
"lynx8" !"xterm -T xterm_lynx8 =80x24+390+390 -e rlogin lynx8 &"
}
menu "button2"
{
"Window Ops" f.title
"Refresh" f.refresh
"Focus on Root" f.focus
"Source .twmrc" f.twmrc
"twm Version" f.version
}
menu "button3"
{
"Cut Buffer" f.title
"Procedure Header" f.file "/usr/ias_soft/tlastrange/src/proc.twm"
"File Header" f.file "/usr/ias_soft/tlastrange/src/file.twm"
"pull right" f.menu "blob"
}
menu "blob"
{
"pull right" f.menu "final"
"another" ^"some text"
}
menu "final"
{
"entry 1" f.nop
"entry 2" f.nop
"entry 3" f.nop
"entry 4" f.nop
}
.EE
.PP
.SH BUGS
.PP
\fITwm\fP needs to deal with color displays at some point. Only
monochrome is currently supported.
.PP
Pull-right menus may still have some problems. They may sometimes
stay around when all pointer buttons have been released.
.PP
.SH FILES
.PP
$HOME/.twmrc
.PP
.SH SEE ALSO
.PP
X(1), Xserver(1)
.SH COPYRIGHT
.ce 4
COPYRIGHT 1988
Evans & Sutherland Computer Corporation
Salt Lake City, Utah
All Rights Reserved.
.LP
THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE AND
SHOULD NOT BE CONSTRUED AS A COMMITMENT BY EVANS & SUTHERLAND.
EVANS & SUTHERLAND MAKES NO REPRESENTATIONS ABOUT THE SUITABILITY
OF THIS SOFTWARE FOR
ANY PURPOSE. IT IS SUPPLIED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY.
.LP
IF THE SOFTWARE IS MODIFIED IN A MANNER CREATING DERIVATIVE COPYRIGHT RIGHTS,
APPROPRIATE LEGENDS MAY BE PLACED ON THE DERIVATIVE WORK IN ADDITION TO THAT
SET FORTH ABOVE.
.LP
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted, provided
that the above copyright notice appear in all copies and that both the
copyright notice and this permission notice appear in supporting documentation,
and that the name of Evans & Sutherland not be used in advertising
or publicity pertaining to distribution of the software without specific,
written prior permission.
.SH AUTHOR
Tom LaStrange,
Evans & Sutherland, Interactive Systems Division, Salt Lake City, Utah.