You can use scrolled windows, such as an XmMainWindow widget with scroll bars or an XmBulletinBoardDialog widget with scroll bars, to present large windows on small screens. This implementation has the disadvantage of not displaying all of a window at one time; that is, the user has to use the scroll bars to view all portions of the window. This could mean that the user has to use the scroll bars to find push buttons or other widgets, but it does ensure that the application interface is available to the user.

When writing your application, you can automatically include scroll bars on all large, and potentially large, windows without regard to screen size. If you set the XmNscrollBarDisplayPolicy resource to XmAS_NEEDED and the XmNscrollingPolicy resource to XmAUTOMATIC, the scroll bars are displayed only when needed. The scroll bars might not ever be needed, but they are always available.

10.3.5 Using the DXmNfitToScreenPolicy Resource

You can specify the DXmNfitToScreenPolicy resource in your application's defaults file to automatically size all dialog widgets for a screen. DXmNfitToScreenPolicy is a resource of the dialog shell widget. When the DXmNfitToScreenPolicy resource is set to XmAS_NEEDED in an application's defaults file, the dialog shell automatically resizes and positions all dialog shells that are too big for the user's screen.

As a side effect of the resizing, the dialog shell creates its own scroll bars, which allow the user to navigate to the occluded portions of the dialog box.

The DXmNfitToScreenPolicy resource can be set only in an application's defaults file; it cannot be set in a UIL module or through a call to XtSetArg. The format for setting this resource is as follows:

*DXmfitToScreenPolicy: AS_NEEDED

If it is possible to do so, the Motif window manager places a window so that it is not clipped by the boundaries of the screen, regardless of the screen size. If clipping cannot be avoided, a window is placed so that at least the upper-left corner of the window is on the screen. Therefore, your application does not have to take any special precautions when setting the XmNy and XmNy resources for widgets.

10.4 Color Support

You can use color to enhance the visual appeal of your DECwindows application. However, how colors are supported and displayed depends on the visual type of the display hardware and the available color resources.

Each screen has one or more visual types associated with it. The visual type identifies the characteristics of the screen, such as color or monochrome capability. Visual types partially determine the appearance of color on the screen and determine how a client can manipulate colormaps for a specified screen.

Your application should not make any assumptions about the display hardware or the availability of color resources.

Specifically, your application must do the following:

• Not assume that colormap cells are writable
• Not make any assumptions about the depth of the display
• Handle insufficient color resources

This policy is especially true if your application will be displayed on multiple hardware platforms.

The sections that follow describe coding recommendations to follow when writing color applications that will be displayed on multiple hardware platforms.

See the X Window System by Scheifler and Gettys for a complete description of the DECwindows color implementation. Some of that information is summarized here for convenience. (The complete description is also contained in the VMS DECwindows Xlib Programming Volume).

10.4.1 Matching Color Requirements to Display Types

The basic philosophy for using color is to determine the color needs of your application and then determine how the display hardware can best support those needs.

Therefore, before defining colors, use the following method to determine the default visual type of a screen:

1. Call the XDefaultVisualofScreen routine to determine the default visual for the screen. Xlib returns the address of a visual data structure.
2. Check the XVisual.class member of the data structure to determine the visual type.

The X Protocol defines the visual types shown in Table 10-3.

Table 10-3 DECwindows Visual Types

