comparison lispref/display.texi @ 9009:7cdfcd5e71ff

entered into RCS

9008:be396da9c611

  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}.

@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

@cindex screen size
@cindex display lines
@cindex display columns
@cindex resize redisplay

  The screen size functions report or tell Emacs 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

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 way you control explicit selective display is by replacing a
newline (control-j) with a carriage return (control-m).  The text which
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

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 as an arrow, 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
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 group
@end example
@end defspec

@defvar temp-buffer-show-function
If this variable, if 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}.

@node Overlays
@section Overlays
@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.

@menu

  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 which 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

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's 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.

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 (respectively, background) color of
face @var{face} to @var{color}.  The argument @var{color} should be a
string, the name of a color.
@end defun

@defun set-face-font face font &optional frame
This function sets the font of face @var{face}.  The argument @var{font}

@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.
@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 (respectively, background) color
of face @var{face}, as a string.
@end defun

@defun face-font face &optional frame
This function returns the name of the font of face @var{face}.
@end defun

@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 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.

;; @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 which makes the other ISO
characters display as 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

9009:7cdfcd5e71ff

  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

@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

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 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

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 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}.

@node Overlays
@section Overlays
@cindex overlays

You can use @dfn{overlays} to alter the appearance of a buffer's text on
the screen.  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

  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

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.

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.
@end defun

@defun set-face-font face font &optional frame
This function sets the font of face @var{face}.  The argument @var{font}

@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-font face &optional frame
This function returns the name of the font of face @var{face}.
@end defun

@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.

;; @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