javax.swing
class LookAndFeel

java.lang.Object javax.swing.LookAndFeel

Direct Known Subclasses:

BasicLookAndFeel, MultiLookAndFeel

public abstract class LookAndFeel
extends Object

{@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 {@code 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 {@code JComponent} subclass has an implementation of a specific {@code ComponentUI} subclass. The {@code ComponentUI} is often referred to as "the ui", "component ui", or "look and feel delegate". The {@code ComponentUI} subclass is responsible for providing the look and feel specific functionality of the component. For example, {@code JTree} requires an implementation of the {@code ComponentUI} subclass {@code TreeUI}. The implementation of the specific {@code ComponentUI} subclass is provided by the {@code LookAndFeel}. Each {@code JComponent} subclass identifies the {@code ComponentUI} subclass it requires by way of the {@code JComponent} method {@code getUIClassID}.

Each {@code LookAndFeel} implementation must provide an implementation of the appropriate {@code ComponentUI} subclass by specifying a value for each of Swing's ui class ids in the {@code UIDefaults} object returned from {@code getDefaults}. For example, {@code BasicLookAndFeel} uses {@code BasicTreeUI} as the concrete implementation for {@code TreeUI}. This is accomplished by {@code BasicLookAndFeel} providing the key-value pair {@code "TreeUI"-"javax.swing.plaf.basic.BasicTreeUI"}, in the {@code UIDefaults} returned from {@code getDefaults}. Refer to {@link UIDefaults#getUI(JComponent)} for defails on how the implementation of the {@code ComponentUI} subclass is obtained.

When a {@code LookAndFeel} is installed the {@code 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 {@code JComponent} subclass is created.

Recommendations for Look and Feels

ComponentUIs and defaults

For primitive values, such as {@code opaque}, the method {@code installProperty} should be invoked. {@code installProperty} only changes the correspoding property if the value has not been changed by the developer.

{@code 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

   JComponent c;
   Font font = c.getFont();
   if (font == null || (font instanceof UIResource)) {
       c.setFont(UIManager.getFont("fontKey"));
   }
 

LookAndFeel

public LookAndFeel()

getDefaults

public UIDefaults getDefaults()

Returns the look and feel defaults. While this method is public, it should only be invoked by the {@code UIManager} when the look and feel is set as the current look and feel and after {@code initialize} has been invoked.

Returns:

the look and feel defaults

getDescription

public abstract String getDescription()

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.

Returns:

short description for the look and feel

getDesktopPropertyValue

public static Object getDesktopPropertyValue(String systemPropertyName,
                                             Object fallbackValue)

Returns the value of the specified system desktop property by invoking Toolkit.getDefaultToolkit().getDesktopProperty(). If the value of the specified property is {@code null}, {@code fallbackValue} is returned.

Parameters:

systemPropertyName - the name of the system desktop property being queried

fallbackValue - the object to be returned as the value if the system value is null

Returns:

the current value of the desktop property

getDisabledIcon

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. 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 {@code null} is passed as icon this method returns {@code null}.

Some look and feels might not render the disabled {@code Icon}, in which case they will ignore this.

Parameters:

component - {@code JComponent} that will display the {@code Icon}, may be {@code null}

icon - {@code Icon} to generate the disabled icon from

Returns:

disabled {@code Icon}, or {@code null} if a suitable {@code Icon} can not be generated

getDisabledSelectedIcon

public Icon getDisabledSelectedIcon(JComponent component,
                                    Icon icon)

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 {@code null} is passed as icon this methods returns {@code null}.

Some look and feels might not render the disabled and selected {@code Icon}, in which case they will ignore this.

Parameters:

component - {@code JComponent} that will display the {@code Icon}, may be {@code null}

icon - {@code Icon} to generate disabled and selected icon from

Returns:

disabled and selected icon, or {@code null} if a suitable {@code Icon} can not be generated.

getID

public abstract String getID()

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.

Returns:

identifier for the look and feel

getLayoutStyle

public LayoutStyle getLayoutStyle()

Returns the LayoutStyle for this look and feel. This never returns {@code null}.

You generally don't use the LayoutStyle from the look and feel, instead use the LayoutStyle method getInstance.

Returns:

the LayoutStyle for this look and feel

getName

public abstract String getName()

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.

Returns:

short identifier for the look and feel

getSupportsWindowDecorations

public boolean getSupportsWindowDecorations()

Returns {@code true} if the LookAndFeel returned RootPaneUI instances support providing {@code Window} decorations in a JRootPane.

The default implementation returns {@code false}, subclasses that support {@code Window} decorations should override this and return {@code true}.

Returns:

{@code true} if the {@code RootPaneUI} instances created by this look and feel support client side decorations

initialize

public void initialize()

Initializes the look and feel. While this method is public, it should only be invoked by the {@code UIManager} when a look and feel is installed as the current look and feel. This method is invoked before the {@code UIManager} invokes {@code 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 {@code isSupportedLookAndFeel()} returns {@code false}.

installBorder

public static void installBorder(JComponent c,
                                 String defaultBorderName)

Convenience method for setting a component's border property with a value from the defaults. The border is only set if the border is {@code null} or an instance of {@code UIResource}.

Parameters:

c - component to set the border on

defaultBorderName - key specifying the border

installColors

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. The properties are only set if the current value is either {@code null} or a {@code UIResource}.

Parameters:

c - component to set the colors on

defaultBgName - key for the background

defaultFgName - key for the foreground

installColorsAndFont

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. The properties are only set if the current value is either {@code null} or a {@code UIResource}.

Parameters:

c - component set to the colors and font on

defaultBgName - key for the background

defaultFgName - key for the foreground

defaultFontName - key for the font

installProperty

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. 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 {@code UIResource} marker, this method uses private state to determine whether the property has been set by the client.

Parameters:

c - target component to set the property on

propertyName - name of the property to set

propertyValue - value of the property

isNativeLookAndFeel

public abstract boolean isNativeLookAndFeel()

If the underlying platform has a "native" look and feel, and this is an implementation of it, return {@code true}. For example, when the underlying platform is Solaris running CDE a CDE/Motif look and feel implementation would return {@code true}.

Returns:

{@code true} if this look and feel represents the underlying platform look and feel

isSupportedLookAndFeel

public abstract boolean isSupportedLookAndFeel()

Return {@code true} if the underlying platform supports and or permits this look and feel. This method returns {@code false} if the look and feel depends on special resources or legal agreements that aren't defined for the current platform.

Returns:

{@code true} if this is a supported look and feel

loadKeyBindings

public static void loadKeyBindings(InputMap retMap,
                                   Object[] keys)

Populates an {@code InputMap} with the specified bindings. The bindings are supplied as a list of alternating {@code keystroke-action key} pairs. The {@code keystroke} is either an instance of {@code KeyStroke}, or a {@code String} that identifies the {@code KeyStroke} for the binding. Refer to {@code KeyStroke.getKeyStroke(String)} for the specific format. The {@code action key} part of the pair is the key registered in the {@code InputMap} for the {@code KeyStroke}.

The following illustrates loading an {@code InputMap} with two {@code key-action} pairs:

   LookAndFeel.loadKeyBindings(inputMap, new Object[] {
     "control X", "cut",
     "control V", "paste"
   });
 

Supplying a {@code null} list of bindings ({@code keys}) does not change {@code retMap} in any way.

Specifying a {@code null} {@code action key} results in removing the {@code keystroke's} entry from the {@code InputMap}. A {@code null} {@code keystroke} is ignored.

Parameters:

retMap - {@code InputMap} to add the {@code key-action} pairs to

keys - bindings to add to {@code retMap}

makeComponentInputMap

public static ComponentInputMap makeComponentInputMap(JComponent c,
                                                      Object[] keys)

Creates a {@code ComponentInputMapUIResource} from keys. This is a convenience method for creating a new {@code ComponentInputMapUIResource}, invoking {@code loadKeyBindings(map, keys)}, and returning the {@code ComponentInputMapUIResource}.

Parameters:

c - component to create the {@code ComponentInputMapUIResource} with

keys - alternating pairs of {@code keystroke-action key} pairs as described in {@link #loadKeyBindings}

Returns:

newly created and populated {@code InputMapUIResource}

makeIcon

public static Object makeIcon(Class baseClass,
                              String gifFile)

Creates and returns a {@code UIDefault.LazyValue} that loads an image. The returned value is an implementation of {@code UIDefaults.LazyValue}. When {@code createValue} is invoked on the returned object, the image is loaded. If the image is {@code non-null}, it is then wrapped in an {@code Icon} that implements {@code UIResource}. The image is loaded using {@code Class.getResourceAsStream(gifFile)}.

This method does not check the arguments in any way. It is strongly recommended that {@code non-null} values are supplied else exceptions may occur when {@code createValue} is invoked on the returned object.

Parameters:

baseClass - {@code Class} used to load the resource

gifFile - path to the image to load

Returns:

a {@code UIDefaults.LazyValue}; when resolved the {@code LazyValue} loads the specified image

makeInputMap

public static InputMap makeInputMap(Object[] keys)

Creates a {@code InputMapUIResource} from keys. This is a convenience method for creating a new {@code InputMapUIResource}, invoking {@code loadKeyBindings(map, keys)}, and returning the {@code InputMapUIResource}.

Parameters:

keys - alternating pairs of {@code keystroke-action key} pairs as described in {@link #loadKeyBindings}

Returns:

newly created and populated {@code InputMapUIResource}

makeKeyBindings

public static JTextComponent.KeyBinding[] makeKeyBindings(Object[] keyBindingList)

Convenience method for building an array of {@code KeyBindings}. While this method is not deprecated, developers should instead use {@code ActionMap} and {@code InputMap} for supplying key bindings.

This method returns an array of {@code KeyBindings}, one for each alternating {@code key-action} pair in {@code keyBindingList}. A {@code key} can either be a {@code String} in the format specified by the KeyStroke.getKeyStroke method, or a {@code KeyStroke}. The {@code action} part of the pair is a {@code String} that corresponds to the name of the {@code Action}.

The following example illustrates creating a {@code KeyBinding} array from six alternating {@code 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 {@code keyBindingList's} length is odd, the last element is ignored.

Supplying a {@code null} value for either the {@code key} or {@code action} part of the {@code key-action} pair results in creating a {@code KeyBinding} with the corresponding value {@code null}. As other parts of Swing's expect {@code non-null} values in a {@code KeyBinding}, you should avoid supplying {@code null} as either the {@code key} or {@code action} part of the {@code key-action} pair.

Parameters:

keyBindingList - an array of {@code key-action} pairs

Returns:

an array of {@code KeyBindings}

provideErrorFeedback

public void provideErrorFeedback(Component component)

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

toString

public String toString()

Returns a string that displays and identifies this object's properties.

Overrides:

toString in class Object

Returns:

a String representation of this object

uninitialize

public void uninitialize()

Uninitializes the look and feel. While this method is public, it should only be invoked by the {@code UIManager} when the look and feel is uninstalled. For example, {@code UIManager.setLookAndFeel} invokes this when the look and feel is changed.

Subclasses may choose to free up some resources here.

uninstallBorder

public static void uninstallBorder(JComponent c)

Convenience method for uninstalling a border. If the border of the component is a {@code UIResource}, it is set to {@code null}.

Parameters:

c - component to uninstall the border on