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 that satisfies 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; see the info node (elisp)Image Descriptors for details. All specifications must at least contain either the property :file FILE or :data DATA, where FILE is the file from which to load the image, and DATA is a string containing the actual image data. If the property :type TYPE is omitted or nil, try to determine the image type from its first few bytes of image data. If that doesn't work, and the property :file FILE provide a file name, use its file extension as indication of the image type. If :type TYPE is provided, it must match the actual type determined for FILE or DATA by create-image.

The function returns the image specification for the first specification in the list whose TYPE is supported and FILE, if specified, exists. It returns nil if no specification in the list can be 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.

View in manual

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 that satisfies 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; see the
info node `(elisp)Image Descriptors' for details.  All specifications
must at least contain either the property `:file FILE' or `:data DATA',
where FILE is the file from which to load the image, and DATA is a
string containing the actual image data.  If the property `:type TYPE'
is omitted or nil, try to determine the image type from its first few
bytes of image data.  If that doesn't work, and the property `:file
FILE' provide a file name, use its file extension as indication of the
image type.  If `:type TYPE' is provided, it must match the actual type
determined for FILE or DATA by `create-image'.

The function returns the image specification for the first specification
in the list whose TYPE is supported and FILE, if specified, exists.  It
returns nil if no specification in the list can be 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)))
	    (cond
             ((stringp file)
	      (when (setq file (image-search-load-path file))
                ;; At this point, remove the :type and :file properties.
                ;; `create-image' will set them depending on image file.
                (setq image (cons 'image (copy-sequence spec)))
                (setf (image-property image :type) nil)
                (setf (image-property image :file) nil)
                (and (setq image (ignore-errors
                                   (apply #'create-image file nil nil
                                          (cdr image))))
                     ;; Ensure, if a type has been provided, it is
                     ;; consistent with the type returned by
                     ;; `create-image'. If not, return nil.
                     (not (null type))
                     (not (eq type (image-property image :type)))
                     (setq image nil))))
	     ((not (null data))
              ;; At this point, remove the :type and :data properties.
              ;; `create-image' will set them depending on image data.
              (setq image (cons 'image (copy-sequence spec)))
              (setf (image-property image :type) nil)
              (setf (image-property image :data) nil)
	      (and (setq image (ignore-errors
                                 (apply #'create-image data nil t
                                        (cdr image))))
                   ;; Ensure, if a type has been provided, it is
                   ;; consistent with the type returned by
                   ;; `create-image'. If not, return nil.
                   (not (null type))
                   (not (eq type (image-property image :type)))
                   (setq image nil))))
	    (setq specs (cdr specs))))
        (when cache
          (setf (gethash orig-specs find-image--cache) image))
        image)))