Viewer - displays a graphical component view hierarchy

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

Name

       Viewer - displays a graphical component view hierarchy

Protected Operations

voidInit(Editor*,GraphicView*,Page*,Grid*,Coord,Coord,Orientation)voidInit(Editor*,GraphicView*,Page*,Grid*)
              Initialize  the  viewer's  member  variables.   The  first  form of this operation initializes all
              parameters that can be passed to a constructor.  The first  form  calls  the  second  form,  which
              initializes a subset of the attributes that may change independently 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.

       virtualvoidManipulate(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.

       virtualvoidUseTool(Tool*,Event&)virtualvoidMomentaryUseTool(Tool*,Event&)
              Helper functions for initiating  direct  manipulation  with  tools  and  executing  their  effect.
              UseTool  first  instructs  the given tool to create a manipulator, 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 executes and  logs  the  command  produced.
              MomentaryUseTool simply engages the given tool, calls UseTool, and re-engages the original tool.

       virtualvoidReorient()
              A helper function that rotates the viewer's graphic to reflect its current orientation.

       virtualvoidUpdateMagnifVar()
              A  helper  function  used  in  SetMagnification  to notify the enclosing viewer's MagnifVar (if it
              defines one) of the change in magnification.

       virtualClassIdViewCategory()
              Returns the view category (see classes(3U)) the viewer will use to instantiate a view if it is not
              given one explicitly.  ViewCategory returns COMPONENT_VIEW by default.

Public Operations

Viewer(Editor*,GraphicView*,Page*,Grid*=nil,Coordwidth=0,Coordheight=0,Orientation=Normal,Alignment=Center,Zooming=Binary)Viewer(constchar*,Editor*,GraphicView*,Page*,Grid*=nil,Coordwidth=0,Coordheight=0Alignment=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.

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

virtualvoidAdjust(Perspective&)
Viewer's Adjust operation will automatically update the editor's MagnifVar (if it defines one) to
reflect the current magnification.

virtualvoidHandle(Event&)
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
explicitly. Nothing happens if the editor does not define a keyboard equivalent for engaging
these tools. The Handle function calls either the UseTool or MomentaryUseTool protected member
functions (described below) in response to these events.

virtualvoidSetGraphicView(GraphicView*)virtualvoidSetPage(Page*)virtualvoidSetGrid(Grid*)virtualGraphicView*GetGraphicView()virtualPage*GetPage()virtualGrid*GetGrid()virtualEditor*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.

virtualvoidSetMagnification(float)
Viewer's SetMagnification operation amends GraphicBlock::SetMagnification to set the value of the
enclosing editor's MagnifVar, if it defines one.

virtualvoidSetOrientation(Orientation)virtualOrientationGetOrientation()
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
amount equal to the width of the page's bounding box.

virtualSelection*GetSelection()
Return the enclosing editor's selection object; it is equivalent to calling GetEditor and then
calling GetSelection on the result.

virtualDamage*GetDamage()
Return the viewer's damage object.

virtualvoidInitRubberband(Rubberband*)virtualvoidInitTextDisplay(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. InitRubberband sets the rubberband's canvas to the viewer's
and initializes its painter as well. InitTextDisplay likewise sets the TextDisplay'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.

virtualvoidIncurTextDisplayDamage(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.

virtualvoidCenterOp()virtualvoidMagnify(Coord,Coord,Coord,Coord)virtualvoidReduceToFit()
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.

virtualvoidConstrain(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 GravityVar.

virtualvoidUseTool(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
GetCurTool operation) starts automatically when the user clicks in the viewer.

virtualvoidAlign(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'.