Volume 6A: Motif Programming Manual

A custom dialog

4.4.5 Pixmaps

In this section, we are going to take a closer look at how Motif supports graphic images. The Motif Label widget and

all of its subclasses can display pixmaps as their labels. The MessageBox provides the XmNsymbolPixmap resource

for specifying the image that is displayed in a dialog.

The Motif toolkit provides a number of routines for manipulating pixmaps. XmGetPixmapByDepth() and

XmGetPixmap() both create a pixmap and cache it, so that it can be reused by an application.

XmGetPixmapByDepth() is new in Motif 1.2; it provides a way to specify the depth of the pixmap that is created.

XmGetPixmap() always creates a pixmap that has the same depth as the screen on which image is created. The

caching mechanism provided by these routines is on a per−client basis; different processes cannot share pixmaps.

Whenever a new pixmap is created using one of these functions, the toolkit retains a handle to the pixmap in case

another call is made requesting the same image. If this occurs, the function returns the exact same pixmap that was

returned to the original requestor and increments an internal reference counter. In order to keep a clean house,

whenever you retrieve a pixmap using either XmGetPixmap() or XmGetPixmapByDepth(), you should call

XmDestroyPixmap() when you no longer need the image. This function decrements the reference count for the

4 Overview of the Motif Toolkit 4.4.5 Pixmaps

71

pixmap. If the reference count reaches zero, XmDestroyPixmap() actually calls XDestroyPixmap() to discard

the pixmap.

XmGetPixmapByDepth() takes the following form:

Pixmap

XmGetPixmapByDepth(screen, image_name, foreground,

background, depth)

Screen *screen;

char *image_name;

Pixel foreground;

Pixel background;

int depth;

The image_name can either be a filename or the name of an image registered using XmInstallImage(), which

we are going to describe shortly. The background and foreground colors and the depth of the pixmap are specified by

the corresponding parameters.

XmGetPixmap() takes the same form as XmGetPixmapByDepth(), minus the depth parameter.

XmGetPixmap() creates a pixmap that has the same depth as the given screen, so you cannot rely on

XmGetPixmap() to create a single−plane pixmap. The terms single−bit and single−plane are interchangeable; they

imply a pixmap with only two colors: 0 and 1. While the term bitmap usually refers to a single−plane pixmap, this is

not necessarily true outside of the X social culture. In Motif 1.2, you can use XmGetPixmapByDepth() to create a

bitmap; with Motif 1.1 you have to use an Xlib routine, XCreateBitmapFromData().

Whenever XmGetPixmapByDepth() or XmGetPixmap() is called, it looks in the cache for a

previously−created pixmap that matches the given name, colors, and depth. If the routine finds a match, it returns the

cached pixmap and increments the reference count for the image. Since the pixmaps are cached, two separate parts of

an application could have a handle to the same pixmap.

The image_name parameter is the key to where the routines get the data for the pixmap. As we just mentioned, this

parameter can either be a filename or a symbolic name previously registered using XmInstallImage(). Both

XmGetPixmap() and XmGetPixmapByDepth() use the following algorithm to determine what pixmap to return

or create:

Look in the pixmap cache for an image that has the same screen, image_name, foreground,

background, and depth as the specified image. If there is a match, return the pixmap.

•

If there is no match in the pixmap cache, look in the image cache for an image that matches the specified

image_name. If there is a match, use the image to create the pixmap that is returned.

•

Otherwise, interpret the image_name as a filename, read the pixmap data directly out of that file, and create

the pixmap.

•

The first step is fairly straightforward. The second step checks the image cache that is used internally by the Motif

toolkit. Motif defines a number of images that you can use in an application. lists the image names predefined by the

toolkit. tab(@), linesize(2); l | l lfCWp9 | l.

Image Name@Description _

background@Solid background tile 25_foreground@A 25% foreground, 75% background tile 50_foreground@A

50% foreground, 50% background tile 75_foreground@A 75% foreground, 25% background tile

horizontal@Horizontal lines tile vertical@Vertical lines tile slant_left@Left slanting lines tile slant_right@Right

slanting lines tile

_ Motif also installs a number of images at run−time to support dialog images and other random pixmaps. None of

these image names are publicly available. You can install your own images by predefining them and loading them into

4 Overview of the Motif Toolkit 4.4.5 Pixmaps

72