An image description is a list of the form
(image . props
where props is a property list containing alternating keyword
symbols (symbols whose names start with a colon) and their values.
You can use any Lisp object as a property, but the only properties
that have any special meaning are certain symbols, all of them keywords.
Every image descriptor must contain the property
type to specify the format of the image. The value of type
should be an image type symbol; for example,
xpm for an image in
Here is a list of other properties that are meaningful for all image types:
:fileproperty says to load the image from file file. If file is not an absolute file name, it is expanded in
:dataproperty says the actual contents of the image. Each image must use either
:file, but not both. For most image types, the value of the
:dataproperty should be a string containing the image data; we recommend using a unibyte string.
:data, look for further information in the section
below describing the specific image format. For some image types,
:data may not be supported; for some, it allows other data types;
:data alone is not enough, so you need to use other
image properties along with
:marginproperty specifies how many pixels to add as an extra margin around the image. The value, margin, must be a non-negative number, or a pair
)of such numbers. If it is a pair, x specifies how many pixels to add horizontally, and y specifies how many pixels to add vertically. If
:marginis not specified, the default is zero.
:ascentproperty specifies the amount of the image's height to use for its ascent—that is, the part above the baseline. The value, ascent, must be a number in the range 0 to 100, or the symbol
If ascent is a number, that percentage of the image's height is used for its ascent.
If ascent is
center, the image is vertically centered
around a centerline which would be the vertical centerline of text drawn
at the position of the image, in the manner specified by the text
properties and overlays that apply to the image.
If this property is omitted, it defaults to 50.
:reliefproperty, if non-
nil, adds a shadow rectangle around the image. The value, relief, specifies the width of the shadow lines, in pixels. If relief is negative, shadows are drawn so that the image appears as a pressed button; otherwise, it appears as an unpressed button.
:conversionproperty, if non-
nil, specifies a conversion algorithm that should be applied to the image before it is displayed; the value, algorithm, specifies which algorithm.
(x-1/y-1 x/y-1 x+1/y-1 x-1/y x/y x+1/y x-1/y+1 x/y+1 x+1/y+1)
The resulting pixel is computed from the color intensity of the color resulting from summing up the RGB values of surrounding pixels, multiplied by the specified factors, and dividing that sum by the sum of the factors' absolute values.
Laplace edge-detection currently uses a matrix of
(1 0 0 0 0 0 9 9 -1)
Emboss edge-detection uses a matrix of
( 2 -1 0 -1 0 1 0 1 -2)
), build a clipping mask for the image, so that the background of a frame is visible behind the image. If bg is not specified, or if bg is
t, determine the background color of the image by looking at the four corners of the image, assuming the most frequently occurring color from the corners is the background color of the image. Otherwise, bg must be a list
(red green blue
)specifying the color to assume for the background of the image.
If mask is
nil, remove a mask from the image, if it has
one. Images in some formats include a mask which can be removed by
An image map is an alist where each element has the format
(area id plist
). An area is specified
as either a rectangle, a circle, or a polygon.
A rectangle is a cons
(rect . ((x0
) . (x1
which specifies the pixel coordinates of the upper left and bottom right
corners of the rectangle area.
A circle is a cons
(circle . ((x0
) . r
which specifies the center and the radius of the circle; r may
be a float or integer.
A polygon is a cons
(poly . [x0 y0 x1 y1
where each pair in the vector describes one corner in the polygon.
When the mouse pointer lies on a hot-spot area of an image, the
plist of that hot-spot is consulted; if it contains a
property, that defines a tool-tip for the hot-spot, and if it contains
pointer property, that defines the shape of the mouse cursor when
it is on the hot-spot.
See Pointer Shape, for available pointer shapes.
When you click the mouse when the mouse pointer is over a hot-spot, an
event is composed by combining the id of the hot-spot with the
mouse event; for instance,
[area4 mouse-1] if the hot-spot's
This function returns
tif image spec has a mask bitmap. frame is the frame on which the image will be displayed. frame
nilor omitted means to use the selected frame (see Input Focus).