GraphicBlock - interactor that displays a graphic

SYNOPSIS

       #include <Unidraw/Graphic/grblock.h>

DESCRIPTION

       A  GraphicBlock  is an interactor that displays a graphic.
       GraphicBlocks are useful for interactors whose  appearance
       is  most  conveniently  defined  with structured graphics.
       The GraphicBlock will draw its graphic in response to Draw
       and Redraw calls.

       The  graphic  can  be  aligned  with respect to the Graph-
       icBlock's canvas.  The GraphicBlock positions its  graphic
       so  that  its bounding box is aligned with the canvas when
       the canvas is allocated.  On subsequent resizes, the  por-
       tion  of  the  graphic within the canvas is aligned.  With
       the default alignment, for example, a graphic will be cen-
       tered  in the canvas initially.  If the canvas is resized,
       then the part of the graphic in the center of  the  canvas
       prior  to resizing will appear in the center of the canvas
       after resizing.

       The graphic can be scrolled and zoomed as well.   Changing
       either  the curwidth/curheight or the width/height members
       of the GraphicBlock's perspective  effectively  zooms  the
       graphic.   For example, calling the Adjust member function
       with a perspective whose curwidth and curheight  are  half
       that of the GraphicBlock's canvas will enlarge the graphic
       by a factor of two. Zooming can be limited  to  magnifica-
       tions  that are powers of two by specifying Binary for the
       Zooming parameter.

       A GraphicBlock's natural size depends on the size  of  the
       graphic  it  displays and on any padding (white space sur-
       rounding  the  graphic)  specified.    GraphicBlocks   are
       infinitely  stretchable  horizontally  and  vertically  by
       default.

PUBLIC OPERATIONS

       GraphicBlock(
           Graphic*, Coord pad = 0,
           Alignment = Center, Zooming = Continuous
       )

       GraphicBlock(
           const char*, Graphic*, Coord pad = 0,
           Alignment = Center, Zooming = Continuous
       )
              Create  a  new  GraphicBlock  with  the   specified
              graphic,  padding, alignment, and zooming behavior.
              You can also specify  the  GraphicBlock's  instance
              Update  updates  the  GraphicBlock's perspective to
              reflect any change in the values returned  by  Get-
              GraphicBox  (described  below),  which  defines the
              extremities of the scrolling area.   Update  should
              be called after the graphic is changed.

       virtual void Highlight(boolean)
              When  highlighted,  GraphicBlock  draws itself with
              the foreground and background colors of its graphic
              and  its  painter  reversed.  GraphicBlock uses its
              output painter to fill its canvas  with  background
              color, thus providing a background for the graphic.

       Graphic* GetGraphic()
              Return the graphic in the GraphicBlock,  stored  in
              the _graphic protected member variable.

       float GetMagnification()
       void SetMagnification(float)
              Get  and  set  the  magnification  applied  to  the
              graphic, relative to  its  magnification  when  the
              GraphicBlock was created (1x).

PROTECTED OPERATIONS

       void Init()
              Initialize   the   GraphicBlock,   positioning  its
              graphic according to the alignment specified in the
              constructor.  The constructor calls this operation.
              Subclasses should call Init if they should  replace
              the displayed graphic with another.

       void UpdatePerspective()
              Change  the  GraphicBlock's  perspective to reflect
              the bounding box of the graphic.  UpdatePerspective
              encapsulates   this   functionality  to  facilitate
              redefinition of  the  Update  function  in  derived
              classes.

       void GrabScroll(Event&)
       void RateScroll(Event&)
              Initiate  grab  scrolling  or rate scrolling.  Once
              called, GrabScroll (RateScroll) polls  the  current
              mouse position as long as the middle (right) button
              is pressed.  As GrabScroll polls,  it  scrolls  the
              GraphicBlock  to  follow the mouse position, making
              it appear as though the user is dragging the Graph-
              icBlock's  graphic  itself.   Each  time RateScroll
              polls the mouse, it scrolls the GraphicBlock by  an
              amount  corresponding  to  the differential between
              the current and initial mouse positions.  This cre-
              ates the illusion of a joystick interface: the fur-
              ther away the mouse is from its  initial  position,
              down,  stops,  and  reverses  direction as the user
              drags the mouse back towards and past  the  initial
              position.

       virtual void GetGraphicBox(Coord&, Coord&, Coord&, Coord&)
              Return the lower-left and  upper-right  coordinates
              of  the total area in which to scroll.  By default,
              this area is corresponds to the graphic's  bounding
              box.

       virtual void Zoom(Perspective&)
       virtual void Scroll(Perspective&)
              These  functions  define  how zooming and scrolling
              are  inferred  from  the  perspective  supplied  to
              Adjust.   The  default behaviors implement standard
              scrolling semantics and zooming as described above.

       virtual float LimitMagnification(float)
              Limit  the  amount  of  magnification  that  can be
              applied to the graphic.  This function is used as a
              filter to convert desired magnifications into legal
              ones.  By default, the  argument  is  returned;  no
              limits are imposed.

SEE ALSO

       Graphic(3U), Interactor(3I), Perspective(3I)