Volume 6A: Motif Programming Manual

25.3.6 Pixmaps

The UIL compiler supports pixmap values so that the various pixmap resources can be set in a UIL module. These

resources include icon−type resources such as XmNsymbolPixmap and shading−type resources such as

XmNbackgroundPixmap. There are two different forms of pixmap values that you can use in a UIL module. The

first type is an xbitmapfile, which is a reference to a bitmap defined in a separate file. For details on the X bitmap

file format, see Volume One, Xlib Programming Manual. The second type is an icon, which is defined entirely

within a UIL module. The xbitmapfile type is used to specify a bitmap file. The contents of the file are used to

create the actual bitmap. The module in the source code shows the use of this type.

/* bomb.uil −− Example using xbitmapfile type */

module bomb

procedure quit;

object root : XmMessageDialog {

arguments {

XmNmessageString = compound_string ("Segmentation Fault", separate=true) &

compound_string ("(Dumping Core)");

XmNsymbolPixmap = xbitmapfile ('bomb.xbm');

XmNdialogTitle = "Fatal Error";

};

};

end module;

This example creates a MessageDialog that uses a customized icon instead of one of the standard Motif symbols. The

output of the module is shown in the figure.

User interface of bomb.uil

The xbitmapfile value is a bitmap whose contents are defined in the file bomb.xbm. X bitmaps are a convenient

format since they can be edited and created with the standard bitmap client. Bitmaps are monochrome images, which

means that each pixel is either on or off. When you use a bitmap in a Motif widget, the "on" pixels are set to the

foreground color of the widget, and the "off" pixels are set to the background color. You can only adjust the colors of

a bitmap by changing the foreground and background color of a widget.

When you compile a module that contains an xbitmapfile value, the UIL compiler does not verify the contents or

existence of the file. The file name is saved in the UID file, and Mrm handles loading the bitmap at run−time by

25 Creating a User Interface With UIL 25.3.6 Pixmaps

686

calling XmGetPixmap(). (For details on this routine, see Section #spixmaps in Chapter 3, Overview of the Motif

Toolkit.) If Mrm cannot find or load a bitmap file, it prints a warning message by calling XtAppWarning(). If the

bitmap file is used as a resource setting, the resource is not set. When an xbitmapfile is used as a callback

argument in early releases of Motif 1.2, the application crashes when the callback is invoked. We recommend that you

only use xbitmapfile values for resource settings. You can also represent pixmaps with the UIL icon type,

which supports full color images. You define icon values entirely within a UIL module, instead of referencing an

external file. The UIL icon type is a useful feature, as neither Motif, Xt, or Xlib provides any support for defining

color pixmaps. The only drawback is that you may have to edit the icon manually using a text editor. Several

third−party vendors sell color pixmap editors that can save images using the UIL icon format; many of these editors

are part of a user interface builder (UIB) tool. The Hello, World example in Chapter 22, Introduction to UIL, used an

icon value to create the earth image. We've taken the image from that example and colorized it to illustrate the

complete syntax of an icon, as shown in the source code

/* globe.uil −− colorize the world icon */

module globe

value

world_colors : color_table (background color = ' ',

color ('black') = '*',

color ('blue') = '.',

color ('green') = 'x',

color ('white') = '=');

world_icon : icon (color_table = world_colors,

' ****** ',

' **.===..** ',

' *xx.==..x..* ',

' *xxx....xxx..* ',

' *.xxxxxxxxx.x* ',

'*.xxxxxx.xxx.xx*',

'*.xxxxxxxxx...x*',

'*.xxxxxxxxx...x*',

'*..xxxxxxxx...x*',

'*...xxxx..x....*',

'*....xx.....x..*',

' *....xx......* ',

' *....xxxxx...* ',

' *..xxxxxxx.* ',

' **xxxxxx** ',

' ****** ' );

object root : XmLabel {

arguments {

XmNlabelType = XmPIXMAP;

XmNlabelPixmap = world_icon;

XmNmarginWidth = 10;

XmNmarginHeight = 10;

};

};

end module;

An icon definition specifies a UIL color_table, which maps characters to color values, and a number of strings,

where each character represents an individual pixel in the resulting pixmap. The output of this module is shown in the

figure. Obviously, the output is not in color, but you can tell from the different degrees of shading that the pixels are

different colors.

25 Creating a User Interface With UIL 25.3.6 Pixmaps

687

User interface of globe.uil

Although color_table is a distinct UIL type, a color_table value is only useful in the context of an icon

definition. A color_table value consists of the keyword color_table followed by a parenthesized list of color

mappings. The form of each mapping is a color or rgb value followed by an equal sign and a single character,

which is used to represent that color in an icon definition. You can also use the special colors foreground color

and background color. These colors are taken from the widget in which an icon appears. We use the

background color around the earth so that it blends in smoothly with the Label.

