HELP PWM                                        Ben Rubinstein, Jan 1987
                                             Revised: Nic Ford, Apr 1987
                                        Revised: Gareth Palmer, Sep 1989

Introduction to the Poplog Window Manager and overview of documentation.

Keywords: PWM, VED

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

 -- Introduction
 -- Ensuring POPLOG is set up for use with the PWM
 -- PWM Documentation

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

The Poplog Window Manager (PWM) allows POPLOG to use the special features
of workstations with graphical interfaces employing windows and mice,
such as the Sun-2 or Sun-3, HP-9000/300, or Atari ST.  PWM windows may
be created and used either by VED to display files, or by user programs.
The windows provided by the PWM have terminal emulator functions and a
limited number of graphics facilities.  The PWM also supports use of
features such as pop-up menus and prompt-boxes, where the workstation
being used supports them.

One of the features of the PWM is that from the user's point of view, it
is device independent: that is, one can write a program using the PWM
facilities which opens some windows, writing text in one and then in
another, and drawing pictures in a third, and interacting with the user
via menus and mouse-buttons; and run this program with sensible
results on any of several different workstations.

Another major feature is that the PWM can be used even if POPLOG is not
running on the workstation that the user is sitting at, but instead is
running on a remote computer somehow connected to the user's workstation
(e.g. by Ethernet, or even just a terminal line).  Thus, if the details
of your site permit it, you can use a Sun-2 workstation to interact with
POPLOG running on a more powerful remote computer, with all the PWM
features available; and an Atari ST, which cannot at present run POPLOG
itself, can be used as a cheap terminal providing a graphics interface
to a machine which does not of itself provide such facilities, such as a
VAX.

The Poplog Window Manager really consists of three parts: a program
which runs on the workstation; a set of routines in POPLOG; and a
specification of a "language" by which the two can communicate.  The
POPLOG interface and the elements of the language are (for the most
part) at a sufficiently general level to overcome the differences
between the different window systems: the interpretation of these
commands to suit the style of the host workstation is undertaken by the
the PWM running on the workstation.

-- Ensuring POPLOG is set up for use with the PWM ----------------------

POPLOG has to know at that it is connected to the PWM.  Normally, the
PWM sets the environment variable TERM to a string starting with "pwm"
(eg "pwmsun" on a Sun), and POPLOG checks for this situation when it
starts up.  In certain kinds of remote or indirect usage, however, or
when using a PWM on something like an Atari ST, this information may be
lost.  There is a procedure -tryunderpwm- which can be used when pop11
is running (but must not be used if you are editing any files): if you
invoke it (with no arguments) POPLOG will try and establish
communication with the PWM.

If POPLOG knows when it is starting up that it is connected to a PWM, it
will look in your $poplib directory (that is, your top level directory)
for a file called "initpwm.p", and if it finds one will compile it (see
HELP *INITIAL). This may be used, for example, to ensure that any
library files you may need are loaded, or to define any macros or
procedures that you wish to use with the PWM.

In particular, many of the facilities you might wish to use with the PWM
are in the library '$poppwmlib'. Thus for example, the following could
be included in your 'initpwm.p' file:

    '$poppwmlib' :: popuseslist -> popuseslist;

In fact there is a library to do this, so you could just say:

    uses poppwmlib;

Similarly, when VED starts up it will look for a file in '$poplib'
called "vedinitpwm.p", and if it finds one will compile it after your
"vedinit.p" file (see HELP *INITIAL).  You can use this to customise the
behaviour of VED using the PWM: see HELP *PWMVED for more details.

-- Some notes on using the PWM ----------------------------------------

It is easy to be confused by the fact that in general when using windows
on most WIMP-style workstations, each window is attached to a different
process. Remember that when POPLOG is running under the PWM, all the
windows it owns are owned by the one POPLOG process: thus if you start
something going in one VED window (loading a large file, perhaps) and
then type into another, there will be no response to your input until
POPLOG has finished the previous task.

If you "Quit" the base window (by selecting an appropriate item from
a menu), you will have to leave POPLOG.  POPLOG will not run without the
base window existing: in fact, the response to quitting the base window
will be to quit POPLOG, and in this will not necessarily destroy the
window: if you were connected to POPLOG on a remote machine, you may
still have to logout out of the remote machine, and possibly perform
some other exit actions, and the PWM will keep the base window open
while you do this.

-- PWM Documentation --------------------------------------------------

The following help files exist for the PWM:

    DOC  *PWM         - technical details of PWM
    HELP *PWM         - this file: information to get you started, and
                        overview of the documentation.
    HELP *PWMVED      - information relating to using VED with the PWM.
    HELP *PWMCHANGES  - details the substantial changes to the PWM
                        facilities between version 12 and version 13 of
                        POPLOG.
    HELP *PWMNAMES    - full list of procedure names and post version 13
                        changes, and an outline of the naming scheme
                        itself.

Information specific to particular workstations using the PWM:

    HELP *SUNPWM      - details specific to Sun-2 and Sun-3 workstations

The top-level files to look at if you wish to use the PWM facilities in
your own programs are

    HELP *PWMGENERAL  - information you must know to program the PWM
    HELP *PWMWINDOWS  - general window creation and manipulation
    HELP *PWMGRAPHICS - graphics surfaces and facilities
    HELP *PWMINPUT    - input events and traps.

These files will also point you to files which go into greater detail of
certain features:

    HELP *PWMCOLOURS      - colour graphic facilities
    HELP *PWMMENUS        - facilities for using pop-up menus
    HELP *PWMFONTS        - different type faces in graphic windows
    HELP *PWMRASTERS      - raster graphic facilities
    HELP *PWM_TRACK_MOUSE - special mouse tracking facilities
    HELP *PWMITEMS        - selectable "items" in windows
    HELP *PWMWINIO        - character stream IO on user windows

It may be helpful to think of the help files as being arranged in a tree
as shown below; and then note that you should probably read at least all
the ancestors of a file before reading it.

                               PWM
                                |
     +----------+--------+------+----------+
     |          |        |      |          |
 PWMCHANGES  PWMNAMES  PWMVED   |       SUNPWM
                                |
                            PWMGENERAL
                                |
      +--------------+----------+-------+---------------+
      |              |                  |               |
  PWMWINDOWS    PWMGRAPHICS          PWMMENUS           |
                     |                                  |
           +---------+---------+                        |
           |         |         |                     PWMINPUT
      PWMCOLOURS  PWMFONTS  PWMRASTERS                  |
                                          +-------------+----------+
                                          |             |          |
                                   PWM_TRACK_MOUSE   PWMITEMS   PWMWINIO

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