Function: find-image

find-image is an autoloaded and byte-compiled function defined in image.el.gz.

Signature

(find-image SPECS &optional CACHE)

Documentation

Find an image, choosing one of a list of image specifications.

SPECS is a list of image specifications.

Each image specification in SPECS is a property list. The contents of a specification are image type dependent. 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 specification whose TYPE is supported, and FILE exists, is used to construct the image specification to be returned. Return nil if no specification is satisfied.

If CACHE is non-nil, results are cached and returned on subsequent calls.

The image is looked for in image-load-path.

Image files should not be larger than specified by max-image-size.

Probably introduced at or before Emacs version 21.1.

Aliases

allout-find-image (obsolete since 28.1)

Source Code

;; Defined in /usr/src/emacs/lisp/image.el.gz
;;;###autoload
(defun find-image (specs &optional cache)
  "Find an image, choosing one of a list of image specifications.

SPECS is a list of image specifications.

Each image specification in SPECS is a property list.  The contents of
a specification are image type dependent.  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 specification whose TYPE
is supported, and FILE exists, is used to construct the image
specification to be returned.  Return nil if no specification is
satisfied.

If CACHE is non-nil, results are cached and returned on subsequent calls.

The image is looked for in `image-load-path'.

Image files should not be larger than specified by `max-image-size'."
  (or (and cache
           (gethash specs find-image--cache))
      (let ((orig-specs specs)
            image)
        (while (and specs (null image))
          (let* ((spec (car specs))
                 (type (plist-get spec :type))
                 (data (plist-get spec :data))
                 (file (plist-get spec :file))
                 found)
	    (when (image-type-available-p type)
	      (cond ((stringp file)
		     (if (setq found (image-search-load-path file))
                         (setq image
			       (cons 'image (plist-put (copy-sequence spec)
						       :file found)))))
		    ((not (null data))
		     (setq image (cons 'image spec)))))
	    (setq specs (cdr specs))))
        (when cache
          (setf (gethash orig-specs find-image--cache) image))
        image)))