NAME

       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 GraphicBlock'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 portion of the graphic within the canvas  is  aligned.   With  the  default  alignment,  for
       example,  a graphic will be centered 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
       magnifications 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 surrounding 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 name with the second form.

       void Update()
              Update updates the GraphicBlock's perspective to reflect any change  in  the  values  returned  by
              GetGraphicBox  (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
              GraphicBlock'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 creates the illusion of a joystick interface: the further away the mouse is from its  initial
              position,  the  greater  the  scrolling  increment  and  the faster the graphic appears to scroll;
              scrolling slows 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)

Unidraw                                          30 January 1991                                GraphicBlock(3U)