NAME

SYNOPSIS

ARGUMENTS

w

A widget or object that specifies the screen, visual, colormap, and depth of the Pixmap to be returned.

table

For XmtGetPixmap(), this argument defines symbolic colors to be used in converting XPM data to a pixmap. If you specify NULL, the value of the colorTable application resource will be used.

name

The name of the bitmap or pixmap to be obtained.

RETURNS

These functions return None if no bitmap or pixmap data with the specified name is found. Otherwise, XmtGetBitmap() returns a single-plane bitmap, and XmtGetPixmap() returns a multi-plane pixmap with the same depth and screen as w, containing the image specified by name, with colors set according to the visual and colormap of w and according to table. The returned bitmap or pixmap should be freed when no longer needed with XmtReleasePixmap().

DESCRIPTION

• the image cache,

• the resource database, and

• the application's auxiliary files.

The subsections below explain how these functions search each of those places. The descriptions below explain how XmtGetPixmap() searches for XPM pixmap data or XBM bitmap data to convert to a pixmap. XmtGetBitmap() works in exactly the same way, except that it only performs the searches for bitmap data.

Because XmtGetPixmap() forms the basis for the Xmt pixmap resource converter, the name argument to that function may also specify a a color table for use in the conversion. This will be explained below.

Note that any bitmap or pixmap returned by these functions will be cached in the XmtImage cache. When they will no longer be needed they should be released with XmtReleasePixmap(). This will decrement a reference count, and when that count reaches zero, the bitmap or pixmap will be destroyed.

Searching the Image Cache

The first place XmtGetPixmap() looks for the named pixmap is in the Xmt image cache. It calls XmtLookupPixmap() (XmtGetBitmap() calls XmtLookupBitmap()) to check the cache for XPM data registered with XmtRegisterImage() or for XBM data registered with XmtRegisterXbmData().

Unless you have registered pixmap or bitmap data with one of these relatively low-level functions, the named pixmap or bitmap will not be found in the image cache. Note however, that whenever XmtGetPixmap() or XmtGetBitmap() find named image data elsewhere, they register that data in the cache by name so that it will be found quickly by subsequent searches.

Searching the Resource Database

If data is not found in the image cache, then XmtGetPixmap() next checks the resource database for a definition of the named pixmap or bitmap. First, it looks for XPM data specified as the value of a resource that matches the following pattern:

_Pixmaps_.visual.depth.size.language.territory.codeset.name

If it does not find pixmap data under _Pixmaps_ in the resource database, then XmtGetPixmap() (as well as XmtGetBitmap()) looks for XBM bitmap data under _Bitmaps_ for a resource that matches the following pattern:

_Bitmaps_.size.language.territory.codeset.name

The components of these searches are the following:

visual

The default visual type of the screen. This will be one of the strings ``color'', ``gray'', or ``monochrome''.

depth

The default depth, in bitplanes, of the screen. Typical values are ``1'' and ``8''.

size

The size or ``resolution'' of the screen, as determined by the number of pixels. This will be one of the strings ``small'' (screen is less than 750 pixels wide), ``medium'', or ``large'' (screen is more than 1150 pixels wide).

language

The ``language part'' of the language string.

territory

The ``territory part'' of the language string.

codeset

The ``codeset part'' of the language string.

name

The name argument.

Note that the visual type and depth are not used when search ing for bitmap data-bitmaps do not include color data, and so this kind of customization is not required.

If resources matching either of the above patterns are found in the resource database their values are assumed to be XPM or XBM data. This data is parsed, registered by name in the image cache, and then converted to a pixmap or bitmap.

You can convert XPM and XBM files as necessary for inclusion in the resource database with the xpm2res and xbm2res scripts.

Searching Auxiliary Files

If the searches of the image cache and resource database fail, then name is assumed to be the name of a file. The following list explains how XmtGetPixmap() looks for the file. Recall that XmtGetBitmap() works in the same way, except that it only looks for XBM data; never XPM pixmap data.

The descriptions below assume familiarity with the function XmtFindFile(). Note that when XmtFindFile() is used to look for pixmap data, it is always passed a type of ``pixmaps'' and a suffix of ``.xpm''. When XmtFindFile() is called to look for bitmap data, it is passed a type of ``bitmaps'' and a suffix of ``.xbm''.

1.

If the name begins with ``/'', ``./'', or ``../'', then it is assumed to be an absolute or relative filename, and no search is required; it is just read directly.

2.

If the XPMLANGPATH environment variable is set, then XmtFindFile() is used to search this path for an XPM file with the specified name. XPMLANGPATH is an Xmt environment variable that is analogous to XBMLANGPATH variable that is searched by the Motif function XmGetPixmap().

3.

If the XBMLANGPATH environment variable is defined, then XmtFindFile() is used to search that path for an XBM file. This is done for compatibility with the search done by XmGetPixmap().

4.

Next, XmtFindFile() is called again to search for an XPM file in four more places:

5.

Finally, XmtFindFile() is called again, to look for an XBM file in four analogous places:

If an XPM or XBM file is found in any of these searches, then it is read in, and its data is parsed and stored by name in the image cache. Then the data is used to create a pixmap or bitmap which is returned.

Specifying a Color Table

As mentioned earlier, XmtGetPixmap() (but not XmtGetBitmap()) can parse a color table specification as part of its supplied name. If name contains a `:', the part before the colon (with whitespace removed) is taken to be the pixmap name, and the part after the colon is taken to be a color table specification, and is parsed by the Xmt color table resource converter. (See Chapter 4, Using Color, for the syntax.)

When a color table is specified in this way, it is created with the specified table as its parent. If no table argument was specified, then the color table is created with the default application color table as its parent. In either case the resulting ``chained'' color table is used to lookup all symbolic colors for the pixmap.

If XmtGetPixmap() finds XPM data, then the color table is used to look up any symbolic colors in the XPM data. If XmtGetPixmap() finds bitmap data, then the symbolic colors ``foreground'' and ``background'' are looked up and used as the foreground and background colors for the pixmap created from this bitmap data.

SEE ALSO