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

How to use VED with the PWM, and how to customise the VED/PWM interface.

Keywords: VED, PWM, windows, mouse, vedmice

    vedusepwmwindows -> <boolean>
    <boolean> -> vedusepwmwindows;

    vedpwmmousetraps -> <vector>
    <vector> -> vedpwmmousetraps

    <procedure|word:P> -> vedmousetrap(<word:W>)
    vedmousetrap(<word:W>) -> <procedure|word:P>

    wvedalwaysraise -> <boolean>
    <boolean> -> wvedalwaysraise

    wvedbreaktofit -> <boolean>
    <boolean> -> wvedbreaktofit

    wvedwindow -> <window-id|false>


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

 -- Introduction
 -- Telling VED whether to use different windows for each file
 -- Special VED commands for use with the PWM
 -- Variables which affect the behaviour of VED under the PWM
 -- Things to note when using VED with the PWM
 -- Customising the VED/PWM interface
 -- NOTE for more advanced customisation
 -- Programming the VED/PWM interface


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

This file makes two assumptions: firstly, that the reader is familiar
with the rationale behind both the PWM (that is, HELP * PWM has been
read) and VED; and secondly, that VED has been correctly set up for the
PWM (i.e. *VEDINITTERM has loaded LIB * VEDPWMSUN).


-- Telling VED whether to use different windows for each file ----------

The PWM starts off by creating a separate window for each new VED file
brought to the screen, thus allowing you to have several VED files being
in various stages of preparation at (or near) the front of the screen at
any one time. However, you may want to use the PWM to talk to POPLOG,
but not want VED to use different windows for each file - for example
because because you want to edit more files at once than there are
windows available or because the program you are working on will need to
create many windows of its own.  The active variable

    -vedusepwmwindows-

controls this aspect: if it is false, VED will use the base window as
an ordinary terminal and display all files in that window; otherwise
VED will use different windows for each file.

Note that the value of this variable can only be changed when you are
not editing any files.

-- Special VED commands for use with the PWM --------------------------

There are two built-in VED commands for use with the PWM

         <ENTER>  windows  <RETURN>

lists all the currently active PWM windows, with details of whether they
are open or iconic and their size.  Those windows owned by VED will have
the filename printed alongside: other windows will have a word
specifying their type (base, graphics, or (user) text window). Graphics
windows will have their size stated in terms of pixels, whereas the size
of all other types of window will be in terms of characters.

         <ENTER> closeall <RETURN>

closes all the windows being managed by the current PWM.  If given any
argument, e.g.

        <ENTER> closeall but <RETURN>

it will close all the windows except the one you give the command in.
This can be useful to reduce confusion when you have acquired a
screenfull of assorted windows.

-- Variables which affect the behaviour of VED under the PWM ----------

    -wvedalwaysraise-

If true, VED will try and ensure the window you are editing in is always
fully visible (default false).

    -wvedbreaktofit-

If true, VED will adjust the point at which lines are broken to be close
to the right edge of the window you are editing in, whenever the window
is resized (default false).

Before a new file is read in to VED, the procedure -vedveddefaults- is
called (see HELP *VEDVEDDEFAULTS).  If you are using VED in the PWM,
the variables -vedscreenwidth- and -vedscreenlength- are set to the
proposed size for a window to contain the file.  After -vedveddefaults-
has been called, the window will be made with -vedscreenwidth- columns
and -vedscreenlength- rows.  If you redefine -vedveddefaults- to change
the value of -vedscreenwidth- and/or -vedscreenlength-, you can
change the initial size of the window.

If VED is taking over a window that has already been created, for
example when the command

        <ENTER> qved <filename>

is used, -vedscreenwidth- and -vedscreenlength- will be set to the
current size of the window.  Thus if you don't change them in your
-vedveddefaults- procedure, the window size will remain unchanged.

