follows:
@defun message string &rest arguments
-This function displays a one-line message in the echo area. The
+This function displays a message in the echo area. The
argument @var{string} is similar to a C language @code{printf} control
string. See @code{format} in @ref{String Conversion}, for the details
on the conversion specifications. @code{message} returns the
its normal size. If the minibuffer is active, this brings the
minibuffer contents back onto the screen immediately.
+@vindex message-truncate-lines
+Normally, displaying a long message resizes the echo area to display
+the entire message. But if the variable @code{message-truncate-lines}
+is non-@code{nil}, the echo area does not resize, and the message is
+truncated to fit it, as in Emacs 20 and before.
+
@example
@group
(message "Minibuffer depth is %d."
@kindex display @r{(overlay property)}
This property activates various features that change the
way text is displayed. For example, it can make text appear taller
-or shorter, higher or lower, wider or narror, or replaced with an image.
+or shorter, higher or lower, wider or narrower, or replaced with an image.
@xref{Display Property}.
@item help-echo
(let ((overlays (overlays-at (point)))
found)
(while overlays
- (let ((overlay (cdr overlays)))
+ (let ((overlay (car overlays)))
(if (overlay-get overlay prop)
(setq found (cons overlay found))))
(setq overlays (cdr overlays)))
@node Faces
@section Faces
-@cindex face
+@cindex faces
A @dfn{face} is a named collection of graphical attributes: font
family, foreground color, background color, optional underlining, and
@kindex underline @r{(face name)}
This face underlines text.
-@item fixed-patch
-@kindex fixed-patch @r{(face name)}
+@item fixed-pitch
+@kindex fixed-pitch @r{(face name)}
This face forces use of a particular fixed-width font.
-@item variable-patch
-@kindex variable-patch @r{(face name)}
+@item variable-pitch
+@kindex variable-pitch @r{(face name)}
This face forces use of a particular variable-width font. It's
reasonable to customize this to use a different variable-width font, if
you like, but you should not make it a fixed-width font.
external-format X bitmap data. The file is found in the directories
listed in the variable @code{x-bitmap-file-path}.
-Alternatively, the value can specify the bitmap directly, with a list of
-the form @code{(@var{width} @var{height} @var{data})}. Here,
-@var{width} and @var{height} specify the size in pixels, and @var{data}
-is a string containing the raw bits of the bitmap, row by row. Each row
-occupies @math{(@var{width} + 7) / 8} consecutie bytes in the string
-(which should be a unibyte string for best results).
+Alternatively, the value can specify the bitmap directly, with a list
+of the form @code{(@var{width} @var{height} @var{data})}. Here,
+@var{width} and @var{height} specify the size in pixels, and
+@var{data} is a string containing the raw bits of the bitmap, row by
+row. Each row occupies @math{(@var{width} + 7) / 8} consecutive bytes
+in the string (which should be a unibyte string for best results).
+This means that each row always occupies at least one whole byte.
If the value is @code{nil}, that means use no stipple pattern.
@defun face-attribute face attribute &optional frame
This returns the value of the @var{attribute} attribute of face
@var{face} on @var{frame}. If @var{frame} is @code{nil},
-that means the selected frame.
+that means the selected frame (@pxref{Input Focus}).
If @var{frame} is @code{t}, the value is the default for
@var{face} for new frames.
contain the wildcards @samp{?} and @samp{*}.
The list describes the display that @var{frame} is on; if @var{frame} is
-omitted or @code{nil}, it applies to the selected frame's display.
+omitted or @code{nil}, it applies to the selected frame's display
+(@pxref{Input Focus}).
The list contains a vector of the following form for each font:
@tindex x-font-family-list
This function returns a list of the font families available for
@var{frame}'s display. If @var{frame} is omitted or @code{nil}, it
-describes the selected frame's display.
+describes the selected frame's display (@pxref{Input Focus}).
The value is a list of elements of this form:
position as that text. This is a special case of marginal display
(@pxref{Display Margins}).
+Recursive display specifications are not supported, i.e.@: string
+display specifications that have a display specification property
+themselves.
+
@item (space-width @var{factor})
This display specification affects all the space characters within the
text that has the specification. It displays all of these spaces
You can also set the margin widths immediately.
-@defun set-window-margins window left right
+@defun set-window-margins window left &optional right
@tindex set-window-margins
This function specifies the margin widths for window @var{window}.
The argument @var{left} controls the left margin and
-@var{right} controls the right margin.
+@var{right} controls the right margin (default @code{0}).
@end defun
@defun window-margins &optional window
package it in another list of the form @code{(when @var{condition} .
@var{spec})}. Then the specification @var{spec} applies only when
@var{condition} evaluates to a non-@code{nil} value. During the
-evaluation, point is temporarily set at the end position of the text
-having this conditional display specification.
+evaluation, @code{object} is bound to the string or buffer having the
+conditional @code{display} property. @code{position} and
+@code{buffer-position} are bound to the position within @code{object}
+and the buffer position where the @code{display} property was found,
+respectively. Both positions can be different when @code{object} is a
+string.
@node Images
@section Images
types:
@table @code
+@item :file @var{file}
+The @code{:file} property specifies to load the image from file
+@var{file}. If @var{file} is not an absolute file name, it is expanded
+in @code{data-directory}.
+
+@item :data @var{data}
+The @code{:data} property specifies the actual contents of the image.
+Each image must use either @code{:data} or @code{:file}, but not both.
+For most image types, the value of the @code{:data} property should be a
+string containing the image data; we recommend using a unibyte string.
+
+Before using @code{:data}, look for further information in the section
+below describing the specific image format. For some image types,
+@code{:data} may not be supported; for some, it allows other data types;
+for some, @code{:data} alone is not enough, so you need to use other
+image properties along with @code{:data}.
+
+@item :margin @var{margin}
+The @code{:margin} property specifies how many pixels to add as an
+extra margin around the image. The value, @var{margin}, must be a a
+non-negative number, or a pair @code{(@var{x} . @var{y})} of such
+numbers. If it is a pair, @var{x} specifies how many pixels to add
+horizontally, and @var{y} specifies how many pixels to add vertically.
+If @code{:margin} is not specified, the default is zero.
+
@item :ascent @var{ascent}
The @code{:ascent} property specifies the amount of the image's
height to use for its ascent---that is, the part above the baseline.
If this property is omitted, it defaults to 50.
-@item :margin @var{margin}
-The @code{:margin} property specifies how many pixels to add as an
-extra margin around the image. The value, @var{margin}, must be a a
-non-negative number, or a pair @code{(@var{x} . @var{y})} of such
-numbers. If it is a pair, @var{x} specifies how many pixels to add
-horizontally, and @var{y} specifies how many pixels to add vertically.
-If @code{:margin} is not specified, the default is zero.
-
@item :relief @var{relief}
The @code{:relief} property, if non-@code{nil}, adds a shadow rectangle
around the image. The value, @var{relief}, specifies the width of the
If @var{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
@code{:mask nil}.
-
-@item :file @var{file}
-The @code{:file} property specifies to load the image from file
-@var{file}. If @var{file} is not an absolute file name, it is expanded
-in @code{data-directory}.
-
-@item :data @var{data}
-The @code{:data} property specifies the actual contents of the image.
-Each image must use either @code{:data} or @code{:file}, but not both.
-For most image types, the value of the @code{:data} property should be a
-string containing the image data; we recommend using a unibyte string.
-
-Before using @code{:data}, look for further information in the section
-below describing the specific image format. For some image types,
-@code{:data} may not be supported; for some, it allows other data types;
-for some, @code{:data} alone is not enough, so you need to use other
-image properties along with @code{:data}.
@end table
@defun image-mask-p spec &optional frame
@tindex image-mask-p
This function returns @code{t} if image @var{spec} has a mask bitmap.
@var{frame} is the frame on which the image will be displayed.
-@var{frame} @code{nil} or omitted means to use the selected frame.
+@var{frame} @code{nil} or omitted means to use the selected frame
+(@pxref{Input Focus}).
@end defun
@node XBM Images
@table @code
@item :foreground @var{foreground}
The value, @var{foreground}, should be a string specifying the image
-foreground color. This color is used for each pixel in the XBM that is
-1. The default is the frame's foreground color.
+foreground color, or @code{nil} for the default color. This color is
+used for each pixel in the XBM that is 1. The default is the frame's
+foreground color.
@item :background @var{background}
The value, @var{background}, should be a string specifying the image
-background color. This color is used for each pixel in the XBM that is
-0. The default is the frame's background color.
+background color, or @code{nil} for the default color. This color is
+used for each pixel in the XBM that is 0. The default is the frame's
+background color.
@end table
If you specify an XBM image using data within Emacs instead of an
@table @code
@item :foreground @var{foreground}
The value, @var{foreground}, should be a string specifying the image
-foreground color. This color is used for each pixel in the XBM that is
-1. The default is the frame's foreground color.
+foreground color, or @code{nil} for the default color. This color is
+used for each pixel in the XBM that is 1. The default is the frame's
+foreground color.
@item :background @var{background}
The value, @var{background}, should be a string specifying the image
-background color. This color is used for each pixel in the XBM that is
-0. The default is the frame's background color.
+background color, or @code{nil} for the default color. This color is
+used for each pixel in the XBM that is 0. The default is the frame's
+background color.
@end table
For JPEG images, specify image type @code{jpeg}.
supported. Otherwise it returns an image descriptor.
@end defun
-@defmac defimage variable doc &rest specs
+@defmac defimage symbol specs &optional doc
@tindex defimage
-This macro defines @var{variable} as an image name. The second argument,
-@var{doc}, is an optional documentation string. The remaining
-arguments, @var{specs}, specify alternative ways to display the image.
+This macro defines @var{symbol} as an image name. The arguments
+@var{specs} is a list which specifies how to display the image.
+The third argument, @var{doc}, is an optional documentation string.
Each argument in @var{specs} has the form of a property list, and each
-one should specify at least the @code{:type} property and the
-@code{:file} property. Here is an example:
+one should specify at least the @code{:type} property and either the
+@code{:file} or the @code{:data} property. The value of @code{:type}
+should be a symbol specifying the image type, the value of
+@code{:file} is the file to load the image from, and the value of
+@code{:data} is a string containing the actual image data. Here is an
+example:
@example
(defimage test-image
@code{defimage} tests each argument, one by one, to see if it is
usable---that is, if the type is supported and the file exists. The
first usable argument is used to make an image descriptor which is
-stored in the variable @var{variable}.
+stored in @var{symbol}.
-If none of the alternatives will work, then @var{variable} is defined
+If none of the alternatives will work, then @var{symbol} is defined
as @code{nil}.
@end defmac
pixels, otherwise return sizes measured in canonical character units
(fractions of the width/height of the frame's default font).
@var{frame} is the frame on which the image will be displayed.
-@var{frame} null or omitted means use the selected frame.
+@var{frame} null or omitted means use the selected frame (@pxref{Input
+Focus}).
@end defun
@node Image Cache
The value of this variable is the current glyph table. It should be a
vector; the @var{g}th element defines glyph code @var{g}. If the value
is @code{nil} instead of a vector, then all glyphs are simple (see
-below).
+below). The glyph table is not used on windowed displays.
@end defvar
Here are the possible types of elements in the glyph table: