* Screen Size:: How big is the Emacs screen.
* Truncation:: Folding or wrapping long text lines.
* The Echo Area:: Where messages are displayed.
-* Selective Display:: Hiding part of the buffer text.
+* Invisible Text:: Hiding part of the buffer text.
+* Selective Display:: Hiding part of the buffer text (the old way).
* Overlay Arrow:: Display of an arrow to indicate position.
* Temporary Displays:: Displays that go away automatically.
* Overlays:: Use overlays to highlight parts of the buffer.
This function clears and redisplays all visible frames.
@end deffn
+ Processing user input takes absolute priority over redisplay. If you
+call these functions when input is available, they do nothing
+immediately, but a full redisplay does happen eventually---after all the
+input has been processed.
+
Normally, suspending and resuming Emacs also refreshes the screen.
Some terminal emulators record separate contents for display-oriented
programs such as Emacs and for ordinary sequential display. If you are
using such a terminal, you might want to inhibit the redisplay on
-resumption. @xref{Suspending Emacs}.
+resumption.
@defvar no-redraw-on-reenter
@cindex suspend (cf. @code{no-redraw-on-reenter})
means no.
@end defvar
- Processing user input takes absolute priority over redisplay. If you
-call these functions when input is available, they do nothing
-immediately, but a full redisplay does happen eventually---after all the
-input has been processed.
-
@node Screen Size
@section Screen Size
@cindex size of screen
@cindex display columns
@cindex resize redisplay
- The screen size functions report or tell Emacs the height or width of
+ The screen size functions access or specify the height or width of
the terminal. When you are using multiple frames, they apply to the
selected frame (@pxref{Frames}).
frame) regardless of the value of @code{truncate-lines}.
@end defopt
-@defvar default-truncate-lines
+@defopt default-truncate-lines
This variable is the default value for @code{truncate-lines}, for
buffers that do not have local values for it.
-@end defvar
+@end defopt
@defopt truncate-partial-width-windows
This variable controls display of lines that extend beyond the right
You can override the images that indicate continuation or truncation
with the display table; see @ref{Display Tables}.
+ If your buffer contains @strong{very} long lines, and you use
+continuation to display them, just thinking about them can make Emacs
+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}.
+
+@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.
+
+Turning on the cache slows down processing of short lines somewhat.
+
+This variable is automatically local in every buffer.
+@end defvar
+
@node The Echo Area
@section The Echo Area
@cindex error display
@cindex echo area
- The @dfn{echo area} is used for displaying messages made with the
+The @dfn{echo area} is used for displaying messages made with the
@code{message} primitive, and for echoing keystrokes. It is not the
same as the minibuffer, despite the fact that the minibuffer appears
(when active) in the same place on the screen as the echo area. The
follows:
@defun message string &rest arguments
-This function prints a one-line message in the echo area. The
+This function displays a one-line message in the echo area. The
argument @var{string} is similar to a C language @code{printf} control
string. See @code{format} in @ref{String Conversion}, for the details
on the conversion specifications. @code{message} returns the
@end example
@end defun
+Almost all the messages displayed in the echo area are also recorded
+in the @samp{*Messages*} buffer.
+
+@defopt message-log-max
+This variable specifies how many lines to keep in the @samp{*Messages*}
+buffer. The value @code{t} means there is no limit on how many lines to
+keep. The value @code{nil} disables message logging entirely. Here's
+how to display a message and prevent it from being logged:
+
+@example
+(let (message-log-max)
+ (message @dots{}))
+@end example
+@end defopt
+
+@defvar echo-keystrokes
+This variable determines how much time should elapse before command
+characters echo. Its value must be an integer, which specifies the
+number of seconds to wait before echoing. If the user types a prefix
+key (such as @kbd{C-x}) and then delays this many seconds before
+continuing, the prefix key is echoed in the echo area. Any subsequent
+characters in the same command will be echoed as well.
+
+If the value is zero, then command input is not echoed.
+@end defvar
+
@defvar cursor-in-echo-area
This variable controls where the cursor appears when a message is
displayed in the echo area. If it is non-@code{nil}, then the cursor
for brief periods of time.
@end defvar
+@node Invisible Text
+@section Invisible Text
+
+@cindex invisible text
+You can make characters @dfn{invisible}, so that they do not appear on
+the screen, with the @code{invisible} property. This can be either a
+text property or a property of an overlay.
+
+In the simplest case, any non-@code{nil} @code{invisible} property makes
+a character invisible. This is the default case---if you don't alter
+the default value of @code{buffer-invisibility-spec}, this is how the
+@code{invisibility} property works. This feature is much like selective
+display (@pxref{Selective Display}), but more general and cleaner.
+
+More generally, you can use the variable @code{buffer-invisibility-spec}
+to control which values of the @code{invisible} property make text
+invisible. This permits you to classify the text into different subsets
+in advance, by giving them different @code{invisible} values, and
+subsequently make various subsets visible or invisible by changing the
+value of @code{buffer-invisibility-spec}.
+
+Controlling visibility with @code{buffer-invisibility-spec} is
+especially useful in a program to display the list of entries in a data
+base. It permits the implementation of convenient filtering commands to
+view just a part of the entries in the data base. Setting this variable
+is very fast, much faster than scanning all the text in the buffer
+looking for properties to change.
+
+@defvar buffer-invisibility-spec
+This variable specifies which kinds of @code{invisible} properties
+actually make a character invisible.
+
+@table @asis
+@item @code{t}
+A character is invisible if its @code{invisible} property is
+non-@code{nil}. This is the default.
+
+@item a list
+Each element of the list makes certain characters invisible.
+Ultimately, a character is invisible if any of the elements of this list
+applies to it. The list can have two kinds of elements:
+
+@table @code
+@item @var{atom}
+A character is invisible if its @code{invisible} propery value
+is @var{atom} or if it is a list with @var{atom} as a member.
+
+@item (@var{atom} . t)
+A character is invisible if its @code{invisible} propery value
+is @var{atom} or if it is a list with @var{atom} as a member.
+Moreover, if this character is at the end of a line and is followed
+by a visible newline, it displays an ellipsis.
+@end table
+@end table
+@end defvar
+
+ Ordinarily, commands that operate on text or move point do not care
+whether the text is invisible. However, the user-level line motion
+commands explicitly ignore invisible newlines.
+
@node Selective Display
@section Selective Display
@cindex selective display
- @dfn{Selective display} is a class of minor modes in which specially
-marked lines do not appear on the screen, or in which highly indented
-lines do not appear.
+ @dfn{Selective display} is a pair of features that hide certain
+lines on the screen.
The first variant, explicit selective display, is designed for use in
a Lisp program. The program controls which lines are hidden by altering
-the text. Outline mode uses this variant. In the second variant, the
-choice of lines to hide is made automatically based on indentation.
-This variant is designed as a user-level feature.
+the text. Outline mode has traditionally used this variant. It has
+been partially replaced by the invisible text feature (@pxref{Invisible
+Text}); there is a new version of Outline mode which uses that instead.
+
+ In the second variant, the choice of lines to hide is made
+automatically based on indentation. This variant is designed to be a
+user-level feature.
The way you control explicit selective display is by replacing a
-newline (control-j) with a carriage return (control-m). The text which
+newline (control-j) with a carriage return (control-m). The text that
was formerly a line following that newline is now invisible. Strictly
speaking, it is temporarily no longer a line at all, since only newlines
can separate lines; it is now part of the previous line.
about to be executed.
@defvar overlay-arrow-string
-This variable holds the string to display as an arrow, or @code{nil} if
-the arrow feature is not in use.
+This variable holds the string to display to call attention to a
+particular line, or @code{nil} if the arrow feature is not in use.
@end defvar
@defvar overlay-arrow-position
-This variable holds a marker which indicates where to display the arrow.
-It should point at the beginning of a line. The arrow text appears at
-the beginning of that line, overlaying any text that would otherwise
-appear. Since the arrow is usually short, and the line usually begins
-with indentation, normally nothing significant is overwritten.
-
-The overlay string is displayed only in the buffer which this marker
+This variable holds a marker that indicates where to display the overlay
+arrow. It should point at the beginning of a line. The arrow text
+appears at the beginning of that line, overlaying any text that would
+otherwise appear. Since the arrow is usually short, and the line
+usually begins with indentation, normally nothing significant is
+overwritten.
+
+The overlay string is displayed only in the buffer that this marker
points into. Thus, only one buffer can have an overlay arrow at any
given time.
@c !!! overlay-arrow-position: but the overlay string may remain in the display
@c now. Is it?
@end defvar
+ You can do the same job by creating an overlay with a
+@code{before-string} property. @xref{Overlay Properties}.
+
@node Temporary Displays
@section Temporary Displays
@end defspec
@defvar temp-buffer-show-function
-If this variable, if non-@code{nil}, @code{with-output-to-temp-buffer}
+If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
calls it as a function to do the job of displaying a help buffer. The
function gets one argument, which is the buffer it should display.
The return value of @code{momentary-string-display} is not meaningful.
+If the string @var{string} does not contain control characters, you can
+do the same job in a more general way by creating an overlay with a
+@code{before-string} property. @xref{Overlay Properties}.
+
If @var{message} is non-@code{nil}, it is displayed in the echo area
while @var{string} is displayed in the buffer. If it is @code{nil}, a
default message says to type @var{char} to continue.
@cindex overlays
You can use @dfn{overlays} to alter the appearance of a buffer's text on
-the screen. An overlay is an object which belongs to a particular
-buffer, and has a specified beginning and end. It also has properties
-that you can examine and set; these affect the display of the text
-within the overlay.
+the screen, for the sake of presentation features. An overlay is an
+object that belongs to a particular buffer, and has a specified
+beginning and end. It also has properties that you can examine and set;
+these affect the display of the text within the overlay.
@menu
* Overlay Properties:: How to read and set properties.
If the @code{window} property is non-@code{nil}, then the overlay
applies only on that window.
+@item category
+@kindex category @r{(overlay property)}
+If an overlay has a @code{category} property, we call it the
+@dfn{category} of the overlay. It should be a symbol. The properties
+of the symbol serve as defaults for the properties of the overlay.
+
@item face
@kindex face @r{(overlay property)}
-This property controls the font and color of text. @xref{Faces}, for
-more information. This feature is temporary; in the future, we may
-replace it with other ways of specifying how to display text.
+This property controls the font and color of text. Its value is a face
+name or a list of face names. @xref{Faces}, for more information. This
+feature may be temporary; in the future, we may replace it with other
+ways of specifying how to display text.
@item mouse-face
@kindex mouse-face @r{(overlay property)}
@kindex modification-hooks @r{(overlay property)}
This property's value is a list of functions to be called if any
character within the overlay is changed or if text is inserted strictly
-within the overlay. Each function receives three arguments: the
-overlay, and the beginning and end of the part of the buffer being
+within the overlay.
+
+The hook functions are called both before and after each change.
+If the functions save the information they receive, and compare notes
+between calls, they can determine exactly what change has been made
+in the buffer text.
+
+When called before a change, each function receives four arguments: the
+overlay, @code{nil}, and the beginning and end of the text range to be
modified.
+When called after a change, each function receives five arguments: the
+overlay, @code{t}, the beginning and end of the text range just
+modified, and the length of the pre-change text replaced by that range.
+(For an insertion, the pre-change length is zero; for a deletion, that
+length is the number of characters deleted, and the post-change
+beginning and end are equal.)
+
@item insert-in-front-hooks
@kindex insert-in-front-hooks @r{(overlay property)}
-This property's value is a list of functions to be called
-if text is inserted right at the beginning of the overlay.
+This property's value is a list of functions to be called before and
+after inserting text right at the beginning of the overlay. The calling
+conventions are the same as for the @code{modification-hooks} functions.
@item insert-behind-hooks
@kindex insert-behind-hooks @r{(overlay property)}
-This property's value is a list of functions to be called if text is
-inserted right at the end of the overlay.
+This property's value is a list of functions to be called before and
+after inserting text right at the end of the overlay. The calling
+conventions are the same as for the @code{modification-hooks} functions.
@item invisible
@kindex invisible @r{(overlay property)}
-A non-@code{nil} @code{invisible} property means that the text in the
-overlay does not appear on the screen. This works much like selective
-display. Details of this feature are likely to change in future
-versions, so check the @file{etc/NEWS} file in the version you are
-using.
+The @code{invisible} property can make the text in the overlay
+invisible, which means that it does not appear on the screen.
+@xref{Invisible Text}, for details.
+
+@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.
@item before-string
@kindex before-string @r{(overlay property)}
This property's value is a string to add to the display at the beginning
of the overlay. The string does not appear in the buffer in any
-sense---only on the screen. This is not yet implemented, but will be.
+sense---only on the screen. The string should contain only characters
+that display as a single column---control characters, including tabs or
+newlines, will give strange results.
@item after-string
@kindex after-string @r{(overlay property)}
This property's value is a string to add to the display at the end of
the overlay. The string does not appear in the buffer in any
-sense---only on the screen. This is not yet implemented, but will be.
+sense---only on the screen. The string should contain only characters
+that display as a single column---control characters, including tabs or
+newlines, will give strange results.
+
+@item evaporate
+@kindex evaporate @r{(overlay property)}
+If this property is non-@code{nil}, the overlay is deleted automatically
+if it ever becomes empty (i.e., if it spans no characters).
@end table
These are the functions for reading and writing the properties of an
@defun overlay-get overlay prop
This function returns the value of property @var{prop} recorded in
-@var{overlay}. If @var{overlay} does not record any value for that
-property, then the value is @code{nil}.
+@var{overlay}, if any. If @var{overlay} does not record any value for
+that property, but it does have a @code{category} property which is a
+symbol, that symbol's @var{prop} property is used. Otherwise, the value
+is @code{nil}.
@end defun
@defun overlay-put overlay prop value
overlays, and to examine their contents.
@defun make-overlay start end &optional buffer
-This function creates and returns an overlay which belongs to
+This function creates and returns an overlay that belongs to
@var{buffer} and ranges from @var{start} to @var{end}. Both @var{start}
and @var{end} must specify buffer positions; they may be integers or
markers. If @var{buffer} is omitted, the overlay is created in the
of an overlay, after @var{pos}.
@end defun
+@defun previous-overlay-change pos
+This function returns the buffer position of the previous beginning or
+end of an overlay, before @var{pos}.
+@end defun
+
@node Faces
@section Faces
@cindex face
low levels within Emacs. However, for most purposes, you can refer to
faces in Lisp programs by their names.
+@defun facep object
+This function returns @code{t} if @var{object} is a face name symbol (or
+if it is a vector of the kind used internally to record face data). It
+returns @code{nil} otherwise.
+@end defun
+
Each face name is meaningful for all frames, and by default it has the
same meaning in all frames. But you can arrange to give a particular
face name a special meaning in one frame if you wish.
@item
With text properties. A character may have a @code{face} property; if so,
-it's displayed with that face. @xref{Special Properties}.
+it is displayed with that face. @xref{Special Properties}.
If the character has a @code{mouse-face} property, that is used instead
of the @code{face} property when the mouse is ``near enough'' to the
With overlays. An overlay may have @code{face} and @code{mouse-face}
properties too; they apply to all the text covered by the overlay.
+@item
+With a region that is active. In Transient Mark mode, the region is
+highlighted with a particular face (see @code{region-face}, below).
+
@item
With special glyphs. Each glyph can specify a particular face id
number. @xref{Glyphs}.
If these various sources together specify more than one face for a
particular character, Emacs merges the attributes of the various faces
specified. The attributes of the faces of special glyphs come first;
+then comes the face for region highlighting, if appropriate;
then come attributes of faces from overlays, followed by those from text
properties, and last the default face.
@defun set-face-foreground face color &optional frame
@defunx set-face-background face color &optional frame
-These functions set the foreground (respectively, background) color of
-face @var{face} to @var{color}. The argument @var{color} should be a
+These functions set the foreground (or background, respectively) color
+of face @var{face} to @var{color}. The argument @var{color} should be a
string, the name of a color.
+
+Certain shades of gray are implemented by stipple patterns on
+black-and-white screens.
+@end defun
+
+@defun set-face-stipple face pattern &optional frame
+This function sets the background stipple pattern of face @var{face} to
+@var{pattern}. The argument @var{pattern} should be the name of a
+stipple pattern defined by the X server, or @code{nil} meaning don't use
+stipple.
+
+Normally there is no need to pay attention to stipple patterns, because
+they are used automatically to handle certain shades of gray.
@end defun
@defun set-face-font face font &optional frame
@defun invert-face face &optional frame
Swap the foreground and background colors of face @var{face}. If the
face doesn't specify both foreground and background, then its foreground
-and background are set to the default background and foreground.
+and background are set to the default background and foreground,
+respectively.
@end defun
These functions examine the attributes of a face. If you don't
@defun face-foreground face &optional frame
@defunx face-background face &optional frame
-These functions return the foreground (respectively, background) color
-of face @var{face}, as a string.
+These functions return the foreground color (or background color,
+respectively) of face @var{face}, as a string.
+@end defun
+
+@defun face-stipple face &optional frame
+This function returns the name of the background stipple pattern of face
+@var{face}, or @code{nil} if it doesn't have one.
@end defun
@defun face-font face &optional frame
This function returns the underline attribute of face @var{face}.
@end defun
-@defun face-id-number face
+@defun face-id face
This function returns the face id number of face @var{face}.
@end defun
parenthesis before giving up.
@end defvar
+@defvar blink-matching-paren-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.
+@end defvar
+
@defun 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
@defopt mode-line-inverse-video
This variable controls the use of inverse video for mode lines. If it
-is non-@code{nil}, then mode lines are displayed in inverse video (under
-X, this uses the face named @code{modeline}, which you can set as you
-wish). Otherwise, mode lines are displayed normally, just like text.
-The default is @code{t}.
+is non-@code{nil}, then mode lines are displayed in inverse video.
+Otherwise, mode lines are displayed normally, just like text. The
+default is @code{t}.
+
+For X window frames, this displays mode lines using the face named
+@code{modeline}, which is normally the inverse of the default face
+unless you change it.
@end defopt
@node Usual Display
@item
All other codes in the range 0 through 31, and code 127, display in one
-of two ways according to the value of @code{ctl-arrow}. If it is is
+of two ways according to the value of @code{ctl-arrow}. If it is
non-@code{nil}, these codes map to sequences of two glyphs, where the
first glyph is the @sc{ASCII} code for @samp{^}. (A display table can
specify a glyph to use instead of @samp{^}.) Otherwise, these codes map
The usual display conventions apply even when there is a display
table, for any character whose entry in the active display table is
@code{nil}. Thus, when you set up a display table, you need only
-specify the the characters for which you want unusual behavior.
+specify the characters for which you want unusual behavior.
These variables affect the way certain characters are displayed on the
screen. Since they change the number of columns the characters occupy,
element says how to display the character code @var{n}. The value
should be @code{nil} or a vector of glyph values (@pxref{Glyphs}). If
an element is @code{nil}, it says to display that character according to
-the usual display conventions (@pxref{Usual Display}). Note that the
-display table has no effect on the tab and newline characters; they are
-always displayed as whitespace in their usual special fashion.
+the usual display conventions (@pxref{Usual Display}).
+
+ If you use the display table to change the display of newline
+characters, the whole buffer will be displayed as one long ``line.''
The remaining six elements of a display table serve special purposes,
and @code{nil} means use the default stated below.
@end example
If you are editing buffers written in the ISO Latin 1 character set and
-your terminal doesn't handle anything but @sc{ASCII}, you can load the file
-@file{iso-ascii} to set up a display table which makes the other ISO
-characters display as sequences of @sc{ASCII} characters. For example, the
-character ``o with umlaut'' displays as @samp{@{"o@}}.
+your terminal doesn't handle anything but @sc{ASCII}, you can load the
+file @file{iso-ascii} to set up a display table that displays the other
+ISO characters as explanatory sequences of @sc{ASCII} characters. For
+example, the character ``o with umlaut'' displays as @samp{@{"o@}}.
Some European countries have terminals that don't support ISO Latin 1
but do support the special characters for that country's language. You
@defvar visible-bell
This variable determines whether Emacs should flash the screen to
represent a bell. Non-@code{nil} means yes, @code{nil} means no. This
-is effective only if the Termcap entry for the terminal in use has the
-visible bell flag (@samp{vb}) set.
+is effective under X windows, and on a character-only terminal provided
+the terminal's Termcap entry defines the visible bell capability
+(@samp{vb}).
@end defvar
@node Window Systems
terminal).
@end defvar
-@defvar window-system-version
-This variable distinguishes between different versions of the X Window
-System. Its value is 10 or 11 when using X; @code{nil} otherwise.
-@end defvar
-
@defvar window-setup-hook
This variable is a normal hook which Emacs runs after loading your
@file{.emacs} file and the default initialization file (if any), after
HCoop / bpt / emacs.git / blobdiff