annotate lispref/display.texi @ 24018:b918e6330d6e

Support configuring with leim.
author Eli Zaretskii <eliz@gnu.org>
date Thu, 07 Jan 1999 12:27:19 +0000
parents 63f6e25f0cbd
children 7451b1458af1
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4 @c See the file elisp.texi for copying conditions.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5 @setfilename ../info/display
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
6 @node Display, Calendar, Processes, Top
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
7 @chapter Emacs Display
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
8
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
9 This chapter describes a number of features related to the display
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10 that Emacs presents to the user.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
11
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
12 @menu
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
13 * Refresh Screen:: Clearing the screen and redrawing everything on it.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
14 * Truncation:: Folding or wrapping long text lines.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
15 * The Echo Area:: Where messages are displayed.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
16 * Invisible Text:: Hiding part of the buffer text.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
17 * Selective Display:: Hiding part of the buffer text (the old way).
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
18 * Overlay Arrow:: Display of an arrow to indicate position.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
19 * Temporary Displays:: Displays that go away automatically.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
20 * Overlays:: Use overlays to highlight parts of the buffer.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
21 * Width:: How wide is a character or string.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
22 * Faces:: A face defines a graphics appearance: font, color, etc.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
23 * Blinking:: How Emacs shows the matching open parenthesis.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
24 * Inverse Video:: Specifying how the screen looks.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
25 * Usual Display:: The usual conventions for displaying nonprinting chars.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
26 * Display Tables:: How to specify other conventions.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
27 * Beeping:: Audible signal to the user.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
28 * Window Systems:: Which window system is being used.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
29 @end menu
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
30
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
31 @node Refresh Screen
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
32 @section Refreshing the Screen
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
33
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
34 The function @code{redraw-frame} redisplays the entire contents of a
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
35 given frame (@pxref{Frames}).
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
36
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37 @c Emacs 19 feature
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
38 @defun redraw-frame frame
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
39 This function clears and redisplays frame @var{frame}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
40 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
41
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
42 Even more powerful is @code{redraw-display}:
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
43
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
44 @deffn Command redraw-display
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
45 This function clears and redisplays all visible frames.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
46 @end deffn
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
47
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
48 Processing user input takes absolute priority over redisplay. If you
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
49 call these functions when input is available, they do nothing
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
50 immediately, but a full redisplay does happen eventually---after all the
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
51 input has been processed.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
52
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
53 Normally, suspending and resuming Emacs also refreshes the screen.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
54 Some terminal emulators record separate contents for display-oriented
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
55 programs such as Emacs and for ordinary sequential display. If you are
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
56 using such a terminal, you might want to inhibit the redisplay on
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8925
diff changeset
57 resumption.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
58
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
59 @defvar no-redraw-on-reenter
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
60 @cindex suspend (cf. @code{no-redraw-on-reenter})
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61 @cindex resume (cf. @code{no-redraw-on-reenter})
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
62 This variable controls whether Emacs redraws the entire screen after it
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
63 has been suspended and resumed. Non-@code{nil} means there is no need
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
64 to redraw, @code{nil} means redrawing is needed. The default is @code{nil}.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
65 @end defvar
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
66
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
67 @node Truncation
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
68 @section Truncation
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
69 @cindex line wrapping
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
70 @cindex continuation lines
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
71 @cindex @samp{$} in display
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
72 @cindex @samp{\} in display
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
73
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
74 When a line of text extends beyond the right edge of a window, the
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
75 line can either be continued on the next screen line, or truncated to
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
76 one screen line. The additional screen lines used to display a long
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
77 text line are called @dfn{continuation} lines. Normally, a @samp{$} in
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
78 the rightmost column of the window indicates truncation; a @samp{\} on
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
79 the rightmost column indicates a line that ``wraps'' onto the next line,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
80 which is also called @dfn{continuing} the line. (The display table can
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
81 specify alternative indicators; see @ref{Display Tables}.)
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
82
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
83 Note that continuation is different from filling; continuation happens
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
84 on the screen only, not in the buffer contents, and it breaks a line
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
85 precisely at the right margin, not at a word boundary. @xref{Filling}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
86
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
87 @defopt truncate-lines
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
88 This buffer-local variable controls how Emacs displays lines that extend
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
89 beyond the right edge of the window. The default is @code{nil}, which
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
90 specifies continuation. If the value is non-@code{nil}, then these
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
91 lines are truncated.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
92
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
93 If the variable @code{truncate-partial-width-windows} is non-@code{nil},
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
94 then truncation is always used for side-by-side windows (within one
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
95 frame) regardless of the value of @code{truncate-lines}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
96 @end defopt
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
97
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
98 @defopt default-truncate-lines
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
99 This variable is the default value for @code{truncate-lines}, for
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
100 buffers that do not have buffer-local values for it.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
101 @end defopt
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
102
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
103 @defopt truncate-partial-width-windows
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
104 This variable controls display of lines that extend beyond the right
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
105 edge of the window, in side-by-side windows (@pxref{Splitting Windows}).
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
106 If it is non-@code{nil}, these lines are truncated; otherwise,
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
107 @code{truncate-lines} says what to do with them.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
108 @end defopt
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
109
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
110 When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
111 a window, that forces truncation.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
112
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
113 You can override the glyphs that indicate continuation or truncation
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
114 using the display table; see @ref{Display Tables}.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
115
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
116 If your buffer contains @emph{very} long lines, and you use
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
117 continuation to display them, just thinking about them can make Emacs
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
118 redisplay slow. The column computation and indentation functions also
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
119 become slow. Then you might find it advisable to set
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
120 @code{cache-long-line-scans} to @code{t}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
121
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
122 @defvar cache-long-line-scans
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
123 If this variable is non-@code{nil}, various indentation and motion
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
124 functions, and Emacs redisplay, cache the results of scanning the
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
125 buffer, and consult the cache to avoid rescanning regions of the buffer
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
126 unless they are modified.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
127
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
128 Turning on the cache slows down processing of short lines somewhat.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
129
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
130 This variable is automatically buffer-local in every buffer.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
131 @end defvar
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
132
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
133 @node The Echo Area
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
134 @section The Echo Area
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
135 @cindex error display
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
136 @cindex echo area
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
137
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
138 The @dfn{echo area} is used for displaying messages made with the
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
139 @code{message} primitive, and for echoing keystrokes. It is not the
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
140 same as the minibuffer, despite the fact that the minibuffer appears
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
141 (when active) in the same place on the screen as the echo area. The
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
142 @cite{GNU Emacs Manual} specifies the rules for resolving conflicts
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
143 between the echo area and the minibuffer for use of that screen space
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
144 (@pxref{Minibuffer,, The Minibuffer, emacs, The GNU Emacs Manual}).
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
145 Error messages appear in the echo area; see @ref{Errors}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
146
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
147 You can write output in the echo area by using the Lisp printing
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
148 functions with @code{t} as the stream (@pxref{Output Functions}), or as
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
149 follows:
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
150
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
151 @defun message string &rest arguments
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
152 This function displays a one-line message in the echo area. The
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
153 argument @var{string} is similar to a C language @code{printf} control
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
154 string. See @code{format} in @ref{String Conversion}, for the details
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
155 on the conversion specifications. @code{message} returns the
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
156 constructed string.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
157
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
158 In batch mode, @code{message} prints the message text on the standard
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
159 error stream, followed by a newline.
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
160
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
161 @c Emacs 19 feature
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
162 If @var{string} is @code{nil}, @code{message} clears the echo area. If
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
163 the minibuffer is active, this brings the minibuffer contents back onto
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
164 the screen immediately.
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
165
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
166 @example
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
167 @group
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
168 (message "Minibuffer depth is %d."
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
169 (minibuffer-depth))
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170 @print{} Minibuffer depth is 0.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
171 @result{} "Minibuffer depth is 0."
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
172 @end group
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
173
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174 @group
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
175 ---------- Echo Area ----------
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
176 Minibuffer depth is 0.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
177 ---------- Echo Area ----------
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
178 @end group
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
179 @end example
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
180 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
181
22843
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
182 @defun message-or-box string &rest arguments
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
183 This function displays a message like @code{message}, but may display it
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
184 in a dialog box instead of the echo area. If this function is called in
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
185 a command that was invoked using the mouse---more precisely, if
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
186 @code{last-nonmenu-event} (@pxref{Command Loop Info}) is either
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
187 @code{nil} or a list---then it uses a dialog box or pop-up menu to
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
188 display the message. Otherwise, it uses the echo area. (This is the
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
189 same criterion that @code{y-or-n-p} uses to make a similar decision; see
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
190 @ref{Yes-or-No Queries}.)
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
191
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
192 You can force use of the mouse or of the echo area by binding
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
193 @code{last-nonmenu-event} to a suitable value around the call.
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
194 @end defun
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
195
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
196 @defun message-box string &rest arguments
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
197 This function displays a message like @code{message}, but uses a dialog
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
198 box (or a pop-up menu) whenever that is possible. If it is impossible
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
199 to use a dialog box or pop-up menu, because the terminal does not
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
200 support them, then @code{message-box} uses the echo area, like
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
201 @code{message}.
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
202 @end defun
63f6e25f0cbd *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22267
diff changeset
203
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
204 @defun current-message
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
205 @tindex current-message
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
206 This function returns the message currently being displayed in the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
207 echo area, or @code{nil} if there is none.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
208 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
209
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
210 @defvar cursor-in-echo-area
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
211 This variable controls where the cursor appears when a message is
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
212 displayed in the echo area. If it is non-@code{nil}, then the cursor
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
213 appears at the end of the message. Otherwise, the cursor appears at
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
214 point---not in the echo area at all.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
215
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
216 The value is normally @code{nil}; Lisp programs bind it to @code{t}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
217 for brief periods of time.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
218 @end defvar
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
219
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
220 @defvar echo-area-clear-hook
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
221 @tindex echo-area-clear-hook
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
222 This normal hook is run whenever the echo area is cleared---either by
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
223 @code{(message nil)} or for any other reason.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
224 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
225
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
226 Almost all the messages displayed in the echo area are also recorded
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
227 in the @samp{*Messages*} buffer.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
228
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
229 @defopt message-log-max
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
230 This variable specifies how many lines to keep in the @samp{*Messages*}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
231 buffer. The value @code{t} means there is no limit on how many lines to
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
232 keep. The value @code{nil} disables message logging entirely. Here's
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
233 how to display a message and prevent it from being logged:
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
234
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
235 @example
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
236 (let (message-log-max)
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
237 (message @dots{}))
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
238 @end example
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
239 @end defopt
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
240
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
241 @defvar echo-keystrokes
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
242 This variable determines how much time should elapse before command
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
243 characters echo. Its value must be an integer, which specifies the
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
244 number of seconds to wait before echoing. If the user types a prefix
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
245 key (such as @kbd{C-x}) and then delays this many seconds before
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
246 continuing, the prefix key is echoed in the echo area. (Once echoing
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
247 begins in a key sequence, all subsequent characters in the same key
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
248 sequence are echoed immediately.)
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
249
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
250 If the value is zero, then command input is not echoed.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
251 @end defvar
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
252
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
253 @node Invisible Text
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
254 @section Invisible Text
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
255
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
256 @cindex invisible text
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
257 You can make characters @dfn{invisible}, so that they do not appear on
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
258 the screen, with the @code{invisible} property. This can be either a
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
259 text property (@pxref{Text Properties}) or a property of an overlay
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
260 (@pxref{Overlays}).
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
261
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
262 In the simplest case, any non-@code{nil} @code{invisible} property makes
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
263 a character invisible. This is the default case---if you don't alter
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
264 the default value of @code{buffer-invisibility-spec}, this is how the
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
265 @code{invisible} property works.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
266
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
267 More generally, you can use the variable @code{buffer-invisibility-spec}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
268 to control which values of the @code{invisible} property make text
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
269 invisible. This permits you to classify the text into different subsets
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
270 in advance, by giving them different @code{invisible} values, and
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
271 subsequently make various subsets visible or invisible by changing the
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
272 value of @code{buffer-invisibility-spec}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
273
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
274 Controlling visibility with @code{buffer-invisibility-spec} is
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
275 especially useful in a program to display the list of entries in a data
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
276 base. It permits the implementation of convenient filtering commands to
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
277 view just a part of the entries in the data base. Setting this variable
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
278 is very fast, much faster than scanning all the text in the buffer
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
279 looking for properties to change.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
280
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
281 @defvar buffer-invisibility-spec
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
282 This variable specifies which kinds of @code{invisible} properties
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
283 actually make a character invisible.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
284
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
285 @table @asis
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
286 @item @code{t}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
287 A character is invisible if its @code{invisible} property is
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
288 non-@code{nil}. This is the default.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
289
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
290 @item a list
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
291 Each element of the list specifies a criterion for invisibility; if a
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
292 character's @code{invisible} property fits any one of these criteria,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
293 the character is invisible. The list can have two kinds of elements:
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
294
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
295 @table @code
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
296 @item @var{atom}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
297 A character is invisible if its @code{invisible} property value
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
298 is @var{atom} or if it is a list with @var{atom} as a member.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
299
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
300 @item (@var{atom} . t)
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
301 A character is invisible if its @code{invisible} property value
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
302 is @var{atom} or if it is a list with @var{atom} as a member.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
303 Moreover, if this character is at the end of a line and is followed
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
304 by a visible newline, it displays an ellipsis.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
305 @end table
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
306 @end table
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
307 @end defvar
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
308
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
309 Two functions are specifically provided for adding elements to
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
310 @code{buffer-invisibility-spec} and removing elements from it.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
311
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
312 @defun add-to-invisibility-spec element
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
313 @tindex add-to-invisibility-spec
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
314 Add the element @var{element} to @code{buffer-invisibility-spec}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
315 (if it is not already present in that list).
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
316 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
317
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
318 @defun remove-from-invisibility-spec element
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
319 @tindex remove-from-invisibility-spec
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
320 Remove the element @var{element} from @code{buffer-invisibility-spec}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
321 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
322
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
323 One convention about the use of @code{buffer-invisibility-spec} is
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
324 that a major mode should use the mode's own name as an element of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
325 @code{buffer-invisibility-spec} and as the value of the @code{invisible}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
326 property:
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
327
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
328 @example
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
329 ;; @r{If you want to display an ellipsis:}
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
330 (add-to-invisibility-spec '(my-symbol . t))
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
331 ;; @r{If you don't want ellipsis:}
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
332 (add-to-invisibility-spec 'my-symbol)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
333
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
334 (overlay-put (make-overlay beginning end)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
335 'invisible 'my-symbol)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
336
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
337 ;; @r{When done with the overlays:}
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
338 (remove-from-invisibility-spec '(my-symbol . t))
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
339 ;; @r{Or respectively:}
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
340 (remove-from-invisibility-spec 'my-symbol)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
341 @end example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
342
15761
77d451c08a30 Document line-move-ignore-invisible.
Richard M. Stallman <rms@gnu.org>
parents: 15074
diff changeset
343 @vindex line-move-ignore-invisible
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
344 Ordinarily, commands that operate on text or move point do not care
15761
77d451c08a30 Document line-move-ignore-invisible.
Richard M. Stallman <rms@gnu.org>
parents: 15074
diff changeset
345 whether the text is invisible. The user-level line motion commands
77d451c08a30 Document line-move-ignore-invisible.
Richard M. Stallman <rms@gnu.org>
parents: 15074
diff changeset
346 explicitly ignore invisible newlines if
77d451c08a30 Document line-move-ignore-invisible.
Richard M. Stallman <rms@gnu.org>
parents: 15074
diff changeset
347 @code{line-move-ignore-invisible} is non-@code{nil}, but only because
77d451c08a30 Document line-move-ignore-invisible.
Richard M. Stallman <rms@gnu.org>
parents: 15074
diff changeset
348 they are explicitly programmed to do so.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
349
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
350 Incremental search can make invisible overlays visible temporarily
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
351 and/or permanently when a match includes invisible text. To enable
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
352 this, the overlay should have a non-@code{nil}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
353 @code{isearch-open-invisible} property. The property value should be a
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
354 function to be called with the overlay as an argument. This function
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
355 should make the overlay visible permanently; it is used when the match
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
356 overlaps the overlay on exit from the search.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
357
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
358 During the search, such overlays are made temporarily visible by
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
359 temporarily modifying their invisible and intangible properties. If you
22267
dfac7398266b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
360 want this to be done differently for a certain overlay, give it an
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
361 @code{isearch-open-invisible-temporary} property which is a function.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
362 The function is called with two arguments: the first is the overlay, and
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
363 the second is @code{t} to make the overlay visible, or @code{nil} to
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
364 make it invisible again.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
365
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
366 @node Selective Display
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
367 @section Selective Display
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
368 @cindex selective display
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
369
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
370 @dfn{Selective display} refers to a pair of related features for
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
371 hiding certain lines on the screen.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
372
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
373 The first variant, explicit selective display, is designed for use in
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
374 a Lisp program: it controls which lines are hidden by altering the text.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
375 The invisible text feature (@pxref{Invisible Text}) has partially
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
376 replaced this feature.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
377
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
378 In the second variant, the choice of lines to hide is made
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
379 automatically based on indentation. This variant is designed to be a
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
380 user-level feature.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
381
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
382 The way you control explicit selective display is by replacing a
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8925
diff changeset
383 newline (control-j) with a carriage return (control-m). The text that
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
384 was formerly a line following that newline is now invisible. Strictly
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
385 speaking, it is temporarily no longer a line at all, since only newlines
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
386 can separate lines; it is now part of the previous line.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
387
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
388 Selective display does not directly affect editing commands. For
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
389 example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly into
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
390 invisible text. However, the replacement of newline characters with
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
391 carriage return characters affects some editing commands. For example,
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
392 @code{next-line} skips invisible lines, since it searches only for
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
393 newlines. Modes that use selective display can also define commands
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
394 that take account of the newlines, or that make parts of the text
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
395 visible or invisible.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
396
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
397 When you write a selectively displayed buffer into a file, all the
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
398 control-m's are output as newlines. This means that when you next read
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
399 in the file, it looks OK, with nothing invisible. The selective display
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
400 effect is seen only within Emacs.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
401
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
402 @defvar selective-display
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
403 This buffer-local variable enables selective display. This means that
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
404 lines, or portions of lines, may be made invisible.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
405
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
406 @itemize @bullet
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
407 @item
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
408 If the value of @code{selective-display} is @code{t}, then any portion
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
409 of a line that follows a control-m is not displayed. This is explicit
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
410 selective display.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
411
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
412 @item
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
413 If the value of @code{selective-display} is a positive integer, then
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
414 lines that start with more than that many columns of indentation are not
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415 displayed.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
416 @end itemize
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
417
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
418 When some portion of a buffer is invisible, the vertical movement
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
419 commands operate as if that portion did not exist, allowing a single
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
420 @code{next-line} command to skip any number of invisible lines.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
421 However, character movement commands (such as @code{forward-char}) do
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
422 not skip the invisible portion, and it is possible (if tricky) to insert
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
423 or delete text in an invisible portion.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
424
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
425 In the examples below, we show the @emph{display appearance} of the
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
426 buffer @code{foo}, which changes with the value of
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
427 @code{selective-display}. The @emph{contents} of the buffer do not
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
428 change.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
429
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
430 @example
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
431 @group
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
432 (setq selective-display nil)
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
433 @result{} nil
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
434
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
435 ---------- Buffer: foo ----------
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
436 1 on this column
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
437 2on this column
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
438 3n this column
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
439 3n this column
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
440 2on this column
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
441 1 on this column
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
442 ---------- Buffer: foo ----------
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
443 @end group
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
444
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
445 @group
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
446 (setq selective-display 2)
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447 @result{} 2
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449 ---------- Buffer: foo ----------
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450 1 on this column
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451 2on this column
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
452 2on this column
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
453 1 on this column
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
454 ---------- Buffer: foo ----------
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
455 @end group
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
456 @end example
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
457 @end defvar
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
458
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
459 @defvar selective-display-ellipses
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
460 If this buffer-local variable is non-@code{nil}, then Emacs displays
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
461 @samp{@dots{}} at the end of a line that is followed by invisible text.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
462 This example is a continuation of the previous one.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
463
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464 @example
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465 @group
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466 (setq selective-display-ellipses t)
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467 @result{} t
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
468
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
469 ---------- Buffer: foo ----------
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
470 1 on this column
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
471 2on this column ...
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
472 2on this column
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
473 1 on this column
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
474 ---------- Buffer: foo ----------
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
475 @end group
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
476 @end example
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
477
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
478 You can use a display table to substitute other text for the ellipsis
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
479 (@samp{@dots{}}). @xref{Display Tables}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
480 @end defvar
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
481
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
482 @node Overlay Arrow
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
483 @section The Overlay Arrow
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
484 @cindex overlay arrow
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
485
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
486 The @dfn{overlay arrow} is useful for directing the user's attention
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
487 to a particular line in a buffer. For example, in the modes used for
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
488 interface to debuggers, the overlay arrow indicates the line of code
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
489 about to be executed.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
490
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
491 @defvar overlay-arrow-string
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8925
diff changeset
492 This variable holds the string to display to call attention to a
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8925
diff changeset
493 particular line, or @code{nil} if the arrow feature is not in use.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
494 @end defvar
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
495
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
496 @defvar overlay-arrow-position
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8925
diff changeset
497 This variable holds a marker that indicates where to display the overlay
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8925
diff changeset
498 arrow. It should point at the beginning of a line. The arrow text
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8925
diff changeset
499 appears at the beginning of that line, overlaying any text that would
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8925
diff changeset
500 otherwise appear. Since the arrow is usually short, and the line
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8925
diff changeset
501 usually begins with indentation, normally nothing significant is
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8925
diff changeset
502 overwritten.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
503
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8925
diff changeset
504 The overlay string is displayed only in the buffer that this marker
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
505 points into. Thus, only one buffer can have an overlay arrow at any
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
506 given time.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
507 @c !!! overlay-arrow-position: but the overlay string may remain in the display
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
508 @c of some other buffer until an update is required. This should be fixed
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
509 @c now. Is it?
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
510 @end defvar
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
511
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
512 You can do a similar job by creating an overlay with a
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
513 @code{before-string} property. @xref{Overlay Properties}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
514
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
515 @node Temporary Displays
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
516 @section Temporary Displays
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
517
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
518 Temporary displays are used by Lisp programs to put output into a
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
519 buffer and then present it to the user for perusal rather than for
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
520 editing. Many help commands use this feature.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
521
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
522 @defspec with-output-to-temp-buffer buffer-name forms@dots{}
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
523 This function executes @var{forms} while arranging to insert any
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
524 output they print into the buffer named @var{buffer-name}. The buffer
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
525 is then shown in some window for viewing, displayed but not selected.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
526
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
527 The string @var{buffer-name} specifies the temporary buffer, which
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
528 need not already exist. The argument must be a string, not a buffer.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
529 The buffer is erased initially (with no questions asked), and it is
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
530 marked as unmodified after @code{with-output-to-temp-buffer} exits.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
531
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
532 @code{with-output-to-temp-buffer} binds @code{standard-output} to the
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
533 temporary buffer, then it evaluates the forms in @var{forms}. Output
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
534 using the Lisp output functions within @var{forms} goes by default to
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
535 that buffer (but screen display and messages in the echo area, although
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
536 they are ``output'' in the general sense of the word, are not affected).
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
537 @xref{Output Functions}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
538
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539 The value of the last form in @var{forms} is returned.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
540
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
541 @example
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
542 @group
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
543 ---------- Buffer: foo ----------
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
544 This is the contents of foo.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
545 ---------- Buffer: foo ----------
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
546 @end group
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
547
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
548 @group
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
549 (with-output-to-temp-buffer "foo"
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
550 (print 20)
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
551 (print standard-output))
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
552 @result{} #<buffer foo>
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
553
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
554 ---------- Buffer: foo ----------
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
555 20
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
556
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
557 #<buffer foo>
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
558
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
559 ---------- Buffer: foo ----------
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
560 @end group
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
561 @end example
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
562 @end defspec
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
563
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
564 @defvar temp-buffer-show-function
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8925
diff changeset
565 If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
566 calls it as a function to do the job of displaying a help buffer. The
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
567 function gets one argument, which is the buffer it should display.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
568
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
569 It is a good idea for this function to run @code{temp-buffer-show-hook}
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
570 just as @code{with-output-to-temp-buffer} normally would, inside of
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
571 @code{save-window-excursion} and with the chosen window and buffer
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
572 selected.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
573 @end defvar
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
574
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
575 @defvar temp-buffer-show-hook
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
576 This normal hook is run by @code{with-output-to-temp-buffer} after
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
577 displaying the help buffer. When the hook runs, the help buffer is
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
578 current, and the window it was displayed in is selected.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
579 @end defvar
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
580
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
581 @defun momentary-string-display string position &optional char message
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
582 This function momentarily displays @var{string} in the current buffer at
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
583 @var{position}. It has no effect on the undo list or on the buffer's
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
584 modification status.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
585
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
586 The momentary display remains until the next input event. If the next
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
587 input event is @var{char}, @code{momentary-string-display} ignores it
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
588 and returns. Otherwise, that event remains buffered for subsequent use
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
589 as input. Thus, typing @var{char} will simply remove the string from
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
590 the display, while typing (say) @kbd{C-f} will remove the string from
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
591 the display and later (presumably) move point forward. The argument
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
592 @var{char} is a space by default.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
593
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
594 The return value of @code{momentary-string-display} is not meaningful.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
595
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
596 If the string @var{string} does not contain control characters, you can
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
597 do the same job in a more general way by creating (and then subsequently
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
598 deleting) an overlay with a @code{before-string} property.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
599 @xref{Overlay Properties}.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
600
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
601 If @var{message} is non-@code{nil}, it is displayed in the echo area
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
602 while @var{string} is displayed in the buffer. If it is @code{nil}, a
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
603 default message says to type @var{char} to continue.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
604
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
605 In this example, point is initially located at the beginning of the
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
606 second line:
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
607
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
608 @example
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
609 @group
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
610 ---------- Buffer: foo ----------
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
611 This is the contents of foo.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
612 @point{}Second line.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
613 ---------- Buffer: foo ----------
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
614 @end group
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
615
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
616 @group
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
617 (momentary-string-display
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
618 "**** Important Message! ****"
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
619 (point) ?\r
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
620 "Type RET when done reading")
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
621 @result{} t
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
622 @end group
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
623
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
624 @group
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
625 ---------- Buffer: foo ----------
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
626 This is the contents of foo.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
627 **** Important Message! ****Second line.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
628 ---------- Buffer: foo ----------
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
629
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
630 ---------- Echo Area ----------
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
631 Type RET when done reading
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
632 ---------- Echo Area ----------
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
633 @end group
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
634 @end example
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
635 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
636
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
637 @node Overlays
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
638 @section Overlays
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
639 @cindex overlays
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
640
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
641 You can use @dfn{overlays} to alter the appearance of a buffer's text on
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
642 the screen, for the sake of presentation features. An overlay is an
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
643 object that belongs to a particular buffer, and has a specified
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
644 beginning and end. It also has properties that you can examine and set;
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
645 these affect the display of the text within the overlay.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
646
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
647 @menu
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
648 * Overlay Properties:: How to read and set properties.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
649 What properties do to the screen display.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
650 * Managing Overlays:: Creating, moving, finding overlays.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
651 @end menu
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
652
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
653 @node Overlay Properties
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
654 @subsection Overlay Properties
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
655
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
656 Overlay properties are like text properties in that the properties that
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
657 alter how a character is displayed can come from either source. But in
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
658 most respects they are different. Text properties are considered a part
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
659 of the text; overlays are specifically considered not to be part of the
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
660 text. Thus, copying text between various buffers and strings preserves
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
661 text properties, but does not try to preserve overlays. Changing a
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
662 buffer's text properties marks the buffer as modified, while moving an
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
663 overlay or changing its properties does not. Unlike text property
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
664 changes, overlay changes are not recorded in the buffer's undo list.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
665 @xref{Text Properties}, for comparison.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
666
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
667 @table @code
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
668 @item priority
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
669 @kindex priority @r{(overlay property)}
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
670 This property's value (which should be a nonnegative number) determines
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
671 the priority of the overlay. The priority matters when two or more
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
672 overlays cover the same character and both specify a face for display;
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
673 the one whose @code{priority} value is larger takes priority over the
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
674 other, and its face attributes override the face attributes of the lower
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
675 priority overlay.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
676
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
677 Currently, all overlays take priority over text properties. Please
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
678 avoid using negative priority values, as we have not yet decided just
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
679 what they should mean.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
680
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
681 @item window
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
682 @kindex window @r{(overlay property)}
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
683 If the @code{window} property is non-@code{nil}, then the overlay
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
684 applies only on that window.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
685
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
686 @item category
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
687 @kindex category @r{(overlay property)}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
688 If an overlay has a @code{category} property, we call it the
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
689 @dfn{category} of the overlay. It should be a symbol. The properties
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
690 of the symbol serve as defaults for the properties of the overlay.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
691
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
692 @item face
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
693 @kindex face @r{(overlay property)}
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
694 This property controls the way text is displayed---for example, which
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
695 font and which colors. Its value is a face name or a list of face
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
696 names. @xref{Faces}, for more information.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
697
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
698 If the property value is a list, elements may also have the form
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
699 @code{(foreground-color . @var{color-name})} or @code{(background-color
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
700 . @var{color-name})}. These elements specify just the foreground color
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
701 or just the background color; therefore, there is no need to create a
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
702 face for each color that you want to use.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
703
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
704 @item mouse-face
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
705 @kindex mouse-face @r{(overlay property)}
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
706 This property is used instead of @code{face} when the mouse is within
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
707 the range of the overlay.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
708
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
709 @item modification-hooks
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
710 @kindex modification-hooks @r{(overlay property)}
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
711 This property's value is a list of functions to be called if any
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
712 character within the overlay is changed or if text is inserted strictly
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
713 within the overlay.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
714
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
715 The hook functions are called both before and after each change.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
716 If the functions save the information they receive, and compare notes
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
717 between calls, they can determine exactly what change has been made
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
718 in the buffer text.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
719
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
720 When called before a change, each function receives four arguments: the
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
721 overlay, @code{nil}, and the beginning and end of the text range to be
7086
075343a6b32b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6598
diff changeset
722 modified.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
723
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
724 When called after a change, each function receives five arguments: the
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
725 overlay, @code{t}, the beginning and end of the text range just
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
726 modified, and the length of the pre-change text replaced by that range.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
727 (For an insertion, the pre-change length is zero; for a deletion, that
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
728 length is the number of characters deleted, and the post-change
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
729 beginning and end are equal.)
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
730
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
731 @item insert-in-front-hooks
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
732 @kindex insert-in-front-hooks @r{(overlay property)}
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
733 This property's value is a list of functions to be called before and
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
734 after inserting text right at the beginning of the overlay. The calling
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
735 conventions are the same as for the @code{modification-hooks} functions.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
736
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
737 @item insert-behind-hooks
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
738 @kindex insert-behind-hooks @r{(overlay property)}
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
739 This property's value is a list of functions to be called before and
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
740 after inserting text right at the end of the overlay. The calling
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
741 conventions are the same as for the @code{modification-hooks} functions.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
742
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
743 @item invisible
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
744 @kindex invisible @r{(overlay property)}
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
745 The @code{invisible} property can make the text in the overlay
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
746 invisible, which means that it does not appear on the screen.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
747 @xref{Invisible Text}, for details.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
748
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
749 @item intangible
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
750 @kindex intangible @r{(overlay property)}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
751 The @code{intangible} property on an overlay works just like the
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
752 @code{intangible} text property. @xref{Special Properties}, for details.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
753
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
754 @item isearch-open-invisible
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
755 This property tells incremental search how to make an invisible overlay
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
756 visible, permanently, if the final match overlaps it. @xref{Invisible
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
757 Text}.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
758
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
759 @item isearch-open-invisible-temporary
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
760 This property tells incremental search how to make an invisible overlay
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
761 visible, temporarily, during the search. @xref{Invisible Text}.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
762
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
763 @item before-string
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
764 @kindex before-string @r{(overlay property)}
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
765 This property's value is a string to add to the display at the beginning
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
766 of the overlay. The string does not appear in the buffer in any
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
767 sense---only on the screen. The string should contain only characters
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
768 that display as a single column---control characters, including tabs or
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
769 newlines, will give strange results.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
770
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
771 @item after-string
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
772 @kindex after-string @r{(overlay property)}
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
773 This property's value is a string to add to the display at the end of
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
774 the overlay. The string does not appear in the buffer in any
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
775 sense---only on the screen. The string should contain only characters
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
776 that display as a single column---control characters, including tabs or
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
777 newlines, will give strange results.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
778
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
779 @item evaporate
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
780 @kindex evaporate @r{(overlay property)}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
781 If this property is non-@code{nil}, the overlay is deleted automatically
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
782 if it ever becomes empty (i.e., if it spans no characters).
16123
ec5f48fe0320 Mention local-value property on an overlay.
Richard M. Stallman <rms@gnu.org>
parents: 15761
diff changeset
783
ec5f48fe0320 Mention local-value property on an overlay.
Richard M. Stallman <rms@gnu.org>
parents: 15761
diff changeset
784 @item local-map
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
785 @cindex keymap of character (and overlays)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
786 @kindex local-map @r{(overlay property)}
16123
ec5f48fe0320 Mention local-value property on an overlay.
Richard M. Stallman <rms@gnu.org>
parents: 15761
diff changeset
787 If this property is non-@code{nil}, it specifies a keymap for a portion
ec5f48fe0320 Mention local-value property on an overlay.
Richard M. Stallman <rms@gnu.org>
parents: 15761
diff changeset
788 of the text. The property's value replaces the buffer's local map, when
ec5f48fe0320 Mention local-value property on an overlay.
Richard M. Stallman <rms@gnu.org>
parents: 15761
diff changeset
789 the character after point is within the overlay. @xref{Active Keymaps}.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
790 @end table
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
791
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
792 These are the functions for reading and writing the properties of an
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
793 overlay.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
794
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
795 @defun overlay-get overlay prop
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
796 This function returns the value of property @var{prop} recorded in
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
797 @var{overlay}, if any. If @var{overlay} does not record any value for
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
798 that property, but it does have a @code{category} property which is a
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
799 symbol, that symbol's @var{prop} property is used. Otherwise, the value
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
800 is @code{nil}.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
801 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
802
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
803 @defun overlay-put overlay prop value
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
804 This function sets the value of property @var{prop} recorded in
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
805 @var{overlay} to @var{value}. It returns @var{value}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
806 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
807
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
808 See also the function @code{get-char-property} which checks both
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
809 overlay properties and text properties for a given character.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
810 @xref{Examining Properties}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
811
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
812 @node Managing Overlays
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
813 @subsection Managing Overlays
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
814
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
815 This section describes the functions to create, delete and move
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
816 overlays, and to examine their contents.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
817
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
818 @defun make-overlay start end &optional buffer front-advance rear-advance
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8925
diff changeset
819 This function creates and returns an overlay that belongs to
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
820 @var{buffer} and ranges from @var{start} to @var{end}. Both @var{start}
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
821 and @var{end} must specify buffer positions; they may be integers or
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
822 markers. If @var{buffer} is omitted, the overlay is created in the
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
823 current buffer.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
824
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
825 The arguments @var{front-advance} and @var{rear-advance} specify the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
826 insertion type for the start of the overlay and for the end of the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
827 overlay. @xref{Marker Insertion Types}.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
828 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
829
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
830 @defun overlay-start overlay
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
831 This function returns the position at which @var{overlay} starts,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
832 as an integer.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
833 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
834
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
835 @defun overlay-end overlay
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
836 This function returns the position at which @var{overlay} ends,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
837 as an integer.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
838 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
839
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
840 @defun overlay-buffer overlay
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
841 This function returns the buffer that @var{overlay} belongs to.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
842 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
843
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
844 @defun delete-overlay overlay
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
845 This function deletes @var{overlay}. The overlay continues to exist as
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
846 a Lisp object, but ceases to be attached to the buffer it belonged to,
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
847 and ceases to have any effect on display.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
848
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
849 A deleted overlay is not permanently useless. You can give it
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
850 a new buffer position by calling @code{move-overlay}.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
851 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
852
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
853 @defun move-overlay overlay start end &optional buffer
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
854 This function moves @var{overlay} to @var{buffer}, and places its bounds
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
855 at @var{start} and @var{end}. Both arguments @var{start} and @var{end}
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
856 must specify buffer positions; they may be integers or markers. If
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
857 @var{buffer} is omitted, the overlay stays in the same buffer.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
858
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
859 The return value is @var{overlay}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
860
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
861 This is the only valid way to change the endpoints of an overlay. Do
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
862 not try modifying the markers in the overlay by hand, as that fails to
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
863 update other vital data structures and can cause some overlays to be
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
864 ``lost''.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
865 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
866
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
867 @defun overlays-at pos
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
868 This function returns a list of all the overlays that contain position
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
869 @var{pos} in the current buffer. The list is in no particular order.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
870 An overlay contains position @var{pos} if it begins at or before
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
871 @var{pos}, and ends after @var{pos}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
872 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
873
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
874 @defun overlays-in beg end
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
875 @tindex overlays-in
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
876 This function returns a list of the overlays that overlap the region
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
877 @var{beg} through @var{end}. ``Overlap'' means that at least one
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
878 character is contained within the overlay and also contained within the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
879 specified region; however, empty overlays are included in the result if
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
880 they are located at @var{beg} or between @var{beg} and @var{end}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
881 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
882
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
883 @defun next-overlay-change pos
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
884 This function returns the buffer position of the next beginning or end
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
885 of an overlay, after @var{pos}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
886 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
887
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
888 @defun previous-overlay-change pos
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
889 This function returns the buffer position of the previous beginning or
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
890 end of an overlay, before @var{pos}.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
891 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
892
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
893 @node Width
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
894 @section Width
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
895
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
896 Since not all characters have the same width, these functions let you
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
897 check the width of a character. @xref{Primitive Indent}, and
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
898 @ref{Screen Lines}, for related functions.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
899
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
900 @defun char-width char
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
901 @tindex char-width
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
902 This function returns the width in columns of the character @var{char},
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
903 if it were displayed in the current buffer and the selected window.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
904 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
905
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
906 @defun string-width string
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
907 @tindex string-width
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
908 This function returns the width in columns of the string @var{string},
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
909 if it were displayed in the current buffer and the selected window.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
910 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
911
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
912 @defun truncate-string-to-width string width &optional start-column padding
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
913 @tindex truncate-string-to-width
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
914 This function returns the part of @var{string} that fits within
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
915 @var{width} columns, as a new string.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
916
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
917 If @var{string} does not reach @var{width}, then the result ends where
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
918 @var{string} ends. If one multi-column character in @var{string}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
919 extends across the column @var{width}, that character is not included in
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
920 the result. Thus, the result can fall short of @var{width} but cannot
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
921 go beyond it.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
922
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
923 The optional argument @var{start-column} specifies the starting column.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
924 If this is non-@code{nil}, then the first @var{start-column} columns of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
925 the string are omitted from the value. If one multi-column character in
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
926 @var{string} extends across the column @var{start-column}, that
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
927 character is not included.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
928
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
929 The optional argument @var{padding}, if non-@code{nil}, is a padding
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
930 character added at the beginning and end of the result string, to extend
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
931 it to exactly @var{width} columns. The padding character is used at the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
932 end of the result if it falls short of @var{width}. It is also used at
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
933 the beginning of the result if one multi-column character in
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
934 @var{string} extends across the column @var{start-column}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
935
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
936 @example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
937 (truncate-string-to-width "\tab\t" 12 4)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
938 @result{} "ab"
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
939 (truncate-string-to-width "\tab\t" 12 4 ?\ )
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
940 @result{} " ab "
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
941 @end example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
942 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
943
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
944 @node Faces
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
945 @section Faces
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
946 @cindex face
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
947
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
948 A @dfn{face} is a named collection of graphical attributes: font,
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
949 foreground color, background color, and optional underlining. Faces
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
950 control the display of text on the screen.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
951
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
952 @cindex face id
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
953 Each face has its own @dfn{face number}, which distinguishes faces at
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
954 low levels within Emacs. However, for most purposes, you can refer to
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
955 faces in Lisp programs by their names.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
956
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
957 @defun facep object
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
958 This function returns @code{t} if @var{object} is a face name symbol (or
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
959 if it is a vector of the kind used internally to record face data). It
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
960 returns @code{nil} otherwise.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
961 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
962
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
963 Each face name is meaningful for all frames, and by default it has the
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
964 same meaning in all frames. But you can arrange to give a particular
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
965 face name a special meaning in one frame if you wish.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
966
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
967 @menu
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
968 * Standard Faces:: The faces Emacs normally comes with.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
969 * Defining Faces:: How to define a face with @code{defface}.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
970 * Merging Faces:: How Emacs decides which face to use for a character.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
971 * Face Functions:: How to define and examine faces.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
972 @end menu
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
973
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
974 @node Standard Faces
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
975 @subsection Standard Faces
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
976
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
977 This table lists all the standard faces and their uses.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
978
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
979 @table @code
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
980 @item default
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
981 @kindex default @r{(face name)}
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
982 This face is used for ordinary text.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
983
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
984 @item modeline
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
985 @kindex modeline @r{(face name)}
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
986 This face is used for mode lines and menu bars.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
987
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
988 @item region
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
989 @kindex region @r{(face name)}
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
990 This face is used for highlighting the region in Transient Mark mode.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
991
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
992 @item secondary-selection
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
993 @kindex secondary-selection @r{(face name)}
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
994 This face is used to show any secondary selection you have made.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
995
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
996 @item highlight
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
997 @kindex highlight @r{(face name)}
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
998 This face is meant to be used for highlighting for various purposes.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
999
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1000 @item underline
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1001 @kindex underline @r{(face name)}
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1002 This face underlines text.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1003
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1004 @item bold
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1005 @kindex bold @r{(face name)}
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1006 This face uses a bold font, if possible. It uses the bold variant of
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1007 the frame's font, if it has one. It's up to you to choose a default
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1008 font that has a bold variant, if you want to use one.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1009
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1010 @item italic
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1011 @kindex italic @r{(face name)}
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1012 This face uses the italic variant of the frame's font, if it has one.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1013
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1014 @item bold-italic
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1015 @kindex bold-italic @r{(face name)}
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1016 This face uses the bold italic variant of the frame's font, if it has
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1017 one.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1018 @end table
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1019
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1020 @node Defining Faces
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1021 @subsection Defining Faces
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1022
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1023 The way to define a new face is with @code{defface}. This creates a
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1024 kind of customization item (@pxref{Customization}) which the user can
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1025 customize using the Customization buffer (@pxref{Easy Customization,,,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1026 emacs, The GNU Emacs Manual}).
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1027
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1028 @defmac defface face spec doc [keyword value]...
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1029 @tindex defface
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1030 Declare @var{face} as a customizable face that defaults according to
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1031 @var{spec}. Do not quote the symbol @var{face}. The argument @var{doc}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1032 specifies the face documentation.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1033
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1034 When @code{defface} executes, it defines the face according to
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1035 @var{spec}, then uses any customizations that were read from the
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1036 @file{.emacs} file to override that specification.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1037
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1038 The purpose of @var{spec} is to specify how the face should appear on
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1039 different kinds of terminals. It should be an alist whose elements have
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1040 the form @code{(@var{display} @var{atts})}. The element's @sc{car},
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1041 @var{display}, specifies a class of terminals. The @sc{cdr},
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1042 @var{atts}, is a list of face attributes and their values; it specifies
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1043 what the face should look like on that kind of terminal. The possible
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1044 attributes are defined in the value of @code{custom-face-attributes}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1045
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1046 The @var{display} part of an element of @var{spec} determines which
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1047 frames the element applies to. If more than one element of @var{spec}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1048 matches a given frame, the first matching element is the only one used
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1049 for that frame. There are two possibilities for @var{display}:
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1050
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1051 @table @asis
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1052 @item @code{t}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1053 This element of @var{spec} matches all frames. Therefore, any
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1054 subsequent elements of @var{spec} are never used. Normally
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1055 @code{t} is used in the last (or only) element of @var{spec}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1056
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1057 @item a list
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1058 If @var{display} is a list, each element should have the form
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1059 @code{(@var{characteristic} @var{value}@dots{})}. Here
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1060 @var{characteristic} specifies a way of classifying frames, and the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1061 @var{value}s are possible classifications which @var{display} should
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1062 apply to. Here are the possible values of @var{characteristic}:
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1063
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1064 @table @code
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1065 @item type
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1066 The kind of window system the frame uses---either @code{x}, @code{pc}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1067 (for the MS-DOS console), @code{w32} (for MS Windows 9X/NT), or
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1068 @code{tty}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1069
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1070 @item class
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1071 What kinds of colors the frame supports---either @code{color},
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1072 @code{grayscale}, or @code{mono}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1073
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1074 @item background
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1075 The kind of background---either @code{light} or @code{dark}.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1076 @end table
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1077
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1078 If an element of @var{display} specifies more than one @var{value} for a
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1079 given @var{characteristic}, any of those values is acceptable. If
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1080 @var{display} has more than one element, each element should specify a
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1081 different @var{characteristic}; then @emph{each} characteristic of the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1082 frame must match one of the @var{value}s specified for it in
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1083 @var{display}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1084 @end table
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1085 @end defmac
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1086
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1087 Here's how the standard face @code{region} could be defined
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1088 with @code{defface}:
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1089
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1090 @example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1091 (defface region
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1092 ((((class color) (background dark))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1093 (:background "blue"))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1094 (t (:background "gray")))
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1095 "Used for displaying the region.")
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1096 @end example
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1097
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1098 Internally, @code{defface} uses the symbol property
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1099 @code{face-defface-spec} to record the face attributes specified in
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1100 @code{defface}, @code{saved-face} for the attributes saved by the user
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1101 with the customization buffer, and @code{face-documentation} for the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1102 documentation string.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1103
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1104 @tindex frame-background-mode
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1105 @defopt frame-background-mode
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1106 This option, if non-@code{nil}, specifies the background type to use for
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1107 interpreting face definitions. If it is @code{dark}, then Emacs treats
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1108 all frames as if they had a dark background, regardless of their actual
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1109 background colors. If it is @code{light}, then Emacs treats all frames
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1110 as if they had a light background.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1111 @end defopt
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1112
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1113 @node Merging Faces
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1114 @subsection Merging Faces for Display
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1115
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1116 Here are all the ways to specify which face to use for display of text:
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1117
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1118 @itemize @bullet
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1119 @item
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1120 With defaults. Each frame has a @dfn{default face}, which is used for
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1121 all text that doesn't somehow specify another face. (We may change this
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1122 in a forthcoming Emacs version to serve as a default for all text.)
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1123
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1124 @item
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1125 With text properties. A character may have a @code{face} property; if so,
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8925
diff changeset
1126 it is displayed with that face. @xref{Special Properties}.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1127
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1128 If the character has a @code{mouse-face} property, that is used instead
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1129 of the @code{face} property when the mouse is ``near enough'' to the
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1130 character.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1131
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1132 @item
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1133 With overlays. An overlay may have @code{face} and @code{mouse-face}
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1134 properties too; they apply to all the text covered by the overlay.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1135
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1136 @item
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1137 With a region that is active. In Transient Mark mode, the region is
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1138 highlighted with a particular face (see @code{region-face}, below).
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1139
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1140 @item
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1141 With special glyphs. Each glyph can specify a particular face
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1142 number. @xref{Glyphs}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1143 @end itemize
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1144
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1145 If these various sources together specify more than one face for a
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1146 particular character, Emacs merges the attributes of the various faces
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1147 specified. The attributes of the faces of special glyphs come first;
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1148 then comes the face for region highlighting, if appropriate;
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1149 then come attributes of faces from overlays, followed by those from text
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1150 properties, and last the default face.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1151
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1152 When multiple overlays cover one character, an overlay with higher
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1153 priority overrides those with lower priority. @xref{Overlays}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1154
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1155 If an attribute such as the font or a color is not specified in any of
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1156 the above ways, the frame's own font or color is used.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1157
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1158 @node Face Functions
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1159 @subsection Functions for Working with Faces
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1160
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1161 The attributes a face can specify include the font, the foreground
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1162 color, the background color, and underlining. The face can also leave
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1163 these unspecified by giving the value @code{nil} for them.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1164
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1165 Here are the primitives for creating and changing faces.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1166
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1167 @defun make-face name
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1168 This function defines a new face named @var{name}, initially with all
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1169 attributes @code{nil}. It does nothing if there is already a face named
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1170 @var{name}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1171 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1172
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1173 @defun face-list
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1174 This function returns a list of all defined face names.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1175 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1176
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1177 @defun copy-face old-face new-name &optional frame new-frame
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1178 This function defines the face @var{new-name} as a copy of the existing
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1179 face named @var{old-face}. It creates the face @var{new-name} if that
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1180 doesn't already exist.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1181
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1182 If the optional argument @var{frame} is given, this function applies
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1183 only to that frame. Otherwise it applies to each frame individually,
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1184 copying attributes from @var{old-face} in each frame to @var{new-face}
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1185 in the same frame.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1186
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1187 If the optional argument @var{new-frame} is given, then @code{copy-face}
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1188 copies the attributes of @var{old-face} in @var{frame} to @var{new-name}
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1189 in @var{new-frame}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1190 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1191
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1192 You can modify the attributes of an existing face with the following
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1193 functions. If you specify @var{frame}, they affect just that frame;
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1194 otherwise, they affect all frames as well as the defaults that apply to
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1195 new frames.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1196
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1197 @defun set-face-foreground face color &optional frame
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1198 @defunx set-face-background face color &optional frame
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8925
diff changeset
1199 These functions set the foreground (or background, respectively) color
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8925
diff changeset
1200 of face @var{face} to @var{color}. The argument @var{color} should be a
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1201 string, the name of a color.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1202
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1203 Certain shades of gray are implemented by stipple patterns on
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1204 black-and-white screens.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1205 @end defun
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1206
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1207 @defun set-face-stipple face pattern &optional frame
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1208 This function sets the background stipple pattern of face @var{face} to
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1209 @var{pattern}. The argument @var{pattern} should be the name of a
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1210 stipple pattern defined by the X server, or @code{nil} meaning don't use
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1211 stipple.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1212
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1213 Normally there is no need to pay attention to stipple patterns, because
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1214 they are used automatically to handle certain shades of gray.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1215 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1216
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1217 @defun set-face-font face font &optional frame
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1218 This function sets the font of face @var{face}. The argument @var{font}
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1219 should be a string, either a valid font name for your system or the name
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1220 of an Emacs fontset (@pxref{Fontsets}). Note that if you set the font
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1221 explicitly, the bold and italic attributes cease to have any effect,
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1222 because the precise font that you specified is always used.
18234
2e66f4ee4ca8 Add make-face-bold/italic and unbold/unitalic.
Richard M. Stallman <rms@gnu.org>
parents: 16123
diff changeset
1223 @end defun
2e66f4ee4ca8 Add make-face-bold/italic and unbold/unitalic.
Richard M. Stallman <rms@gnu.org>
parents: 16123
diff changeset
1224
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1225 @defun set-face-bold-p face bold-p &optional frame
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1226 @tindex set-face-bold-p
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1227 This function sets the bold attribute of face @var{face}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1228 Non-@code{nil} means bold; @code{nil} means non-bold.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1229 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1230
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1231 @defun set-face-italic-p face italic-p &optional frame
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1232 @tindex set-face-italic-p
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1233 This function sets the italic attribute of face @var{face}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1234 Non-@code{nil} means italic; @code{nil} means non-italic.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1235 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1236
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1237 @defun set-face-underline-p face underline-p &optional frame
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1238 This function sets the underline attribute of face @var{face}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1239 Non-@code{nil} means do underline; @code{nil} means don't.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1240 @end defun
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1241
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1242 @defun invert-face face &optional frame
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1243 Swap the foreground and background colors of face @var{face}. If the
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1244 face doesn't specify both foreground and background, then its foreground
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8925
diff changeset
1245 and background are set to the default background and foreground,
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8925
diff changeset
1246 respectively.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1247 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1248
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1249 These functions examine the attributes of a face. If you don't
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1250 specify @var{frame}, they refer to the default data for new frames.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1251
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1252 @defun face-foreground face &optional frame
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1253 @defunx face-background face &optional frame
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8925
diff changeset
1254 These functions return the foreground color (or background color,
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8925
diff changeset
1255 respectively) of face @var{face}, as a string.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1256 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1257
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1258 @defun face-stipple face &optional frame
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1259 This function returns the name of the background stipple pattern of face
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1260 @var{face}, or @code{nil} if it doesn't have one.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1261 @end defun
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1262
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1263 @defun face-font face &optional frame
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1264 This function returns the name of the font of face @var{face}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1265 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1266
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1267 @defun face-bold-p face &optional frame
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1268 @tindex face-bold-p
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1269 This function returns the bold attribute of face @var{face}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1270 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1271
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1272 @defun face-italic-p face &optional frame
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1273 @tindex face-italic-p
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1274 This function returns the italic attribute of face @var{face}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1275 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1276
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1277 @defun face-underline-p face &optional frame
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1278 This function returns the underline attribute of face @var{face}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1279 @end defun
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1280
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1281 @defun face-id face
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1282 This function returns the face number of face @var{face}.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1283 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1284
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1285 @defun face-documentation face
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1286 @tindex face-documentation
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1287 This function returns the documentation string of face @var{face}, or
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1288 @code{nil} if none was specified for it.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1289 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1290
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1291 @defun face-equal face1 face2 &optional frame
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1292 This returns @code{t} if the faces @var{face1} and @var{face2} have the
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1293 same attributes for display.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1294 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1295
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1296 @defun face-differs-from-default-p face &optional frame
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1297 This returns @code{t} if the face @var{face} displays differently from
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1298 the default face. A face is considered to be ``the same'' as the normal
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1299 face if each attribute is either the same as that of the default face or
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1300 @code{nil} (meaning to inherit from the default).
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1301 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1302
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1303 @defvar region-face
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1304 This variable's value specifies the face number to use to display characters
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1305 in the region when it is active (in Transient Mark mode only). The face
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1306 thus specified takes precedence over all faces that come from text
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1307 properties and overlays, for characters in the region. @xref{The Mark},
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1308 for more information about Transient Mark mode.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1309
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1310 Normally, the value is the face number of the face named @code{region}.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1311 @end defvar
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1312
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1313 @tindex frame-update-face-colors
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1314 @defun frame-update-face-colors frame
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1315 This function updates the way faces display on @var{frame}, for a change
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1316 in @var{frame}'s foreground or background color.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1317 @end defun
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1318
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1319 @node Blinking
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1320 @section Blinking Parentheses
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1321 @cindex parenthesis matching
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1322 @cindex blinking
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1323 @cindex balancing parentheses
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1324 @cindex close parenthesis
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1325
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1326 This section describes the mechanism by which Emacs shows a matching
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1327 open parenthesis when the user inserts a close parenthesis.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1328
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1329 @defvar blink-paren-function
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1330 The value of this variable should be a function (of no arguments) to
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1331 be called whenever a character with close parenthesis syntax is inserted.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1332 The value of @code{blink-paren-function} may be @code{nil}, in which
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1333 case nothing is done.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1334 @end defvar
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1335
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1336 @defopt blink-matching-paren
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1337 If this variable is @code{nil}, then @code{blink-matching-open} does
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1338 nothing.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1339 @end defopt
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1340
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1341 @defopt blink-matching-paren-distance
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1342 This variable specifies the maximum distance to scan for a matching
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1343 parenthesis before giving up.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1344 @end defopt
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1345
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1346 @defopt blink-matching-delay
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1347 This variable specifies the number of seconds for the cursor to remain
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1348 at the matching parenthesis. A fraction of a second often gives
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1349 good results, but the default is 1, which works on all systems.
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1350 @end defopt
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1351
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1352 @deffn Command blink-matching-open
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1353 This function is the default value of @code{blink-paren-function}. It
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1354 assumes that point follows a character with close parenthesis syntax and
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1355 moves the cursor momentarily to the matching opening character. If that
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1356 character is not already on the screen, it displays the character's
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1357 context in the echo area. To avoid long delays, this function does not
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1358 search farther than @code{blink-matching-paren-distance} characters.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1359
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1360 Here is an example of calling this function explicitly.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1361
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1362 @smallexample
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1363 @group
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1364 (defun interactive-blink-matching-open ()
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1365 @c Do not break this line! -- rms.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1366 @c The first line of a doc string
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1367 @c must stand alone.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1368 "Indicate momentarily the start of sexp before point."
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1369 (interactive)
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1370 @end group
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1371 @group
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1372 (let ((blink-matching-paren-distance
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1373 (buffer-size))
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1374 (blink-matching-paren t))
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1375 (blink-matching-open)))
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1376 @end group
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1377 @end smallexample
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1378 @end deffn
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1379
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1380 @node Inverse Video
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1381 @section Inverse Video
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1382 @cindex Inverse Video
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1383
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1384 @defopt inverse-video
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1385 @cindex highlighting
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1386 This variable controls whether Emacs uses inverse video for all text
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1387 on the screen. Non-@code{nil} means yes, @code{nil} means no. The
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1388 default is @code{nil}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1389 @end defopt
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1390
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1391 @defopt mode-line-inverse-video
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1392 This variable controls the use of inverse video for mode lines. If it
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1393 is non-@code{nil}, then mode lines are displayed in inverse video.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1394 Otherwise, mode lines are displayed normally, just like text. The
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1395 default is @code{t}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1396
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1397 For window frames, this displays mode lines using the face named
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1398 @code{modeline}, which is normally the inverse of the default face
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1399 unless you change it.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1400 @end defopt
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1401
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1402 @node Usual Display
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1403 @section Usual Display Conventions
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1404
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1405 The usual display conventions define how to display each character
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1406 code. You can override these conventions by setting up a display table
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1407 (@pxref{Display Tables}). Here are the usual display conventions:
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1408
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1409 @itemize @bullet
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1410 @item
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1411 Character codes 32 through 126 map to glyph codes 32 through 126.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1412 Normally this means they display as themselves.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1413
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1414 @item
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1415 Character code 9 is a horizontal tab. It displays as whitespace
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1416 up to a position determined by @code{tab-width}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1417
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1418 @item
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1419 Character code 10 is a newline.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1420
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1421 @item
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1422 All other codes in the range 0 through 31, and code 127, display in one
9009
7cdfcd5e71ff entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8925
diff changeset
1423 of two ways according to the value of @code{ctl-arrow}. If it is
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1424 non-@code{nil}, these codes map to sequences of two glyphs, where the
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1425 first glyph is the @sc{ASCII} code for @samp{^}. (A display table can
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1426 specify a glyph to use instead of @samp{^}.) Otherwise, these codes map
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1427 just like the codes in the range 128 to 255.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1428
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1429 @item
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1430 Character codes 128 through 255 map to sequences of four glyphs, where
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1431 the first glyph is the @sc{ASCII} code for @samp{\}, and the others are
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1432 digit characters representing the character code in octal. (A display
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1433 table can specify a glyph to use instead of @samp{\}.)
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1434
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1435 @item
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1436 Multibyte character codes above 256 are displayed as themselves, or as a
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1437 question mark or empty box if the terminal cannot display that
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1438 character.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1439 @end itemize
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1440
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1441 The usual display conventions apply even when there is a display
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1442 table, for any character whose entry in the active display table is
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1443 @code{nil}. Thus, when you set up a display table, you need only
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1444 specify the characters for which you want special behavior.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1445
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1446 These variables affect the way certain characters are displayed on the
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1447 screen. Since they change the number of columns the characters occupy,
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1448 they also affect the indentation functions. These variables also affect
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1449 how the mode line is displayed; if you want to force redisplay of the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1450 mode line using the new values, call the function
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1451 @code{force-mode-line-update} (@pxref{Mode Line Format}).
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1452
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1453 @defopt ctl-arrow
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1454 @cindex control characters in display
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1455 This buffer-local variable controls how control characters are
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1456 displayed. If it is non-@code{nil}, they are displayed as a caret
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1457 followed by the character: @samp{^A}. If it is @code{nil}, they are
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1458 displayed as a backslash followed by three octal digits: @samp{\001}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1459 @end defopt
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1460
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1461 @c Following may have overfull hbox.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1462 @defvar default-ctl-arrow
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1463 The value of this variable is the default value for @code{ctl-arrow} in
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1464 buffers that do not override it. @xref{Default Value}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1465 @end defvar
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1466
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1467 @defopt tab-width
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1468 The value of this variable is the spacing between tab stops used for
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1469 displaying tab characters in Emacs buffers. The default is 8. Note
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1470 that this feature is completely independent of the user-settable tab
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1471 stops used by the command @code{tab-to-tab-stop}. @xref{Indent Tabs}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1472 @end defopt
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1473
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1474 @node Display Tables
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1475 @section Display Tables
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1476
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1477 @cindex display table
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1478 You can use the @dfn{display table} feature to control how all possible
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1479 character codes display on the screen. This is useful for displaying
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1480 European languages that have letters not in the @sc{ASCII} character
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1481 set.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1482
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1483 The display table maps each character code into a sequence of
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1484 @dfn{glyphs}, each glyph being an image that takes up one character
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1485 position on the screen. You can also define how to display each glyph
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1486 on your terminal, using the @dfn{glyph table}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1487
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1488 Display tables affect how the mode line is displayed; if you want to
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1489 force redisplay of the mode line using a new display table, call
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1490 @code{force-mode-line-update} (@pxref{Mode Line Format}).
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1491
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1492 @menu
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1493 * Display Table Format:: What a display table consists of.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1494 * Active Display Table:: How Emacs selects a display table to use.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1495 * Glyphs:: How to define a glyph, and what glyphs mean.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1496 @end menu
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1497
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1498 @node Display Table Format
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1499 @subsection Display Table Format
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1500
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1501 A display table is actually a char-table (@pxref{Char-Tables}) with
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1502 @code{display-table} as its subtype.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1503
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1504 @defun make-display-table
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1505 This creates and returns a display table. The table initially has
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1506 @code{nil} in all elements.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1507 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1508
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1509 The ordinary elements of the display table are indexed by character
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1510 codes; the element at index @var{c} says how to display the character
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1511 code @var{c}. The value should be @code{nil} or a vector of glyph
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1512 values (@pxref{Glyphs}). If an element is @code{nil}, it says to
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1513 display that character according to the usual display conventions
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1514 (@pxref{Usual Display}).
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
1515
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
1516 If you use the display table to change the display of newline
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 10211
diff changeset
1517 characters, the whole buffer will be displayed as one long ``line.''
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1518
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1519 The display table also has six ``extra slots'' which serve special
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1520 purposes. Here is a table of their meanings; @code{nil} in any slot
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1521 means to use the default for that slot, as stated below.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1522
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1523 @table @asis
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1524 @item 0
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1525 The glyph for the end of a truncated screen line (the default for this
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1526 is @samp{$}). @xref{Glyphs}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1527 @item 1
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1528 The glyph for the end of a continued line (the default is @samp{\}).
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1529 @item 2
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1530 The glyph for indicating a character displayed as an octal character
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1531 code (the default is @samp{\}).
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1532 @item 3
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1533 The glyph for indicating a control character (the default is @samp{^}).
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1534 @item 4
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1535 A vector of glyphs for indicating the presence of invisible lines (the
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1536 default is @samp{...}). @xref{Selective Display}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1537 @item 5
8925
b05788fd41f0 *** empty log message ***
Jim Blandy <jimb@redhat.com>
parents: 8096
diff changeset
1538 The glyph used to draw the border between side-by-side windows (the
b05788fd41f0 *** empty log message ***
Jim Blandy <jimb@redhat.com>
parents: 8096
diff changeset
1539 default is @samp{|}). @xref{Splitting Windows}.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1540 @end table
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1541
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1542 For example, here is how to construct a display table that mimics the
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1543 effect of setting @code{ctl-arrow} to a non-@code{nil} value:
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1544
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1545 @example
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1546 (setq disptab (make-display-table))
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1547 (let ((i 0))
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1548 (while (< i 32)
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1549 (or (= i ?\t) (= i ?\n)
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1550 (aset disptab i (vector ?^ (+ i 64))))
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1551 (setq i (1+ i)))
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1552 (aset disptab 127 (vector ?^ ??)))
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1553 @end example
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1554
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1555 @defun display-table-slot display-table slot
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1556 @tindex display-table-slot
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1557 This function returns the value of the extra slot @var{slot} of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1558 @var{display-table}. The argument @var{slot} may be a number from 0 to
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1559 5 inclusive, or a slot name (symbol). Valid symbols are
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1560 @code{truncation}, @code{wrap}, @code{escape}, @code{control},
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1561 @code{selective-display}, and @code{vertical-border}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1562 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1563
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1564 @defun set-display-table-slot display-table slot value
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1565 @tindex set-display-table-slot
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1566 This function stores @var{value} in the extra slot @var{slot} of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1567 @var{display-table}. The argument @var{slot} may be a number from 0 to
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1568 5 inclusive, or a slot name (symbol). Valid symbols are
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1569 @code{truncation}, @code{wrap}, @code{escape}, @code{control},
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1570 @code{selective-display}, and @code{vertical-border}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1571 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1572
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1573 @node Active Display Table
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1574 @subsection Active Display Table
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1575 @cindex active display table
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1576
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1577 Each window can specify a display table, and so can each buffer. When
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1578 a buffer @var{b} is displayed in window @var{w}, display uses the
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1579 display table for window @var{w} if it has one; otherwise, the display
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1580 table for buffer @var{b} if it has one; otherwise, the standard display
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1581 table if any. The display table chosen is called the @dfn{active}
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1582 display table.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1583
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1584 @defun window-display-table window
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1585 This function returns @var{window}'s display table, or @code{nil}
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1586 if @var{window} does not have an assigned display table.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1587 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1588
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1589 @defun set-window-display-table window table
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1590 This function sets the display table of @var{window} to @var{table}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1591 The argument @var{table} should be either a display table or
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1592 @code{nil}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1593 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1594
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1595 @defvar buffer-display-table
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1596 This variable is automatically buffer-local in all buffers; its value in
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1597 a particular buffer specifies the display table for that buffer. If it
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1598 is @code{nil}, that means the buffer does not have an assigned display
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1599 table.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1600 @end defvar
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1601
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1602 @defvar standard-display-table
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1603 This variable's value is the default display table, used whenever a
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1604 window has no display table and neither does the buffer displayed in
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1605 that window. This variable is @code{nil} by default.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1606 @end defvar
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1607
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1608 If there is no display table to use for a particular window---that is,
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1609 if the window specifies none, its buffer specifies none, and
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1610 @code{standard-display-table} is @code{nil}---then Emacs uses the usual
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1611 display conventions for all character codes in that window. @xref{Usual
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1612 Display}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1613
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1614 @node Glyphs
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1615 @subsection Glyphs
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1616
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1617 @cindex glyph
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1618 A @dfn{glyph} is a generalization of a character; it stands for an
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1619 image that takes up a single character position on the screen. Glyphs
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1620 are represented in Lisp as integers, just as characters are.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1621
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1622 @cindex glyph table
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1623 The meaning of each integer, as a glyph, is defined by the glyph
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1624 table, which is the value of the variable @code{glyph-table}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1625
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1626 @defvar glyph-table
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1627 The value of this variable is the current glyph table. It should be a
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1628 vector; the @var{g}th element defines glyph code @var{g}. If the value
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1629 is @code{nil} instead of a vector, then all glyphs are simple (see
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1630 below).
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1631 @end defvar
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1632
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1633 Here are the possible types of elements in the glyph table:
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1634
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1635 @table @asis
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1636 @item @var{string}
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1637 Send the characters in @var{string} to the terminal to output
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1638 this glyph. This alternative is available on character terminals,
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1639 but not under a window system.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1640
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1641 @item @var{integer}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1642 Define this glyph code as an alias for glyph code @var{integer}. You
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1643 can use an alias to specify a face code for the glyph; see below.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1644
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1645 @item @code{nil}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1646 This glyph is simple. On an ordinary terminal, the glyph code mod
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1647 524288 is the character to output. In a window system, the glyph code
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1648 mod 524288 is the character to output, and the glyph code divided by
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1649 524288 specifies the face number (@pxref{Face Functions}) to use while
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1650 outputting it. (524288 is
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1651 @ifinfo
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1652 2**19.)
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1653 @end ifinfo
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1654 @tex
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1655 $2^{19}$.)
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1656 @end tex
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1657 @xref{Faces}.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1658 @end table
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1659
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1660 If a glyph code is greater than or equal to the length of the glyph
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1661 table, that code is automatically simple.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1662
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1663 @node Beeping
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1664 @section Beeping
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1665 @cindex beeping
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1666 @cindex bell
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1667
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1668 This section describes how to make Emacs ring the bell (or blink the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1669 screen) to attract the user's attention. Be conservative about how
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1670 often you do this; frequent bells can become irritating. Also be
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1671 careful not to use just beeping when signaling an error is more
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1672 appropriate. (@xref{Errors}.)
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1673
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1674 @defun ding &optional do-not-terminate
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1675 @cindex keyboard macro termination
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1676 This function beeps, or flashes the screen (see @code{visible-bell} below).
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1677 It also terminates any keyboard macro currently executing unless
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1678 @var{do-not-terminate} is non-@code{nil}.
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1679 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1680
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1681 @defun beep &optional do-not-terminate
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1682 This is a synonym for @code{ding}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1683 @end defun
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1684
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1685 @defopt visible-bell
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1686 This variable determines whether Emacs should flash the screen to
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1687 represent a bell. Non-@code{nil} means yes, @code{nil} means no. This
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1688 is effective on a window system, and on a character-only terminal
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1689 provided the terminal's Termcap entry defines the visible bell
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1690 capability (@samp{vb}).
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1691 @end defopt
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1692
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1693 @defvar ring-bell-function
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1694 @tindex ring-bell-function
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1695 If this is non-@code{nil}, it specifies how Emacs should ``ring the
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1696 bell.'' Its value should be a function of no arguments.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1697 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1698
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1699 @node Window Systems
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1700 @section Window Systems
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1701
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1702 Emacs works with several window systems, most notably the X Window
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1703 System. Both Emacs and X use the term ``window'', but use it
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1704 differently. An Emacs frame is a single window as far as X is
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1705 concerned; the individual Emacs windows are not known to X at all.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1706
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1707 @defvar window-system
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1708 This variable tells Lisp programs what window system Emacs is running
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1709 under. The possible values are
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1710
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1711 @table @code
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1712 @item x
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1713 @cindex X Window System
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1714 Emacs is displaying using X.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1715 @item pc
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1716 Emacs is displaying using MSDOS.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1717 @item w32
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1718 Emacs is displaying using Windows NT or Windows 95.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1719 @item nil
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1720 Emacs is using a character-based terminal.
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1721 @end table
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1722 @end defvar
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1723
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1724 @defvar window-setup-hook
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1725 This variable is a normal hook which Emacs runs after handling the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1726 initialization files. Emacs runs this hook after it has completed
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 18234
diff changeset
1727 loading your @file{.emacs} file, the default initialization file (if
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1728 any), and the terminal-specific Lisp code, and running the hook
6598
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1729 @code{term-setup-hook}.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1730
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1731 This hook is used for internal purposes: setting up communication with
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1732 the window system, and creating the initial window. Users should not
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1733 interfere with it.
db2685239be9 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1734 @end defvar