| java.lang.Object javax.swing.LookAndFeel
All known Subclasses: javax.swing.plaf.basic.BasicLookAndFeel, javax.swing.plaf.multi.MultiLookAndFeel,
LookAndFeel | abstract public class LookAndFeel (Code) | | LookAndFeel , as the name implies, encapsulates a look and
feel. Beyond installing a look and feel most developers never need to
interact directly with
LookAndFeel . In general only developers
creating a custom look and feel need to concern themselves with this class.
Swing is built upon the foundation that each
JComponent subclass has an implementation of a specific
ComponentUI subclass. The
ComponentUI is often referred to as "the ui",
"component ui", or "look and feel delegate". The
ComponentUI subclass is responsible for providing the look and feel specific
functionality of the component. For example,
JTree requires
an implementation of the
ComponentUI subclass
TreeUI . The implementation of the specific
ComponentUI subclass is provided by the
LookAndFeel . Each
JComponent subclass identifies the
ComponentUI subclass it requires by way of the
JComponent method
getUIClassID .
Each
LookAndFeel implementation must provide
an implementation of the appropriate
ComponentUI subclass by
specifying a value for each of Swing's ui class ids in the
UIDefaults object returned from
getDefaults . For example,
BasicLookAndFeel uses
BasicTreeUI as the concrete
implementation for
TreeUI . This is accomplished by
BasicLookAndFeel providing the key-value pair
"TreeUI"-"javax.swing.plaf.basic.BasicTreeUI" , in the
UIDefaults returned from
getDefaults . Refer to
UIDefaults.getUI(JComponent) for defails on how the implementation
of the
ComponentUI subclass is obtained.
When a
LookAndFeel is installed the
UIManager does
not check that an entry exists for all ui class ids. As such,
random exceptions will occur if the current look and feel has not
provided a value for a particular ui class id and an instance of
the
JComponent subclass is created.
Recommendations for Look and Feels
As noted in
UIManager each
LookAndFeel has the opportunity
to provide a set of defaults that are layered in with developer and
system defaults. Some of Swing's components require the look and feel
to provide a specific set of defaults. These are documented in the
classes that require the specific default.
ComponentUIs and defaults
All
ComponentUIs typically need to set various properties
on the
JComponent the
ComponentUI is providing the
look and feel for. This is typically done when the
ComponentUI is installed on the
JComponent . Setting a
property should only be done if the developer has not set the
property. For non-primitive values it is recommended that the
ComponentUI only change the property on the
JComponent if the current value is
null or implements
UIResource . If the current value is
null or
implements
UIResource it indicates the property has not
been set by the developer, and the ui is free to change it. For
example,
BasicButtonUI.installDefaults only changes the
font on the
JButton if the return value from
button.getFont() is
null or implements
UIResource . On the other hand if
button.getFont() returned
a
non-null value that did not implement
UIResource then
BasicButtonUI.installDefaults would not change the
JButton 's font.
For primitive values, such as
opaque , the method
installProperty should be invoked.
installProperty only changes
the correspoding property if the value has not been changed by the
developer.
ComponentUI implementations should use the various install methods
provided by this class as they handle the necessary checking and install
the property using the recommended guidelines.
Exceptions
All of the install methods provided by
LookAndFeel need to
access the defaults if the value of the property being changed is
null or a
UIResource . For example, installing the
font does the following:
JComponent c;
Font font = c.getFont();
if (font == null || (font instanceof UIResource)) {
c.setFont(UIManager.getFont("fontKey"));
}
If the font is
null or a
UIResource , the
defaults table is queried with the key
fontKey . All of
UIDefault's get methods throw a
NullPointerException if passed in
null . As such, unless
otherwise noted each of the various install methods of
LookAndFeel throw a
NullPointerException if the current
value is
null or a
UIResource and the supplied
defaults key is
null . In addition, unless otherwise specified
all of the
install methods throw a
NullPointerException if
a
null component is passed in.
version: 1.50 05/05/07 author: Tom Ball author: Hans Muller |
Method Summary | |
public UIDefaults | getDefaults() Returns the look and feel defaults. | abstract public String | getDescription() Return a one line description of this look and feel implementation,
e.g. | public static Object | getDesktopPropertyValue(String systemPropertyName, Object fallbackValue) Returns the value of the specified system desktop property by
invoking Toolkit.getDefaultToolkit().getDesktopProperty() . | public Icon | getDisabledIcon(JComponent component, Icon icon) Returns an Icon with a disabled appearance.
This method is used to generate a disabled Icon when
one has not been specified. | public Icon | getDisabledSelectedIcon(JComponent component, Icon icon) Returns an Icon for use by disabled
components that are also selected. | abstract public String | getID() Return a string that identifies this look and feel. | public LayoutStyle | getLayoutStyle() Returns the LayoutStyle for this look
and feel. | abstract public String | getName() Return a short string that identifies this look and feel, e.g.
"CDE/Motif". | public boolean | getSupportsWindowDecorations() Returns
true if the LookAndFeel returned
RootPaneUI instances support providing
Window decorations in a JRootPane . | public void | initialize() Initializes the look and feel. | public static void | installBorder(JComponent c, String defaultBorderName) Convenience method for setting a component's border property with
a value from the defaults. | public static void | installColors(JComponent c, String defaultBgName, String defaultFgName) Convenience method for setting a component's foreground
and background color properties with values from the
defaults. | public static void | installColorsAndFont(JComponent c, String defaultBgName, String defaultFgName, String defaultFontName) Convenience method for setting a component's foreground,
background and font properties with values from the
defaults. | public static void | installProperty(JComponent c, String propertyName, Object propertyValue) Convenience method for installing a property with the specified name
and value on a component if that property has not already been set
by the developer. | abstract public boolean | isNativeLookAndFeel() If the underlying platform has a "native" look and feel, and
this is an implementation of it, return
true . | abstract public boolean | isSupportedLookAndFeel() Return
true if the underlying platform supports and or permits
this look and feel. | public static void | loadKeyBindings(InputMap retMap, Object[] keys) Populates an
InputMap with the specified bindings.
The bindings are supplied as a list of alternating
keystroke-action key pairs. | public static ComponentInputMap | makeComponentInputMap(JComponent c, Object[] keys) Creates a
ComponentInputMapUIResource from
keys . | public static Object | makeIcon(Class> baseClass, String gifFile) Creates and returns a
UIDefault.LazyValue that loads an
image. | public static InputMap | makeInputMap(Object[] keys) Creates a
InputMapUIResource from keys . | public static JTextComponent.KeyBinding[] | makeKeyBindings(Object[] keyBindingList) Convenience method for building an array of
KeyBindings . | public void | provideErrorFeedback(Component component) Invoked when the user attempts an invalid operation,
such as pasting into an uneditable JTextField
that has focus. | public String | toString() Returns a string that displays and identifies this
object's properties. | public void | uninitialize() Uninitializes the look and feel. | public static void | uninstallBorder(JComponent c) Convenience method for uninstalling a border. |
getDescription | abstract public String getDescription()(Code) | | Return a one line description of this look and feel implementation,
e.g. "The CDE/Motif Look and Feel". This string is intended for
the user, e.g. in the title of a window or in a ToolTip message.
short description for the look and feel |
getDesktopPropertyValue | public static Object getDesktopPropertyValue(String systemPropertyName, Object fallbackValue)(Code) | | Returns the value of the specified system desktop property by
invoking Toolkit.getDefaultToolkit().getDesktopProperty() .
If the value of the specified property is
null ,
fallbackValue is returned.
Parameters: systemPropertyName - the name of the system desktop property being queried Parameters: fallbackValue - the object to be returned as the value if the system value is null the current value of the desktop property See Also: java.awt.Toolkit.getDesktopProperty since: 1.4 |
getDisabledIcon | public Icon getDisabledIcon(JComponent component, Icon icon)(Code) | | Returns an Icon with a disabled appearance.
This method is used to generate a disabled Icon when
one has not been specified. For example, if you create a
JButton and only specify an Icon via
setIcon this method will be called to generate the
disabled Icon . If
null is passed as
icon this method returns
null .
Some look and feels might not render the disabled
Icon , in which
case they will ignore this.
Parameters: component - JComponent that will display the Icon ,may be null Parameters: icon - Icon to generate the disabled icon from disabled Icon , or null if a suitable Icon can not be generated since: 1.5 |
getDisabledSelectedIcon | public Icon getDisabledSelectedIcon(JComponent component, Icon icon)(Code) | | Returns an Icon for use by disabled
components that are also selected. This method is used to generate an
Icon for components that are in both the disabled and
selected states but do not have a specific Icon for this
state. For example, if you create a JButton and only
specify an Icon via setIcon this method
will be called to generate the disabled and selected
Icon . If
null is passed as icon this
methods returns
null .
Some look and feels might not render the disabled and selected
Icon , in which case they will ignore this.
Parameters: component - JComponent that will display the Icon ,may be null Parameters: icon - Icon to generate disabled and selected icon from disabled and selected icon, or null if a suitable Icon can not be generated. since: 1.5 |
getID | abstract public String getID()(Code) | | Return a string that identifies this look and feel. This string
will be used by applications/services that want to recognize
well known look and feel implementations. Presently
the well known names are "Motif", "Windows", "Mac", "Metal". Note
that a LookAndFeel derived from a well known superclass
that doesn't make any fundamental changes to the look or feel
shouldn't override this method.
identifier for the look and feel |
getLayoutStyle | public LayoutStyle getLayoutStyle()(Code) | | Returns the LayoutStyle for this look
and feel. This never returns
null .
You generally don't use the LayoutStyle from
the look and feel, instead use the LayoutStyle
method getInstance .
See Also: LayoutStyle.getInstance the LayoutStyle for this look and feel since: 1.6 |
getName | abstract public String getName()(Code) | | Return a short string that identifies this look and feel, e.g.
"CDE/Motif". This string should be appropriate for a menu item.
Distinct look and feels should have different names, e.g.
a subclass of MotifLookAndFeel that changes the way a few components
are rendered should be called "CDE/Motif My Way"; something
that would be useful to a user trying to select a L&F from a list
of names.
short identifier for the look and feel |
initialize | public void initialize()(Code) | | Initializes the look and feel. While this method is public,
it should only be invoked by the
UIManager when a
look and feel is installed as the current look and feel. This
method is invoked before the
UIManager invokes
getDefaults . This method is intended to perform any
initialization for the look and feel. Subclasses
should do any one-time setup they need here, rather than
in a static initializer, because look and feel class objects
may be loaded just to discover that
isSupportedLookAndFeel() returns
false .
See Also: LookAndFeel.uninitialize See Also: UIManager.setLookAndFeel |
installBorder | public static void installBorder(JComponent c, String defaultBorderName)(Code) | | Convenience method for setting a component's border property with
a value from the defaults. The border is only set if the border is
null or an instance of
UIResource .
Parameters: c - component to set the border on Parameters: defaultBorderName - key specifying the border throws: NullPointerException - as described inexceptions |
installColors | public static void installColors(JComponent c, String defaultBgName, String defaultFgName)(Code) | | Convenience method for setting a component's foreground
and background color properties with values from the
defaults. The properties are only set if the current
value is either
null or a
UIResource .
Parameters: c - component to set the colors on Parameters: defaultBgName - key for the background Parameters: defaultFgName - key for the foreground See Also: LookAndFeel.installColorsAndFont See Also: UIManager.getColor throws: NullPointerException - as described inexceptions |
installColorsAndFont | public static void installColorsAndFont(JComponent c, String defaultBgName, String defaultFgName, String defaultFontName)(Code) | | Convenience method for setting a component's foreground,
background and font properties with values from the
defaults. The properties are only set if the current
value is either
null or a
UIResource .
Parameters: c - component set to the colors and font on Parameters: defaultBgName - key for the background Parameters: defaultFgName - key for the foreground Parameters: defaultFontName - key for the font throws: NullPointerException - as described inexceptions See Also: LookAndFeel.installColors See Also: UIManager.getColor See Also: UIManager.getFont |
installProperty | public static void installProperty(JComponent c, String propertyName, Object propertyValue)(Code) | | Convenience method for installing a property with the specified name
and value on a component if that property has not already been set
by the developer. This method is intended to be used by
ui delegate instances that need to specify a default value for a
property of primitive type (boolean, int, ..), but do not wish
to override a value set by the client. Since primitive property
values cannot be wrapped with the
UIResource marker, this method
uses private state to determine whether the property has been set
by the client.
throws: IllegalArgumentException - if the specified property is notone which can be set using this method throws: ClassCastException - if the property value has not been setby the developer and the type does not match the property's type throws: NullPointerException - if c is null , or thenamed property has not been set by the developer and propertyValue is null Parameters: c - target component to set the property on Parameters: propertyName - name of the property to set Parameters: propertyValue - value of the property since: 1.5 |
isNativeLookAndFeel | abstract public boolean isNativeLookAndFeel()(Code) | | If the underlying platform has a "native" look and feel, and
this is an implementation of it, return
true . For
example, when the underlying platform is Solaris running CDE
a CDE/Motif look and feel implementation would return
true .
true if this look and feel represents the underlyingplatform look and feel |
isSupportedLookAndFeel | abstract public boolean isSupportedLookAndFeel()(Code) | | Return
true if the underlying platform supports and or permits
this look and feel. This method returns
false if the look
and feel depends on special resources or legal agreements that
aren't defined for the current platform.
true if this is a supported look and feel See Also: UIManager.setLookAndFeel |
loadKeyBindings | public static void loadKeyBindings(InputMap retMap, Object[] keys)(Code) | | Populates an
InputMap with the specified bindings.
The bindings are supplied as a list of alternating
keystroke-action key pairs. The
keystroke is either
an instance of
KeyStroke , or a
String that identifies the
KeyStroke for the binding. Refer
to
KeyStroke.getKeyStroke(String) for the specific
format. The
action key part of the pair is the key
registered in the
InputMap for the
KeyStroke .
The following illustrates loading an
InputMap with two
key-action pairs:
LookAndFeel.loadKeyBindings(inputMap, new Object[] {
"control X", "cut",
"control V", "paste"
});
Supplying a
null list of bindings (
keys ) does not
change
retMap in any way.
Specifying a
null
action key results in
removing the
keystroke's entry from the
InputMap .
A
null
keystroke is ignored.
Parameters: retMap - InputMap to add the key-action pairs to Parameters: keys - bindings to add to retMap throws: NullPointerException - if keys is non-null , not empty, and retMap is null See Also: KeyStroke.getKeyStroke(String) See Also: InputMap since: 1.3 |
makeIcon | public static Object makeIcon(Class> baseClass, String gifFile)(Code) | | Creates and returns a
UIDefault.LazyValue that loads an
image. The returned value is an implementation of
UIDefaults.LazyValue . When
createValue is invoked on
the returned object, the image is loaded. If the image is
non-null , it is then wrapped in an
Icon that implements
UIResource . The image is loaded using
Class.getResourceAsStream(gifFile) .
This method does not check the arguments in any way. It is
strongly recommended that
non-null values are supplied else
exceptions may occur when
createValue is invoked on the
returned object.
Parameters: baseClass - Class used to load the resource Parameters: gifFile - path to the image to load a UIDefaults.LazyValue ; when resolved the LazyValue loads the specified image See Also: UIDefaults.LazyValue See Also: Icon See Also: Class.getResourceAsStream(String) |
makeInputMap | public static InputMap makeInputMap(Object[] keys)(Code) | | Creates a
InputMapUIResource from keys . This is
a convenience method for creating a new
InputMapUIResource ,
invoking
loadKeyBindings(map, keys) , and returning the
InputMapUIResource .
Parameters: keys - alternating pairs of keystroke-action key pairs as described in LookAndFeel.loadKeyBindings newly created and populated InputMapUIResource See Also: LookAndFeel.loadKeyBindings since: 1.3 |
makeKeyBindings | public static JTextComponent.KeyBinding[] makeKeyBindings(Object[] keyBindingList)(Code) | | Convenience method for building an array of
KeyBindings . While this method is not deprecated, developers
should instead use
ActionMap and
InputMap for
supplying key bindings.
This method returns an array of
KeyBindings , one for each
alternating
key-action pair in
keyBindingList .
A
key can either be a
String in the format
specified by the KeyStroke.getKeyStroke method, or
a
KeyStroke . The
action part of the pair is a
String that corresponds to the name of the
Action .
The following example illustrates creating a
KeyBinding array
from six alternating
key-action pairs:
JTextComponent.KeyBinding[] multilineBindings = makeKeyBindings( new Object[] {
"UP", DefaultEditorKit.upAction,
"DOWN", DefaultEditorKit.downAction,
"PAGE_UP", DefaultEditorKit.pageUpAction,
"PAGE_DOWN", DefaultEditorKit.pageDownAction,
"ENTER", DefaultEditorKit.insertBreakAction,
"TAB", DefaultEditorKit.insertTabAction
});
If
keyBindingList's length is odd, the last element is
ignored.
Supplying a
null value for either the
key or
action part of the
key-action pair results in
creating a
KeyBinding with the corresponding value
null . As other parts of Swing's expect
non-null values
in a
KeyBinding , you should avoid supplying
null as
either the
key or
action part of the
key-action pair.
Parameters: keyBindingList - an array of key-action pairs an array of KeyBindings throws: NullPointerException - if keyBindingList is null throws: ClassCastException - if the key part of the pair isnot a KeyStroke or String , or the action part of the pair is not a String See Also: ActionMap See Also: InputMap See Also: KeyStroke.getKeyStroke |
provideErrorFeedback | public void provideErrorFeedback(Component component)(Code) | | Invoked when the user attempts an invalid operation,
such as pasting into an uneditable JTextField
that has focus. The default implementation beeps. Subclasses
that wish different behavior should override this and provide
the additional feedback.
Parameters: component - the Component the error occurred in,may be null indicating the error condition is not directly associated with a Component since: 1.4 |
toString | public String toString()(Code) | | Returns a string that displays and identifies this
object's properties.
a String representation of this object |
uninitialize | public void uninitialize()(Code) | | Uninitializes the look and feel. While this method is public,
it should only be invoked by the
UIManager when
the look and feel is uninstalled. For example,
UIManager.setLookAndFeel invokes this when the look and
feel is changed.
Subclasses may choose to free up some resources here.
See Also: LookAndFeel.initialize See Also: UIManager.setLookAndFeel |
uninstallBorder | public static void uninstallBorder(JComponent c)(Code) | | Convenience method for uninstalling a border. If the border of
the component is a
UIResource , it is set to
null .
Parameters: c - component to uninstall the border on throws: NullPointerException - if c is null |
|
|