38.13.8 Showing Images

You can use an image descriptor by setting up the display property yourself, but it is easier to use the functions in this section.

Function: insert-image image &optional string area

This function inserts image in the current buffer at point. The value image should be an image descriptor; it could be a value returned by create-image, or the value of a symbol defined with defimage. The argument string specifies the text to put in the buffer to hold the image.

The argument area specifies whether to put the image in a margin. If it is left-margin, the image appears in the left margin; right-margin specifies the right margin. If area is nil or omitted, the image is displayed at point within the buffer's text.

Internally, this function inserts string in the buffer, and gives it a display property which specifies image. See section 38.12 The display Property.

Function: put-image image pos &optional string area

This function puts image image in front of pos in the current buffer. The argument pos should be an integer or a marker. It specifies the buffer position where the image should appear. The argument string specifies the text that should hold the image as an alternative to the default.

The argument image must be an image descriptor, perhaps returned by create-image or stored by defimage.

The argument area specifies whether to put the image in a margin. If it is left-margin, the image appears in the left margin; right-margin specifies the right margin. If area is nil or omitted, the image is displayed at point within the buffer's text.

Internally, this function creates an overlay, and gives it a before-string property containing text that has a display property whose value is the image. (Whew!)

Function: remove-images start end &optional buffer

This function removes images in buffer between positions start and end. If buffer is omitted or nil, images are removed from the current buffer.

This removes only images that were put into buffer the way put-image does it, not images that were inserted with insert-image or in other ways.

Function: image-size spec &optional pixels frame

This function returns the size of an image as a pair (width . height). spec is an image specification. pixels non-nil means return sizes measured in pixels, otherwise return sizes measured in canonical character units (fractions of the width/height of the frame's default font). frame is the frame on which the image will be displayed. frame null or omitted means use the selected frame (see section 29.9 Input Focus).