This chapter describes a set of interoperability coding recommendations you should follow if you are writing DECwindows applications for multiple hardware platforms. The chapter includes code examples that demonstrate the interoperability coding recommendations.

The chapter provides information on the following topics:

• Font fallback
• Screen independence
• Color support
• Image format

When you write a DECwindows application, you cannot always be sure what type of hardware will be used to display it. For example, a user might run an application on an OpenVMS cluster node and display it on a PC screen. If your application makes assumptions about the size of the screen, it might not display correctly.

It is possible to code your DECwindows application so that it is not dependent upon the display hardware. The sections that follow provide interoperability coding recommendations and examples.

10.2 Font Fallback

You should use system-default fonts whenever possible to ensure that your application appears well integrated in the Motif environment. However, you might need to use a particular font for some application-specific purpose. DECwindows lets you specify the fonts for your application to use. The term font fallback refers to using a second-choice font if the font you specified is not available.

The fonts bundled with the DECwindows server include fonts supplied by Digital as well as fonts supplied with the X11 R5 release. The fonts supplied by Digital are available with all implementations of the DECwindows server. However, if you run a DECwindows application and display the results on some other vendor's workstation or PC, the fonts supplied by Digital are not available. Your application must be able to handle this case and use another font.

How your application deals with font fallback depends on whether the application uses UIL or the Toolkit routines to specify fonts:

• If your application specifies fonts through UIL by using the FONT function and the VALUE declaration, you do not need to be concerned with font fallback because the DECwindows Motif Toolkit provides it for you according to the algorithm described in Section 10.2.2.
• If your application specifies fonts through the Toolkit routines, you can use the DXmLoadQueryFont or DXmFindFontFallback routines to determine a fallback font. The DXmLoadQueryFont and DXmFindFontFallback routines also use the algorithm described in Section 10.2.2 to determine the fallback font.
• You can explicitly use only fonts that are common to both DECwindows and the X11 R5 release.

The sections that follow provide additional detail on font fallback.

10.2.1 Font Naming Convention

Part IV of the X Window System by Scheifler and Gettys contains a complete description of the X11 font naming convention, which is summarized here for convenience. (The VMS DECwindows Xlib Programming Volume also contains this same information.)

Xlib font names consist of the following fields, in left-to-right order:

1. Foundry that supplied the font, or the font designer
2. Typeface family of the font
3. Weight (book, demi, medium, bold, light)
4. Slant (R (roman), I (italic), O (oblique))
5. Width per horizontal unit of the font (normal, wide, double wide, narrow)
6. Additional style font identifier (usually blank)
7. Pixel font size
8. Point size (8, 10, 12, 14, 18, 24) in decipoints
9. X Resolution in pixels/dots per inch
10. Y Resolution in pixels/dots per inch
11. Spacing (P (proportional), M (monospaced), or C (character cell))
12. Average width of all characters in the font
13. Character set registry
14. Character set encoding

The full name of a representative font is as follows:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 -ADOBE-ITC Avant Garde Gothic-Book-R-Normal--14-100-100-100-P-80-ISO8859-1

In the example:

1. The font foundry is Adobe.
2. The font is named ITC Avant Garde Gothic.
3. The Font weight is book.
4. The font slant is R (roman).
5. The width per font unit is normal.
6. The additional style font identifier is blank.
7. The pixel size is 14.
8. The point size is 10 (derived from 100/10).
9. The horizontal resolution in dots per inch (dpi) is 100.
10. The vertical resolution in dots per inch (dpi) is 100. (When the dpi is 100, 14 pixels are required to represent a 10-point font.)
11. The font is proportionally spaced.
12. The average width of characters is 80.
13. The character set registry is ISO8859.
14. The character set encoding is Latin-1.

The DECwindows Motif Toolkit first tries to load the specified font. If it is unable to successfully load the font, the DECwindows Motif Toolkit uses the fallbacks listed in Table 10-1 and Table 10-2.

The font fallback implementation uses whatever matching fonts are available on the display including, but not limited to, the DECwindows and X11 R5 server fonts. Asterisks indicate a wildcard.

Table 10-1 Font Fallbacks

Field	Fallback
(Foundry)
All families but Terminal	Adobe
(Family)
ITC Avant Garde Gothic	Helvetica
ITC Lubalin Graph	New Century Schoolbook
Menu	Helvetica
ITC Souvenir	Times
Any other	Fixed
(Weight)
Menu family	Bold (overrides any other weight remapping)
Book weight	Medium
Demi weight	Bold
Light weight	Medium
(Style)
ITC Lubalin Graph family and O slant	Italic
(Width)
All AVERAGE_WIDTH values	*
(Pixel Size When Not DPI 100)
*	*
(Pixel Size When DPI 100)
10	11
13	14
16	17
19	20
24	25
33	34

Table 10-2 Terminal Font Fallbacks

