elisp: Image Descriptors
37.17.2 Image Descriptors
-------------------------
An “image descriptor” is a list which specifies the underlying data for
an image, and how to display it. It is typically used as the value of a
‘display’ overlay or text property (
Other Display Specs); but
Showing Images, for convenient helper functions to insert images
into buffers.
Each image descriptor has the form ‘(image . PROPS)’, where PROPS is
a property list of alternating keyword symbols and values, including at
least the pair ‘:type TYPE’ that specifies the image type.
The following is a list of properties that are meaningful for all
image types (there are also properties which are meaningful only for
certain image types, as documented in the following subsections):
‘:type TYPE’
The image type. Image Formats. Every image descriptor
must include this property.
‘:file FILE’
This says to load the image from file FILE. If FILE is not an
absolute file name, it is expanded in ‘data-directory’.
‘:data DATA’
This specifies the raw image data. Each image descriptor must have
either ‘:data’ or ‘:file’, but not both.
For most image types, the value of a ‘:data’ property should be a
string containing the image data. Some image types do not support
‘:data’; for some others, ‘:data’ alone is not enough, so you need
to use other image properties along with ‘:data’. See the
following subsections for details.
‘:margin MARGIN’
This 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
‘(X . Y)’ 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 ‘:margin’ is not specified, the default is zero.
‘:ascent ASCENT’
This 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 ‘center’.
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.
‘:relief RELIEF’
This 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.
‘:conversion ALGORITHM’
This specifies a conversion algorithm that should be applied to the
image before it is displayed; the value, ALGORITHM, specifies which
algorithm.
‘laplace’
‘emboss’
Specifies the Laplace edge detection algorithm, which blurs
out small differences in color while highlighting larger
differences. People sometimes consider this useful for
displaying the image for a disabled button.
‘(edge-detection :matrix MATRIX :color-adjust ADJUST)’
Specifies a general edge-detection algorithm. MATRIX must be
either a nine-element list or a nine-element vector of
numbers. A pixel at position x/y in the transformed image is
computed from original pixels around that position. MATRIX
specifies, for each pixel in the neighborhood of x/y, a factor
with which that pixel will influence the transformed pixel;
element 0 specifies the factor for the pixel at x-1/y-1,
element 1 the factor for the pixel at x/y-1 etc., as shown
below:
(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
0 0 -1)
Emboss edge-detection uses a matrix of
( 2 -1 0
-1 0 1
0 1 -2)
‘disabled’
Specifies transforming the image so that it looks disabled.
‘:mask MASK’
If MASK is ‘heuristic’ or ‘(heuristic BG)’, 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
specifying ‘:mask nil’.
‘:pointer SHAPE’
This specifies the pointer shape when the mouse pointer is over
this image. Pointer Shape, for available pointer shapes.
‘:map MAP’
This associates an image map of “hot spots” with this image.
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 . Y0) . (X1 . Y1)))’ which
specifies the pixel coordinates of the upper left and bottom right
corners of the rectangle area.
A circle is a cons ‘(circle . ((X0 . Y0) . 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 ‘help-echo’
property, that defines a tool-tip for the hot-spot, and if it
contains a ‘pointer’ property, that defines the shape of the mouse
cursor when it is on the hot-spot. 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 ID
is ‘area4’.
-- Function: image-mask-p spec &optional frame
This function returns ‘t’ if image SPEC has a mask bitmap. FRAME
is the frame on which the image will be displayed. FRAME ‘nil’ or
omitted means to use the selected frame (Input Focus).
Info Catalog
elisp: Image Formats
elisp: Images
elisp: XBM Images