Viewer - displays a graphical component view hierarchy
SYNOPSIS
#include <Unidraw/viewer.h>
DESCRIPTION
A Viewer displays a graphical component view and provides
an interface to scrolling and zooming it. The viewer also
processes user input events and generates the appropriate
calls on Unidraw objects in response. The Viewer class is
a derived from GraphicBlock; thus it can draw the struc-
tured graphics hierarchy embodied in GraphicView's
graphic. A viewer uses a damage object to keep the screen
up to date. Viewer's sensor catches up and down events,
and its Handle implements implements the tool manipulation
loop.
PUBLIC OPERATIONS
Viewer(
Editor*, GraphicView*, Page*, Grid* = nil,
Coord width = 0, Coord height = 0, Orientation = Nor-
mal,
Alignment = Center, Zooming = Binary
)
Viewer(
const char*, Editor*, GraphicView*, Page*, Grid* =
nil,
Coord width = 0, Coord height = 0
Alignment = Center, Zooming = Binary
)
Both constructors take the enclosing editor, the
GraphicView object that the viewer will display, a
page object, and optionally a grid, a natural width
and height, initial page orientation, alignment,
and zooming specifications. The second form adds a
parameter for specifying the Viewer's instance
name.
virtual void Update()
Viewer augments GraphicBlock's Update semantics by
repairing any damage that has been accumulated. In
addition, Update will replace its graphical view if
its subject differs from the editor's component; in
that case, it will create a graphical view of the
editor's component, delete its own view, and
replace it with the new one.
virtual void Adjust(Perspective&)
Viewer's Adjust operation will automatically update
the editor's MagnifVar (if it defines one) to
reflect the current magnification.
By default, Handle employs the editor's current
tool on a LEFTMOUSE down event. On MIDDLEMOUSE or
RIGHTMOUSE down events, it momentarily engages the
editor's MoveTool or SelectTool, respectively,
allowing the user to move or select a graphical
component without changing the current tool explic-
itly. Nothing happens if the editor does not
define a keyboard equivalent for engaging these
tools. The Handle function calls either the Use-
Tool or MomentaryUseTool protected member functions
(described below) in response to these events.
virtual void SetGraphicView(GraphicView*)
virtual void SetPage(Page*)
virtual void SetGrid(Grid*)
virtual GraphicView* GetGraphicView()
virtual Page* GetPage()
virtual Grid* GetGrid()
virtual Editor* GetEditor()
Explicitly set or get a constructor-specified
parameter. The Set operations delete the value
they replace if it is different from the given one.
virtual void SetMagnification(float)
Viewer's SetMagnification operation amends Graph-
icBlock::SetMagnification to set the value of the
enclosing editor's MagnifVar, if it defines one.
virtual void SetOrientation(Orientation)
virtual Orientation GetOrientation()
Set and get the viewer's orientation parameter,
which specifies whether the graphical view, page,
and grid will appear in portrait or landscape mode.
No transformation will be applied in portrait mode,
while landscape mode will rotate the page -90
degrees and translate it vertically by an amout
equal to the width of the page's bounding box.
virtual Selection* GetSelection()
Return the enclosing editor's selection object; it
is equivalent to calling GetEditor and then calling
GetSelection on the result.
virtual Damage* GetDamage()
Return the viewer's damage object.
virtual void InitRubberband(Rubberband*)
virtual void InitTextDisplay(TextDisplay*, Painter*)
These operations let Rubberband and TextDisplay
instances appear to work in a viewer by allowing
them to draw on the viewer's canvas. InitRubber-
band sets the rubberband's canvas to the viewer's
canvas to the viewer's. It also modifies the given
painter's background color to match the viewer's
and supplies the painter to the TextDisplay for its
use.
virtual void IncurTextDisplayDamage(TextDisplay*,
Painter*)
Incur minimal damage on the viewer's damage object
to account for the TextDisplay's current size. The
TextDisplay's painter must be passed explicitly.
virtual void CenterOp()
virtual void Magnify(Coord, Coord, Coord, Coord)
virtual void ReduceToFit()
Convenience functions for adjusting the viewer's
perspective. CenterOp centers the page in the
viewer's canvas without changing the magnification.
Magnify scrolls and magnifies the given area (in
canvas coordinates) so that it fills the viewer's
canvas. Magnify ensures that the area will remain
fully visible in the viewer. ReduceToFit scrolls
and reduces the view so that the entire page is
visible.
virtual void Constrain(Coord&, Coord&)
Constrain the supplied coordinates to fall on the
nearest grid point if the viewer defines a grid and
if the enclosing editor defines an active Gravity-
Var.
virtual void UseTool(Tool*)
Commence direct-manipulation with the given tool
without an explicit action on the user's part.
Normally, direct manipulation with the currently
engaged tool (as returned by the editor's GetCur-
Tool operation) starts automatically when the user
clicks in the viewer.
virtual void Align(GraphicComp*, Alignment)
Align the graphical component with respect to
viewer's canvas, assuming a view of the component
appears in the viewer. For example, a ``Center''
alignment will align the component's center with
the canvas'; a ``BottomLeft'' alignment will align
the component's bottom-left corner to the canvas'.
PROTECTED OPERATIONS
void Init(
Editor*, GraphicView*, Page*, Grid*,
Coord, Coord, Orientation
)
Initialize the viewer's member variables. The
first form of this operation initializes all param-
eters that can be passed to a constructor. The
first form calls the second form, which initializes
a subset of the attributes that may change indepen-
dently of the others.
Tool* CurTool()
A convenience function equivalent to calling the
same operation on the enclosing editor.
Transformer* GetTransformer()
Return the transformer that the viewer uses to
implement scrolling and zooming.
virtual void Manipulate(Manipulator*, Event&)
This operation implements a direct manipulation
loop governed by the given manipulator. First it
calls Grasp on the manipulator with the given
event. Then it reads events in a loop, calling the
manipulator's Manipulating operation with each new
event. When Manipulating returns false, it calls
Effect on the manipulator with the event read last.
virtual void UseTool(Tool*, Event&)
virtual void MomentaryUseTool(Tool*, Event&)
Helper functions for initiating direct manipulation
with tools and executing their effect. UseTool
first instructs the given tool to create a manipu-
lator, and then it calls Manipulate to carry the
manipulation through to completion. Next it asks
the tool to interpret the manipulator, which in
turn may produce a command. Finally, UseTool exe-
cutes and logs the command produced. MomentaryUse-
Tool simply engages the given tool, calls UseTool,
and re-engages the original tool.
virtual void Reorient()
A helper function that rotates the viewer's graphic
to reflect its current orientation.
virtual void UpdateMagnifVar()
A helper function used in SetMagnification to
notify the enclosing viewer's MagnifVar (if it
defines one) of the change in magnification.
virtual ClassId ViewCategory()
Returns the view category (see classes(3U)) the
viewer will use to instantiate a view if it is not
given one explicitly. ViewCategory returns COMPO-
NENT_VIEW by default.
Damage(3U), Editor(3U), Event(3I), Graphic(3U), Graph-
icBlock(3U), GraphicComp(3U), GraphicView(3U), Grid(3U),
Manipulator(3U), MoveTool(3U), Page(3U), Perspective(3I),
Rubband(3I), SelectTool(3U), Selection(3U), Sensor(3I),
TextDisplay(3I), Tool(3U), classes(3U), globals(3U), stat-
evars(3U)
Man(1) output converted with
man2html