HELP SUNPWM                      -draft-     Ben Rubinstein January 1987

Details of using the PWM specific to the Sun-2 and Sun-3 versions.

Keywords: Sun, PWM, pwmtool

== CONTENTS - (Use <ENTER> g to access required sections) ==

 -- Introduction
 -- Invoking pwmtool
 -- Limits on windows and menus
 -- Selections and "stuff" in the base window
 -- Sun specific bugs

-- Introduction -------------------------------------------------------

The Poplog Window Manager (PWM) is is a device-independent system
providing graphical interfaces to VED and user programs on a variety of
workstations.  HELP * PWM describes its main features and gives an
overview of other documentation: this file discusses items
relating specifically to using the PWM on the Sun-2 and Sun-3
workstations.  It assumes you have read HELP * PWM.

-- Invoking pwmtool ----------------------------------------------------

The PWM is invoked from inside 'suntools' by running 'pwmtool'. As with
shelltool, this may be done from either another shell, by typing

    pwmtool

or from a '.suntools' file or menu (see MAN SUNTOOLS). In the first
case, error messages from the PWM will go to the window from which it
was invoked, otherwise they will go to the console window.

At startup, the PWM creates and 'opens' one window , referred to as the
base window. If pwmtool is invoked with no argument, it will run POP-11
in this window. However, just as with shelltool, optional arguments may
be specified. Thus for example

    pwmtool clisp

will run pwmtool with Common LISP.

The pwmtool accepts the "generic tool arguments" (see MAN SUNTOOLS), but
many of them are ignored.  In particular, the base window is always
started up as 24 rows of 80 columns; this cannot be changed until it has
started (and should not be changed until POPLOG is running in it,
otherwise it will probably not know about the size).  The most useful
arguments are those which determine the position of the icon.  For the
PWM, this argument will be set the position of the icon for the base
window: icons for other windows will be spaced in a line starting from
this position.  By default, the base window icon appears in the top left
corner of the screen, and other icons proceed along the top to the
right.  By using the "generic" argument "-WP" (icon position) you can
set the position of the base window icon; there is a new argument "-WD"
which allows you to specify the direction which the other icons will
take relative to this, as North South East or West.  For example,

    pwmtool -WP 1084 4 -WD South -Wi clisp

    will start up a pwmtool running Common LISP; the base window will
start iconic, in the top right corner of the screen; and other icons
will appear in a column below it.  (The argument to "-WD" can be
abbreviated to its initial letter.)

    If the combination of base window icon initial position and icon
direction is such as would cause an icon to be placed off the edge of
the screen, it will "wrap" round (appearing near the top if it would
have disappeared at the bottom, for example).

Care should be taken in specifying arguments to pwmtool: if it gets
confused about the arguments (or if you specify it should run something
that cannot be run, such as "closp") you may find it ends up running
itself (there will thus be two base windows, one on top of the other).
If this happens, try typing <CTRL> c to each window.

It is possible (if your installation allows it) to run POPLOG on another
machine through pwmtool running on the SUN. Thus:

    pwmtool rlogin <hostname>

With the current version, the remote machine that is running POPLOG must
be a UNIX machine, although in future versions this may not be the case.
In the current version, you will probably encounter some odd behaviour
on a remote machine, before you enter POPLOG and when you have left it:
there may be too much echoing, and you may find you have to use the
<line feed> key instead of <return>.  This behaviour should not affect
you while you are using POPLOG on the remote machine.  It is also
important to note that you cannot send an EOF character through the
PWM (in this version only); POPLOG, whether on a remote machine or
not, will accept <CTRL> z as an EOF character, however; this is
unaffected by any EOF characters you may have set using STTY.

NOTE FOR EXPERTS: POP-11 tests the environment variable TERM to see
whether it is running under a PWM. The SUN PWM sets this to 'pwmsun' for
the process it forks to run in the base window. But if you are doing
something weird, you must ensure that it is set up appropriately before
you enter POP-11 (or CLISP or PROLOG).


-- Limits on windows and menus -----------------------------------------