If VED is going to make a new window to edit the file in, however, the
variables -vedscreenwidth- and -vedscreenlength- will be initialised
from the variables -vedpwmdefaultwidth- and -vedpwmdefaultheight-
before -vedveddefaults- is called.  These are initially set to 80 and
24 respectively, but you can change them - for example in your
"vedinitpwm.p" file (see below).  As a (slightly contrived) example, you
could set -vedpwmdefaultheight- to 34, and define vedveddefaults to
include the fragment:

    if isendstring('.dat', vedcurrent) then
        100 -> vedscreenwidth;
        12 -> vedscreenlength;
    elseif vedbufferlist.length > 5 then
        if vedscreenwidth = vedpwmdefaultwidth
        and vedscreenlength = vedpwmdefaultheight then
            24 -> vedscreenlength
        endif;
    endif;

Then whenever you edited a file whose name ended in ".dat", the window
would be 100 columns and 12 rows; any other file, if it was replacing a
file in an existing window, would inherit the size of the window
unchanged; and any other file starting in a new window would get a
window 80 columns by 34 rows, unless there were already at least five
files being edited, in which case the new window would be 80 columns and
24 rows.

-- Things to note when using VED with the PWM -------------------------

In general, VED works just as normal with the PWM, but a few useful
notes and extra VED commands are given below:

1.  The PWM response to a bell character is to flash the top line of the
    window.

2.  If you wish to quit one file and edit another it may be useful to
    use the command:

         <ENTER>  qved  <filename>  <RETURN>

    This allows VED to take over the existing window for the new file,
    which is quicker than killing one window and creating another.
    Similarly, commands such as "qteach", "qhelp", "qshowlib" may be
    used.

3.  It is easy to be confused by the fact that in general when using
    windows on the a multi-tasking workstation, such as a SUN or
    "Bobcat", 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.

4.  There is a limit to the number of windows that the PWM can maintain
    at one time.  At present, VED requires a window for every file that
    is being edited: therefore if you are using VED with PWM windows,
    you may be restricted in the number of files that you can edit at
    once.  If you need to edit a lot of files, but still want to use
    the PWM facilities in your program, you should assign false to
    -vedusepwmwindows- as described above.  For details of the limits on
    the number of windows that apply to you, see the section entitled
    "Limits on windows" in the help file for the workstation you are
    using: one of HELP * SUNPWM

5.  On most WIMP'ish workstations, the user has explicit control over
    which window input will be directed to, either just by moving the
    mouse into it or by somehow selecting the window with the mouse.

    To avoid confusing the user model of interaction with the
    workstation, the PWM conforms to this: therefore the user should
    remember that invoking VED on a file, or moving to it, for example
    with <ESC> e, will not necessarily cause subsequent keyboard input
    to go that file. The user can control this by means of the
    (active) variable vedusepwmwindows, which can have the value FALSE
    meaning don't use multiple windows for VED, TRUE, corresponding to
    the use before Poplog Version 13.82, or a list indicating contexts
    in which input focus should be automatically altered. For full details
    see REF * VEDUSEPWMWINDOWS.

    Prior to V13.82, the input focus was changed only in the context of
    -vedswapfiles- (<ESC> x, ved_mi, ved_rb, etc) which does explicitly
    select the window (on some machines, this involves moving the mouse
    cursor into the window).

6.  If you are using the PWM with a remote login to a Unix computer, and
    hence have a shell 'under' the POPLOG process, you can suspend the
    POPLOG process to temporarily return to the shell using
        <ENTER> stop <RETURN>
    (if you are in VED) or a macro "stop" if you are in pop11.  Using
    one of these commands instead of a control character allows POPLOG
    to clean things up before and after it is suspended so that things
    will work properly.

-- Customising the VED/PWM interface ----------------------------------

When VED starts up using the PWM, it loks for a file in your "$poplib"
directory (generally your top level directory) called "vedinitpwm.p", and
if finds one attempts to compile it (see HELP *INITIAL for further
details).  You can use this to set up flags controlling the behaviour of
VED under the PWM as mentioned above; or for example to load a file
attaching actions to mouse events (such as LIB VEDMICE or some file of
your own devising, see below); or to set up special commands or
key-assignments for use with the PWM.

