NAME

       Control, ControlState - select and execute an action

SYNOPSIS

       #include <InterViews/control.h>

DESCRIPTION

       A  control  is a monoscene that allows an action to be selected and executed.  The component of a control
       determines the appearance associated with the control.  A control state is a subject that  coordinates  a
       group  of  related  controls.  The control state contains a pointer to the currently selected control (if
       any).

       Controls are useful for grabbing input  and  moving  over  potentially  selectable  items.   Examples  of
       controls  include  popup  menus,  pull-down menus, and menu items.  It is generally not necessary to call
       functions directly on a control.

PUBLIC OPERATIONS

       Control(Interactor*)
              Construct a new control with the given interactor as the component.

       ~Control
              Destruct a control.  Because a control is a monoscene, deleting it implies deleting its  component
              interactor.

       ControlState* State()
       void SetState(ControlState*)
              Get or set the control state associated with a control.

       virtual void Handle(Event&)
              Controls  are  initially  inactive.   A DownEvent causes a control to become active.  If an active
              control receives an EnterEvent, it will set the current selection to itself.  If an active control
              receives a LeaveEvent, it will set the current selection to nil.

       virtual void Enable(boolean)
       boolean Enabled()
              Depending on the argument, Enable  enables  (true)  or  disables  (false)  the  control.   Control
              subclasses  can  check  whether  the  control  is enabled with the Enabled operation and then take
              whatever action is appropriate.

       virtual void Select()
              Highlight the control and call the protected virtual functions Open and Grab (see below).

       virtual void Unselect()
              Call the protected virtual function Close and then unhighlight the control.

       virtual void Do()
              Implement a selected action.  When a  control  sees  an  UpEvent,  it  calls  Do  on  the  current
              selection.

       Control* ParentControl()
       Control* RootControl()
              The  control  hierarchy  does  not  necessarily  correspond  to  the  interactor hierarchy.  These
              operations return the control's parent control or the root of the control hierarchy,  if  any,  as
              defined by control subclasses.

PROTECTED OPERATIONS

       virtual void Down()
       virtual void Up()
              Down  and  Up  are  called when the control receives a DownEvent and an UpEvent, respectively.  By
              default, Down activates the control if it is enabled, and Up deactivates the control and calls  Do
              on the current selection.

       virtual void Enter()
       virtual void Leave()
              Enter  makes  the control the current selection if it is enabled and active, while Leave nullifies
              the current selection if the control is enabled and active.

       virtual void Open()
       virtual void Close()
              The base class Open and Close do nothing, but subclasses may insert and remove an interactor, such
              as a pull-down menu.

       virtual void Grab()
              Grab reads input and only passes through an event if its target is an active control.

       virtual void Skip()
              Skip reads and discards input events until it reads an  event  targeted  for  a  control  that  is
              currently grabbing input, as indicated by IsGrabbing (see below).

       virtual void Busy()
       virtual void Done()
              The  Up  operation calls Busy just before it calls Do on the target, and it calls Done immediately
              afterwards.  These operations do nothing by default; subclasses may reimplement them to start  and
              stop some indication that the control is doing its job.

       virtual boolean IsGrabbing(Interactor*)
              IsGrabbing returns true if the given interactor is grabbing control.

       void Reparent(Control* target, Control* parent)
              Set target's parent to parent.  Controls that compose child controls should call this operation on
              their children.

SEE ALSO

       Event(3I), Interactor(3I), Menu(3I), Scene(3I)

InterViews                                      15 September 1989                                    Control(3I)