1XmGetPixmap(library call)                            XmGetPixmap(library call)
2
3
4

NAME

6       XmGetPixmap — A pixmap caching function that generates a pixmap, stores
7       it in a pixmap cache, and returns the pixmap
8

SYNOPSIS

10       #include <Xm/Xm.h>
11       Pixmap XmGetPixmap(
12       Screen *screen,
13       char *image_name,
14       Pixel foreground,
15       Pixel background);
16

DESCRIPTION

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
24       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
28       image_name
29                 Specifies the name of the image to be used  to  generate  the
30                 pixmap
31
32       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
36       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
40       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
44       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
49       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
68       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
75       If XBMLANGPATH is not set but the environment variable  XAPPLRESDIR  is
76       set, the following pathnames are searched:
77
78          ·  %B
79
80          ·  $XAPPLRESDIR/%L/bitmaps/%N/%B
81
82          ·  $XAPPLRESDIR/%l_%t/bitmaps/%N/%B
83
84          ·  $XAPPLRESDIR/%l/bitmaps/%N/%B
85
86          ·  $XAPPLRESDIR/bitmaps/%N/%B
87
88          ·  $XAPPLRESDIR/%L/bitmaps/%B
89
90          ·  $XAPPLRESDIR/%l_%t/bitmaps/%B
91
92          ·  $XAPPLRESDIR/%l/bitmaps/%B
93
94          ·  $XAPPLRESDIR/bitmaps/%B
95
96          ·  $HOME/bitmaps/%B
97
98          ·  $HOME/%B
99
100          ·  /usr/lib/X11/%L/bitmaps/%N/%B
101
102          ·  /usr/lib/X11/%l_%t/bitmaps/%N/%B
103
104          ·  /usr/lib/X11/%l/bitmaps/%N/%B
105
106          ·  /usr/lib/X11/bitmaps/%N/%B
107
108          ·  /usr/lib/X11/%L/bitmaps/%B
109
110          ·  /usr/lib/X11/%l_%t/bitmaps/%B
111
112          ·  /usr/lib/X11/%l/bitmaps/%B
113
114          ·  /usr/lib/X11/bitmaps/%B
115
116          ·  /usr/include/X11/bitmaps/%B
117
118       If  neither XBMLANGPATH nor XAPPLRESDIR is set, the following pathnames
119       are searched:
120
121          ·  %B
122
123          ·  $HOME/%L/bitmaps/%N/%B
124
125          ·  $HOME/%l_%t/bitmaps/%N/%B
126
127          ·  $HOME/%l/bitmaps/%N/%B
128
129          ·  $HOME/bitmaps/%N/%B
130
131          ·  $HOME/%L/bitmaps/%B
132
133          ·  $HOME/%l_%t/bitmaps/%B
134
135          ·  $HOME/%l/bitmaps/%B
136
137          ·  $HOME/bitmaps/%B
138
139          ·  $HOME/%B
140
141          ·  /usr/lib/X11/%L/bitmaps/%N/%B
142
143          ·  /usr/lib/X11/%l_%t/bitmaps/%N/%B
144
145          ·  /usr/lib/X11/%l/bitmaps/%N/%B
146
147          ·  /usr/lib/X11/bitmaps/%N/%B
148
149          ·  /usr/lib/X11/%L/bitmaps/%B
150
151          ·  /usr/lib/X11/%l_%t/bitmaps/%B
152
153          ·  /usr/lib/X11/%l/bitmaps/%B
154
155          ·  /usr/lib/X11/bitmaps/%B
156
157          ·  /usr/include/X11/bitmaps/%B
158
159       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
163       The following substitutions are used in these paths:
164
165       %B        The image name, from the image_name argument
166
167       %N        The class name of the application
168
169       %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
173       %l_%t     The language and territory component of  the  display's  lan‐
174                 guage string
175
176       %l        The language component of the display's language string
177
178       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

RETURN

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
189
190
191                                                     XmGetPixmap(library call)
Impressum