xemacs-beta: man/lispref/display.texi comparison

comparison man/lispref/display.texi @ 428:3ecd8885ac67 r21-2-22

Import from CVS: tag r21-2-22

author	cvs
date	Mon, 13 Aug 2007 11:28:15 +0200
parents
children	abe6d1db359e

comparison

equal deleted inserted replaced

-:0a0253eac470
+:3ecd8885ac67
+@c -*-texinfo-*-
+@c This is part of the XEmacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998 Free Software Foundation, Inc.
+@c See the file lispref.texi for copying conditions.
+@setfilename ../../info/display.info
+@node Display, Hash Tables, Annotations, Top
+@chapter Emacs Display
+This chapter describes a number of other features related to the display
+that XEmacs presents to the user.
+@menu
+* Refresh Screen::      Clearing the screen and redrawing everything on it.
+* Truncation::          Folding or wrapping long text lines.
+* The Echo Area::       Where messages are displayed.
+* Warnings::            Display of Warnings.
+* 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.
+* Blinking::            How XEmacs shows the matching open parenthesis.
+* Usual Display::	The usual conventions for displaying nonprinting chars.
+* Display Tables::	How to specify other conventions.
+* Beeping::             Audible signal to the user.
+@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 &optional device
+This function redraws all frames on @var{device} marked as having their
+image garbled.  @var{device} defaults to the selected device.  If
+@var{device} is @code{t}, all devices will have their frames checked.
+@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 XEmacs also refreshes the screen.
+Some terminal emulators record separate contents for display-oriented
+programs such as XEmacs and for ordinary sequential display.  If you are
+using such a terminal, you might want to inhibit the redisplay on
+resumption.  @xref{Suspending XEmacs}.
+@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 XEmacs redraws the entire screen after it
+has been suspended and resumed.  Non-@code{nil} means yes, @code{nil}
+means no.
+@end defvar
+@cindex display update
+@cindex update display
+@cindex refresh display
+The above functions do not actually cause the display to be updated;
+rather, they clear out the internal display records that XEmacs
+maintains, so that the next time the display is updated it will be
+redrawn from scratch.  Normally this occurs the next time that
+@code{next-event} or @code{sit-for} is called; however, a display update
+will not occur if there is input pending.  @xref{Command Loop}.
+@defun force-cursor-redisplay
+This function causes an immediate update of the cursor on the selected
+frame.  (This function does not exist in FSF Emacs.)
+@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 truncated or continued on the next line.  When a line
+is truncated, this is normally shown with a @samp{\} in the rightmost
+column of the window on X displays, and with a @samp{$} on TTY devices.
+When a line is continued or ``wrapped'' onto the next line, this is
+shown with a curved arrow in the rightmost column of the window (or with
+a @samp{\} on TTY devices).  The additional screen lines used to display
+a long text line are called @dfn{continuation} lines.
+Normally, whenever line truncation is in effect for a particular
+window, a horizontal scrollbar is displayed in that window if the
+device supports scrollbars.  @xref{Scrollbars}.
+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 XEmacs displays lines that
+extend beyond the right edge of the window.  If it is non-@code{nil},
+then XEmacs does not display continuation lines; rather each line of
+text occupies exactly one screen line, and a backslash appears at the
+edge of any line that extends to or beyond the edge of the window.  The
+default is @code{nil}.
+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
+The backslash and curved arrow used to indicate truncated or continued
+lines are only defaults, and can be changed.  These images are actually
+glyphs (@pxref{Glyphs}).  XEmacs provides a great deal of flexibility
+in how glyphs can be controlled. (This differs from FSF Emacs, which
+uses display tables to control these images.)
+For details, @ref{Redisplay Glyphs}.
+@ignore Not yet in XEmacs
+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
+@end ignore
+@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{XEmacs Reference 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 XEmacs Reference 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
+In addition to only displaying a message, XEmacs allows you to
+@dfn{label} your messages, giving you fine-grained control of their
+display.  Message label is a symbol denoting the message type.  Some
+standard labels are:
+@itemize @bullet
+@item @code{message}---default label used by the @code{message}
+function;
+@item @code{error}---default label used for reporting errors;
+@item @code{progress}---progress indicators like
+@samp{Converting... 45%} (not logged by default);
+@item @code{prompt}---prompt-like messages like @samp{Isearch: foo} (not
+logged by default);
+@item @code{command}---helper command messages like @samp{Mark set} (not
+logged by default);
+@item @code{no-log}---messages that should never be logged
+@end itemize
+Several messages may be stacked in the echo area at once.  Lisp programs
+may access these messages, or remove them as appropriate, via the
+message stack.
+@defun display-message label message &optional frame stdout-p
+This function displays @var{message} (a string) labeled as @var{label},
+as described above.
+The @var{frame} argument specifies the frame to whose minibuffer the
+message should be printed.  This is currently unimplemented.  The
+@var{stdout-p} argument is used internally.
+@example
+(display-message 'command "Mark set")
+@end example
+@end defun
+@defun lmessage label string &rest arguments
+This function displays a message @var{string} with label @var{label}.
+It is similar to @code{message} in that it accepts a @code{printf}-like
+strings and any number of arguments.
+@example
+@group
+;; @r{Display a command message.}
+(lmessage 'command "Comment column set to %d" comment-column)
+@end group
+@group
+;; @r{Display a progress message.}
+(lmessage 'progress "Fontifying %s... (%d)" buffer percentage)
+@end group
+@group
+;; @r{Display a message that should not be logged.}
+(lmessage 'no-log "Done")
+@end group
+@end example
+@end defun
+@defun clear-message &optional label frame stdout-p no-restore
+This function remove any message with the given @var{label}
+from the message-stack, erasing it from the echo area if it's currently
+displayed there.
+If a message remains at the head of the message-stack and
+@var{no-restore} is @code{nil}, it will be displayed.  The string which
+remains in the echo area will be returned, or @code{nil} if the
+message-stack is now empty.  If @var{label} is nil, the entire
+message-stack is cleared.
+@example
+;; @r{Show a message, wait for 2 seconds, and restore old minibuffer}
+;; @r{contents.}
+(message "A message")
+@print{} A message
+@result{} "A Message"
+(lmessage 'my-label "Newsflash!  Newsflash!")
+@print{} Newsflash!  Newsflash!
+@result{} "Newsflash!  Newsflash!"
+(sit-for 2)
+(clear-message 'my-label)
+@print{} A message
+@result{} "A message"
+@end example
+Unless you need the return value or you need to specify a label,
+you should just use @code{(message nil)}.
+@end defun
+@defun current-message &optional frame
+This function returns the current message in the echo area, or
+@code{nil}.  The @var{frame} argument is currently unused.
+@end defun
+Some of the messages displayed in the echo area are also recorded in the
+@samp{ *Message-Log*} buffer.  Exactly which messages will be recorded
+can be tuned using the following variables.
+@defopt log-message-max-size
+This variable specifies the maximum size of the @samp{ *Message-log*}
+buffer.
+@end defopt
+@defvar log-message-ignore-labels
+This variable specifies the labels whose messages will not be logged.
+It should be a list of symbols.
+@end defvar
+@defvar log-message-ignore-regexps
+This variable specifies the regular expressions matching messages that
+will not be logged.  It should be a list of regular expressions.
+Normally, packages that generate messages that might need to be ignored
+should label them with @code{progress}, @code{prompt}, or @code{no-log},
+so they can be filtered by @code{log-message-ignore-labels}.
+@end defvar
+@defvar echo-keystrokes
+This variable determines how much time should elapse before command
+characters echo.  Its value must be a number, 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 Warnings
+@section Warnings
+XEmacs contains a facility for unified display of various warnings.
+Unlike errors, warnings are displayed in the situations when XEmacs
+encounters a problem that is recoverable, but which should be fixed for
+safe future operation.
+For example, warnings are printed by the startup code when it encounters
+problems with X keysyms, when there is an error in @file{.emacs}, and in
+other problematic situations.  Unlike messages, warnings are displayed
+in a separate buffer, and include an explanatory message that may span
+across several lines.  Here is an example of how a warning is displayed:
+@example
+(1) (initialization/error) An error has occurred while loading ~/.emacs:
+Symbol's value as variable is void: bogus-variable
+To ensure normal operation, you should investigate the cause of the error
+in your initialization file and remove it.  Use the `-debug-init' option
+to XEmacs to view a complete error backtrace.
+@end example
+Each warning has a @dfn{class} and a @dfn{priority level}.  The class is
+a symbol describing what sort of warning this is, such as
+@code{initialization}, @code{resource} or @code{key-mapping}.
+The warning priority level specifies how important the warning is.  The
+recognized warning levels, in increased order of priority, are:
+@code{debug}, @code{info}, @code{notice}, @code{warning}, @code{error},
+@code{critical}, @code{alert} and @code{emergency}.
+@defun display-warning class message &optional level
+This function displays a warning message @var{message} (a string).
+@var{class} should be a warning class symbol, as described above, or a
+list of such symbols.  @var{level} describes the warning priority level.
+If unspecified, it default to @code{warning}.
+@example
+@group
+(display-warning 'resource
+"Bad resource specification encountered:
+something like
+Emacs*foo: bar
+You should replace the * with a . in order to get proper behavior when
+you use the specifier and/or `set-face-*' functions.")
+@end group
+@group
+---------- Warning buffer ----------
+(1) (resource/warning) Bad resource specification encountered:
+something like
+Emacs*foo: bar
+You should replace the * with a . in order to get proper behavior when
+you use the specifier and/or `set-face-*' functions.
+---------- Warning buffer ----------
+@end group
+@end example
+@end defun
+@defun lwarn class level message &rest args
+This function displays a formatted labeled warning message.  As above,
+@var{class} should be the warning class symbol, or a list of such
+symbols, and @var{level} should specify the warning priority level
+(@code{warning} by default).
+Unlike in @code{display-warning}, @var{message} may be a formatted
+message, which will be, together with the rest of the arguments, passed
+to @code{format}.
+@example
+(lwarn 'message-log 'warning
+"Error caught in `remove-message-hook': %s"
+(error-message-string e))
+@end example
+@end defun
+@defvar log-warning-minimum-level
+This variable specifies the minimum level of warnings that should be
+generated.  Warnings with level lower than defined by this variable are
+completely ignored, as if they never happened.
+@end defvar
+@defvar display-warning-minimum-level
+This variable specifies the minimum level of warnings that should be
+displayed.  Unlike @code{log-warning-minimum-level}, setting this
+function does not suppress warnings entirely---they are still generated
+in the @samp{*Warnings*} buffer, only they are not displayed by default.
+@end defvar
+@defvar log-warning-suppressed-classes
+This variable specifies a list of classes that should not be logged or
+displayed.  If any of the class symbols associated with a warning is the
+same as any of the symbols listed here, the warning will be completely
+ignored, as it they never happened.
+@end defvar
+@defvar display-warning-suppressed-classes
+This variable specifies a list of classes that should not be logged or
+displayed.  If any of the class symbols associated with a warning is the
+same as any of the symbols listed here, the warning will not be
+displayed.  The warning will still logged in the *Warnings* buffer
+(unless also contained in `log-warning-suppressed-classes'), but the
+buffer will not be automatically popped up.
+@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} property 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} property 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 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 XEmacs.
+@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 XEmacs 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.
+Despite its name, the value of this variable can be either a string
+or a glyph (@pxref{Glyphs}).
+@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 extent with a
+@code{begin-glyph} property.  @xref{Extent 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.
+You can do the same job in a more general way by creating an extent
+with a begin-glyph property.  @xref{Extent 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
+This function works by actually changing the text in the buffer.  As a
+result, if you later undo in this buffer, you will see the message come
+and go.
+@end defun
+@node Blinking
+@section Blinking Parentheses
+@cindex parenthesis matching
+@cindex blinking
+@cindex balancing parentheses
+@cindex close parenthesis
+This section describes the mechanism by which XEmacs 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 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{runes}, each rune being an image that takes up one character
+position on the screen.  You can also define how to display each rune
+on your terminal, using the @dfn{rune table}.
+@menu
+* Display Table Format::	What a display table consists of.
+* Active Display Table::	How XEmacs selects a display table to use.
+* Character Descriptors::	Format of an individual element of a
+				  display table.
+@end menu
+@ignore Not yet working in XEmacs?
+* ISO Latin 1::			How to use display tables
+				  to support the ISO Latin 1 character set.
+@end ignore
+@node Display Table Format
+@subsection Display Table Format
+A display table is an array of 256 elements. (In FSF Emacs, a display
+table is 262 elements.  The six extra elements specify the truncation
+and continuation glyphs, etc.  This method is very kludgey, and in
+XEmacs the variables @code{truncation-glyph}, @code{continuation-glyph},
+etc. are used.  @xref{Truncation}.)
+@defun make-display-table
+This creates and returns a display table.  The table initially has
+@code{nil} in all elements.
+@end defun
+The 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}, a string, a glyph, or a vector of strings and
+glyphs (@pxref{Character Descriptors}).  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.''
+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 (concat "^" (char-to-string (+ i 64)))))
+(setq i (1+ i)))
+(aset disptab 127 "^?"))
+@end example
+@node Active Display Table
+@subsection Active Display Table
+@cindex active display table
+The active display table is controlled by the variable
+@code{current-display-table}.  This is a specifier, which means
+that you can specify separate values for it in individual buffers,
+windows, frames, and devices, as well as a global value.  It also
+means that you cannot set this variable using @code{setq}; use
+@code{set-specifier} instead.  @xref{Specifiers}. (FSF Emacs
+uses @code{window-display-table}, @code{buffer-display-table},
+@code{standard-display-table}, etc. to control the display table.
+However, specifiers are a cleaner and more powerful way of doing
+the same thing.  FSF Emacs also uses a different format for
+the contents of a display table, using additional indirection
+to a ``glyph table'' and such.  Note that ``glyph'' has a different
+meaning in XEmacs.)
+Individual faces can also specify an overriding display table;
+this is set using @code{set-face-display-table}.  @xref{Faces}.
+If no display table can be determined for a particular window,
+then XEmacs uses the usual display conventions.  @xref{Usual Display}.
+@node Character Descriptors
+@subsection Character Descriptors
+@cindex character descriptor
+Each element of the display-table vector describes how to display
+a particular character and is called a @dfn{character descriptor}.
+A character descriptor can be:
+@table @asis
+@item a string
+Display this particular string wherever the character is to be displayed.
+@item a glyph
+Display this particular glyph wherever the character is to be displayed.
+@item a vector
+The vector may contain strings and/or glyphs.  Display the elements of
+the vector one after another wherever the character is to be displayed.
+@item @code{nil}
+Display according to the standard interpretation (@pxref{Usual Display}).
+@end table
+@ignore Not yet working in XEmacs?
+@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.
+@end ignore
+@node Beeping
+@section Beeping
+@cindex beeping
+@cindex bell
+@cindex sound
+You can make XEmacs ring a bell, play a sound, 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 sound device
+@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}.  If @var{sound} is
+specified, it should be a symbol specifying which sound to make.  This
+sound will be played if @code{visible-bell} is @code{nil}. (This only
+works if sound support was compiled into the executable and you are
+running on the console of a Sun SparcStation, SGI, HP9000s700, or Linux
+PC. Otherwise you just get a beep.) The optional third argument
+specifies what device to make the sound on, and defaults to the selected
+device.
+@end defun
+@defun beep &optional dont-terminate sound device
+This is a synonym for @code{ding}.
+@end defun
+@defopt visible-bell
+This variable determines whether XEmacs should flash the screen to
+represent a bell.  Non-@code{nil} means yes, @code{nil} means no.  On
+TTY devices, this is effective only if the Termcap entry for the
+terminal type has the visible bell flag (@samp{vb}) set.
+@end defopt
+@defvar sound-alist
+This variable holds an alist associating names with sounds.  When
+@code{beep} or @code{ding} is called with one of the name symbols, the
+associated sound will be generated instead of the standard beep.
+Each element of @code{sound-alist} is a list describing a sound.  The
+first element of the list is the name of the sound being defined.
+Subsequent elements of the list are alternating keyword/value pairs:
+@table @code
+@item sound
+A string of raw sound data, or the name of another sound to play.  The
+symbol @code{t} here means use the default X beep.
+@item volume
+An integer from 0-100, defaulting to @code{bell-volume}.
+@item pitch
+If using the default X beep, the pitch (Hz) to generate.
+@item duration
+If using the default X beep, the duration (milliseconds).
+@end table
+For compatibility, elements of `sound-alist' may also be:
+@itemize @bullet
+@item
+@code{( sound-name . <sound> )}
+@item
+@code{( sound-name <volume> <sound> )}
+@end itemize
+You should probably add things to this list by calling the function
+@code{load-sound-file}.
+Caveats:
+@itemize @minus
+@item
+You can only play audio data if running on the console screen of a Sun
+SparcStation, SGI, or HP9000s700.
+@item
+The pitch, duration, and volume options are available everywhere, but
+many X servers ignore the `pitch' option.
+@end itemize
+The following beep-types are used by XEmacs itself:
+@table @code
+@item auto-save-error
+when an auto-save does not succeed
+@item command-error
+when the XEmacs command loop catches an error
+@item undefined-key
+when you type a key that is undefined
+@item undefined-click
+when you use an undefined mouse-click combination
+@item no-completion
+during completing-read
+@item y-or-n-p
+when you type something other than 'y' or 'n'
+@item yes-or-no-p
+when you type something other than 'yes' or 'no'
+@item default
+used when nothing else is appropriate.
+@end table
+Other lisp packages may use other beep types, but these are the ones that
+the C kernel of XEmacs uses.
+@end defvar
+@defopt bell-volume
+This variable specifies the default volume for sounds, from 0 to 100.
+@end defopt
+@deffn Command load-default-sounds
+This function loads and installs some sound files as beep-types.
+@end deffn
+@deffn Command load-sound-file filename sound-name &optional volume
+This function reads in an audio file and adds it to @code{sound-alist}.
+The sound file must be in the Sun/NeXT U-LAW format.  @var{sound-name}
+should be a symbol, specifying the name of the sound.  If @var{volume}
+is specified, the sound will be played at that volume; otherwise, the
+value of @var{bell-volume} will be used.
+@end deffn
+@defun play-sound sound &optional volume device
+This function plays sound @var{sound}, which should be a symbol
+mentioned in @code{sound-alist}.  If @var{volume} is specified, it
+overrides the value (if any) specified in @code{sound-alist}.
+@var{device} specifies the device to play the sound on, and defaults
+to the selected device.
+@end defun
+@deffn Command play-sound-file file &optional volume device
+This function plays the named sound file at volume @var{volume}, which
+defaults to @code{bell-volume}.  @var{device} specifies the device to
+play the sound on, and defaults to the selected device.
+@end deffn

Mercurial > hg > xemacs-beta

comparison man/lispref/display.texi @ 428:3ecd8885ac67 r21-2-22