plucky (3) GraphicBlock.3U.gz

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)