Provided by: ivtools-dev_1.2.11a1-11_amd64 bug

NAME

       Interactor - base class for interactive objects

SYNOPSIS

       #include <InterViews/interactor.h>

DESCRIPTION

       In  2.6,  Interactor  was  the  base  class  for all interactive objects.  It is currently
       provided for backward compatibility.

       Every interactor has a shape member variable that defines the desired  characteristics  of
       screen  space  in  terms  of size, shrinkability, and stretchability.  This information is
       used to allocate display space for the  interactor  and  the  interactor's  canvas  member
       variable  is  set  to  the  actual space obtained.  The lower left corner of the canvas is
       addressed by (0, 0); the upper right by the member variables (xmax, ymax).

       The input member variable is the normal sensor for  reading  events.   The  output  member
       variable  is  the  standard  painter  for  performing  graphics  operations.   Interactors
       generally should not set output; it  will  either  be  inherited  (and  shared)  from  the
       interactor's parent or set by user customization attributes.

       An  interactor  may  optionally  define  the  perspective member variable to represent the
       portion of total area that the interactor is displaying.  Perspectives  allow  interactors
       to  coordinate with other interactors, such as scrollers, that want to control the display
       area.

       An interactor also may specify certain characteristics of the interactor's canvas, such as
       whether  it  is  read-only  or  read/write,  whether its contents should be saved when not
       visible.  Interactors also may specify the visual format and interpretation of  the  input
       pointing device (e.g., mouse cursor) when it is inside the interactor's canvas.

       To  be mapped to some portion of the display, an interactor must have been inserted into a
       scene, called its parent.  The interactor will be mapped when its parent is  mapped.   The
       root scene for the display can be accessed through a World(3I) object.

CONSTRUCTORS

       Interactor()
              Construct  an  interactor.  The input sensor and output painters are initialized to
              nil.

       Interactor(const char* name)
              Construct an interactor associated with the string name.  The  string  is  used  to
              customize  the  behavior of the interactor according to user preferences.  Behavior
              can also be customized on a per-class basis using the subclass name.  Although  not
              explicitly  documented, an instance of any object inheriting from interactor may be
              constructed with an additional argument (appearing  first)  containing  the  string
              name.   For  example,  both  ``HGlue(natural,  stretch)''  and  ``HGlue("somename",
              natural, stretch)'' are valid.

       ~Interactor()
              The base destructor automatically deletes the base fields, including shape, canvas,
              input, and output.

CONFIGURATION

       void Align(Alignment, int w, int h, Coord& l, Coord& b)
              Return the coordinates at which an object with the given width and height will have
              the given alignment within the interactor's canvas.

       void SetClassName(const char*)
       const char* GetClassName()
       void SetInstance(const char*)
       const char* GetInstance()
              Set/get the class or instance name for  an  interactor.   The  names  are  used  to
              determine  user  style  preferences.   SetClassName  and  SetInstance  can  only be
              performed by subclasses.

       void Config(Scene* s)
              Configure this interactor and its descendants according to user  preferences.   The
              scene  s  is assumed to be the interactor's parent and is used to inherit attribute
              values.  This operation need not be called explicitly; it is  called  automatically
              when  the  ancestors of an interactor become known (e.g., when the interactor or an
              ancestor is inserted into a world).

       Configuration involves a traversal of the interactor hierarchy.  For  each  interactor  in
       the  hierarchy,  the output painter is either inherited from its parent or copied from its
       parent if there are user preferences specific to the  interactor  for  painter  attributes
       such   as  colors,  font,  and  brush.   For  example,  suppose  the  user  preference  is
       ``A*B*font:9x15'' and the interactor hierarchy is ``A.B.C.D'' (each ``.''  representing  a
       nesting  level in the hierarchy).  Interactors A and B will share the same output painter,
       C will copy B's output and change the font to ``9x15'', and D will share C's output.

       After assigning the output painter, configuration is performed recursively on any children
       interactors.  The final step at each node in the traversal is to call the virtual Reconfig
       operation.

       virtual void Reconfig()
              Perform any configuration specific to  a  particular  interactor.   This  operation
              should  minimally compute the interactor's shape based on the shape of its children
              and/or the characteristics of  its  output  painter  (e.g.,  font).   It  can  also
              retrieve  user  preferences  specific  to  this interactor's class or instance name
              using GetAttribute.

       const char* GetAttribute(const char*)
              Retrieve the value of a user preference with the given name.  GetAttribute searches
              for the most specific match to the current context.

       virtual void Reshape(Shape&)
       Shape* GetShape()
              Set/get the shape of an interactor.  Reshape is a a suggestion that an interactor's
              shape should change to the given one.  The default operation sets the  interactor's
              shape  to  the  new  shape  and  calls  Scene::Change  on  the interactor's parent.
              Suggested shape information may be lost when an interactor is configured; thus,  it
              is  best  to  avoid  use  of  Reshape.   The same affect can usually be achieved by
              putting the interactor in a box along with a particular shape of glue.

       void SetCursor(Cursor*)
       Cursor* GetCursor()
              Set/get the cursor that will be displayed when the pointing device  is  inside  the
              interactor's canvas.  If the interactor does not explicitly set its cursor, it will
              use its parent's cursor.  GetCursor returns nil in this case.

