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 compati-
bility.
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 can-
vas 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 inher-
ited (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 for-
mat 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 out-
put painters are initialized to nil.
Interactor(const char* name)
Construct an interactor associated with the string
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(natu-
ral, 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 align-
ment 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 interac-
tor. 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 automati-
cally 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 hier-
archy. 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 per-
formed recursively on any children interactors. The final
virtual void Reconfig()
Perform any configuration specific to a particular
interactor. This operation should minimally com-
pute the interactor's shape based on the shape of
its children and/or the characteristics of its out-
put 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. Sug-
gested shape information may be lost when an inter-
actor 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 cur-
sor, 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 inter-
actor 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 interac-
tor'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.
actor**&, 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 allo-
cated from free store. The third and fourth param-
eters 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 interac-
tor, including the contents of any interior inter-
actors. 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 opera-
tion is a nop.
void SetCanvasType(CanvasType)
CanvasType GetCanvasType()
Set/get the type of canvas desired for an interac-
tor. This operation must be performed before an
interactor is mapped. The possible canvas types
are CanvasShapeOnly, meaning the interactor per-
forms no input or output (e.g., glue), CanvasInpu-
tOnly, meaning the interactor performs no output,
CanvasInputOutput, which is the default, Canvas-
SaveUnder, 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 CanvasSaveCon-
tents.
void Flush()
Sync waits until any pending operations have com-
pleted. Flush makes sure the local buffer of pend-
ing 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 Lis-
ten(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 oper-
ations 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 sec-
onds 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&)
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 Check-
Queue does not correspond, therefore, to the actual
number of input events.
VIEWS
virtual void Adjust(Perspective&)
Adjust suggests to an interactor that its perspec-
tive 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 perspec-
tive, 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
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 typi-
cally 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)
Man(1) output converted with
man2html