1 /* RepaintManager.java --
2 Copyright (C) 2002 Free Software Foundation, Inc.
4 This file is part of GNU Classpath.
6 GNU Classpath is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2, or (at your option)
11 GNU Classpath is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with GNU Classpath; see the file COPYING. If not, write to the
18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
21 Linking this library statically or dynamically with other modules is
22 making a combined work based on this library. Thus, the terms and
23 conditions of the GNU General Public License cover the whole
26 As a special exception, the copyright holders of this library give you
27 permission to link this library with independent modules to produce an
28 executable, regardless of the license terms of these independent
29 modules, and to copy and distribute the resulting executable under
30 terms of your choice, provided that you also meet, for each linked
31 independent module, the terms and conditions of the license of that
32 module. An independent module is a module which is not derived from
33 or based on this library. If you modify this library, you may extend
34 this exception to your version of the library, but you are not
35 obligated to do so. If you do not wish to do so, delete this
36 exception statement from your version. */
40 import java.awt.Component;
41 import java.awt.Dimension;
42 import java.awt.Image;
43 import java.awt.Rectangle;
44 import java.util.Enumeration;
45 import java.util.Hashtable;
46 import java.util.HashMap;
47 import java.util.Iterator;
49 import java.util.Vector;
53 * <p>The repaint manager holds a set of dirty regions, invalid components,
54 * and a double buffer surface. The dirty regions and invalid components
55 * are used to coalesce multiple revalidate() and repaint() calls in the
56 * component tree into larger groups to be refreshed "all at once"; the
57 * double buffer surface is used by root components to paint
60 * <p>In general, painting is very confusing in swing. see <a
61 * href="http://java.sun.com/products/jfc/tsc/articles/painting/index.html">this
62 * document</a> for more details.</p>
64 * @author Graydon Hoare (graydon@redhat.com)
66 public class RepaintManager
70 * <p>A helper class which is placed into the system event queue at
71 * various times in order to facilitate repainting and layout. There is
72 * typically only one of these objects active at any time. When the
73 * {@link RepaintManager} is told to queue a repaint, it checks to see if
74 * a {@link RepaintWorker} is "live" in the system event queue, and if
75 * not it inserts one using {@link SwingUtilities.invokeLater}.</p>
77 * <p>When the {@link RepaintWorker} comes to the head of the system
78 * event queue, its {@link RepaintWorker#run} method is executed by the
79 * swing paint thread, which revalidates all invalid components and
80 * repaints any damage in the swing scene.</p>
83 protected class RepaintWorker
87 public RepaintWorker()
91 public synchronized void setLive(boolean b)
95 public synchronized boolean isLive()
101 RepaintManager rm = RepaintManager.globalManager;
103 rm.validateInvalidComponents();
104 rm.paintDirtyRegions();
110 * A table storing the dirty regions of components. The keys of this
111 * table are components, the values are rectangles. Each component maps
112 * to exactly one rectangle. When more regions are marked as dirty on a
113 * component, they are union'ed with the existing rectangle.
115 * @see #addDirtyRegion
116 * @see #getDirtyRegion
117 * @see #isCompletelyDirty
118 * @see #markCompletelyClean
119 * @see #markCompletelyDirty
121 Hashtable dirtyComponents;
124 * A single, shared instance of the helper class. Any methods which mark
125 * components as invalid or dirty eventually activate this instance. It
126 * is added to the event queue if it is not already active, otherwise
129 * @see #addDirtyRegion
130 * @see #addInvalidComponent
132 RepaintWorker repaintWorker;
135 * The set of components which need revalidation, in the "layout" sense.
136 * There is no additional information about "what kind of layout" they
137 * need (as there is with dirty regions), so it is just a vector rather
140 * @see #addInvalidComponent
141 * @see #removeInvalidComponent
142 * @see #validateInvalidComponents
144 Vector invalidComponents;
147 * Whether or not double buffering is enabled on this repaint
148 * manager. This is merely a hint to clients; the RepaintManager will
149 * always return an offscreen buffer when one is requested.
151 * @see #getDoubleBufferingEnabled
152 * @see #setDoubleBufferingEnabled
154 boolean doubleBufferingEnabled;
157 * The current offscreen buffer. This is reused for all requests for
158 * offscreen drawing buffers. It grows as necessary, up to {@link
159 * #doubleBufferMaximumSize}, but there is only one shared instance.
161 * @see #getOffscreenBuffer
162 * @see #doubleBufferMaximumSize
167 * The maximum width and height to allocate as a double buffer. Requests
168 * beyond this size are ignored.
170 * @see #paintDirtyRegions
171 * @see #getDoubleBufferMaximumSize
172 * @see #setDoubleBufferMaximumSize
174 Dimension doubleBufferMaximumSize;
178 * The global, shared RepaintManager instance. This is reused for all
179 * components in all windows.
181 * @see #currentManager
182 * @see #setCurrentManager
184 private static RepaintManager globalManager;
187 * Create a new RepaintManager object.
189 public RepaintManager()
191 dirtyComponents = new Hashtable();
192 invalidComponents = new Vector();
193 repaintWorker = new RepaintWorker();
194 doubleBufferMaximumSize = new Dimension(2000,2000);
195 doubleBufferingEnabled = true;
199 * Get the value of the shared {@link #globalManager} instance, possibly
200 * returning a special manager associated with the specified
201 * component. The default implementaiton ignores the component parameter.
203 * @param component A component to look up the manager of
205 * @return The current repaint manager
207 * @see #setCurrentManager
209 public static RepaintManager currentManager(Component component)
211 if (globalManager == null)
212 globalManager = new RepaintManager();
213 return globalManager;
217 * Get the value of the shared {@link #globalManager} instance, possibly
218 * returning a special manager associated with the specified
219 * component. The default implementaiton ignores the component parameter.
221 * @param component A component to look up the manager of
223 * @return The current repaint manager
225 * @see #setCurrentManager
227 public static RepaintManager currentManager(JComponent component)
229 return currentManager((Component)component);
233 * Set the value of the shared {@link #globalManager} instance.
235 * @param manager The new value of the shared instance
237 * @see #currentManager
239 public static void setCurrentManager(RepaintManager manager)
241 globalManager = manager;
245 * Add a component to the {@link #invalidComponents} vector. If the
246 * {@link #repaintWorker} class is not active, insert it in the system
249 * @param component The component to add
251 * @see #removeInvalidComponent
253 public synchronized void addInvalidComponent(JComponent component)
255 while ((component.getParent() != null)
256 && (component.getParent() instanceof JComponent)
257 && (component.isValidateRoot()))
258 component = (JComponent) component.getParent();
260 if (invalidComponents.contains(component))
263 invalidComponents.add(component);
264 component.invalidate();
266 if (! repaintWorker.isLive())
268 repaintWorker.setLive(true);
269 SwingUtilities.invokeLater(repaintWorker);
274 * Remove a component from the {@link #invalidComponents} vector.
276 * @param component The component to remove
278 * @see #addInvalidComponent
280 public synchronized void removeInvalidComponent(JComponent component)
282 invalidComponents.removeElement(component);
286 * Add a region to the set of dirty regions for a specified component.
287 * This involves union'ing the new region with any existing dirty region
288 * associated with the component. If the {@link #repaintWorker} class
289 * is not active, insert it in the system event queue.
291 * @param component The component to add a dirty region for
292 * @param x The left x coordinate of the new dirty region
293 * @param y The top y coordinate of the new dirty region
294 * @param w The width of the new dirty region
295 * @param h The height of the new dirty region
297 * @see #addDirtyRegion
298 * @see #getDirtyRegion
299 * @see #isCompletelyDirty
300 * @see #markCompletelyClean
301 * @see #markCompletelyDirty
303 public synchronized void addDirtyRegion(JComponent component, int x, int y,
306 Rectangle r = new Rectangle(x, y, w, h);
307 if (dirtyComponents.containsKey(component))
308 r = r.union((Rectangle)dirtyComponents.get(component));
309 dirtyComponents.put(component, r);
310 if (! repaintWorker.isLive())
312 repaintWorker.setLive(true);
313 SwingUtilities.invokeLater(repaintWorker);
318 * Get the dirty region associated with a component, or <code>null</code>
319 * if the component has no dirty region.
321 * @param component The component to get the dirty region of
323 * @return The dirty region of the component
325 * @see #dirtyComponents
326 * @see #addDirtyRegion
327 * @see #isCompletelyDirty
328 * @see #markCompletelyClean
329 * @see #markCompletelyDirty
331 public Rectangle getDirtyRegion(JComponent component)
333 return (Rectangle) dirtyComponents.get(component);
337 * Mark a component as dirty over its entire bounds.
339 * @param component The component to mark as dirty
341 * @see #dirtyComponents
342 * @see #addDirtyRegion
343 * @see #getDirtyRegion
344 * @see #isCompletelyDirty
345 * @see #markCompletelyClean
347 public void markCompletelyDirty(JComponent component)
349 Rectangle r = component.getBounds();
350 addDirtyRegion(component, r.x, r.y, r.width, r.height);
354 * Remove all dirty regions for a specified component
356 * @param component The component to mark as clean
358 * @see #dirtyComponents
359 * @see #addDirtyRegion
360 * @see #getDirtyRegion
361 * @see #isCompletelyDirty
362 * @see #markCompletelyDirty
364 public void markCompletelyClean(JComponent component)
366 dirtyComponents.remove(component);
370 * Return <code>true</code> if the specified component is completely
371 * contained within its dirty region, otherwise <code>false</code>
373 * @param component The component to check for complete dirtyness
375 * @return Whether the component is completely dirty
377 * @see #dirtyComponents
378 * @see #addDirtyRegion
379 * @see #getDirtyRegion
380 * @see #isCompletelyDirty
381 * @see #markCompletelyClean
383 public boolean isCompletelyDirty(JComponent component)
385 Rectangle dirty = (Rectangle) dirtyComponents.get(component);
388 Rectangle r = component.getBounds();
391 return dirty.contains(r);
395 * Validate all components which have been marked invalid in the {@link
396 * #invalidComponents} vector.
398 public void validateInvalidComponents()
400 for (Enumeration e = invalidComponents.elements(); e.hasMoreElements(); )
402 JComponent comp = (JComponent) e.nextElement();
403 if (! (comp.isVisible() && comp.isShowing()))
407 invalidComponents.clear();
411 * Repaint all regions of all components which have been marked dirty in
412 * the {@link #dirtyComponents} table.
414 public void paintDirtyRegions()
416 // step 1: pull out roots and calculate spanning damage
418 HashMap roots = new HashMap();
419 for (Enumeration e = dirtyComponents.keys(); e.hasMoreElements(); )
421 JComponent comp = (JComponent) e.nextElement();
422 if (! (comp.isVisible() && comp.isShowing()))
424 Rectangle damaged = getDirtyRegion(comp);
425 if (damaged.width == 0 || damaged.height == 0)
427 JRootPane root = comp.getRootPane();
428 Rectangle rootDamage = SwingUtilities.convertRectangle(comp, damaged, root);
429 if (! roots.containsKey(root))
431 roots.put(root, rootDamage);
435 roots.put(root, ((Rectangle)roots.get(root)).union(rootDamage));
438 dirtyComponents.clear();
440 // step 2: paint those roots
441 Iterator i = roots.entrySet().iterator();
444 Map.Entry ent = (Map.Entry) i.next();
445 JRootPane root = (JRootPane) ent.getKey();
446 Rectangle rect = (Rectangle) ent.getValue();
447 root.paintImmediately(rect);
452 * Get an offscreen buffer for painting a component's image. This image
453 * may be smaller than the proposed dimensions, depending on the value of
454 * the {@link #doubleBufferMaximumSize} property.
456 * @param component The component to return an offscreen buffer for
457 * @param proposedWidth The proposed width of the offscreen buffer
458 * @param proposedHeight The proposed height of the offscreen buffer
460 * @return A shared offscreen buffer for painting
464 public Image getOffscreenBuffer(Component component, int proposedWidth,
467 if (doubleBuffer == null
468 || (((doubleBuffer.getWidth(null) < proposedWidth)
469 || (doubleBuffer.getHeight(null) < proposedHeight))
470 && (proposedWidth < doubleBufferMaximumSize.width)
471 && (proposedHeight < doubleBufferMaximumSize.height)))
473 doubleBuffer = component.createImage(proposedWidth, proposedHeight);
479 * Get the value of the {@link #doubleBufferMaximumSize} property.
481 * @return The current value of the property
483 * @see #setDoubleBufferMaximumSize
485 public Dimension getDoubleBufferMaximumSize()
487 return doubleBufferMaximumSize;
491 * Set the value of the {@link #doubleBufferMaximumSize} property.
493 * @param size The new value of the property
495 * @see #getDoubleBufferMaximumSize
497 public void setDoubleBufferMaximumSize(Dimension size)
499 doubleBufferMaximumSize = size;
503 * Set the value of the {@link #doubleBufferingEnabled} property.
505 * @param buffer The new value of the property
507 * @see #getDoubleBufferingEnabled
509 public void setDoubleBufferingEnabled(boolean buffer)
511 doubleBufferingEnabled = buffer;
515 * Get the value of the {@link #doubleBufferingEnabled} property.
517 * @return The current value of the property
519 * @see #setDoubleBufferingEnabled
521 public boolean isDoubleBufferingEnabled()
523 return doubleBufferingEnabled;
526 public String toString()
528 return "RepaintManager";