- The "echo area" is used for displaying messages made with the
-`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 `XEmacs
-Reference Manual' specifies the rules for resolving conflicts between
-the echo area and the minibuffer for use of that screen space (*note
-The Minibuffer: (emacs)Minibuffer.). Error messages appear in the echo
-area; see *Note Errors::.
-
- You can write output in the echo area by using the Lisp printing
-functions with `t' as the stream (*note Output Functions::), or as
-follows:
-
- - Function: message string &rest arguments
- This function displays a one-line message in the echo area. The
- argument STRING is similar to a C language `printf' control
- string. See `format' in *Note String Conversion::, for the details
- on the conversion specifications. `message' returns the
- constructed string.
-
- In batch mode, `message' prints the message text on the standard
- error stream, followed by a newline.
-
- If STRING is `nil', `message' clears the echo area. If the
- minibuffer is active, this brings the minibuffer contents back onto
- the screen immediately.
-
- (message "Minibuffer depth is %d."
- (minibuffer-depth))
- -| Minibuffer depth is 0.
- => "Minibuffer depth is 0."
-
- ---------- Echo Area ----------
- Minibuffer depth is 0.
- ---------- Echo Area ----------
-
- In addition to only displaying a message, XEmacs allows you to
-"label" your messages, giving you fine-grained control of their
-display. Message label is a symbol denoting the message type. Some
-standard labels are:
-
- * `message'--default label used by the `message' function;
-
- * `error'--default label used for reporting errors;
-
- * `progress'--progress indicators like `Converting... 45%' (not
- logged by default);
-
- * `prompt'--prompt-like messages like `Isearch: foo' (not logged by
- default);
-
- * `command'--helper command messages like `Mark set' (not logged by
- default);
-
- * `no-log'--messages that should never be logged
-
- 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.
-
- - Function: display-message label message &optional frame stdout-p
- This function displays MESSAGE (a string) labeled as LABEL, as
- described above.
-
- The FRAME argument specifies the frame to whose minibuffer the
- message should be printed. This is currently unimplemented. The
- STDOUT-P argument is used internally.
-
- (display-message 'command "Mark set")
-
- - Function: lmessage label string &rest arguments
- This function displays a message STRING with label LABEL. It is
- similar to `message' in that it accepts a `printf'-like strings
- and any number of arguments.
-
- ;; Display a command message.
- (lmessage 'command "Comment column set to %d" comment-column)
-
- ;; Display a progress message.
- (lmessage 'progress "Fontifying %s... (%d)" buffer percentage)
-
- ;; Display a message that should not be logged.
- (lmessage 'no-log "Done")
-
- - Function: clear-message &optional label frame stdout-p no-restore
- This function remove any message with the given 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
- NO-RESTORE is `nil', it will be displayed. The string which
- remains in the echo area will be returned, or `nil' if the
- message-stack is now empty. If LABEL is nil, the entire
- message-stack is cleared.
-
- ;; Show a message, wait for 2 seconds, and restore old minibuffer
- ;; contents.
- (message "A message")
- -| A message
- => "A Message"
- (lmessage 'my-label "Newsflash! Newsflash!")
- -| Newsflash! Newsflash!
- => "Newsflash! Newsflash!"
- (sit-for 2)
- (clear-message 'my-label)
- -| A message
- => "A message"
-
- Unless you need the return value or you need to specify a label,
- you should just use `(message nil)'.
-
- - Function: current-message &optional frame
- This function returns the current message in the echo area, or
- `nil'. The FRAME argument is currently unused.
-
- Some of the messages displayed in the echo area are also recorded in
-the ` *Message-Log*' buffer. Exactly which messages will be recorded
-can be tuned using the following variables.
-
- - User Option: log-message-max-size
- This variable specifies the maximum size of the ` *Message-log*'
- buffer.
-
- - Variable: log-message-ignore-labels
- This variable specifies the labels whose messages will not be
- logged. It should be a list of symbols.
-
- - Variable: 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 `progress', `prompt', or `no-log',
- so they can be filtered by `log-message-ignore-labels'.
-
- - Variable: 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 `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.
-
- - Variable: cursor-in-echo-area
- This variable controls where the cursor appears when a message is
- displayed in the echo area. If it is non-`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 `nil'; Lisp programs bind it to `t' for
- brief periods of time.
-
-\1f
-File: lispref.info, Node: Warnings, Next: Invisible Text, Prev: The Echo Area, Up: Display
-
-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 `.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:
-
- (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.
-
- Each warning has a "class" and a "priority level". The class is a
-symbol describing what sort of warning this is, such as
-`initialization', `resource' or `key-mapping'.
-
- The warning priority level specifies how important the warning is.
-The recognized warning levels, in increased order of priority, are:
-`debug', `info', `notice', `warning', `error', `critical', `alert' and
-`emergency'.
-
- - Function: display-warning class message &optional level
- This function displays a warning message MESSAGE (a string).
- CLASS should be a warning class symbol, as described above, or a
- list of such symbols. LEVEL describes the warning priority level.
- If unspecified, it default to `warning'.
-
- (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.")
-
- ---------- 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 ----------
-
- - Function: lwarn class level message &rest args
- This function displays a formatted labeled warning message. As
- above, CLASS should be the warning class symbol, or a list of such
- symbols, and LEVEL should specify the warning priority level
- (`warning' by default).
-
- Unlike in `display-warning', MESSAGE may be a formatted message,
- which will be, together with the rest of the arguments, passed to
- `format'.
-
- (lwarn 'message-log 'warning
- "Error caught in `remove-message-hook': %s"
- (error-message-string e))
-
- - Variable: 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.
-
- - Variable: display-warning-minimum-level
- This variable specifies the minimum level of warnings that should
- be displayed. Unlike `log-warning-minimum-level', setting this
- function does not suppress warnings entirely--they are still
- generated in the `*Warnings*' buffer, only they are not displayed
- by default.
-
- - Variable: 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.
-
- - Variable: 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.
-
-\1f
-File: lispref.info, Node: Invisible Text, Next: Selective Display, Prev: Warnings, Up: Display
-
-Invisible Text
-==============
-
- You can make characters "invisible", so that they do not appear on
-the screen, with the `invisible' property. This can be either a text
-property or a property of an overlay.
-
- In the simplest case, any non-`nil' `invisible' property makes a
-character invisible. This is the default case--if you don't alter the
-default value of `buffer-invisibility-spec', this is how the
-`invisibility' property works. This feature is much like selective
-display (*note Selective Display::), but more general and cleaner.
-
- More generally, you can use the variable `buffer-invisibility-spec'
-to control which values of the `invisible' property make text
-invisible. This permits you to classify the text into different subsets
-in advance, by giving them different `invisible' values, and
-subsequently make various subsets visible or invisible by changing the
-value of `buffer-invisibility-spec'.
-
- Controlling visibility with `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.
-
- - Variable: buffer-invisibility-spec
- This variable specifies which kinds of `invisible' properties
- actually make a character invisible.
-
- `t'
- A character is invisible if its `invisible' property is
- non-`nil'. This is the default.
-
- 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:
-
- `ATOM'
- A character is invisible if its `invisible' property
- value is ATOM or if it is a list with ATOM as a member.
-
- `(ATOM . t)'
- A character is invisible if its `invisible' property
- value is ATOM or if it is a list with 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.
-
- 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.
-
-\1f
-File: lispref.info, Node: Selective Display, Next: Overlay Arrow, Prev: Invisible Text, Up: Display
-
-Selective Display
-=================
-
- "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 (*note 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, `C-f' (`forward-char') moves point unhesitatingly into
-invisible text. However, the replacement of newline characters with
-carriage return characters affects some editing commands. For example,
-`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.
-
- - Variable: selective-display
- This buffer-local variable enables selective display. This means
- that lines, or portions of lines, may be made invisible.
-
- * If the value of `selective-display' is `t', then any portion
- of a line that follows a control-m is not displayed.
-
- * If the value of `selective-display' is a positive integer,
- then lines that start with more than that many columns of
- indentation are not displayed.
-
- When some portion of a buffer is invisible, the vertical movement
- commands operate as if that portion did not exist, allowing a
- single `next-line' command to skip any number of invisible lines.
- However, character movement commands (such as `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 _display appearance_ of the
- buffer `foo', which changes with the value of `selective-display'.
- The _contents_ of the buffer do not change.
-
- (setq selective-display nil)
- => 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 2)
- => 2
-
- ---------- Buffer: foo ----------
- 1 on this column
- 2on this column
- 2on this column
- 1 on this column
- ---------- Buffer: foo ----------
-
- - Variable: selective-display-ellipses
- If this buffer-local variable is non-`nil', then XEmacs displays
- `...' at the end of a line that is followed by invisible text.
- This example is a continuation of the previous one.
-
- (setq selective-display-ellipses t)
- => t
-
- ---------- Buffer: foo ----------
- 1 on this column
- 2on this column ...
- 2on this column
- 1 on this column
- ---------- Buffer: foo ----------
-
- You can use a display table to substitute other text for the
- ellipsis (`...'). *Note Display Tables::.