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  deter-
       mines  the appearance associated with the control.  A con-
       trol 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  compo-
              nent interactor.

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

       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 vir-
              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  corre-
              spond  to  the  interactor hierarchy.  These opera-
              tions 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 sub-
              classes 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 targetted 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 after-
              wards.   These  operations  do  nothing by default;

       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 com-
              pose child controls should call this  operation  on
              their children.

SEE ALSO

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