001/* ComponentUI.java -- 002 Copyright (C) 2002, 2003, 2004 Free Software Foundation, Inc. 003 004This file is part of GNU Classpath. 005 006GNU Classpath is free software; you can redistribute it and/or modify 007it under the terms of the GNU General Public License as published by 008the Free Software Foundation; either version 2, or (at your option) 009any later version. 010 011GNU Classpath is distributed in the hope that it will be useful, but 012WITHOUT ANY WARRANTY; without even the implied warranty of 013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014General Public License for more details. 015 016You should have received a copy of the GNU General Public License 017along with GNU Classpath; see the file COPYING. If not, write to the 018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 01902110-1301 USA. 020 021Linking this library statically or dynamically with other modules is 022making a combined work based on this library. Thus, the terms and 023conditions of the GNU General Public License cover the whole 024combination. 025 026As a special exception, the copyright holders of this library give you 027permission to link this library with independent modules to produce an 028executable, regardless of the license terms of these independent 029modules, and to copy and distribute the resulting executable under 030terms of your choice, provided that you also meet, for each linked 031independent module, the terms and conditions of the license of that 032module. An independent module is a module which is not derived from 033or based on this library. If you modify this library, you may extend 034this exception to your version of the library, but you are not 035obligated to do so. If you do not wish to do so, delete this 036exception statement from your version. */ 037 038 039package javax.swing.plaf; 040 041import java.awt.Color; 042import java.awt.Dimension; 043import java.awt.Graphics; 044 045import javax.accessibility.Accessible; 046import javax.swing.JComponent; 047 048/** 049 * The abstract base class for all delegates that provide the 050 * pluggable look and feel for Swing components. User applications 051 * should not need to access this class; it is internal to Swing 052 * and the look-and-feel implementations. 053 * 054 * <p><img src="doc-files/ComponentUI-1.png" width="700" height="550" 055 * alt="[UML diagram illustrating the architecture for pluggable 056 * look and feels]" /></p> 057 * 058 * <p>Components such as {@link javax.swing.JSlider} do not directly 059 * implement operations related to the look and feel of the user 060 * interface, such as painting or layout. Instead, they use a delegate 061 * object for all such tasks. In the case of <code>JSlider</code>, the 062 * user interface would be provided by some concrete subclass of 063 * {@link javax.swing.plaf.SliderUI}. 064 * 065 * <p>Soon after its creation, a <code>ComponentUI</code> will be sent 066 * an {@link #installUI} message. The <code>ComponentUI</code> will 067 * react by setting properties such as the border or the background 068 * color of the <code>JComponent</code> for which it provides its 069 * services. Soon before the end of its lifecycle, the 070 * <code>ComponentUI</code> will receive an {@link #uninstallUI} 071 * message, at which time the <code>ComponentUI</code> is expected to 072 * undo any changes.</p> 073 * 074 * <p>Note that the <code>ui</code> of a <code>JComponent</code> 075 * changes whenever the user switches between look and feels. For 076 * example, the <code>ui</code> property of a <code>JSlider</code> 077 * could change from an instance of <code>MetalSliderUI</code> to an 078 * instance of <code>FooSliderUI</code>. This switch can happen at any 079 * time, but it will always be performed from inside the Swing thread.</p> 080 * 081 * @author Sascha Brawer (brawer@dandelis.ch) 082 */ 083public abstract class ComponentUI 084{ 085 /** 086 * Constructs a new UI delegate. 087 */ 088 public ComponentUI() 089 { 090 // Nothing to do here. 091 } 092 093 094 /** 095 * Sets up the specified component so it conforms the the design 096 * guidelines of the implemented look and feel. When the look and 097 * feel changes, a <code>ComponentUI</code> delegate is created. 098 * The delegate object then receives an <code>installUI</code> 099 * message. 100 * 101 * <p>This method should perform the following tasks:</p> 102 * 103 * <ul> 104 * <li>Set visual properties such as borders, fonts, colors, or 105 * icons. However, no change should be performed for those 106 * properties whose values have been directly set by the client 107 * application. To allow the distinction, LookAndFeels are expected 108 * to use values that implement the {@link UIResource} marker 109 * interface, such as {@link BorderUIResource} or {@link 110 * ColorUIResource}.</li> 111 * <li>If necessary, install a {@link java.awt.LayoutManager}.</li> 112 * <li>Embed custom sub-components. For instance, the UI delegate 113 * for a {@link javax.swing.JSplitPane} might install a special 114 * component for the divider.</li> 115 * <li>Register event listeners.</li> 116 * <li>Set up properties related to keyborad navigation, such as 117 * mnemonics or focus traversal policies.</li> 118 * </ul> 119 * 120 * @param c the component for which this delegate will provide 121 * services. 122 * 123 * @see #uninstallUI 124 * @see javax.swing.JComponent#setUI 125 * @see javax.swing.JComponent#updateUI 126 */ 127 public void installUI(JComponent c) 128 { 129 // The default implementation does not change any properties. 130 } 131 132 133 /** 134 * Puts the specified component into the state it had before 135 * {@link #installUI} was called. 136 * 137 * @param c the component for which this delegate has provided 138 * services. 139 * 140 * @see #installUI 141 * @see javax.swing.JComponent#setUI 142 * @see javax.swing.JComponent#updateUI 143 */ 144 public void uninstallUI(JComponent c) 145 { 146 // The default implementation does not change any properties. 147 } 148 149 150 /** 151 * Paints the component according to the design guidelines 152 * of the look and feel. Most subclasses will want to override 153 * this method. 154 * 155 * @param g the graphics for painting. 156 * 157 * @param c the component for which this delegate performs 158 * services. 159 */ 160 public void paint(Graphics g, JComponent c) 161 { 162 // Nothing is done here. This method is meant to be overridden by 163 // subclasses. 164 } 165 166 167 /** 168 * Fills the specified component with its background color 169 * (unless the <code>opaque</code> property is <code>false</code>) 170 * before calling {@link #paint}. 171 * 172 * <p>It is unlikely that a subclass needs to override this method. 173 * The actual rendering should be performed by the {@link #paint} 174 * method. 175 * 176 * @param g the graphics for painting. 177 * 178 * @param c the component for which this delegate performs 179 * services. 180 * 181 * @see #paint 182 * @see javax.swing.JComponent#paintComponent 183 */ 184 public void update(Graphics g, JComponent c) 185 { 186 if (c.isOpaque()) 187 { 188 Color oldColor = g.getColor(); 189 g.setColor(c.getBackground()); 190 g.fillRect(0, 0, c.getWidth(), c.getHeight()); 191 g.setColor(oldColor); 192 } 193 paint(g, c); 194 } 195 196 /** 197 * Determines the preferred size of a component. The default 198 * implementation returns <code>null</code>, which means that 199 * <code>c</code>’s layout manager should be asked to 200 * calculate the preferred size. 201 * 202 * @param c the component for which this delegate performs services. 203 * 204 * @return the preferred size, or <code>null</code> to indicate that 205 * <code>c</code>’s layout manager should be asked 206 * for the preferred size. 207 */ 208 public Dimension getPreferredSize(JComponent c) 209 { 210 return null; 211 } 212 213 214 /** 215 * Determines the minimum size of a component. The default 216 * implementation calls {@link #getPreferredSize}, but subclasses 217 * might want to override this. 218 * 219 * @param c the component for which this delegate performs services. 220 * 221 * @return the minimum size, or <code>null</code> to indicate that 222 * <code>c</code>’s layout manager should be asked 223 * to calculate the minimum size. 224 */ 225 public Dimension getMinimumSize(JComponent c) 226 { 227 return getPreferredSize(c); 228 } 229 230 231 /** 232 * Determines the maximum size of a component. The default 233 * implementation calls {@link #getPreferredSize}, but subclasses 234 * might want to override this. 235 * 236 * @param c the component for which this delegate performs services. 237 * 238 * @return the maximum size, or <code>null</code> to indicate that 239 * <code>c</code>’s layout manager should be asked 240 * to calculate the maximum size. 241 */ 242 public Dimension getMaximumSize(JComponent c) 243 { 244 return getPreferredSize(c); 245 } 246 247 248 /** 249 * Determines whether a click into the component at a specified 250 * location is considered as having hit the component. The default 251 * implementation checks whether the point falls into the 252 * component’s bounding rectangle. Some subclasses might want 253 * to override this, for example in the case of a rounded button. 254 * 255 * @param c the component for which this delegate performs services. 256 * 257 * @param x the x coordinate of the point, relative to the local 258 * coordinate system of the component. Zero would be be 259 * component’s left edge, irrespective of the location 260 * inside its parent. 261 * 262 * @param y the y coordinate of the point, relative to the local 263 * coordinate system of the component. Zero would be be 264 * component’s top edge, irrespective of the location 265 * inside its parent. 266 */ 267 public boolean contains(JComponent c, int x, int y) 268 { 269 /* JComponent.contains calls the ui delegate for hit 270 * testing. Therefore, endless mutual recursion would result if we 271 * called c.contains(x, y) here. 272 * 273 * The previous Classpath implementation called the deprecated 274 * method java.awt.Component.inside. In the Sun implementation, it 275 * can be observed that inside, other than contains, does not call 276 * the ui delegate. But that inside() behaves different to 277 * contains() clearly is in violation of the method contract, and 278 * it is not something that a good implementation should rely upon 279 * -- even if Classpath ends up being forced to replicate this 280 * apparent bug of the Sun implementation. 281 */ 282 return (x >= 0) && (x < c.getWidth()) 283 && (y >= 0) && (y < c.getHeight()); 284 } 285 286 287 /** 288 * Creates a delegate object for the specified component. Users 289 * should use the <code>createUI</code> method of a suitable 290 * subclass. The implementation of <code>ComponentUI</code> 291 * always throws an error. 292 * 293 * @param c the component for which a UI delegate is requested. 294 */ 295 public static ComponentUI createUI(JComponent c) 296 { 297 throw new Error( 298 "javax.swing.plaf.ComponentUI does not implement createUI; call " 299 + "createUI on a subclass."); 300 } 301 302 303 /** 304 * Counts the number of accessible children in the component. The 305 * default implementation delegates the inquiry to the {@link 306 * javax.accessibility.AccessibleContext} of <code>c</code>. 307 * 308 * @param c the component whose accessible children 309 * are to be counted. 310 */ 311 public int getAccessibleChildrenCount(JComponent c) 312 { 313 return c.getAccessibleContext().getAccessibleChildrenCount(); 314 } 315 316 317 /** 318 * Returns the specified accessible child of the component. The 319 * default implementation delegates the inquiry to the {@link 320 * javax.accessibility.AccessibleContext} of <code>c</code>. 321 * 322 * @param i the index of the accessible child, starting at zero. 323 * 324 * @param c the component whose <code>i</code>-th accessible child 325 * is requested. 326 */ 327 public Accessible getAccessibleChild(JComponent c, int i) 328 { 329 return c.getAccessibleContext().getAccessibleChild(i); 330 } 331}