INTERACTOR HIERARCHY

       Scene* Parent()
              Return the interactor's parent or nil if the interactor has not been inserted  into
              a scene.

       World* GetWorld()
              Return  a  pointer to the world the interactor has been inserted into or nil if the
              interactor's root ancestor is not mapped.

       void GetRelative(Coord& x, Coord& y, Interactor* = nil)
              Map coordinates that are relative to this interactor's canvas  to  be  relative  to
              another  interactor's canvas.  If the other interactor is nil, then the coordinates
              are made relative to the world.

       virtual void GetComponents(Interactor**, int, Interactor**&, int&)
              Construct an array of pointers to the interactors contained within this interactor.
              The  first  and  second  parameters specify an array of interactors that is already
              allocated.  This array is used if it is large enough,  otherwise  a  new  array  is
              allocated  from free store.  The third and fourth parameters return the which array
              was used and the actual number of components.  This operation is  only  defined  by
              scenes; the default operation sets the number of elements to zero.

OUTPUT

       Canvas* GetCanvas() const
              Return the interactor's canvas, which may be nil if the interactor is not mapped to
              a display.

       ManagedWindow* GetTopLevelWindow() const
              Return the top-level window associated with the interactor, if  it  is  mapped  and
              top-level.

       virtual void Draw()
              Draw  is  used  to display the contents of an interactor, including the contents of
              any    interior    interactors.     The    default     Draw     operation     calls
              Redraw(0, 0, xmax, ymax).   Interactors  usually don't need to redefine Draw unless
              they contain interior interactors (i.e., scene subclasses); most simple interactors
              redefine only Redraw.

       virtual void Highlight(boolean)
              Turn  highlighting  on or off, depending on whether the parameter is true or false.
              The default operation is a nop.

       void SetCanvasType(CanvasType)
       CanvasType GetCanvasType()
              Set/get the type of canvas desired for  an  interactor.   This  operation  must  be
              performed   before  an  interactor  is  mapped.   The  possible  canvas  types  are
              CanvasShapeOnly, meaning the interactor performs no input or output  (e.g.,  glue),
              CanvasInputOnly,  meaning  the  interactor  performs  no output, CanvasInputOutput,
              which is the default, CanvasSaveUnder, which suggests that the interactor  will  be
              mapped  for  a  short  time (e.g., a popup menu) and that the information under the
              canvas should be saved, CanvasSaveContents, which suggests that  Redraw  calls  are
              expensive  and  should be avoided by caching the display, and CanvasSaveBoth, which
              requests both CanvasSaveUnder and CanvasSaveContents.

       void Sync()
       void Flush()
              Sync waits until any pending operations have completed.  Flush makes sure the local
              buffer  of  pending operations (if any) is sent to the display.  An input operation
              will do a Sync automatically if it would block; thus, applications  generally  need
              not call Sync or Flush explicitly.

INPUT

       void Listen(Sensor*)
              When  an  interactor  is mapped onto a display, its input interest is determined by
              its input sensor.  A different sensor can be specified with the  Listen  operation.
              To switch back to input, call Listen(input).

       void Read(Event&)
       boolean Read(long sec, long usec, Event&)
              Each  application  has a single input queue of events.  Any interactor can use Read
              to take the next event from the queue.  Redraw and Resize operations may be  called
              as a side effect of a Read (or any input operation).  The target field of the event
              specifies the interactor for which the event is intended, which is not  necessarily
              the  same  as  the  interactor that performed the Read.  The target is normally the
              interactor whose canvas is under the pointing device.   The  second  form  of  Read
              behaves  differently  if there are no events to read in that it times out after the
              given number of seconds and microseconds have elapsed  and  returns  false  to  the
              calling program.

       void UnRead(Event&)
              UnRead puts an event back on the input queue as if it had never been read.

       virtual void Handle(Event&)
              When  an  interactor  wishes  to  pass an event to another interactor, it calls the
              other interactor's Handle operation.   Thus,  input  flow  control  can  be  either
              procedural with Read or event-driven with Handle.

       void Run()
              Run  implements  a  simple  event  dispatching loop.  It calls Read to get the next
              event and passes  the  event  to  the  target  interactor  via  Handle.   The  loop
              terminates if the Handle operation sets the event's target to nil.

       void QuitRunning(Event&)
              QuitRunning sets the event's target to nil.  A Handle operation can call it to make
              Run exit its event dispatching loop.

       boolean Check()
              Check determines whether an event of interest has occurred.

       void Poll(Event&)
              Poll sets an event to reflect the  current  input  state.   Input  polling  can  be
              wasteful of cycles and should be avoided if possible.

       int CheckQueue()
              CheckQueue  returns  the  number  of input packets that have been queued within the
              application.  The event queue manager always reads as much information as  possible
              from  input;  thus,  a  single  Read  might  store  many  events in a local buffer.
              Subsequent reads can simply access the buffer.  This buffer can include out-of-band
              packets,  such as those requiring a Redraw.  The number returned by CheckQueue does
              not correspond, therefore, to the actual number of input events.

VIEWS

       virtual void Adjust(Perspective&)
              Adjust suggests to an interactor that its perspective should change  to  the  given
              perspective;  the  interactor  may choose to accept any part of the new perspective
              and must ensure that the parameter matches its (new) perspective before  returning.
              Adjust can be used by another interactor to scroll, pan, or zoom an interactor.

       Perspective* GetPerspective()
              GetPerspective  returns the perspective associated with an interactor or nil if the
              interactor has not assigned one.

       virtual void Update()
              Change the display to reflect some change in state that the interactor depends  on.
              This  operation  is  used  in  a  number  of  contexts.  One example is in managing
              perspectives.  If an interactor changes its perspective (e.g., the total of size of
              what it is displaying changes), it must notify its perspective, which in turn calls
              Update on the interactors that access the perspective (such as a scroller).

PROTECTED OPERATIONS

       virtual void Redraw(Coord l, Coord b, Coord r, Coord t)
              The Redraw operation is called when some portion of  the  Interactor  needs  to  be
              redrawn,  presumably  because  it  was  previously  obscured.  The Redraw operation
              should NOT  redraw  interior  interactors;  the  Interviews  library  or  the  Draw
              operation  will  call  their  Redraw  operations automatically.  The default Redraw
              operation does nothing.

       virtual void RedrawList(int n, Coord l[], Coord b[], Coord r[], Coord t[])
              RedrawList notifies an interactor that several areas  of  its  canvas  need  to  be
              redrawn,  presumably  because  it  was  raised  to  the top of other canvases.  The
              default RedrawList operation redraws each area separately with Redraw.

       virtual void Resize()
              Resize notifies an interactor that its canvas has been created or  modified.   Only
              scenes  are  typically  concerned  with  Resize, as they must place their component
              interactors within the new or resized canvas.  The default  Resize  operation  does
              nothing.

SEE ALSO

       InterViews Reference Manual, Perspective(3I), Scene(3I), Sensor(3I), Shape(3I), World(3I)