Source for javax.swing.plaf.ComponentUI

   1: /* ComponentUI.java --
   2:    Copyright (C) 2002, 2003, 2004  Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   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)
   9: any later version.
  10: 
  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.
  15: 
  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., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  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
  24: combination.
  25: 
  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. */
  37: 
  38: 
  39: package javax.swing.plaf;
  40: 
  41: import java.awt.Color;
  42: import java.awt.Dimension;
  43: import java.awt.Graphics;
  44: import java.awt.Rectangle;
  45: 
  46: import javax.accessibility.Accessible;
  47: import javax.swing.JComponent;
  48: 
  49: /**
  50:  * The abstract base class for all delegates that provide the
  51:  * pluggable look and feel for Swing components. User applications
  52:  * should not need to access this class; it is internal to Swing
  53:  * and the look-and-feel implementations.
  54:  *
  55:  * <p><img src="doc-files/ComponentUI-1.png" width="700" height="550"
  56:  * alt="[UML diagram illustrating the architecture for pluggable
  57:  * look and feels]" /></p>
  58:  *
  59:  * <p>Components such as {@link javax.swing.JSlider} do not directly
  60:  * implement operations related to the look and feel of the user
  61:  * interface, such as painting or layout. Instead, they use a delegate
  62:  * object for all such tasks. In the case of <code>JSlider</code>, the
  63:  * user interface would be provided by some concrete subclass of
  64:  * {@link javax.swing.plaf.SliderUI}.
  65:  *
  66:  * <p>Soon after its creation, a <code>ComponentUI</code> will be sent
  67:  * an {@link #installUI} message. The <code>ComponentUI</code> will
  68:  * react by setting properties such as the border or the background
  69:  * color of the <code>JComponent</code> for which it provides its
  70:  * services. Soon before the end of its lifecycle, the
  71:  * <code>ComponentUI</code> will receive an {@link #uninstallUI}
  72:  * message, at which time the <code>ComponentUI</code> is expected to
  73:  * undo any changes.</p>
  74:  *
  75:  * <p>Note that the <code>ui</code> of a <code>JComponent</code>
  76:  * changes whenever the user switches between look and feels.  For
  77:  * example, the <code>ui</code> property of a <code>JSlider</code>
  78:  * could change from an instance of <code>MetalSliderUI</code> to an
  79:  * instance of <code>FooSliderUI</code>. This switch can happen at any
  80:  * time, but it will always be performed from inside the Swing thread.</p>
  81:  *
  82:  * @author Sascha Brawer (brawer@dandelis.ch)
  83:  */
  84: public abstract class ComponentUI 
  85: {
  86:   /**
  87:    * Constructs a new UI delegate.
  88:    */
  89:   public ComponentUI()
  90:   {
  91:     // Nothing to do here.
  92:   }
  93:   
  94:   
  95:   /**
  96:    * Sets up the specified component so it conforms the the design
  97:    * guidelines of the implemented look and feel. When the look and
  98:    * feel changes, a <code>ComponentUI</code> delegate is created.
  99:    * The delegate object then receives an <code>installUI</code>
 100:    * message.
 101:    *
 102:    * <p>This method should perform the following tasks:</p>
 103:    *
 104:    * <ul>
 105:    * <li>Set visual properties such as borders, fonts, colors, or
 106:    *     icons. However, no change should be performed for those
 107:    *     properties whose values have been directly set by the client
 108:    *     application. To allow the distinction, LookAndFeels are expected
 109:    *     to use values that implement the {@link UIResource} marker
 110:    *     interface, such as {@link BorderUIResource} or {@link
 111:    *     ColorUIResource}.</li>
 112:    * <li>If necessary, install a {@link java.awt.LayoutManager}.</li>
 113:    * <li>Embed custom sub-components. For instance, the UI delegate
 114:    *     for a {@link javax.swing.JSplitPane} might install a special
 115:    *     component for the divider.</li>
 116:    * <li>Register event listeners.</li>
 117:    * <li>Set up properties related to keyborad navigation, such as
 118:    *     mnemonics or focus traversal policies.</li>
 119:    * </ul>
 120:    *
 121:    * @param c the component for which this delegate will provide
 122:    *        services.
 123:    *
 124:    * @see #uninstallUI
 125:    * @see javax.swing.JComponent#setUI
 126:    * @see javax.swing.JComponent#updateUI
 127:    */
 128:   public void installUI(JComponent c)
 129:   {
 130:     // The default implementation does not change any properties.
 131:   }
 132: 
 133: 
 134:   /**
 135:    * Puts the specified component into the state it had before
 136:    * {@link #installUI} was called.
 137:    *
 138:    * @param c the component for which this delegate has provided
 139:    *        services.
 140:    *
 141:    * @see #installUI
 142:    * @see javax.swing.JComponent#setUI
 143:    * @see javax.swing.JComponent#updateUI
 144:    */
 145:   public void uninstallUI(JComponent c)
 146:   {
 147:     // The default implementation does not change any properties.
 148:   }
 149:   
 150:   
 151:   /**
 152:    * Paints the component according to the design guidelines
 153:    * of the look and feel. Most subclasses will want to override
 154:    * this method.
 155:    *
 156:    * @param g the graphics for painting.
 157:    *
 158:    * @param c the component for which this delegate performs
 159:    *          services.
 160:    */
 161:   public void paint(Graphics g, JComponent c)
 162:   {
 163:     // Nothing is done here. This method is meant to be overridden by
 164:     // subclasses.
 165:   }
 166:   
 167:   
 168:   /**
 169:    * Fills the specified component with its background color
 170:    * (unless the <code>opaque</code> property is <code>false</code>)
 171:    * before calling {@link #paint}.
 172:    *
 173:    * <p>It is unlikely that a subclass needs to override this method.
 174:    * The actual rendering should be performed by the {@link #paint}
 175:    * method.
 176:    *
 177:    * @param g the graphics for painting.
 178:    *
 179:    * @param c the component for which this delegate performs
 180:    *          services.
 181:    *
 182:    * @see #paint
 183:    * @see javax.swing.JComponent#paintComponent
 184:    */
 185:   public void update(Graphics g, JComponent c)
 186:   {
 187:     if (c.isOpaque())
 188:     {
 189:       Color oldColor = g.getColor();
 190:       g.setColor(c.getBackground());
 191:       g.fillRect(0, 0, c.getWidth(), c.getHeight());
 192:       g.setColor(oldColor);
 193:     }
 194:     paint(g, c);
 195:   }
 196:    
 197:   /**
 198:    * Determines the preferred size of a component. The default
 199:    * implementation returns <code>null</code>, which means that
 200:    * <code>c</code>&#x2019;s layout manager should be asked to
 201:    * calculate the preferred size.
 202:    *
 203:    * @param c the component for which this delegate performs services.
 204:    *
 205:    * @return the preferred size, or <code>null</code> to indicate that
 206:    *         <code>c</code>&#x2019;s layout manager should be asked
 207:    *         for the preferred size.
 208:    */
 209:   public Dimension getPreferredSize(JComponent c)
 210:   {
 211:     return null;
 212:   }
 213:   
 214:   
 215:   /**
 216:    * Determines the minimum size of a component. The default
 217:    * implementation calls {@link #getPreferredSize}, but subclasses
 218:    * might want to override this.
 219:    *
 220:    * @param c the component for which this delegate performs services.
 221:    *
 222:    * @return the minimum size, or <code>null</code> to indicate that
 223:    *         <code>c</code>&#x2019;s layout manager should be asked
 224:    *         to calculate the minimum size.
 225:    */
 226:   public Dimension getMinimumSize(JComponent c)
 227:   {
 228:     return getPreferredSize(c);
 229:   }
 230: 
 231: 
 232:   /**
 233:    * Determines the maximum size of a component. The default
 234:    * implementation calls {@link #getPreferredSize}, but subclasses
 235:    * might want to override this.
 236:    *
 237:    * @param c the component for which this delegate performs services.
 238:    *
 239:    * @return the maximum size, or <code>null</code> to indicate that
 240:    *         <code>c</code>&#x2019;s layout manager should be asked
 241:    *         to calculate the maximum size.
 242:    */
 243:   public Dimension getMaximumSize(JComponent c)
 244:   {
 245:     return getPreferredSize(c);
 246:   }
 247: 
 248: 
 249:   /**
 250:    * Determines whether a click into the component at a specified
 251:    * location is considered as having hit the component. The default
 252:    * implementation checks whether the point falls into the
 253:    * component&#x2019;s bounding rectangle. Some subclasses might want
 254:    * to override this, for example in the case of a rounded button.
 255:    *
 256:    * @param c the component for which this delegate performs services.
 257:    *
 258:    * @param x the x coordinate of the point, relative to the local
 259:    *        coordinate system of the component. Zero would be be
 260:    *        component&#x2019;s left edge, irrespective of the location
 261:    *        inside its parent.
 262:    *
 263:    * @param y the y coordinate of the point, relative to the local
 264:    *        coordinate system of the component. Zero would be be
 265:    *        component&#x2019;s top edge, irrespective of the location
 266:    *        inside its parent.
 267:    */
 268:   public boolean contains(JComponent c, int x, int y)
 269:   {    
 270:     /* JComponent.contains calls the ui delegate for hit
 271:      * testing. Therefore, endless mutual recursion would result if we
 272:      * called c.contains(x, y) here.
 273:      *
 274:      * The previous Classpath implementation called the deprecated
 275:      * method java.awt.Component.inside. In the Sun implementation, it
 276:      * can be observed that inside, other than contains, does not call
 277:      * the ui delegate.  But that inside() behaves different to
 278:      * contains() clearly is in violation of the method contract, and
 279:      * it is not something that a good implementation should rely upon
 280:      * -- even if Classpath ends up being forced to replicate this
 281:      * apparent bug of the Sun implementation.
 282:      */
 283:     return (x >= 0) && (x < c.getWidth())
 284:       && (y >= 0) && (y < c.getHeight());
 285:   }
 286:   
 287:   
 288:   /**
 289:    * Creates a delegate object for the specified component.  Users
 290:    * should use the <code>createUI</code> method of a suitable
 291:    * subclass. The implementation of <code>ComponentUI</code>
 292:    * always throws an error.
 293:    *
 294:    * @param c the component for which a UI delegate is requested.
 295:    */
 296:   public static ComponentUI createUI(JComponent c)
 297:   {
 298:     throw new Error(
 299:       "javax.swing.plaf.ComponentUI does not implement createUI; call "
 300:       + "createUI on a subclass.");
 301:   }
 302:   
 303: 
 304:   /**
 305:    * Counts the number of accessible children in the component.  The
 306:    * default implementation delegates the inquiry to the {@link
 307:    * javax.accessibility.AccessibleContext} of <code>c</code>.
 308:    *
 309:    * @param c the component whose accessible children
 310:    *        are to be counted.
 311:    */
 312:   public int getAccessibleChildrenCount(JComponent c)
 313:   {
 314:     return c.getAccessibleContext().getAccessibleChildrenCount();
 315:   }
 316: 
 317: 
 318:   /**
 319:    * Returns the specified accessible child of the component. The
 320:    * default implementation delegates the inquiry to the {@link
 321:    * javax.accessibility.AccessibleContext} of <code>c</code>.
 322:    *
 323:    * @param i the index of the accessible child, starting at zero.
 324:    *
 325:    * @param c the component whose <code>i</code>-th accessible child
 326:    *        is requested.
 327:    */
 328:   public Accessible getAccessibleChild(JComponent c, int i)
 329:   {
 330:     return c.getAccessibleContext().getAccessibleChild(i);
 331:   }
 332: }