Damage - repairs damaged graphics

SYNOPSIS

       #include <Unidraw/Graphic/damage.h>

DESCRIPTION

       Damage objects store damaged areas of a graphic for subse-
       quent incremental repair.  Areas of a  graphic  are  "dam-
       aged"  if they need to be redrawn for any reason, e.g., if
       their state has  been  modified  or  if  under/overlapping
       graphics  change  their appearance.  Damage objects try to
       minimize the  amount  of  redrawing  needed  to  repair  a
       graphic.  They are most useful when the graphic is compli-
       cated enough that it would be undesirable  to  redraw  the
       entire  canvas  when  the  graphic  is  modified.   Damage
       objects do not eliminate  the  need  for  an  interactor's
       Redraw  member  function,  though  they  could  be used to
       implement it.

PUBLIC OPERATIONS

       Damage(Canvas* = nil, Painter* = nil, Graphic* = nil)
              Create a new Damage object for  a  graphic  on  the
              given canvas.  The painter is used to erase damaged
              areas using its ClearRect function prior to redraw-
              ing them.

       virtual void Incur(Graphic*)
       virtual void Incur(BoxObj&)
       virtual void Incur(
           Coord left, Coord bottom, Coord right, Coord top
       )
              Notify  the  damage  object that a rectangular area
              has been damaged, either  by  passing  the  graphic
              that contributed the area or the area itself.

       virtual void Added(Graphic*)
              Notify the damage object that the given graphic was
              appended (not inserted) to the  graphic  but  never
              drawn.   The  damage object can thus be responsible
              for drawing newly added graphics as well.

       virtual void Repair()
              Repair all damage incurred since  the  last  Repair
              (or  since the damage object was created if this is
              the first Repair).

       virtual void Reset()
              Reset the damage object.  Any  damage  incurred  is
              lost.

       virtual boolean Incurred()
              Returns true if any damage has been incurred.

       void SetPainter(Painter*)
       void SetGraphic(Graphic*)

       Canvas* GetCanvas()
       Painter* GetPainter()
       Graphic* GetGraphic()
              Set and get attributes of the damage object.

PROTECTED OPERATIONS

       int Area(BoxObj&)
              A  helper  function that returns the area in square
              pixels occupied by the given BoxObj.

       virtual void DrawAreas()
       virtual void DrawAdditions()
              Explicitly draw the areas  of  incurred  and  added
              damage, respectively.

       virtual void Merge(BoxObj&)
              Merge  the given BoxObj into the list of incur-dam-
              aged areas, coalescing it into an existing area  if
              the number of non-overlapping areas exceeds 2.

       void FirstArea(Iterator&)
       void FirstAddition(Iterator&)
       void Next(Iterator&)
       boolean Done(Iterator)
       BoxObj* GetArea(Iterator)
       Graphic* GetAddition(Iterator)
              Operations  for iterating over the lists of damaged
              areas (represented with BoxObj objects)  and  added
              Graphics.   FirstArea  and FirstAddition initialize
              the iterator to point to the first item on the cor-
              responding  list,  Next  advances the iterator, and
              Done returns true if the iterator points beyond the
              end  of  the  list.  GetArea and GetAddition return
              the BoxObj or Graphic to which the iterator points.

       UList* Elem(Iterator)
              A  helper function for returning the UList to which
              an iterator points.  The _areas protected member is
              a  UList that stores the list of damaged areas, and
              the _additions protected stores the list  of  added
              graphics.

       void DeleteArea(BoxObj*)
       void DeleteAreas()
              DeleteArea  is  a  helper function for deleting the
              storage associated with a damaged  area,  including
              the area itself and the UList element.  DeleteAreas
              is a helper function that deletes the list of  dam-
              aged areas.

       Canvas(3I),    Graphic(3U),   Iterator(3U),   Painter(3I),
       UList(3U), geomobjs(3U)