-@c -*-texinfo-*-
+@c -*- mode: texinfo; coding: utf-8 -*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-2015 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-2016 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Display
@chapter Emacs Display
newly arriving input.
@end defun
-@defvar pre-redisplay-function
-A function run just before redisplay. It is called with one argument,
-the set of windows to redisplay.
-@end defvar
-
Although @code{redisplay} tries immediately to redisplay, it does
not change how Emacs decides which parts of its frame(s) to redisplay.
By contrast, the following function adds certain windows to the
it waits for input, or when the function @code{redisplay} is called.
@end defun
+@defvar pre-redisplay-function
+A function run just before redisplay. It is called with one argument,
+the set of windows to be redisplayed. The set can be @code{nil},
+meaning only the selected window, or @code{t}, meaning all the
+windows.
+@end defvar
+
+@defvar pre-redisplay-functions
+This hook is run just before redisplay. It is called once in each
+window that is about to be redisplayed, with @code{current-buffer} set
+to the buffer displayed in that window.
+@end defvar
+
@node Truncation
@section Truncation
@cindex line wrapping
The string is also added to the @file{*Messages*} buffer, but without
text properties (@pxref{Logging Messages}).
+In a format string containing single quotes, curved quotes @t{‘like
+this’} and grave quotes @t{`like this'} work better than straight
+quotes @t{'like this'}, as @code{message} typically formats every
+straight quote as a curved closing quote.
+
In batch mode, the message is printed to the standard error stream,
followed by a newline.
@example
@group
-(message "Minibuffer depth is %d."
- (minibuffer-depth))
- @print{} Minibuffer depth is 0.
-@result{} "Minibuffer depth is 0."
+(message "Reverting `%s'..." (buffer-name))
+ @print{} Reverting ‘subr.el’...
+@result{} "Reverting ‘subr.el’..."
@end group
@group
---------- Echo Area ----------
-Minibuffer depth is 0.
+Reverting ‘subr.el’...
---------- 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} (see below).
+
+@strong{Warning:} If you want to use your own string as a message
+verbatim, don't just write @code{(message @var{string})}. If
+@var{string} contains @samp{%}, @samp{`}, or @samp{'} it may be
+reformatted, with undesirable results. Instead, use @code{(message
+"%s" @var{string})}.
@end defun
@defvar inhibit-message
@code{message}.
@end defun
-@defun display-message-or-buffer message &optional buffer-name not-this-window frame
+@defun display-message-or-buffer message &optional buffer-name action frame
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
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
+The optional arguments @var{action} and @var{frame} are as for
@code{display-buffer}, and only used if a buffer is displayed.
@end defun
@item intangible
@kindex intangible @r{(overlay property)}
The @code{intangible} property on an overlay works just like the
-@code{intangible} text property. @xref{Special Properties}, for details.
+@code{intangible} text property. It is obsolete. @xref{Special
+Properties}, for details.
@item isearch-open-invisible
This property tells incremental search how to make an invisible overlay
the beginning of the result if one multi-column character in
@var{string} extends across the column @var{start-column}.
+@vindex truncate-string-ellipsis
If @var{ellipsis} is non-@code{nil}, it should be a string which will
replace the end of @var{string} (including any padding) if it extends
beyond @var{width}, unless the display width of @var{string} is equal
to or less than the display width of @var{ellipsis}. If
@var{ellipsis} is non-@code{nil} and not a string, it stands for
-@code{"..."}.
+the value of the variable @code{truncate-string-ellipsis}.
@example
(truncate-string-to-width "\tab\t" 12 4)
@end table
@end defun
+@cindex font information for layout
+The following four functions return size information about fonts used
+by various faces, allowing various layout considerations in Lisp
+programs. These functions take face remapping into consideration,
+returning information about the remapped face, if the face in question
+was remapped. @xref{Face Remapping}.
+
+@defun default-font-width
+This function returns the average width in pixels of the font used by
+the current buffer's default face.
+@end defun
+
+@defun default-font-height
+This function returns the height in pixels of the font used by the
+current buffer's default face.
+@end defun
+
+@defun window-font-width &optional window face
+This function returns the average width in pixels for the font used by
+@var{face} in @var{window}. The specified @var{window} must be a live
+window. If @code{nil} or omitted, @var{window} defaults to the
+selected window, and @var{face} defaults to the default face in
+@var{window}.
+@end defun
+
+@defun window-font-height &optional window face
+This function returns the height in pixels for the font used by
+@var{face} in @var{window}. The specified @var{window} must be a live
+window. If @code{nil} or omitted, @var{window} defaults to the
+selected window, and @var{face} defaults to the default face in
+@var{window}.
+@end defun
+
@node Fringes
@section Fringes
@cindex fringes
Specifies that the width of the stretch should be computed from the
first character in the group of consecutive characters that have the
same @code{display} property. The space width is the pixel width of
-that character, multiplied by @var{factor}. This specification is
-only supported on graphic terminals.
+that character, multiplied by @var{factor}. (On text-mode terminals,
+the ``pixel width'' of a character is usually 1, but it could be more
+for TABs and double-width CJK characters.)
@item :align-to @var{hpos}
Specifies that the space should be wide enough to reach @var{hpos}.