-@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
@cindex @samp{\} in display
When a line of text extends beyond the right edge of a window, Emacs
-can @dfn{continue} the line (make it ``wrap'' to the next screen
+can @dfn{continue} the line (make it wrap to the next screen
line), or @dfn{truncate} the line (limit it to one screen line). The
additional screen lines used to display a long text line are called
@dfn{continuation} lines. Continuation is not the same as filling;
indicate truncated and continued lines (@pxref{Fringes}). On a text
terminal, a @samp{$} in the rightmost column of the window indicates
truncation; a @samp{\} on the rightmost column indicates a line that
-``wraps''. (The display table can specify alternate characters to use
+wraps. (The display table can specify alternate characters to use
for this; @pxref{Display Tables}).
@defopt truncate-lines
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
The arguments @var{min-value} and @var{max-value} should be numbers
standing for the starting and final states of the operation. For
-instance, an operation that ``scans'' a buffer should set these to the
+instance, an operation that scans a buffer should set these to the
results of @code{point-min} and @code{point-max} correspondingly.
@var{max-value} should be greater than @var{min-value}.
@defun progress-reporter-done reporter
This function should be called when the operation is finished. It
-prints the message of @var{reporter} followed by word ``done'' in the
+prints the message of @var{reporter} followed by word @samp{done} in the
echo area.
You should always call this function and not hope for
-@code{progress-reporter-update} to print ``100%''. Firstly, it may
+@code{progress-reporter-update} to print @samp{100%}. Firstly, it may
never print it, there are many good reasons for this not to happen.
-Secondly, ``done'' is more explicit.
+Secondly, @samp{done} is more explicit.
@end defun
@defmac dotimes-with-progress-reporter (var count [result]) message body@dots{}
successive related messages for the sake of two cases: question
followed by answer, and a series of progress messages.
- A ``question followed by an answer'' means two messages like the
+ A question followed by an answer has two messages like the
ones produced by @code{y-or-n-p}: the first is @samp{@var{question}},
and the second is @samp{@var{question}...@var{answer}}. The first
message conveys no additional information beyond what's in the second,
so logging the second message discards the first from the log.
- A ``series of progress messages'' means successive messages like
+ A series of progress messages has successive messages like
those produced by @code{make-progress-reporter}. They have the form
@samp{@var{base}...@var{how-far}}, where @var{base} is the same each
time, while @var{how-far} varies. Logging each message in the series
This is the only valid way to change the endpoints of an overlay. Do
not try modifying the markers in the overlay by hand, as that fails to
update other vital data structures and can cause some overlays to be
-``lost''.
+lost.
@end defun
@defun remove-overlays &optional start end name value
@end example
Emacs stores the overlays of each buffer in two lists, divided
-around an arbitrary ``center position''. One list extends backwards
+around an arbitrary center position. One list extends backwards
through the buffer from that center position, and the other extends
forwards from that center position. The center position can be anywhere
in the buffer.
@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
@defun overlays-in beg end
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 (@pxref{Managing Overlays,
-empty overlay}) are included in the result if they are located at
+@var{beg} through @var{end}. An overlay overlaps with a region if it
+contains one or more characters in the region; empty overlays
+(@pxref{Managing Overlays, empty overlay}) overlap if they are at
@var{beg}, strictly between @var{beg} and @var{end}, or at @var{end}
when @var{end} denotes the position at the end of the buffer.
@end defun
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)
@item
If the text lies within an overlay with a non-@code{nil} @code{face}
property, Emacs applies the face(s) specified by that property. If
-the overlay has a @code{mouse-face} property and the mouse is ``near
-enough'' to the overlay, Emacs applies the face or face attributes
+the overlay has a @code{mouse-face} property and the mouse is near
+enough to the overlay, Emacs applies the face or face attributes
specified by the @code{mouse-face} property instead. @xref{Overlay
Properties}.
arguments, @var{specs}, should form either a list of face names, or a
property list of attribute/value pairs.
-The return value is a Lisp object that serves as a ``cookie''; you can
+The return value is a Lisp object that serves as a cookie; you can
pass this object as an argument to @code{face-remap-remove-relative}
if you need to remove the remapping later.
often a good idea to use certain existing faces or inherit from them,
rather than defining entirely new faces. This way, if other users
have customized the basic faces to give Emacs a certain look, your
-program will ``fit in'' without additional customization.
+program will fit in without additional customization.
Some of the basic faces defined in Emacs are listed below. In
addition to these, you might want to make use of the Font Lock faces
unspecified (and so given by @code{default}).
@item shadow
-For ``dimmed out'' text. For example, it is used for the ignored
+For dimmed-out text. For example, it is used for the ignored
part of a filename in the minibuffer (@pxref{Minibuffer File,,
Minibuffers for File Names, emacs, The GNU Emacs Manual}).
@item link
@itemx link-visited
For clickable text buttons that send the user to a different
-buffer or ``location''.
+buffer or location.
@item highlight
For stretches of text that should temporarily stand out. For example,
character codes. An individual font cannot display the whole range of
characters that Emacs supports, but a fontset can. Fontsets have names,
just as fonts do, and you can use a fontset name in place of a font name
-when you specify the ``font'' for a frame or a face. Here is
+when you specify the font for a frame or a face. Here is
information about defining a fontset under Lisp program control.
@defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror
maximum length of the returned list. The optional argument
@var{prefer}, if non-@code{nil}, should be another font spec, which is
used to control the order of the returned list; the returned font
-entities are sorted in order of decreasing ``closeness'' to that font
+entities are sorted in order of decreasing closeness to that font
spec.
@end defun
If you call @code{set-face-attribute} and pass a font spec, font
entity, or font name string as the value of the @code{:font}
-attribute, Emacs opens the best ``matching'' font that is available
+attribute, Emacs opens the best matching font that is available
for display. It then stores the corresponding font object as the
actual value of the @code{:font} attribute for that face.
@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
@cindex right dividers
@cindex bottom dividers
-Window dividers are bars drawn between a frame's windows. A ``right''
+Window dividers are bars drawn between a frame's windows. A right
divider is drawn between a window and any adjacent windows on the right.
Its width (thickness) is specified by the frame parameter
-@code{right-divider-width}. A ``bottom'' divider is drawn between a
+@code{right-divider-width}. A bottom divider is drawn between a
window and adjacent windows on the bottom or the echo area. Its width
is specified by the frame parameter @code{bottom-divider-width}. In
either case, specifying a width of zero means to not draw such dividers.
@xref{Layout Parameters}.
- Technically, a right divider ``belongs'' to the window on its left,
+ Technically, a right divider belongs to the window on its left,
which means that its width contributes to the total width of that
-window. A bottom divider ``belongs'' to the window above it, which
+window. A bottom divider belongs to the window above it, which
means that its width contributes to the total height of that window.
@xref{Window Sizes}. When a window has both, a right and a bottom
-divider, the bottom divider ``prevails''. This means that a bottom
+divider, the bottom divider prevails. This means that a bottom
divider is drawn over the full total width of its window while the right
divider ends above the bottom divider.
display specifications make most other display specifications
irrelevant, since those don't apply to the replacement.
- For replacing display specifications, ``the text that has the
-property'' means all the consecutive characters that have the same
+ For replacing display specifications, @dfn{the text that has the
+property} means all the consecutive characters that have the same
Lisp object as their @code{display} property; these characters are
replaced as a single unit. If two characters have different Lisp
objects as their @code{display} properties (i.e., objects which are
@item :relative-width @var{factor}
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 width of that
-character, multiplied by @var{factor}.
+same @code{display} property. The space width is the pixel width of
+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}.
@table @asis
@item @code{(+ @var{n})}
@c FIXME: Add an index for "step"? --xfq
-This means to use a font that is @var{n} steps larger. A ``step'' is
+This means to use a font that is @var{n} steps larger. A @dfn{step} is
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
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.
+disabled button.
@item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust})
@cindex edge detection, images
@end ifnottex
@item disabled
-Specifies transforming the image so that it looks ``disabled''.
+Specifies transforming the image so that it looks disabled.
@end table
@item :mask @var{mask}
@code{insert-image}, but splits the image into @var{rows}x@var{cols}
equally sized slices.
-If an image is inserted ``sliced'', Emacs displays each slice as a
-separate image, and allow more intuitive scrolling up/down, instead of
+Emacs displays each slice as a
+separate image, and allows more intuitive scrolling up/down, instead of
jumping up/down the entire image when paging through a buffer that
displays (large) images.
@end defun
multiple frames for GIF, TIFF, and certain ImageMagick formats such as
DJVM@.
-The frames can be used either to represent multiple ``pages'' (this is
+The frames can be used either to represent multiple pages (this is
usually the case with multi-frame TIFF files, for example), or to
create animation (usually the case with multi-frame GIF files).
specific tasks.
@defun define-button-type name &rest properties
-Define a ``button type'' called @var{name} (a symbol).
+Define a button type called @var{name} (a symbol).
The remaining arguments
form a sequence of @var{property value} pairs, specifying default
property values for buttons with this type (a button's type may be set
These are commands and functions for locating and operating on
buttons in an Emacs buffer.
-@code{push-button} is the command that a user uses to actually ``push''
+@code{push-button} is the command that a user uses to actually push
a button, and is bound by default in the button itself to @key{RET}
and to @key{mouse-2} using a local keymap in the button's overlay or
text properties. Commands that are useful outside the buttons itself,
The Ewoc package constructs buffer text that represents a structure
of Lisp objects, and updates the text to follow changes in that
structure. This is like the ``view'' component in the
-``model/view/controller'' design paradigm. Ewoc means ``Emacs's
+``model--view--controller'' design paradigm. Ewoc means ``Emacs's
Widget for Object Collections''.
An @dfn{ewoc} is a structure that organizes information required to
@noindent
You can also use, as the data element value, a Lisp object (list or
-vector) that is a container for the ``real'' value, or an index into
+vector) that is a container for the real value, or an index into
some other structure. The example (@pxref{Abstract Display Example})
uses the latter approach.
the footer and every node's textual description. If @var{nosep}
is non-@code{nil}, no newline is inserted. This may be useful for
displaying an entire ewoc on a single line, for example, or for
-making nodes ``invisible'' by arranging for @var{pretty-printer}
+making nodes invisible by arranging for @var{pretty-printer}
to do nothing for those nodes.
An ewoc maintains its text in the buffer that is current when
@subsection Abstract Display Example
Here is a simple example using functions of the ewoc package to
-implement a ``color components display'', an area in a buffer that
+implement a @dfn{color components} display, an area in a buffer that
represents a vector of three integers (itself representing a 24-bit RGB
value) in various ways.
@end example
@cindex controller part, model/view/controller
- This example can be extended to be a ``color selection widget'' (in
-other words, the controller part of the ``model/view/controller''
+ This example can be extended to be a color selection widget (in
+other words, the ``controller'' part of the ``model--view--controller''
design paradigm) by defining commands to modify @code{colorcomp-data}
-and to ``finish'' the selection process, and a keymap to tie it all
+and to finish the selection process, and a keymap to tie it all
together conveniently.
@smallexample
@strong{Warning:} if you use the display table to change the display
of newline characters, the whole buffer will be displayed as one long
-``line''.
+line.
- The display table also has six ``extra slots'' which serve special
+ The display table also has six @dfn{extra slots} which serve special
purposes. Here is a table of their meanings; @code{nil} in any slot
means to use the default for that slot, as stated below.
window display table nor a buffer display table defined, or when Emacs
is outputting text to the standard output or error streams. Although its
default is typically @code{nil}, in an interactive session if the
-locale cannot display curved quotes, or if the initial value of
-@code{text-quoting-style} specifies a preference for ASCII, its
-default maps curved quotes to ASCII approximations. @xref{Keys in
-Documentation}.
+terminal cannot display curved quotes, its default maps curved quotes
+to ASCII approximations. @xref{Keys in Documentation}.
@end defvar
The @file{disp-table} library defines several functions for changing
@samp{\230}).
@item format-control
-Characters of Unicode General Category ``Cf'', such as @samp{U+200E}
+Characters of Unicode General Category [Cf], such as @samp{U+200E}
(Left-to-Right Mark), but excluding characters that have graphic
images, such as @samp{U+00AD} (Soft Hyphen).
@end defopt
@defvar 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. If this is
+If this is non-@code{nil}, it specifies how Emacs should ring the
+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
which is described in Annex #9 of the Unicode standard
(@url{http://www.unicode.org/reports/tr9/}). Emacs provides a ``Full
Bidirectionality'' class implementation of the @acronym{UBA},
-consistent with the requirements of the Unicode Standard v7.0.
+consistent with the requirements of the Unicode Standard v8.0.
@defvar bidi-display-reordering
If the value of this buffer-local variable is non-@code{nil} (the
when two strings with bidirectional content are juxtaposed in a
buffer, or otherwise programmatically concatenated into a string of
text. A typical problematic case is when a buffer consists of
-sequences of text ``fields'' separated by whitespace or punctuation
+sequences of text fields separated by whitespace or punctuation
characters, like Buffer Menu mode or Rmail Summary Mode. Because the
punctuation characters used as separators have @dfn{weak
directionality}, they take on the directionality of surrounding text.