GNU Info

(elisp)Defining Images

---

Next: Showing Images Prev: Other Image Types Up: Images

---

Enter node , (file) or (file)node

Defining Images
---------------

   The functions `create-image', `defimage' and `find-image' provide
convenient ways to create image descriptors.

 - Function: create-image file &optional type &rest props
     This function creates and returns an image descriptor which uses
     the data in FILE.

     The optional argument TYPE is a symbol specifying the image type.
     If TYPE is omitted or `nil', `create-image' tries to determine the
     image type from the file's first few bytes, or else from the
     file's name.

     The remaining arguments, PROPS, specify additional image
     properties--for example,

          (create-image "foo.xpm" 'xpm :heuristic-mask t)

     The function returns `nil' if images of this type are not
     supported.  Otherwise it returns an image descriptor.

 - Macro: defimage variable doc &rest specs
     This macro defines VARIABLE as an image name.  The second argument,
     DOC, is an optional documentation string.  The remaining
     arguments, SPECS, specify alternative ways to display the image.

     Each argument in SPECS has the form of a property list, and each
     one should specify at least the `:type' property and the `:file'
     property.  Here is an example:

          (defimage test-image
            '((:type xpm :file "~/test1.xpm")
              (:type xbm :file "~/test1.xbm")))

     `defimage' tests each argument, one by one, to see if it is
     usable--that is, if the type is supported and the file exists.  The
     first usable argument is used to make an image descriptor which is
     stored in the variable VARIABLE.

     If none of the alternatives will work, then VARIABLE is defined as
     `nil'.

 - Function: find-image specs
     This function provides a convenient way to find an image
     satisfying one of a list of image specifications SPECS.

     Each specification in SPECS is a property list with contents
     depending on image type.  All specifications must at least contain
     the properties `:type TYPE' and either `:file FILE' or
     `:data DATA', where TYPE is a symbol specifying the image type,
     e.g. `xbm', FILE is the file to load the image from, and DATA is a
     string containing the actual image data.  The first specification
     in the list whose TYPE is supported, and FILE exists, is used to
     construct the image specification to be returned.  If no
     specification is satisfied, `nil' is returned.

     The image is looked for first on `load-path' and then in
     `data-directory'.