Provided by: ivtools-dev_2.0.11d.a1-1build4_amd64 bug

NAME

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

PUBLIC OPERATIONS

       Viewer(
           Editor*, GraphicView*, Page*, Grid* = nil,
           Coord width = 0, Coord height = 0, Orientation = Normal,
           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.

       virtual void Handle(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.

       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 GraphicBlock::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 amount 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.   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.

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

       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 GetCurTool 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
       )

       void Init(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.

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

       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  COMPONENT_VIEW  by
              default.

SEE ALSO

       Damage(3U),   Editor(3U),   Event(3I),   Graphic(3U),  GraphicBlock(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), statevars(3U)