| Documentation Contents

# Windows Desktop Property Support

This feature involves two areas:

- Honor More User Preferences
  - Color Properties
  - Geometry Properties
  - Font Properties
  - Visual Effect Properties
  - Audio Feedback Properties
  - Input Properties
- Respond to Dynamic Changes

## Honor More User Preferences

On the Windows platform, users may customize their GUIs via the"Properties" option off the desktop's popup menu. In order to ensure the Swing Windows Look and Feel properly implements the user's visual and behavioral preferences, it must obtain the values of these UI properties from the system registry. The values for these properties will be retrievable from the `getDesktopProperty()` method on java.awt.Toolkit.

Most of the properties accessible via this method are specific to the Windows platform and hence have a "win." prefix. The list of supported Windows property names can be obtained programmaticallyby querying the "win.propNames" property:

         String propnames[] = (String[])Toolkit.getDefaultToolkit().getDesktopProperty("win.propNames");
         System.out.println("Supported windows property names:");
             for(int i = 0; i < propnames.length; i++) {
                 System.out.println(propnames[i]);
             }

Properties which are supported on all platforms begin with an "awt." prefix.

Programs do not need to access these properties directly; the Windows look and feel will automatically read and interpret these properties to provide proper visuals and behavior for the components.

### Color Properties

User Preference | Java Property Name | Type
--- | --- | ---
3D Object Background | "win.3d.backgroundColor" | java.awt.Color
3D Object Highlight | "win.3d.highlightColor" | java.awt.Color
3D Object Light Highlight | "win.3d.lightColor" | java.awt.Color
3D Object Shadow | "win.3d.shadowColor" | java.awt.Color
Active Title Bar color1 | "win.frame.activeCaptionColor" | java.awt.Color
Active Title Bar color2 | "win.frame.activeCaptionGradientColor"(TBI) | java.awt.Color
Active Title Bar font color | "win.frame.captionTextColor" | java.awt.Color
Active Window Border color | "win.frame.activeBorderColor" | java.awt.Color
Application Background color | "win.mdi.backgroundColor" | java.lang.Color
Desktop color | "win.desktop.backgroundColor" | java.awt.Color
Inactive Title Bar color1 | "win.frame.inactiveCaptionColor" | java.awt.Color
Inactive Title Bar color2 | "win.frame.inactiveCaptionGradientColor"(TBI) | java.awt.Color
Inactive Title Bar font color | "win.frame.inactiveCaptionTextColor" | java.awt.Color
Inactive Window Border color | "win.frame.inactiveBorderColor" | java.awt.Color
Menu color | "win.menu.backgroundColor" | java.awt.Color
Menu font color | "win.menu.textColor" | java.awt.Color
Message Box font color | "win.frame.textColor?????" | java.awt.Color
Selected Items color | "win.item.highlightColor" | java.awt.Color
Selected Items font color | "win.item.highlightTextColor" | java.awt.Color
ToolTip color | "win.tooltip.backgroundColor" | java.awt.Color
ToolTip font color | "win.tooltip.textColor" | java.awt.Color
Window color | "win.frame.backgroundColor" | java.awt.Color
Window font color | "win.frame.textColor" | java.awt.Color
Hot tracking color | "win.item.hotTrackedColor" | java.awt.Color

### Geometry Properties

User Preference | Java Property Name | Type
--- | --- | ---
Active Title Bar size | "win.frame.captionHeight" | java.lang.Integer
Active Window Border size | "win.frame.sizingBorderWidth" | java.lang.Integer
Caption Buttons size | "win.frame.captionButtonHeight" "win.frame.captionButtonWidth" win.frame.captionHeight" | java.lang.Integer
Icon size | "win.icon.hspacing" "win.icon.vspacing"??? | java.lang.Integer
Icon horizontal spacing | "win.icon.hspacing" | java.lang.Integer
Icon vertical spacing | "win.icon.vspacing" | java.lang.Integer
Inactive Title Bar size | "win.frame.captionButtonHeight" "win.frame.captionButtonWidth" "win.frame.captionHeight" | java.lang.Integer
Inactive Window Border size | "win.frame.sizingBorderWidth" | java.lang.Integer
Menu font size | "win.menu.font" "win.menu.height" | java.lang.Integer
Menu Size | "win.menu.height" "win.menu.buttonWidth" | java.awt.Integer
Palette Title size | "win.frame.smallCaptionHeight" "win.frame.smallCaptionButtonHeight" "win.frame.smallCaptionButtonWidth" | java.lang.Integer
Scrollbar width | "win.scrollbar.width" | java.lang.Integer
Scrollbar height | "win.scrollbar.height" | java.lang.Integer
Selected Items size | "win.menu.height" "win.menu.buttonWidth" | java.lang.Integer

### Font Properties

User Preference | Java Property Name | Type
--- | --- | ---
Active Title Bar font | "win.frame.captionFont" | java.awt.Font
Icon font | "win.icon.font" | java.awt.Font
Inactive Title Bar font | "win.frame.captionFont" | java.awt.Font
Menu font | "win.menu.font" | java.awt.Font
Message Box font | "win.messagebox.font" | java.awt.Font
Palette Title font | "win.frame.smallCaptionFont" | java.awt.Font
Selected Items font | "win.menu.font" | java.awt.Font
ToolTip font | "win.tooltip.font" | java.awt.Font

#### Font Compatibility

Now Swing programs running in the Windows look and feel will render with the system font set by the user instead of a Java-defined font. Since this may cause compatibility problems for programs which depend on the old behavior (because of geometry issues, localization dependencies on particular font glyphs, etc.), a runtime property has been provided to allow this feature to be turned off as necessary:

         java -Dswing.useSystemFontSettings=false MyJavaProgram

### Visual Effect Properties

User Preference | Java Property Name | Type
--- | --- | ---
Icon title wrapping | "win.icon.titleWrappingOn" | java.lang.Boolean
Window Drag effects | "win.frame.fullWindowDragOn" | java.lang.Boolean
Keyboard Navigation Display | "win.menu.keyboardCuesOn"(TBI) | java.lang.Boolean
Hot tracking on toolbars/menubars | "win.item.hotTrackingOn" | java.lang.Boolean
Title Bar Gradients | "win.frame.captionGradientsOn" | java.lang.Boolean

### Audio-feedback Properties

User Preference | Java Property Name | Type
--- | --- | ---
Default sound | "win.sound.default" | java.lang.Runnable
Close sound | "win.sound.close" | java.lang.Runnable
Maximize sound | "win.sound.maximize" | java.lang.Runnable
Minimize sound | "win.sound.minimize" | java.lang.Runnable
Menu Command sound | "win.sound.menuCommand" | java.lang.Runnable
Menu Popup sound | "win.sound.menuPopup" | java.lang.Runnable
Open sound | "win.sound.open" | java.lang.Runnable
Restore Down sound | "win.sound.restoreDown" | java.lang.Runnable
Restore Up sound | "win.sound.restoreUp" | java.lang.Runnable
System Asterisk sound | "win.sound.asterisk" | java.lang.Runnable
System Exclamation sound | "win.sound.exclamation" | java.lang.Runnable
System Exit sound | "win.sound.exit" | java.lang.Runnable
System Hand sound | "win.sound.hand" | java.lang.Runnable
System Question sound | "win.sound.question" | java.lang.Runnable
System Start sound | "win.sound.start" | java.lang.Runnable

#### Dynamic Changes to Sounds

Note that the object returned for a sound property is simply a `Runnable` that plays the current audio clip for that property. This means that there is no need for watching for dynamic changes to sound properties because the sound's property value is a live link to the current sound setting.

### Input Properties

User Preference | Java Property Name | Type
--- | --- | ---
Double click interval | "awt.multiClickInterval" | java.lang.Integer
Cursor blink rate | "awt.cursorBlinkRate"(TBI) | java.lang.Integer

## Respond to Dynamic Changes

In JDK 1.3, AWT added the ability to register for notification when one of these desktop property values changes. This is supported via the `addPropertyChangeListener()` method on java.awt.Toolkit. Swing's Windows Look and Feel will use this mechanism to watch for dynamic property change events on visual properties, and update the GUI by uninstalling and reinstalling the UI delegates in order for the components to have the most up-to-date visual property values. This dynamic behavior will automatically occur for all Swing programs running the Windows look and feel.

This mechanism will update GUI components by traversing the GUI hierarchy (starting with `Frame.getFrames()` and traversing all windows/containers/components from there). If a client has any undisplayable components when this occurs (see the `isDisplayable()` method on java.awt.Component for a definition of when a component is displayable), those components will not update automatically and it will be the client program's responsibility to update the UI on those components to ensure their Look and Feel is up-to-date. For example, this occurs in the SwingSet2 demo because demo panels are created but not added to the GUI heirarchy until they are selected from the demo's tabbedpane. Therefore, before the newly selected demo panel is added to the hierarchy, its UI is updated to ensure it has the most current property settings:

        fragment from SwingSet2.java:  // Ensure panel's UI is current before making visible
        JComponent currentDemoPanel = demo.getDemoPanel();
        SwingUtilities.updateComponentTreeUI(currentDemoPanel);
        // Replace current demo with newly selected demo
        demoPanel.removeAll();
        demoPanel.add(currentDemoPanel, BorderLayout.CENTER);

Copyright © 1995-2010 Sun Microsystems, Inc. All Rights Reserved. Please send comments using this Feedback page. | Java Technology