|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.|
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().
XmtGetBitmap() and XmtGetPixmap() look up and return named bitmaps or pixmaps. These functions are very flexible; they form the basis of the Xmt String-to-Bitmap and String-to Pixmap converters, and look for bitmap and pixmap data in a number of different places:
o the image cache,
o the resource database, and
o the applications 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:
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:
The components of these searches are the following:
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.
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.
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:
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.
a. The user path specified by the userConfigPath resource and the XUSERFILESEARCHPATH and XAPPLRESDIR resources (see Chapter 6 for details.) b. The path, if any, specified by the pixmapFilePath application resource. The default for this resource is NULL, so this search is not usually performed. c. The path specified by the configPath application resource. d. The standard system path (see Chapter 6 for details.) 5. Finally, XmtFindFile() is called again, to look for an XBM file in four analogous places:
a. The user path. b. The path, if any, specified by the bitmapFilePath application resource. c. The path specified by configPath. d. The system path.
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.
Chapter 5, Using Icons,
Chapter 4, Using Color,
Chapter 6, Managing Auxiliary Files,
XmtLookupBitmap(), XmtLookupBitmask(), XmtLookupPixmap(), XmtParseXpmData(), XmtParseXpmFile(), XmtRegisterImage(), XmtRegisterXbmData(), XmtReleasePixmap().
|Xmt||XMTGETBITMAP (3)||Motif Tools|