Field	Fallback
(Foundry)
*	*
When 75 dpi	DEC
When 100 dpi	Bitstream
(Pixel Size)
*	*
When 75 dpi	14
When 100 dpi	18
(Setwidth Name)
All SETWIDTH_NAME values	Normal
(Point Size)
All POINT_SIZE values	140
(Average Width)
All AVERAGE_WIDTH values	*

The Fixed font is returned if the family, weight, slant, width, character set registry, or character set encoding font name fields are wildcarded or if the font name syntax cannot be parsed (for example, if hyphens are not positioned correctly or are missing). Note that the terminal line-drawing characters are not available in the Fixed font.

10.2.3 Using Common Fonts

If your application specifies fonts through the Toolkit routines but does not use the DXmLoadQueryFont or DXmFindFontFallback routines to determine a fallback font, the application should use only fonts common to both the DECwindows and X11 R5 servers.

The font fallback policy implemented through UIL and the DXmLoadQueryFont and DXmFindFontFallback routines provides the best assurance of finding a suitable font. However, if your application uses only fonts common to both the DECwindows and X11 R5 servers, the application will be able to display on other vendors' workstations that support the X11 fonts.

Font families common to both DECwindows and X11 R5 are as follows:

• Courier
• Helvetica
• New Century Schoolbook
• Symbol
• Times

You can use FONT function and the VALUE declaration to create font lists through UIL. For example, the following UIL code segment defines a font by using the FONT function and the VALUE declaration:

VALUE k_button_font : font('-ADOBE-Courier-Bold-R-Normal--14-140-75-75-M-90-ISO8859-1');

If this font is not available when the widget associated with it is fetched, the DECwindows Motif Toolkit determines the fallback font as described in Section 10.2.2.

If for some reason the font fallback implementation is not appropriate for your application, do not specify the font through UIL. Instead, use the Toolkit routines to select a fallback font.

10.2.5 Implementing Font Fallback Through Toolkit Routines

The program in Example 10-1 creates a font list and uses it to specify the font used in a CSText widget.

Example 10-1 Font Fallback Through Toolkit Routines

#include <stdio> #include <Mrm/MrmAppl.h> #include <DXm/DXmCSText.h> static void change_cs(); static void ok_text(); XmString cstring; Widget toplevel, text_shell, text_label, text_w, ok_button; int main(argc, argv) unsigned int argc; char **argv; { XtAppContext app_context; Arg arglist[15]; int ac = 0; (1)XFontStruct *font; (2)XmFontList font_list; XtCallbackRec callback_arg[2]; toplevel = XtAppInitialize(&app_context, "example", NULL, 0, &argc, argv, NULL, NULL, 0); ac = 0; cstring = XmStringCreateLtoR("User Defined", XmSTRING_ISO8859_1); XtSetArg( arglist[ac], XmNdialogTitle, cstring);ac++; XtSetArg( arglist[ac], XmNallowOverlap, TRUE);ac++; XtSetArg( arglist[ac], XmNheight, 300);ac++; XtSetArg( arglist[ac], XmNwidth, 300);ac++; XtSetArg( arglist[ac], XmNresizePolicy, XmRESIZE_GROW);ac++; text_shell = XmCreateBulletinBoard(toplevel, "CSText", arglist, ac ); XmStringFree(cstring); ac = 0; cstring = XmStringCreateLtoR("Enter a 10-letter title\nfor this widget", XmSTRING_ISO8859_1); XtSetArg( arglist[ac], XmNlabelString, cstring);ac++; XtSetArg( arglist[ac], XmNx, 90);ac++; XtSetArg( arglist[ac], XmNy, 20);ac++; text_label = XmCreateLabel(text_shell, "textlabel", arglist, ac ); XmStringFree(cstring); (3)font = DXmLoadQueryFont( XtDisplay (toplevel), "-ADOBE-Courier-Bold-R-Normal--14-140-*-*-M-90-ISO8859-1"); (4)if (font == NULL){ printf("Fonts Are Not Available"); exit(0); } (5)font_list = XmStringCreateFontList(font, XmSTRING_ISO8859_1); callback_arg[0].callback = change_cs; callback_arg[0].closure = 0; callback_arg[1].callback = NULL; callback_arg[1].closure = NULL; ac = 0; (6)XtSetArg( arglist[ac], XmNfontList, font_list ); ac++; XtSetArg( arglist[ac], XmNx, 40);ac++; XtSetArg( arglist[ac], XmNy, 100);ac++; XtSetArg( arglist[ac], XmNrows, 2 ); ac++; XtSetArg( arglist[ac], XmNcolumns, 35 ); ac++; XtSetArg( arglist[ac], XmNmaxLength, 10 ); ac++; XtSetArg( arglist[ac], XmNactivateCallback, callback_arg);ac++; text_w = DXmCreateCSText(text_shell, "textwidget", arglist, ac ); (7)XmFontListFree (font_list ); XtManageChild(text_w); XtManageChild(text_label); XtManageChild(text_shell); XtRealizeWidget(toplevel); XtAppMainLoop(app_context); } . . .

