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)