Java AWT: Desktop Colors

Last Updated: February 3, 1997

Purpose

It is common for platform desktops (Windows95, Solaris/CDE, etc.) to provide a color scheme for objects on the desktop, and typically this scheme is configurable by the user. It is usually desirable to have applications running on that desktop use that color scheme in order to maintain visual consistency.

The AWT attempts to set appropriate default colors for its components, but there is currently no convenient way for a Java program to query and use those colors directly. This is particularly a problem when creating custom components where you'd like to ensure that the background, shadow, and font colors all match the rest of the desktop. As of version 1.1 of the Java^TM platform, the AWT provides a simple API for accessing and using these desktop colors.

Desktop Color API

The API involves introducing a new type of "symbolic" color, which is represented by a subclass of java.awt.Color:


        java.awt.SystemColor

A SystemColor object can be used just like any other Color object, the only difference being that the actual value that represents its current color may change dynamically (on systems which support dynamic notification when the user changes the color scheme).

SystemColor objects are defined by the system and cannot be instantiated by Java programs.

Range of Colors

The SystemColor class provides a standard set of these symbolic colors that represent each distinct type of coloration on the desktop. These symbolic color objects are created automatically and stored statically in java.awt.SystemColor:

	public final static SystemColor desktop; // Background color of desktop

	public final static SystemColor activeCaption; // Background color for captions

	public final static SystemColor activeCaptionText; // Text color for captions

	public final static SystemColor activeCaptionBorder; // Border color for caption text

	public final static SystemColor inactiveCaption; // Background color for inactive captions

	public final static SystemColor inactiveCaptionText; // Text color for inactive captions

	public final static SystemColor inactiveCaptionBorder; // Border color for inactive captions

	public final static SystemColor window; // Background for windows

	public final static SystemColor windowBorder; // Color of window border frame

	public final static SystemColor windowText; // Text color inside windows

	public final static SystemColor menu; // Background for menus

	public final static SystemColor menuText; // Text color for menus

	public final static SystemColor text; // background color for text

	public final static SystemColor textText; // text color for text

	public final static SystemColor textHighlight; // background color for highlighted text

	public final static SystemColor textHighlightText; // text color for highlighted text

	public final static SystemColor control; // Background color for controls

	public final static SystemColor controlText; // Text color for controls

	public final static SystemColor controlLtHighlight; // Light highlight color for controls

	public final static SystemColor controlHighlight; // Highlight color for controls

	public final static SystemColor controlShadow; // Shadow color for controls

	public final static SystemColor controlDkShadow; // Dark shadow color for controls

	public final static SystemColor inactiveControlText; // Text color for inactive controls

	public final static SystemColor scrollbar; // Background color for scrollbars

	public final static SystemColor info; // Background color for spot-help text

	public final static SystemColor infoText; // Text color for spot-help text

If a Java program either sets the foreground or background of a component to be one of these symbolic colors, or uses one of these for rendering, the current value for that symbolic color will be used.

Not all platforms support distinct colors for each of these symbolic names. In the cases where a symbolic color is not supported by a platform, it is mapped to the most appropriate default. These colors are guaranteed to be non-null.

The AWT base components will be modified to use these symbolic colors in order to provide more consistent default integration with the desktop. Java programs written for 1.0 which make any assumptions about the default color of components (i.e. assume they will be "gray") may not render correctly under 1.1. It is always important to query the component for its background/foreground colors within paint() methods for this reason.

One-time vs. Dynamic Updates

At a minimum, these colors are initialized dynamically when the toolkit is first loaded. Some desktops provide dynamic update capabilities such that the AWT can detect when the user changes the color scheme and then update all these symbolic colors on the fly. However, this is platform-specific and is not a guaranteed feature of this interface.

Sample Code

Following is an example of a custom component (a separator) which uses this API:

	
import java.awt.*;

//
// Oversimplified separator class for creating 3D horizontal
// line separators
//
public class Separator extends Component {

    public Separator(int length, int thickness) {
       super();
       setSize(length, thickness);
       setBackground(SystemColor.control);
    }

    public void paint(Graphics g) {
       int x1, y1, x2, y2;
       Rectangle bbox = getBounds();
     
       x1 = 0;
       x2 = bbox.width - 1;
       y1 = y2 = bbox.height/2 - 1;

       g.setColor(SystemColor.controlShadow);
       g.drawLine(x1, y2, x2, y2);
       g.setColor(SystemColor.controlHighlight);
       g.drawLine(x1, y2+1, x2, y2+1);
    }

    public static void main(String[] args) {
        Frame f = new Frame("Separator Example");
        f.setSize(200, 100);
        f.setBackground(SystemColor.control);
        Separator sep = new Separator(200, 4);
        f.add("Center", sep);
        f.show();
    }
}

Send feedback to:java-awt@java.sun.com