9/10/90

Notes on selection:
   The following defines a valid selection of a box:
    if the current box is a menu, then the selected box must be
a descendent of that box.
    if the current box is a slider, toggle, or text entry box, then
the selected box must be a descendent or a sibling of the that box.
    a key press will first go to a currently selected text entry box, and
if there is no such then be checked for box selection.

    If an invalid selection is made the following happens:
  if made with a key press, a warning is printed but no action taken.
  if made with a mouse and the current box is a menu, then the display is
reset to initial conditions.  Otherwise a warning is printed and no action 
is taken.
   

The box flags induce_state_change, cleanup, and stop_cleanup:

  A state change is induced when a box with a induce_state_change flag set
is "activated".  By default the boxes and their activations 
are:
   Menu items with no children:  select with mouse or keyboard
   toggles:   select with mouse or kybd
   sliders:   change with mouse.
   text entry:  return key hit.

A cleanup of display is induced whenever a box with cleanup flag set 
is activated.
By default the clean-up inducing boxes and their activations are as
follows:
   Menu items with no children: select with mouse or kybd.

A cleanup can be stopped by a box with a stop_cleanup flag set- when
this is encountered as an ancestor of the clean-up inducing box
the cleanup is stopped and the current box is set to the stopper's
parent.  By default, the stop_cleanup flag is not set for any box.

9/15/90

Public functions:

Routines to get at box selections

     ExtractBoxTopWindow(status)
     VOID *status;
     /* Returns TopWindow cast to an int */

     BoxStateChange(status)
     VOID *status;

     ExtractBoxSelection(status,choice)
     VOID *status;
     int *choice;

     ExtractBoxTextEntryText(status,id,buff)
     VOID *status;
     int id;
     char *buff;

     ExtractBoxSliderValue(status,id,value)
     VOID *status;
     int id;
     double *value;

     ExtractBoxToggleState(status,id,boolean)
     VOID *status;
     int id;
     int *boolean;

     ExtractBoxDimensions(status,id,x,y,width,height)
     VOID *status;
     int id;
     int *x,*y,*width,*height;



Routines to modify essential box variables:

     ChangeBoxSliderValue(status,box_id,value)
     VOID *status; int box_id; double value;

     ChangeBoxTextPrompt(status,box_id,prompt,attr_id)
     VOID *status;
     int box_id,attr_id;
     char *prompt;

     ChangeBoxTextDefault(status,box_id,dflt,attr_id)
     VOID *status;
     int box_id,attr_id;
     char *dflt;

     ChangeBoxToggleState(status,box_id,state)
     VOID *status;
     int box_id,state;
     /* state = 1 for on, otherwise off */


Routines to control box selections and display from the outside

     SelectBoxByID(status,id)
     VOID *status;
     int id;

     BoxPublicKeyPress(status,key)
     VOID *status;
     char key;

     DrawBoxByID(status,id)
     VOID *status;
     int id;


Routines to create boxes, modify flags

     CreateBox(status,type,x,y,width,height)
     VOID *status;
     int type,x,y,width,height;

     AddBoxChild(status,child_id,parent_id)
     VOID *status;
     int child_id,parent_id;

     ToggleBoxAlwaysVisible(status,id,boolean)
     VOID *status; int id,boolean;

     ToggleBoxExclusive(status,id,boolean)
     VOID *status; int id,boolean;

     ToggleBoxStopCleanup(status,id,boolean)
     VOID *status; int id,boolean;

     ToggleBoxCleanup(status,id,boolean)
     VOID *status; int id,boolean;

     ToggleBoxInduceStateChange(status,id,boolean)
     VOID *status; int id,boolean;

     ChangeBoxKey(status,box_id,key)
     VOID *status; int box_id; char key;

     ChangeBoxVisibility(status,id,visible)
     VOID *status;
     int id,visible;

     AddBoxLocalCallback(status,id,callback)
     VOID *status;
     int id;
     int (*callback)();

     AddBoxGlobalCallback(status,id,callback)
     void *status;
     int id;
     int (*callback)();

     AddBoxText(status,box_id,x,y,strng,attr_id)
     VOID *status;
     int box_id,x,y,attr_id;
     char *strng;

Miscellaneous routines:

     BoxPublicPrintMessage(status,mssg)
     VOID *status; char *mssg;

     BoxPublicUrgentWindowDialogue(status,prmpt,rtrn)
     VOID *status; char *prmpt,*rtrn;

