1 /* 2 * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.swing.plaf; 27 28 import javax.swing.JComponent; 29 import javax.swing.SwingUtilities; 30 import javax.accessibility.Accessible; 31 32 import java.awt.Component; 33 import java.awt.Container; 34 import java.awt.Dimension; 35 import java.awt.Graphics; 36 import java.awt.Insets; 37 38 39 /** 40 * The base class for all UI delegate objects in the Swing pluggable 41 * look and feel architecture. The UI delegate object for a Swing 42 * component is responsible for implementing the aspects of the 43 * component that depend on the look and feel. 44 * The <code>JComponent</code> class 45 * invokes methods from this class in order to delegate operations 46 * (painting, layout calculations, etc.) that may vary depending on the 47 * look and feel installed. <b>Client programs should not invoke methods 48 * on this class directly.</b> 49 * 50 * @see javax.swing.JComponent 51 * @see javax.swing.UIManager 52 * 53 */ 54 public abstract class ComponentUI { 55 /** 56 * Sole constructor. (For invocation by subclass constructors, 57 * typically implicit.) 58 */ 59 public ComponentUI() { 60 } 61 62 /** 63 * Configures the specified component appropriately for the look and feel. 64 * This method is invoked when the <code>ComponentUI</code> instance is being installed 65 * as the UI delegate on the specified component. This method should 66 * completely configure the component for the look and feel, 67 * including the following: 68 * <ol> 69 * <li>Install default property values for color, fonts, borders, 70 * icons, opacity, etc. on the component. Whenever possible, 71 * property values initialized by the client program should <i>not</i> 72 * be overridden. 73 * <li>Install a <code>LayoutManager</code> on the component if necessary. 74 * <li>Create/add any required sub-components to the component. 75 * <li>Create/install event listeners on the component. 76 * <li>Create/install a <code>PropertyChangeListener</code> on the component in order 77 * to detect and respond to component property changes appropriately. 78 * <li>Install keyboard UI (mnemonics, traversal, etc.) on the component. 79 * <li>Initialize any appropriate instance data. 80 * </ol> 81 * @param c the component where this UI delegate is being installed 82 * 83 * @see #uninstallUI 84 * @see javax.swing.JComponent#setUI 85 * @see javax.swing.JComponent#updateUI 86 */ 87 public void installUI(JComponent c) { 88 } 89 90 /** 91 * Reverses configuration which was done on the specified component during 92 * <code>installUI</code>. This method is invoked when this 93 * <code>UIComponent</code> instance is being removed as the UI delegate 94 * for the specified component. This method should undo the 95 * configuration performed in <code>installUI</code>, being careful to 96 * leave the <code>JComponent</code> instance in a clean state (no 97 * extraneous listeners, look-and-feel-specific property objects, etc.). 98 * This should include the following: 99 * <ol> 100 * <li>Remove any UI-set borders from the component. 101 * <li>Remove any UI-set layout managers on the component. 102 * <li>Remove any UI-added sub-components from the component. 103 * <li>Remove any UI-added event/property listeners from the component. 104 * <li>Remove any UI-installed keyboard UI from the component. 105 * <li>Nullify any allocated instance data objects to allow for GC. 106 * </ol> 107 * @param c the component from which this UI delegate is being removed; 108 * this argument is often ignored, 109 * but might be used if the UI object is stateless 110 * and shared by multiple components 111 * 112 * @see #installUI 113 * @see javax.swing.JComponent#updateUI 114 */ 115 public void uninstallUI(JComponent c) { 116 } 117 118 /** 119 * Paints the specified component appropriately for the look and feel. 120 * This method is invoked from the <code>ComponentUI.update</code> method when 121 * the specified component is being painted. Subclasses should override 122 * this method and use the specified <code>Graphics</code> object to 123 * render the content of the component. 124 * 125 * @param g the <code>Graphics</code> context in which to paint 126 * @param c the component being painted; 127 * this argument is often ignored, 128 * but might be used if the UI object is stateless 129 * and shared by multiple components 130 * 131 * @see #update 132 */ 133 public void paint(Graphics g, JComponent c) { 134 } 135 136 /** 137 * Notifies this UI delegate that it is time to paint the specified 138 * component. This method is invoked by <code>JComponent</code> 139 * when the specified component is being painted. 140 * 141 * <p>By default this method fills the specified component with 142 * its background color if its {@code opaque} property is {@code true}, 143 * and then immediately calls {@code paint}. In general this method need 144 * not be overridden by subclasses; all look-and-feel rendering code should 145 * reside in the {@code paint} method. 146 * 147 * @param g the <code>Graphics</code> context in which to paint 148 * @param c the component being painted; 149 * this argument is often ignored, 150 * but might be used if the UI object is stateless 151 * and shared by multiple components 152 * 153 * @see #paint 154 * @see javax.swing.JComponent#paintComponent 155 */ 156 public void update(Graphics g, JComponent c) { 157 if (c.isOpaque()) { 158 g.setColor(c.getBackground()); 159 g.fillRect(0, 0, c.getWidth(),c.getHeight()); 160 } 161 paint(g, c); 162 } 163 164 /** 165 * Returns the specified component's preferred size appropriate for 166 * the look and feel. If <code>null</code> is returned, the preferred 167 * size will be calculated by the component's layout manager instead 168 * (this is the preferred approach for any component with a specific 169 * layout manager installed). The default implementation of this 170 * method returns <code>null</code>. 171 * 172 * @param c the component whose preferred size is being queried; 173 * this argument is often ignored, 174 * but might be used if the UI object is stateless 175 * and shared by multiple components 176 * @return a {@code Dimension} object containing given component's preferred 177 * size appropriate for the look and feel 178 * @see javax.swing.JComponent#getPreferredSize 179 * @see java.awt.LayoutManager#preferredLayoutSize 180 */ 181 public Dimension getPreferredSize(JComponent c) { 182 return null; 183 } 184 185 /** 186 * Returns the specified component's minimum size appropriate for 187 * the look and feel. If <code>null</code> is returned, the minimum 188 * size will be calculated by the component's layout manager instead 189 * (this is the preferred approach for any component with a specific 190 * layout manager installed). The default implementation of this 191 * method invokes <code>getPreferredSize</code> and returns that value. 192 * 193 * @param c the component whose minimum size is being queried; 194 * this argument is often ignored, 195 * but might be used if the UI object is stateless 196 * and shared by multiple components 197 * 198 * @return a <code>Dimension</code> object or <code>null</code> 199 * 200 * @see javax.swing.JComponent#getMinimumSize 201 * @see java.awt.LayoutManager#minimumLayoutSize 202 * @see #getPreferredSize 203 */ 204 public Dimension getMinimumSize(JComponent c) { 205 return getPreferredSize(c); 206 } 207 208 /** 209 * Returns the specified component's maximum size appropriate for 210 * the look and feel. If <code>null</code> is returned, the maximum 211 * size will be calculated by the component's layout manager instead 212 * (this is the preferred approach for any component with a specific 213 * layout manager installed). The default implementation of this 214 * method invokes <code>getPreferredSize</code> and returns that value. 215 * 216 * @param c the component whose maximum size is being queried; 217 * this argument is often ignored, 218 * but might be used if the UI object is stateless 219 * and shared by multiple components 220 * @return a <code>Dimension</code> object or <code>null</code> 221 * 222 * @see javax.swing.JComponent#getMaximumSize 223 * @see java.awt.LayoutManager2#maximumLayoutSize 224 */ 225 public Dimension getMaximumSize(JComponent c) { 226 return getPreferredSize(c); 227 } 228 229 /** 230 * Returns <code>true</code> if the specified <i>x,y</i> location is 231 * contained within the look and feel's defined shape of the specified 232 * component. <code>x</code> and <code>y</code> are defined to be relative 233 * to the coordinate system of the specified component. Although 234 * a component's <code>bounds</code> is constrained to a rectangle, 235 * this method provides the means for defining a non-rectangular 236 * shape within those bounds for the purpose of hit detection. 237 * 238 * @param c the component where the <i>x,y</i> location is being queried; 239 * this argument is often ignored, 240 * but might be used if the UI object is stateless 241 * and shared by multiple components 242 * @param x the <i>x</i> coordinate of the point 243 * @param y the <i>y</i> coordinate of the point 244 * @return {@code true} if the specified {@code x,y} location is contained 245 * within the look and feel's defined shape for the given component 246 * @see javax.swing.JComponent#contains 247 * @see java.awt.Component#contains 248 */ 249 @SuppressWarnings("deprecation") 250 public boolean contains(JComponent c, int x, int y) { 251 return c.inside(x, y); 252 } 253 254 /** 255 * Returns an instance of the UI delegate for the specified component. 256 * Each subclass must provide its own static <code>createUI</code> 257 * method that returns an instance of that UI delegate subclass. 258 * If the UI delegate subclass is stateless, it may return an instance 259 * that is shared by multiple components. If the UI delegate is 260 * stateful, then it should return a new instance per component. 261 * The default implementation of this method throws an error, as it 262 * should never be invoked. 263 * 264 * @param c a {@code JComponent} for which to create a UI delegate 265 * @return a {@code ComponentUI} object for {@code c} 266 */ 267 public static ComponentUI createUI(JComponent c) { 268 throw new Error("ComponentUI.createUI not implemented."); 269 } 270 271 /** 272 * Returns the baseline. The baseline is measured from the top of 273 * the component. This method is primarily meant for 274 * <code>LayoutManager</code>s to align components along their 275 * baseline. A return value less than 0 indicates this component 276 * does not have a reasonable baseline and that 277 * <code>LayoutManager</code>s should not align this component on 278 * its baseline. 279 * <p> 280 * This method returns -1. Subclasses that have a meaningful baseline 281 * should override appropriately. 282 * 283 * @param c <code>JComponent</code> baseline is being requested for 284 * @param width the width to get the baseline for 285 * @param height the height to get the baseline for 286 * @throws NullPointerException if <code>c</code> is <code>null</code> 287 * @throws IllegalArgumentException if width or height is < 0 288 * @return baseline or a value < 0 indicating there is no reasonable 289 * baseline 290 * @see javax.swing.JComponent#getBaseline(int,int) 291 * @since 1.6 292 */ 293 public int getBaseline(JComponent c, int width, int height) { 294 if (c == null) { 295 throw new NullPointerException("Component must be non-null"); 296 } 297 if (width < 0 || height < 0) { 298 throw new IllegalArgumentException( 299 "Width and height must be >= 0"); 300 } 301 return -1; 302 } 303 304 /** 305 * Returns an enum indicating how the baseline of the component 306 * changes as the size changes. This method is primarily meant for 307 * layout managers and GUI builders. 308 * <p> 309 * This method returns <code>BaselineResizeBehavior.OTHER</code>. 310 * Subclasses that support a baseline should override appropriately. 311 * 312 * @param c <code>JComponent</code> to return baseline resize behavior for 313 * @return an enum indicating how the baseline changes as the component 314 * size changes 315 * @throws NullPointerException if <code>c</code> is <code>null</code> 316 * @see javax.swing.JComponent#getBaseline(int, int) 317 * @since 1.6 318 */ 319 public Component.BaselineResizeBehavior getBaselineResizeBehavior( 320 JComponent c) { 321 if (c == null) { 322 throw new NullPointerException("Component must be non-null"); 323 } 324 return Component.BaselineResizeBehavior.OTHER; 325 } 326 327 /** 328 * Returns the number of accessible children in the object. If all 329 * of the children of this object implement <code>Accessible</code>, 330 * this 331 * method should return the number of children of this object. 332 * UIs might wish to override this if they present areas on the 333 * screen that can be viewed as components, but actual components 334 * are not used for presenting those areas. 335 * 336 * Note: As of v1.3, it is recommended that developers call 337 * <code>Component.AccessibleAWTComponent.getAccessibleChildrenCount()</code> instead 338 * of this method. 339 * 340 * @param c {@code JComponent} for which to get count of accessible children 341 * @return the number of accessible children in the object 342 * @see #getAccessibleChild 343 */ 344 public int getAccessibleChildrenCount(JComponent c) { 345 return SwingUtilities.getAccessibleChildrenCount(c); 346 } 347 348 /** 349 * Returns the <code>i</code>th <code>Accessible</code> child of the object. 350 * UIs might need to override this if they present areas on the 351 * screen that can be viewed as components, but actual components 352 * are not used for presenting those areas. 353 * 354 * <p> 355 * 356 * Note: As of v1.3, it is recommended that developers call 357 * <code>Component.AccessibleAWTComponent.getAccessibleChild()</code> instead of 358 * this method. 359 * 360 * @param c a {@code JComponent} for which to get a child object 361 * @param i zero-based index of child 362 * @return the <code>i</code>th <code>Accessible</code> child of the object 363 * @see #getAccessibleChildrenCount 364 */ 365 public Accessible getAccessibleChild(JComponent c, int i) { 366 return SwingUtilities.getAccessibleChild(c, i); 367 } 368 }