HELP PWMCHANGES                              Ben Rubinstein, Feb 1987
                                             Revised: Nic Ford, Apr 1987

Changes to the PWM interface between POPLOG versions 12.0 and 13.0

Keywords: PWM, news, 13

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

 -- Introduction
 -- Summary of signifigant changes from v12
 -- Getting old code to run with minimal changes
 -- Rewriting old code for the new interface
 -- Major new features

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

As users were warned might happen in the documentation for the PWM in
version 12 of POPLOG, the PWM and the interface to it has been
signifigantly changed for version 13.  The changes represent
considerable improvements in the convenience and power of the interface,
but inevitably must cause some problems for the owners of existing code.
We have endeavoured to keep these problems to a minimum, and the vast
majority of code should still run with few if any changes.  However,
users are strongly advised to revise code to make use of the new
software as soon as possible.

If you are trying to get some old code to work now, you may wish to skip
the next section for the moment.

Also, see HELP *V12PWM for an easier, but unguaranteed, method.

-- Summary of changes from v13 ----------------------------------------

The major change from v13 to v14 has been a rationalisation of the PWM
name-space. All old names have been kept as auto-loadable libraries with
synonyms to the new names; so all old programs should continue to work.
See HELP * PWMNAMES for details

-- Summary of signifigant changes from v12 ----------------------------

The first major change is that the documentation has been massively
expanded, from three help files to around sixteen, and with entries for
all functions in the "ved_whats" database (see HELP *VED_WHAT).  The
starting point for the documentation is now HELP *PWM.

The second change is that windows (and many other PWM-maintained
objects) are now represented by special identifier objects, where they
used to be represented by small integers.  This change brings with it
several benefits, including checking for validity in POPLOG calls,
garbage-collectible windows, and a signifigant decrease in confusion;
however, it may cause problems for any existing code which made use of
the fact that numbers were used (not that there was ever any reason why
programs should do that...).  See HELP *PWMGENERAL for more details.

The area of input suffered from the deadlines of version 12 and was the
least supported area of the PWM.  It has now been considerably cleaned
up.  Input events are now represented in a sensible and easily-handled
fashion, and there are a number of new functions available to help you
distribute events.  See HELP *PWMWINPUT for full details.

The various window-manipulation functions now take a window-id as an
argument, rather than acting on the window currently selected for text.
The latter association proved to be a signifigant piece of mis-design.
See HELP *PWMWINDOWS.

As well as separating the selection of a window as recipient for text
from the selection of a window for various other functions, the method
of selecting a window for text or graphics output has changed. They are
now each controlled by an active variable (see HELP *ACTIVE_VARIABLES)
which allows them to be conveniently localised by a function.  See the
files HELP *PWMWINDOWS and HELP *PWMGRAPHICS for details.

Finally, whereas in version 12 all PWM functions (unless they were built
in to the system) were defined in one of two libraries in either
"$popsunlib" or"$pophplib", all the functions which are not built in
are now defined in individual auto-loadable libraries in "$poppwmlib",
which allows programs to load only those functions they require.  VED no
longer needs any special setting up to work with the PWM (it used to
require either "$popsunlib" or"$pophplib" to be in -popautolist-); and
POPLOG and VED will now automatically look for "initpwm.p" and
"vedinitpwm.p" when they start up (see HELP *INITIAL).

-- Getting old code to run with minimal changes -----------------------

Although the changes that have been made since version 12 are extensive,
it should be possible to get old code running on the new version with
very few changes.  This section describes what you may need to do.  Two
things need to be emphasised: firstly, the effect of mixing the old and
new interfaces is somewhat undefined, so this is not recommended;
secondly, it is STRONGLY advised that you revise all programs to use the
new interface (which should have a much longer life-span!) as soon as
possible.  You will probably find that this revision consists mainly of
ripping out old code, rather having to write new: and in our experience
the revised programs will be much cleaner.

All the procedures which have changed their arguments or semantics from
version 12 have been given new names to avoid conflict with the old.
Functions with the old names which simulate the effect of the old
procedures in terms of the new are defined in the library files
LIB *PWMSUNUTILS and LIB *PWMSUNGRAPH, in $popsunlib.  In the
(unlikely?) event that your program did not load these files (because
it used only those functions which were defined in the core) you will
have to load LIB *PWMSUNUTILS, since none of the old functions are
now built-in.

