Damage regions

Painting the JCanvas or parts of the JCanvas is a recursive operation that touches several key classes. Components in the Diva Canvas can initiate a repaint request by using the repaint() method. The actual painting is managed by Swing, which initiates painting of a region some time after a paint request is made, or when (for example) the JCanvas is redisplayed or a portion of it becomes uncovered. The following figure illustrates the repaint-paint operation in the canvas.

When a figure is modified (let's say, its color changed), it calls its repaint() method. repaint() creates a DamageRegion object, which contains a reference to this figure and the region it damaged, and passes it to its parent figure. By default, the damaged region is simply the bounding box of the figure. (The DamageRegion instances are static to avoid the cost of allocating them on the heap.) This call propagates upwards until it reaches the JCanvas, which calls the DamageRegion object's apply() method. This method transforms the damage region into screen coordinates, and calls Swing's RepaintManager to schedule a future paint operation of that region.

(Currently, all damage regions are rectangles. In the future, we hope to support non-rectangular damage regions to allow more efficient repainting of long multi-segment lines.)

Some time later, Swing's event loop runs again, and calls the paint(Graphics2D) method of the JCanvas. Swing has already set a clip region in the Graphics2D object (the graphics drawing port), so the JCanvas extracts this, converts it to the pane's coordinate system, and passes it to the pane. From then on, the paint request propagates downwards, except that:

Any object that defines a new transform context converts the clip rectangle into its own coordinate system, and
FigureContainers generally only call paint() on a child if the child intersects the clip rectangle.

Finally, at a leaf figure, the default behavior is to call paint(Graphics2D), which will paint the whole leaf figure.