Repaint

Contents
Swinging Duke

When a model's attribute changes, the view part of the affected component should redisplay the smallest region that has changed. Currently, components call the repaint() method when repainting is required. This repaint strategy has the following shortcomings:

An action can mutate more than one value of the model before a repaint occurs. In this kind of situation, more than one repaint event can be sent to refresh the same region. Even if repaint events are coalesced, sending an event more than one time for the same region creates some overhead.
Using the time parameter is rarely what developer wants. It is difficult to guess how long one will have to wait for a paint operation to occur.
If components call repaint() with different delay times, more than one painting operation can be generated.
Repaint operations are always delayed and cannot be easily triggered synchronously.

Because of these issues, a new repaint batching system is being developed. This new mechanism provides ways to:

Mark a component region out of date.
Compute the intersection of all out-of-date regions and repaint what is appropriate.
Provide a way for objects to be aware of all out-of-date regions in a component hierarchy at a given time so advanced optimization will be possible.
Plug in a custom repaint batching system for special applications.

Overview

The new repaint batching system is implemented using an interface called a DirtyRegionManager. The DirtyRegionManager is an object that stores out-of-date regions and out-of-date components. It can compute and generate the minimal repaint events that are needed to refresh all out-of-date regions.

The DirtyRegionManager defines an out-of-date region, or a region that needs to be painted, as a "dirty" region. A region that does not need repainting is defined as "clean". A factory object called the DirtyRegionManagerFactory is responsible for returning a DirtyRegionManager implementation when it is provided with information about a component and the current execution thread.

The DirtyRegionManagerFactory offers some convenience when you need to set a DirtyRegionManager for a container. If a component is contained by a component that has a default manager, the contained component has access to a parent parent default manager. If no default manager has been set for a component or its parent, the default manager factory provides a different manager for each thread group.

When a dirty region is added, the dirty region manager adds an event for itself. If the code does not repaint dirty regions, processing this event repaints dirty regions.

The Repaint Batching System API

This section describes the DirtyRegionManager interface and presents the function calls for the Swing repaint batching system.

The DirtyRegionManager Interface

DirtyRegionManagers are responsible for storing out-of-date regions in components. A primitive can be called to request all out-of-date regions to be painted synchronously. DirtyRegionManagers are vended to components by the DirtyRegionManagerFactory.

Methods defined by the DirtyRegionManager interface include the following:

public void addDirtyRegion(Component aComponent, Shape dirtyRegion)

Adds aComponent to a list of components that should be refreshed. If aComponent already has one or more dirty regions, the new dirty region is added to the region that should be redrawn. If dirtyRegion is null, the component is completely be redrawn when dirty regions are repainted.

public void addDirtyRegion(Component aComponent, 
   int x, int y, nt width, int height)

Adds aComponent to the list of components that should be refreshed. If aComponent already has one or more dirty regions, the region enclosed by the rect (x, y, width, height) is added to the region that should be redrawn.

public Shape getDirtyRegion(Component aComponent)

Returns the current dirty region for aComponent. Returns an empty shape if the component is not dirty.

public void markCompletelyDirty(Component aComponent)

Marks aComponent completely dirty. A component that is marked "dirty" is completely painted when dirty regions are painted.

public void markCompletelyClean(Component aComponent)

Marks aComponent completely clean. A component that is marked "clean" will not be painted when dirty regions are painted.

public boolean isCompletelyDirty(Component aComponent)

Designed as a convenience, this method returns true if aComponent will be completely painted during the next paintDirtyRegions() call. If computing dirty regions is expensive for your component, call this method and avoid computing dirty region if it returns true.

public void paintDirtyRegions()

Causes all known dirty regions to be painted.

The DirtyRegionManagerFactory

The DirtyRegionManagerFactory provides a generic way of binding a component with a DirtyRegionManager. To obtain a default DirtyRegionManager for a component, call DirtyRegionManager.getManagerForComponent(). If you want to implement a custom DirtyRegionManager, you can call DirtyRegionManagerFactory.setDefaultClassName() to plug in the custom DirtyRegionManager.

public static DirtyRegionManager getManagerForComponent(Component 
   aComponent)

Returns a DirtyRegionManager for aComponent. If no manager has been set for aComponent or one of its parents, this method returns one DirtyRegionManager instance of the default manager class per thread group.

public static void setManagerForComponent(DirtyRegionManager 
   aManager, Component aComponent)

Sets the DirtyRegionManager instance that should be used to manage out-of-date regions of aComponent in the calling thread group. If aComponent is a container, a manager is used for any child of the container, provided no other manager has been set for the child.

public static void setDefaultClassName(String aClassName)

Sets the name of the class that should be used when getManagerForComponent() is creating a new DirtyRegionManager instance for the calling thread group.

public static String getDefaultClassName()

Returns the name of the class that is used when getManagerForComponent() is creating a new DirtyRegionManager instance for the calling thread group.

Conveniences in JComponent

Even if DirtyRegionManager and DirtyRegionManagerFactory are public, most developers will only use the following conveniences in JComponent.

public void addDirtyRegion(Shape dirtyRegion)

Adds the receiver in the list of components that should be repainted. The dirtyRegion argument is a shape that describes the region that should be painted.

public void addDirtyRegion(int x, int y, int width, int height)

Adds the receiver in the list of component that should be repainted. The region enclosed by the rectangle (x, y, width, height) is marked as out-of-date and will be repainted when the system is painting dirty regions.

public Shape getDirtyRegion()

Returns the region that will be repainted for the receiver when the system repaints dirty regions.

public void markCompletelyDirty()

Marks the receiver as being "completely dirty." The receiver is then completely repainted when dirty regions are repainted.

public void markCompletelyClean()

Marks the receiver completely clean. Then the receiver will not be painted when dirty regions are repainted.

public void paintDirtyRegions()

Causes all dirty regions for the receiving component's component hierarchy to be repainted immediately. This method is called automatically by the system when the control returns from processing an event. You might want to call this method explicitly when when you are computing an event and need more than one repaint .