Having loaded these libraries, there are just two areas where you are
likely to encounter problems.  As described above, one of these is
input: an input catching procedure which used to expect either a
character or string as its second argument will now receive a vector.
The structure of this vector is described in HELP *PWMINPUT.  As
suggested above, the changes you are likely to have to make to get your
program working with input are likely to involve principally the
deletion of now-redundant code, in this case code which parsed the
string into an event and possibly some numeric details of the event.

The second area which it is possible may cause you problems is in
window identifiers.  In version 12 these were integers: they are now
special records.  Thus mishaps with a message to the effect that numbers
are required, involving a window record (which print as
"<pwm-XXX-window...>", so are easily recognisable) represent this kind
of problem.  If the program was adding numbers in order to scan all the
windows it should really have been using -apppwmwindows-, and the
easiest solution would be to rewrite it do so (-apppwmwindows- has now
been replaced by the more powerful -pwm_scan_windows-, but as mentioned
above it is advisable to avoid mixing the interfaces).  If the code was
checking for a return value of -1 indicating a failure to make a new
window, it should note that such a failure causes a return value of
false.

-- Rewriting old code for the new interface ---------------------------

Obviously you should read as much as is relevant of the new
documentation (there is a tree at the end of HELP *PWM which may help
you see what is relevant).  The major structural changes have been noted
above.

The "ved_what" facility (see HELP *VED_WHAT) knows about both the old
and the new PWM interfaces: thus
    <ENTER> ? pwm_select <RETURN>

will print on the command line the message
    "Obsolete.  See -pwmtextwindow-"

and
    <ENTER> ? pwmtextwindow <RETURN>

will give a short description of the way to use the new facility:
    "<window-id> -> pwmtextwindow"

Using "<ENTER> ??" on one of the old functions will give you the name of
the help file in which its replacement is documented, and if you use
<ESC>-n to get to this and <ESC>-h to read it, VED will put you in the
appropriate HELP file, at the first reference to the new function.  Using
"<ENTER> ??" on one of the new functions will give you details of any
other call forms, and a short description of the new function.

Finally, it is worth mentioning the new "vedexpand" facility (see
HELP *VEDEXPAND).  With this, you could just put the cursor next to the
old PWM procedure and do "<ENTER> ? ^w" to find out the name of it's
replacement.

You can test that you have completely freed your code from the old
interface by making sure it can compile without having the library files
PWMSUNUTILS and PWMGRAPHICS loaded.

-- Major new features -------------------------------------------------

Finally, to prove that the change is not all bad news (and as an
incentive to switch over to the new interface) here is a brief survey of
major new features.

 - Text can now be written in either kind of window in different fonts
    (but terminal emulation facilities are only supported for the
    standard font).  See HELP *PWMFONTS.

 - "Pages" (invisible windows) are now available for storing bit-images
    etc off-screen.  This allows fast copying of images to the screen,
    inverting or flashing of arbitrary images, etc. (HELP *PWMGRAPHICS)

 - Colour functions are now supported (only on colour workstations!)
    (see HELP *PWMCOLOUR)

 - Sophisticated new facilities for tracking the mouse and giving fast
    visual feedback are available, see HELP *PWM_TRACK_MOUSE.

 - VED can be used in just the base window under the PWM, to allow all
    available windows to be used by programs, and to allow large
    numbers of files to be edited simultaneously. See HELP *PWMVED.

 - As well as the general handling of input having been vastly improved,
    there is a library to help distribute different kinds of mouse
    events in different areas of a window between different catcher
    procedures; and several libraries built on this to provide items
    of "window furniture" from which user interfaces can conveniently
    be built: see HELP *PWMINPUT, HELP *PWMITEMS.

 - Many other new functions are provided, for example to find out the
    size of the terminal emulation font; to set the position and
    iconic status of a new window before it has been made; and to find
    out the size of the workstation screen, whether it is a monochrome
    or colour screen, and what kind of workstation it is.

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