1 This is ../info/lispref.info, produced by makeinfo version 4.0b from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Annotation Basics, Next: Annotation Primitives, Up: Annotations
58 Marginal annotations are notes associated with a particular location
59 in a buffer. They may be displayed in a margin created on the
60 left-hand or right-hand side of the frame, in any whitespace at the
61 beginning or end of a line, or inside of the text itself. Every
62 annotation may have an associated action to be performed when the
63 annotation is selected. The term "annotation" is used to refer to an
64 individual note. The term "margin" is generically used to refer to the
65 whitespace before the first character on a line or after the last
68 Each annotation has the following characteristics:
70 This is a glyph object and is used as the displayed representation
74 If given, this glyph is used as the displayed representation of
75 the annotation when the mouse is pressed down over the annotation.
78 The face with which to display the glyph.
81 Which side of the text (left or right) the annotation is displayed
85 If non-`nil', this field must contain a function capable of being
86 the first argument to `funcall'. This function is normally
87 evaluated with a single argument, the value of the DATA field,
88 each time the annotation is selected. However, if the WITH-EVENT
89 parameter to `make-annotation' is non-`nil', the function is
90 called with two arguments. The first argument is the same as
91 before, and the second argument is the event (a button-up event,
92 usually) that activated the annotation.
95 Not used internally. This field can contain any E-Lisp object.
96 It is passed as the first argument to ACTION described above.
99 A menu displayed when the right mouse button is pressed over the
102 The margin is divided into "outside" and "inside". The outside
103 margin is space on the left or right side of the frame which normal text
104 cannot be displayed in. The inside margin is that space between the
105 leftmost or rightmost point at which text can be displayed and where the
106 first or last character actually is.
108 There are four different "layout types" which affect the exact
109 location an annotation appears.
112 The annotation is placed in the outside margin area. as close as
113 possible to the edge of the frame. If the outside margin is not
114 wide enough for an annotation to fit, it is not displayed.
117 The annotation is placed in the inside margin area, as close as
118 possible to the edge of the frame. If the inside margin is not
119 wide enough for the annotation to fit, it will be displayed using
120 any available outside margin space if and only if the specifier
121 `use-left-overflow' or `use-right-overflow' (depending on which
122 side the annotation appears in) is non-`nil'.
125 The annotation is placed in the inside margin area, as close as
126 possible to the first or last non-whitespace character on a line.
127 If the inside margin is not wide enough for the annotation to fit,
128 it will be displayed if and only if the specifier
129 `use-left-overflow' or `use-right-overflow' (depending on which
130 side the annotation appears in) is non-`nil'.
133 The annotation is placed at the position it is inserted. It will
134 create enough space for itself inside of the text area. It does
135 not take up a place in the logical buffer, only in the display of
138 The current layout policy is that all `whitespace' annotations are
139 displayed first. Next, all `inside-margin' annotations are displayed
140 using any remaining space. Finally as many `outside-margin'
141 annotations are displayed as possible. The `text' annotations will
142 always display as they create their own space to display in.
145 File: lispref.info, Node: Annotation Primitives, Next: Annotation Properties, Prev: Annotation Basics, Up: Annotations
147 Annotation Primitives
148 =====================
150 - Function: make-annotation glyph &optional position layout buffer
151 with-event d-glyph rightp
152 This function creates a marginal annotation at position POSITION in
153 BUFFER. The annotation is displayed using GLYPH, which should be
154 a glyph object or a string, and is positioned using layout policy
155 LAYOUT. If POSITION is `nil', point is used. If LAYOUT is `nil',
156 `whitespace' is used. If BUFFER is `nil', the current buffer is
159 If WITH-EVENT is non-`nil', then when an annotation is activated,
160 the triggering event is passed as the second arg to the annotation
161 function. If D-GLYPH is non-`nil' then it is used as the glyph
162 that will be displayed when button1 is down. If RIGHTP is
163 non-`nil' then the glyph will be displayed on the right side of
164 the buffer instead of the left.
166 The newly created annotation is returned.
168 - Function: delete-annotation annotation
169 This function removes ANNOTATION from its buffer. This does not
170 modify the buffer text.
172 - Function: annotationp annotation
173 This function returns `t' if ANNOTATION is an annotation, `nil'
177 File: lispref.info, Node: Annotation Properties, Next: Margin Primitives, Prev: Annotation Primitives, Up: Annotations
179 Annotation Properties
180 =====================
182 - Function: annotation-glyph annotation
183 This function returns the glyph object used to display ANNOTATION.
185 - Function: set-annotation-glyph annotation glyph &optional layout side
186 This function sets the glyph of ANNOTATION to GLYPH, which should
187 be a glyph object. If LAYOUT is non-`nil', set the layout policy
188 of ANNOTATION to LAYOUT. If SIDE is `left' or `right', change the
189 side of the buffer at which the annotation is displayed to the
190 given side. The new value of `annotation-glyph' is returned.
192 - Function: annotation-down-glyph annotation
193 This function returns the glyph used to display ANNOTATION when
194 the left mouse button is depressed on the annotation.
196 - Function: set-annotation-down-glyph annotation glyph
197 This function returns the glyph used to display ANNOTATION when
198 the left mouse button is depressed on the annotation to GLYPH,
199 which should be a glyph object.
201 - Function: annotation-face annotation
202 This function returns the face associated with ANNOTATION.
204 - Function: set-annotation-face annotation face
205 This function sets the face associated with ANNOTATION to FACE.
207 - Function: annotation-layout annotation
208 This function returns the layout policy of ANNOTATION.
210 - Function: set-annotation-layout annotation layout
211 This function sets the layout policy of ANNOTATION to LAYOUT.
213 - Function: annotation-side annotation
214 This function returns the side of the buffer that ANNOTATION is
215 displayed on. Return value is a symbol, either `left' or `right'.
217 - Function: annotation-data annotation
218 This function returns the data associated with ANNOTATION.
220 - Function: set-annotation-data annotation data
221 This function sets the data field of ANNOTATION to DATA. DATA is
224 - Function: annotation-action annotation
225 This function returns the action associated with ANNOTATION.
227 - Function: set-annotation-action annotation action
228 This function sets the action field of ANNOTATION to ACTION.
231 - Function: annotation-menu annotation
232 This function returns the menu associated with ANNOTATION.
234 - Function: set-annotation-menu annotation menu
235 This function sets the menu associated with ANNOTATION to MENU.
236 This menu will be displayed when the right mouse button is pressed
239 - Function: annotation-visible annotation
240 This function returns `t' if there is enough available space to
241 display ANNOTATION, `nil' otherwise.
243 - Function: annotation-width annotation
244 This function returns the width of ANNOTATION in pixels.
246 - Function: hide-annotation annotation
247 This function removes ANNOTATION's glyph, making it invisible.
249 - Function: reveal-annotation annotation
250 This function restores ANNOTATION's glyph, making it visible.
253 File: lispref.info, Node: Locating Annotations, Next: Annotation Hooks, Prev: Margin Primitives, Up: Annotations
258 - Function: annotations-in-region start end buffer
259 This function returns a list of all annotations in BUFFER which
260 are between START and END inclusively.
262 - Function: annotations-at &optional position buffer
263 This function returns a list of all annotations at POSITION in
264 BUFFER. If POSITION is `nil' point is used. If BUFFER is `nil'
265 the current buffer is used.
267 - Function: annotation-list &optional buffer
268 This function returns a list of all annotations in BUFFER. If
269 BUFFER is `nil', the current buffer is used.
271 - Function: all-annotations
272 This function returns a list of all annotations in all buffers in
276 File: lispref.info, Node: Margin Primitives, Next: Locating Annotations, Prev: Annotation Properties, Up: Annotations
281 The margin widths are controllable on a buffer-local, window-local,
282 frame-local, device-local, or device-type-local basis through the use
283 of specifiers. *Note Specifiers::.
285 - Specifier: left-margin-width
286 This is a specifier variable controlling the width of the left
287 outside margin, in characters. Use `set-specifier' to change its
290 - Specifier: right-margin-width
291 This is a specifier variable controlling the width of the right
292 outside margin, in characters. Use `set-specifier' to change its
295 - Specifier: use-left-overflow
296 If non-`nil', use the left outside margin as extra whitespace when
297 displaying `whitespace' and `inside-margin' annotations. Defaults
298 to `nil'. This is a specifier variable; use `set-specifier' to
301 - Specifier: use-right-overflow
302 If non-`nil', use the right outside margin as extra whitespace when
303 displaying `whitespace' and `inside-margin' annotations. Defaults
304 to `nil'. This is a specifier variable; use `set-specifier' to
307 - Function: window-left-margin-pixel-width &optional window
308 This function returns the width in pixels of the left outside
309 margin of WINDOW. If WINDOW is `nil', the selected window is
312 - Function: window-right-margin-pixel-width &optional window
313 This function returns the width in pixels of the right outside
314 margin of WINDOW. If WINDOW is `nil', the selected window is
317 The margin colors are controlled by the faces `left-margin' and
318 `right-margin'. These can be set using the X resources
319 `Emacs.left-margin.background' and `Emacs.left-margin.foreground';
320 likewise for the right margin.
323 File: lispref.info, Node: Annotation Hooks, Prev: Locating Annotations, Up: Annotations
328 The following three hooks are provided for use with the marginal
331 `before-delete-annotation-hook'
332 This hook is called immediately before an annotation is destroyed.
333 It is passed a single argument, the annotation being destroyed.
335 `after-delete-annotation-hook'
336 This normal hook is called immediately after an annotation is
339 `make-annotation-hook'
340 This hook is called immediately after an annotation is created.
341 It is passed a single argument, the newly created annotation.
344 File: lispref.info, Node: Display, Next: Hash Tables, Prev: Annotations, Up: Top
349 This chapter describes a number of other features related to the
350 display that XEmacs presents to the user.
354 * Refresh Screen:: Clearing the screen and redrawing everything on it.
355 * Truncation:: Folding or wrapping long text lines.
356 * The Echo Area:: Where messages are displayed.
357 * Warnings:: Display of Warnings.
358 * Invisible Text:: Hiding part of the buffer text.
359 * Selective Display:: Hiding part of the buffer text (the old way).
360 * Overlay Arrow:: Display of an arrow to indicate position.
361 * Temporary Displays:: Displays that go away automatically.
362 * Blinking:: How XEmacs shows the matching open parenthesis.
363 * Usual Display:: The usual conventions for displaying nonprinting chars.
364 * Display Tables:: How to specify other conventions.
365 * Beeping:: Audible signal to the user.
368 File: lispref.info, Node: Refresh Screen, Next: Truncation, Up: Display
370 Refreshing the Screen
371 =====================
373 The function `redraw-frame' redisplays the entire contents of a
374 given frame. *Note Frames::.
376 - Function: redraw-frame &optional frame no-preempt
377 This function clears and redisplays frame FRAME.
379 FRAME defaults to the selected frame if omitted.
381 Normally, redisplay is preempted as normal if input arrives.
382 However, if optional second arg NO-PREEMPT is non-`nil', redisplay
383 will not stop for input and is guaranteed to proceed to completion.
385 Even more powerful is `redraw-display':
387 - Command: redraw-display &optional device
388 This function redraws all frames on DEVICE marked as having their
389 image garbled. DEVICE defaults to the selected device. If DEVICE
390 is `t', all devices will have their frames checked.
392 Processing user input takes absolute priority over redisplay. If you
393 call these functions when input is available, they do nothing
394 immediately, but a full redisplay does happen eventually--after all the
395 input has been processed.
397 Normally, suspending and resuming XEmacs also refreshes the screen.
398 Some terminal emulators record separate contents for display-oriented
399 programs such as XEmacs and for ordinary sequential display. If you are
400 using such a terminal, you might want to inhibit the redisplay on
401 resumption. *Note Suspending XEmacs::.
403 - Variable: no-redraw-on-reenter
404 This variable controls whether XEmacs redraws the entire screen
405 after it has been suspended and resumed. Non-`nil' means yes,
408 The above functions do not actually cause the display to be updated;
409 rather, they clear out the internal display records that XEmacs
410 maintains, so that the next time the display is updated it will be
411 redrawn from scratch. Normally this occurs the next time that
412 `next-event' or `sit-for' is called; however, a display update will not
413 occur if there is input pending. *Note Command Loop::.
415 - Function: force-cursor-redisplay &optional frame
416 This function causes an immediate update of the cursor on FRAME,
417 which defaults to the selected frame.
420 File: lispref.info, Node: Truncation, Next: The Echo Area, Prev: Refresh Screen, Up: Display
425 When a line of text extends beyond the right edge of a window, the
426 line can either be truncated or continued on the next line. When a line
427 is truncated, this is normally shown with a `\' in the rightmost column
428 of the window on X displays, and with a `$' on TTY devices. When a
429 line is continued or "wrapped" onto the next line, this is shown with a
430 curved arrow in the rightmost column of the window (or with a `\' on
431 TTY devices). The additional screen lines used to display a long text
432 line are called "continuation" lines.
434 Normally, whenever line truncation is in effect for a particular
435 window, a horizontal scrollbar is displayed in that window if the
436 device supports scrollbars. *Note Scrollbars::.
438 Note that continuation is different from filling; continuation
439 happens on the screen only, not in the buffer contents, and it breaks a
440 line precisely at the right margin, not at a word boundary. *Note
443 - User Option: truncate-lines
444 This buffer-local variable controls how XEmacs displays lines that
445 extend beyond the right edge of the window. If it is non-`nil',
446 then XEmacs does not display continuation lines; rather each line
447 of text occupies exactly one screen line, and a backslash appears
448 at the edge of any line that extends to or beyond the edge of the
449 window. The default is `nil'.
451 If the variable `truncate-partial-width-windows' is non-`nil',
452 then truncation is always used for side-by-side windows (within one
453 frame) regardless of the value of `truncate-lines'.
455 - User Option: default-truncate-lines
456 This variable is the default value for `truncate-lines', for
457 buffers that do not have local values for it.
459 - User Option: truncate-partial-width-windows
460 This variable controls display of lines that extend beyond the
461 right edge of the window, in side-by-side windows (*note Splitting
462 Windows::). If it is non-`nil', these lines are truncated;
463 otherwise, `truncate-lines' says what to do with them.
465 The backslash and curved arrow used to indicate truncated or
466 continued lines are only defaults, and can be changed. These images
467 are actually glyphs (*note Glyphs::). XEmacs provides a great deal of
468 flexibility in how glyphs can be controlled. (This differs from FSF
469 Emacs, which uses display tables to control these images.)
471 For details, *Note Redisplay Glyphs::.
474 File: lispref.info, Node: The Echo Area, Next: Warnings, Prev: Truncation, Up: Display
479 The "echo area" is used for displaying messages made with the
480 `message' primitive, and for echoing keystrokes. It is not the same as
481 the minibuffer, despite the fact that the minibuffer appears (when
482 active) in the same place on the screen as the echo area. The `XEmacs
483 Lisp Reference Manual' specifies the rules for resolving conflicts
484 between the echo area and the minibuffer for use of that screen space
485 (*note The Minibuffer: (xemacs)Minibuffer.). Error messages appear in
486 the echo area; see *Note Errors::.
488 You can write output in the echo area by using the Lisp printing
489 functions with `t' as the stream (*note Output Functions::), or as
492 - Function: message string &rest arguments
493 This function displays a one-line message in the echo area. The
494 argument STRING is similar to a C language `printf' control
495 string. See `format' in *Note String Conversion::, for the details
496 on the conversion specifications. `message' returns the
499 In batch mode, `message' prints the message text on the standard
500 error stream, followed by a newline.
502 If STRING is `nil', `message' clears the echo area. If the
503 minibuffer is active, this brings the minibuffer contents back onto
504 the screen immediately.
506 (message "Minibuffer depth is %d."
508 -| Minibuffer depth is 0.
509 => "Minibuffer depth is 0."
511 ---------- Echo Area ----------
512 Minibuffer depth is 0.
513 ---------- Echo Area ----------
515 In addition to only displaying a message, XEmacs allows you to
516 "label" your messages, giving you fine-grained control of their
517 display. Message label is a symbol denoting the message type. Some
520 * `message'--default label used by the `message' function;
522 * `error'--default label used for reporting errors;
524 * `progress'--progress indicators like `Converting... 45%' (not
527 * `prompt'--prompt-like messages like `Isearch: foo' (not logged by
530 * `command'--helper command messages like `Mark set' (not logged by
533 * `no-log'--messages that should never be logged
535 Several messages may be stacked in the echo area at once. Lisp
536 programs may access these messages, or remove them as appropriate, via
539 - Function: display-message label message &optional frame stdout-p
540 This function displays MESSAGE (a string) labeled as LABEL, as
543 The FRAME argument specifies the frame to whose minibuffer the
544 message should be printed. This is currently unimplemented. The
545 STDOUT-P argument is used internally.
547 (display-message 'command "Mark set")
549 - Function: lmessage label string &rest arguments
550 This function displays a message STRING with label LABEL. It is
551 similar to `message' in that it accepts a `printf'-like strings
552 and any number of arguments.
554 ;; Display a command message.
555 (lmessage 'command "Comment column set to %d" comment-column)
557 ;; Display a progress message.
558 (lmessage 'progress "Fontifying %s... (%d)" buffer percentage)
560 ;; Display a message that should not be logged.
561 (lmessage 'no-log "Done")
563 - Function: clear-message &optional label frame stdout-p no-restore
564 This function remove any message with the given LABEL from the
565 message-stack, erasing it from the echo area if it's currently
568 If a message remains at the head of the message-stack and
569 NO-RESTORE is `nil', it will be displayed. The string which
570 remains in the echo area will be returned, or `nil' if the
571 message-stack is now empty. If LABEL is `nil', the entire
572 message-stack is cleared.
574 ;; Show a message, wait for 2 seconds, and restore old minibuffer
576 (message "A message")
579 (lmessage 'my-label "Newsflash! Newsflash!")
580 -| Newsflash! Newsflash!
581 => "Newsflash! Newsflash!"
583 (clear-message 'my-label)
587 Unless you need the return value or you need to specify a label,
588 you should just use `(message nil)'.
590 - Function: current-message &optional frame
591 This function returns the current message in the echo area, or
592 `nil'. The FRAME argument is currently unused.
594 Some of the messages displayed in the echo area are also recorded in
595 the ` *Message-Log*' buffer. Exactly which messages will be recorded
596 can be tuned using the following variables.
598 - User Option: log-message-max-size
599 This variable specifies the maximum size of the ` *Message-log*'
602 - Variable: log-message-ignore-labels
603 This variable specifies the labels whose messages will not be
604 logged. It should be a list of symbols.
606 - Variable: log-message-ignore-regexps
607 This variable specifies the regular expressions matching messages
608 that will not be logged. It should be a list of regular
611 Normally, packages that generate messages that might need to be
612 ignored should label them with `progress', `prompt', or `no-log',
613 so they can be filtered by `log-message-ignore-labels'.
615 - Variable: echo-keystrokes
616 This variable determines how much time should elapse before command
617 characters echo. Its value must be a number, which specifies the
618 number of seconds to wait before echoing. If the user types a
619 prefix key (such as `C-x') and then delays this many seconds
620 before continuing, the prefix key is echoed in the echo area. Any
621 subsequent characters in the same command will be echoed as well.
623 If the value is zero, then command input is not echoed.
625 - Variable: cursor-in-echo-area
626 This variable controls where the cursor appears when a message is
627 displayed in the echo area. If it is non-`nil', then the cursor
628 appears at the end of the message. Otherwise, the cursor appears
629 at point--not in the echo area at all.
631 The value is normally `nil'; Lisp programs bind it to `t' for
632 brief periods of time.
635 File: lispref.info, Node: Warnings, Next: Invisible Text, Prev: The Echo Area, Up: Display
640 XEmacs contains a facility for unified display of various warnings.
641 Unlike errors, warnings are displayed in the situations when XEmacs
642 encounters a problem that is recoverable, but which should be fixed for
643 safe future operation.
645 For example, warnings are printed by the startup code when it
646 encounters problems with X keysyms, when there is an error in `.emacs',
647 and in other problematic situations. Unlike messages, warnings are
648 displayed in a separate buffer, and include an explanatory message that
649 may span across several lines. Here is an example of how a warning is
652 (1) (initialization/error) An error has occurred while loading ~/.emacs:
654 Symbol's value as variable is void: bogus-variable
656 To ensure normal operation, you should investigate the cause of the error
657 in your initialization file and remove it. Use the `-debug-init' option
658 to XEmacs to view a complete error backtrace.
660 Each warning has a "class" and a "priority level". The class is a
661 symbol describing what sort of warning this is, such as
662 `initialization', `resource' or `key-mapping'.
664 The warning priority level specifies how important the warning is.
665 The recognized warning levels, in increased order of priority, are:
666 `debug', `info', `notice', `warning', `error', `critical', `alert' and
669 - Function: display-warning class message &optional level
670 This function displays a warning message MESSAGE (a string).
671 CLASS should be a warning class symbol, as described above, or a
672 list of such symbols. LEVEL describes the warning priority level.
673 If unspecified, it default to `warning'.
675 (display-warning 'resource
676 "Bad resource specification encountered:
681 You should replace the * with a . in order to get proper behavior when
682 you use the specifier and/or `set-face-*' functions.")
684 ---------- Warning buffer ----------
685 (1) (resource/warning) Bad resource specification encountered:
690 You should replace the * with a . in order to get proper behavior when
691 you use the specifier and/or `set-face-*' functions.
692 ---------- Warning buffer ----------
694 - Function: lwarn class level message &rest args
695 This function displays a formatted labeled warning message. As
696 above, CLASS should be the warning class symbol, or a list of such
697 symbols, and LEVEL should specify the warning priority level
698 (`warning' by default).
700 Unlike in `display-warning', MESSAGE may be a formatted message,
701 which will be, together with the rest of the arguments, passed to
704 (lwarn 'message-log 'warning
705 "Error caught in `remove-message-hook': %s"
706 (error-message-string e))
708 - Variable: log-warning-minimum-level
709 This variable specifies the minimum level of warnings that should
710 be generated. Warnings with level lower than defined by this
711 variable are completely ignored, as if they never happened.
713 - Variable: display-warning-minimum-level
714 This variable specifies the minimum level of warnings that should
715 be displayed. Unlike `log-warning-minimum-level', setting this
716 function does not suppress warnings entirely--they are still
717 generated in the `*Warnings*' buffer, only they are not displayed
720 - Variable: log-warning-suppressed-classes
721 This variable specifies a list of classes that should not be
722 logged or displayed. If any of the class symbols associated with
723 a warning is the same as any of the symbols listed here, the
724 warning will be completely ignored, as it they never happened.
726 - Variable: display-warning-suppressed-classes
727 This variable specifies a list of classes that should not be
728 logged or displayed. If any of the class symbols associated with
729 a warning is the same as any of the symbols listed here, the
730 warning will not be displayed. The warning will still logged in
731 the *Warnings* buffer (unless also contained in
732 `log-warning-suppressed-classes'), but the buffer will not be
733 automatically popped up.
736 File: lispref.info, Node: Invisible Text, Next: Selective Display, Prev: Warnings, Up: Display
741 You can make characters "invisible", so that they do not appear on
742 the screen, with the `invisible' property. This can be either a text
743 property or a property of an overlay.
745 In the simplest case, any non-`nil' `invisible' property makes a
746 character invisible. This is the default case--if you don't alter the
747 default value of `buffer-invisibility-spec', this is how the
748 `invisibility' property works. This feature is much like selective
749 display (*note Selective Display::), but more general and cleaner.
751 More generally, you can use the variable `buffer-invisibility-spec'
752 to control which values of the `invisible' property make text
753 invisible. This permits you to classify the text into different subsets
754 in advance, by giving them different `invisible' values, and
755 subsequently make various subsets visible or invisible by changing the
756 value of `buffer-invisibility-spec'.
758 Controlling visibility with `buffer-invisibility-spec' is especially
759 useful in a program to display the list of entries in a data base. It
760 permits the implementation of convenient filtering commands to view
761 just a part of the entries in the data base. Setting this variable is
762 very fast, much faster than scanning all the text in the buffer looking
763 for properties to change.
765 - Variable: buffer-invisibility-spec
766 This variable specifies which kinds of `invisible' properties
767 actually make a character invisible.
770 A character is invisible if its `invisible' property is
771 non-`nil'. This is the default.
774 Each element of the list makes certain characters invisible.
775 Ultimately, a character is invisible if any of the elements
776 of this list applies to it. The list can have two kinds of
780 A character is invisible if its `invisible' property
781 value is ATOM or if it is a list with ATOM as a member.
784 A character is invisible if its `invisible' property
785 value is ATOM or if it is a list with ATOM as a member.
786 Moreover, if this character is at the end of a line and
787 is followed by a visible newline, it displays an
790 Ordinarily, commands that operate on text or move point do not care
791 whether the text is invisible. However, the user-level line motion
792 commands explicitly ignore invisible newlines.
795 File: lispref.info, Node: Selective Display, Next: Overlay Arrow, Prev: Invisible Text, Up: Display
800 "Selective display" is a pair of features that hide certain lines on
803 The first variant, explicit selective display, is designed for use in
804 a Lisp program. The program controls which lines are hidden by altering
805 the text. Outline mode has traditionally used this variant. It has
806 been partially replaced by the invisible text feature (*note Invisible
807 Text::); there is a new version of Outline mode which uses that instead.
809 In the second variant, the choice of lines to hide is made
810 automatically based on indentation. This variant is designed to be a
813 The way you control explicit selective display is by replacing a
814 newline (control-j) with a carriage return (control-m). The text that
815 was formerly a line following that newline is now invisible. Strictly
816 speaking, it is temporarily no longer a line at all, since only newlines
817 can separate lines; it is now part of the previous line.
819 Selective display does not directly affect editing commands. For
820 example, `C-f' (`forward-char') moves point unhesitatingly into
821 invisible text. However, the replacement of newline characters with
822 carriage return characters affects some editing commands. For example,
823 `next-line' skips invisible lines, since it searches only for newlines.
824 Modes that use selective display can also define commands that take
825 account of the newlines, or that make parts of the text visible or
828 When you write a selectively displayed buffer into a file, all the
829 control-m's are output as newlines. This means that when you next read
830 in the file, it looks OK, with nothing invisible. The selective display
831 effect is seen only within XEmacs.
833 - Variable: selective-display
834 This buffer-local variable enables selective display. This means
835 that lines, or portions of lines, may be made invisible.
837 * If the value of `selective-display' is `t', then any portion
838 of a line that follows a control-m is not displayed.
840 * If the value of `selective-display' is a positive integer,
841 then lines that start with more than that many columns of
842 indentation are not displayed.
844 When some portion of a buffer is invisible, the vertical movement
845 commands operate as if that portion did not exist, allowing a
846 single `next-line' command to skip any number of invisible lines.
847 However, character movement commands (such as `forward-char') do
848 not skip the invisible portion, and it is possible (if tricky) to
849 insert or delete text in an invisible portion.
851 In the examples below, we show the _display appearance_ of the
852 buffer `foo', which changes with the value of `selective-display'.
853 The _contents_ of the buffer do not change.
855 (setq selective-display nil)
858 ---------- Buffer: foo ----------
865 ---------- Buffer: foo ----------
867 (setq selective-display 2)
870 ---------- Buffer: foo ----------
875 ---------- Buffer: foo ----------
877 - Variable: selective-display-ellipses
878 If this buffer-local variable is non-`nil', then XEmacs displays
879 `...' at the end of a line that is followed by invisible text.
880 This example is a continuation of the previous one.
882 (setq selective-display-ellipses t)
885 ---------- Buffer: foo ----------
890 ---------- Buffer: foo ----------
892 You can use a display table to substitute other text for the
893 ellipsis (`...'). *Note Display Tables::.
896 File: lispref.info, Node: Overlay Arrow, Next: Temporary Displays, Prev: Selective Display, Up: Display
901 The "overlay arrow" is useful for directing the user's attention to
902 a particular line in a buffer. For example, in the modes used for
903 interface to debuggers, the overlay arrow indicates the line of code
904 about to be executed.
906 - Variable: overlay-arrow-string
907 This variable holds the string to display to call attention to a
908 particular line, or `nil' if the arrow feature is not in use.
909 Despite its name, the value of this variable can be either a string
910 or a glyph (*note Glyphs::).
912 - Variable: overlay-arrow-position
913 This variable holds a marker that indicates where to display the
914 overlay arrow. It should point at the beginning of a line. The
915 arrow text appears at the beginning of that line, overlaying any
916 text that would otherwise appear. Since the arrow is usually
917 short, and the line usually begins with indentation, normally
918 nothing significant is overwritten.
920 The overlay string is displayed only in the buffer that this marker
921 points into. Thus, only one buffer can have an overlay arrow at
924 You can do the same job by creating an extent with a `begin-glyph'
925 property. *Note Extent Properties::.
928 File: lispref.info, Node: Temporary Displays, Next: Blinking, Prev: Overlay Arrow, Up: Display
933 Temporary displays are used by commands to put output into a buffer
934 and then present it to the user for perusal rather than for editing.
935 Many of the help commands use this feature.
937 - Special Form: with-output-to-temp-buffer buffer-name forms...
938 This function executes FORMS while arranging to insert any output
939 they print into the buffer named BUFFER-NAME. The buffer is then
940 shown in some window for viewing, displayed but not selected.
942 The string BUFFER-NAME specifies the temporary buffer, which need
943 not already exist. The argument must be a string, not a buffer.
944 The buffer is erased initially (with no questions asked), and it is
945 marked as unmodified after `with-output-to-temp-buffer' exits.
947 `with-output-to-temp-buffer' binds `standard-output' to the
948 temporary buffer, then it evaluates the forms in FORMS. Output
949 using the Lisp output functions within FORMS goes by default to
950 that buffer (but screen display and messages in the echo area,
951 although they are "output" in the general sense of the word, are
952 not affected). *Note Output Functions::.
954 The value of the last form in FORMS is returned.
956 ---------- Buffer: foo ----------
957 This is the contents of foo.
958 ---------- Buffer: foo ----------
960 (with-output-to-temp-buffer "foo"
962 (print standard-output))
965 ---------- Buffer: foo ----------
970 ---------- Buffer: foo ----------
972 - Variable: temp-buffer-show-function
973 If this variable is non-`nil', `with-output-to-temp-buffer' calls
974 it as a function to do the job of displaying a help buffer. The
975 function gets one argument, which is the buffer it should display.
977 In Emacs versions 18 and earlier, this variable was called
978 `temp-buffer-show-hook'.
980 - Function: momentary-string-display string position &optional char
982 This function momentarily displays STRING in the current buffer at
983 POSITION. It has no effect on the undo list or on the buffer's
986 The momentary display remains until the next input event. If the
987 next input event is CHAR, `momentary-string-display' ignores it
988 and returns. Otherwise, that event remains buffered for
989 subsequent use as input. Thus, typing CHAR will simply remove the
990 string from the display, while typing (say) `C-f' will remove the
991 string from the display and later (presumably) move point forward.
992 The argument CHAR is a space by default.
994 The return value of `momentary-string-display' is not meaningful.
996 You can do the same job in a more general way by creating an extent
997 with a begin-glyph property. *Note Extent Properties::.
999 If MESSAGE is non-`nil', it is displayed in the echo area while
1000 STRING is displayed in the buffer. If it is `nil', a default
1001 message says to type CHAR to continue.
1003 In this example, point is initially located at the beginning of the
1006 ---------- Buffer: foo ----------
1007 This is the contents of foo.
1009 ---------- Buffer: foo ----------
1011 (momentary-string-display
1012 "**** Important Message! ****"
1014 "Type RET when done reading")
1017 ---------- Buffer: foo ----------
1018 This is the contents of foo.
1019 **** Important Message! ****Second line.
1020 ---------- Buffer: foo ----------
1022 ---------- Echo Area ----------
1023 Type RET when done reading
1024 ---------- Echo Area ----------
1026 This function works by actually changing the text in the buffer.
1027 As a result, if you later undo in this buffer, you will see the
1028 message come and go.
1031 File: lispref.info, Node: Blinking, Next: Usual Display, Prev: Temporary Displays, Up: Display
1033 Blinking Parentheses
1034 ====================
1036 This section describes the mechanism by which XEmacs shows a matching
1037 open parenthesis when the user inserts a close parenthesis.
1039 - Variable: blink-paren-function
1040 The value of this variable should be a function (of no arguments)
1041 to be called whenever a character with close parenthesis syntax is
1042 inserted. The value of `blink-paren-function' may be `nil', in
1043 which case nothing is done.
1045 *Please note:* This variable was named `blink-paren-hook' in
1046 older Emacs versions, but since it is not called with the
1047 standard convention for hooks, it was renamed to
1048 `blink-paren-function' in version 19.
1050 - Variable: blink-matching-paren
1051 If this variable is `nil', then `blink-matching-open' does nothing.
1053 - Variable: blink-matching-paren-distance
1054 This variable specifies the maximum distance to scan for a matching
1055 parenthesis before giving up.
1057 - Variable: blink-matching-paren-delay
1058 This variable specifies the number of seconds for the cursor to
1059 remain at the matching parenthesis. A fraction of a second often
1060 gives good results, but the default is 1, which works on all
1063 - Command: blink-matching-open
1064 This function is the default value of `blink-paren-function'. It
1065 assumes that point follows a character with close parenthesis
1066 syntax and moves the cursor momentarily to the matching opening
1067 character. If that character is not already on the screen, it
1068 displays the character's context in the echo area. To avoid long
1069 delays, this function does not search farther than
1070 `blink-matching-paren-distance' characters.
1072 Here is an example of calling this function explicitly.
1074 (defun interactive-blink-matching-open ()
1075 "Indicate momentarily the start of sexp before point."
1077 (let ((blink-matching-paren-distance
1079 (blink-matching-paren t))
1080 (blink-matching-open)))
1083 File: lispref.info, Node: Usual Display, Next: Display Tables, Prev: Blinking, Up: Display
1085 Usual Display Conventions
1086 =========================
1088 The usual display conventions define how to display each character
1089 code. You can override these conventions by setting up a display table
1090 (*note Display Tables::). Here are the usual display conventions:
1092 * Character codes 32 through 126 map to glyph codes 32 through 126.
1093 Normally this means they display as themselves.
1095 * Character code 9 is a horizontal tab. It displays as whitespace
1096 up to a position determined by `tab-width'.
1098 * Character code 10 is a newline.
1100 * All other codes in the range 0 through 31, and code 127, display
1101 in one of two ways according to the value of `ctl-arrow'. If it is
1102 non-`nil', these codes map to sequences of two glyphs, where the
1103 first glyph is the ASCII code for `^'. (A display table can
1104 specify a glyph to use instead of `^'.) Otherwise, these codes map
1105 just like the codes in the range 128 to 255.
1107 * Character codes 128 through 255 map to sequences of four glyphs,
1108 where the first glyph is the ASCII code for `\', and the others are
1109 digit characters representing the code in octal. (A display table
1110 can specify a glyph to use instead of `\'.)
1112 The usual display conventions apply even when there is a display
1113 table, for any character whose entry in the active display table is
1114 `nil'. Thus, when you set up a display table, you need only specify
1115 the characters for which you want unusual behavior.
1117 These variables affect the way certain characters are displayed on
1118 the screen. Since they change the number of columns the characters
1119 occupy, they also affect the indentation functions.
1121 - User Option: ctl-arrow
1122 This buffer-local variable controls how control characters are
1123 displayed. If it is non-`nil', they are displayed as a caret
1124 followed by the character: `^A'. If it is `nil', they are
1125 displayed as a backslash followed by three octal digits: `\001'.
1127 - Variable: default-ctl-arrow
1128 The value of this variable is the default value for `ctl-arrow' in
1129 buffers that do not override it. *Note Default Value::.
1131 - User Option: tab-width
1132 The value of this variable is the spacing between tab stops used
1133 for displaying tab characters in Emacs buffers. The default is 8.
1134 Note that this feature is completely independent from the
1135 user-settable tab stops used by the command `tab-to-tab-stop'.
1136 *Note Indent Tabs::.
1139 File: lispref.info, Node: Display Tables, Next: Beeping, Prev: Usual Display, Up: Display
1144 You can use the "display table" feature to control how all 256
1145 possible character codes display on the screen. This is useful for
1146 displaying European languages that have letters not in the ASCII
1149 The display table maps each character code into a sequence of
1150 "runes", each rune being an image that takes up one character position
1151 on the screen. You can also define how to display each rune on your
1152 terminal, using the "rune table".
1156 * Display Table Format:: What a display table consists of.
1157 * Active Display Table:: How XEmacs selects a display table to use.
1158 * Character Descriptors:: Format of an individual element of a
1162 File: lispref.info, Node: Display Table Format, Next: Active Display Table, Up: Display Tables
1164 Display Table Format
1165 --------------------
1167 A display table is an array of 256 elements. (In FSF Emacs, a display
1168 table is 262 elements. The six extra elements specify the truncation
1169 and continuation glyphs, etc. This method is very kludgey, and in
1170 XEmacs the variables `truncation-glyph', `continuation-glyph', etc. are
1171 used. *Note Truncation::.)
1173 - Function: make-display-table
1174 This creates and returns a display table. The table initially has
1175 `nil' in all elements.
1177 The 256 elements correspond to character codes; the Nth element says
1178 how to display the character code N. The value should be `nil', a
1179 string, a glyph, or a vector of strings and glyphs (*note Character
1180 Descriptors::). If an element is `nil', it says to display that
1181 character according to the usual display conventions (*note Usual
1184 If you use the display table to change the display of newline
1185 characters, the whole buffer will be displayed as one long "line."
1187 For example, here is how to construct a display table that mimics the
1188 effect of setting `ctl-arrow' to a non-`nil' value:
1190 (setq disptab (make-display-table))
1193 (or (= i ?\t) (= i ?\n)
1194 (aset disptab i (concat "^" (char-to-string (+ i 64)))))
1196 (aset disptab 127 "^?"))
projects / chise / xemacs-chise.git / blob