As a developer, it is impossible for you to choose colors and fonts for your application that satisfy all users. Aside from the consideration of individual taste, display characteristics vary and some users have various degrees of colorblindness. Schemes allow users to select colors and fonts according to their preferences and needs.

Although users can already use the X resource mechanism to customize colors and fonts, it is very difficult and time-consuming for most end users to do so, because the task requires knowledge of the internal structure of the program. On the other hand, if your application supports schemes, users can use the graphical Schemes Browser, schemebr (available from the “Colors” option of the Customize menu in Desktop toolchest), to change colors and fonts.

Using schemes also reduces the time and effort required to develop your application. Instead of choosing your own colors and fonts and coding them into your application, you can simply set a resource value to activate schemes and get the distinctive Indigo Magic appearance.

A scheme simply maps specific colors and fonts to abstract resource names according to the functions they serve in an application. So instead of using specific colors like “blue” or “#123456” and specific fonts like “-*-screen-medium-r-normal--13-*-*-*-*-*-iso8859-1,” your application can use symbolic values like TextForeground, TextSelectedColor, and FixedWidthFont. The exact definition of these symbolic values depends on the scheme the user chooses to apply to your application. As long as your application uses the symbolic color and font names for the purposes for which they were intended, users or graphic designers can design a new palette (a binding of the symbolic values to specific colors) and the result should look good with your application.

Often, you don't even need to deal with the symbolic colors and fonts yourself. The schemes mechanism includes a map file that automatically binds the symbolic values to the various IRIS IM widgets and widget resources. One case where you might need to set a color or font explicitly is if you need to highlight a component (for example, in a chart). The schemes mechanism defines special symbolic values such as HighlightColor1 through HighlightColor8 for these purposes. (See “Directly Accessing Colors and Fonts” for more information on the symbolic values.)

Silicon Graphics incorporates schemes in its implementation of Xt, so you don't need to link to a separate schemes library or call a special function to use schemes. All you need to do to enable schemes is to include in your application's app-defaults file (in the /usr/lib/X11/app-defaults directory) the line:

AppClass*useSchemes:     all

where AppClass is your application's class name. This activates all aspects of schemes.

---

Note: To ensure that users don't accidently override your settings, be sure to prefix the useSchemes resource with your application's class name.

---

To deactivate schemes, you can set:

AppClass*useSchemes: none

If you wish to activate schemes without using an app-defaults file, or if you want to guarantee that the schemes setting can't be changed by users, call the function SgiUsesScheme():

void SgiUsesScheme(char *value)

value can be either “all” or “none”. This function requires that you include the header file <X11/SGIScheme.h>.

The schemes map file automatically handles applying colors and fonts to most IRIS IM widgets based on the widgets' class names. Unfortunately, IRIS IM doesn't have unique class names for menu bars, menu panes, and option menus. To allow schemes to be applied to these elements, your application must follow some simple naming conventions for these widgets. Schemes expect applications to name all menu bars “menuBar,” all option menus “optionMenu,” and the pane of all option menus “optionPane.” Schemes also recognize some other variations of these names, including “menu_bar,” “menubar,” “menu_Bar,” and so on.

If you need to set a color or a font in your application, use the procedures described in “Assigning Non-Default Colors and Fonts to Widgets” and “Directly Accessing Colors and Fonts”. Don't hard code colors or fonts in your application because they might not work with the scheme that a user selects. For example, if you programmatically set a text color to black and a user chooses a scheme that has a very dark background, your text is unreadable. Also avoid setting colors that IRIS IM normally computes. For example, if you hard code the top or bottom shadow colors used by IRIS IM controls, these colors might not be correct if a user changes the scheme.

There are obviously some cases for which this recommendation doesn't apply. The most common are windows in which you are rendering images. For example, if your application uses OpenGL or some other library to render an image in a window, the colors used in this window aren't derived from schemes.

Fonts are usually less critical than colors, although the best visual effects will be produced if you use only the fonts defined in the schemes. You should be aware that on low-resolution screens, the sizes of the fonts defined by schemes can change. Therefore, you should design the layout of your application to handle variable-sized fonts. This means you shouldn't hard-code x, y locations or fixed widths or heights for widgets in your application. Instead use IRIS IM manager widgets such as the Form to achieve a flexible layout that can respond to changes in font sizes.

Sometimes, you might want to override the default color or font assigned to a widget by a scheme. For example, all labels are set by default to use a bold font (BoldLabelFont); however you might decide that a regular font (PlainLabelFont) is more appropriate for some of your application's labels.

To assign a non-default font or color to a widget, include a line in your application's app-defaults file mapping a different symbolic scheme resource to that widget. For example, the following line assigns a regular label font (rather than the default bold font) to a label in your application named “simpleLabel”:

YourApp*simpleLabel*fontList: SGI_DYNAMIC PlainLabelFont

The symbol SGI_DYNAMIC identifies this resource as a dynamically changeable scheme resource. The actual font assigned to PlainLabelFont could potentially be different in each scheme. As the user changes schemes, the correct resource is applied to your program.

---

Note: Remember to prefix the widget hierarchy with your application's class name to prevent users from accidentally overriding your setting.

---

You can use the same technique with colors. For example, suppose you have two types of label widgets positioned on an IRIS IM XmDrawingArea widget and you want to use color to give some significance to different labels. Perhaps the application is some type of a flowchart and some of the labels represent tasks in progress, while other represent tasks that have been completed. The schemes map file already maps the symbolic scheme resource DrawingAreaColor to the XmDrawingArea widget. The scheme palette also provides colors that both provide a nice contrast against the DrawingAreaColor and allow the current TextForeground color to be readable. These colors are DrawingAreaContrast1, DrawingAreaContrast2, DrawingAreaContrast3, and DrawingAreaContrast4. To specify the colors of each label widget in your application, you could set the following resources:

YourApp*label1*background: SGI_DYNAMIC DrawingAreaContrast1
YourApp*label2*background: SGI_DYNAMIC DrawingAreaContrast1
YourApp*label3*background: SGI_DYNAMIC DrawingAreaContrast2
...

Each scheme also contains a set of basic colors that you can use for simple graphics, icons, and so on. These colors maintain their basic characteristics, but change slightly from scheme to scheme to blend with the general flavor of the scheme. For example, you could set a label widget to be “red” as follows:

YourApp*label*background: SGI_DYNAMIC RedColor

The exact shade of red will change from scheme to scheme, but will always be “reddish” and always fit with the other colors in the scheme.

If necessary, you can also use non-scheme colors and fonts, although Silicon Graphics strongly recommends that you don't do this. In particular, if you hard-code a color, the user might select a scheme in which that color doesn't provide the contrast you desire. The color could even be “lost” among the other scheme colors. Non-scheme fonts are less likely to cause problems, but your application will still have an inconsistent appearance if it uses them.

You use the same methods to assign a non-scheme color or font that you normally would in an X program. For example, you could set a font for a label named “simpleLabel” in your app-defaults file as follows:

YourApp*simpleLabel*fontList: 6x12

When your application uses widgets only, the schemes map file automatically retrieves all colors and fonts from the current scheme and assigns them to your application's widgets. However, you might need to access some of the scheme's colors or fonts directly from within a program. For example, you might want to draw a bar chart or other display using colors that look good no matter what scheme the user has selected.

Example 3-1 shows an example of a function that retrieves a color value given a widget, the color resource name, and the color resource class.

Pixel getColorResource(Widget w, char *name, char *classname)
{

    XtResource request_resources;
    Display *dpy  = XtDisplay ( w );
    int      scr  = DefaultScreen ( dpy );
    Colormap cmap = DefaultColormap ( dpy, scr );
    XColor   color, ignore;
    char    *colorname;

    request_resources.resource_name   = (char *) name;
    request_resources.resource_class  = (char *) className;
    request_resources.resource_type   = XmRString;
    request_resources.resource_size   = sizeof (char *);
    request_resources.default_type    = XmRImmediate;
    request_resources.resource_offset = 0;
    request_resources.default_addr    = (XtPointer) NULL;

    XtGetSubresources(w,
                      (XtPointer) &colorname,
                      NULL, NULL,
                      &requested_resources,
                      1, NULL, 0);

    if ( colorname &&
         XAllocNamedColor ( dpy, cmap, colorname, &color,
                            &ignore ) )
        return ( color.pixel );
    else
        return ( BlackPixel ( dpy, scr ) );
}

You could then retrieve the color defined by the scheme resource drawingAreaContrastColor1 using getColorResource() as follows:

color1 = getColorResource(barChartWidget,
                          "drawingAreaContrastColor1",
                          XmCForeground);

where barChartWidget is the widget that you'll use the color in.

---

Tip: There is a far simpler method for retrieving a resource value if you're using the IRIS ViewKit toolkit. Instead of writing the getColorResource() function listed in Example 3-1, you could simply call:

---

Pixel color1 = (Pixel) VkGetResource( barChartWidget,
                            "drawingAreaContrastColor1",
                             XmCForeground, XmRPixel, 
                            "Black" ); 

You must handle some resources programmatically. For example, the Indigo Magic User Interface Guidelines suggests that your application use a different color for text fields that are not editable than it uses for editable text fields. The IRIS IM text widget currently does not change colors automatically when set to read only mode, so your application must handle this itself. The correct color is provided by schemes as the symbolic name ReadOnlyColor, and can be retrieved by the resource readOnlyColor. Assuming that you've created the getColorResource() function listed in Example 3-1, the following code illustrates this process:

ro = getColorResource( textw,  "readOnlyColor",
                       XmCForeground);
XtVaSetValues( textw, XmNeditable, FALSE,
               XmNbackgroundColor, ro,
               NULL);

---

Tip: The equivalent IRIS ViewKit code would be:

---

Pixel ro = (Pixel) VkGetResource( textw, "readOnlyColor",
                                  XmCForeground, XmRPixel,
                                  "White" );
XtVaSetValues( textw, XmNeditable, FALSE,
               XmNbackgroundColor, ro,
               NULL);

Table 3-1 lists the pre-defined scheme resources and symbolic values. You can use the resources to retrieve color and font values from within your application as described in “Directly Accessing Colors and Fonts”. You can use the symbolic values to assign colors and fonts to widgets in resource files as explained “Assigning Non-Default Colors and Fonts to Widgets”.