Function: put-image

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

Signature

(put-image IMAGE POS &optional STRING AREA)

Documentation

Put image IMAGE in front of POS in the current buffer.

IMAGE must be an image created with create-image or defimage. IMAGE is displayed by putting an overlay into the current buffer with a before-string STRING that has a display property whose value is the image. STRING is defaulted if you omit it. The overlay created will have the put-image property set to t. POS may be an integer or marker. 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.

Probably introduced at or before Emacs version 21.1.

Source Code

;; Defined in /usr/src/emacs/lisp/image.el.gz
;;;###autoload
(defun put-image (image pos &optional string area)
  "Put image IMAGE in front of POS in the current buffer.
IMAGE must be an image created with `create-image' or `defimage'.
IMAGE is displayed by putting an overlay into the current buffer with a
`before-string' STRING that has a `display' property whose value is the
image.  STRING is defaulted if you omit it.
The overlay created will have the `put-image' property set to t.
POS may be an integer or marker.
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."
  (unless string (setq string "x"))
  (let ((buffer (current-buffer)))
    (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))
    (setq string (copy-sequence string))
    (let ((overlay (make-overlay pos pos buffer))
	  (prop (if (null area) image (list (list 'margin area) image))))
      (put-text-property 0 (length string) 'display prop string)
      (overlay-put overlay 'put-image t)
      (overlay-put overlay 'before-string string)
      (overlay-put overlay 'map image-map)
      overlay)))