⟦dfa6e2182⟧

TextFile

@setfilename ../info/display
@node Emacs Display, Tips and Standards, Operating System Interface, Top
@chapter Emacs Display

This chapter describes a number of features related to the display
that Emacs presents to the user.

@menu
* Window Systems::      Which window system is being used
* Screen Attributes::   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
* Overlay Arrow::       Display of an arrow to indicate position
* Temporary Displays::  Displays that go away automatically
* Waiting::             Forcing display update and waiting for user
* Blinking::            Bouncing the cursor
* Displaying Control Characters::    How control characters are displayed
@end menu

@deffn Command redraw-display
  This function clears the screen and redraws what is supposed to appear
on it.
@end deffn

@node Window Systems, Screen Attributes, Emacs Display, Emacs Display
@section Window Systems

  Emacs works with several window systems, most notably, X.

@defvar window-setup-hook
  The value of the @code{window-setup-hook} variable is either
@code{nil} or that of a function that Emacs calls after loading your
@file{.emacs} file, the default initialization file (if any),  after
loading terminal-specific lisp code, and after calling @code{term-setup-hook}.
@code{window-setup-hook} is called with no arguments.
@end defvar

@defvar window-system
@cindex X window system
  This global variable tells Emacs what window system it 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-system-version
  This variable will be either 10 or 11 when using the X window system.
@end defvar

@node Screen Attributes, Truncation, Window Systems, Emacs Display
@section Screen Attributes

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

  The screen attribute functions describe and define the characteristics
of your terminal.

@defun screen-height
  This function returns number of lines on the screen that are available
for display.

@example
(screen-height)
     @result{} 50
@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 will be altered proportionally to fit.

  If @var{not-actual-size} is non-@code{nil}, then Emacs should use
@var{lines} for display, but it will still know about the actual size of
the screen.  Knowing the correct actual size may be necessary for
correct cursor positioning.

  If @var{lines} is different from what it was previously, Emacs will
redisplay the screen using the new size.

  It returns @code{nil}.
@end defun

@defun screen-width
  This function returns number of columns on the screen that are
available for display.

@example
(screen-width)
     @result{} 80
@end example
@end defun

@defun set-screen-width columns &optional not-actual-size
  This function declares that the terminal can display @var{columns}
columns.  

  @var{not-actual-size} is the same as in @code{set-screen-height}.

  If @var{columns} is different from what it was previously, Emacs will
redisplay the screen using the new size.

  It returns @code{nil}.
@end defun

@defvar no-redraw-on-reenter
@cindex @code{suspend-emacs}, related to @code{no-redraw-on-reenter}
@cindex resume, related to @code{no-redraw-on-reenter}
  This global variable determines whether Emacs should redraw the entire
screen after it has been suspended and resumed.  @code{t} means do,
@code{nil} means don't.  This is useful if the terminal can remember and
restore the Emacs screen.
@end defvar

@defvar inverse-video
@cindex highlighting
  This global variable determines whether Emacs will use inverse video
for all text on the screen.  @code{t} means do, @code{nil} means don't.
@end defvar

@defopt mode-line-inverse-video
  This variable determines how the mode line will be displayed.  If
it is non-@code{nil}, then the mode line will use inverse video (or
another suitable display mode).  Otherwise the mode line will be in
normal display, just like the rest of the screen.
@end defopt

