@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).
-@end defvar
-
@defvar pre-redisplay-function
A function run just before redisplay. It is called with one argument,
the set of windows to redisplay.
@node Echo Area Customization
@subsection Echo Area Customization
+@cindex echo area customization
These variables control details of how the echo area works.
@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}
@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
@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
@table @code
@item priority
@kindex priority @r{(overlay property)}
-This property's value determines the priority of the overlay. No priority, or
-@code{nil}, means zero. A non-nil and non-integer value has
-undefined behavior.
+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 &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-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}.
+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:
@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
@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.
@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.
@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
@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 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
@end defun
@defun window-scroll-bar-width &optional window
-This function returns the width of @var{window}'s vertical scrollbar,
-in pixels. @var{window} must be a live window. If @var{window} is
-@code{nil} or omitted, it will be the selected 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
@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
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
@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.
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
@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{emacs-startup-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
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