.\" @(#)xwindow	1.2	2/10/92
.H1 "The X Window System"
.pp
Pigi uses the X window system, version 11 release 5 (X11R5).
It will also run correctly under X11R4 and under Sun Open Windows.
This section provides just enough information about using X
so that if you are not familiar with it you will nonetheless
be able to get started.
Complete documentation, however
would be helpful.
Complete guides to the X window system are
available in many technical bookstores.
If you are familiar with X, and your user account
is properly configured to run X11R4 or X11R5, you may skip
the rest of this section, proceeding directly to the \*(PT demos.
Pigi will automatically load the resources it needs
for operation.
If you wish to customize these resources, it may be useful
to scan this section.
Resources are explained below.
.H2 "Starting X"
.pp
If your user account has already been set up to run \*(PT, you may
skip this section.
There are two principal ways that X may be configured:
.bu
The X server may be running all the time.  In this configuration,
when no one is logged in a single window together with a background
appears.  You don't have to worry about starting X.  A daemon
program called
.i xdm
is responsible for logging you in.
.bu
The user may be responsible for starting X \- in this case, when
you log in you get a bare Sun (or VaxStation or DecStation) tube.
.pp
Our sample configuration attempts to support both to some degree.
If
.i xdm
is running, it will use the supplied .xsession file to set up
windows.  If xdm is not running, and the user is on a bare Sun
tube, the
.i xinit
program will fire up, starting the X server; the .xinitrc file
is used in this case to configure windows.
The supplied .xinitrc file reads:
.IE ".xinitrc file"
.IE ".xsession file"
.(c
xrdb $HOME/.Xresources
twm&
xterm -geometry 80x30+0-0 -fn 9x15 -name "bottom left" &
xclock -geometry 120x120-0+0 &
exec xterm -geometry +0+0 -fn 9x15 -name "login" -ls
.)c
The first line reads X resources from the file ~/.Xresources.
Then the window manager called ``twm'' is started.
The next three lines open windows using the xterm and xclock commands.
The .xsession file works pretty much the same way for xdm installations.
The function of the mouse buttons is determined by
the ~ptolemy/.twmrc file.
This file is reasonably easy to interpret, even without any X experience,
so you may wish to examine it and customize it.
If your installation uses the X window system in some way that differs
from our default, then whoever installed \*(PT should have modified
the .login file above to reflect this.
.H2 "Manipulating Windows"
.pp
If you already know how to use the X Window system and you are using
your own window manager configuration rather than
the standard \*(PT configuration, you may skip this section.
Assuming you use the file ~ptolemy/.twmrc without modification,
rather than your own window manager,
the basic window manipulations are explained below.
Note that there are often several different ways to accomplish the
same objective.  Feel free to experiment with key and mouse button
combinations in various parts of the screen.
First, you must identify the ``meta'' key on your keyboard.
It may be labeled in any of various ways, including ``meta'', ``left'',
``right'', ``alt'', a small diamond,  or any of a number of other possibilities.
It is usually close to the shift and control keys.
Most window manipulations require that you hold down the meta key
while depressing mouse buttons.
.UH "Iconifying windows."
.lp
Depressing the meta key, and clicking the left mouse button in any window
will iconify it.
The window disappears, replaced by a symbol in the icon manager at the right
of the screen.
To get the window back, place the cursor in the appropriate slot
of the icon manager, and click the left mouse button.
An alternative iconifying mechanism is to click any mouse button
on the icon symbol at the left of the window header.
.UH "Moving windows."
.lp
Holding the meta key and dragging with the middle mouse button will move
a window.  ``Dragging'' simply means to hold the mouse button while
moving the mouse.
Alternatively, you can drag the
left button in the middle of the window header.
.UH "Resizing windows."
.lp
The meta key and right mouse button can be used to resize a window.
Place the mouse cursor near a corner of a window, depress the meta key,
and drag the right button.
Alternatively, without the meta key,
any button in the rightmost corner of the window header will resize the window.
.UH "Mnemonic."
.lp
The window header has an iconify icon at the left, a blue bar for moving
the window in the middle, and a resize symbol at the right.
Correspondingly, without going to the window header, but using the meta key,
the left mouse button will iconify a window, the middle button will move it,
and the right button will resize it.  Hence, the window header can be used
as a mnemonic to help remember which mouse button has which function when
the meta key is depressed.
.UH "Pick up and stuff."
.lp
In a text window, without the meta key, the mouse may be used to grab text
and put it somewhere else,  either in the same window, or in some other window.
This can be very useful to avoid copying long sections of text.
The left mouse button, when depressed and dragged, highlights a region
of text in a window, and stores the text.
The right button can be used to modify the extent of the highlighted
region.
The highlighted text is "picked up", stored for future use.
The middle button causes the highlighted text to be typed
to whatever window has the mouse cursor.
.UH "New windows."
.lp
A useful command, defined in ~ptolemy/.cshrc, is ``term''.
Typing this in any window, followed by a carriage return,
opens a new terminal window with a reasonable size and color.
You may change the size and location in the usual way.
.UH "Removing windows."
.lp
Most windows, including all pigi windows,
can be removed by typing control-D with
the mouse cursor in the window.
.H3 "Resources"
.pp
A \fIresource\fR in X is a parameter 
.IE resource
that customizes the behavior of applications that run under X.
For instance, resources determine the foreground and background
color of your windows.
Pigi requires that some resources be set.
These resources are defined in the file ~ptolemy/lib/pigiXRes,
and are automatically merged with whatever other resources you may
have defined.
The merging occurs when you invoke the startup script ~ptolemy/bin/pigi.
In addition to these required resources, there are many optional resources.
Some of these are set in ~ptolemy/.Xresources.
.pp
If you have not used the X window system before,
you will probably not have a file with the name .Xresources in your home
directory, and can simply copy the one from ~ptolemy.
This file defines some basic resources.
If you already have a file with this name, then you can probably
use the one you have as is.
.pp
VEM can be extensively customized using resources.
Please see the VEM section of the Almagest for instructions.
.EQ
delim $$
.EN
.\" Local variables:
.\" mode: nroff
.\" End:
