Interactor(3I)
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)
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
