This patch (committed) fixes a few problems in the API docs for
LookAndFeel.java:
2006-03-14 David Gilbert <[EMAIL PROTECTED]>
* javax/swing/LookAndFeel.java: Updated API docs.
Regards,
Dave
Index: javax/swing/LookAndFeel.java
===================================================================
RCS file: /sources/classpath/classpath/javax/swing/LookAndFeel.java,v
retrieving revision 1.16
diff -u -r1.16 LookAndFeel.java
--- javax/swing/LookAndFeel.java 6 Dec 2005 17:34:43 -0000 1.16
+++ javax/swing/LookAndFeel.java 14 Mar 2006 15:08:34 -0000
@@ -1,5 +1,5 @@
/* LookAndFeel.java --
- Copyright (C) 2002, 2004, 2005 Free Software Foundation, Inc.
+ Copyright (C) 2002, 2004, 2005, 2006, Free Software Foundation, Inc.
This file is part of GNU Classpath.
@@ -49,15 +49,25 @@
import javax.swing.plaf.IconUIResource;
import javax.swing.plaf.InputMapUIResource;
import javax.swing.plaf.UIResource;
+import javax.swing.plaf.metal.MetalLookAndFeel;
import javax.swing.text.JTextComponent;
+/**
+ * A <i>look-and-feel</i> controls most aspects of the appearance and
+ * operation of user interface components in <code>javax.swing</code>. A
+ * cross-platform look-and-feel (the [EMAIL PROTECTED] MetalLookAndFeel}) is
provided.
+ *
+ * @see UIManager#getInstalledLookAndFeels()
+ * @see UIManager#setLookAndFeel(LookAndFeel)
+ */
public abstract class LookAndFeel
{
/**
- * This method is called once by UIManager.setLookAndFeel to create
- * the look and feel specific defaults table.
+ * Creates and returns a look-and-feel specific defaults table. This method
+ * is called once by [EMAIL PROTECTED]
UIManager#setLookAndFeel(LookAndFeel)} and
+ * shouldn't be called again (as it creates a large table of defaults).
*
- * @return the UI defaults
+ * @return The UI defaults.
*/
public UIDefaults getDefaults()
{
@@ -71,10 +81,21 @@
*/
public abstract String getDescription();
+ /**
+ * Returns the value of <code>Toolkit.getDefaultToolkit()
+ * .getDesktopProperty(systemPropertyName)</code>, or
+ * <code>fallbackValue</code> if no such property is defined.
+ *
+ * @param systemPropertyName the system property name.
+ * @param fallbackValue the fallback value.
+ *
+ * @return The property value or <code>fallbackValue</code>.
+ */
public static Object getDesktopPropertyValue(String systemPropertyName,
Object fallbackValue)
{
- Object value =
Toolkit.getDefaultToolkit().getDesktopProperty(systemPropertyName);
+ Object value = Toolkit.getDefaultToolkit().getDesktopProperty(
+ systemPropertyName);
return value != null ? value : fallbackValue;
}
@@ -93,11 +114,12 @@
public abstract String getName();
/**
- * Returns true when the Look and Feel supports window decorations,
- * false others. This method returns always false and needs to be overwritten
- * when the derived Look and Feel supports this.
+ * Returns <code>true</code> when the look-and-feel supports window
+ * decorations, and <code>false</code> otherwise. This default implementation
+ * always returns <code>false</code> and needs to be overridden when the
+ * derived look-and-feel supports this.
*
- * @return false
+ * @return <code>false</code>.
*
* @since 1.4
*/
@@ -107,8 +129,11 @@
}
/**
- * UIManager.setLookAndFeel calls this method before the first call
- * (and typically the only call) to getDefaults().
+ * Initializes the look-and-feel. The
+ * [EMAIL PROTECTED] UIManager#setLookAndFeel(LookAndFeel)} method calls
this method
+ * before the first call (and typically the only call) to
+ * [EMAIL PROTECTED] #getDefaults()}. This default implementation does
nothing, but
+ * subclasses can override this behaviour.
*/
public void initialize()
{
@@ -117,9 +142,13 @@
}
/**
- * Convenience method for installing a component's default Border object
- * on the specified component if either the border is currently null
- * or already an instance of UIResource.
+ * Convenience method for installing a component's default [EMAIL PROTECTED]
Border}
+ * object on the specified component if either the border is currently
+ * <code>null</code> or already an instance of [EMAIL PROTECTED]
UIResource}.
+ *
+ * @param c the component (<code>null</code> not permitted).
+ * @param defaultBorderName the border name (for lookup in the UIDefaults
+ * table).
*/
public static void installBorder(JComponent c, String defaultBorderName)
{
@@ -131,6 +160,12 @@
/**
* Convenience method for initializing a component's foreground and
* background color properties with values from the current defaults table.
+ *
+ * @param c the component (<code>null</code> not permitted).
+ * @param defaultBgName the key for the background color in the UIDefaults
+ * table.
+ * @param defaultFgName the key for the foreground color in the UIDefaults
+ * table.
*/
public static void installColors(JComponent c, String defaultBgName,
String defaultFgName)
@@ -147,8 +182,15 @@
}
/**
- * Convenience method for initializing a components foreground background
- * and font properties with values from the current defaults table.
+ * Convenience method for initializing a component's foreground, background
+ * and font properties with values from the current defaults table.
+ *
+ * @param component the component (<code>null</code> not permitted).
+ * @param defaultBgName the key for the background color in the UIDefaults
+ * table.
+ * @param defaultFgName the key for the foreground color in the UIDefaults
+ * table.
+ * @param defaultFontName the key for the font in the UIDefaults table.
*/
public static void installColorsAndFont(JComponent component,
String defaultBgName,
@@ -164,8 +206,10 @@
}
/**
- * Returns <code>true</code> if the look and feel is the "native" look and
- * feel for the current platform, and <code>false</code> otherwise.
+ * Returns <code>true</code> if the look-and-feel is the "native"
+ * look-and-feel for the current platform, and <code>false</code> otherwise.
+ * A native look-and-feel emulates the appearance and behaviour of the
+ * default windowing system on the host operating system.
*
* @return A flag indicating whether or not this is the native look and feel
* for the current platform.
@@ -173,13 +217,13 @@
public abstract boolean isNativeLookAndFeel();
/**
- * Returns <code>true</code> if the look and feel is supported on the
+ * Returns <code>true</code> if the look-and-feel is supported on the
* current operating system, and <code>false</code> otherwise. This
- * mechanism is provided so that it is possible to prevent a look and feel
+ * mechanism is provided so that it is possible to prevent a look-and-feel
* from being used on some operating systems (usually for legal, not
* technical, reasons).
*
- * @return A flag indicating whether or not the look and feel is supported
+ * @return A flag indicating whether or not the look-and-feel is supported
* on the current platform.
*/
public abstract boolean isSupportedLookAndFeel();
@@ -219,6 +263,8 @@
*
* @param c the JComponent associated with the ComponentInputMap
* @param keys the Object array describing the InputMap as above
+ *
+ * @return A new input map.
*/
public static ComponentInputMap makeComponentInputMap(JComponent c,
Object[] keys)
@@ -230,7 +276,13 @@
/**
* Utility method that creates a UIDefaults.LazyValue that creates an
- * ImageIcon UIResource for the specified gifFile filename.
+ * ImageIcon UIResource for the specified gifFile filename.
+ *
+ * @param baseClass the base class for accessing the icon resource.
+ * @param gifFile the file name.
+ *
+ * @return A [EMAIL PROTECTED] UIDefaults.LazyValue} that serves up an
+ * [EMAIL PROTECTED] IconUIResource}.
*/
public static Object makeIcon(Class baseClass, String gifFile)
{
@@ -252,6 +304,8 @@
* ActionMap.
*
* @param keys the Object array describing the InputMap as above
+ *
+ * @return A new input map.
*/
public static InputMap makeInputMap(Object[] keys)
{
@@ -269,7 +323,8 @@
* @param keyBindingList the array of KeyStroke-Action pairs
* @return a JTextComponent.KeyBinding array
*/
- public static JTextComponent.KeyBinding[] makeKeyBindings(Object[]
keyBindingList)
+ public static JTextComponent.KeyBinding[] makeKeyBindings(
+ Object[] keyBindingList)
{
JTextComponent.KeyBinding[] retBindings =
new JTextComponent.KeyBinding[keyBindingList.length / 2];
@@ -280,15 +335,16 @@
stroke = (KeyStroke)keyBindingList[i];
else
stroke = KeyStroke.getKeyStroke((String)keyBindingList[i]);
- retBindings[i/2] = new JTextComponent.KeyBinding(stroke,
(String)keyBindingList[i+1]);
+ retBindings[i/2] = new JTextComponent.KeyBinding(stroke,
+ (String) keyBindingList[i+1]);
}
return retBindings;
}
/**
- * Invoked when the user attempts an invalid operation. The default implement
- * just beeps. Subclasses that wish to change this need to override this
- * method.
+ * Invoked when the user attempts an invalid operation. The default
+ * implementation just beeps. Subclasses that wish to change this need to
+ * override this method.
*
* @param component the component the error occured in
*/
@@ -320,6 +376,8 @@
/**
* Convenience method for un-installing a component's default border on the
* specified component if the border is currently an instance of UIResource.
+ *
+ * @param c the component (<code>null</code> not permitted).
*/
public static void uninstallBorder(JComponent c)
{