Visual Type	Colormap	Description
Pseudocolor	read/write	Pseudocolor is a full-color device. A pixel value indexes a colormap composed of red, green, and blue definitions. Each definition in the colormap stores the red, green, and blue component values for one color. The color index refers directly to a single entry in the color map. RGB values can be changed dynamically if a cell has been allocated for exclusive use. Pseudocolor is the default visual type on Digital 4-plane and 8-plane systems.
Gray scale	read/write	Gray scale is a black and white device. Gray scale is the same as pseudocolor except that a pixel value indexes a colormap that produces shades of gray only. The gray shades are defined in a colormap with each definition having just one component that defines the level of the white intensity.
Direct color	read/write	Direct color is a full-color device. Both the pixel value and the colormap are separated into three independent parts, one each for red, green, and blue. The red part of the pixel indexes the red part of the colormap, the green indexes the green part of the colormap, and the blue indexes the blue part of the colormap. A complete color definition comprises the three parts in each colormap. When you use the XAllocColorPlanes routine to allocate color resources for a direct color model, pixel values that differ only in one part share the colormap entries indexed by their identical parts. For example, two different pixels (for simplicity, pixel A and pixel B) might index different red color cells but index the same green and blue color cells. If you then use XStoreColors to change the RGB values of the color cells indexed by pixel A, the value of the shared color cells indexed by pixel B would change as well. RGB values can be changed dynamically if a cell has been allocated for exclusive use.
True color	read only	True color is a full-color device. True color is the same as direct color except that the colormap has predefined read-only RGB values in ascending order. True color is the default visual type on Digital 24-plane systems.
Static gray	read only	Static gray is a black and white device. Static gray is the same as gray scale except that the values in the colormap are read-only. Static gray with a two-entry colormap can be thought of as monochrome.
Static color	read only	Static color is a full-color device and is the same as pseudocolor except that the colormap has predefined, read-only, server-dependent values in an undefined, server-dependent order.

The OpenVMS DECburger demo application uses the code shown in Example 10-2 to test the XVisual.class member to see if it is being displayed on a color screen. DECburger implements a "customize background color" feature only for color screens.

Example 10-2 Testing XVisual.class Member

. . . /* If it's a color display, map the customize color menu entry */ if ((XDefaultVisualOfScreen(the_screen))->class == TrueColor || (XDefaultVisualOfScreen(the_screen))->class == PseudoColor || (XDefaultVisualOfScreen(the_screen))->class == DirectColor || (XDefaultVisualOfScreen(the_screen))->class == StaticColor) XtSetMappedWhenManaged(widget_array[k_custom_pdme], TRUE); . . .

10.4.1.1 Writable Color Cells

Color cells can be read-only or writable, depending on the visual type. If the XVisual.class field indicates that the display has read-only color cells (StaticGray, StaticColor, TrueColor), an X error is generated if you attempt to allocate read/write color cells.

When an application calls the XAllocColor routine to allocate a read-only color cell, it specifies the RGB values for the color it wants to use. The server then searches the colors that have already been allocated. If the requested color has been allocated, that pixel value is returned. Otherwise, the server allocates a color cell to store the specified RGB values or those that most closely match the specified RGB values. XAllocColor returns the pixel value that identifies the color cell in the XColor.pixel field. The application cannot change the RGB values of the cell.

Read-only color cells are shared among clients; that is, if another application also calls XAllocColor with these same RGB values, the pixel value is returned to that application as well. This does not count as an additional entry in the colormap.

For read/write color cells, the initial RGB values of the cells are undefined. An application must call XStoreColor or XStoreColors to store RGB values into the cells. Read/write cells should not be shared because the RGB values of the cells can change.

10.4.1.2 Display Depth

You should not make any assumptions about the depth (number of planes) of a display. For example, if you assume that eight planes are available and the application is displayed on a screen with only four planes, unpredictable results will occur.

Your application should call the XDefaultDepthofScreen or XPlanesofScreen routines to determine the maximum number of planes supported on a screen.

Remember that, on some systems, a single display can support multiple screens. Each screen can have several different visual types supported at different depths.

10.4.1.3 Handling Insufficient Color Resources

If your application is displayed on a system with limited color resources, your application should be prepared to deal with this lack of resources. For example, if your application wants to allocate 20 color cells, but only 10 are available, your application must determine how it wants to proceed.

If your application cannot function without all the color cells, you might just print a message that insufficient color resources are available and exit. For example, the OpenVMS DECburger demo application uses the code shown in Example 10-3 to print a message and exit if it is unable to allocate a color cell.

Example 10-3 Testing Color Resources

