@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
+@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
@node Display, Calendar, Processes, Top
* Overlay Arrow:: Display of an arrow to indicate position.
* Temporary Displays:: Displays that go away automatically.
* Overlays:: Use overlays to highlight parts of the buffer.
-* Width:: How wide is a character or string.
-* Faces:: A face defines a graphics appearance: font, color, etc.
+* Width:: How wide a character or string is on the screen.
+* Faces:: A face defines a graphics style for text characters:
+ font, colors, etc.
* Display Property:: Enabling special display features.
* Images:: Displaying images in Emacs buffers.
* Blinking:: How Emacs shows the matching open parenthesis.
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."
---------- 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
-@tindex current-message
This function returns the message currently being displayed in the
echo area, or @code{nil} if there is none.
@end defun
@end defvar
@defvar echo-area-clear-hook
-@tindex echo-area-clear-hook
This normal hook is run whenever the echo area is cleared---either by
@code{(message nil)} or for any other reason.
@end defvar
@defvar echo-keystrokes
This variable determines how much time should elapse before command
-characters echo. Its value must be an integer, which specifies the
+characters echo. Its value must be an integer or floating point number,
+which specifies the
number of seconds to wait before echoing. If the user types a prefix
key (such as @kbd{C-x}) and then delays this many seconds before
continuing, the prefix key is echoed in the echo area. (Once echoing
value of @code{buffer-invisibility-spec}.
Controlling visibility with @code{buffer-invisibility-spec} is
-especially useful in a program to display the list of entries in a data
-base. It permits the implementation of convenient filtering commands to
-view just a part of the entries in the data base. Setting this variable
-is very fast, much faster than scanning all the text in the buffer
-looking for properties to change.
+especially useful in a program to display the list of entries in a
+database. It permits the implementation of convenient filtering
+commands to view just a part of the entries in the database. Setting
+this variable is very fast, much faster than scanning all the text in
+the buffer looking for properties to change.
@defvar buffer-invisibility-spec
This variable specifies which kinds of @code{invisible} properties
@code{buffer-invisibility-spec} and removing elements from it.
@defun add-to-invisibility-spec element
-@tindex add-to-invisibility-spec
Add the element @var{element} to @code{buffer-invisibility-spec}
(if it is not already present in that list).
@end defun
@defun remove-from-invisibility-spec element
-@tindex remove-from-invisibility-spec
Remove the element @var{element} from @code{buffer-invisibility-spec}.
+This does nothing if @var{element} is not in the list.
@end defun
One convention about the use of @code{buffer-invisibility-spec} is
want this to be done differently for a certain overlay, give it an
@code{isearch-open-invisible-temporary} property which is a function.
The function is called with two arguments: the first is the overlay, and
-the second is @code{t} to make the overlay visible, or @code{nil} to
+the second is @code{nil} to make the overlay visible, or @code{t} to
make it invisible again.
@node Selective Display
@itemize @bullet
@item
-If the value of @code{selective-display} is @code{t}, then any portion
-of a line that follows a control-m is not displayed. This is explicit
-selective display.
+If the value of @code{selective-display} is @code{t}, then the character
+control-m marks the start of invisible text; the control-m, and the rest
+of the line following it, are not displayed. This is explicit selective
+display.
@item
If the value of @code{selective-display} is a positive integer, then
@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
@menu
* Overlay Properties:: How to read and set properties.
What properties do to the screen display.
-* Managing Overlays:: Creating, moving, finding overlays.
+* Managing Overlays:: Creating and moving overlays.
+* Finding Overlays:: Searching for overlays.
@end menu
@node Overlay Properties
font and which colors. @xref{Faces}, for more information.
In the simplest case, the value is a face name. It can also be a list;
-then each element can be any of these possibilities;
+then each element can be any of these possibilities:
@itemize @bullet
@item
@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. It 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)}
@kindex before-string @r{(overlay property)}
This property's value is a string to add to the display at the beginning
of the overlay. The string does not appear in the buffer in any
-sense---only on the screen. The string should contain only characters
-that display as a single column---control characters, including tabs or
-newlines, will give strange results.
+sense---only on the screen.
@item after-string
@kindex after-string @r{(overlay property)}
This property's value is a string to add to the display at the end of
the overlay. The string does not appear in the buffer in any
-sense---only on the screen. The string should contain only characters
-that display as a single column---control characters, including tabs or
-newlines, will give strange results.
+sense---only on the screen.
@item evaporate
@kindex evaporate @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}.
+
+@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
The arguments @var{front-advance} and @var{rear-advance} specify the
insertion type for the start of the overlay and for the end of the
-overlay. @xref{Marker Insertion Types}.
+overlay, respectively. @xref{Marker Insertion Types}.
@end defun
@defun overlay-start overlay
@defun delete-overlay overlay
This function deletes @var{overlay}. The overlay continues to exist as
-a Lisp object, but ceases to be attached to the buffer it belonged to,
-and ceases to have any effect on display.
+a Lisp object, and its property list is unchanged, but it ceases to be
+attached to the buffer it belonged to, and ceases to have any effect on
+display.
-A deleted overlay is not permanently useless. You can give it
-a new buffer position by calling @code{move-overlay}.
+A deleted overlay is not permanently disconnected. You can give it a
+position in a buffer again by calling @code{move-overlay}.
@end defun
@defun move-overlay overlay start end &optional buffer
This function moves @var{overlay} to @var{buffer}, and places its bounds
at @var{start} and @var{end}. Both arguments @var{start} and @var{end}
-must specify buffer positions; they may be integers or markers. If
-@var{buffer} is omitted, the overlay stays in the same buffer.
+must specify buffer positions; they may be integers or markers.
+
+If @var{buffer} is omitted, @var{overlay} stays in the same buffer it
+was already associated with; if @var{overlay} was deleted, it goes into
+the current buffer.
The return value is @var{overlay}.
``lost''.
@end defun
+ Here are some examples:
+
+@example
+;; @r{Create an overlay.}
+(setq foo (make-overlay 1 10))
+ @result{} #<overlay from 1 to 10 in display.texi>
+(overlay-start foo)
+ @result{} 1
+(overlay-end foo)
+ @result{} 10
+(overlay-buffer foo)
+ @result{} #<buffer display.texi>
+;; @r{Give it a property we can check later.}
+(overlay-put foo 'happy t)
+ @result{} t
+;; @r{Verify the property is present.}
+(overlay-get foo 'happy)
+ @result{} t
+;; @r{Move the overlay.}
+(move-overlay foo 5 20)
+ @result{} #<overlay from 5 to 20 in display.texi>
+(overlay-start foo)
+ @result{} 5
+(overlay-end foo)
+ @result{} 20
+;; @r{Delete the overlay.}
+(delete-overlay foo)
+ @result{} nil
+;; @r{Verify it is deleted.}
+foo
+ @result{} #<overlay in no buffer>
+;; @r{A deleted overlay has no position.}
+(overlay-start foo)
+ @result{} nil
+(overlay-end foo)
+ @result{} nil
+(overlay-buffer foo)
+ @result{} nil
+;; @r{Undelete the overlay.}
+(move-overlay foo 1 20)
+ @result{} #<overlay from 1 to 20 in display.texi>
+;; @r{Verify the results.}
+(overlay-start foo)
+ @result{} 1
+(overlay-end foo)
+ @result{} 20
+(overlay-buffer foo)
+ @result{} #<buffer display.texi>
+;; @r{Moving and deleting the overlay does not change its properties.}
+(overlay-get foo 'happy)
+ @result{} t
+@end example
+
+@node Finding Overlays
+@subsection Searching for Overlays
+
@defun overlays-at pos
-This function returns a list of all the overlays that contain position
-@var{pos} in the current buffer. The list is in no particular order.
-An overlay contains position @var{pos} if it begins at or before
-@var{pos}, and ends after @var{pos}.
+This function returns a list of all the overlays that cover the
+character at position @var{pos} in the current buffer. The list is in
+no particular order. An overlay contains position @var{pos} if it
+begins at or before @var{pos}, and ends after @var{pos}.
+
+To illustrate usage, here is a Lisp function that returns a list of the
+overlays that specify property @var{prop} for the character at point:
+
+@smallexample
+(defun find-overlays-specifying (prop)
+ (let ((overlays (overlays-at (point)))
+ found)
+ (while overlays
+ (let ((overlay (car overlays)))
+ (if (overlay-get overlay prop)
+ (setq found (cons overlay found))))
+ (setq overlays (cdr overlays)))
+ found))
+@end smallexample
@end defun
@defun overlays-in beg end
-@tindex overlays-in
This function returns a list of the overlays that overlap the region
@var{beg} through @var{end}. ``Overlap'' means that at least one
character is contained within the overlay and also contained within the
specified region; however, empty overlays are included in the result if
-they are located at @var{beg} or between @var{beg} and @var{end}.
+they are located at @var{beg}, or strictly between @var{beg} and @var{end}.
@end defun
@defun next-overlay-change pos
end of an overlay, before @var{pos}.
@end defun
+ Here's an easy way to use @code{next-overlay-change} to search for the
+next character which gets a non-@code{nil} @code{happy} property from
+either its overlays or its text properties (@pxref{Property Search}):
+
+@smallexample
+(defun find-overlay-prop (prop)
+ (save-excursion
+ (while (and (not (eobp))
+ (not (get-char-property (point) 'happy)))
+ (goto-char (min (next-overlay-change (point))
+ (next-single-property-change (point) 'happy))))
+ (point)))
+@end smallexample
+
@node Width
@section Width
@ref{Screen Lines}, for related functions.
@defun char-width char
-@tindex char-width
This function returns the width in columns of the character @var{char},
if it were displayed in the current buffer and the selected window.
@end defun
@defun string-width string
-@tindex string-width
This function returns the width in columns of the string @var{string},
if it were displayed in the current buffer and the selected window.
@end defun
@defun truncate-string-to-width string width &optional start-column padding
-@tindex truncate-string-to-width
This function returns the part of @var{string} that fits within
@var{width} columns, as a new string.
@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
@item mode-line
@kindex mode-line @r{(face name)}
-This face is used for mode lines, and for menu bars
-when toolkit menus are not used.
+This face is used for mode lines, and for menu bars when toolkit menus
+are not used---but only if @code{mode-line-inverse-video} is
+non-@code{nil}.
@item modeline
@kindex modeline @r{(face name)}
@kindex header-line @r{(face name)}
This face is used for the header lines of windows that have them.
+@item menu
+This face controls the display of menus, both their colors and their
+font. (This works only on certain systems.)
+
@item fringe
@kindex fringe @r{(face name)}
This face controls the colors of window fringes, the thin areas on
@item trailing-whitespace
@kindex trailing-whitespace @r{(face name)}
-This face is used to display excess whitespace at the end of a line.
+This face is used to display excess whitespace at the end of a line,
+if @code{show-trailing-whitespace} is non-@code{nil}.
@end table
In contrast, these faces are provided to change the appearance of text
@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 diffrent variable-width font, if
+reasonable to customize this to use a different variable-width font, if
you like, but you should not make it a fixed-width font.
@end table
+@defvar show-trailing-whitespace
+@tindex show-trailing-whitespace
+If this variable is non-@code{nil}, Emacs uses the
+@code{trailing-whitespace} face to display any spaces and tabs at the
+end of a line.
+@end defvar
+
@node Defining Faces
@subsection Defining Faces
emacs, The GNU Emacs Manual}).
@defmac defface face spec doc [keyword value]...
-@tindex defface
-Declare @var{face} as a customizable face that defaults according to
-@var{spec}. Do not quote the symbol @var{face}. The argument @var{doc}
-specifies the face documentation.
+This declares @var{face} as a customizable face that defaults according
+to @var{spec}. You should not quote the symbol @var{face}. The
+argument @var{doc} specifies the face documentation. The keywords you
+can use in @code{defface} are the same ones that are meaningful in both
+@code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
When @code{defface} executes, it defines the face according to
@var{spec}, then uses any customizations that were read from the
-@file{.emacs} file to override that specification.
+init file (@pxref{Init File}) to override that specification.
The purpose of @var{spec} is to specify how the face should appear on
different kinds of terminals. It should be an alist whose elements have
-the form @code{(@var{display} @var{atts})}. The element's @sc{car},
-@var{display}, specifies a class of terminals. The @sc{cdr},
+the form @code{(@var{display} @var{atts})}. Each element's @sc{car},
+@var{display}, specifies a class of terminals. The element's second element,
@var{atts}, is a list of face attributes and their values; it specifies
what the face should look like on that kind of terminal. The possible
attributes are defined in the value of @code{custom-face-attributes}.
@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},
@end table
@end defmac
- Here's how the standard face @code{region} could be defined
-with @code{defface}:
+ Here's how the standard face @code{region} is defined:
@example
+@group
(defface region
- ((((class color) (background dark))
- (:background "blue"))
- (t (:background "gray")))
- "Used for displaying the region.")
+ `((((type tty) (class color))
+ (:background "blue" :foreground "white"))
+@end group
+ (((type tty) (class mono))
+ (:inverse-video t))
+ (((class color) (background dark))
+ (:background "blue"))
+ (((class color) (background light))
+ (:background "lightblue"))
+ (t (:background "gray")))
+@group
+ "Basic face for highlighting the region."
+ :group 'basic-faces)
+@end group
@end example
Internally, @code{defface} uses the symbol property
with the customization buffer, and @code{face-documentation} for the
documentation string.
-@tindex frame-background-mode
@defopt frame-background-mode
This option, if non-@code{nil}, specifies the background type to use for
interpreting face definitions. If it is @code{dark}, then Emacs treats
The effect of using a face is determined by a fixed set of @dfn{face
attributes}. This table lists all the face attributes, and what they
-mean. Note that in general, more than one face be specified for a given
-piece of text; when that happens, the attributes of all the faces are
-merged to specify how to display the text. @xref{Merging Faces}.
+mean. Note that in general, more than one face can be specified for a
+given piece of text; when that happens, the attributes of all the faces
+are merged to specify how to display the text. @xref{Merging Faces}.
In Emacs 21, any attribute in a face can have the value
@code{unspecified}. This means the face doesn't specify that attribute.
attribute, that means the next face gets a chance. However, the
@code{default} face must specify all attributes.
- Some of these font attributes are meaningful only on certain
-kinds of displays---if your display cannot handle a certain attribute,
-the attribute is ignored.
+ Some of these font attributes are meaningful only on certain kinds of
+displays---if your display cannot handle a certain attribute, the
+attribute is ignored. (The attributes @code{:family}, @code{:width},
+@code{:height}, @code{:weight}, and @code{:slant} correspond to parts of
+an X Logical Font Descriptor.)
@table @code
@item :family
Font family name, or fontset name (@pxref{Fontsets}). If you specify a
-font family name, the wild-cards @samp{*} and @samp{?} are allowed.
+font family name, the wild-card characters @samp{*} and @samp{?} are
+allowed.
@item :width
Relative proportionate width, also known as the character set width or
@code{extra-expanded}, or @code{ultra-expanded}.
@item :height
-Font height, an integer in units of 1/10pt.
+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):
@code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold},
@code{normal}, @code{semi-light}, @code{light}, @code{extra-light},
-@code{ultra-light}, or else @code{nil} meaning this attribute is not
-specified.
+or @code{ultra-light}.
On a text-only terminal, any weight greater than normal is displayed as
extra bright, and any weight less than normal is displayed as
-half-bright (This is provided the terminal supports the feature.)
+half-bright (provided the terminal supports the feature).
@item :slant
Font slant---one of the symbols @code{italic}, @code{oblique}, @code{normal},
value should be @code{t} (yes) or @code{nil} (no).
@item :stipple
-The background stipple, a bitmap name.
+The background stipple, a bitmap.
-The value can be a string; then is the name of a file of pixmap data.
-The file is found in the directories listed in the variable
-@code{x-bitmap-file-path}.
+The value can be a string; that should be the name of a file containing
+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 be a list of the form @code{(@var{width}
-@var{height} @var{data})}. Here, width and height are the size in
-pixels, and @var{data} is a string containing the raw bits of the
-bitmap.
+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.
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. See below for the possible
-values and what they mean.
+width of the box lines, and 3D appearance.
@end table
Here are the possible values of the @code{:box} attribute, and what
The attributes @code{:overline}, @code{:strike-through} and
@code{:box} are new in Emacs 21. The attributes @code{:family},
@code{:height}, @code{:width}, @code{:weight}, @code{:slant} are also
-new, previous versions had another way to specify some of the same
-information.
+new; previous versions used the following attributes, now semi-obsolete,
+to specify some of the same information:
@table @code
@item :font
-This attribute specified the font name.
+This attribute specifies the font name.
@item :bold
A non-@code{nil} value specifies a bold font.
@table @code
@item :font
-@code{:font} is not really a font attribute, but you can use it in
-@code{set-face-attribute} to specify several attributes at once. You
-specify an X font name as the value, and based on this font name, and
-it sets the attributes @code{:family}, @code{:width}, @code{:height},
-@code{:weight}, and @code{:slant} according to the font name.
+You can specify an X font name as the ``value'' of this ``attribute'';
+that sets the @code{:family}, @code{:width}, @code{:height},
+@code{:weight}, and @code{:slant} attributes according to the font name.
If the value is a pattern with wildcards, the first font that matches
the pattern is used to set these attributes.
for bitmap files, for the @code{:stipple} attribute.
@end defvar
+@defun bitmap-spec-p object
+This returns @code{t} if @var{object} is a valid bitmap
+specification, suitable for use with @code{:stipple}.
+It returns @code{nil} otherwise.
+@end defun
+
@node Attribute Functions
@subsection Face Attribute Functions
The extra arguments @var{arguments} specify the attributes to set, and
the values for them. They should consist of alternating attribute names
-(such as @code{:family} or @code{:underline} and corresponding values.
+(such as @code{:family} or @code{:underline}) and corresponding values.
Thus,
@example
@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.
@end example
@end defun
- For older Emacs versions, you can these functions to set
+ The functions above did not exist before Emacs 21. For compatibility
+with older Emacs versions, you can use the following functions to set
and examine the face attributes which existed in those versions.
@defun set-face-foreground face color &optional frame
@end defun
@defun set-face-bold-p face bold-p &optional frame
-@tindex set-face-bold-p
This function specifies whether @var{face} should be bold. If
@var{bold-p} is non-@code{nil}, that means yes; @code{nil} means no.
@end defun
@defun set-face-italic-p face italic-p &optional frame
-@tindex set-face-italic-p
This function specifies whether @var{face} should be italic. If
@var{italic-p} is non-@code{nil}, that means yes; @code{nil} means no.
These functions examine the attributes of a face. If you don't
specify @var{frame}, they refer to the default data for new frames.
+They return the symbol @code{unspecified} if the face doesn't define any
+value for that attribute.
@defun face-foreground face &optional frame
@defunx face-background face &optional frame
@end defun
@defun face-bold-p face &optional frame
-@tindex face-bold-p
This function returns @code{t} if @var{face} is bold---that is, if it is
bolder than normal. It returns @code{nil} otherwise.
@end defun
@defun face-italic-p face &optional frame
-@tindex face-italic-p
This function returns @code{t} if @var{face} is italic or oblique,
@code{nil} otherwise.
@end defun
and character's registry and encoding. If there is a font that matches
exactly, it is used, of course. The hard case is when no available font
exactly fits the specification. Then Emacs looks for one that is
-``close''---one attribute at a time. You can specify the order
-to consider the attributes.
+``close''---one attribute at a time. You can specify the order to
+consider the attributes. In the case where a specified font family is
+not available, you can specify a set of mappings for alternatives to
+try.
@defvar face-font-selection-order
@tindex face-font-selection-order
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
@noindent
allows the use of scalable fonts with registry @code{muleindian-2}.
-@end example
+@end defvar
@defun clear-face-cache &optional unload-p
@tindex clear-face-cache
@end defun
@defun face-documentation face
-@tindex face-documentation
This function returns the documentation string of face @var{face}, or
@code{nil} if none was specified for it.
@end defun
@defun face-differs-from-default-p face &optional frame
This returns @code{t} if the face @var{face} displays differently from
-the default face. A face is considered to be ``the same'' as the normal
-face if each attribute is either the same as that of the default face or
-@code{nil} (meaning to inherit from the default).
-@end defun
-
-@tindex frame-update-face-colors
-@defun frame-update-face-colors frame
-This function updates the way faces display on @var{frame}, for a change
-in @var{frame}'s foreground or background color.
+the default face. A face is considered to be ``the same'' as the
+default face if each attribute is either the same as that of the default
+face, or unspecified (meaning to inherit from the default).
@end defun
@node Auto Faces
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:
@end example
@noindent
-the font specification for ASCII characters would be this:
+the font specification for @sc{ascii} characters would be this:
@example
-*-fixed-medium-r-normal-*-24-*-ISO8859-1
@cindex display specification
@kindex display @r{(text property)}
- The @code{display} text property is used to insert images into text,
-and also control other aspects of how text displays. These features are
-available starting in Emacs 21. The value of the @code{display}
-property should be a display specification, or a list or vector
-containing several display specifications. The rest of this section
-describes several kinds of display specifications and what they mean.
+ The @code{display} text property (or overlay property) is used to
+insert images into text, and also control other aspects of how text
+displays. These features are available starting in Emacs 21. The value
+of the @code{display} property should be a display specification, or a
+list or vector containing several display specifications. The rest of
+this section describes several kinds of display specifications and what
+they mean.
@menu
-* Specified Space::
-* Other Display Specs::
-* Display Margins::
-* Conditional Display::
+* Specified Space:: Displaying one space with a specified width.
+* Other Display Specs:: Displaying an image; magnifying text; moving it
+ up or down on the page; adjusting the width
+ of spaces within text.
+* Display Margins:: Displaying text or images to the side of the main text.
+* Conditional Display:: Making any of the above features conditional
+ depending on some Lisp expression.
@end menu
@node Specified Space
@cindex variable-width spaces
To display a space of specified width and/or height, use a display
-specification of the form @code{(space @var{props})}, where @var{props}
-is a property list (see below). You can put this property on one or
-more consecutive characters; a space of the specified height and width
-is displayed in place of @emph{all} of those characters.
+specification of the form @code{(space . @var{props})}, where
+@var{props} is a property list (a list of alternating properties and
+values). You can put this property on one or more consecutive
+characters; a space of the specified height and width is displayed in
+place of @emph{all} of those characters. These are the properties you
+can use to specify the weight of the space:
@table @code
@item :width @var{width}
@item :align-to @var{hpos}
Specifies that the space should be wide enough to reach @var{hpos}. The
-value @var{hpos} is measured in units of the normal character width.
+value @var{hpos} is measured in units of the normal character width. It
+may be an interer or a floating point number.
@end table
Exactly one of the above properties should be used. You can also
@item :ascent @var{ascent}
Specifies that @var{ascent} percent of the height of the space should be
-considered as the ascent of the space. The value of @var{ascent} must
-be a non-negative number no greater than 100.
+considered as the ascent of the space---that is, the part above the
+baseline. The value of @var{ascent} must be a non-negative number no
+greater than 100.
@end table
You should not use both @code{:height} and @code{:relative-height}
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 spaces in the text that has
-the specification. It displays all of these spaces @var{factor} times
-as wide as normal. The element @var{factor} should be an integer or
-float.
+This display specification affects all the space characters within the
+text that has the specification. It displays all of these spaces
+@var{factor} times as wide as normal. The element @var{factor} should
+be an integer or float. Characters other than spaces are not affected
+at all; in particular, this has no effect on tab characters.
@item (height @var{height})
This display specification makes the text taller or shorter.
@table @asis
@item @code{(+ @var{n})}
This means to use a font that is @var{n} steps larger. A ``step'' is
-defined by the set of available fonts; each size for which a font is
-available counts as a step. @var{n} should be an integer.
+defined by the set of available fonts---specifically, those that match
+what was otherwise specified for this text, in all attributes except
+height. Each size for which a suitable font is available counts as
+another step. @var{n} should be an integer.
@item @code{(- @var{n})}
This means to use a font that is @var{n} steps smaller.
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
@end defvar
@menu
-* Image Descriptors::
-* XBM Images::
-* XPM Images::
-* GIF Images::
-* Postscript Images::
-* Other Image Types::
-* Defining Images::
-* Showing Images::
-* Image Cache::
+* Image Descriptors:: How to specify an image for use in @code{:display}.
+* XBM Images:: Special features for XBM format.
+* XPM Images:: Special features for XPM format.
+* GIF Images:: Special features for GIF format.
+* Postscript Images:: Special features for Postscript format.
+* Other Image Types:: Various other formats are supported.
+* Defining Images:: Convenient ways to define an image for later use.
+* Showing Images:: Convenient ways to display an image once it is defined.
+* Image Cache:: Internal mechanisms of image display.
@end menu
@node Image Descriptors
An image description is a list of the form @code{(image
. @var{props})}, where @var{props} is a property list containing
alternating keyword symbols (symbols whose names start with a colon) and
-their values. Every image descriptor must contain the property
-@code{:type @var{type}} to specify the format of the image. The value
-of @var{type} should be an image type symbol; for example, @code{xpm}
-for an image in XPM format.
+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 @code{:type
+@var{type}} to specify the format of the image. The value of @var{type}
+should be an image type symbol; for example, @code{xpm} for an image in
+XPM format.
Here is a list of other properties that are meaningful for all image
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.
-
-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.
-
-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})}.
-
-@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.
-However, only certain image types support @code{:data}; for other types,
-you must use @code{:file}.
+@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
+
+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
+@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
+
+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 disabled
+Specifies transforming the image so that it looks ``disabled''.
+@end table
-The formats that support @code{:data} include XBM and XPM.
-Before using @code{:data}, see the section describing the specific
-format you wish to use for further information.
+@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
+(@pxref{Input Focus}).
+@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
- You can specify an XBM image using data within Emacs instead
-of an external file. To do this, don't use @code{:file}; instead,
-use the following three properties (all of them):
+ If you specify an XBM image using data within Emacs instead of an
+external file, use the following three properties:
@table @code
-@item :width @var{width}
-The value, @var{width}, specifies the width the image in pixels.
+@item :data @var{data}
+The value, @var{data}, specifies the contents of the image.
+There are three formats you can use for @var{data}:
-@item :height @var{height}
-The value, @var{height}, specifies the height of the image in pixels.
+@itemize @bullet
+@item
+A vector of strings or bool-vectors, each specifying one line of the
+image. Do specify @code{:height} and @code{:width}.
-@item :data @var{data}
-The value, @var{data}, is normally a string or a bool-vector. Either
-way, it must contain enough bits for the area of the image: at least
-@var{width} * @code{height}.
+@item
+A string containing the same byte sequence as an XBM file would contain.
+You must not specify @code{:height} and @code{:width} in this case,
+because omitting them is what indicates the data has the format of an
+XBM file. The file contents specify the height and width of the image.
-Alternatively, @var{data} can be a vector of strings or bool-vectors,
-each specifying one line of the image.
+@item
+A string or a bool-vector containing the bits of the image (plus perhaps
+some extra bits at the end that will not be used). It should contain at
+least @var{width} * @code{height} bits. In this case, you must specify
+@code{:height} and @code{:width}, both to indicate that the string
+contains just the bits rather than a whole XBM file, and to specify the
+size of the image.
+@end itemize
+
+@item :width @var{width}
+The value, @var{width}, specifies the width of the image, in pixels.
+
+@item :height @var{height}
+The value, @var{height}, specifies the height of the image, in pixels.
@end table
@node XPM Images
@subsection XPM Images
@cindex XPM
- To use XPM format, specify @code{xpm} as the image type. These
-additional image properties are meaningful with the @code{xpm} image
-type:
+ To use XPM format, specify @code{xpm} as the image type. The
+additional image property @code{:color-symbols} is also meaningful with
+the @code{xpm} image type:
@table @code
@item :color-symbols @var{symbols}
form @code{(@var{name} . @var{color})}. In each element, @var{name} is
the name of a color as it appears in the image file, and @var{color}
specifies the actual color to use for displaying that name.
-
-@item :data @var{data}
-XPM images can be displayed from data instead of files. In that case,
-use the @code{:data} property instead of the @code{:file} property.
-
-The value @var{data} must be a string containing an XPM image. The
-contents of the string have same format as an external XPM file.
@end table
@node GIF Images
@end example
@end table
+ Displaying Postscript images from Lisp data is not currently
+implemented, but it may be implemented by the time you read this.
+See the @file{etc/NEWS} file to make sure.
+
@node Other Image Types
@subsection Other Image Types
@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}. There are no
-additional image properties defined.
+ For JPEG images, specify image type @code{jpeg}.
For TIFF images, specify image type @code{tiff}.
@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
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:
-@smallexample
-(defimage test-image ((:type xpm :file \"~/test1.xpm\")
- (:type xbm :file \"~/test1.xbm\")))"
-@end smallexample
+@example
+(defimage test-image
+ '((:type xpm :file "~/test1.xpm")
+ (:type xbm :file "~/test1.xbm")))
+@end example
@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
+@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 &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
-@code{defimage}.
+@code{defimage}. The argument @var{string} specifies the text to put in
+the buffer to hold the image.
The argument @var{area} specifies whether to put the image in a margin.
If it is @code{left-margin}, the image appears in the left margin;
@code{nil} or omitted, the image is displayed at point within the
buffer's text.
-Internally, this function inserts an @samp{x} in the buffer, and gives
-it a @code{display} property which specifies this image. @xref{Display
+Internally, this function inserts @var{string} in the buffer, and gives
+it a @code{display} property which specifies @var{image}. @xref{Display
Property}.
@end defun
-@defun put-image image pos &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
+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}.
@var{start} and @var{end}. If @var{buffer} is omitted or @code{nil},
images are removed from the current buffer.
-This remove only images that were put into @var{buffer} the way
+This removes only images that were put into @var{buffer} the way
@code{put-image} does it, not images that were inserted with
@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 (@pxref{Input
+Focus}).
+@end defun
+
@node Image Cache
@subsection Image Cache
display them again more efficiently. It removes an image from the cache
when it hasn't been displayed for a specified period of time.
+When an image is looked up in the cache, its specification is compared
+with cached image specifications using @code{equal}. This means that
+all images with equal specifications share the same image in the cache.
+
@defvar image-cache-eviction-delay
@tindex image-cache-eviction-delay
This variable specifies the number of seconds an image can remain in the
only the cache for that frame is cleared. Otherwise all frames' caches
are cleared.
@end defun
+
@node Blinking
@section Blinking Parentheses
@cindex parenthesis matching
@end defopt
@defopt mode-line-inverse-video
-This variable controls the use of inverse video for mode lines. If it
-is non-@code{nil}, then mode lines are displayed in inverse video.
-Otherwise, mode lines are displayed normally, just like text. The
-default is @code{t}.
-
-For window frames, this displays mode lines using the face named
-@code{modeline}, which is normally the inverse of the default face
-unless you change it.
+This variable controls the use of inverse video for mode lines and menu
+bars. If it is non-@code{nil}, then these lines are displayed in
+inverse video. Otherwise, these lines are displayed normally, just like
+other text. The default is @code{t}.
+
+For window frames, this feature actually applies the face named
+@code{mode-line}; that face is normally set up as the inverse of the
+default face, unless you change it.
@end defopt
@node Usual Display
buffers that do not override it. @xref{Default Value}.
@end defvar
+@defopt indicate-empty-lines
+@tindex indicate-empty-lines
+When this is non-@code{nil}, Emacs displays a special glyph in
+each empty line at the end of the buffer, on terminals that
+support it (window systems).
+@end defopt
+
@defopt tab-width
The value of this variable is the spacing between tab stops used for
-displaying tab characters in Emacs buffers. The default is 8. Note
-that this feature is completely independent of the user-settable tab
-stops used by the command @code{tab-to-tab-stop}. @xref{Indent Tabs}.
+displaying tab characters in Emacs buffers. The value is in units of
+columns, and the default is 8. Note that this feature is completely
+independent of the user-settable tab stops used by the command
+@code{tab-to-tab-stop}. @xref{Indent Tabs}.
@end defopt
@node Display Tables
@end example
@defun display-table-slot display-table slot
-@tindex display-table-slot
This function returns the value of the extra slot @var{slot} of
@var{display-table}. The argument @var{slot} may be a number from 0 to
5 inclusive, or a slot name (symbol). Valid symbols are
@end defun
@defun set-display-table-slot display-table slot value
-@tindex set-display-table-slot
This function stores @var{value} in the extra slot @var{slot} of
@var{display-table}. The argument @var{slot} may be a number from 0 to
5 inclusive, or a slot name (symbol). Valid symbols are
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:
mod 524288 is the character to output, and the glyph code divided by
524288 specifies the face number (@pxref{Face Functions}) to use while
outputting it. (524288 is
-@ifinfo
+@ifnottex
2**19.)
-@end ifinfo
+@end ifnottex
@tex
$2^{19}$.)
@end tex
@end defopt
@defvar ring-bell-function
-@tindex ring-bell-function
If this is non-@code{nil}, it specifies how Emacs should ``ring the
-bell.'' Its value should be a function of no arguments.
+bell.'' Its value should be a function of no arguments. If this is
+non-@code{nil}, it takes precedence over the @code{visible-bell}
+variable.
@end defvar
@node Window Systems
@item pc
Emacs is displaying using MS-DOS.
@item w32
-Emacs is displaying using Windows NT or Windows 9x.
+Emacs is displaying using Windows.
@item mac
Emacs is displaying using a Macintosh.
@item nil
@defvar window-setup-hook
This variable is a normal hook which Emacs runs after handling the
initialization files. Emacs runs this hook after it has completed
-loading your @file{.emacs} file, the default initialization file (if
+loading your init file, the default initialization file (if
any), and the terminal-specific Lisp code, and running the hook
@code{term-setup-hook}.