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.
- 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)