ACTIVEREGIONS     D. Barstow     2.Sept.1982


ACTIVEREGIONS is a lispusers package for specifying that certain regions
of a window be sensitive to button activity of the mouse.  Whenever the
left mouse button is held down and the mouse is within one of the active
regions associated with a window, that region will be highlighted.  A
region is "picked" by releasing the left button when the region is
highlighted.  When a region is picked, the associated function is invoked.
The picked region is only lowlighted by calls to SETPICKREGION.
SETPICKREGION is called automatically whenever the mouse is used to pick a
new region; otherwise it is the user's responsibility to call it when
appropriate.  The most recently picked region is saved and can be accessed
by a call to GETPICKREGION.  It is probably best not to try to mix this
package with other menus or button activity in a window, since
BUTTONEVENTFN may get screwed up.


SETACTIVEREGIONS(WINDOW REGIONLIST HIGHLIGHTFN LOWLIGHTFN)

     REGIONLIST is a list of elements of instances of ACTIVEREGION, a
     record with seven fields:
          REGION is relative to WINDOW
          HELPSTRING is a string which will be put in the prompt window
               when the mouse button is held down for ?? seconds
          DOWNFN is a function with three arguments: WINDOW REGION DATA
               it is called when either:
                     1. the left goes down in a region
                     2. a region is entered with the left button down
                        after the left button went down in the window
          UPFN is a function with three arguments: WINDOW REGION DATA
               it is called when the left goes up in a region
          HIGHLIGHTFN, if given, overrides the highlightfn used in
               the call to SETACTIVEREGIONS
          LOWLIGHTFN, if given, overrides the lowlightfn used in
               the call to SETACTIVEREGIONS
          DATA is arbitrary information you may associate with the region
     If REGIONLIST is NIL, the active region stuff for the window will be
     disabled.

     HIGHLIGHTFN and LOWLIGHTFN are functions of two arguments:
     WINDOW ACTIVEREGION.  LOWLIGHTFN defaults to HIGHLIGHTFN,
     which in turn defaults to inverting the indicated region.

FINDACTIVEREGION(WINDOW POSITION REGIONLIST/OPTIONAL)

     Returns the ACTIVEREGION which contains POSITION.  If there are
     several, returns the first in the activeregion list.

ADDACTIVEREGION(WINDOW ACTIVEREGION)

     Adds ACTIVEREGION at the front of the activeregion list for WINDOW.

DELETEACTIVEREGION(WINDOW ACTIVEREGION)

     Deletes ACTIVEREGION from the activeregion list for WINDOW.

SETPICKREGION(WINDOW ACTIVEREGION OLDREGION/OPTIONAL)

     Lowlights the most recent picked region of a window and sets
     ACTIVEREGION to be the new active region.

GETPICKREGION(WINDOW)

     Returns the pick region of a window (as an ACTIVEREGION).


Examples:

If you want each active region to act like a menu item, simply put the
appropriate actions as the PICKFNs of the regions in REGIONLIST.  Each
PICKFN should call (SETPICKREGION WINDOW NIL) unless it redisplays the
entire window, in which case it should call SETACTIVEREGIONS again.

If you want to pick a region and later use it (e.g., as an argument to
an item on some fixed menu), give each ACTIVEREGION a PICKFN of NIL and
use (GETPICKREGION WINDOW) to determine the most recently picked region.
This action would presumably want to call (SETPICKREGION WINDOW NIL) or
something similar.