Interactor(3X) manual page
Table of Contents
Interactor - base class for interactive objects
#include
<ivplus/interactor.h>
Interactor is the base class for all interactive
objects. 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. 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 points to the default Sensor for reading events, if any. The
output member variable points to 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 scrollbars, that want to control the display area by scrolling
or possibly zooming.
An interactor also may specify certain characteristics
of the interactor’s canvas, such as whether it is read-only or read/write,
or whether its contents should be saved when not visible.
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. An interactor that has been inserted directly into the world
is called a top-level interactor.
The interactor can specify whether or not
it is traversable using the Motif keyboard traversal model.
The interactor
has an event translation table which contains a set of event-action pairs.
If an incoming event is matched to an entry in the translation table, the
corresponding action(s) are sent to Interpret(). See Translations(3X)
for
a full description of the event translator syntax.
Interactor is an abstract
base class.
Interactor->Glyph->Resource
Interactor is derived
from Glyph which in turn is derived from Resource (since Glyphs are shared
objects). InterViews Plus is based on the Interactor hierarchy, so for
the purposes of this Reference Manual, Interactor is considered the root
class of the hierarchy.
Create
an interactor. The interactor can not perform input or output until it has
been configured, that is, it or one of its ancestors, has been inserted
into the world.
The optional instanceName creates an interactor associated
with the string instanceName. The string is used to customize the behavior
of the interactor according to user preferences.
Since Interactor is an
abstract base class, these constructors are protected.
This is used by the keyboard traversal
mechanism to construct tab groups.
This is used by the event translation mechanism to determine how
to combine translation strings.
See
SetCanvasType().
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.
Returns the coordinates which an object with the given width and height
will have using the given alignment within the interactor’s canvas. See
Alignment(3X)
for valid values.
Returns
true if On, on, True, or true for the given attribute has been set by
the user. Otherwise, it returns false.
A return of true
ensures that a subsequent call to Read() will not block. In other words,
there is an event of interest to this interactor on the event queue.
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.
Configures this interactor
and its descendants according to user preferences. The scene 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 or copied from its parent. If there are user
preferences specific to the interactor for painter attributes such as colors,
font, and brush, the painter will be copied. For example, suppose the user
preference is A*B*font:9x15 and the interactor hierarchy is A.B.C.D (each
represents 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.
Performs the same actions as void Config(Scene*)
except that attributes are inherited from World rather than a parent scene.
Builds the tab group structure for the traversable
child interactors of the calling interactor. The tab groups created are
added to the list of tab groups maintained by the TabGroupLeader object
associated with the top level interactor.
This operation
is only called by a top level interactor from one of the World::Insert*
operations. The first time it is called, it creates a TabGroupLeader object
to manage the keyboard traversal for the interactors within this window.
It then calls CreateTabGroup() on the top level interactor to actually
create the tab group structure.
Changes
the keyboard focus to the given interactor.
Returns
a pointer to the interactor that currently has the keyboard traversal focus.
Returns nil if no interactor has the focus or if keyboardFocusPolicy
is pointer.
Makes the interactor disabled. If it is
currently accepting input, it may not now.
Displays
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
(e.g. Scene). Most simple interactors only redefine Redraw().
Makes the interactor enabled. If it had previously not been accepting
input, accept it now.
Returns whether or not this
interactor is enabled. Disabled interactors ignore input events and may
have a different visual appearance.
Makes sure the local buffer
of pending operations (if any) is sent to the interactor’s display.
Focused(true) tells the interactor that it has the
current keyboard focus. The interactor will typically set some internal
state, and draw a highlight border called the location cursor, using the
static painter highlightPainter. Focused() is called during keyboard traversal.
Returns true if the X resource keyboardFocusPolicy
is set to explicit for this application. In general, an explicit focus
means that the user must click in an interactor to give it the keyboard
focus. TabGroups and keyboard traversal are available in explicit mode.
If keyboardFocusPolicy is set to pointer or any other value, this routine
will return false.
Retrieves
the value of a user preference with the given name. GetAttribute() searches
for the most specific match to the current context. Returns nil if no match
is made. This may be called anytime during or after the Config() traversal
which takes place after a composition is inserted into the World.
Returns the interactor’s canvas. If the interactor has not
been mapped to a display, GetCanvas() will return nil.
Returns the CanvasType used for the interactor. See SetCanvasType()
for more information.
Gets the class name
associated with an interactor.
Constructs 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 actual array that was used and
the actual number of components. This operation is defined only by Scene.
The default operation sets the number of elements to zero.
Returns a pointer to 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, returns nil.
Returns the
instance name associated with an interactor. Returns nil if no instance
name was specified for the interactor.
Returns
the perspective associated with an interactor or nil if the interactor
has not assigned one.
Returns the world coordinates of the lower-left corner of the interactor.
Maps
local coordinates into another interactor’s coordinate system.
If the other
interactor is nil, then the coordinates are made relative to the world.
This is often used to find the coordinates of an interactor relative to
its parent.
Maps
coordinates that are relative to this interactor’s canvas to be relative
to the interactor’s world.
Returns a pointer to the
Shape object of the interactor.
Returns the tab
group pointer associated with the interactor. The TabGroup class is used
internally by the library during keyboard traversal.
Called by a top level interactor (one which has been inserted directly
into the world), returns the associated ManagedWindow. An interactor that
is not top level or is not mapped will return nil.
Returns
a pointer to the world the interactor has been inserted into or nil if
the interactor’s root ancestor is not mapped. Use World::current() to retrieve
a world pointer in situations where GetWorld() fails.
Blocks input events for all other windows on the display except for
the calling interactor’s top level window. An optional cursor can be passed
which will change the cursor used for the pointing device during the grab.
Processes the given event. This is usually done
by checking one or more attributes of the event, such as the event type,
and then performing some action. The mouse-based behavior of the interactor
is largely determined by the actions defined in this function.
Handle()
is typically called by the current event loop after having failed to find
an event translation.
Turns highlight on
or off. The default operation does nothing. Derived classes can define an
appearance and behavior when highlighted.
Takes
an action based on the given event prior to passing the event to the target
interactor’s Handle() function. This is generally used to check for a match
against the interactor’s translation table. If the event is successfully
intercepted, returns true, otherwise returns false. In general, if true
is returned, the target interactor’s Handle() will not be called.
When an incoming event is matched
to an event translation in this interactor’s translation table, Interpret()
is called for each action specified in the translation.
The action string
is an arbitrary string and does not necessarily correspond to an actual
member function of the interactor.
The action string is compared against
the set of valid actions for this interactor and if a match is found, the
corresponding functionality is invoked and Interpret() returns true. In
the default event loop Run(), this will result in the target interactor’s
Handle() function not being called.
If no match is found, call this interactor’s
base class Interpret() with the action string and return the result.
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).
If the interactor is a top level interactor (i.e., it was inserted directly
into the world), Listen() will augment the current sensor or create a
new sensor, if one was not defined, with the following event interest:
UpEvent
DownEvent
KeyEvent
FocusInEvent
FocusOutEvent
This guarantees that events of interest to the event translation
and keyboard traversal mechanisms are not lost.
Returns
the navigation type of the interactor: Tab_Item, Tab_Group, or Menus.
Sets the navigation type for the interactor.
Returns the interactor’s parent. If the interactor
has not been inserted into a scene or was inserted directly into the world,
returns nil.
Sets an event to reflect the current input
state. This is often used to get the current <x, y> coordinates of the mouse
pointer. It is important to note that the event’s target field is not set
and will cause problems if passed to a function expecting a valid value
for this field.
Sets the event’s target to nil. A
Handle() operation can call it to make Run() exit its event dispatching
loop. If an event is not available, consider using World::quit().
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. This is not necessarily the same as the interactor that performed
the Read(). The target is normally the first interactor whose canvas is
under the pointing device, and whose sensor has expressed event interest
in the event’s eventType.
Performs
the same function as Read(Event&) with one exception. If there are no events
to read within the given number of sec seconds and usec microseconds, the
call will time out and return a value of false. If an event was successfully
read, return true.
Performs 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().
Removes any event translations
associated with target from this interactor’s translation table.
Sets the shape of the interactor to the passed Shape.
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
the use of Reshape().
Implements a simple event dispatching loop.
It calls Read() to get the next event and passes the event to Intercept()
to see if there is a valid event translation defined in the translation
table. If Intercept() returns false, the target interactor’s Handle()
function is called. The loop terminates if World::Done() returns true,
or the Handle() operation sets the event’s target to nil with QuitRunning().
Adds
an accelerator (an event translation) to this interactor’s translation
table along with the given destination interactor. When the event specified
in the accelerator occurs in this interactor, the action(s) also defined
in the accelerator will be passed to the destination’s Interpret() function.
Sets the type of canvas desired for an interactor.
This operation must be performed before an interactor is mapped. The possible
canvas types are:
- CanvasShapeOnly
- The interactor performs no input or
output.
- CanvasInputOnly
- The interactor performs no output.
- CanvasInputOutput
- This is the default. The interactor performs both input and output operations.
- CanvasSaveUnder
- Suggests that the interactor will be mapped for a short
time and that the information under the canvas should be saved.
- CanvasSaveContents
- Suggests that Redraw() calls are expensive and should be avoided by caching
the display.
- CanvasSaveBoth
- Requests both CanvasSaveUnder and CanvasSaveContents.
Sets 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.
Sets the tab group pointer to the given TabGroup.
The TabGroup class is not currently documented.
Sets
the TabGroupLeader object for the top level interactor. This class manages
the keyboard traversal for this window.
Waits until any pending
operations have completed. An input operation will do a Sync() automatically
if it would block. Thus, applications generally need not call Sync() explicitly.
Returns the TabGroupLeader object for
the top level interactor. This class manages the keyboard traversal for
this window.
Returns a pointer to the interactor’s
top level parent in the instance hierarchy. A top level object is one which
has been inserted directly into the world.
Returns
true if the interactor is traversable using the keyboard traversal model,
false otherwise.
Sets whether or not
this interactor can be a member of a tab group. If set to true, the operation
Focused() must also be defined, and the interactor must take responsibility
for drawing the location cursor.
Stops blocking
input events to other windows and returns the cursor to the default cursor.
Puts an event back on the input queue as if it had never
been read.
Changes the display to reflect some state
change on which the interactor depends. 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).
The
width of the Motif-style bevel for this interactor (if any). This can be
set by the user using the X resource shadowThickness. If not specified
it will default to Beveller::DefaultBevelWidth=2.
This variable is commonly
used to calculate canvas offsets and as an argument to the Beveller::Update()
function.
Created during the Config() traversal,
this instance pointer is used by derived classes to draw Motif-style bevels.
The user can set this variable by using the
X resource bottomShadowColor. It is used exclusively as an argument to
the Beveller::Update() function.
Pointer to this interactor’s
canvas object.
Indicates whether the X resource
highlightOnEnter is set to true or false for this program. A value of
true will cause traversable interactors to display their location cursor
when the keyboard focus policy is explicit, and the mouse pointer is within
canvas of this interactor.
Used by derived
classes to draw the keyboard traversal highlight border called the location
cursor. The color of this painter defaults to black (#000000) and can be
set by the user using the X resource highlightColor.
The
width of the keyboard traversal highlight border called the location cursor.
This can be set by the user using the X resource highlightThickness . If
not specified it will default to DefaultHighlightWidth=2.
This variable
is commonly used to calculate canvas offsets and as an argument to the
Beveller::Update() function.
Pointer to this interactor’s
default input sensor, if defined.
Indicates whether or not
this interactor has the current keyboard traversal focus.
Pointer
to this interactor’s default output painter.
Pointer
to this interactor’s perspective object.
The user
can set this variable by using the X resource selectColor. It is used exclusively
as an argument to the Beveller::Update() function.
Pointer
to this interactor’s shape object.
The tab group associated
with this interactor, if any. The Scene class allocates a TabGroup object
in its constructor.
The tab group leader associated
with this interactor, if any. Only top level interactors, and some menu
classes have a TabGroupLeader object associated with them. This class manages
the keyboard traversal structure.
The user can
set this variable by using the X resource topShadowColor. It is used exclusively
as an argument to the Beveller::Update() function.
Coordinates
for the upper right corner of this interactor’s canvas object. xmax is equal
to the canvas’ width minus one, and ymax is equal to the canvas’ height
minus one. These variables are used in most calculations of offsets and
drawing coordinates relative to the canvas.
Notifies the interactor that its canvas has just been mapped.
Notifies the interactor that its canvas is about
to be unmapped.
Strips the directive
(if any) from a translation string and returns the corresponding DirectiveType.
Called by Intercept()
to check for a match between the event and the event translations in the
interactor’s translation table. If found, the action string(s) specified
in the translation are passed to Interpret().
Take the given translation
and merge it with the current set of translations depending on the directive
(Augment, Replace, Override). The resulting string will eventually be converted
into the interactor’s translation table during the configuration traversal.
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.
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 calls to Redraw().
Notifies an
interactor that its canvas has been created or modified. Only Scenes are
typically concerned with calling Resize(), as they must place their component
interactors within the new or resized canvas. The default Resize() operation
does nothing. Interactors should update their perspective and any other
information dependent on the dimensions of the canvas.
Sets the class name associated with the interactor. The name is used
to determine user style preferences.
Sets
the instance name associated with the interactor. The name can be used to
determine user style preferences.
Sets the default
output painter’s background color.
Darker shadow
color used in drawing Motif-style bevels.
Font for text drawing
operations.
Sets the default output painter’s foreground
color.
Color used to draw the keyboard traversal border.
The default is black (#000000).
Controls
whether or not traversable interactors will draw their highlight border.
Only valid when the application resource keyboardFocusPolicy is set to
pointer.
Width of the keyboard traversal border (location
cursor).
If set to None and the interactor
is traversable, it will be included in a tab group. If set to TabGroup
and the interactor is traversable, the interactor becomes a tab group by
itself. If set to TabGroup and the interactor is a scene, it will create
a tab group with any traversable children.
Typically darker
than the background. Used to enhance the appearance of the 3D bevelled appearance
of a selected interactor.
Determines input sensitivity.
An interactor with a sensitivity of False or Off will be disabled, meaning
it generally not accept any input from the user and may appear grayed out.
An interactor with a sensitivity of True or On will be enabled.
The
width of the Motif-style bevelled border around most visual interactors.
Defaults to Beveller::DefaultBevelWidth=2.
Lighter shadow
color used in drawing Motif-style bevels.
Modifies the
default translation table (if any). A directive can be used to either augment,
replace, or override the existing translations. Multiple translations can
be given by separating them with a For a full description of the event
translation syntax, see Translations(3X)
.
Only
valid for interactors that are already traversable and wehn the keyboard
focus policy is explicit. A value of Off or False excludes the interactor
from being included in the tab group structure. This prevents the interactor
from ever receiving the keyboard focus. A value of On or True allows the
interactor to be traversed normally.
None.
No
example for this abstract base class.
interactor.h
Canvas(3X)
, Perspective(3X)
, Resource(3X)
, Scene(3X)
, Sensor(3X)
,
Shape(3X)
, Translations(3X)
, World(3X)
.
Table of Contents
- Name
- Synopsis
- Description
- Class Hierarchy
- Constructors
- Public Data
- Public Operations
- virtual void Adjust(Perspective&)
- void Align(Alignment, int w, int h, IntCoord& l, IntCoord& b) const
- boolean AttributeIsSet(const char*) const
- boolean Check()
- int CheckQueue()
- void Config(Scene* nil)
- void Config(World*)
- void CreateTabGroup()
- void CreateTabGroups()
- virtual void CurrentFocus(Interactor*)
- virtual Interactor* CurrentFocus()
- virtual void Disable()
- virtual void Draw()
- virtual void Enable()
- virtual boolean Enabled()
- void Flush()
- virtual void Focused(boolean)
- boolean FocusIsExplicit()
- const char* GetAttribute(const char*) const
- Canvas* GetCanvas() const
- CanvasType GetCanvasType() const
- const char* GetClassName() const
- virtual void GetComponents(Interactor**, int, Interactor**&, int&)
- Cursor* GetCursor() const
- const char* GetInstance() const
- Perspective* GetPerspective() const
- void GetPosition(IntCoord& left, IntCoord& bottom) const
- void GetRelative(IntCoord& x, IntCoord& y, Interactor* = nil) const
- void GetRelative(IntCoord& x, IntCoord& y, World*) const
- Shape* GetShape() const
- TabGroup* GetTabGroup()
- ManagedWindow* GetTopLevelWindow() const
- World* GetWorld() const
- virtual void GrabTopLevel(Cursor* = nil)
- virtual void Handle(Event&)
- virtual void Highlight(boolean)
- virtual boolean Intercept(Event&)
- virtual boolean Interpret(const char* action)
- void Listen(Sensor*)
- virtual NavType NavigationType()
- virtual void NavigationType(NavType)
- Scene* Parent() const
- void Poll(Event&)
- void QuitRunning(Event&)
- void Read(Event&)
- boolean Read(long sec, long usec, Event&)
- virtual void Reconfig()
- virtual void RemoveAccelerator(Interactor* target)
- virtual void Reshape(Shape&)
- void Run()
- virtual void SetAccelerator(const char* accelerator, Interactor* destination)
- void SetCanvasType(CanvasType)
- void SetCursor(Cursor*)
- virtual void SetTabGroup(TabGroup*)
- virtual void SetTabLeader(TabGroupLeader*)
- void Sync()
- virtual TabGroupLeader* TabLeader()
- virtual Scene* TopLevelParent()
- virtual boolean Traversable()
- virtual void Traversable(boolean)
- virtual void UnGrabTopLevel()
- void UnRead(Event&)
- virtual void Update()
- Protected Data
- Protected Operations
- X Resources
- Default Keyboard Translations
- Examples
- Files
- See Also
![[Go to CFHT Home Page]](/images/cfht-icon.gif){kind=icon}
Man Pages 
Back to Software Index 
Manpage Top Level