ButtonState,  Button, TextButton, PushButton, RadioButton,
       CheckBox - interactive buttons

SYNOPSIS

       #include <InterViews/button.h>

DESCRIPTION

       Button is a class of interactors that can set the value of
       a  piece of state.  ButtonState is a class of objects that
       contain a value and a list of buttons  that  can  set  its
       value.   A  value  is  either  an  integer or an arbitrary
       pointer.

       TextButton is a subclass of Button that has an  associated
       text  label  to be displayed inside or to the right of the
       button.  PushButton, RadioButton, and  CheckBox  are  sub-
       classes of TextButton that provide particular displays for
       buttons.  Each kind of button will display itself  differ-
       ently  for  each  of the five possible cases: ``enabled'',
       when the button is listening to input, ``disabled'',  when
       the button is not listening, ``chosen'', when the button's
       value is equal to its button state's value, ``hit'',  when
       a  button  that  is not chosen first receives a DownEvent,
       and ``same-hit'', when a button that is chosen receives  a
       DownEvent.

       When  a  button receives a DownEvent, it calls the virtual
       Refresh() to update its  display.   It  then  reads  input
       waiting  for  an  UpEvent.  If the UpEvent coordinates are
       also within the button, then it calls the virtual Press().
       The  default  Press  operation sets the associated state's
       value to the button's value.

       A button can have a list of attached buttons.  When a but-
       ton  is  not chosen its attached buttons are ``disabled'',
       meaning they ignore all input events.

BUTTONSTATE OPERATIONS

       ButtonState()
       ButtonState(int)
       ButtonState(void*)
              Define a button state optionally  with  an  initial
              value.

       void Attach(Button*)
              Add  a  button to the list associated with a button
              state.  The button will be notified when the button
              state's value is modified.

       void Detach(Button*)
              Remove  a  button  from  the list associated with a
              button state.

       void GetValue(void*&)
              Get the value of a button.

       void SetValue(int)
       void SetValue(void*)
              Set the value of a button state and notify all  the
              buttons associated with the state.

       void operator=(ButtonState&)
              Copy the value of one button state to another.  The
              button list associated with the source button state
              is not copied.

BUTTON OPERATIONS

       void PushButton(const char* text, ButtonState* s, int v)
       void PushButton(const char* text, ButtonState* s, void* v)
              Construct a button with text in the  center  and  a
              polygon  on  the  outside.   The  polygon is like a
              rectangle, but with rounded corners.  When  chosen,
              the  entire  button  is  drawn  with foreground and
              background colors reversed.

       void RadioButton(const char* text, ButtonState* s, int v)
       void RadioButton(const char* text, ButtonState* s, void*
              v)
              Construct  a  button  with a circle on the left and
              text on the right.  When hit, a  second  circle  is
              drawn inside the first.  When chosen, a filled cir-
              cle is drawn inside the outer circle.

       void CheckBox(const char* text, ButtonState* s, int on,
              int off)
       void  CheckBox(const  char* text, ButtonState* s, void*
              on, void* off)
              Construct a button with a rectangle on the left and
              text on the right.  When hit, a second rectangle is
              drawn  inside the first.  When chosen, two diagonal
              lines are drawn connecting the opposite corners  of
              the  rectangle.   When  a  checkbox  is pressed the
              first time, it sets s to off if the value is on and
              sets  s  to  on otherwise.  Subsequent presses swap
              the values of the checkbox and s.

       void Attach(Button*)
              Add to this button's list  of  associated  buttons.
              These buttons are enabled when the button is chosen
              and disabled when it is not chosen.

       void Detach(Button*)
              Remove a button from this button's list of  associ-
              ated buttons.

              Stop  listening  to input events.  Disabled buttons
              are typically ``grayed out''  by  drawing  a  half-
              filled rectangle in the background.

       void Enable()
              Start listening to input events.

       void Choose()
              Make  the button as chosen, enabling any associated
              buttons.

       void Handle(Event&)
              If the event type is DownEvent and  the  button  is
              enabled,  call  Refresh  and  read  events until an
              UpEvent occurs.  If the button is the target of the
              UpEvent, then call Press.

       virtual void Press()
              Take  the  appropriate  action for the button being
              pressed.  The default  is  to  set  the  associated
              state to the button's value, which will trigger all
              related buttons to update their display.

       virtual void Refresh()
              Update the button display.

       void SetDimensions(int width, int height)
              Specify  the  natural  size  of  the  button.   The
              default size is a function of the size of the text.
              This routine is obsolete;  use  Interactor::Reshape
              instead.

       void UnChoose()
              Mark  the button as not chosen, disabling any asso-
              ciated buttons.

SEE ALSO

       Event(3I), Interactor(3I)