1 This is ../info/lispref.info, produced by makeinfo version 4.0 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 POS 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 POS 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 frame
377 This function clears and redisplays frame FRAME.
379 Even more powerful is `redraw-display':
381 - Command: redraw-display &optional device
382 This function redraws all frames on DEVICE marked as having their
383 image garbled. DEVICE defaults to the selected device. If DEVICE
384 is `t', all devices will have their frames checked.
386 Processing user input takes absolute priority over redisplay. If you
387 call these functions when input is available, they do nothing
388 immediately, but a full redisplay does happen eventually--after all the
389 input has been processed.
391 Normally, suspending and resuming XEmacs also refreshes the screen.
392 Some terminal emulators record separate contents for display-oriented
393 programs such as XEmacs and for ordinary sequential display. If you are
394 using such a terminal, you might want to inhibit the redisplay on
395 resumption. *Note Suspending XEmacs::.
397 - Variable: no-redraw-on-reenter
398 This variable controls whether XEmacs redraws the entire screen
399 after it has been suspended and resumed. Non-`nil' means yes,
402 The above functions do not actually cause the display to be updated;
403 rather, they clear out the internal display records that XEmacs
404 maintains, so that the next time the display is updated it will be
405 redrawn from scratch. Normally this occurs the next time that
406 `next-event' or `sit-for' is called; however, a display update will not
407 occur if there is input pending. *Note Command Loop::.
409 - Function: force-cursor-redisplay
410 This function causes an immediate update of the cursor on the
411 selected frame. (This function does not exist in FSF Emacs.)
414 File: lispref.info, Node: Truncation, Next: The Echo Area, Prev: Refresh Screen, Up: Display
419 When a line of text extends beyond the right edge of a window, the
420 line can either be truncated or continued on the next line. When a line
421 is truncated, this is normally shown with a `\' in the rightmost column
422 of the window on X displays, and with a `$' on TTY devices. When a
423 line is continued or "wrapped" onto the next line, this is shown with a
424 curved arrow in the rightmost column of the window (or with a `\' on
425 TTY devices). The additional screen lines used to display a long text
426 line are called "continuation" lines.
428 Normally, whenever line truncation is in effect for a particular
429 window, a horizontal scrollbar is displayed in that window if the
430 device supports scrollbars. *Note Scrollbars::.
432 Note that continuation is different from filling; continuation
433 happens on the screen only, not in the buffer contents, and it breaks a
434 line precisely at the right margin, not at a word boundary. *Note
437 - User Option: truncate-lines
438 This buffer-local variable controls how XEmacs displays lines that
439 extend beyond the right edge of the window. If it is non-`nil',
440 then XEmacs does not display continuation lines; rather each line
441 of text occupies exactly one screen line, and a backslash appears
442 at the edge of any line that extends to or beyond the edge of the
443 window. The default is `nil'.
445 If the variable `truncate-partial-width-windows' is non-`nil',
446 then truncation is always used for side-by-side windows (within one
447 frame) regardless of the value of `truncate-lines'.
449 - User Option: default-truncate-lines
450 This variable is the default value for `truncate-lines', for
451 buffers that do not have local values for it.
453 - User Option: truncate-partial-width-windows
454 This variable controls display of lines that extend beyond the
455 right edge of the window, in side-by-side windows (*note Splitting
456 Windows::). If it is non-`nil', these lines are truncated;
457 otherwise, `truncate-lines' says what to do with them.
459 The backslash and curved arrow used to indicate truncated or
460 continued lines are only defaults, and can be changed. These images
461 are actually glyphs (*note Glyphs::). XEmacs provides a great deal of
462 flexibility in how glyphs can be controlled. (This differs from FSF
463 Emacs, which uses display tables to control these images.)
465 For details, *Note Redisplay Glyphs::.
468 File: lispref.info, Node: The Echo Area, Next: Warnings, Prev: Truncation, Up: Display
473 The "echo area" is used for displaying messages made with the
474 `message' primitive, and for echoing keystrokes. It is not the same as
475 the minibuffer, despite the fact that the minibuffer appears (when
476 active) in the same place on the screen as the echo area. The `XEmacs
477 Reference Manual' specifies the rules for resolving conflicts between
478 the echo area and the minibuffer for use of that screen space (*note
479 The Minibuffer: (emacs)Minibuffer.). Error messages appear in the echo
480 area; see *Note Errors::.
482 You can write output in the echo area by using the Lisp printing
483 functions with `t' as the stream (*note Output Functions::), or as
486 - Function: message string &rest arguments
487 This function displays a one-line message in the echo area. The
488 argument STRING is similar to a C language `printf' control
489 string. See `format' in *Note String Conversion::, for the details
490 on the conversion specifications. `message' returns the
493 In batch mode, `message' prints the message text on the standard
494 error stream, followed by a newline.
496 If STRING is `nil', `message' clears the echo area. If the
497 minibuffer is active, this brings the minibuffer contents back onto
498 the screen immediately.
500 (message "Minibuffer depth is %d."
502 -| Minibuffer depth is 0.
503 => "Minibuffer depth is 0."
505 ---------- Echo Area ----------
506 Minibuffer depth is 0.
507 ---------- Echo Area ----------
509 In addition to only displaying a message, XEmacs allows you to
510 "label" your messages, giving you fine-grained control of their
511 display. Message label is a symbol denoting the message type. Some
514 * `message'--default label used by the `message' function;
516 * `error'--default label used for reporting errors;
518 * `progress'--progress indicators like `Converting... 45%' (not
521 * `prompt'--prompt-like messages like `Isearch: foo' (not logged by
524 * `command'--helper command messages like `Mark set' (not logged by
527 * `no-log'--messages that should never be logged
529 Several messages may be stacked in the echo area at once. Lisp
530 programs may access these messages, or remove them as appropriate, via
533 - Function: display-message label message &optional frame stdout-p
534 This function displays MESSAGE (a string) labeled as LABEL, as
537 The FRAME argument specifies the frame to whose minibuffer the
538 message should be printed. This is currently unimplemented. The
539 STDOUT-P argument is used internally.
541 (display-message 'command "Mark set")
543 - Function: lmessage label string &rest arguments
544 This function displays a message STRING with label LABEL. It is
545 similar to `message' in that it accepts a `printf'-like strings
546 and any number of arguments.
548 ;; Display a command message.
549 (lmessage 'command "Comment column set to %d" comment-column)
551 ;; Display a progress message.
552 (lmessage 'progress "Fontifying %s... (%d)" buffer percentage)
554 ;; Display a message that should not be logged.
555 (lmessage 'no-log "Done")
557 - Function: clear-message &optional label frame stdout-p no-restore
558 This function remove any message with the given LABEL from the
559 message-stack, erasing it from the echo area if it's currently
562 If a message remains at the head of the message-stack and
563 NO-RESTORE is `nil', it will be displayed. The string which
564 remains in the echo area will be returned, or `nil' if the
565 message-stack is now empty. If LABEL is nil, the entire
566 message-stack is cleared.
568 ;; Show a message, wait for 2 seconds, and restore old minibuffer
570 (message "A message")
573 (lmessage 'my-label "Newsflash! Newsflash!")
574 -| Newsflash! Newsflash!
575 => "Newsflash! Newsflash!"
577 (clear-message 'my-label)
581 Unless you need the return value or you need to specify a label,
582 you should just use `(message nil)'.
584 - Function: current-message &optional frame
585 This function returns the current message in the echo area, or
586 `nil'. The FRAME argument is currently unused.
588 Some of the messages displayed in the echo area are also recorded in
589 the ` *Message-Log*' buffer. Exactly which messages will be recorded
590 can be tuned using the following variables.
592 - User Option: log-message-max-size
593 This variable specifies the maximum size of the ` *Message-log*'
596 - Variable: log-message-ignore-labels
597 This variable specifies the labels whose messages will not be
598 logged. It should be a list of symbols.
600 - Variable: log-message-ignore-regexps
601 This variable specifies the regular expressions matching messages
602 that will not be logged. It should be a list of regular
605 Normally, packages that generate messages that might need to be
606 ignored should label them with `progress', `prompt', or `no-log',
607 so they can be filtered by `log-message-ignore-labels'.
609 - Variable: echo-keystrokes
610 This variable determines how much time should elapse before command
611 characters echo. Its value must be a number, which specifies the
612 number of seconds to wait before echoing. If the user types a
613 prefix key (such as `C-x') and then delays this many seconds
614 before continuing, the prefix key is echoed in the echo area. Any
615 subsequent characters in the same command will be echoed as well.
617 If the value is zero, then command input is not echoed.
619 - Variable: cursor-in-echo-area
620 This variable controls where the cursor appears when a message is
621 displayed in the echo area. If it is non-`nil', then the cursor
622 appears at the end of the message. Otherwise, the cursor appears
623 at point--not in the echo area at all.
625 The value is normally `nil'; Lisp programs bind it to `t' for
626 brief periods of time.
629 File: lispref.info, Node: Warnings, Next: Invisible Text, Prev: The Echo Area, Up: Display
634 XEmacs contains a facility for unified display of various warnings.
635 Unlike errors, warnings are displayed in the situations when XEmacs
636 encounters a problem that is recoverable, but which should be fixed for
637 safe future operation.
639 For example, warnings are printed by the startup code when it
640 encounters problems with X keysyms, when there is an error in `.emacs',
641 and in other problematic situations. Unlike messages, warnings are
642 displayed in a separate buffer, and include an explanatory message that
643 may span across several lines. Here is an example of how a warning is
646 (1) (initialization/error) An error has occurred while loading ~/.emacs:
648 Symbol's value as variable is void: bogus-variable
650 To ensure normal operation, you should investigate the cause of the error
651 in your initialization file and remove it. Use the `-debug-init' option
652 to XEmacs to view a complete error backtrace.
654 Each warning has a "class" and a "priority level". The class is a
655 symbol describing what sort of warning this is, such as
656 `initialization', `resource' or `key-mapping'.
658 The warning priority level specifies how important the warning is.
659 The recognized warning levels, in increased order of priority, are:
660 `debug', `info', `notice', `warning', `error', `critical', `alert' and
663 - Function: display-warning class message &optional level
664 This function displays a warning message MESSAGE (a string).
665 CLASS should be a warning class symbol, as described above, or a
666 list of such symbols. LEVEL describes the warning priority level.
667 If unspecified, it default to `warning'.
669 (display-warning 'resource
670 "Bad resource specification encountered:
675 You should replace the * with a . in order to get proper behavior when
676 you use the specifier and/or `set-face-*' functions.")
678 ---------- Warning buffer ----------
679 (1) (resource/warning) Bad resource specification encountered:
684 You should replace the * with a . in order to get proper behavior when
685 you use the specifier and/or `set-face-*' functions.
686 ---------- Warning buffer ----------
688 - Function: lwarn class level message &rest args
689 This function displays a formatted labeled warning message. As
690 above, CLASS should be the warning class symbol, or a list of such
691 symbols, and LEVEL should specify the warning priority level
692 (`warning' by default).
694 Unlike in `display-warning', MESSAGE may be a formatted message,
695 which will be, together with the rest of the arguments, passed to
698 (lwarn 'message-log 'warning
699 "Error caught in `remove-message-hook': %s"
700 (error-message-string e))
702 - Variable: log-warning-minimum-level
703 This variable specifies the minimum level of warnings that should
704 be generated. Warnings with level lower than defined by this
705 variable are completely ignored, as if they never happened.
707 - Variable: display-warning-minimum-level
708 This variable specifies the minimum level of warnings that should
709 be displayed. Unlike `log-warning-minimum-level', setting this
710 function does not suppress warnings entirely--they are still
711 generated in the `*Warnings*' buffer, only they are not displayed
714 - Variable: log-warning-suppressed-classes
715 This variable specifies a list of classes that should not be
716 logged or displayed. If any of the class symbols associated with
717 a warning is the same as any of the symbols listed here, the
718 warning will be completely ignored, as it they never happened.
720 - Variable: display-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 not be displayed. The warning will still logged in
725 the *Warnings* buffer (unless also contained in
726 `log-warning-suppressed-classes'), but the buffer will not be
727 automatically popped up.
730 File: lispref.info, Node: Invisible Text, Next: Selective Display, Prev: Warnings, Up: Display
735 You can make characters "invisible", so that they do not appear on
736 the screen, with the `invisible' property. This can be either a text
737 property or a property of an overlay.
739 In the simplest case, any non-`nil' `invisible' property makes a
740 character invisible. This is the default case--if you don't alter the
741 default value of `buffer-invisibility-spec', this is how the
742 `invisibility' property works. This feature is much like selective
743 display (*note Selective Display::), but more general and cleaner.
745 More generally, you can use the variable `buffer-invisibility-spec'
746 to control which values of the `invisible' property make text
747 invisible. This permits you to classify the text into different subsets
748 in advance, by giving them different `invisible' values, and
749 subsequently make various subsets visible or invisible by changing the
750 value of `buffer-invisibility-spec'.
752 Controlling visibility with `buffer-invisibility-spec' is especially
753 useful in a program to display the list of entries in a data base. It
754 permits the implementation of convenient filtering commands to view
755 just a part of the entries in the data base. Setting this variable is
756 very fast, much faster than scanning all the text in the buffer looking
757 for properties to change.
759 - Variable: buffer-invisibility-spec
760 This variable specifies which kinds of `invisible' properties
761 actually make a character invisible.
764 A character is invisible if its `invisible' property is
765 non-`nil'. This is the default.
768 Each element of the list makes certain characters invisible.
769 Ultimately, a character is invisible if any of the elements
770 of this list applies to it. The list can have two kinds of
774 A character is invisible if its `invisible' property
775 value is ATOM or if it is a list with ATOM as a member.
778 A character is invisible if its `invisible' property
779 value is ATOM or if it is a list with ATOM as a member.
780 Moreover, if this character is at the end of a line and
781 is followed by a visible newline, it displays an
784 Ordinarily, commands that operate on text or move point do not care
785 whether the text is invisible. However, the user-level line motion
786 commands explicitly ignore invisible newlines.
789 File: lispref.info, Node: Selective Display, Next: Overlay Arrow, Prev: Invisible Text, Up: Display
794 "Selective display" is a pair of features that hide certain lines on
797 The first variant, explicit selective display, is designed for use in
798 a Lisp program. The program controls which lines are hidden by altering
799 the text. Outline mode has traditionally used this variant. It has
800 been partially replaced by the invisible text feature (*note Invisible
801 Text::); there is a new version of Outline mode which uses that instead.
803 In the second variant, the choice of lines to hide is made
804 automatically based on indentation. This variant is designed to be a
807 The way you control explicit selective display is by replacing a
808 newline (control-j) with a carriage return (control-m). The text that
809 was formerly a line following that newline is now invisible. Strictly
810 speaking, it is temporarily no longer a line at all, since only newlines
811 can separate lines; it is now part of the previous line.
813 Selective display does not directly affect editing commands. For
814 example, `C-f' (`forward-char') moves point unhesitatingly into
815 invisible text. However, the replacement of newline characters with
816 carriage return characters affects some editing commands. For example,
817 `next-line' skips invisible lines, since it searches only for newlines.
818 Modes that use selective display can also define commands that take
819 account of the newlines, or that make parts of the text visible or
822 When you write a selectively displayed buffer into a file, all the
823 control-m's are output as newlines. This means that when you next read
824 in the file, it looks OK, with nothing invisible. The selective display
825 effect is seen only within XEmacs.
827 - Variable: selective-display
828 This buffer-local variable enables selective display. This means
829 that lines, or portions of lines, may be made invisible.
831 * If the value of `selective-display' is `t', then any portion
832 of a line that follows a control-m is not displayed.
834 * If the value of `selective-display' is a positive integer,
835 then lines that start with more than that many columns of
836 indentation are not displayed.
838 When some portion of a buffer is invisible, the vertical movement
839 commands operate as if that portion did not exist, allowing a
840 single `next-line' command to skip any number of invisible lines.
841 However, character movement commands (such as `forward-char') do
842 not skip the invisible portion, and it is possible (if tricky) to
843 insert or delete text in an invisible portion.
845 In the examples below, we show the _display appearance_ of the
846 buffer `foo', which changes with the value of `selective-display'.
847 The _contents_ of the buffer do not change.
849 (setq selective-display nil)
852 ---------- Buffer: foo ----------
859 ---------- Buffer: foo ----------
861 (setq selective-display 2)
864 ---------- Buffer: foo ----------
869 ---------- Buffer: foo ----------
871 - Variable: selective-display-ellipses
872 If this buffer-local variable is non-`nil', then XEmacs displays
873 `...' at the end of a line that is followed by invisible text.
874 This example is a continuation of the previous one.
876 (setq selective-display-ellipses t)
879 ---------- Buffer: foo ----------
884 ---------- Buffer: foo ----------
886 You can use a display table to substitute other text for the
887 ellipsis (`...'). *Note Display Tables::.
890 File: lispref.info, Node: Overlay Arrow, Next: Temporary Displays, Prev: Selective Display, Up: Display
895 The "overlay arrow" is useful for directing the user's attention to
896 a particular line in a buffer. For example, in the modes used for
897 interface to debuggers, the overlay arrow indicates the line of code
898 about to be executed.
900 - Variable: overlay-arrow-string
901 This variable holds the string to display to call attention to a
902 particular line, or `nil' if the arrow feature is not in use.
903 Despite its name, the value of this variable can be either a string
904 or a glyph (*note Glyphs::).
906 - Variable: overlay-arrow-position
907 This variable holds a marker that indicates where to display the
908 overlay arrow. It should point at the beginning of a line. The
909 arrow text appears at the beginning of that line, overlaying any
910 text that would otherwise appear. Since the arrow is usually
911 short, and the line usually begins with indentation, normally
912 nothing significant is overwritten.
914 The overlay string is displayed only in the buffer that this marker
915 points into. Thus, only one buffer can have an overlay arrow at
918 You can do the same job by creating an extent with a `begin-glyph'
919 property. *Note Extent Properties::.
922 File: lispref.info, Node: Temporary Displays, Next: Blinking, Prev: Overlay Arrow, Up: Display
927 Temporary displays are used by commands to put output into a buffer
928 and then present it to the user for perusal rather than for editing.
929 Many of the help commands use this feature.
931 - Special Form: with-output-to-temp-buffer buffer-name forms...
932 This function executes FORMS while arranging to insert any output
933 they print into the buffer named BUFFER-NAME. The buffer is then
934 shown in some window for viewing, displayed but not selected.
936 The string BUFFER-NAME specifies the temporary buffer, which need
937 not already exist. The argument must be a string, not a buffer.
938 The buffer is erased initially (with no questions asked), and it is
939 marked as unmodified after `with-output-to-temp-buffer' exits.
941 `with-output-to-temp-buffer' binds `standard-output' to the
942 temporary buffer, then it evaluates the forms in FORMS. Output
943 using the Lisp output functions within FORMS goes by default to
944 that buffer (but screen display and messages in the echo area,
945 although they are "output" in the general sense of the word, are
946 not affected). *Note Output Functions::.
948 The value of the last form in FORMS is returned.
950 ---------- Buffer: foo ----------
951 This is the contents of foo.
952 ---------- Buffer: foo ----------
954 (with-output-to-temp-buffer "foo"
956 (print standard-output))
959 ---------- Buffer: foo ----------
964 ---------- Buffer: foo ----------
966 - Variable: temp-buffer-show-function
967 If this variable is non-`nil', `with-output-to-temp-buffer' calls
968 it as a function to do the job of displaying a help buffer. The
969 function gets one argument, which is the buffer it should display.
971 In Emacs versions 18 and earlier, this variable was called
972 `temp-buffer-show-hook'.
974 - Function: momentary-string-display string position &optional char
976 This function momentarily displays STRING in the current buffer at
977 POSITION. It has no effect on the undo list or on the buffer's
980 The momentary display remains until the next input event. If the
981 next input event is CHAR, `momentary-string-display' ignores it
982 and returns. Otherwise, that event remains buffered for
983 subsequent use as input. Thus, typing CHAR will simply remove the
984 string from the display, while typing (say) `C-f' will remove the
985 string from the display and later (presumably) move point forward.
986 The argument CHAR is a space by default.
988 The return value of `momentary-string-display' is not meaningful.
990 You can do the same job in a more general way by creating an extent
991 with a begin-glyph property. *Note Extent Properties::.
993 If MESSAGE is non-`nil', it is displayed in the echo area while
994 STRING is displayed in the buffer. If it is `nil', a default
995 message says to type CHAR to continue.
997 In this example, point is initially located at the beginning of the
1000 ---------- Buffer: foo ----------
1001 This is the contents of foo.
1003 ---------- Buffer: foo ----------
1005 (momentary-string-display
1006 "**** Important Message! ****"
1008 "Type RET when done reading")
1011 ---------- Buffer: foo ----------
1012 This is the contents of foo.
1013 **** Important Message! ****Second line.
1014 ---------- Buffer: foo ----------
1016 ---------- Echo Area ----------
1017 Type RET when done reading
1018 ---------- Echo Area ----------
1020 This function works by actually changing the text in the buffer.
1021 As a result, if you later undo in this buffer, you will see the
1022 message come and go.
1025 File: lispref.info, Node: Blinking, Next: Usual Display, Prev: Temporary Displays, Up: Display
1027 Blinking Parentheses
1028 ====================
1030 This section describes the mechanism by which XEmacs shows a matching
1031 open parenthesis when the user inserts a close parenthesis.
1033 - Variable: blink-paren-function
1034 The value of this variable should be a function (of no arguments)
1035 to be called whenever a character with close parenthesis syntax is
1036 inserted. The value of `blink-paren-function' may be `nil', in
1037 which case nothing is done.
1039 *Please note:* This variable was named `blink-paren-hook' in
1040 older Emacs versions, but since it is not called with the
1041 standard convention for hooks, it was renamed to
1042 `blink-paren-function' in version 19.
1044 - Variable: blink-matching-paren
1045 If this variable is `nil', then `blink-matching-open' does nothing.
1047 - Variable: blink-matching-paren-distance
1048 This variable specifies the maximum distance to scan for a matching
1049 parenthesis before giving up.
1051 - Variable: blink-matching-paren-delay
1052 This variable specifies the number of seconds for the cursor to
1053 remain at the matching parenthesis. A fraction of a second often
1054 gives good results, but the default is 1, which works on all
1057 - Function: blink-matching-open
1058 This function is the default value of `blink-paren-function'. It
1059 assumes that point follows a character with close parenthesis
1060 syntax and moves the cursor momentarily to the matching opening
1061 character. If that character is not already on the screen, it
1062 displays the character's context in the echo area. To avoid long
1063 delays, this function does not search farther than
1064 `blink-matching-paren-distance' characters.
1066 Here is an example of calling this function explicitly.
1068 (defun interactive-blink-matching-open ()
1069 "Indicate momentarily the start of sexp before point."
1071 (let ((blink-matching-paren-distance
1073 (blink-matching-paren t))
1074 (blink-matching-open)))
1077 File: lispref.info, Node: Usual Display, Next: Display Tables, Prev: Blinking, Up: Display
1079 Usual Display Conventions
1080 =========================
1082 The usual display conventions define how to display each character
1083 code. You can override these conventions by setting up a display table
1084 (*note Display Tables::). Here are the usual display conventions:
1086 * Character codes 32 through 126 map to glyph codes 32 through 126.
1087 Normally this means they display as themselves.
1089 * Character code 9 is a horizontal tab. It displays as whitespace
1090 up to a position determined by `tab-width'.
1092 * Character code 10 is a newline.
1094 * All other codes in the range 0 through 31, and code 127, display
1095 in one of two ways according to the value of `ctl-arrow'. If it is
1096 non-`nil', these codes map to sequences of two glyphs, where the
1097 first glyph is the ASCII code for `^'. (A display table can
1098 specify a glyph to use instead of `^'.) Otherwise, these codes map
1099 just like the codes in the range 128 to 255.
1101 * Character codes 128 through 255 map to sequences of four glyphs,
1102 where the first glyph is the ASCII code for `\', and the others are
1103 digit characters representing the code in octal. (A display table
1104 can specify a glyph to use instead of `\'.)
1106 The usual display conventions apply even when there is a display
1107 table, for any character whose entry in the active display table is
1108 `nil'. Thus, when you set up a display table, you need only specify
1109 the characters for which you want unusual behavior.
1111 These variables affect the way certain characters are displayed on
1112 the screen. Since they change the number of columns the characters
1113 occupy, they also affect the indentation functions.
1115 - User Option: ctl-arrow
1116 This buffer-local variable controls how control characters are
1117 displayed. If it is non-`nil', they are displayed as a caret
1118 followed by the character: `^A'. If it is `nil', they are
1119 displayed as a backslash followed by three octal digits: `\001'.
1121 - Variable: default-ctl-arrow
1122 The value of this variable is the default value for `ctl-arrow' in
1123 buffers that do not override it. *Note Default Value::.
1125 - User Option: tab-width
1126 The value of this variable is the spacing between tab stops used
1127 for displaying tab characters in Emacs buffers. The default is 8.
1128 Note that this feature is completely independent from the
1129 user-settable tab stops used by the command `tab-to-tab-stop'.
1130 *Note Indent Tabs::.
1133 File: lispref.info, Node: Display Tables, Next: Beeping, Prev: Usual Display, Up: Display
1138 You can use the "display table" feature to control how all 256
1139 possible character codes display on the screen. This is useful for
1140 displaying European languages that have letters not in the ASCII
1143 The display table maps each character code into a sequence of
1144 "runes", each rune being an image that takes up one character position
1145 on the screen. You can also define how to display each rune on your
1146 terminal, using the "rune table".
1150 * Display Table Format:: What a display table consists of.
1151 * Active Display Table:: How XEmacs selects a display table to use.
1152 * Character Descriptors:: Format of an individual element of a
1156 File: lispref.info, Node: Display Table Format, Next: Active Display Table, Up: Display Tables
1158 Display Table Format
1159 --------------------
1161 A display table is an array of 256 elements. (In FSF Emacs, a display
1162 table is 262 elements. The six extra elements specify the truncation
1163 and continuation glyphs, etc. This method is very kludgey, and in
1164 XEmacs the variables `truncation-glyph', `continuation-glyph', etc. are
1165 used. *Note Truncation::.)
1167 - Function: make-display-table
1168 This creates and returns a display table. The table initially has
1169 `nil' in all elements.
1171 The 256 elements correspond to character codes; the Nth element says
1172 how to display the character code N. The value should be `nil', a
1173 string, a glyph, or a vector of strings and glyphs (*note Character
1174 Descriptors::). If an element is `nil', it says to display that
1175 character according to the usual display conventions (*note Usual
1178 If you use the display table to change the display of newline
1179 characters, the whole buffer will be displayed as one long "line."
1181 For example, here is how to construct a display table that mimics the
1182 effect of setting `ctl-arrow' to a non-`nil' value:
1184 (setq disptab (make-display-table))
1187 (or (= i ?\t) (= i ?\n)
1188 (aset disptab i (concat "^" (char-to-string (+ i 64)))))
1190 (aset disptab 127 "^?"))
1193 File: lispref.info, Node: Active Display Table, Next: Character Descriptors, Prev: Display Table Format, Up: Display Tables
1195 Active Display Table
1196 --------------------
1198 The active display table is controlled by the variable
1199 `current-display-table'. This is a specifier, which means that you can
1200 specify separate values for it in individual buffers, windows, frames,
1201 and devices, as well as a global value. It also means that you cannot
1202 set this variable using `setq'; use `set-specifier' instead. *Note
1203 Specifiers::. (FSF Emacs uses `window-display-table',
1204 `buffer-display-table', `standard-display-table', etc. to control the
1205 display table. However, specifiers are a cleaner and more powerful way
1206 of doing the same thing. FSF Emacs also uses a different format for
1207 the contents of a display table, using additional indirection to a
1208 "glyph table" and such. Note that "glyph" has a different meaning in
1211 Individual faces can also specify an overriding display table; this
1212 is set using `set-face-display-table'. *Note Faces::.
1214 If no display table can be determined for a particular window, then
1215 XEmacs uses the usual display conventions. *Note Usual Display::.
1218 File: lispref.info, Node: Character Descriptors, Prev: Active Display Table, Up: Display Tables
1220 Character Descriptors
1221 ---------------------
1223 Each element of the display-table vector describes how to display a
1224 particular character and is called a "character descriptor". A
1225 character descriptor can be:
1228 Display this particular string wherever the character is to be
1232 Display this particular glyph wherever the character is to be
1236 The vector may contain strings and/or glyphs. Display the
1237 elements of the vector one after another wherever the character is
1241 Display according to the standard interpretation (*note Usual
projects / chise / xemacs-chise.git / blob