1XmGetPixmap(library call) XmGetPixmap(library call)
2
6 XmGetPixmap — A pixmap caching function that generates a pixmap, stores
7 it in a pixmap cache, and returns the pixmap
8
10 #include <Xm/Xm.h>
11 Pixmap XmGetPixmap(
12 Screen *screen,
13 char *image_name,
14 Pixel foreground,
15 Pixel background);
16
18 XmGetPixmap uses the parameter data to perform a lookup in the pixmap
19 cache to see if a pixmap has already been generated that matches the
20 data. If one is found, a reference count is incremented and the pixmap
21 is returned. Applications should use XmDestroyPixmap when the pixmap is
22 no longer needed.
23 screen Specifies the display screen on which the pixmap is to be
25 drawn. The depth of the pixmap is the default depth for this
26 screen.
27 image_name
29 Specifies the name of the image to be used to generate the
30 pixmap
31 foreground
33 Combines the image with the foreground color to create the
34 pixmap if the image referenced is a bit-per-pixel image
35 background
37 Combines the image with the background color to create the
38 pixmap if the image referenced is a bit-per-pixel image
39 If a pixmap is not found, image_name is used to perform a lookup in the
41 image cache. If an image is found, it is used to generate the pixmap,
42 which is then cached and returned.
43 If an image is not found, the image_name is used as a filename, and a
45 search is made for an X10 or X11 bitmap file. If it is found, the file
46 is read, converted into an image, and cached in the image cache. The
47 image is then used to generate a pixmap, which is cached and returned.
48 If image_name has a leading slash (/), it specifies a full pathname,
50 and XmGetPixmap opens the file as specified. Otherwise, image_name
51 specifies a filename. In this case, XmGetPixmap looks for the file
52 along a search path specified by the XBMLANGPATH environment variable
53 or by a default search path, which varies depending on whether or not
54 the XAPPLRESDIR environment variable is set. The default search path
55 contains a lot of directories. Therefore, XmGetPixmap will need a rel‐
56 atively long time to search through all these directories for pixmaps
57 and bitmaps. Applications that use a lot of pixmaps and bitmaps will
58 probably run more quickly if XBMLANGPATH is set to a short list of
59 directories. In addition to X bitmap files (XBM), Motif also supports
60 XPM (X Pixmap) file formats and, from version 2.3, JPEG and PNG image
61 formats. (Note that support of JPEG and PNG image format is an
62 optional feature of Motif, in order to check if current version sup‐
63 ports PNG ang JPEG image formats the PNG_SUPPORT and JPEG_SUPPORT
64 macros should be checked correspondingly.) The XBMLANGPATH specifies
65 the path for both XBM, XPM, PNG and JPEG files. Refer to the XmGet‐
66 PixmapByDepth reference page for further details.
67 The XBMLANGPATH environment variable specifies a search path for X bit‐
69 map files. It can contain the substitution field %B, where the
70 image_name argument to XmGetPixmap is substituted for %B. It can also
71 contain the substitution fields accepted by XtResolvePathname. The
72 substitution field %T is always mapped to bitmaps, and %S is always
73 mapped to NULL.
74 If XBMLANGPATH is not set but the environment variable XAPPLRESDIR is
76 set, the following pathnames are searched:
77 · %B
79 · $XAPPLRESDIR/%L/bitmaps/%N/%B
81 · $XAPPLRESDIR/%l_%t/bitmaps/%N/%B
83 · $XAPPLRESDIR/%l/bitmaps/%N/%B
85 · $XAPPLRESDIR/bitmaps/%N/%B
87 · $XAPPLRESDIR/%L/bitmaps/%B
89 · $XAPPLRESDIR/%l_%t/bitmaps/%B
91 · $XAPPLRESDIR/%l/bitmaps/%B
93 · $XAPPLRESDIR/bitmaps/%B
95 · $HOME/bitmaps/%B
97 · $HOME/%B
99 · /usr/lib/X11/%L/bitmaps/%N/%B
101 · /usr/lib/X11/%l_%t/bitmaps/%N/%B
103 · /usr/lib/X11/%l/bitmaps/%N/%B
105 · /usr/lib/X11/bitmaps/%N/%B
107 · /usr/lib/X11/%L/bitmaps/%B
109 · /usr/lib/X11/%l_%t/bitmaps/%B
111 · /usr/lib/X11/%l/bitmaps/%B
113 · /usr/lib/X11/bitmaps/%B
115 · /usr/include/X11/bitmaps/%B
117 If neither XBMLANGPATH nor XAPPLRESDIR is set, the following pathnames
119 are searched:
120 · %B
122 · $HOME/%L/bitmaps/%N/%B
124 · $HOME/%l_%t/bitmaps/%N/%B
126 · $HOME/%l/bitmaps/%N/%B
128 · $HOME/bitmaps/%N/%B
130 · $HOME/%L/bitmaps/%B
132 · $HOME/%l_%t/bitmaps/%B
134 · $HOME/%l/bitmaps/%B
136 · $HOME/bitmaps/%B
138 · $HOME/%B
140 · /usr/lib/X11/%L/bitmaps/%N/%B
142 · /usr/lib/X11/%l_%t/bitmaps/%N/%B
144 · /usr/lib/X11/%l/bitmaps/%N/%B
146 · /usr/lib/X11/bitmaps/%N/%B
148 · /usr/lib/X11/%L/bitmaps/%B
150 · /usr/lib/X11/%l_%t/bitmaps/%B
152 · /usr/lib/X11/%l/bitmaps/%B
154 · /usr/lib/X11/bitmaps/%B
156 · /usr/include/X11/bitmaps/%B
158 These paths are defaults that vendors may change. For example, a ven‐
160 dor may use different directories for /usr/lib/X11 and
161 /usr/include/X11.
162 The following substitutions are used in these paths:
164 %B The image name, from the image_name argument
166 %N The class name of the application
168 %L The display's language string. This string is influenced by
170 XtSetLanguageProc. The default string is determined by call‐
171 ing setlocale(LC_ALL, NULL).
172 %l_%t The language and territory component of the display's lan‐
174 guage string
175 %l The language component of the display's language string
177 The contents of the file must conform to the rules for X11 bitmap
179 files. In other words, Motif can read any X11 conformant bitmap file.
180
182 Returns a pixmap when successful; returns XmUNSPECIFIED_PIXMAP if the
183 image corresponding to image_name cannot be found.
184
186 XmDestroyPixmap(3), XmGetPixmapByDepth(3), XmInstallImage(3), and
187 XmUninstallImage(3).
188 XmGetPixmap(library call)