NAME    [Toc]    [Back]

       XmGetPixmap  -  A pixmap caching function that generates a
       pixmap, stores it in  a  pixmap  cache,  and  returns  the
       pixmap

SYNOPSIS    [Toc]    [Back]

       #include <Xm/Xm.h>

       Pixmap  XmGetPixmap (screen, image_name, foreground, background)

               Screen *screen;
               char *image_name;
               Pixel foreground;
               Pixel background;

DESCRIPTION    [Toc]    [Back]

       XmGetPixmap uses the parameter data to perform a lookup in
       the  pixmap cache to see if a pixmap has already been generated
 that matches the data.  If one is found,  a  reference
  count  is  incremented  and  the pixmap is returned.
       Applications should use XmDestroyPixmap when the pixmap is
       no longer needed.

       If  a pixmap is not found, image_name is used to perform a
       lookup in the image cache.  If an image is  found,  it  is
       used  to  generate  the  pixmap,  which is then cached and
       returned.

       If an image is not found, the  image_name  is  used  as  a
       filename,  and  a  search is made for an X10 or X11 bitmap
       file.  If it is found, the file is read, converted into an
       image,  and  cached in the image cache.  The image is then
       used to generate a pixmap, which is cached and returned.

       If image_name has a leading slash (/), it specifies a full
       pathname,  and  XmGetPixmap  opens  the file as specified.
       Otherwise, image_name specifies a filename. In  this  case
       XmGetPixmap  looks for the file along a search path specified
 by the  XBMLANGPATH  environment  variable  or  by  a
       default  search path, which varies depending on whether or
       not the XAPPLRESDIR environment variable is set.

       The XBMLANGPATH environment variable  specifies  a  search
       path  for  X bitmap files. It can contain the substitution
       field %B, where the image_name argument to XmGetPixmap  is
       substituted  for  %B. It can also contain the substitution
       fields accepted  by  XtResolvePathname.  The  substitution
       field  %T  is  always  mapped to bitmaps, and %S is always
       mapped to NULL.

       If XBMLANGPATH is not set  but  the  environment  variable
       XAPPLRESDIR is set, the following pathnames are searched:
               %B
               $XAPPLRESDIR/%L/bitmaps/%N/%B
               $XAPPLRESDIR/%l/bitmaps/%N/%B
               $XAPPLRESDIR/bitmaps/%N/%B
               $XAPPLRESDIR/%L/bitmaps/%B
               $XAPPLRESDIR/%l/bitmaps/%B
               $XAPPLRESDIR/bitmaps/%B
               $HOME/bitmaps/%B
               $HOME/%B
               /usr/lib/X11/%L/bitmaps/%N/%B
               /usr/lib/X11/%l/bitmaps/%N/%B
               /usr/lib/X11/bitmaps/%N/%B
               /usr/lib/X11/%L/bitmaps/%B
               /usr/lib/X11/%l/bitmaps/%B
               /usr/lib/X11/bitmaps/%B
               /usr/include/X11/bitmaps/%B

       If neither XBMLANGPATH nor XAPPLRESDIR is set, the following
 pathnames are searched:
               %B
               $HOME/%L/bitmaps/%N/%B
               $HOME/%l/bitmaps/%N/%B
               $HOME/bitmaps/%N/%B
               $HOME/%L/bitmaps/%B
               $HOME/%l/bitmaps/%B
               $HOME/bitmaps/%B
               $HOME/%B
               /usr/lib/X11/%L/bitmaps/%N/%B
               /usr/lib/X11/%l/bitmaps/%N/%B
               /usr/lib/X11/bitmaps/%N/%B
               /usr/lib/X11/%L/bitmaps/%B
               /usr/lib/X11/%l/bitmaps/%B
               /usr/lib/X11/bitmaps/%B
               /usr/include/X11/bitmaps/%B

       These paths are defaults  that  vendors  may  change.  For
       example,  a  vendor  may  use  different  directories  for
       /usr/lib/X11 and /usr/include/X11.

       The following substitutions are used in these  paths:  The
       image  name, from the image_name argument.  The class name
       of the application.  The display's language  string.   The
       language component of the display's language string.

       Parameter  descriptions  are  listed  below: Specifies the
       display screen on which the pixmap is  to  be  drawn.  The
       depth  of the pixmap is the default depth for this screen.
       Specifies the name of the image to be used to generate the
       pixmap  Combines  the  image  with the foreground color to
       create the pixmap if the image referenced  is  a  bit-perpixel
  image  Combines the image with the background color
       to create the pixmap if the image referenced is a bit-perpixel
 image

RETURN VALUE    [Toc]    [Back]

       Returns  a  pixmap  when  successful;  returns  XmUNSPECIFIED_PIXMAP
 if the image corresponding to  the  image_name
       cannot be found.

SEE ALSO    [Toc]    [Back]

       XmDestroyPixmap(3X),  XmGetPixmapByDepth(3X), XmInstallImage(3X), XmUninstallImage(3X)



                                                  XmGetPixmap(3X)