@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-2013 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-2014 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Display
@chapter Emacs Display
* Selective Display:: Hiding part of the buffer text (the old way).
* Temporary Displays:: Displays that go away automatically.
* Overlays:: Use overlays to highlight parts of the buffer.
-* Width:: How wide a character or string is on the screen.
+* Size of Displayed Text:: How large displayed text is.
* Line Height:: Controlling the height of lines.
* Faces:: A face defines a graphics style for text characters:
font, colors, etc.
* Fringes:: Controlling window fringes.
* Scroll Bars:: Controlling vertical scroll bars.
+* Window Dividers:: Separating windows visually.
* Display Property:: Enabling special display features.
* Images:: Displaying images in Emacs buffers.
* Buttons:: Adding clickable buttons to Emacs buffers.
@node Refresh Screen
@section Refreshing the Screen
+@cindex refresh the screen
+@cindex screen refresh
The function @code{redraw-frame} clears and redisplays the entire
contents of a given frame (@pxref{Frames}). This is useful if the
@defun redisplay &optional force
This function tries immediately to redisplay. The optional argument
@var{force}, if non-@code{nil}, forces the redisplay to be performed,
-instead of being preempted, even if input is pending and the variable
-@code{redisplay-dont-pause} is @code{nil} (see below). If
-@code{redisplay-dont-pause} is non-@code{nil} (the default), this
-function redisplays in any case, i.e., @var{force} does nothing.
+instead of being preempted if input is pending.
The function returns @code{t} if it actually tried to redisplay, and
@code{nil} otherwise. A value of @code{t} does not mean that
newly arriving input.
@end defun
-@defvar redisplay-dont-pause
-If this variable is @code{nil}, arriving input events preempt
-redisplay; Emacs avoids starting a redisplay, and stops any redisplay
-that is in progress, until the input has been processed. In
-particular, @code{(redisplay)} returns @code{nil} without actually
-redisplaying, if there is pending input.
-
-The default value is @code{t}, which means that pending input does not
-preempt redisplay.
-@end defvar
-
-@defvar redisplay-preemption-period
-If @code{redisplay-dont-pause} is @code{nil}, this variable specifies
-how many seconds Emacs waits between checks for new input during
-redisplay; if input arrives during this interval, redisplay stops and
-the input is processed. The default value is 0.1; if the value is
-@code{nil}, Emacs does not check for input during redisplay.
-
-This variable has no effect when @code{redisplay-dont-pause} is
-non-@code{nil} (the default).
+@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
@end defopt
@defopt truncate-partial-width-windows
+@cindex partial-width windows
This variable controls line truncation in @dfn{partial-width} windows.
A partial-width window is one that does not occupy the entire frame
width (@pxref{Splitting Windows}). If the value is @code{nil}, line
over the @code{line-prefix} variable. @xref{Special Properties}.
@end defvar
- If your buffer contains @emph{very} long lines, and you use
-continuation to display them, computing the continuation lines can
-make redisplay slow. The column computation and indentation functions
-also become slow. Then you might find it advisable to set
-@code{cache-long-line-scans} to @code{t}.
+@ignore
+ If your buffer contains only very short lines, you might find it
+advisable to set @code{cache-long-scans} to @code{nil}.
-@defvar cache-long-line-scans
-If this variable is non-@code{nil}, various indentation and motion
-functions, and Emacs redisplay, cache the results of scanning the
-buffer, and consult the cache to avoid rescanning regions of the buffer
-unless they are modified.
+@defvar cache-long-scans
+If this variable is non-@code{nil} (the default), various indentation
+and motion functions, and Emacs redisplay, cache the results of
+scanning the buffer, and consult the cache to avoid rescanning regions
+of the buffer unless they are modified.
-Turning on the cache slows down processing of short lines somewhat.
+Turning off the cache speeds up processing of short lines somewhat.
This variable is automatically buffer-local in every buffer.
@end defvar
+@end ignore
@node The Echo Area
@section The Echo Area
@cindex error display
@cindex echo area
+@c FIXME: Why not use @xref{Minibuffers} directly? --xfq
The @dfn{echo area} is used for displaying error messages
(@pxref{Errors}), for messages made with the @code{message} primitive,
and for echoing keystrokes. It is not the same as the minibuffer,
The first two arguments have the same meaning as for
@code{progress-reporter-update}. Optional @var{new-message} allows
-you to change the message of the @var{reporter}. Since this functions
+you to change the message of the @var{reporter}. Since this function
always updates the echo area, such a change will be immediately
presented to the user.
@end defun
Almost all the messages displayed in the echo area are also recorded
in the @file{*Messages*} buffer so that the user can refer back to
them. This includes all the messages that are output with
-@code{message}.
+@code{message}. By default, this buffer is read-only and uses the major
+mode @code{messages-buffer-mode}. Nothing prevents the user from
+killing the @file{*Messages*} buffer, but the next display of a message
+recreates it. Any Lisp code that needs to access the
+@file{*Messages*} buffer directly and wants to ensure that it exists
+should use the function @code{messages-buffer}.
+
+@defun messages-buffer
+This function returns the @file{*Messages*} buffer. If it does not
+exist, it creates it, and switches it to @code{messages-buffer-mode}.
+@end defun
@defopt message-log-max
This variable specifies how many lines to keep in the @file{*Messages*}
@node Echo Area Customization
@subsection Echo Area Customization
+@cindex echo area customization
These variables control details of how the echo area works.
@defopt echo-keystrokes
This variable determines how much time should elapse before command
-characters echo. Its value must be an integer or floating point number,
-which specifies the
+characters echo. Its value must be a number, and 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
@code{condition-case}, the user won't see the error message; it could
show the message to the user by reporting it as a warning.)
+@c FIXME: Why use "(bytecomp)" instead of "'bytecomp" or simply
+@c "bytecomp" here? The parens are part of warning-type-format but
+@c not part of the warning type. --xfq
@cindex warning type
Each warning has a @dfn{warning type} to classify it. The type is a
list of symbols. The first symbol should be the custom group that you
@defun lwarn type level message &rest args
This function reports a warning using the value of @code{(format
-@var{message} @var{args}...)} as the message. In other respects it is
-equivalent to @code{display-warning}.
+@var{message} @var{args}...)} as the message in the @file{*Warnings*}
+buffer. In other respects it is equivalent to @code{display-warning}.
@end defun
@defun warn message &rest args
@node Warning Variables
@subsection Warning Variables
+@cindex warning variables
Programs can customize how their warnings appear by binding
the variables described in this section.
@node Warning Options
@subsection Warning Options
+@cindex warning options
These variables are used by users to control what happens
when a Lisp program reports a warning.
@node Delayed Warnings
@subsection Delayed Warnings
+@cindex delayed warnings
Sometimes, you may wish to avoid showing a warning while a command is
running, and only show it only after the end of the command. You can
@vindex line-move-ignore-invisible
Ordinarily, functions that operate on text or move point do not care
-whether the text is invisible. The user-level line motion commands
-ignore invisible newlines if @code{line-move-ignore-invisible} is
-non-@code{nil} (the default), but only because they are explicitly
-programmed to do so.
-
- However, if a command ends with point inside or at the boundary of
+whether the text is invisible, they process invisible characters and
+visible characters alike. The user-level line motion commands,
+such as @code{next-line}, @code{previous-line}, ignore invisible
+newlines if @code{line-move-ignore-invisible} is non-@code{nil} (the
+default), i.e., behave like these invisible newlines didn't exist in
+the buffer, but only because they are explicitly programmed to do so.
+
+ If a command ends with point inside or at the boundary of
invisible text, the main editing loop relocates point to one of the
two ends of the invisible text. Emacs chooses the direction of
relocation so that it is the same as the overall movement direction of
to the first visible character that follows the invisible text and then forward
one more character.
+ These @dfn{adjustments} of point that ended up in the middle of
+invisible text can be disabled by setting @code{disable-point-adjustment}
+to a non-@code{nil} value. @xref{Adjusting Point}.
+
Incremental search can make invisible overlays visible temporarily
and/or permanently when a match includes invisible text. To enable
this, the overlay should have a non-@code{nil}
@dfn{Selective display} refers to a pair of related features for
hiding certain lines on the screen.
- The first variant, explicit selective display, is designed for use
-in a Lisp program: it controls which lines are hidden by altering the
-text. This kind of hiding in some ways resembles the effect of the
-@code{invisible} property (@pxref{Invisible Text}), but the two
-features are different and do not work the same way.
+@cindex explicit selective display
+ The first variant, explicit selective display, was designed for use in a Lisp
+program: it controls which lines are hidden by altering the text. This kind of
+hiding is now obsolete; instead you can get the same effect with the
+@code{invisible} property (@pxref{Invisible Text}).
In the second variant, the choice of lines to hide is made
automatically based on indentation. This variant is designed to be a
@node Temporary Displays
@section Temporary Displays
+@cindex temporary display
+@cindex temporary buffer display
Temporary displays are used by Lisp programs to put output into a
buffer and then present it to the user for perusal rather than for
editing. Many help commands use this feature.
-@defmac with-output-to-temp-buffer buffer-name forms@dots{}
-This function executes @var{forms} while arranging to insert any output
-they print into the buffer named @var{buffer-name}, which is first
-created if necessary, and put into Help mode. Finally, the buffer is
-displayed in some window, but not selected. (See the similar
-form @code{with-temp-buffer-window} below.)
-
-If the @var{forms} do not change the major mode in the output buffer,
-so that it is still Help mode at the end of their execution, then
-@code{with-output-to-temp-buffer} makes this buffer read-only at the
-end, and also scans it for function and variable names to make them
-into clickable cross-references. @xref{Docstring hyperlinks, , Tips
-for Documentation Strings}, in particular the item on hyperlinks in
+@defmac with-output-to-temp-buffer buffer-name body@dots{}
+This function executes the forms in @var{body} while arranging to insert
+any output they print into the buffer named @var{buffer-name}, which is
+first created if necessary, and put into Help mode. (See the similar
+form @code{with-temp-buffer-window} below.) Finally, the buffer is
+displayed in some window, but that window is not selected.
+
+If the forms in @var{body} do not change the major mode in the output
+buffer, so that it is still Help mode at the end of their execution,
+then @code{with-output-to-temp-buffer} makes this buffer read-only at
+the end, and also scans it for function and variable names to make them
+into clickable cross-references. @xref{Docstring hyperlinks, , Tips for
+Documentation Strings}, in particular the item on hyperlinks in
documentation strings, for more details.
-The string @var{buffer-name} specifies the temporary buffer, which
-need not already exist. The argument must be a string, not a buffer.
-The buffer is erased initially (with no questions asked), and it is
-marked as unmodified after @code{with-output-to-temp-buffer} exits.
+The string @var{buffer-name} specifies the temporary buffer, which need
+not already exist. The argument must be a string, not a buffer. The
+buffer is erased initially (with no questions asked), and it is marked
+as unmodified after @code{with-output-to-temp-buffer} exits.
@code{with-output-to-temp-buffer} binds @code{standard-output} to the
-temporary buffer, then it evaluates the forms in @var{forms}. Output
-using the Lisp output functions within @var{forms} goes by default to
+temporary buffer, then it evaluates the forms in @var{body}. Output
+using the Lisp output functions within @var{body} goes by default to
that buffer (but screen display and messages in the echo area, although
they are ``output'' in the general sense of the word, are not affected).
@xref{Output Functions}.
Several hooks are available for customizing the behavior
of this construct; they are listed below.
-The value of the last form in @var{forms} is returned.
+The value of the last form in @var{body} is returned.
@example
@group
@result{} #<buffer foo>
---------- Buffer: foo ----------
+
20
#<buffer foo>
is current, and the window it was displayed in is selected.
@end defvar
-@defmac with-temp-buffer-window buffer-or-name action quit-function forms@dots{}
-This macro is similar to @code{with-output-to-temp-buffer}.
-Like that construct, it executes @var{forms} while arranging to insert
-any output they print into the buffer named @var{buffer-or-name}.
-Finally, the buffer is displayed in some window, but not selected.
-Unlike @code{with-output-to-temp-buffer}, this does not switch to Help
-mode.
-
-The argument @var{buffer-or-name} specifies the temporary buffer.
-It can be either a buffer, which must already exist, or a string,
-in which case a buffer of that name is created if necessary.
-The buffer is marked as unmodified and read-only when
-@code{with-temp-buffer-window} exits.
+@defmac with-temp-buffer-window buffer-or-name action quit-function body@dots{}
+This macro is similar to @code{with-output-to-temp-buffer}. Like that
+construct, it executes @var{body} while arranging to insert any output
+it prints into the buffer named @var{buffer-or-name} and displays that
+buffer in some window. Unlike @code{with-output-to-temp-buffer},
+however, it does not automatically switch that buffer to Help mode.
+
+Like @code{with-output-to-temp-buffer} it neither makes the buffer
+specified by @var{buffer-or-name} current when executing @var{body}.
+@findex with-current-buffer-window
+The otherwise identical macro @code{with-current-buffer-window} can be
+used to execute @var{body} with that buffer current.
+
+The argument @var{buffer-or-name} specifies the temporary buffer. It
+can be either a buffer, which must already exist, or a string, in which
+case a buffer of that name is created, if necessary. The buffer is
+marked as unmodified and read-only when @code{with-temp-buffer-window}
+exits.
This macro does not call @code{temp-buffer-show-function}. Rather, it
passes the @var{action} argument to @code{display-buffer} in order to
display the buffer.
-The value of the last form in @var{forms} is returned, unless the
-argument @var{quit-function} is specified. In that case,
-it is called with two arguments: the window showing the buffer
-and the result of @var{forms}. The final return value is then
-whatever @var{quit-function} returns.
+The value of the last form in @var{body} is returned, unless the
+argument @var{quit-function} is specified. In that case, it is called
+with two arguments: the window showing the buffer and the result of
+@var{body}. The final return value is then whatever
+@var{quit-function} returns.
@vindex temp-buffer-window-setup-hook
@vindex temp-buffer-window-show-hook
@node Overlays
@section Overlays
@cindex overlays
+@c FIXME: mention intervals in this section?
You can use @dfn{overlays} to alter the appearance of a buffer's text on
the screen, for the sake of presentation features. An overlay is an
@node Managing Overlays
@subsection Managing Overlays
+@cindex managing overlays
+@cindex overlays, managing
This section describes the functions to create, delete and move
overlays, and to examine their contents. Overlay changes are not
@node Overlay Properties
@subsection Overlay Properties
+@cindex overlay properties
Overlay properties are like text properties in that the properties that
alter how a character is displayed can come from either source. But in
Since more than one overlay can specify a property value for the
same character, Emacs lets you specify a priority value of each
-overlay. You should not make assumptions about which overlay will
-prevail when there is a conflict and they have the same priority.
+overlay. In case two overlays have the same priority value, and one
+is nested in the other, then the inner one will have priority over the
+outer one. If neither is nested in the other then you should not make
+assumptions about which overlay will prevail.
These functions read and set the properties of an overlay:
@table @code
@item priority
@kindex priority @r{(overlay property)}
-This property's value (which should be a non-negative integer number)
-determines the priority of the overlay. No priority, or @code{nil},
-means zero.
+This property's value determines the priority of the overlay.
+If you want to specify a priority value, use either @code{nil}
+(or zero), or a positive integer. Any other value has undefined behavior.
The priority matters when two or more overlays cover the same
character and both specify the same property; the one whose
override the face attributes of the lower priority @code{face}
property.
-Currently, all overlays take priority over text properties. Please
-avoid using negative priority values, as we have not yet decided just
-what they should mean.
+Currently, all overlays take priority over text properties.
+
+Note that Emacs sometimes uses non-numeric priority values for some of
+its internal overlays, so do not try to do arithmetic on the
+priority of an overlay (unless it is one that you created). If you
+need to put overlays in priority order, use the @var{sorted} argument
+of @code{overlays-at}. @xref{Finding Overlays}.
@item window
@kindex window @r{(overlay property)}
@node Finding Overlays
@subsection Searching for Overlays
+@cindex searching for overlays
+@cindex overlays, searching for
-@defun overlays-at 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}.
+@defun overlays-at pos &optional sorted
+This function returns a list of all the overlays that cover the character at
+position @var{pos} in the current buffer. If @var{sorted} is non-@code{nil},
+the list is in decreasing order of priority, otherwise it 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:
(point)))
@end smallexample
-@node Width
-@section Width
+@node Size of Displayed Text
+@section Size of Displayed Text
+@cindex size of text on display
+@cindex character width on display
Since not all characters have the same width, these functions let you
check the width of a character. @xref{Primitive Indent}, and
@var{string} extends across the column @var{start-column}.
If @var{ellipsis} is non-@code{nil}, it should be a string which will
-replace the end of @var{str} (including any padding) if it extends
-beyond @var{end-column}, unless the display width of @var{str} is
-equal to or less than the display width of @var{ellipsis}. If
+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{"..."}.
@end example
@end defun
+The following function returns the size in pixels of text as if it were
+displayed in a given window. This function is used by
+@code{fit-window-to-buffer} (@pxref{Resizing Windows}) and
+@code{fit-frame-to-buffer} (@pxref{Size and Position}) to make a window
+exactly as large as the text it contains.
+
+@defun window-text-pixel-size &optional window from to x-limit y-limit mode-and-header-line
+This function returns the size of the text of @var{window}'s buffer in
+pixels. @var{window} must be a live window and defaults to the selected
+one. The return value is a cons of the maximum pixel-width of any text
+line and the maximum pixel-height of all text lines.
+
+The optional argument @var{from}, if non-@code{nil}, specifies the first
+text position to consider and defaults to the minimum accessible
+position of the buffer. If @var{from} is @code{t}, it uses the minimum
+accessible position that is not a newline character. The optional
+argument @var{to}, if non-@code{nil}, specifies the last text position
+to consider and defaults to the maximum accessible position of the
+buffer. If @var{to} is @code{t}, it uses the maximum accessible
+position that is not a newline character.
+
+The optional argument @var{x-limit}, if non-@code{nil}, specifies the
+maximum pixel-width that can be returned. @var{x-limit} @code{nil} or
+omitted, means to use the pixel-width of @var{window}'s body
+(@pxref{Window Sizes}); this is useful when the caller does not intend
+to change the width of @var{window}. Otherwise, the caller should
+specify here the maximum width @var{window}'s body may assume. Text
+whose x-coordinate is beyond @var{x-limit} is ignored. Since
+calculating the width of long lines can take some time, it's always a
+good idea to make this argument as small as needed; in particular, if
+the buffer might contain long lines that will be truncated anyway.
+
+The optional argument @var{y-limit}, if non-@code{nil}, specifies the
+maximum pixel-height that can be returned. Text lines whose
+y-coordinate is beyond @var{y-limit} are ignored. Since calculating the
+pixel-height of a large buffer can take some time, it makes sense to
+specify this argument; in particular, if the caller does not know the
+size of the buffer.
+
+The optional argument @var{mode-and-header-line} @code{nil} or omitted
+means to not include the height of the mode- or header-line of
+@var{window} in the return value. If it is either the symbol
+@code{mode-line} or @code{header-line}, include only the height of that
+line, if present, in the return value. If it is @code{t}, include the
+height of both, if present, in the return value.
+@end defun
+
+
@node Line Height
@section Line Height
@cindex line height
+@cindex height of a line
The total height of each display line consists of the height of the
contents of the line, plus optional additional vertical line spacing
to bring the total line height up to @var{total}. In this case, the
other ways to specify the line spacing are ignored.
+@cindex height spec
Any other kind of property value is a height spec, which translates
into a number---the specified line height. There are several ways to
write a height spec; here's how each of them translates into a number:
lines in a frame, using the @code{line-spacing} frame parameter
(@pxref{Layout Parameters}). However, if the default value of
@code{line-spacing} is non-@code{nil}, it overrides the
-frame's @code{line-spacing} parameter. An integer value specifies the
-number of pixels put below lines. A floating point number specifies
+frame's @code{line-spacing} parameter. An integer specifies the
+number of pixels put below lines. A floating-point number specifies
the spacing relative to the frame's default line height.
@vindex line-spacing
You can specify the line spacing for all lines in a buffer via the
-buffer-local @code{line-spacing} variable. An integer value specifies
-the number of pixels put below lines. A floating point number
+buffer-local @code{line-spacing} variable. An integer specifies
+the number of pixels put below lines. A floating-point number
specifies the spacing relative to the default frame line height. This
overrides line spacings specified for the frame.
The height of the font. In the simplest case, this is an integer in
units of 1/10 point.
-The value can also be a floating point number or a function, which
+The value can also be floating point or a function, which
specifies the height relative to an @dfn{underlying face}
-(@pxref{Displaying Faces}). If the value is a floating point number,
-that specifies the amount by which to scale the height of the
-underlying face. If the value is a function, that function is called
+(@pxref{Displaying Faces}). A floating-point value
+specifies the amount by which to scale the height of the
+underlying face. A function value is called
with one argument, the height of the underlying face, and returns the
height of the new face. If the function is passed an integer
argument, it must return an integer.
black-and-white displays, certain shades of gray are implemented by
stipple patterns.
+@item :distant-foreground
+Alternative foreground color, a string. This is like @code{:foreground}
+but the color is only used as a foreground when the background color is
+near to the foreground that would have been used. This is useful for
+example when marking text (i.e. the region face). If the text has a foreground
+that is visible with the region face, that foreground is used.
+If the foreground is near the region face background,
+@code{:distant-foreground} is used instead so the text is readable.
+
@item :background
Background color, a string. The value can be a system-defined color
name, or a hexadecimal color specification. @xref{Color Names}.
Whether or not characters should be strike-through, and in what
color. The value is used like that of @code{:overline}.
+@cindex 2D box
+@cindex 3D box
@item :box
Whether or not a box should be drawn around characters, its color, the
width of the box lines, and 3D appearance. Here are the possible
the values of the @code{:family}, @code{:foundry}, @code{:width},
@code{:height}, @code{:weight}, and @code{:slant} attributes.
+@cindex inheritance, for faces
@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
@node Defining Faces
@subsection Defining Faces
+@cindex defining faces
@cindex face spec
The usual way to define a face is through the @code{defface} macro.
@var{spec} should be a face spec, as described in the above
documentation for @code{defface}.
+This function also defines @var{face} as a valid face name if it is
+not already one, and (re)calculates its attributes on existing frames.
+
@cindex override spec @r{(for a face)}
The argument @var{spec-type} determines which spec to set. If it is
@code{nil} or @code{face-override-spec}, this function sets the
@dfn{override spec}, which overrides over all other face specs on
-@var{face}. If it is @code{face-defface-spec}, this function sets the
-default face spec (the same one set by @code{defface}). If it is
-@code{reset}, this function clears out all customization specs and
-override specs from @var{face} (in this case, the value of @var{spec}
-is ignored). Any other value of @var{spec-type} is reserved for
-internal use.
+@var{face}. If it is @code{customized-face} or @code{saved-face},
+this function sets the customized spec or the saved custom spec. If
+it is @code{face-defface-spec}, this function sets the default face
+spec (the same one set by @code{defface}). If it is @code{reset},
+this function clears out all customization specs and override specs
+from @var{face} (in this case, the value of @var{spec} is ignored).
+Any other value of @var{spec-type} is reserved for internal use.
@end defun
@node Attribute Functions
@subsection Face Attribute Functions
+@cindex face attributes, access and modification
This section describes functions for directly accessing and
modifying the attributes of a named face.
@end example
@end defun
+@c FIXME: Add an index for "relative face attribute", maybe here? --xfq
@defun face-attribute-relative-p attribute value
This function returns non-@code{nil} if @var{value}, when used as the
value of the face attribute @var{attribute}, is relative. This means
@node Displaying Faces
@subsection Displaying Faces
+@cindex displaying faces
+@cindex face merging
When Emacs displays a given piece of text, the visual appearance of
the text may be determined by faces drawn from different sources. If
@node Face Remapping
@subsection Face Remapping
+@cindex face remapping
The variable @code{face-remapping-alist} is used for buffer-local or
global changes in the appearance of a face. For instance, it is used
@code{mode-line} face.
@end defvar
+@cindex relative remapping, faces
+@cindex base remapping, faces
The following functions implement a higher-level interface to
@code{face-remapping-alist}. Most Lisp code should use these
functions instead of setting @code{face-remapping-alist} directly, to
modes to remap faces in the buffers they control.
@defun face-remap-add-relative face &rest specs
-This functions adds the face spec in @var{specs} as relative
+This function adds the face spec in @var{specs} as relative
remappings for face @var{face} in the current buffer. The remaining
arguments, @var{specs}, should form either a list of face names, or a
property list of attribute/value pairs.
@node Basic Faces
@subsection Basic Faces
+@cindex basic faces
If your Emacs Lisp program needs to assign some faces to text, it is
often a good idea to use certain existing faces or inherit from them,
@node Font Selection
@subsection Font Selection
+@cindex font selection
+@cindex selecting a font
Before Emacs can draw a character on a graphical display, it must
select a @dfn{font} for that character@footnote{In this context, the
until it finds a registry that does exist.
@end defopt
+@cindex scalable fonts
Emacs can make use of scalable fonts, but by default it does not use
them.
expression in the list. For example,
@example
-(setq scalable-fonts-allowed '("muleindian-2$"))
+(setq scalable-fonts-allowed '("iso10646-1$"))
@end example
@noindent
-allows the use of scalable fonts with registry @code{muleindian-2}.
+allows the use of scalable fonts with registry @code{iso10646-1}.
@end defopt
@defvar face-font-rescale-alist
@node Font Lookup
@subsection Looking Up Fonts
+@cindex font lookup
+@cindex looking up fonts
@defun x-list-fonts name &optional reference-face frame maximum width
This function returns a list of available font names that match
@node Fontsets
@subsection Fontsets
+@cindex fontset
A @dfn{fontset} is a list of fonts, each assigned to a range of
character codes. An individual font cannot display the whole range of
If optional argument @var{style-variant-p} is non-@code{nil}, that says
to create bold, italic and bold-italic variants of the fontset as well.
These variant fontsets do not have a short name, only a long one, which
-is made by altering @var{fontpattern} to indicate the bold or italic
+is made by altering @var{fontpattern} to indicate the bold and/or italic
status.
The specification string also says which fonts to use in the fontset.
@node Low-Level Font
@subsection Low-Level Font Representation
+@cindex font property
Normally, it is not necessary to manipulate fonts directly. In case
you need to do so, this section explains how.
@code{font-entity}.
@end defun
+@cindex font object
A font object is a Lisp object that represents a font that Emacs has
@dfn{opened}. Font objects cannot be modified in Lisp, but they can
be inspected.
specifies a position in that string.
@end defun
+@cindex font spec
A font spec is a Lisp object that contains a set of specifications
that can be used to find a font. More than one font may match the
specifications in a font spec.
@item :size
The font size---either a non-negative integer that specifies the pixel
-size, or a floating point number that specifies the point size.
+size, or a floating-point number that specifies the point size.
@item :adstyle
Additional typographic style information for the font, such as
@samp{sans}. The value should be a string or a symbol.
+@cindex font registry
@item :registry
The charset registry and encoding of the font, such as
@samp{iso8859-1}. The value should be a string or a symbol.
The script that the font must support (a symbol).
@item :otf
+@cindex OpenType font
The font must be an OpenType font that supports these OpenType
features, provided Emacs is compiled with support for @samp{libotf} (a
library for performing complex text layout in certain scripts). The
to @var{value}.
@end defun
+@cindex font entity
A font entity is a reference to a font that need not be open. Its
properties are intermediate between a font object and a font spec:
like a font object, and unlike a font spec, it refers to a single,
@defopt indicate-empty-lines
@cindex fringes, and empty line indication
+@cindex empty lines, indicating
When this is non-@code{nil}, Emacs displays a special glyph in the
fringe of each empty line at the end of the buffer, on graphical
displays. @xref{Fringes}. This variable is automatically
@end defopt
@defopt indicate-buffer-boundaries
+@cindex buffer boundaries, indicating
This buffer-local variable controls how the buffer boundaries and
window scrolling are indicated in the window fringes.
@xref{Fringe Bitmaps}.
@end ifnottex
+@c FIXME: I can't find the fringes-indicator-alist variable. Maybe
+@c it should be fringe-indicator-alist or fringe-cursor-alist? --xfq
When @code{fringe-cursor-alist} has a buffer-local value, and there is
no bitmap defined for a cursor type, the corresponding value from the
default value of @code{fringes-indicator-alist} is used.
@node Customizing Bitmaps
@subsection Customizing Fringe Bitmaps
+@cindex fringe bitmaps, customizing
@defun define-fringe-bitmap bitmap bits &optional height width align
This function defines the symbol @var{bitmap} as a new fringe bitmap,
@var{horizontal-type} is not actually meaningful.
@end defun
+@defun window-scroll-bar-width &optional window
+This function returns the width in pixels of @var{window}'s vertical
+scrollbar. @var{window} must be a live window, and defaults to the
+selected window.
+@end defun
+
If you don't specify these values for a window with
@code{set-window-scroll-bars}, the buffer-local variables
@code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being
to use the value specified by the frame.
@end defvar
+@node Window Dividers
+@section Window Dividers
+@cindex window dividers
+@cindex right dividers
+@cindex bottom dividers
+
+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
+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,
+which means that its width contributes to the total width of that
+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 is drawn over the full total width of its window while the right
+divider ends above the bottom divider.
+
+ Dividers can be dragged with the mouse and are therefore useful for
+adjusting the sizes of adjacent windows with the mouse. They also serve
+to visually set apart adjacent windows when no scroll bars or mode lines
+are present. The following three faces allow to customize the
+appearance of dividers:
+
+@table @code
+@item window-divider
+When a divider is less than three pixels wide, it is drawn solidly with
+the foreground of this face. For larger dividers this face is used for
+the inner part only, excluding the first and last pixel.
+
+@item window-divider-first-pixel
+This is the face used for drawing the first pixel of a divider that is
+at least three pixels wide. To obtain a solid appearance, set this to
+the same value used for the @code{window-divider} face.
+
+@item window-divider-last-pixel
+This is the face used for drawing the last pixel of a divider that is at
+least three pixels wide. To obtain a solid appearance, set this to the
+same value used for the @code{window-divider} face.
+@end table
+
+You can get the sizes of the dividers of a specific window with the
+following two functions.
+
+@defun window-right-divider-width &optional window
+Return the width (thickness) in pixels of @var{window}'s right divider.
+@var{window} must be a live window and defaults to the selected one.
+The return value is always zero for a rightmost window.
+@end defun
+
+@defun window-bottom-divider-width &optional window
+Return the width (thickness) in pixels of @var{window}'s bottom divider.
+@var{window} must be a live window and defaults to the selected one.
+The return value is zero for the minibuffer window or a bottommost
+window on a minibuffer-less frame.
+@end defun
+
+
@node Display Property
@section The @code{display} Property
@cindex display specification
@node Replacing Specs
@subsection Display Specs That Replace The Text
+@cindex replacing display specs
Some kinds of display specifications specify something to display
instead of the text that has the property. These are called
@table @code
@item :width @var{width}
-If @var{width} is an integer or floating point number, it specifies
+If @var{width} is a number, it specifies
that the space width should be @var{width} times the normal character
width. @var{width} can also be a @dfn{pixel width} specification
(@pxref{Pixel Specification}).
@table @code
@item :height @var{height}
Specifies the height of the space.
-If @var{height} is an integer or floating point number, it specifies
+If @var{height} is a number, it specifies
that the space height should be @var{height} times the normal character
height. The @var{height} may also be a @dfn{pixel height} specification
(@pxref{Pixel Specification}).
(a partial area) of the image to display. The elements @var{y} and
@var{x} specify the top left corner of the slice, within the image;
@var{width} and @var{height} specify the width and height of the
-slice. Integer values are numbers of pixels. A floating point number
+slice. Integers are numbers of pixels. A floating-point number
in the range 0.0--1.0 stands for that fraction of the width or height
of the entire image.
@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
defined by the set of available fonts---specifically, those that match
what was otherwise specified for this text, in all attributes except
variables:
@defvar left-margin-width
-This variable specifies the width of the left margin.
-It is buffer-local in all buffers.
+This variable specifies the width of the left margin, in character
+cell (a.k.a.@: ``column'') units. It is buffer-local in all buffers.
+A value of @code{nil} means no left marginal area.
@end defvar
@defvar right-margin-width
-This variable specifies the width of the right margin.
-It is buffer-local in all buffers.
+This variable specifies the width of the right margin, in character
+cell units. It is buffer-local in all buffers. A value of @code{nil}
+means no right marginal area.
@end defvar
Setting these variables does not immediately affect the window. These
You can also set the margin widths immediately.
@defun set-window-margins window left &optional right
-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 (default @code{0}).
+This function specifies the margin widths for window @var{window}, in
+character cell units. The argument @var{left} controls the left
+margin, and @var{right} controls the right margin (default @code{0}).
@end defun
@defun window-margins &optional window
-This function returns the left and right margins of @var{window}
-as a cons cell of the form @code{(@var{left} . @var{right})}.
-If @var{window} is @code{nil}, the selected window is used.
+This function returns the width of the left and right margins of
+@var{window} as a cons cell of the form @w{@code{(@var{left}
+. @var{right})}}. If one of the two marginal areas does not exist,
+its width is returned as @code{nil}; if neither of the two margins exist,
+the function returns @code{(nil)}. If @var{window} is @code{nil}, the
+selected window is used.
@end defun
@node Images
Each image descriptor has the form @code{(image . @var{props})},
where @var{props} is a property list of alternating keyword symbols
-and values, including at least the pair @code{:type @var{TYPE}} which
+and values, including at least the pair @code{:type @var{type}} that
specifies the image type.
The following is a list of properties that are meaningful for all
``disabled'' button.
@item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust})
+@cindex edge detection, images
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
image. @xref{Pointer Shape}, for available pointer shapes.
@item :map @var{map}
+@cindex image maps
This associates an image map of @dfn{hot spots} with this image.
An image map is an alist where each element has the format
ImageMagick entirely.
@end defopt
+@defvar image-format-suffixes
+This variable is an alist mapping image types to file name extensions.
+Emacs uses this in conjunction with the @code{:format} image property
+(see below) to give a hint to the ImageMagick library as to the type
+of an image. Each element has the form @code{(@var{type}
+@var{extension})}, where @var{type} is a symbol specifying an image
+content-type, and @var{extension} is a string that specifies the
+associated file name extension.
+@end defvar
+
Images loaded with ImageMagick support the following additional
image descriptor properties:
supports transparency. If the value is @code{nil}, it defaults to the
frame's background color.
-@item :width, :height
+@item :width @var{width}, :height @var{height}
The @code{:width} and @code{:height} keywords are used for scaling the
image. If only one of them is specified, the other one will be
calculated so as to preserve the aspect ratio. If both are specified,
aspect ratio may not be preserved.
-@item :max-width, :max-height
+@item :max-width @var{max-width}, :max-height @var{max-height}
The @code{:max-width} and @code{:max-height} keywords are used for
scaling if the size of the image of the image exceeds these values.
If @code{:width} is set it will have precedence over @code{max-width},
wish. @code{:max-width} and @code{:max-height} will always preserve
the aspect ratio.
-@item :rotation
+@item :format @var{type}
+The value, @var{type}, should be a symbol specifying the type of the
+image data, as found in @code{image-format-suffixes}. This is used
+when the image does not have an associated file name, to provide a
+hint to ImageMagick to help it detect the image type.
+
+@item :rotation @var{angle}
Specifies a rotation angle in degrees.
-@item :index
+@item :index @var{frame}
@c Doesn't work: http://debbugs.gnu.org/7978
@xref{Multi-Frame Images}.
@end table
@node Defining Images
@subsection Defining Images
+@cindex define image
The functions @code{create-image}, @code{defimage} and
@code{find-image} provide convenient ways to create image descriptors.
The remaining arguments, @var{props}, specify additional image
properties---for example,
+@c ':heuristic-mask' is not documented?
@example
(create-image "foo.xpm" 'xpm nil :heuristic-mask t)
@end example
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
+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
@node Showing Images
@subsection Showing Images
+@cindex show image
You can use an image descriptor by setting up the @code{display}
property yourself, but it is easier to use the functions in this
Otherwise, @var{slice} is a list @code{(@var{x} @var{y} @var{width}
@var{height})} which specifies the @var{x} and @var{y} positions and
@var{width} and @var{height} of the image area to insert. Integer
-values are in units of pixels. A floating point number in the range
+values are in units of pixels. A floating-point number in the range
0.0--1.0 stands for that fraction of the width or height of the entire
image.
@end defun
@defun image-size spec &optional pixels frame
+@cindex size of image
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-@code{nil} means return sizes
larger than this limit.
If the value is an integer, it directly specifies the maximum
-image height and width, measured in pixels. If it is a floating
-point number, it specifies the maximum image height and width
+image height and width, measured in pixels. If it is floating
+point, it specifies the maximum image height and width
as a ratio to the frame height and width. If the value is
non-numeric, there is no explicit limit on the size of images.
from accidentally being loaded into Emacs. It only takes effect the
first time an image is loaded. Once an image is placed in the image
cache, it can always be displayed, even if the value of
-@var{max-image-size} is subsequently changed (@pxref{Image Cache}).
+@code{max-image-size} is subsequently changed (@pxref{Image Cache}).
@end defvar
@node Multi-Frame Images
@subsection Multi-Frame Images
+@cindex multi-frame images
@cindex animation
@cindex image animation
forever; if a number animation stops after that many seconds.
@end defun
+@vindex image-minimum-frame-delay
+@vindex image-default-frame-delay
@noindent Animation operates by means of a timer. Note that Emacs imposes a
minimum frame delay of 0.01 (@code{image-minimum-frame-delay}) seconds.
If the image itself does not specify a delay, Emacs uses
@code{button-buffer-map} as a parent keymap for its keymap.
If the button has a non-@code{nil} @code{follow-link} property, and
-@var{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click
+@code{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click
will also activate the @code{push-button} command.
@xref{Clickable Text}.
@defun next-button pos &optional count-current
@defunx previous-button pos &optional count-current
-Return the next button after (for @code{next-button} or before (for
+Return the next button after (for @code{next-button}) or before (for
@code{previous-button}) position @var{pos} in the current buffer. If
@var{count-current} is non-@code{nil}, count any button at @var{pos}
in the search, instead of starting at the next button.
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.
+``model/view/controller'' design paradigm. Ewoc means ``Emacs's
+Widget for Object Collections''.
An @dfn{ewoc} is a structure that organizes information required to
construct buffer text that represents certain Lisp data. The buffer
The header and footer strings.
@item
+@cindex node, ewoc
+@c or "@cindex node, abstract display"?
A doubly-linked chain of @dfn{nodes}, each of which contains:
@itemize
representation to another, and so forth. @xref{Abstract Display
Functions}.
+@cindex encapsulation, ewoc
+@c or "@cindex encapsulation, abstract display"?
A node @dfn{encapsulates} a data element much the way a variable
holds a value. Normally, encapsulation occurs as a part of adding a
node to the ewoc. You can retrieve the data element value and place a
@end defopt
@defopt blink-matching-delay
-This variable specifies the number of seconds for the cursor to remain
-at the matching parenthesis. A fraction of a second often gives
-good results, but the default is 1, which works on all systems.
+This variable specifies the number of seconds to keep indicating the
+matching parenthesis. A fraction of a second often gives good
+results, but the default is 1, which works on all systems.
@end defopt
@deffn Command blink-matching-open
This function is the default value of @code{blink-paren-function}. It
-assumes that point follows a character with close parenthesis syntax and
-moves the cursor momentarily to the matching opening character. If that
-character is not already on the screen, it displays the character's
-context in the echo area. To avoid long delays, this function does not
-search farther than @code{blink-matching-paren-distance} characters.
+assumes that point follows a character with close parenthesis syntax
+and applies the appropriate effect momentarily to the matching opening
+character. If that character is not already on the screen, it
+displays the character's context in the echo area. To avoid long
+delays, this function does not search farther than
+@code{blink-matching-paren-distance} characters.
Here is an example of calling this function explicitly.
@smallexample
@group
(defun interactive-blink-matching-open ()
- "Indicate momentarily the start of sexp before point."
+ "Indicate momentarily the start of parenthesized sexp before point."
(interactive)
@end group
@group
@subsection Glyphs
@cindex glyph
+@cindex glyph code
A @dfn{glyph} is a graphical symbol which occupies a single
character position on the screen. Each glyph is represented in Lisp
as a @dfn{glyph code}, which specifies a character and optionally a
@code{display-graphic-p} or any of the other @code{display-*-p}
predicates described in @ref{Display Feature Testing}.
-@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 init file, the default initialization file (if
-any), and the terminal-specific Lisp code, and running the hook
-@code{term-setup-hook}.
-
-This hook is used for internal purposes: setting up communication with
-the window system, and creating the initial window. Users should not
-interfere with it.
-@end defvar
-
@node Bidirectional Display
@section Bidirectional Display
@cindex bidirectional display
@cindex reading order
@cindex visual order
@cindex unicode bidirectional algorithm
+@cindex UBA
@cindex bidirectional reordering
+@cindex reordering, of bidirectional text
Text is stored in Emacs buffers and strings in @dfn{logical} (or
@dfn{reading}) order, i.e., the order in which a human would read
each character. In right-to-left and bidirectional text, the order in
position. In performing this @dfn{bidirectional reordering}, Emacs
follows the Unicode Bidirectional Algorithm (a.k.a.@: @acronym{UBA}),
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}.
+(@url{http://www.unicode.org/reports/tr9/}). Emacs currently provides
+a ``Non-isolate Bidirectionality'' class implementation of the
+@acronym{UBA}: it does not yet support the isolate directional
+formatting characters introduced with Unicode Standard v6.3.0.
@defvar bidi-display-reordering
If the value of this buffer-local variable is non-@code{nil} (the