XmGetPixmapByDepth(3X)

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

SYNOPSIS
     #include <Xm/Xm.h>

     Pixmap XmGetPixmapByDepth (screen, image_name,foreground, background, depth)
          Screen    *screen;
          char      *image_name;
          Pixel     foreground;
          Pixel     background;
          int       depth;


VERSION
     This page documents version 1.2 of the Motif library.

DESCRIPTION
     XmGetPixmapByDepth 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  matching 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, 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, con-
     verted  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
     XmGetPixmapByDepth  opens  the  file  as  specified.  Otherwise, image_name
     specifies a filename.  In this case XmGetPixmapByDepth 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 XAP-
     PLRESDIR 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 ar-
     gument to XmGetPixmapByDepth 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:


     %B   The image name, from the image_name argument

     %N   The class name of the application

     %L   The display's language string

     %l   The language component of the display's language string


     Parameter descriptions are listed below:


     screen    Specifies the display screen on which the pixmap is to be drawn

     image_nameSpecifies the name of the image to be used to generate the pixmap

     foregroundCombines the image with the foreground color to create the pixmap
               if the image referenced is a bit-per-pixel image

     backgroundCombines the image with the background color to create the pixmap
               if the image referenced is a bit-per-pixel image

     depth     Specifies the depth of the pixmap


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

RELATED INFORMATION
     XmDestroyPixmap(3X), XmInstallImage(3X), and XmUninstallImage(3X).

                                                          XmGetPixmapByDepth(3X)