001    /* ComponentUI.java --
002       Copyright (C) 2002, 2003, 2004  Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package javax.swing.plaf;
040    
041    import java.awt.Color;
042    import java.awt.Dimension;
043    import java.awt.Graphics;
044    
045    import javax.accessibility.Accessible;
046    import 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     */
083    public 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>&#x2019;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>&#x2019;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>&#x2019;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>&#x2019;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&#x2019;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&#x2019;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&#x2019;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    }