1. The variable font is declared as a pointer to an X font structure.
2. The variable font_list is declared as a font list.
3. The DXmLoadQueryFont routine attempts to load the specified font. If that font fails to load, a fallback font is loaded. If a font is successfully loaded, a pointer to the XFontStruct of the font is returned. Applications that require identification of the returned font can access the font's properties to obtain the needed information.
4. If a font cannot be loaded for any reason, NULL is returned.
   You could also use the DXmFindFontFallback routine, which allows you to specify a font name and receive a fallback font name in return. Your application could then call the Xlib XLoadFont routine to attempt to load the fallback font.
5. The XmStringCreateFontList routine creates a font list. In the example, the first argument to the XmStringCreateFontList routine specifies the X font structure returned by the DXmLoadQueryFont routine. The second argument to this routine is a constant that identifies the character set.
6. The font list is used to specify the font the CSText widget will use to display text.
7. After using the font list, free the memory associated with it.

You should not make any assumptions about the screen on which your application will display. This section discusses several interoperability issues related to screen independence.

10.3.1 Screen DPI Assumptions

As described in Section 10.2.2, not all screens support both 75 DPI and 100 DPI fonts. To avoid screen interoperability problems, you can use wildcards for the x and y resolution fields. The first example shows specific values for the x and y resolution fields:

VALUE k_button_font : font('-ADOBE-Courier-Bold-R-Normal--14-140-75-75-M-90-ISO8859-1');

This example uses wildcards for the x and y resolution fields:

VALUE k_button_font : font('-ADOBE-Courier-Bold-R-Normal--14-140-*-*-M-90-ISO8859-1');

10.3.2 MultiHead Server Support

DECwindows supports servers with multiple screens. Such systems are called multiheaded displays.

DECwindows servers currently support a maximum of two screens. However, other vendor's server implementations might support additional screens.

When you create a DECwindows application, you should not make any assumptions as to whether the application will run on screen zero (the default), screen one, or any other screen of a display. Rather, you should let the user specify the screen by using command line arguments, the SET DISPLAY command on OpenVMS systems, or the DISPLAY environment variable on UNIX and Windows NT systems.

If you hard code a screen number of zero, the user cannot display the application on any other screen. If you hard code a screen number of one, the user cannot display the application on any other screen.

Hard-coding screen numbers can result in severe limitations. For example, if you hard code a screen number of one and the server has only the default screen (screen zero), your application will not be able to open the display.

Note that there is no way for your application to determine in advance of opening the display how many screens are attached. All of the Xlib routines that return screen information require that you first open the display. For example, your application must first open the display before it can call Xlib routines such as XScreenCount or XScreenofDisplay.

10.3.2.1 Using XtAppInitialize to Specify a Screen

DECwindows Motif Toolkit applications generally call the XtAppInitialize routine to initialize the toolkit and open the display. XtAppInitialize uses command line arguments or, if command line arguments are not present, the result of the last command used to set the DISPLAY environment variable (UNIX and Windows NT) or DISPLAY logical (OpenVMS) to determine the display and screen to use. In this way, XtAppInitialize uses the "default" display and screen; it does not otherwise explicitly set the display or screen to use.

10.3.2.2 Using XtOpenDisplay to Specify a Screen

DECwindows Motif Toolkit applications that want to open a connection to a specific display or screen (without also initializing the toolkit) can call the XtOpenDisplay routine to open a display, initialize it, and add it to an application context.

XtOpenDisplay calls the Xlib routine XOpenDisplay with the specified display name. If the display name argument is null, XtOpenDisplay uses the current value of the display option specified in the command-line argvalue argument. If no display is specified in argvalue, XtOpenDisplay uses the result of the last command that defined DISPLAY.

The format of the display name argument is hostname:number.screen (UNIX and Windows NT) or hostname::number.screen (OpenVMS). The element hostname is the network name of the host, number is the number of the server on the host, and screen is the number of the screen to use. Currently, the screen number can be zero or one for DECwindows servers; additional screens are possible in other vendors' server implementations.

If you specifically wanted your application to use screen one, you could specify screen one in a call to XtOpenDisplay and then test to see if XtOpenDisplay returns NULL to indicate failure.

• If XtOpenDisplay returns non-NULL, screen one is attached.
• If XtOpenDisplay returns NULL, call XtOpenDisplay without specifying a screen.

If your application will be displayed on PC or other small screens, you must make sure that your application windows are not too big to fit on the screen.

This section describes two possible implementations for adjusting window size:

• Implementing the window with scroll bars so that the user can navigate throughout the window
• Using the DXmNfitToScreenPolicy resource to reduce the size of dialog boxes and add scroll bars

Other implementations are also possible.