You can use an image descriptor by setting up the display
property yourself, but it is easier to use the functions in this
section.
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. If it is omitted or nil,
insert-image uses " " by default.
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.
The argument slice specifies a slice of the image to insert. If
slice is nil or omitted the whole image is inserted.
(However, note that images are chopped on display at the window’s
right edge, because wrapping images is not supported.) Otherwise,
slice is a list (x y width
height) which specifies the x and y positions and
width and height of the image area to insert. Integer
values are in units of pixels. A floating-point number in the range
0.0–1.0 stands for that fraction of the width or height of the entire
image.
Internally, this function inserts string in the buffer, and gives
it a display property which specifies image. See The display Property. By default, doing interactive searches in the buffer will
consider string when searching. If inhibit-isearch is
non-nil, this is inhibited.
This function inserts image in the current buffer at point, like
insert-image, but splits the image into rowsxcols
equally sized slices.
Emacs displays each slice as a separate image, and allows more intuitive scrolling up/down, instead of jumping up/down the entire image when paging through a buffer that displays (large) images.
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 ‘x’.
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! that was a mouthful…)
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.
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 the default character size
of frame (see Frame Font). frame is the frame on which
the image will be displayed. frame nil or omitted means
use the selected frame (see Input Focus).
This variable is used to define the maximum size of image that Emacs will load. Emacs will refuse to load (and display) any image that is larger than this limit.
If the value is an integer, it directly specifies the maximum image height and width, measured in pixels. If it is floating point, it specifies the maximum image height and width as a ratio to the frame height and width. If the value is non-numeric, there is no explicit limit on the size of images.
The purpose of this variable is to prevent unreasonably large images
from accidentally being loaded into Emacs. It only takes effect the
first time an image is loaded. Once an image is placed in the image
cache, it can always be displayed, even if the value of
max-image-size is subsequently changed (see Image Cache).
This function returns t if point is on an image, and nil
otherwise.
Images inserted with the insertion functions above also get a local keymap installed in the text properties (or overlays) that span the displayed image. This keymap defines the following commands:
Increase the image size (image-increase-size)
Decrease the image size (image-decrease-size).
Rotate the image (image-rotate).
Flip the image horizontally (image-flip-horizontally).
Flip the image vertically (image-flip-vertically).
Save the image to a file (image-save).
Interactively crop the image (image-crop).
Interactively cut a rectangle from the image (image-cut).
See Image Mode in The GNU Emacs Manual, for more details about these image-specific key bindings.