When you use a color value in a color_table, you can specify how the color appears on a monochrome display,

or when Mrm cannot allocate color, you can specify either foreground or background after the color name. For

example, we can ensure that our earth icon looks reasonable on a monochrome display by using the following

color_table definition:

world_colors : color_table (background color = ' ',

color ('black', foreground) = '*',

color ('blue', background) = '.',

color ('green', foreground) = 'x',

color ('white', foreground) = '=');

Without these attributes, each color is mapped to white on a monochrome display. We recommend specifying the

foreground and background attributes in a color_table, as they ensure that an icon looks reasonable. These

attributes only affect colors that are allocated as part of a color_table; if you specify the attribute in a color that is

used as a resource or a callback argument, the UIL compiler quietly ignores the attribute.

The UIL compiler does not support the foreground and background attributes with rgb values. However,

unlike a color value, an rgb value maps predictably to black or white based on its intensity. The mapping of a

monochrome color value depends on the X server's color database, which varies from server to server. If you must

use rgb values in a color_table, you should use rgb values for all of the mappings and be sure to view the

resulting icon on a monochrome screen. Avoid mixing color and rgb values in the same color_table, since the

mapping of a color value depends on the foreground and background colors of a widget, while the mapping of an

rgb value is always the same.

An icon definition consists of the keyword icon followed by an optional color_table setting and a list of

equal−length strings that define the rows of the pixmap. If you leave out the color_table setting, as we did in the

original world_icon definition, the following default color_table is used:

color_table (background color = ' ',

foreground color = '*');

If you specify a color_table, it must be the first entry in the icon definition, as in the source code The pixmap

definition consists of an arbitrary number of comma−separated strings that correspond to the rows of the pixmap.

25 Creating a User Interface With UIL 25.3.6 Pixmaps

688

Each pixel in the pixmap is defined using one of the characters from the color_table. Any other characters are

illegal and are flagged as such by the UIL compiler. The compiler also verifies that all of the strings in an icon

definition are the same length. Pixmap values are another one of the types that cannot be fetched with

MrmFetchLiteral() because Mrm needs a Screen pointer, as well as background and foreground colors, in

order to create a pixmap. Mrm provides two specialized functions for fetching pixmap values:

MrmFetchBitmapLiteral() and MrmFetchIconLiteral(). MrmFetchBitmapLiteral() is new in

Motif 1.2; it takes the following form:

Cardinal

MrmFetchBitmapLiteral(hierarchy, name, screen, display, pixmap_return,

width_return, height_return)

MrmHierarchy hierarchy;

String name;

Screen *screen;

Display *display;

Pixmap *pixmap_return;

Dimension *width_return;

Dimension *height_return;

This routine fetches an icon value in the form of a Bitmap, which is a Pixmap with a depth of 1. The

hierarchy argument specifies the Mrm hierarchy that contains the exported icon value specified by the name

argument. If Mrm finds the icon, it creates the bitmap on the screen of the display and returns it in

pixmap_return. The width and height of the pixmap are returned in width_return and height_return. A

return value of MrmSUCCESS indicates that the pixmap has been fetched and created successfully. In this case, the

application is responsible for freeing the pixmap with XFreePixmap().

The icon that is specified can only use the colors foreground color and background color. These colors

represent the values of 1 and 0, respectively, in the resulting bitmap. If you use any other colors, the function fails and

returns MrmNOT_VALID. The function can also return MrmBAD_HIERARCHY if the hierarchy argument is not a

valid Mrm hierarchy, MrmNOT_FOUND if Mrm cannot find the icon in the hierarchy, MrmWRONG_TYPE if Mrm

finds a value but it is not an icon, or MrmFAILURE if anything else goes wrong.

You can use the bitmap returned by MrmFetchBitmapLiteral() anywhere that a bitmap or a bit mask is

needed. Common uses include setting the window manager icon of an application or defining a cursor by calling

XCreatePixmapCursor().

You can also fetch pixmaps with MrmFetchIconLiteral(). This function can retrieve both icon and

xbitmapfile values. The routine returns a Pixmap whose depth is the default depth of the screen as returned by

the DefaultDepthOfScreen() macro. It takes the following form:

Cardinal

MrmFetchIconLiteral(hierarchy, name, screen, display, foreground,

background, pixmap_return);

MrmHierarchy hierarchy;

String name;

Screen *screen;

Display *display;

Pixel foreground;

Pixel background;

Pixmap *pixmap_return;

The first four arguments are the same as for MrmFetchBitmapLiteral(). The foreground and

background arguments specify the colors of the pixmap. When you fetch an xbitmapfile, "on" pixels are set to

the foreground color and "off" pixels are set to the background color. When you fetch a UIL icon, it specifies the

25 Creating a User Interface With UIL 25.3.6 Pixmaps

689