@node Truncation, The Echo Area, Screen Attributes, Emacs Display
@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 truncated or continued on the next line.  When a line
is trucated, this is shown with a @samp{$} in the right most column of
the window.  When a line is continued or `wrapped' onto the next line,
this is shown with a @samp{\} on the right most column of the window.
Lines that continue onto the next line are called @dfn{continuation}
lines.  (Note that wrapped lines are not filled.  Filling has nothing to
do with truncation and continuation.  @xref{Auto Filling}.)

@defopt truncate-lines
   This per-buffer-local variable controls how Emacs displays lines that
extend beyond the right edge of the window.  If it is non-@code{nil},
then Emacs will not display continuation lines; but rather each line of
text will take exactly one screen line and a dollar sign will be shown
at the edge of any line that extends to or beyond the edge of the
window.

 This variable is overridden by the variable
@code{truncate-partial-width-windows} if that variable is non-@code{nil}
and the window in question is not the full width of the screen.
@end defopt

@defvar default-truncate-lines
  This variable is the default value for @code{truncate-lines} in buffers
that do not override it.
@end defvar

@defopt truncate-partial-width-windows
@cindex horizontal split lines
  This variable determines how lines that are too wide to fit on the
screen are displayed in side-by-side windows (@pxref{Splitting Windows}).  If it is non-@code{nil}, then wide lines will be truncated
(with a @samp{$} at the end of the line), otherwise they will be wrapped
(with a @samp{\} at the end of the line).
@end defopt


@node The Echo Area, Selective Display, Truncation, Emacs Display
@section The Echo Area

@cindex error display
  The minibuffer is @emph{not} the @dfn{echo area}, despite the fact
that they occupy the same physical space on the screen.  The echo area
is where messages from Emacs are displayed, using the @code{message}
primitive or something similar.  The @cite{GNU Emacs Manual} specifies
the rules for how conflicts between use of the echo area and the
minibuffer are resolved (@pxref{Minibuffer, , The Minibuffer, emacs,
The GNU Emacs User Manual}).

@defun message string &rest arguments
  This function prints a one-line message in the echo area.
@var{string} is similar to a C language @code{printf} control string.
See @code{format} in @ref{Conversion of Characters and Strings} for the
details on the conversion specifications.  It returns the constructed
string.

@example
(message "Minibuffer depth is %d." (minibuffer-depth))
@print{} "Minibuffer depth is 0."

---------- Echo Area ----------
Minibuffer depth is 0.
---------- Echo Area ----------
@end example

@end defun

@defvar cursor-in-echo-area
  This global variable controls where the cursor will be placed when a
message is displayed in the echo area.  If it is non-@code{nil}, then do
put the cursor there.
@end defvar

@node Selective Display, Overlay Arrow, The Echo Area, Emacs Display
@section Selective Display
@cindex selective display

  Selective display causes specially marked lines not to appear, or
indented lines not to appear.  Outline mode uses selective display.

  In first variant, the user inserts strings that Emacs recognizes as
marking a heading, such as an @samp{*} and @samp{**}, or @samp{@@chapter}
and @samp{@@section}; in the other variant, the user inserts
indentation.

  Selective display works by replacing the newline (@key{^j}) following
a heading pattern or indentation with a @key{RET} (i.e., a @key{^m}).
As far as Emacs is concerned, the line following a @key{^m} is
invisible.

  You can customize the criterion for distinguishing heading lines by
setting the variable @code{outline-regexp}.  @xref{Outline Format, ,
Format of Outlines, emacs, The GNU Emacs Manual}.

  On its own, selective display does not effect editing commands; for
example, @kbd{C-f} (@code{forward-char} will move point into invisible
space.  However, the replacement of newline characters with carriage return
characters affects some editing commands, such as the vertical movement
commands that use the newline character to locate the ends of lines.
This means that a @code{next-line} command will skip invisible lines.
Also, most modes that use selective display provide mode-specific
editing commands, such as @code{outline-forward-same-level}.

  When you write a selectively displayed buffer into a file, all the
@key{^m}'s are replaced by their original newlines.  This means that
when you next read in the file, it looks OK, with nothing invisible.
Selective display is an effect that is only seen in 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 @key{^m} will not be displayed.

@item
If the value of @code{selective-display} is a positive integer, then
lines that start with whitespace in more than @code{selective-display}
columns will not be 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 a hundred lines.  Character movement
commands (such as @code{forward-char}) will not skip the invisible
portion however, and it is possible, if tricky, to insert or delete
parts of an invisible portion.

  In the examples below, what is shown is the @emph{display} of the buffer
@code{foo}, which changes with the value of @code{selective-display}.  The
@emph{contents} of the buffer does not change.

@example
(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 ----------

(setq selective-display-ellipses t)
     @result{} t
(setq selective-display 2)
     @result{} 2

---------- Buffer: foo ----------
1 on this column
 2on this column ...
 2on this column
1 on this column
---------- Buffer: foo ----------

(setq selective-display-ellipses nil)
     @result{} nil

---------- Buffer: foo ----------
1 on this column
 2on this column
 2on this column
1 on this column
---------- Buffer: foo ----------
@end example
@end defvar

@defvar selective-display-ellipses
  This buffer-local variable means display @samp{@dots{}} on the previous
line when a line is made invisible due to @code{selective-display}
being non-@code{nil}. 
@end defvar

@node Overlay Arrow, Temporary Displays, Selective Display, Emacs Display
@section Overlay Arrow

The @dfn{overlay arrow} is useful for directing the user's attention
to a particular line in a buffer.  For example, in a debugger mode,
the overlay arrow might point to the current line of code about to
be executed.

@defvar overlay-arrow-string

The string to display as an arrow.

@end defvar

@defvar overlay-arrow-position
Marker for where to display @code{overlay-arrow-string} on top
of the buffer text.  This must be a marker at the beginning of
some line.  The overlay string will only display over text on that
line up to the end of line.

The overlay string will only be displayed in the buffer which this
marker points into.

@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

@node Temporary Displays, Waiting, Overlay Arrow, Emacs Display
@section Temporary Displays

  Temporary displays are used by help commands.

@defvar temp-buffer-show-hook
     The value of the @code{temp-buffer-show-hook} variable is either
@code{nil} or is called as a function to display a help buffer.  This
variable is used by @code{with-output-to-temp-buffer}.
@end defvar

@defspec with-output-to-temp-buffer buffer-name forms@dots{}
  This function arranges that output generated by evaluating @var{forms}
will be inserted into the buffer named @var{buffer-name}.  The buffer is
then popped into some window for viewing.  The buffer is displayed but
not selected.

  The buffer is named by the string @var{buffer-name}, and it need not
exist.  @var{buffer-name} 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} first binds @code{standard-output} to
the buffer, then it evaluates the forms in @var{forms}.  With
@code{standard-output} rebound, any output directed there will naturally
be inserted into the buffer.

  The value of the last form in @var{forms} is returned.

@example
---------- Buffer: foo ----------
 This is the contents of foo.
---------- Buffer: foo ----------

(with-output-to-temp-buffer "foo"
    (print 20)
    (print standard-output))
@result{} #<buffer foo>

---------- Buffer: foo ----------
20

#<buffer foo>

---------- Buffer: foo ----------
@end example
@end defspec

@defun momentary-string-display string position &optional char message
  This function momentarily displays @var{string} in the current buffer at
@var{position} (which is a character offset from the beginning of the buffer).
The display remains until the next character is typed.

  If the next character the user types is @var{char}, then Emacs
ignores it.  Otherwise it is then the first character in the next
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 move the point forward.  @var{char} is @key{SPC} by default.

Note that the result of @code{momentary-string-display} is the character
typed rather than @code{t} if that character is not @var{char}.

  If @var{message} is non-@code{nil}, it is displayed in the echo area.  If
it is @code{nil}, then instructions to type @var{char} are
displayed there, e.g., @samp{Type RET to continue editing}.

  In the example, the point in @samp{foo} is located at the beginning of the
second line.

@example
---------- Buffer: foo ----------
This is the contents of foo.
@point{}This is the contents of foo.
---------- Buffer: foo ----------

(momentary-string-display
   "******* Important Message! *******" (point) ?\r
   "Type RET when done reading")

     @result{} t

---------- Buffer: foo ----------
This is the contents of foo.
******* Important Message! *******This is the contents of foo.
---------- Buffer: foo ----------

---------- Echo Area ----------
Type RET when done reading
@end example

  One disadvantage of using this function is minor confusion in how to undo.
@end defun

@node Waiting, Blinking, Temporary Displays, Emacs Display
@section Waiting for Elapsed Time or Input

@cindex pausing
@cindex waiting
@cindex waiting for Elapsed Time or Input

  The waiting commands are designed to make Emacs wait for a certain
amount of time to pass to until there is input.  For example, you may
wish to pause in the middle of a computation to allow the user time to
view the display.  @code{sit-for} performs a pause with an update of
screen, while @code{sleep-for} performs a pause without updating the
screen.

@defun sit-for seconds
  This function performs redisplay (if there is no pending input from
the user), then waits @var{seconds} seconds, or until input is
available.  The result is @code{t} if @code{sit-for} waited the full
time with no input arriving (see @code{input-pending-p} in @ref{Keyboard
Input}).  Otherwise, @code{nil} is returned.

@cindex forcing redisplay
Redisplay is always preempted if input arrives, and does not
happen at all if input is available before it starts.  Thus there is no
way to force an update if there is pending input.  But if there is no
input pending, you can force an update with no delay by using
@code{(sit-for 0)}.

  You use @code{sit-for} to give the user time to read messages that you
display.
@end defun

@defun sleep-for seconds
  This function simply pauses, without updating the display, for
@var{seconds} seconds.  It pays no attention to available input.  It
returns @code{nil}.

  You use @code{sleep-for} to guarantee a delay.
@end defun

@node Blinking, Displaying Control Characters, Waiting, Emacs Display
@section Blinking

@cindex parenthesis matching
@cindex blinking
@cindex balancing
@cindex close parenthesis

  These are the internals of the mechanism by which Emacs shows a matching open
parenthesis.

@vindex blink-paren-hook
@vindex blink-paren-function
@defvar blink-paren-hook
  The value of this variable should be a function (of no arguments) to
be called whenever a char with close parenthesis syntax is inserted.
The value of @code{blink-paren-hook} may be @code{nil}, in which case
nothing is done.

@quotation
@b{Note:} In version 18, this function is named @code{blink-paren-hook};
but since @code{blink-paren-hook} is not called by the @code{run-hooks}
function, it is being re-named @code{blink-paren-function} in Version
19.
@end quotation
@end defvar

@defvar blink-matching-paren
Non-@code{nil} means show matching open-paren when close-paren is inserted.
@end defvar

@defun blink-matching-open
Move cursor momentarily to the beginning of the sexp before point.

@example
(defun interactive-blink-matching-open ()
  "Move cursor momentarily to the beginning of the sexp before point."
  (interactive)
  (let ((blink-matching-paren t))
    (blink-matching-open)))
@end example
@end defun

@node Displaying Control Characters,  , Blinking, Emacs Display
@section Displaying Control Characters

@defopt ctl-arrow
@cindex control characters in display
  This buffer-local variable controls how control characters are displayed.
If it is non-@code{nil}, then they are displayed as an uparrow followed by the
character: @samp{^A}.  If it is @code{nil}, then they are displayed as a
backslash followed by three octal digits, @samp{\001}.
@end defopt

@defvar default-ctl-arrow
  The value of this variable is the default value for @code{ctl-arrow} in
buffers that do not override it.  This is the same as @code{(default-value
'ctl-arrow)}.
@end defvar
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦dfa6e2182⟧ TextFile

Derivation

TextFile
