@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000
+@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
@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
@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
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}.
+
+@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},
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
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
-non-negative number; if it 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
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}.