Function: insert-image

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

Signature

(insert-image IMAGE &optional STRING AREA SLICE INHIBIT-ISEARCH)

Documentation

Insert IMAGE into current buffer at point.

IMAGE is displayed by inserting STRING into the current buffer with a display property whose value is the image.

STRING defaults to a single space if you omit it, which means that the inserted image will behave as whitespace syntactically.

AREA is where to display the image. AREA nil or omitted means display it in the text area, a value of left-margin means display it in the left marginal area, a value of right-margin means display it in the right marginal area.

SLICE specifies slice of IMAGE to insert. SLICE nil or omitted means insert whole image. SLICE is a list (X Y WIDTH HEIGHT) specifying the X and Y positions and WIDTH and HEIGHT of image area to insert. A float value 0.0 - 1.0 means relative to the width or height of the image; integer values are taken as pixel values.

Normally isearch is able to search for STRING in the buffer even if it's hidden behind a displayed image. If INHIBIT-ISEARCH is non-nil, this is inhibited.

View in manual

Probably introduced at or before Emacs version 21.1.

Source Code

;; Defined in /usr/src/emacs/lisp/image.el.gz
;;;###autoload
(defun insert-image (image &optional string area slice inhibit-isearch)
  "Insert IMAGE into current buffer at point.
IMAGE is displayed by inserting STRING into the current buffer
with a `display' property whose value is the image.

STRING defaults to a single space if you omit it, which means
that the inserted image will behave as whitespace syntactically.

AREA is where to display the image.  AREA nil or omitted means
display it in the text area, a value of `left-margin' means
display it in the left marginal area, a value of `right-margin'
means display it in the right marginal area.

SLICE specifies slice of IMAGE to insert.  SLICE nil or omitted
means insert whole image.  SLICE is a list (X Y WIDTH HEIGHT)
specifying the X and Y positions and WIDTH and HEIGHT of image area
to insert.  A float value 0.0 - 1.0 means relative to the width or
height of the image; integer values are taken as pixel values.

Normally `isearch' is able to search for STRING in the buffer
even if it's hidden behind a displayed image.  If INHIBIT-ISEARCH
is non-nil, this is inhibited."
  ;; Use a space as least likely to cause trouble when it's a hidden
  ;; character in the buffer.
  (unless string (setq string " "))
  (unless (eq (car-safe image) 'image)
    (error "Not an image: %s" image))
  (unless (or (null area) (memq area '(left-margin right-margin)))
    (error "Invalid area %s" area))
  (if area
      (setq image (list (list 'margin area) image))
    ;; Cons up a new spec equal but not eq to `image' so that
    ;; inserting it twice in a row (adjacently) displays two copies of
    ;; the image.  Don't try to avoid this by looking at the display
    ;; properties on either side so that we DTRT more often with
    ;; cut-and-paste.  (Yanking killed image text next to another copy
    ;; of it loses anyway.)
    (setq image (cons 'image (cdr image))))
  (let ((start (point)))
    (insert string)
    (add-text-properties start (point)
			 `(display ,(if slice
					(list (cons 'slice slice) image)
				      image)
                                   rear-nonsticky t
				   inhibit-isearch ,inhibit-isearch
                                   keymap ,(if slice
                                               image-slice-map
                                             image-map)))))