Windows on the SUN - both 'tool' windows and sub-windows - require
devices. The devices they require are the ones called  '/dev/winXX'. A
typical tool, such as a shelltool or a PWM window, takes two devices;
one for the outer 'tool' window and one for the inner sub-window, while
something like the icontool takes six. Thus the main limit on the total
number of windows that can be on the screen is the number of 'winXX'
devices in '/dev'.  A typical value for this on a SUN-2 seems to be 32,
while on a Sun3 it is generally much larger.  More such devices can be
set up by the system manager by using '/dev/MAKEDEV'.

However there is a further limit restricting the number of windows an
individual tool can make. This is the files-per-process limit which is
32. Since the PWM needs to keep various other files open in addition to
the two devices needed for each window (such as one to communicate with
POPLOG) it is possible to run into the PWM's private limit first. When
this happens, there will be a message on the PWM's standard error
saying:

    PWM: can't make window - too many PWM windows

In this case, the user will have to kill at least one PWM window before
another can be created.

If however there are a lot of other windows on the screen, and the
'global' limit (related to the number of /dev/winXX devices) has been
reached first, the message on the error output will read:

    PWM: can't make window - not enough window devices

In this case, getting rid of any of the windows on the screen, whether
they belong to the PWM or not, will alleviate the problem.

There is also a limit to the number of items that may be included in
a pop-up menu, and on the total size (in characters) of a menu. These
limits are currently (Version 13) set at:

    Maximum number of menu items            20
    Maximum size of menu (characters)      512

Reckless users may wish to to alter these limits by changing the
constants VW_MAXITEMS and ARGSTRSIZE in the file

    $usepop/pop/pwm/pwdec.h

and then rebuilding the PWM by giving these Shell commands

    % touch pwmenus.c
    % mkpwmtool


-- Selections and "stuff" in the base window --------------------------

The SUN pwmtool provides a slightly cruder version of the Shelltool's
"selection" mechanism, in the base window only.  The left button is used
to mark the beginning of the selected text, and the middle button the
end.  The selection is made when any input other than a mouse button is
received, when the mouse is moved out of the base window, or when output
is sent to any of the PWM's windows.  The position marked by the left
button is always the first character in the selection, and that marked
by the middle button always the last; thus pressing the middle button
with the mouse cursor at a position before the start of the current
selection cancels the selection, while pressing the left button always
starts a new selection.  Pressing the right mouse button in the base
window invokes a one-option menu; the option is to "stuff" the current
selection (which need not have come from a PWM window, of course).

You cannot directly use the mouse to select text out of any PWM window
other than the base window, but you can program the mouse (or anything
else) to make selections out of other PWM text windows, and to read in
the current selection.  See HELP * PWMGENERAL.

-- Sun specific bugs --------------------------------------------------

Because of a bug in Sun's colour software, the normal routines for
writing text in a window do not work properly if the window has more
than two colours.  It is therefore important that you do not assign a
colour map segment (see HELP * PWMCOLOURS) with more than two entries to
a text window.  However, the routines for writing "transparent" text
(i.e. only the pixels which are part of the character are affected,
rather than all the pixels in the character cell) do work properly with
colour windows.  So -pwm_gfxtext- (see HELP * PWMFONTS) has been
frigged, on the Sun version, to detect the colour case, and use the
transparent text routines in that case.  Therefore multiple colours and
text can co-exist in a graphics window, but the text routines run a
little slower and will only do transparent text in that case.  This bug
only applies to colour Suns.

Another bug on colour Suns concerns lines, which can only be drawn in a
downward direction (!).  This need not concern the user, but in order to
avoid the bug the -gfx_drawline- routine runs slightly slower in this
context.  This bug only applies to colour Suns.

The full range of menu features (see HELP * PWMMENUS) are not currently
supported by the Sun PWM.  This is a consequence of the necessity to
remain compatible, up to this version, with release 2.0 of Sun Unix.
Specifically, non-selectable options and horizontal separators are not
supported.  Consult HELP * PWMMENUS for details of the degradation path.

--- C.pwm/help/sunpwm -----------------------------------------
--- Copyright University of Sussex 1987. All rights reserved. ----------
