 HELP PWMGENERAL                                 Ben Rubinstein, Feb 1987
                                             Revised: Nic Ford, Mar 1987
                                        Revised: Gareth Palmer, Jul 1987

General notes for programming the PWM, and miscellaneous PWM functions.

Keywords: PWM, identifiers

    ispwm_id(<item>) -> <boolean>

    pwm_idtype(<item>) -> <word|false>

    islivepwm_id(<item>) -> <boolean>

    pwm_get_selection()

    pwm_set_selection(<window-id>, <integer:X1>, <integer:Y1>,
                        <integer:X2>, <integer:Y2>)

    pwm_screenwidth() -> <integer>

    pwm_screenheight() -> <integer>

    pwm_screendepth() -> <integer>

    pwm_workstation() -> <word>


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

 -- Window and other identifiers
 -- Communicating with the PWM
 -- Selections
 -- Finding whether POPLOG is connected to a PWM, and what kind

-- Window and other identifiers ---------------------------------------

All PWM windows are referenced in POPLOG by a special record called a
"window identifier", or "window-id" for short.  The functions which make
a window return such an identifier, and the functions which destroy a
window, open or close a window, discover or change certain window
attributes and so on all take a window-id as one of their arguments.  If
you lose track of the window-id for a window you have created, you will
be unable to do anything with the window, including kill it.  For this
reason, when POPLOG notices (at the next garbage collection: see
HELP *SYSGARBAGE) that you have no pointer to the window-id, it will
kill the window, so freeing the resources associated with it .

There are similar identifiers for other objects which can be created and
destroyed by the PWM at POPLOG's behest (such as pages, menus and
fonts) and for these too POPLOG will notice if you no longer have any
access to the identifier, and if so instruct the PWM to destroy the
associated object. An item can be recognised as a valid PWM identifier
by the following procedure:

    ispwm_id(<item>) -> <boolean>

which returns true if <item> is a valid PWM identifier, false otherwise.
Likewise,

    pwm_idtype(<item>) -> <word|false>

will return <false> if <item> is not a valid PWM object, or the object's
word ("window", "page", "cursor", "font", "cms" or "menu") if it is.
Lastly,

    islivepwm_id(<item>) -> <boolean>

will returns true if <item> is the identifier for a PWM object which is
currently alive.

Remember that the only way to specify a PWM object, such as a window, to
any of the PWM functions is with this identifier record.  It is a common
mistake to try to use, for example, the window label (that is, the title
it displays on screen).

There are some identifier records already created, for PWM objects
that are always in existence:

    -pwmbasewindow-

The value of this constant is the identifier for the base window (see
HELP *PWMWINDOWS).

    -pwmstdfont-

The value of this constant is the identifier for the font used for
terminal emulation (see HELP *PWMFONTS).

If you are using VED with the PWM, the identifier for the current VED
window is in the variable -vedpwmwindow-.

-- Communicating with the PWM -----------------------------------------

Many of the functions described in this and other related help files
send a message to the PWM and return a reply - for example a function to
make a new window (-pwm_make_txtwin- or -pwm_make_gfxwin-) takes
arguments specifying some details of the required window, and returns a
window identifier by which the new window can be referenced; a function
to find out the position of a window (-pwm_windowlocation-) takes the
window's identifier as argument and returns a vector of two integers
representing the coordinate of a corner of the window.

Sometimes POPLOG and the PWM will have trouble communicating (for
example, this can be caused by user type-ahead interfering with
communications); in this case, the function will return -false- as its
result.  In some of the functions, there may be no communications
problems, but the PWM may be unable to grant the request (for example,
there is a limit to the number of windows that can be made); and in this
case too the function will return -false-.  It has been found that in
most cases it is more convenient to treat these two kinds of failure in
the same way; however, if in some case you do need to distinguish them
(perhaps to try again if it was just a communications problem) the
variable -pwmgotreport- contains the result of the last attempt to
get a report from the PWM: if it is non-false, then communications were
successful.  E.g.

    if (pwm_make_txtwin('output', 80, 10) ->> win) then
        ;;; got a new window
        ....
    else     ;;; something went wrong
        if pwmgotreport then
            ;;; communications ok, must have hit window limit
            mishap(0, 'no more windows')
        else
            ;;; got a garbled message
            mishap(0, 'couldn't make window (type-ahead?)')
        endif
    endif;

-- Selections ---------------------------------------------------------

There is a notion of a "text selection" which is maintained by the PWM.
This is simply a continuous block of text, not tied to any window.
Where appropriate, the implementation is tied in with similar systems on
host workstations - for example the Sun "stuff" mechanism and the GEM
"scrap" mechanism, so allowing small amounts of text to be conveniently
exchanged between other applications and windows.  There are two PWM
functions:

    pwm_get_selection()

instructs the PWM to insert the current text selection, if any, into the
input stream as if the user had just typed it at the keyboard;

    pwm_set_selection(<window-id>, <integer:X1>, <integer:Y1>,
                        <integer:X2>, <integer:Y2>)

instructs the PWM to save a portion of the text displayed on <window-id> from
the point (X1, Y1) to the point (X2, Y2), inclusive.  All units are in
character cells, from  the top-left corner which is (0, 0); either point may
be clipped as necessary if it lies outside the window.  There may be a limit
to the size of a selection, according to the particular PWM (consult the help
file for the PWM); in this case as much as possible of the text from the
beginning of the requested selection will be saved.  Note that this function
always clears any previous selection, even if it is unable to create a new one
(for example because the second point precedes the first).

-- Finding whether POPLOG is connected to a PWM, and what kind --------

The variable -popunderpwm- is false if POPLOG is not connected to a PWM
(or doesn't know that it is connected to a PWM).  If POPLOG has managed
to open communications with the PWM, the value of -popunderpwm- is a
vector giving details about the PWM it is connected to, including the
version number and date (which might be useful if you need to contact
support staff with a query).  The parts of this vector which might be
useful to a program are best accessed through the following functions
(this protects you from any future change in the format of
-popunderpwm-):

    pwm_screenwidth() -> <integer>
    pwm_screenheight() -> <integer>
    pwm_screendepth() -> <integer>

These functions return the width and height, in pixels, of the screen
that the PWM is being used on; and the depth, bits per pixel.  For
example, a standard monochrome Sun is 1152 pixels wide, 900 pixels high,
and one bit deep; a standard colour Sun is the same width and height but
eight bits deep. The depth of a monitor denotes the number of colours
available to the PWM, as a power of two - by example: a pixel on a
monochrome Sun, which has a depth of 1, can show one of 2**1 = 2 colours
at any time (that is, black or white); a pixel on a standard colour Sun,
with a depth of eight, can show one of 2**8 = 256 colours at any time.

    pwm_workstation() -> <word>

This returns the name of the workstation that the PWM is running on:
for example "sun2".

-- Using the PWM with saved images ------------------------------------

You can restore an image saved from a POPLOG running under the PWM to
POPLOG running from a terminal, and vice-versa.  However, it is unwise
to save an image when you have any PWM windows (other than the base
window) open.

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