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 either the property :file FILE or :data DATA, where FILE is the file to load the image from, 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 image type. If :type TYPE is provided, it must match the actual type determined for FILE or DATA by create-image. 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.

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, 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 either the property `:file FILE' or `:data DATA',
where FILE is the file to load the image from, 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 image type.
If `:type TYPE' is provided, it must match the actual type
determined for FILE or DATA by `create-image'.  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)))
	    (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)))