For example, I find it useful to be able to close or hide the current
window without having to take my hands from the keyboard, so I have the
following lines in my "vedinitpwm.p" file:

    vedsetkey('\^[i', procedure;        ;;; esc-i   go iconic
                        pwm_close_window(pwmtextwindow);
                      endprocedure);
    vedsetkey('\^[d', procedure;        ;;; esc-d   window down in stack
                        pwm_hide_window(pwmtextwindow);
                      endprocedure);

See HELP *VEDSETKEY, HELP *PWMWINDOWS, and HELP *PWMGENERAL for more
details.


-- NOTE for more advanced customisation -------------------------------

VED must be configured for the PWM, just as it must for use with any
other terminal, as described in REF * VEDTERMINALS and HELP * TERMINAL.

By default, this is done for the PWM by loading the library file LIB
*VEDPWMSUN. If you wish to set up VED differently for the PWM, you can
arrange this in your "vedinitpwm.p" file. In this case, to prevent LIB
*VEDPWMSUN being loaded over your own configuration, you must declare
and initialise the variable VEDPWMSUN. There is another library, LIB
*VEDSUN, which must not be confused with VEDPWMSUN as it sets up VED to
work in normal 'terminal mode' in a Sunview Shelltool window (see HELP
*VEDSUN).


-- Programming the VED/PWM interface ----------------------------------

You can customise the actions taken by VED in response to mouse input
quite easily.  As a demonstration, the library LIB *VEDMICE will set VED
to allow you do things like change files, move the cursor, and mark,
delete, move and copy a range of text, using the mouse.  While this has
been found to be quite useful, and for the moment you might wish to use
it, it is not intended to be a definitive interface, but rather an
extended example to demonstrate how an interface to suit your own
requirements can be built.

Before you try writing your own interface, you should have read the
files HELP *PWMGENERAL and HELP *PWMWINDOWS.  You might also find it
useful to look at the files HELP *PWMMENUS, HELP *PWMINPUT and HELP
*PWM_TRACK_MOUSE.  When you have read those and the following details,
you should probably have a look at LIB *VEDMICE to make sure you
understand how it works.  You may wish to note that the variable
-wvedwindow- points to the identifier record for the window for the
current file.

There are four mouse events that can occur in a VED window: a mouse
button being pressed, a mouse button being released, a mouse being moved
with a button held down, and a mouse going out of the window while a
button is being held down.  You can assign a procedure to catch each
of these events, and VED will then call the appropriate procedure when
the event occurs.  There are two ways to assign a procedure to
catch mouse events: you can "set a trap" for a particular event in the
current file, or you can set the procedure that will be used in all
files unless a trap is set in a particular file.

The procedure called for a "press", "release", or "move" event will be
called with three arguments: the number of the button (button #1 is the
left button) and the coordinates of the event, in character units from
(0, 0) at the top-left character.  The procedure called for an "exit"
event is given no arguments.

The variable -vedpwmmousetraps- points to a four-element vector which
contains the "global" traps: each element is either -false-, indicating
no trap is set for this event;  a procedure, the function that will be
called for an appropriate event; or a word which is the name of such a
procedure. The order of the procedures is: press, release, move,
mouseexit; i.e. the second procedure in the vector is the one that will
be called for a mouse-button-released event.

When a new file is edited, it will inherit the set of traps from
-vedpwmmousetraps-.  If an element of this vector is changed, all the
files which have inherited the global set of traps will get the new
trap.  However, if you want to set a trap for a mouse event in a
particular file, you can use the procedure -vedmousetrap-.  This takes a
word, the name of an event, as argument and returns the procedure (or
word) which is currently the handler for such an event in the current
file; or it's updater can be used to set the trap for an event in the
current file.  The names of the events are "press", "release", "move"
and "mousexit".  For example, this procedure would be called if a
mouse button was pressed, and would just print out a message giving the
details:

    define catchpress(b, x, y);
        lvars b x y;
        vedputmessage('button ' >< b >< ' pressed at ' >< x >< ',' >< y);
    enddefine;

    catchpress -> vedmousetrap("press");


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