AWT/Swing Painting Guidelines

 

AWT Painting Guidelines

The AWT provides a simple callback API for painting components. When you use it, the following guidelines apply:

1. For most programs, all client paint code should be placed within the scope of the component's paint() method.

    

2. Programs may trigger a future call to paint() by invoking repaint(), but shouldn't call paint() directly.

    

3. On components with complex output, repaint() should be invoked with arguments which define only the rectangle that needs updating, rather than the no-arg version, which causes the entire component to be repainted.

    

4. Since a call to repaint() results first in a call to update(), which is forwarded to paint() by default, heavyweight components may override update() to do incremental drawing if desired (lightweights do not support incremental drawing)

    

5. Extensions of java.awt.Container which override paint() should always invoke super.paint() to ensure children are painted.

    

6. Components which render complex output should make smart use of the clip rectangle to narrow the drawing operations to those which intersects with the clip area.

Swing Painting Guidelines

Swing programs should understand these guidelines when writing paint code:

1. For Swing components, paint() is always invoked as a result of both system-triggered and app-triggered paint requests;update() is never invoked on Swing components.

    

2. Programs may trigger a future call to paint() by invoking repaint(), but shouldn't call paint() directly.

    

3. On components with complex output, repaint() should be invoked with arguments which define only the rectangle that needs updating, rather than the no-arg version, which causes the entire component to be repainted.

    

4. Swing's implementation of paint() factors the call into 3 separate callbacks:
   1. paintComponent()
   2. paintBorder()
   3. paintChildren()
   Extensions of Swing components which wish to implement their own paint code should place this code within the scope of the paintComponent() method (not within paint()).

    

5. Swing introduces two properties to maximize painting efficiency:
   • opaque: will the component paint all its bits or not?
   • optimizedDrawingEnabled: may any of this component's children overlap?

    

6. If a Swing component's opaque property is set to true, then it is agreeing to paint all of the bits contained within its bounds (this includes clearing it's own background within paintComponent()), otherwise screen garbage may result.

7. Setting either the opaque or optimizedDrawingEnabled properties to false on a component will cause more processing on each paint operation, therefore we recommend judicious use of both transparency and overlapping components.

8. Extensions of Swing components which have UI delegates (including JPanel), should typically invoke super.paintComponent() within their own paintComponent() implementation. Since the UI delegate will take responsibility for clearing the background on opaque components, this will take care of #5.

9. Swing supports built-in double-buffering via the JComponent doubleBuffered property, and it defaults to true for all Swing components, however setting it to true on a Swing container has the general effect of turning it on for all lightweight descendents of that container, regardless of their individual property settings.

10. It is strongly recommended that double-buffering be enabled for all Swing components.

11. Components which render complex output should make smart use of the clip rectangle to narrow the drawing operations to those which intersect with the clip area.