mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-19 10:22:27 +00:00
1458 lines
52 KiB
Plaintext
1458 lines
52 KiB
Plaintext
@c -*-texinfo-*-
|
|
@c This is part of the GNU Emacs Lisp Reference Manual.
|
|
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
|
|
@c See the file elisp.texi for copying conditions.
|
|
@setfilename ../info/display
|
|
@node Display, Calendar, System Interface, Top
|
|
@chapter Emacs Display
|
|
|
|
This chapter describes a number of features related to the display
|
|
that Emacs presents to the user.
|
|
|
|
@menu
|
|
* Refresh Screen:: Clearing the screen and redrawing everything on it.
|
|
* Screen Size:: How big is the Emacs screen.
|
|
* Truncation:: Folding or wrapping long text lines.
|
|
* The Echo Area:: Where messages are displayed.
|
|
* 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.
|
|
* Faces:: A face defines a graphics appearance: font, color, etc.
|
|
* Blinking:: How Emacs shows the matching open parenthesis.
|
|
* Inverse Video:: Specifying how the screen looks.
|
|
* Usual Display:: The usual conventions for displaying nonprinting chars.
|
|
* Display Tables:: How to specify other conventions.
|
|
* Beeping:: Audible signal to the user.
|
|
* Window Systems:: Which window system is being used.
|
|
@end menu
|
|
|
|
@node Refresh Screen
|
|
@section Refreshing the Screen
|
|
|
|
The function @code{redraw-frame} redisplays the entire contents of a
|
|
given frame. @xref{Frames}.
|
|
|
|
@c Emacs 19 feature
|
|
@defun redraw-frame frame
|
|
This function clears and redisplays frame @var{frame}.
|
|
@end defun
|
|
|
|
Even more powerful is @code{redraw-display}:
|
|
|
|
@deffn Command redraw-display
|
|
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.
|
|
|
|
@defvar no-redraw-on-reenter
|
|
@cindex suspend (cf. @code{no-redraw-on-reenter})
|
|
@cindex resume (cf. @code{no-redraw-on-reenter})
|
|
This variable controls whether Emacs redraws the entire screen after it
|
|
has been suspended and resumed. Non-@code{nil} means yes, @code{nil}
|
|
means no.
|
|
@end defvar
|
|
|
|
@node Screen Size
|
|
@section Screen Size
|
|
@cindex size of screen
|
|
@cindex screen size
|
|
@cindex display lines
|
|
@cindex display columns
|
|
@cindex resize redisplay
|
|
|
|
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}).
|
|
|
|
@defun screen-height
|
|
This function returns the number of lines on the screen that are
|
|
available for display.
|
|
|
|
@example
|
|
@group
|
|
(screen-height)
|
|
@result{} 50
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun screen-width
|
|
This function returns the number of columns on the screen that are
|
|
available for display.
|
|
|
|
@example
|
|
@group
|
|
(screen-width)
|
|
@result{} 80
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun set-screen-height lines &optional not-actual-size
|
|
This function declares that the terminal can display @var{lines} lines.
|
|
The sizes of existing windows are altered proportionally to fit.
|
|
|
|
If @var{not-actual-size} is non-@code{nil}, then Emacs displays
|
|
@var{lines} lines of output, but does not change its value for the
|
|
actual height of the screen. (Knowing the correct actual size may be
|
|
necessary for correct cursor positioning.) Using a smaller height than
|
|
the terminal actually implements may be useful to reproduce behavior
|
|
observed on a smaller screen, or if the terminal malfunctions when using
|
|
its whole screen.
|
|
|
|
If @var{lines} is different from what it was previously, then the
|
|
entire screen is cleared and redisplayed using the new size.
|
|
|
|
This function returns @code{nil}.
|
|
@end defun
|
|
|
|
@defun set-screen-width columns &optional not-actual-size
|
|
This function declares that the terminal can display @var{columns}
|
|
columns. The details are as in @code{set-screen-height}.
|
|
@end defun
|
|
|
|
@node Truncation
|
|
@section Truncation
|
|
@cindex line wrapping
|
|
@cindex continuation lines
|
|
@cindex @samp{$} in display
|
|
@cindex @samp{\} in display
|
|
|
|
When a line of text extends beyond the right edge of a window, the
|
|
line can either be continued on the next screen line, or truncated to
|
|
one screen line. The additional screen lines used to display a long
|
|
text line are called @dfn{continuation} lines. Normally, a @samp{$} in
|
|
the rightmost column of the window indicates truncation; a @samp{\} on
|
|
the rightmost column indicates a line that ``wraps'' or is continued
|
|
onto the next line. (The display table can specify alternative
|
|
indicators; see @ref{Display Tables}.)
|
|
|
|
Note that continuation is different from filling; continuation happens
|
|
on the screen only, not in the buffer contents, and it breaks a line
|
|
precisely at the right margin, not at a word boundary. @xref{Filling}.
|
|
|
|
@defopt truncate-lines
|
|
This buffer-local variable controls how Emacs displays lines that extend
|
|
beyond the right edge of the window. The default is @code{nil}, which
|
|
specifies continuation. If the value is non-@code{nil}, then these
|
|
lines are truncated.
|
|
|
|
If the variable @code{truncate-partial-width-windows} is non-@code{nil},
|
|
then truncation is always used for side-by-side windows (within one
|
|
frame) regardless of the value of @code{truncate-lines}.
|
|
@end defopt
|
|
|
|
@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 defopt
|
|
|
|
@defopt truncate-partial-width-windows
|
|
This variable controls display of lines that extend beyond the right
|
|
edge of the window, in side-by-side windows (@pxref{Splitting Windows}).
|
|
If it is non-@code{nil}, these lines are truncated; otherwise,
|
|
@code{truncate-lines} says what to do with them.
|
|
@end defopt
|
|
|
|
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
|
|
@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
|
|
@cite{GNU Emacs Manual} specifies the rules for resolving conflicts
|
|
between the echo area and the minibuffer for use of that screen space
|
|
(@pxref{Minibuffer,, The Minibuffer, emacs, The GNU Emacs Manual}).
|
|
Error messages appear in the echo area; see @ref{Errors}.
|
|
|
|
You can write output in the echo area by using the Lisp printing
|
|
functions with @code{t} as the stream (@pxref{Output Functions}), or as
|
|
follows:
|
|
|
|
@defun message string &rest arguments
|
|
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
|
|
constructed string.
|
|
|
|
In batch mode, @code{message} prints the message text on the standard
|
|
error stream, followed by a newline.
|
|
|
|
@c Emacs 19 feature
|
|
If @var{string} is @code{nil}, @code{message} clears the echo area. If
|
|
the minibuffer is active, this brings the minibuffer contents back onto
|
|
the screen immediately.
|
|
|
|
@example
|
|
@group
|
|
(message "Minibuffer depth is %d."
|
|
(minibuffer-depth))
|
|
@print{} Minibuffer depth is 0.
|
|
@result{} "Minibuffer depth is 0."
|
|
@end group
|
|
|
|
@group
|
|
---------- Echo Area ----------
|
|
Minibuffer depth is 0.
|
|
---------- Echo Area ----------
|
|
@end group
|
|
@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
|
|
appears at the end of the message. Otherwise, the cursor appears at
|
|
point---not in the echo area at all.
|
|
|
|
The value is normally @code{nil}; Lisp programs bind it to @code{t}
|
|
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
|
|
|
|
@vindex line-move-ignore-invisible
|
|
Ordinarily, commands that operate on text or move point do not care
|
|
whether the text is invisible. The user-level line motion commands
|
|
explicitly ignore invisible newlines if
|
|
@code{line-move-ignore-invisible} is non-@code{nil}, but only because
|
|
they are explicitly programmed to do so.
|
|
|
|
@node Selective Display
|
|
@section Selective Display
|
|
@cindex selective display
|
|
|
|
@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 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 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.
|
|
|
|
Selective display does not directly affect editing commands. For
|
|
example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly into
|
|
invisible text. However, the replacement of newline characters with
|
|
carriage return characters affects some editing commands. For example,
|
|
@code{next-line} skips invisible lines, since it searches only for
|
|
newlines. Modes that use selective display can also define commands
|
|
that take account of the newlines, or that make parts of the text
|
|
visible or invisible.
|
|
|
|
When you write a selectively displayed buffer into a file, all the
|
|
control-m's are output as newlines. This means that when you next read
|
|
in the file, it looks OK, with nothing invisible. The selective display
|
|
effect is seen only within Emacs.
|
|
|
|
@defvar selective-display
|
|
This buffer-local variable enables selective display. This means that
|
|
lines, or portions of lines, may be made invisible.
|
|
|
|
@itemize @bullet
|
|
@item
|
|
If the value of @code{selective-display} is @code{t}, then any portion
|
|
of a line that follows a control-m is not displayed.
|
|
|
|
@item
|
|
If the value of @code{selective-display} is a positive integer, then
|
|
lines that start with more than that many columns of indentation are not
|
|
displayed.
|
|
@end itemize
|
|
|
|
When some portion of a buffer is invisible, the vertical movement
|
|
commands operate as if that portion did not exist, allowing a single
|
|
@code{next-line} command to skip any number of invisible lines.
|
|
However, character movement commands (such as @code{forward-char}) do
|
|
not skip the invisible portion, and it is possible (if tricky) to insert
|
|
or delete text in an invisible portion.
|
|
|
|
In the examples below, we show the @emph{display appearance} of the
|
|
buffer @code{foo}, which changes with the value of
|
|
@code{selective-display}. The @emph{contents} of the buffer do not
|
|
change.
|
|
|
|
@example
|
|
@group
|
|
(setq selective-display nil)
|
|
@result{} nil
|
|
|
|
---------- Buffer: foo ----------
|
|
1 on this column
|
|
2on this column
|
|
3n this column
|
|
3n this column
|
|
2on this column
|
|
1 on this column
|
|
---------- Buffer: foo ----------
|
|
@end group
|
|
|
|
@group
|
|
(setq selective-display 2)
|
|
@result{} 2
|
|
|
|
---------- Buffer: foo ----------
|
|
1 on this column
|
|
2on this column
|
|
2on this column
|
|
1 on this column
|
|
---------- Buffer: foo ----------
|
|
@end group
|
|
@end example
|
|
@end defvar
|
|
|
|
@defvar selective-display-ellipses
|
|
If this buffer-local variable is non-@code{nil}, then Emacs displays
|
|
@samp{@dots{}} at the end of a line that is followed by invisible text.
|
|
This example is a continuation of the previous one.
|
|
|
|
@example
|
|
@group
|
|
(setq selective-display-ellipses t)
|
|
@result{} t
|
|
|
|
---------- Buffer: foo ----------
|
|
1 on this column
|
|
2on this column ...
|
|
2on this column
|
|
1 on this column
|
|
---------- Buffer: foo ----------
|
|
@end group
|
|
@end example
|
|
|
|
You can use a display table to substitute other text for the ellipsis
|
|
(@samp{@dots{}}). @xref{Display Tables}.
|
|
@end defvar
|
|
|
|
@node Overlay Arrow
|
|
@section The Overlay Arrow
|
|
@cindex overlay arrow
|
|
|
|
The @dfn{overlay arrow} is useful for directing the user's attention
|
|
to a particular line in a buffer. For example, in the modes used for
|
|
interface to debuggers, the overlay arrow indicates the line of code
|
|
about to be executed.
|
|
|
|
@defvar overlay-arrow-string
|
|
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 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 of some other buffer until an update is required. This should be fixed
|
|
@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
|
|
|
|
Temporary displays are used by commands to put output into a buffer
|
|
and then present it to the user for perusal rather than for editing.
|
|
Many of the help commands use this feature.
|
|
|
|
@defspec 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}. The buffer
|
|
is then shown in some window for viewing, displayed but not selected.
|
|
|
|
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
|
|
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}.
|
|
|
|
The value of the last form in @var{forms} is returned.
|
|
|
|
@example
|
|
@group
|
|
---------- Buffer: foo ----------
|
|
This is the contents of foo.
|
|
---------- Buffer: foo ----------
|
|
@end group
|
|
|
|
@group
|
|
(with-output-to-temp-buffer "foo"
|
|
(print 20)
|
|
(print standard-output))
|
|
@result{} #<buffer foo>
|
|
|
|
---------- Buffer: foo ----------
|
|
20
|
|
|
|
#<buffer foo>
|
|
|
|
---------- Buffer: foo ----------
|
|
@end group
|
|
@end example
|
|
@end defspec
|
|
|
|
@defvar temp-buffer-show-function
|
|
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.
|
|
|
|
In Emacs versions 18 and earlier, this variable was called
|
|
@code{temp-buffer-show-hook}.
|
|
@end defvar
|
|
|
|
@defun momentary-string-display string position &optional char message
|
|
This function momentarily displays @var{string} in the current buffer at
|
|
@var{position}. It has no effect on the undo list or on the buffer's
|
|
modification status.
|
|
|
|
The momentary display remains until the next input event. If the next
|
|
input event is @var{char}, @code{momentary-string-display} ignores it
|
|
and returns. Otherwise, that event remains buffered for subsequent use
|
|
as input. Thus, typing @var{char} will simply remove the string from
|
|
the display, while typing (say) @kbd{C-f} will remove the string from
|
|
the display and later (presumably) move point forward. The argument
|
|
@var{char} is a space by default.
|
|
|
|
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.
|
|
|
|
In this example, point is initially located at the beginning of the
|
|
second line:
|
|
|
|
@example
|
|
@group
|
|
---------- Buffer: foo ----------
|
|
This is the contents of foo.
|
|
@point{}Second line.
|
|
---------- Buffer: foo ----------
|
|
@end group
|
|
|
|
@group
|
|
(momentary-string-display
|
|
"**** Important Message! ****"
|
|
(point) ?\r
|
|
"Type RET when done reading")
|
|
@result{} t
|
|
@end group
|
|
|
|
@group
|
|
---------- Buffer: foo ----------
|
|
This is the contents of foo.
|
|
**** Important Message! ****Second line.
|
|
---------- Buffer: foo ----------
|
|
|
|
---------- Echo Area ----------
|
|
Type RET when done reading
|
|
---------- Echo Area ----------
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@node Overlays
|
|
@section Overlays
|
|
@cindex overlays
|
|
|
|
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
|
|
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.
|
|
What properties do to the screen display.
|
|
* Managing Overlays:: Creating, moving, finding overlays.
|
|
@end menu
|
|
|
|
@node Overlay Properties
|
|
@subsection Overlay Properties
|
|
|
|
Overlay properties are like text properties in some respects, but the
|
|
differences are more important than the similarities. Text properties
|
|
are considered a part of the text; overlays are specifically considered
|
|
not to be part of the text. Thus, copying text between various buffers
|
|
and strings preserves text properties, but does not try to preserve
|
|
overlays. Changing a buffer's text properties marks the buffer as
|
|
modified, while moving an overlay or changing its properties does not.
|
|
Unlike text propery changes, overlay changes are not recorded in the
|
|
buffer's undo list.
|
|
|
|
@table @code
|
|
@item priority
|
|
@kindex priority @r{(overlay property)}
|
|
This property's value (which should be a nonnegative number) determines
|
|
the priority of the overlay. The priority matters when two or more
|
|
overlays cover the same character and both specify a face for display;
|
|
the one whose @code{priority} value is larger takes priority over the
|
|
other, and its face attributes override the face attributes of the lower
|
|
priority overlay.
|
|
|
|
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.
|
|
|
|
@item window
|
|
@kindex window @r{(overlay property)}
|
|
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. 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)}
|
|
This property is used instead of @code{face} when the mouse is within
|
|
the range of the overlay. This feature may be temporary, like
|
|
@code{face}.
|
|
|
|
@item modification-hooks
|
|
@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.
|
|
|
|
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 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 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)}
|
|
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.
|
|
|
|
@ignore This isn't implemented yet
|
|
@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.
|
|
@end ignore
|
|
|
|
@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. 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. 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
|
|
overlay.
|
|
|
|
@defun overlay-get overlay prop
|
|
This function returns the value of property @var{prop} recorded in
|
|
@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
|
|
This function sets the value of property @var{prop} recorded in
|
|
@var{overlay} to @var{value}. It returns @var{value}.
|
|
@end defun
|
|
|
|
See also the function @code{get-char-property} which checks both
|
|
overlay properties and text properties for a given character.
|
|
@xref{Examining Properties}.
|
|
|
|
@node Managing Overlays
|
|
@subsection Managing Overlays
|
|
|
|
This section describes the functions to create, delete and move
|
|
overlays, and to examine their contents.
|
|
|
|
@defun make-overlay start end &optional buffer
|
|
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
|
|
current buffer.
|
|
@end defun
|
|
|
|
@defun overlay-start overlay
|
|
This function returns the position at which @var{overlay} starts.
|
|
@end defun
|
|
|
|
@defun overlay-end overlay
|
|
This function returns the position at which @var{overlay} ends.
|
|
@end defun
|
|
|
|
@defun overlay-buffer overlay
|
|
This function returns the buffer that @var{overlay} belongs to.
|
|
@end defun
|
|
|
|
@defun delete-overlay overlay
|
|
This function deletes @var{overlay}. The overlay continues to exist as
|
|
a Lisp object, but ceases to be part of the buffer it belonged to, and
|
|
ceases to have any effect on display.
|
|
@end defun
|
|
|
|
@defun move-overlay overlay start end &optional buffer
|
|
This function moves @var{overlay} to @var{buffer}, and places its bounds
|
|
at @var{start} and @var{end}. Both arguments @var{start} and @var{end}
|
|
must specify buffer positions; they may be integers or markers. If
|
|
@var{buffer} is omitted, the overlay stays in the same buffer.
|
|
|
|
The return value is @var{overlay}.
|
|
|
|
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''.
|
|
@end defun
|
|
|
|
@defun overlays-at pos
|
|
This function returns a list of all the overlays that contain 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}.
|
|
@end defun
|
|
|
|
@defun next-overlay-change pos
|
|
This function returns the buffer position of the next beginning or end
|
|
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
|
|
|
|
A @dfn{face} is a named collection of graphical attributes: font,
|
|
foreground color, background color and optional underlining. Faces
|
|
control the display of text on the screen.
|
|
|
|
@cindex face id
|
|
Each face has its own @dfn{face id number} which distinguishes faces at
|
|
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.
|
|
|
|
@menu
|
|
* Standard Faces:: The faces Emacs normally comes with.
|
|
* Merging Faces:: How Emacs decides which face to use for a character.
|
|
* Face Functions:: How to define and examine faces.
|
|
@end menu
|
|
|
|
@node Standard Faces
|
|
@subsection Standard Faces
|
|
|
|
This table lists all the standard faces and their uses.
|
|
|
|
@table @code
|
|
@item default
|
|
@kindex default @r{(face name)}
|
|
This face is used for ordinary text.
|
|
|
|
@item modeline
|
|
@kindex modeline @r{(face name)}
|
|
This face is used for mode lines and menu bars.
|
|
|
|
@item region
|
|
@kindex region @r{(face name)}
|
|
This face is used for highlighting the region in Transient Mark mode.
|
|
|
|
@item secondary-selection
|
|
@kindex secondary-selection @r{(face name)}
|
|
This face is used to show any secondary selection you have made.
|
|
|
|
@item highlight
|
|
@kindex highlight @r{(face name)}
|
|
This face is meant to be used for highlighting for various purposes.
|
|
|
|
@item underline
|
|
@kindex underline @r{(face name)}
|
|
This face underlines text.
|
|
|
|
@item bold
|
|
@kindex bold @r{(face name)}
|
|
This face uses a bold font, if possible. It uses the bold variant of
|
|
the frame's font, if it has one. It's up to you to choose a default
|
|
font that has a bold variant, if you want to use one.
|
|
|
|
@item italic
|
|
@kindex italic @r{(face name)}
|
|
This face uses the italic variant of the frame's font, if it has one.
|
|
|
|
@item bold-italic
|
|
@kindex bold-italic @r{(face name)}
|
|
This face uses the bold italic variant of the frame's font, if it has
|
|
one.
|
|
@end table
|
|
|
|
@node Merging Faces
|
|
@subsection Merging Faces for Display
|
|
|
|
Here are all the ways to specify which face to use for display of text:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
With defaults. Each frame has a @dfn{default face}, whose id number is
|
|
zero, which is used for all text that doesn't somehow specify another
|
|
face.
|
|
|
|
@item
|
|
With text properties. A character may have a @code{face} property; if so,
|
|
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
|
|
character.
|
|
|
|
@item
|
|
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}.
|
|
@end itemize
|
|
|
|
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.
|
|
|
|
When multiple overlays cover one character, an overlay with higher
|
|
priority overrides those with lower priority. @xref{Overlays}.
|
|
|
|
If an attribute such as the font or a color is not specified in any of
|
|
the above ways, the frame's own font or color is used.
|
|
|
|
@node Face Functions
|
|
@subsection Functions for Working with Faces
|
|
|
|
The attributes a face can specify include the font, the foreground
|
|
color, the background color, and underlining. The face can also leave
|
|
these unspecified by giving the value @code{nil} for them.
|
|
|
|
Here are the primitives for creating and changing faces.
|
|
|
|
@defun make-face name
|
|
This function defines a new face named @var{name}, initially with all
|
|
attributes @code{nil}. It does nothing if there is already a face named
|
|
@var{name}.
|
|
@end defun
|
|
|
|
@defun face-list
|
|
This function returns a list of all defined face names.
|
|
@end defun
|
|
|
|
@defun copy-face old-face new-name &optional frame new-frame
|
|
This function defines the face @var{new-name} as a copy of the existing
|
|
face named @var{old-face}. It creates the face @var{new-name} if that
|
|
doesn't already exist.
|
|
|
|
If the optional argument @var{frame} is given, this function applies
|
|
only to that frame. Otherwise it applies to each frame individually,
|
|
copying attributes from @var{old-face} in each frame to @var{new-face}
|
|
in the same frame.
|
|
|
|
If the optional argument @var{new-frame} is given, then @code{copy-face}
|
|
copies the attributes of @var{old-face} in @var{frame} to @var{new-name}
|
|
in @var{new-frame}.
|
|
@end defun
|
|
|
|
You can modify the attributes of an existing face with the following
|
|
functions. If you specify @var{frame}, they affect just that frame;
|
|
otherwise, they affect all frames as well as the defaults that apply to
|
|
new frames.
|
|
|
|
@defun set-face-foreground face color &optional frame
|
|
@defunx set-face-background face color &optional frame
|
|
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
|
|
This function sets the font of face @var{face}. The argument @var{font}
|
|
should be a string.
|
|
@end defun
|
|
|
|
@defun set-face-underline-p face underline-p &optional frame
|
|
This function sets the underline attribute of face @var{face}.
|
|
Non-@code{nil} means do underline; @code{nil} means don't.
|
|
@end defun
|
|
|
|
@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,
|
|
respectively.
|
|
@end defun
|
|
|
|
These functions examine the attributes of a face. If you don't
|
|
specify @var{frame}, they refer to the default data for new frames.
|
|
|
|
@defun face-foreground face &optional frame
|
|
@defunx face-background face &optional frame
|
|
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 name of the font of face @var{face}.
|
|
@end defun
|
|
|
|
@defun face-underline-p face &optional frame
|
|
This function returns the underline attribute of face @var{face}.
|
|
@end defun
|
|
|
|
@defun face-id face
|
|
This function returns the face id number of face @var{face}.
|
|
@end defun
|
|
|
|
@defun face-equal face1 face2 &optional frame
|
|
This returns @code{t} if the faces @var{face1} and @var{face2} have the
|
|
same attributes for display.
|
|
@end defun
|
|
|
|
@defun face-differs-from-default-p face &optional frame
|
|
This returns @code{t} if the face @var{face} displays differently from
|
|
the default face. A face is considered to be ``the same'' as the normal
|
|
face if each attribute is either the same as that of the default face or
|
|
@code{nil} (meaning to inherit from the default).
|
|
@end defun
|
|
|
|
@defvar region-face
|
|
This variable's value specifies the face id to use to display characters
|
|
in the region when it is active (in Transient Mark mode only). The face
|
|
thus specified takes precedence over all faces that come from text
|
|
properties and overlays, for characters in the region. @xref{The Mark},
|
|
for more information about Transient Mark mode.
|
|
|
|
Normally, the value is the id number of the face named @code{region}.
|
|
@end defvar
|
|
|
|
@node Blinking
|
|
@section Blinking Parentheses
|
|
@cindex parenthesis matching
|
|
@cindex blinking
|
|
@cindex balancing parentheses
|
|
@cindex close parenthesis
|
|
|
|
This section describes the mechanism by which Emacs shows a matching
|
|
open parenthesis when the user inserts a close parenthesis.
|
|
|
|
@vindex blink-paren-hook
|
|
@defvar blink-paren-function
|
|
The value of this variable should be a function (of no arguments) to
|
|
be called whenever a character with close parenthesis syntax is inserted.
|
|
The value of @code{blink-paren-function} may be @code{nil}, in which
|
|
case nothing is done.
|
|
|
|
@quotation
|
|
@strong{Please note:} This variable was named @code{blink-paren-hook} in
|
|
older Emacs versions, but since it is not called with the standard
|
|
convention for hooks, it was renamed to @code{blink-paren-function} in
|
|
version 19.
|
|
@end quotation
|
|
@end defvar
|
|
|
|
@defvar blink-matching-paren
|
|
If this variable is @code{nil}, then @code{blink-matching-open} does
|
|
nothing.
|
|
@end defvar
|
|
|
|
@defvar blink-matching-paren-distance
|
|
This variable specifies the maximum distance to scan for a matching
|
|
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
|
|
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.
|
|
|
|
Here is an example of calling this function explicitly.
|
|
|
|
@smallexample
|
|
@group
|
|
(defun interactive-blink-matching-open ()
|
|
@c Do not break this line! -- rms.
|
|
@c The first line of a doc string
|
|
@c must stand alone.
|
|
"Indicate momentarily the start of sexp before point."
|
|
(interactive)
|
|
@end group
|
|
@group
|
|
(let ((blink-matching-paren-distance
|
|
(buffer-size))
|
|
(blink-matching-paren t))
|
|
(blink-matching-open)))
|
|
@end group
|
|
@end smallexample
|
|
@end defun
|
|
|
|
@node Inverse Video
|
|
@section Inverse Video
|
|
@cindex Inverse Video
|
|
|
|
@defopt inverse-video
|
|
@cindex highlighting
|
|
This variable controls whether Emacs uses inverse video for all text
|
|
on the screen. Non-@code{nil} means yes, @code{nil} means no. The
|
|
default is @code{nil}.
|
|
@end defopt
|
|
|
|
@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.
|
|
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
|
|
@section Usual Display Conventions
|
|
|
|
The usual display conventions define how to display each character
|
|
code. You can override these conventions by setting up a display table
|
|
(@pxref{Display Tables}). Here are the usual display conventions:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Character codes 32 through 126 map to glyph codes 32 through 126.
|
|
Normally this means they display as themselves.
|
|
|
|
@item
|
|
Character code 9 is a horizontal tab. It displays as whitespace
|
|
up to a position determined by @code{tab-width}.
|
|
|
|
@item
|
|
Character code 10 is a newline.
|
|
|
|
@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
|
|
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
|
|
just like the codes in the range 128 to 255.
|
|
|
|
@item
|
|
Character codes 128 through 255 map to sequences of four glyphs, where
|
|
the first glyph is the @sc{ASCII} code for @samp{\}, and the others are
|
|
digit characters representing the code in octal. (A display table can
|
|
specify a glyph to use instead of @samp{\}.)
|
|
@end itemize
|
|
|
|
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 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,
|
|
they also affect the indentation functions.
|
|
|
|
@defopt ctl-arrow
|
|
@cindex control characters in display
|
|
This buffer-local variable controls how control characters are
|
|
displayed. If it is non-@code{nil}, they are displayed as a caret
|
|
followed by the character: @samp{^A}. If it is @code{nil}, they are
|
|
displayed as a backslash followed by three octal digits: @samp{\001}.
|
|
@end defopt
|
|
|
|
@c Following may have overfull hbox.
|
|
@defvar default-ctl-arrow
|
|
The value of this variable is the default value for @code{ctl-arrow} in
|
|
buffers that do not override it. @xref{Default Value}.
|
|
@end defvar
|
|
|
|
@defopt tab-width
|
|
The value of this variable is the spacing between tab stops used for
|
|
displaying tab characters in Emacs buffers. The default is 8. Note
|
|
that this feature is completely independent from the user-settable tab
|
|
stops used by the command @code{tab-to-tab-stop}. @xref{Indent Tabs}.
|
|
@end defopt
|
|
|
|
@node Display Tables
|
|
@section Display Tables
|
|
|
|
@cindex display table
|
|
You can use the @dfn{display table} feature to control how all 256
|
|
possible character codes display on the screen. This is useful for
|
|
displaying European languages that have letters not in the @sc{ASCII}
|
|
character set.
|
|
|
|
The display table maps each character code into a sequence of
|
|
@dfn{glyphs}, each glyph being an image that takes up one character
|
|
position on the screen. You can also define how to display each glyph
|
|
on your terminal, using the @dfn{glyph table}.
|
|
|
|
@menu
|
|
* Display Table Format:: What a display table consists of.
|
|
* Active Display Table:: How Emacs selects a display table to use.
|
|
* Glyphs:: How to define a glyph, and what glyphs mean.
|
|
* ISO Latin 1:: How to use display tables
|
|
to support the ISO Latin 1 character set.
|
|
@end menu
|
|
|
|
@node Display Table Format
|
|
@subsection Display Table Format
|
|
|
|
A display table is actually an array of 262 elements.
|
|
|
|
@defun make-display-table
|
|
This creates and returns a display table. The table initially has
|
|
@code{nil} in all elements.
|
|
@end defun
|
|
|
|
The first 256 elements correspond to character codes; the @var{n}th
|
|
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}).
|
|
|
|
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.
|
|
|
|
@table @asis
|
|
@item 256
|
|
The glyph for the end of a truncated screen line (the default for this
|
|
is @samp{$}). @xref{Glyphs}.
|
|
@item 257
|
|
The glyph for the end of a continued line (the default is @samp{\}).
|
|
@item 258
|
|
The glyph for indicating a character displayed as an octal character
|
|
code (the default is @samp{\}).
|
|
@item 259
|
|
The glyph for indicating a control character (the default is @samp{^}).
|
|
@item 260
|
|
A vector of glyphs for indicating the presence of invisible lines (the
|
|
default is @samp{...}). @xref{Selective Display}.
|
|
@item 261
|
|
The glyph used to draw the border between side-by-side windows (the
|
|
default is @samp{|}). @xref{Splitting Windows}.
|
|
@end table
|
|
|
|
For example, here is how to construct a display table that mimics the
|
|
effect of setting @code{ctl-arrow} to a non-@code{nil} value:
|
|
|
|
@example
|
|
(setq disptab (make-display-table))
|
|
(let ((i 0))
|
|
(while (< i 32)
|
|
(or (= i ?\t) (= i ?\n)
|
|
(aset disptab i (vector ?^ (+ i 64))))
|
|
(setq i (1+ i)))
|
|
(aset disptab 127 (vector ?^ ??)))
|
|
@end example
|
|
|
|
@node Active Display Table
|
|
@subsection Active Display Table
|
|
@cindex active display table
|
|
|
|
Each window can specify a display table, and so can each buffer. When
|
|
a buffer @var{b} is displayed in window @var{w}, display uses the
|
|
display table for window @var{w} if it has one; otherwise, the display
|
|
table for buffer @var{b} if it has one; otherwise, the standard display
|
|
table if any. The display table chosen is called the @dfn{active}
|
|
display table.
|
|
|
|
@defun window-display-table window
|
|
This function returns @var{window}'s display table, or @code{nil}
|
|
if @var{window} does not have an assigned display table.
|
|
@end defun
|
|
|
|
@defun set-window-display-table window table
|
|
This function sets the display table of @var{window} to @var{table}.
|
|
The argument @var{table} should be either a display table or
|
|
@code{nil}.
|
|
@end defun
|
|
|
|
@defvar buffer-display-table
|
|
This variable is automatically local in all buffers; its value in a
|
|
particular buffer is the display table for that buffer, or @code{nil} if
|
|
the buffer does not have an assigned display table.
|
|
@end defvar
|
|
|
|
@defvar standard-display-table
|
|
This variable's value is the default display table, used whenever a
|
|
window has no display table and neither does the buffer displayed in
|
|
that window. This variable is @code{nil} by default.
|
|
@end defvar
|
|
|
|
If there is no display table to use for a particular window---that is,
|
|
if the window has none, its buffer has none, and
|
|
@code{standard-display-table} has none---then Emacs uses the usual
|
|
display conventions for all character codes in that window. @xref{Usual
|
|
Display}.
|
|
|
|
@node Glyphs
|
|
@subsection Glyphs
|
|
|
|
@cindex glyph
|
|
A @dfn{glyph} is a generalization of a character; it stands for an
|
|
image that takes up a single character position on the screen. Glyphs
|
|
are represented in Lisp as integers, just as characters are.
|
|
|
|
@cindex glyph table
|
|
The meaning of each integer, as a glyph, is defined by the glyph
|
|
table, which is the value of the variable @code{glyph-table}.
|
|
|
|
@defvar glyph-table
|
|
The value of this variable is the current glyph table. It should be a
|
|
vector; the @var{g}th element defines glyph code @var{g}. If the value
|
|
is @code{nil} instead of a vector, then all glyphs are simple (see
|
|
below).
|
|
@end defvar
|
|
|
|
Here are the possible types of elements in the glyph table:
|
|
|
|
@table @var
|
|
@item string
|
|
Send the characters in @var{string} to the terminal to output
|
|
this glyph. This alternative is available on character terminals,
|
|
but not under X.
|
|
|
|
@item integer
|
|
Define this glyph code as an alias for code @var{integer}. You can use
|
|
an alias to specify a face code for the glyph; see below.
|
|
|
|
@item @code{nil}
|
|
This glyph is simple. On an ordinary terminal, the glyph code mod 256
|
|
is the character to output. With X, the glyph code mod 256 is the
|
|
character to output, and the glyph code divided by 256 specifies the
|
|
@dfn{face id number} to use while outputting it. @xref{Faces}.
|
|
@end table
|
|
|
|
If a glyph code is greater than or equal to the length of the glyph
|
|
table, that code is automatically simple.
|
|
|
|
@node ISO Latin 1
|
|
@subsection ISO Latin 1
|
|
|
|
If you have a terminal that can handle the entire ISO Latin 1 character
|
|
set, you can arrange to use that character set as follows:
|
|
|
|
@example
|
|
(require 'disp-table)
|
|
;; @r{Set char codes 160--255 to display as themselves.}
|
|
;; @r{(Codes 128--159 are the additional control characters.)}
|
|
(standard-display-8bit 160 255)
|
|
@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 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
|
|
can define a display table to work one language using such terminals.
|
|
For an example, see @file{lisp/iso-swed.el}, which handles certain
|
|
Swedish terminals.
|
|
|
|
You can load the appropriate display table for your terminal
|
|
automatically by writing a terminal-specific Lisp file for the terminal
|
|
type.
|
|
|
|
@node Beeping
|
|
@section Beeping
|
|
@cindex beeping
|
|
@cindex bell
|
|
|
|
You can make Emacs ring a bell (or blink the screen) to attract the
|
|
user's attention. Be conservative about how often you do this; frequent
|
|
bells can become irritating. Also be careful not to use beeping alone
|
|
when signaling an error is appropriate. (@xref{Errors}.)
|
|
|
|
@defun ding &optional dont-terminate
|
|
@cindex keyboard macro termination
|
|
This function beeps, or flashes the screen (see @code{visible-bell} below).
|
|
It also terminates any keyboard macro currently executing unless
|
|
@var{dont-terminate} is non-@code{nil}.
|
|
@end defun
|
|
|
|
@defun beep &optional dont-terminate
|
|
This is a synonym for @code{ding}.
|
|
@end defun
|
|
|
|
@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 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
|
|
@section Window Systems
|
|
|
|
Emacs works with several window systems, most notably the X Window
|
|
System. Both Emacs and X use the term ``window'', but use it
|
|
differently. An Emacs frame is a single window as far as X is
|
|
concerned; the individual Emacs windows are not known to X at all.
|
|
|
|
@defvar window-system
|
|
@cindex X Window System
|
|
This variable tells Lisp programs what window system Emacs is running
|
|
under. Its value should be a symbol such as @code{x} (if Emacs is
|
|
running under X) or @code{nil} (if Emacs is running on an ordinary
|
|
terminal).
|
|
@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
|
|
loading terminal-specific Lisp code, and after 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
|