@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/display
---------- Echo Area ----------
@end group
@end example
+
+To automatically display a message in the echo area or in a pop-buffer,
+depending on its size, use @code{display-message-or-buffer}.
@end defun
@tindex with-temp-message
@code{message}.
@end defun
+@defun display-message-or-buffer message &optional buffer-name not-this-window frame
+@tindex display-message-or-buffer
+This function displays the message @var{message}, which may be either a
+string or a buffer. If it is shorter than the maximum height of the
+echo area, as defined by @code{max-mini-window-height}, it is displayed
+in the echo area, using @code{message}. Otherwise,
+@code{display-buffer} is used to show it in a pop-up buffer.
+
+Returns either the string shown in the echo area, or when a pop-up
+buffer is used, the window used to display it.
+
+If @var{message} is a string, then the optional argument
+@var{buffer-name} is the name of the buffer used to display it when a
+pop-up buffer is used, defaulting to @samp{*Message*}. In the case
+where @var{message} is a string and displayed in the echo area, it is
+not specified whether the contents are inserted into the buffer anyway.
+
+The optional arguments @var{not-this-window} and @var{frame} are as for
+@code{display-buffer}, and only used if a buffer is displayed.
+@end defun
+
@defun current-message
This function returns the message currently being displayed in the
echo area, or @code{nil} if there is none.
@defvar overlay-arrow-string
This variable holds the string to display to call attention to a
particular line, or @code{nil} if the arrow feature is not in use.
+On a graphical display the contents of the string are ignored; instead a
+glyph is displayed in the fringe area to the left of the display area.
@end defvar
@defvar overlay-arrow-position
This variable holds a marker that indicates where to display the overlay
-arrow. It should point at the beginning of a line. The arrow text
+arrow. It should point at the beginning of a line. On a non-graphical
+display the arrow text
appears at the beginning of that line, overlaying any text that would
otherwise appear. Since the arrow is usually short, and the line
usually begins with indentation, normally nothing significant is
@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
@kindex help-echo @r{(text property)}
-If an overlay has a string as its @code{help-echo} property, then when
-you move the mouse onto the text in the overlay, Emacs displays that
-string in the echo area, or in the tooltip window. This feature is
-available starting in Emacs 21.
+If an overlay has a @code{help-echo} property, then when you move the
+mouse onto the text in the overlay, Emacs displays a help string in the
+echo area, or in the tooltip window. For details see @ref{Text
+help-echo}. This feature is available starting in Emacs 21.
@item modification-hooks
@kindex modification-hooks @r{(overlay property)}
If this property is non-@code{nil}, the overlay is deleted automatically
if it ever becomes empty (i.e., if it spans no characters).
-@item keymap
+@item local-map
@cindex keymap of character (and overlays)
-@kindex keymap @r{(overlay property)}
+@kindex local-map @r{(overlay property)}
If this property is non-@code{nil}, it specifies a keymap for a portion
of the text. The property's value replaces the buffer's local map, when
the character after point is within the overlay. @xref{Active Keymaps}.
-@end table
-@item local-map
-@cindex keymap of character (and overlays)
-@kindex local-map @r{(overlay property)}
-This property is like the @code{keymap} property, except that it doesn't
-replace the buffer's local map. Keys not defined in the keymap
-specified with @code{local-map} are looked up in the buffer's local map.
+@item keymap
+@kindex keymap @r{(overlay property)}
+The @code{keymap} property is similar to @code{local-map} but overrides the
+buffer's local map (and the map specified by the @code{local-map}
+property) rather than replacing it.
@end table
@node Managing Overlays
(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)))
@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.
@table @code
@item type
-The kind of window system the frame uses---either @code{x}, @code{pc}
-(for the MS-DOS console), @code{w32} (for MS Windows 9X/NT), or
-@code{tty}.
+The kind of window system the frame uses---either @code{graphic} (any
+graphics-capable display), @code{x}, @code{pc} (for the MS-DOS console),
+@code{w32} (for MS Windows 9X/NT), or @code{tty} (a non-graphics-capable
+display).
@item class
What kinds of colors the frame supports---either @code{color},
@code{extra-expanded}, or @code{ultra-expanded}.
@item :height
-Font height, an integer in units of 1/10 point.
+Either the font height, an integer in units of 1/10 point, a floating
+point number specifying the amount by which to scale the height of any
+underlying face, or a function, which is called with the old height
+(from the underlying face), and should return the new height.
@item :weight
Font weight---a symbol from this series (from most dense to most faint):
Whether or not characters should be strike-through, and in what
color. The value is used like that of @code{:underline}.
+@item :inherit
+The name of a face from which to inherit attributes, or a list of face
+names. Attributes from inherited faces are merged into the face like an
+underlying face would be, with higher priority than underlying faces.
+
@item :box
Whether or not a box should be drawn around characters, its color, the
width of the box lines, and 3D appearance.
quite right.
@end defvar
-@defvar face-alternative-font-family-alist
-@tindex face-alternative-font-family-alist
+@defvar face-font-family-alternatives
+@tindex face-font-family-alternatives
This variable lets you specify alternative font families to try, if a
given family is specified and doesn't exist. Each element should have
this form:
If @var{family} is specified but not available, Emacs will try the other
families given in @var{alternate-families}, one by one, until it finds a
family that does exist.
+@end defvar
+
+@defvar face-font-registry-alternatives
+@tindex face-font-registry-alternatives
+This variable lets you specify alternative font registries to try, if a
+given registry is specified and doesn't exist. Each element should have
+this form:
+
+@example
+(@var{registry} @var{alternate-registries}@dots{})
+@end example
+
+If @var{registry} is specified but not available, Emacs will try the
+other registries given in @var{alternate-registries}, one by one,
+until it finds a registry that does exist.
@end defvar
Emacs can make use of scalable fonts, but by default it does not use
display specification, it means to display the image instead of the text
that has the display specification.
+@item ((margin nil) @var{string})
+@itemx @var{string}
+A display specification of this form means to display @var{string}
+instead of the text that has the display specification, at the same
+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
@cindex conditional display specifications
You can make any display specification conditional. To do that,
-package it in another list of the form @code{(when @var{condition}
+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 :ascent @var{ascent}
-The @code{:ascent} property specifies the percentage of the image's
-height to use for its ascent---that is, the part above the baseline. The
-value, @var{ascent}, must be a number in the range 0 to 100. If this
-property is omitted, it defaults to 50.
+@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
-non-negative number; if it is not specified, the default is zero.
+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.
+The value, @var{ascent}, must be a number in the range 0 to 100, or
+the symbol @code{center}.
+
+If @var{ascent} is a number, that percentage of the image's height is
+used for its ascent.
+
+If @var{ascent} is @code{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.
@item :relief @var{relief}
The @code{:relief} property, if non-@code{nil}, adds a shadow rectangle
so that the image appears as a pressed button; otherwise, it appears as
an unpressed button.
-@item :algorithm @var{algorithm}
-The @code{:algorithm} property, if non-@code{nil}, specifies a
+@item :conversion @var{algorithm}
+The @code{:conversion} property, if non-@code{nil}, specifies a
conversion algorithm that should be applied to the image before it is
displayed; the value, @var{algorithm}, specifies which algorithm.
-Currently, the only meaningful value for @var{algorithm} (aside from
-@code{nil}) is @code{laplace}; this applies 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.
-
-@item :heuristic-mask @var{transparent-color}
-The @code{:heuristic-mask} property, if non-@code{nil}, specifies that a
-certain color in the image should be transparent. Each pixel where this
-color appears will actually allow the frame's background to show
-through.
+@table @code
+@item laplace
+@itemx 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.
+
+@item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust})
+Specifies a general edge-detection algorithm. @var{matrix} must be
+either a nine-element list or a nine-element vector of numbers. A pixel
+at position @math{x/y} in the transformed image is computed from
+original pixels around that position. @var{matrix} specifies, for each
+pixel in the neighborhood of @math{x/y}, a factor with which that pixel
+will influence the transformed pixel; element @math{0} specifies the
+factor for the pixel at @math{x-1/y-1}, element @math{1} the factor for
+the pixel at @math{x/y-1} etc., as shown below:
+@iftex
+@tex
+$$\pmatrix{x-1/y-1 & x/y-1 & x+1/y-1 \cr
+ x-1/y & x/y & x+1/y \cr
+ x-1/y+1& x/y+1 & x+1/y+1 \cr}$$
+@end tex
+@end iftex
+@ifnottex
+@display
+ (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)
+@end display
+@end ifnottex
-If @var{transparent-color} is @code{t}, then determine the transparent
-color by looking at the four corners of the image. This uses the color
-that occurs most frequently near the corners as the transparent color.
+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.
-Otherwise, @var{heuristic-mask} should specify the transparent color
-directly, as a list of three integers in the form @code{(@var{red}
-@var{green} @var{blue})}.
+Laplace edge-detection currently uses a matrix of
+@iftex
+@tex
+$$\pmatrix{1 & 0 & 0 \cr
+ 0& 0 & 0 \cr
+ 9 & 9 & -1 \cr}$$
+@end tex
+@end iftex
+@ifnottex
+@display
+ (1 0 0
+ 0 0 0
+ 9 9 -1)
+@end display
+@end ifnottex
-@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}.
+Emboss edge-detection uses a matrix of
+@iftex
+@tex
+$$\pmatrix{ 2 & -1 & 0 \cr
+ -1 & 0 & 1 \cr
+ 0 & 1 & -2 \cr}$$
+@end tex
+@end iftex
+@ifnottex
+@display
+ ( 2 -1 0
+ -1 0 1
+ 0 1 -2)
+@end display
+@end ifnottex
-@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.
+@item disabled
+Specifies transforming the image so that it looks ``disabled''.
+@end table
-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 :mask @var{mask}
+If @var{mask} is @code{heuristic} or @code{(heuristic @var{bg})}, build
+a clipping mask for the image, so that the background of a frame is
+visible behind the image. If @var{bg} is not specified, or if @var{bg}
+is @code{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,
+@var{bg} must be a list @code{(@var{red} @var{green} @var{blue})}
+specifying the color to assume for the background of the image.
+
+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}.
@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.
+@end defun
+
@node XBM Images
@subsection XBM Images
@cindex XBM
@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
@cindex PBM
For PBM images, specify image type @code{pbm}. Color, gray-scale and
-monochromatic images are supported.
+monochromatic images are supported. For mono PBM images, two additional
+image properties are supported.
+
+@table @code
+@item :foreground @var{foreground}
+The value, @var{foreground}, should be a string specifying the image
+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, 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}.
@node Defining Images
@subsection Defining Images
- The functions @code{create-image} and @code{defimage} provide
-convenient ways to create image descriptors.
+ The functions @code{create-image}, @code{defimage} and
+@code{find-image} provide convenient ways to create image descriptors.
@defun create-image file &optional type &rest props
@tindex create-image
as @code{nil}.
@end defmac
+@defun find-image specs
+@tindex find-image
+This function provides a convenient way to find an image satisfying one
+of a list of image specifications @var{specs}.
+
+Each specification in @var{specs} is a property list with contents
+depending on image type. All specifications must at least contain the
+properties @code{:type @var{type}} and either @w{@code{:file @var{file}}}
+or @w{@code{:data @var{DATA}}}, where @var{type} is a symbol specifying
+the image type, e.g.@: @code{xbm}, @var{file} is the file to load the
+image from, and @var{data} is a string containing the actual image data.
+The first specification in the list whose @var{type} is supported, and
+@var{file} exists, is used to construct the image specification to be
+returned. If no specification is satisfied, @code{nil} is returned.
+
+The image is looked for first on @code{load-path} and then in
+@code{data-directory}.
+@end defun
+
@node Showing Images
@subsection Showing Images
property yourself, but it is easier to use the functions in this
section.
-@defun insert-image image string &optional area
+@defun insert-image image &optional string area
This function inserts @var{image} in the current buffer at point. The
value @var{image} should be an image descriptor; it could be a value
returned by @code{create-image}, or the value of a symbol defined with
Property}.
@end defun
-@defun put-image image pos string &optional area
+@defun put-image image pos &optional string area
This function puts image @var{image} in front of @var{pos} in the
current buffer. The argument @var{pos} should be an integer or a
marker. It specifies the buffer position where the image should appear.
-The argument @var{string} specifies the text that should hold the image.
+The argument @var{string} specifies the text that should hold the image
+as an alternative to the default.
The argument @var{image} must be an image descriptor, perhaps returned
by @code{create-image} or stored by @code{defimage}.
@code{insert-image} or in other ways.
@end defun
+@defun image-size spec &optional pixels frame
+@tindex image-size
+This function returns the size of an image as a pair
+@w{@code{(@var{width} . @var{height})}}. @var{spec} is an image
+specification. @var{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).
+@var{frame} is the frame on which the image will be displayed.
+@var{frame} null or omitted means use the selected frame.
+@end defun
+
@node Image Cache
@subsection Image Cache