if (XAllocColor(XtDisplay(toplevel_widget), XDefaultColormapOfScreen(the_screen), &newcolor)) { ac = 0; XtSetArg (arglist[ac], XmNbackground, newcolor.pixel);ac++; XtSetValues(widget_array[k_total_order], arglist, ac); XtSetValues(main_window_widget, arglist, ac); } else s_error ("can't allocate color cell"); . . . static void s_error(problem_string) char *problem_string; { printf("%s\n", problem_string); exit(0);

If your application can function while allocating only some of the color cells, allocate the color cells according to their priority. For example, the color mixing widget tries to allocate 29 color cells to represent the colors in the various color models, as described in Section 10.4.1.3. The color mixing widget allocates the most important color cells first. If all of the 29 cells are not available, the color mix widget dims features as required.

10.5 Image Format

Applications are required to present image data (bitmaps, pixmaps) to the X server in a format that the server expects; otherwise, errors occur. This becomes especially important if your application will be displayed on multiple hardware platforms that have different image formats.

For example, assume that you used the /usr/examples/motif/bitmap.exe (UNIX) or DECW$EXAMPLES:BITMAP.EXE (OpenVMS) program to create the following bitmap. (Note that the bitmap example is not available with eXcursion for Windows NT.)

#define icon_width 24 #define icon_height 20 static char icon_bits[] = { 0x00, 0x00, 0x00, 0x00, 0x3c, 0x00, 0x00, 0x3c, 0x00, 0x00, 0x3c, 0x00, 0x00, 0x3c, 0x00, 0x00, 0x3c, 0x00, 0x00, 0x3c, 0x00, 0xfe, 0xff, 0x7f, 0xfe, 0xff, 0x7f, 0x0c, 0x00, 0x30, 0x18, 0x00, 0x18, 0x30, 0x00, 0x0c, 0x60, 0x00, 0x06, 0xc0, 0x00, 0x03, 0x80, 0x81, 0x01, 0x00, 0xc3, 0x00, 0x00, 0x66, 0x00, 0x00, 0x3c, 0x00, 0x00, 0x18, 0x00, 0x00, 0x00, 0x00};

For example, BITMAP.EXE creates bitmaps with byte_order and bitmap_bit_order equal to LSBFirst. You could use this bitmap as data for an image on VAX displays, but it might cause errors when displayed on some PC servers. If your application will be displayed on multiple hardware platforms, you must provide for this possible conflict in image formats.

The sections that follow describe how to provide for this possible conflict.

10.5.1 Image Format Implementation

X11 servers and Xlib implementations exchange protocol information to set protocol-request size maximums, establish the byte order for protocol requests, and so forth. The server determines most of these connection parameters, including the image format order to use.

To allow applications to determine the server's image format, the Xlib XOpenDisplay routine fills in a Display data with the following setup parameters provided by the server:

Display field	Description
byte_order	The image byte order. Allowed values are LSBFirst (least significant byte leftmost) and MSBFirst (most significant byte leftmost).
bitmap_bit_order	The bitmap bit order. Allowed values are LSBFirst (least significant bit leftmost) and MSBFirst (most significant bit leftmost).

Xlib includes XImageByteOrder and XBitmapBitOrder routines that your application can call to determine the image byte and bit order.

10.5.2 Determining Image Format

The XCreateImage routine does not let applications specify the byte_order and bitmap_bit_order of the data being used for the image.

Therefore, your application must function as follows:

1. Call XCreateImage to create the image. An XImage data structure is returned.
2. Explicitly set the XImage.byte_order and XImage.bit_order fields to the format of your data.
   • If your application uses only Xlib calls to create the data, you can assume that Xlib used the server's image format to create the data. In this case, call the XImageByteOrder and XBitmapBitOrder Xlib routines to determine the server's image format.
   • If your application runs on OpenVMS and uses the DECW$EXAMPLES:BITMAP.EXE program to create a bitmap to be used as your image data, set the byte_order and bitmap_bit_order fields to LSBFirst. By default, DECW$EXAMPLES:BITMAP.EXE creates bitmaps with byte_order and bitmap_bit_order equal to LSBFirst.
   • If you create data by your own mechanism, you need to know the format of the data.
3. When your application calls XPutImage to combine the image in memory with the drawable, XPutImage tests to see if the byte_order and bitmap_bit_order of the data match the format expected by the server and changes the data to the server's format if it does not match.
   Note that if your application does not explicitly set the byte_order and bitmap_bit_order fields, XPutImage uses the server's default format and does not test the format of your data. Such a situation could cause errors.