|
428
|
1
|
|
3387
|
2 @c FIXME -- we demand a detail menu!
|
|
|
3
|
|
428
|
4 @node Customization, Quitting, Emulation, Top
|
|
|
5 @chapter Customization
|
|
|
6 @cindex customization
|
|
|
7
|
|
|
8 This chapter talks about various topics relevant to adapting the
|
|
|
9 behavior of Emacs in minor ways.
|
|
|
10
|
|
|
11 All kinds of customization affect only the particular Emacs job that you
|
|
442
|
12 do them in. They are completely lost when you kill the Emacs job, and
|
|
|
13 have no effect on other Emacs jobs you may run at the same time or
|
|
|
14 later. The only way an Emacs job can affect anything outside of it is
|
|
|
15 by writing a file; in particular, the only way to make a customization
|
|
|
16 `permanent' is to put something in your init file or other appropriate
|
|
|
17 file to do the customization in each session. @xref{Init File}.
|
|
428
|
18
|
|
|
19 @menu
|
|
|
20 * Minor Modes:: Each minor mode is one feature you can turn on
|
|
|
21 independently of any others.
|
|
775
|
22 * Behaviors:: Like minor modes, behaviors are independent of other
|
|
|
23 features, but behaviors are usually enabled globally,
|
|
|
24 while minor modes are per-buffer and often temporary.
|
|
428
|
25 * Variables:: Many Emacs commands examine Emacs variables
|
|
|
26 to decide what to do; by setting variables,
|
|
|
27 you can control their functioning.
|
|
|
28 * Keyboard Macros:: A keyboard macro records a sequence of keystrokes
|
|
|
29 to be replayed with a single command.
|
|
|
30 * Key Bindings:: The keymaps say what command each key runs.
|
|
|
31 By changing them, you can "redefine keys".
|
|
|
32 * Syntax:: The syntax table controls how words and expressions
|
|
|
33 are parsed.
|
|
442
|
34 * Init File:: How to write common customizations in the init file.
|
|
|
35 * Audible Bell:: Changing how Emacs sounds the bell.
|
|
|
36 * Faces:: Changing the fonts and colors of a region of text.
|
|
|
37 * Frame Components:: Controlling the presence and positions of the
|
|
|
38 menubar, toolbars, and gutters.
|
|
440
|
39 * X Resources:: X resources controlling various aspects of the
|
|
428
|
40 behavior of XEmacs.
|
|
|
41 @end menu
|
|
|
42
|
|
|
43 @node Minor Modes
|
|
|
44 @section Minor Modes
|
|
|
45 @cindex minor modes
|
|
|
46
|
|
|
47 @cindex mode line
|
|
2736
|
48 Minor modes are common options which may be useful in many major
|
|
|
49 modes, but which may need to be enabled or disabled independently of the
|
|
|
50 major mode. (This may be because user preferences for the feature vary,
|
|
|
51 or because the feature is sometimes more of a hindrance than an aid
|
|
|
52 depending on the specific content of the buffer.) For example, Auto
|
|
|
53 Fill mode is a minor mode in which @key{SPC} automatically breaks lines
|
|
|
54 between words at the right margin
|
|
|
55 as you type. Minor modes are independent of each other and of
|
|
428
|
56 the selected major mode. Most minor modes inform you in the mode line
|
|
|
57 when they are on; for example, @samp{Fill} in the mode line means that
|
|
|
58 Auto Fill mode is on.
|
|
|
59
|
|
|
60 Append @code{-mode} to the name of a minor mode to get the name of a
|
|
|
61 command function that turns the mode on or off. Thus, the command to
|
|
|
62 enable or disable Auto Fill mode is called @kbd{M-x auto-fill-mode}. These
|
|
|
63 commands are usually invoked with @kbd{M-x}, but you can bind keys to them
|
|
|
64 if you wish. With no argument, the function turns the mode on if it was
|
|
2736
|
65 off and off if it was on. This is called @dfn{toggling}. A positive
|
|
428
|
66 argument always turns the mode on, and an explicit zero argument or a
|
|
|
67 negative argument always turns it off.
|
|
|
68
|
|
2736
|
69 @c #### maybe this list should be extended and moved to its own node?
|
|
|
70
|
|
428
|
71 @cindex Auto Fill mode
|
|
|
72 @findex auto-fill-mode
|
|
|
73 Auto Fill mode allows you to enter filled text without breaking lines
|
|
|
74 explicitly. Emacs inserts newlines as necessary to prevent lines from
|
|
|
75 becoming too long. @xref{Filling}.
|
|
|
76
|
|
2736
|
77 @cindex Filladapt mode
|
|
|
78 @findex filladapt-mode
|
|
|
79 Filladapt mode is an extension of Auto Fill mode which recognizes
|
|
|
80 @dfn{line prefixes} and automatically prepends them when automatically
|
|
|
81 breaking lines. Filladapt mode is smart enough to recognize common
|
|
|
82 idioms for bullets (e.g., leading isolated hyphens) and enumerated
|
|
|
83 paragraphs, and insert appropriate leading whitespace (and omit the
|
|
|
84 bullet!) It also does a good job of recognizing common quotation styles
|
|
|
85 in email. Filladapt mode must be enabled in addition to Auto Fill
|
|
|
86 mode. If Auto Fill mode is disabled, Filladapt mode will be
|
|
|
87 inactivated, but the indicator will remain in the modeline.
|
|
|
88
|
|
428
|
89 @cindex Overwrite mode
|
|
|
90 @findex overwrite-mode
|
|
|
91 Overwrite mode causes ordinary printing characters to replace existing
|
|
|
92 text instead of moving it to the right. For example, if point is in
|
|
|
93 front of the @samp{B} in @samp{FOOBAR}, and you type a @kbd{G} in Overwrite
|
|
|
94 mode, it changes to @samp{FOOGAR}, instead of @samp{FOOGBAR}.@refill
|
|
|
95
|
|
2736
|
96 @cindex Pending Delete mode
|
|
|
97 @findex pending-delete-mode
|
|
|
98 Pending Delete mode cause buffer insertions and deletions to replace the
|
|
|
99 active region (with nothing, for deletions). This is the common
|
|
|
100 behavior in most modern programs, but conflicts with the ``lightweight
|
|
|
101 selections'' used in the X Window System.
|
|
|
102
|
|
428
|
103 @cindex Abbrev mode
|
|
|
104 @findex abbrev-mode
|
|
|
105 Abbrev mode allows you to define abbreviations that automatically expand
|
|
|
106 as you type them. For example, @samp{amd} might expand to @samp{abbrev
|
|
|
107 mode}. @xref{Abbrevs}, for full information.
|
|
|
108
|
|
775
|
109 @c Updated for 21.5.6 2002/03/13 sjt
|
|
|
110 @node Behaviors
|
|
|
111 @section Behaviors
|
|
|
112 @cindex behavior
|
|
|
113
|
|
2736
|
114 @dfn{Behaviors} are an alternative interface to minor modes. The toggle
|
|
|
115 interface emphasizes the case-specific nature of a minor mode: use it
|
|
|
116 with @emph{this} major mode but not in @emph{those} buffers. However,
|
|
|
117 this is inconvenient for behavior that depends on user preference.
|
|
|
118 For example, someone who discovers filladapt and really
|
|
775
|
119 likes it must toggle it separately in each buffer. On the other hand,
|
|
|
120 after trying it for a while she might like to disable it everywhere,
|
|
2736
|
121 having decided it doesn't work very well for her.
|
|
|
122
|
|
|
123 Use of mode hooks will invoke the minor mode automatically in the
|
|
|
124 future, but this is inconvenient (you must switch tasks to editing the
|
|
|
125 init file) and doesn't help with existing buffers in the session. The
|
|
|
126 behavior interface addresses this problem. The command
|
|
|
127 @code{enable-behavior} prompts (with completion) for a registered
|
|
|
128 behavior (denoted by a symbol), and enables it. Conversely,
|
|
|
129 @code{disable-behavior} prompts for a behavior, and disables it.
|
|
|
130
|
|
|
131 @c #### This belongs in the Lispref in the description of creating
|
|
|
132 @c packages or in customize or both.
|
|
|
133
|
|
|
134 @c The package developer will register behaviors with XEmacs. Then the
|
|
|
135 @c user invokes the @code{enable-behavior} and @code{disable-behavior}
|
|
|
136 @c functions to enable or disable a given behavior. The behavior registry
|
|
|
137 @c was introduced in XEmacs 21.5.6.
|
|
|
138 @c
|
|
|
139 @c @defun enable-behavior behavior &optionl force
|
|
|
140 @c Called interactively, prompt the user, read a behavior symbol name with
|
|
|
141 @c completion for @var{behavior}, and take @var{force} from the prefix
|
|
|
142 @c argument. Then enable the behavior registered under the symbol
|
|
|
143 @c @var{behavior}.
|
|
|
144 @c
|
|
|
145 @c The optional argument @var{force} is unimplemented in 21.5.6.
|
|
|
146 @c @end defun
|
|
|
147 @c
|
|
|
148 @c @defun disable-behavior behavior &optional force
|
|
|
149 @c Called interactively, prompt the user, read a behavior symbol name with
|
|
|
150 @c completion for @var{behavior}, and take @var{force} from the prefix
|
|
|
151 @c argument. Then disable the behavior registered under the symbol
|
|
|
152 @c @var{behavior}.
|
|
|
153 @c
|
|
|
154 @c The optional argument @var{force} is unimplemented in 21.5.6.
|
|
|
155 @c @end defun
|
|
775
|
156
|
|
|
157
|
|
428
|
158 @node Variables
|
|
|
159 @section Variables
|
|
|
160 @cindex variable
|
|
|
161 @cindex option
|
|
|
162
|
|
|
163 A @dfn{variable} is a Lisp symbol which has a value. Variable names
|
|
|
164 can contain any characters, but by convention they are words separated
|
|
|
165 by hyphens. A variable can also have a documentation string, which
|
|
|
166 describes what kind of value it should have and how the value will be
|
|
|
167 used.
|
|
|
168
|
|
|
169 Lisp allows any variable to have any kind of value, but most variables
|
|
|
170 that Emacs uses require a value of a certain type. Often the value has
|
|
|
171 to be a string or a number. Sometimes we say that a certain feature is
|
|
|
172 turned on if a variable is ``non-@code{nil},'' meaning that if the
|
|
|
173 variable's value is @code{nil}, the feature is off, but the feature is
|
|
|
174 on for @i{any} other value. The conventional value to turn on the
|
|
|
175 feature---since you have to pick one particular value when you set the
|
|
|
176 variable---is @code{t}.
|
|
|
177
|
|
|
178 Emacs uses many Lisp variables for internal recordkeeping, as any Lisp
|
|
|
179 program must, but the most interesting variables for you are the ones that
|
|
|
180 exist for the sake of customization. Emacs does not (usually) change the
|
|
|
181 values of these variables; instead, you set the values, and thereby alter
|
|
|
182 and control the behavior of certain Emacs commands. These variables are
|
|
|
183 called @dfn{options}. Most options are documented in this manual and
|
|
|
184 appear in the Variable Index (@pxref{Variable Index}).
|
|
|
185
|
|
|
186 One example of a variable which is an option is @code{fill-column}, which
|
|
|
187 specifies the position of the right margin (as a number of characters from
|
|
|
188 the left margin) to be used by the fill commands (@pxref{Filling}).
|
|
|
189
|
|
|
190 @menu
|
|
|
191 * Examining:: Examining or setting one variable's value.
|
|
|
192 * Easy Customization:: Convenient and easy customization of variables.
|
|
|
193 * Edit Options:: Examining or editing list of all variables' values.
|
|
|
194 * Locals:: Per-buffer values of variables.
|
|
|
195 * File Variables:: How files can specify variable values.
|
|
|
196 @end menu
|
|
|
197
|
|
|
198 @node Examining
|
|
|
199 @subsection Examining and Setting Variables
|
|
|
200 @cindex setting variables
|
|
|
201
|
|
|
202 @table @kbd
|
|
|
203 @item C-h v
|
|
|
204 @itemx M-x describe-variable
|
|
|
205 Print the value and documentation of a variable.
|
|
|
206 @findex set-variable
|
|
|
207 @item M-x set-variable
|
|
|
208 Change the value of a variable.
|
|
|
209 @end table
|
|
|
210
|
|
|
211 @kindex C-h v
|
|
|
212 @findex describe-variable
|
|
|
213 To examine the value of a single variable, use @kbd{C-h v}
|
|
|
214 (@code{describe-variable}), which reads a variable name using the
|
|
|
215 minibuffer, with completion. It prints both the value and the
|
|
|
216 documentation of the variable.
|
|
|
217
|
|
|
218 @example
|
|
|
219 C-h v fill-column @key{RET}
|
|
|
220 @end example
|
|
|
221
|
|
|
222 @noindent
|
|
|
223 prints something like:
|
|
|
224
|
|
|
225 @smallexample
|
|
|
226 fill-column's value is 75
|
|
|
227
|
|
|
228 Documentation:
|
|
|
229 *Column beyond which automatic line-wrapping should happen.
|
|
|
230 Automatically becomes local when set in any fashion.
|
|
|
231 @end smallexample
|
|
|
232
|
|
|
233 @cindex option
|
|
|
234 @noindent
|
|
|
235 The star at the beginning of the documentation indicates that this variable
|
|
|
236 is an option. @kbd{C-h v} is not restricted to options; it allows any
|
|
|
237 variable name.
|
|
|
238
|
|
|
239 @findex set-variable
|
|
|
240 If you know which option you want to set, you can use @kbd{M-x
|
|
|
241 set-variable} to set it. This prompts for the variable name in the
|
|
|
242 minibuffer (with completion), and then prompts for a Lisp expression for the
|
|
|
243 new value using the minibuffer a second time. For example,
|
|
|
244
|
|
|
245 @example
|
|
|
246 M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET}
|
|
|
247 @end example
|
|
|
248
|
|
|
249 @noindent
|
|
|
250 sets @code{fill-column} to 75, as if you had executed the Lisp expression
|
|
|
251 @code{(setq fill-column 75)}.
|
|
|
252
|
|
|
253 Setting variables in this way, like all means of customizing Emacs
|
|
|
254 except where explicitly stated, affects only the current Emacs session.
|
|
|
255
|
|
|
256 @node Easy Customization
|
|
|
257 @subsection Easy Customization Interface
|
|
|
258
|
|
|
259 @findex customize
|
|
|
260 @cindex customization buffer
|
|
|
261 A convenient way to find the user option variables that you want to
|
|
600
|
262 change, and then change them, is with @kbd{C-h C} (@code{customize}).
|
|
|
263 This command creates a @dfn{customization buffer} with which you can
|
|
|
264 browse through the Emacs user options in a logically organized
|
|
|
265 structure, then edit and set their values. You can also use the
|
|
|
266 customization buffer to save settings permanently. (Not all Emacs user
|
|
|
267 options are included in this structure as of yet, but we are adding the
|
|
|
268 rest.)
|
|
428
|
269
|
|
|
270 @menu
|
|
|
271 * Groups: Customization Groups.
|
|
|
272 How options are classified in a structure.
|
|
|
273 * Changing an Option:: How to edit a value and set an option.
|
|
|
274 * Face Customization:: How to edit the attributes of a face.
|
|
|
275 * Specific Customization:: Making a customization buffer for specific
|
|
|
276 options, faces, or groups.
|
|
|
277 @end menu
|
|
|
278
|
|
|
279 @node Customization Groups
|
|
|
280 @subsubsection Customization Groups
|
|
|
281 @cindex customization groups
|
|
|
282
|
|
|
283 For customization purposes, user options are organized into
|
|
|
284 @dfn{groups} to help you find them. Groups are collected into bigger
|
|
|
285 groups, all the way up to a master group called @code{Emacs}.
|
|
|
286
|
|
602
|
287 @kbd{C-h C} (@code{customize}) creates a customization buffer that
|
|
600
|
288 shows the top-level @code{Emacs} group and the second-level groups
|
|
|
289 immediately under it. It looks like this, in part:
|
|
428
|
290
|
|
|
291 @smallexample
|
|
|
292 /- Emacs group: ---------------------------------------------------\
|
|
|
293 [State]: visible group members are all at standard settings.
|
|
|
294 Customization of the One True Editor.
|
|
|
295 See also [Manual].
|
|
|
296
|
|
|
297 [Open] Editing group
|
|
|
298 Basic text editing facilities.
|
|
|
299
|
|
|
300 [Open] External group
|
|
|
301 Interfacing to external utilities.
|
|
|
302
|
|
|
303 @var{more second-level groups}
|
|
|
304
|
|
|
305 \- Emacs group end ------------------------------------------------/
|
|
|
306
|
|
|
307 @end smallexample
|
|
|
308
|
|
|
309 @noindent
|
|
|
310 This says that the buffer displays the contents of the @code{Emacs}
|
|
|
311 group. The other groups are listed because they are its contents. But
|
|
|
312 they are listed differently, without indentation and dashes, because
|
|
|
313 @emph{their} contents are not included. Each group has a single-line
|
|
|
314 documentation string; the @code{Emacs} group also has a @samp{[State]}
|
|
|
315 line.
|
|
|
316
|
|
|
317 @cindex editable fields (customization buffer)
|
|
|
318 @cindex active fields (customization buffer)
|
|
|
319 Most of the text in the customization buffer is read-only, but it
|
|
|
320 typically includes some @dfn{editable fields} that you can edit. There
|
|
|
321 are also @dfn{active fields}; this means a field that does something
|
|
|
322 when you @dfn{invoke} it. To invoke an active field, either click on it
|
|
|
323 with @kbd{Mouse-1}, or move point to it and type @key{RET}.
|
|
|
324
|
|
|
325 For example, the phrase @samp{[Open]} that appears in a second-level
|
|
|
326 group is an active field. Invoking the @samp{[Open]} field for a group
|
|
|
327 opens up a new customization buffer, which shows that group and its
|
|
|
328 contents. This field is a kind of hypertext link to another group.
|
|
|
329
|
|
|
330 The @code{Emacs} group does not include any user options itself, but
|
|
|
331 other groups do. By examining various groups, you will eventually find
|
|
|
332 the options and faces that belong to the feature you are interested in
|
|
|
333 customizing. Then you can use the customization buffer to set them.
|
|
|
334
|
|
|
335 @findex customize-browse
|
|
|
336 You can view the structure of customization groups on a larger scale
|
|
|
337 with @kbd{M-x customize-browse}. This command creates a special kind of
|
|
|
338 customization buffer which shows only the names of the groups (and
|
|
|
339 options and faces), and their structure.
|
|
|
340
|
|
|
341 In this buffer, you can show the contents of a group by invoking
|
|
|
342 @samp{[+]}. When the group contents are visible, this button changes to
|
|
|
343 @samp{[-]}; invoking that hides the group contents.
|
|
|
344
|
|
|
345 Each group, option or face name in this buffer has an active field
|
|
|
346 which says @samp{[Group]}, @samp{[Option]} or @samp{[Face]}. Invoking
|
|
|
347 that active field creates an ordinary customization buffer showing just
|
|
|
348 that group and its contents, just that option, or just that face.
|
|
|
349 This is the way to set values in it.
|
|
|
350
|
|
|
351 @node Changing an Option
|
|
|
352 @subsubsection Changing an Option
|
|
|
353
|
|
|
354 Here is an example of what a user option looks like in the
|
|
|
355 customization buffer:
|
|
|
356
|
|
|
357 @smallexample
|
|
|
358 Kill Ring Max: [Hide] 30
|
|
|
359 [State]: this option is unchanged from its standard setting.
|
|
|
360 Maximum length of kill ring before oldest elements are thrown away.
|
|
|
361 @end smallexample
|
|
|
362
|
|
|
363 The text following @samp{[Hide]}, @samp{30} in this case, indicates
|
|
|
364 the current value of the option. If you see @samp{[Show]} instead of
|
|
|
365 @samp{[Hide]}, it means that the value is hidden; the customization
|
|
|
366 buffer initially hides values that take up several lines. Invoke
|
|
|
367 @samp{[Show]} to show the value.
|
|
|
368
|
|
|
369 The line after the option name indicates the @dfn{customization state}
|
|
|
370 of the option: in the example above, it says you have not changed the
|
|
|
371 option yet. The word @samp{[State]} at the beginning of this line is
|
|
|
372 active; you can get a menu of various operations by invoking it with
|
|
|
373 @kbd{Mouse-1} or @key{RET}. These operations are essential for
|
|
|
374 customizing the variable.
|
|
|
375
|
|
|
376 The line after the @samp{[State]} line displays the beginning of the
|
|
|
377 option's documentation string. If there are more lines of
|
|
|
378 documentation, this line ends with @samp{[More]}; invoke this to show
|
|
|
379 the full documentation string.
|
|
|
380
|
|
|
381 To enter a new value for @samp{Kill Ring Max}, move point to the value
|
|
|
382 and edit it textually. For example, you can type @kbd{M-d}, then insert
|
|
|
383 another number.
|
|
|
384
|
|
|
385 When you begin to alter the text, you will see the @samp{[State]} line
|
|
|
386 change to say that you have edited the value:
|
|
|
387
|
|
|
388 @smallexample
|
|
|
389 [State]: you have edited the value as text, but not set the option.
|
|
|
390 @end smallexample
|
|
|
391
|
|
|
392 @cindex setting option value
|
|
|
393 Editing the value does not actually set the option variable. To do
|
|
|
394 that, you must @dfn{set} the option. To do this, invoke the word
|
|
|
395 @samp{[State]} and choose @samp{Set for Current Session}.
|
|
|
396
|
|
|
397 The state of the option changes visibly when you set it:
|
|
|
398
|
|
|
399 @smallexample
|
|
|
400 [State]: you have set this option, but not saved it for future sessions.
|
|
|
401 @end smallexample
|
|
|
402
|
|
|
403 You don't have to worry about specifying a value that is not valid;
|
|
|
404 setting the option checks for validity and will not really install an
|
|
|
405 unacceptable value.
|
|
|
406
|
|
|
407 @kindex M-TAB @r{(customization buffer)}
|
|
|
408 @findex widget-complete
|
|
|
409 While editing a value or field that is a file name, directory name,
|
|
|
410 command name, or anything else for which completion is defined, you can
|
|
|
411 type @kbd{M-@key{TAB}} (@code{widget-complete}) to do completion.
|
|
|
412
|
|
|
413 Some options have a small fixed set of possible legitimate values.
|
|
|
414 These options don't let you edit the value textually. Instead, an
|
|
|
415 active field @samp{[Value Menu]} appears before the value; invoke this
|
|
|
416 field to edit the value. For a boolean ``on or off'' value, the active
|
|
|
417 field says @samp{[Toggle]}, and it changes to the other value.
|
|
|
418 @samp{[Value Menu]} and @samp{[Toggle]} edit the buffer; the changes
|
|
|
419 take effect when you use the @samp{Set for Current Session} operation.
|
|
|
420
|
|
|
421 Some options have values with complex structure. For example, the
|
|
|
422 value of @code{load-path} is a list of directories. Here is how it
|
|
|
423 appears in the customization buffer:
|
|
|
424
|
|
|
425 @smallexample
|
|
|
426 Load Path:
|
|
|
427 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/site-lisp
|
|
|
428 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/site-lisp
|
|
|
429 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/leim
|
|
|
430 [INS] [DEL] [Current dir?]: /usr/local/share/emacs/19.34.94/lisp
|
|
|
431 [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp
|
|
|
432 [INS] [DEL] [Current dir?]: /build/emacs/e19/lisp/gnus
|
|
|
433 [INS]
|
|
|
434 [State]: this item has been changed outside the customization buffer.
|
|
|
435 List of directories to search for files to load....
|
|
|
436 @end smallexample
|
|
|
437
|
|
|
438 @noindent
|
|
|
439 Each directory in the list appears on a separate line, and each line has
|
|
|
440 several editable or active fields.
|
|
|
441
|
|
|
442 You can edit any of the directory names. To delete a directory from
|
|
|
443 the list, invoke @samp{[DEL]} on that line. To insert a new directory in
|
|
|
444 the list, invoke @samp{[INS]} at the point where you want to insert it.
|
|
|
445
|
|
|
446 You can also invoke @samp{[Current dir?]} to switch between including
|
|
|
447 a specific named directory in the path, and including @code{nil} in the
|
|
|
448 path. (@code{nil} in a search path means ``try the current
|
|
|
449 directory.'')
|
|
|
450
|
|
|
451 @kindex TAB @r{(customization buffer)}
|
|
|
452 @kindex S-TAB @r{(customization buffer)}
|
|
|
453 @findex widget-forward
|
|
|
454 @findex widget-backward
|
|
|
455 Two special commands, @key{TAB} and @kbd{S-@key{TAB}}, are useful for
|
|
|
456 moving through the customization buffer. @key{TAB}
|
|
|
457 (@code{widget-forward}) moves forward to the next active or editable
|
|
|
458 field; @kbd{S-@key{TAB}} (@code{widget-backward}) moves backward to the
|
|
|
459 previous active or editable field.
|
|
|
460
|
|
|
461 Typing @key{RET} on an editable field also moves forward, just like
|
|
|
462 @key{TAB}. The reason for this is that people have a tendency to type
|
|
|
463 @key{RET} when they are finished editing a field. If you have occasion
|
|
|
464 to insert a newline in an editable field, use @kbd{C-o} or @kbd{C-q
|
|
|
465 C-j},
|
|
|
466
|
|
|
467 @cindex saving option value
|
|
|
468 Setting the option changes its value in the current Emacs session;
|
|
|
469 @dfn{saving} the value changes it for future sessions as well. This
|
|
442
|
470 works by writing code into your init file so as to set the option
|
|
|
471 variable again each time you start Emacs. @xref{Init File}. To save
|
|
|
472 the option, invoke @samp{[State]} and select the @samp{Save for Future
|
|
|
473 Sessions} operation.
|
|
428
|
474
|
|
|
475 You can also restore the option to its standard value by invoking
|
|
|
476 @samp{[State]} and selecting the @samp{Reset} operation. There are
|
|
|
477 actually three reset operations:
|
|
|
478
|
|
|
479 @table @samp
|
|
|
480 @item Reset to Current
|
|
|
481 If you have made some modifications and not yet set the option,
|
|
|
482 this restores the text in the customization buffer to match
|
|
|
483 the actual value.
|
|
|
484
|
|
|
485 @item Reset to Saved
|
|
|
486 This restores the value of the option to the last saved value,
|
|
|
487 and updates the text accordingly.
|
|
|
488
|
|
|
489 @item Reset to Standard Settings
|
|
|
490 This sets the option to its standard value, and updates the text
|
|
|
491 accordingly. This also eliminates any saved value for the option,
|
|
|
492 so that you will get the standard value in future Emacs sessions.
|
|
|
493 @end table
|
|
|
494
|
|
|
495 The state of a group indicates whether anything in that group has been
|
|
|
496 edited, set or saved. You can select @samp{Set for Current Session},
|
|
|
497 @samp{Save for Future Sessions} and the various kinds of @samp{Reset}
|
|
|
498 operation for the group; these operations on the group apply to all
|
|
|
499 options in the group and its subgroups.
|
|
|
500
|
|
|
501 Near the top of the customization buffer there are two lines
|
|
|
502 containing several active fields:
|
|
|
503
|
|
|
504 @smallexample
|
|
|
505 [Set] [Save] [Reset] [Done]
|
|
|
506 @end smallexample
|
|
|
507
|
|
|
508 @noindent
|
|
|
509 Invoking @samp{[Done]} buries this customization buffer. Each of the
|
|
|
510 other fields performs an operation---set, save or reset---on each of the
|
|
|
511 items in the buffer that could meaningfully be set, saved or reset.
|
|
|
512
|
|
|
513 @node Face Customization
|
|
|
514 @subsubsection Customizing Faces
|
|
|
515 @cindex customizing faces
|
|
|
516 @cindex bold font
|
|
|
517 @cindex italic font
|
|
|
518 @cindex fonts and faces
|
|
|
519
|
|
|
520 In addition to user options, some customization groups also include
|
|
|
521 faces. When you show the contents of a group, both the user options and
|
|
|
522 the faces in the group appear in the customization buffer. Here is an
|
|
|
523 example of how a face looks:
|
|
|
524
|
|
|
525 @smallexample
|
|
|
526 Custom Changed Face: (sample)
|
|
|
527 [State]: this face is unchanged from its standard setting.
|
|
|
528 Face used when the customize item has been changed.
|
|
|
529 Parent groups: [Custom Magic Faces]
|
|
|
530 Attributes: [ ] Bold: [Toggle] off (nil)
|
|
|
531 [ ] Italic: [Toggle] off (nil)
|
|
|
532 [ ] Underline: [Toggle] off (nil)
|
|
|
533 [ ] Foreground: white (sample)
|
|
|
534 [ ] Background: blue (sample)
|
|
|
535 [ ] Inverse: [Toggle] off (nil)
|
|
1137
|
536 [ ] Stipple:
|
|
|
537 [ ] Font Family:
|
|
|
538 [ ] Size:
|
|
428
|
539 [ ] Strikethru: off
|
|
|
540 @end smallexample
|
|
|
541
|
|
|
542 Each face attribute has its own line. The @samp{[@var{x}]} field
|
|
|
543 before the attribute name indicates whether the attribute is
|
|
|
544 @dfn{enabled}; @samp{X} means that it is. You can enable or disable the
|
|
|
545 attribute by invoking that field. When the attribute is enabled, you
|
|
|
546 can change the attribute value in the usual ways.
|
|
|
547
|
|
1142
|
548 @xref{Faces}, for description of how @code{face-frob-from-locale-first}
|
|
|
549 variable affects changing @samp{Bold} and @samp{Italic} attributes.
|
|
|
550
|
|
428
|
551 @c Is this true for XEmacs?
|
|
|
552 @c On a black-and-white display, the colors you can use for the
|
|
|
553 @c background are @samp{black}, @samp{white}, @samp{gray}, @samp{gray1},
|
|
|
554 @c and @samp{gray3}. Emacs supports these shades of gray by using
|
|
|
555 @c background stipple patterns instead of a color.
|
|
1137
|
556 @c
|
|
428
|
557 Setting, saving and resetting a face work like the same operations for
|
|
|
558 options (@pxref{Changing an Option}).
|
|
|
559
|
|
|
560 A face can specify different appearances for different types of
|
|
|
561 display. For example, a face can make text red on a color display, but
|
|
|
562 use a bold font on a monochrome display. To specify multiple
|
|
|
563 appearances for a face, select @samp{Show Display Types} in the menu you
|
|
|
564 get from invoking @samp{[State]}.
|
|
|
565
|
|
|
566 @c It would be cool to implement this
|
|
|
567 @c @findex modify-face
|
|
|
568 @c Another more basic way to set the attributes of a specific face is
|
|
|
569 @c with @kbd{M-x modify-face}. This command reads the name of a face, then
|
|
|
570 @c reads the attributes one by one. For the color and stipple attributes,
|
|
|
571 @c the attribute's current value is the default---type just @key{RET} if
|
|
|
572 @c you don't want to change that attribute. Type @samp{none} if you want
|
|
|
573 @c to clear out the attribute.
|
|
|
574
|
|
|
575 @node Specific Customization
|
|
|
576 @subsubsection Customizing Specific Items
|
|
|
577
|
|
|
578 Instead of finding the options you want to change by moving down
|
|
|
579 through the structure of groups, you can specify the particular option,
|
|
|
580 face or group that you want to customize.
|
|
|
581
|
|
|
582 @table @kbd
|
|
|
583 @item M-x customize-option @key{RET} @var{option} @key{RET}
|
|
|
584 Set up a customization buffer with just one option, @var{option}.
|
|
|
585 @item M-x customize-face @key{RET} @var{face} @key{RET}
|
|
|
586 Set up a customization buffer with just one face, @var{face}.
|
|
|
587 @item M-x customize-group @key{RET} @var{group} @key{RET}
|
|
|
588 Set up a customization buffer with just one group, @var{group}.
|
|
|
589 @item M-x customize-apropos @key{RET} @var{regexp} @key{RET}
|
|
|
590 Set up a customization buffer with all the options, faces and groups
|
|
|
591 that match @var{regexp}.
|
|
1137
|
592 @item M-x customize-saved
|
|
428
|
593 Set up a customization buffer containing all options and faces that you
|
|
|
594 have saved with customization buffers.
|
|
|
595 @item M-x customize-customized
|
|
|
596 Set up a customization buffer containing all options and faces that you
|
|
|
597 have customized but not saved.
|
|
|
598 @end table
|
|
|
599
|
|
|
600 @findex customize-option
|
|
|
601 If you want to alter a particular user option variable with the
|
|
|
602 customization buffer, and you know its name, you can use the command
|
|
|
603 @kbd{M-x customize-option} and specify the option name. This sets up
|
|
|
604 the customization buffer with just one option---the one that you asked
|
|
|
605 for. Editing, setting and saving the value work as described above, but
|
|
|
606 only for the specified option.
|
|
|
607
|
|
|
608 @findex customize-face
|
|
|
609 Likewise, you can modify a specific face, chosen by name, using
|
|
|
610 @kbd{M-x customize-face}.
|
|
|
611
|
|
|
612 @findex customize-group
|
|
|
613 You can also set up the customization buffer with a specific group,
|
|
|
614 using @kbd{M-x customize-group}. The immediate contents of the chosen
|
|
|
615 group, including option variables, faces, and other groups, all appear
|
|
|
616 as well. However, these subgroups' own contents start out hidden. You
|
|
|
617 can show their contents in the usual way, by invoking @samp{[Show]}.
|
|
|
618
|
|
|
619 @findex customize-apropos
|
|
|
620 To control more precisely what to customize, you can use @kbd{M-x
|
|
|
621 customize-apropos}. You specify a regular expression as argument; then
|
|
|
622 all options, faces and groups whose names match this regular expression
|
|
|
623 are set up in the customization buffer. If you specify an empty regular
|
|
|
624 expression, this includes @emph{all} groups, options and faces in the
|
|
|
625 customization buffer (but that takes a long time).
|
|
|
626
|
|
|
627 @findex customize-saved
|
|
|
628 @findex customize-customized
|
|
|
629 If you change option values and then decide the change was a mistake,
|
|
|
630 you can use two special commands to revisit your previous changes. Use
|
|
|
631 @kbd{customize-saved} to look at the options and faces that you have
|
|
|
632 saved. Use @kbd{M-x customize-customized} to look at the options and
|
|
|
633 faces that you have set but not saved.
|
|
|
634
|
|
|
635 @node Edit Options
|
|
|
636 @subsection Editing Variable Values
|
|
|
637
|
|
|
638 @table @kbd
|
|
|
639 @item M-x list-options
|
|
|
640 Display a buffer listing names, values, and documentation of all options.
|
|
|
641 @item M-x edit-options
|
|
|
642 Change option values by editing a list of options.
|
|
|
643 @end table
|
|
|
644
|
|
|
645 @findex list-options
|
|
|
646 @kbd{M-x list-options} displays a list of all Emacs option variables in
|
|
|
647 an Emacs buffer named @samp{*List Options*}. Each option is shown with its
|
|
|
648 documentation and its current value. Here is what a portion of it might
|
|
|
649 look like:
|
|
|
650
|
|
|
651 @smallexample
|
|
|
652 ;; exec-path:
|
|
|
653 ("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc")
|
|
|
654 *List of directories to search programs to run in subprocesses.
|
|
|
655 Each element is a string (directory name)
|
|
|
656 or nil (try the default directory).
|
|
|
657 ;;
|
|
|
658 ;; fill-column:
|
|
|
659 75
|
|
|
660 *Column beyond which automatic line-wrapping should happen.
|
|
|
661 Automatically becomes local when set in any fashion.
|
|
|
662 ;;
|
|
|
663 @end smallexample
|
|
|
664
|
|
|
665 @findex edit-options
|
|
|
666 @kbd{M-x edit-options} goes one step further and immediately selects the
|
|
|
667 @samp{*List Options*} buffer; this buffer uses the major mode Options mode,
|
|
|
668 which provides commands that allow you to point at an option and change its
|
|
|
669 value:
|
|
|
670
|
|
|
671 @table @kbd
|
|
|
672 @item s
|
|
|
673 Set the variable point is in or near to a new value read using the
|
|
|
674 minibuffer.
|
|
|
675 @item x
|
|
|
676 Toggle the variable point is in or near: if the value was @code{nil},
|
|
|
677 it becomes @code{t}; otherwise it becomes @code{nil}.
|
|
|
678 @item 1
|
|
|
679 Set the variable point is in or near to @code{t}.
|
|
|
680 @item 0
|
|
|
681 Set the variable point is in or near to @code{nil}.
|
|
|
682 @item n
|
|
|
683 @itemx p
|
|
|
684 Move to the next or previous variable.
|
|
|
685 @end table
|
|
|
686
|
|
|
687 @node Locals
|
|
|
688 @subsection Local Variables
|
|
|
689
|
|
|
690 @table @kbd
|
|
|
691 @item M-x make-local-variable
|
|
|
692 Make a variable have a local value in the current buffer.
|
|
|
693 @item M-x kill-local-variable
|
|
|
694 Make a variable use its global value in the current buffer.
|
|
|
695 @item M-x make-variable-buffer-local
|
|
|
696 Mark a variable so that setting it will make it local to the
|
|
|
697 buffer that is current at that time.
|
|
|
698 @end table
|
|
|
699
|
|
|
700 @cindex local variables
|
|
|
701 You can make any variable @dfn{local} to a specific Emacs buffer.
|
|
|
702 This means that the variable's value in that buffer is independent of
|
|
|
703 its value in other buffers. A few variables are always local in every
|
|
|
704 buffer. All other Emacs variables have a @dfn{global} value which is in
|
|
|
705 effect in all buffers that have not made the variable local.
|
|
|
706
|
|
|
707 Major modes always make the variables they set local to the buffer.
|
|
|
708 This is why changing major modes in one buffer has no effect on other
|
|
|
709 buffers.
|
|
|
710
|
|
|
711 @findex make-local-variable
|
|
|
712 @kbd{M-x make-local-variable} reads the name of a variable and makes it
|
|
|
713 local to the current buffer. Further changes in this buffer will not
|
|
|
714 affect others, and changes in the global value will not affect this
|
|
|
715 buffer.
|
|
|
716
|
|
|
717 @findex make-variable-buffer-local
|
|
|
718 @cindex per-buffer variables
|
|
|
719 @kbd{M-x make-variable-buffer-local} reads the name of a variable and
|
|
|
720 changes the future behavior of the variable so that it automatically
|
|
|
721 becomes local when it is set. More precisely, once you have marked a
|
|
|
722 variable in this way, the usual ways of setting the
|
|
|
723 variable will automatically invoke @code{make-local-variable} first. We
|
|
|
724 call such variables @dfn{per-buffer} variables.
|
|
|
725
|
|
|
726 Some important variables have been marked per-buffer already. They
|
|
|
727 include @code{abbrev-mode}, @code{auto-fill-function},
|
|
|
728 @code{case-fold-search}, @code{comment-column}, @code{ctl-arrow},
|
|
|
729 @code{fill-column}, @code{fill-prefix}, @code{indent-tabs-mode},
|
|
|
730 @code{left-margin}, @*@code{mode-line-format}, @code{overwrite-mode},
|
|
|
731 @code{selective-display-ellipses}, @*@code{selective-display},
|
|
|
732 @code{tab-width}, and @code{truncate-lines}. Some other variables are
|
|
|
733 always local in every buffer, but they are used for internal
|
|
|
734 purposes.@refill
|
|
|
735
|
|
|
736 Note: the variable @code{auto-fill-function} was formerly named
|
|
|
737 @code{auto-fill-hook}.
|
|
|
738
|
|
|
739 @findex kill-local-variable
|
|
|
740 If you want a variable to cease to be local to the current buffer,
|
|
|
741 call @kbd{M-x kill-local-variable} and provide the name of a variable to
|
|
|
742 the prompt. The global value of the variable
|
|
|
743 is again in effect in this buffer. Setting the major mode kills all
|
|
|
744 the local variables of the buffer.
|
|
|
745
|
|
|
746 @findex setq-default
|
|
|
747 To set the global value of a variable, regardless of whether the
|
|
|
748 variable has a local value in the current buffer, you can use the
|
|
|
749 Lisp function @code{setq-default}. It works like @code{setq}.
|
|
|
750 If there is a local value in the current buffer, the local value is
|
|
|
751 not affected by @code{setq-default}; thus, the new global value may
|
|
|
752 not be visible until you switch to another buffer, as in the case of:
|
|
|
753
|
|
|
754 @example
|
|
|
755 (setq-default fill-column 75)
|
|
|
756 @end example
|
|
|
757
|
|
|
758 @noindent
|
|
|
759 @code{setq-default} is the only way to set the global value of a variable
|
|
|
760 that has been marked with @code{make-variable-buffer-local}.
|
|
|
761
|
|
|
762 @findex default-value
|
|
|
763 Programs can look at a variable's default value with @code{default-value}.
|
|
|
764 This function takes a symbol as an argument and returns its default value.
|
|
|
765 The argument is evaluated; usually you must quote it explicitly, as in
|
|
|
766 the case of:
|
|
|
767
|
|
|
768 @example
|
|
|
769 (default-value 'fill-column)
|
|
|
770 @end example
|
|
|
771
|
|
|
772 @node File Variables
|
|
|
773 @subsection Local Variables in Files
|
|
|
774 @cindex local variables in files
|
|
|
775
|
|
|
776 A file can contain a @dfn{local variables list}, which specifies the
|
|
3510
|
777 buffer-local values to use for certain Emacs variables when that file is
|
|
|
778 edited. Visiting the file checks for a local variables list and makes
|
|
|
779 each variable in the list local to the buffer in which the file is
|
|
|
780 visited, with the value specified in the file.
|
|
428
|
781
|
|
|
782 A local variables list goes near the end of the file, in the last page.
|
|
|
783 (It is often best to put it on a page by itself.) The local variables list
|
|
|
784 starts with a line containing the string @samp{Local Variables:}, and ends
|
|
|
785 with a line containing the string @samp{End:}. In between come the
|
|
|
786 variable names and values, one set per line, as @samp{@var{variable}:@:
|
|
|
787 @var{value}}. The @var{value}s are not evaluated; they are used literally.
|
|
|
788
|
|
|
789 The line which starts the local variables list does not have to say
|
|
|
790 just @samp{Local Variables:}. If there is other text before @samp{Local
|
|
|
791 Variables:}, that text is called the @dfn{prefix}, and if there is other
|
|
|
792 text after, that is called the @dfn{suffix}. If a prefix or suffix are
|
|
|
793 present, each entry in the local variables list should have the prefix
|
|
|
794 before it and the suffix after it. This includes the @samp{End:} line.
|
|
|
795 The prefix and suffix are included to disguise the local variables list
|
|
|
796 as a comment so the compiler or text formatter will ignore it.
|
|
|
797 If you do not need to disguise the local variables list as a comment in
|
|
|
798 this way, there is no need to include a prefix or a suffix.@refill
|
|
|
799
|
|
|
800 Two ``variable'' names are special in a local variables list: a value
|
|
|
801 for the variable @code{mode} sets the major mode, and a value for the
|
|
|
802 variable @code{eval} is simply evaluated as an expression and the value
|
|
|
803 is ignored. These are not real variables; setting them in any other
|
|
|
804 context does not have the same effect. If @code{mode} is used in a
|
|
|
805 local variables list, it should be the first entry in the list.
|
|
|
806
|
|
|
807 Here is an example of a local variables list:
|
|
|
808 @example
|
|
|
809 ;;; Local Variables: ***
|
|
|
810 ;;; mode:lisp ***
|
|
|
811 ;;; comment-column:0 ***
|
|
|
812 ;;; comment-start: ";;; " ***
|
|
|
813 ;;; comment-end:"***" ***
|
|
|
814 ;;; End: ***
|
|
|
815 @end example
|
|
|
816
|
|
|
817 Note that the prefix is @samp{;;; } and the suffix is @samp{ ***}.
|
|
|
818 Note also that comments in the file begin with and end with the same
|
|
|
819 strings. Presumably the file contains code in a language which is
|
|
|
820 enough like Lisp for Lisp mode to be useful but in which comments
|
|
|
821 start and end differently. The prefix and suffix are used in the local
|
|
|
822 variables list to make the list look like several lines of comments when
|
|
1137
|
823 the compiler or interpreter for that language reads the file.
|
|
428
|
824
|
|
|
825 The start of the local variables list must be no more than 3000
|
|
|
826 characters from the end of the file, and must be in the last page if the
|
|
|
827 file is divided into pages. Otherwise, Emacs will not notice it is
|
|
|
828 there. The purpose is twofold: a stray @samp{Local Variables:}@: not in
|
|
|
829 the last page does not confuse Emacs, and Emacs never needs to search a
|
|
|
830 long file that contains no page markers and has no local variables list.
|
|
|
831
|
|
2736
|
832 You may be tempted to turn on minor modes like Auto Fill mode with a
|
|
|
833 local variable list. That is inappropriate. Those behaviors that seem
|
|
|
834 appropriate for almost any personal taste, such as setting up the syntax
|
|
|
835 table "symbol constituent" character class, are collected into a major
|
|
|
836 mode. But whether you use Auto Fill mode or not is
|
|
428
|
837 a matter of personal taste, not a matter of the contents of particular
|
|
|
838 files. If you want to use Auto Fill, set up major mode hooks with your
|
|
442
|
839 init file to turn it on (when appropriate) for you alone
|
|
2736
|
840 (@pxref{Init File}). Don't use a local variable list that would
|
|
428
|
841 impose your taste on everyone working with the file.
|
|
|
842
|
|
|
843 XEmacs allows you to specify local variables in the first line
|
|
|
844 of a file, in addition to specifying them in the @code{Local Variables}
|
|
|
845 section at the end of a file.
|
|
|
846
|
|
|
847 If the first line of a file contains two occurrences of @code{`-*-'},
|
|
|
848 XEmacs uses the information between them to determine what the major
|
|
|
849 mode and variable settings should be. For example, these are all legal:
|
|
|
850
|
|
|
851 @example
|
|
440
|
852 ;;; -*- mode: emacs-lisp -*-
|
|
|
853 ;;; -*- mode: postscript; version-control: never -*-
|
|
|
854 ;;; -*- tags-file-name: "/foo/bar/TAGS" -*-
|
|
428
|
855 @end example
|
|
|
856
|
|
|
857 For historical reasons, the syntax @code{`-*- modename -*-'} is allowed
|
|
|
858 as well; for example, you can use:
|
|
|
859
|
|
|
860 @example
|
|
440
|
861 ;;; -*- emacs-lisp -*-
|
|
428
|
862 @end example
|
|
|
863
|
|
|
864 @vindex enable-local-variables
|
|
|
865 The variable @code{enable-local-variables} controls the use of local
|
|
|
866 variables lists in files you visit. The value can be @code{t},
|
|
|
867 @code{nil}, or something else. A value of @code{t} means local variables
|
|
|
868 lists are obeyed; @code{nil} means they are ignored; anything else means
|
|
|
869 query.
|
|
|
870
|
|
|
871 The command @code{M-x normal-mode} always obeys local variables lists
|
|
|
872 and ignores this variable.
|
|
|
873
|
|
|
874 @node Keyboard Macros
|
|
|
875 @section Keyboard Macros
|
|
|
876
|
|
|
877 @cindex keyboard macros
|
|
|
878 A @dfn{keyboard macro} is a command defined by the user to abbreviate a
|
|
|
879 sequence of keys. For example, if you discover that you are about to type
|
|
|
880 @kbd{C-n C-d} forty times, you can speed your work by defining a keyboard
|
|
|
881 macro to invoke @kbd{C-n C-d} and calling it with a repeat count of forty.
|
|
|
882
|
|
|
883 @c widecommands
|
|
|
884 @table @kbd
|
|
|
885 @item C-x (
|
|
|
886 Start defining a keyboard macro (@code{start-kbd-macro}).
|
|
|
887 @item C-x )
|
|
|
888 End the definition of a keyboard macro (@code{end-kbd-macro}).
|
|
|
889 @item C-x e
|
|
|
890 Execute the most recent keyboard macro (@code{call-last-kbd-macro}).
|
|
|
891 @item C-u C-x (
|
|
|
892 Re-execute last keyboard macro, then add more keys to its definition.
|
|
|
893 @item C-x q
|
|
|
894 When this point is reached during macro execution, ask for confirmation
|
|
|
895 (@code{kbd-macro-query}).
|
|
|
896 @item M-x name-last-kbd-macro
|
|
|
897 Give a command name (for the duration of the session) to the most
|
|
|
898 recently defined keyboard macro.
|
|
|
899 @item M-x insert-kbd-macro
|
|
|
900 Insert in the buffer a keyboard macro's definition, as Lisp code.
|
|
|
901 @end table
|
|
|
902
|
|
|
903 Keyboard macros differ from other Emacs commands in that they are
|
|
|
904 written in the Emacs command language rather than in Lisp. This makes it
|
|
|
905 easier for the novice to write them and makes them more convenient as
|
|
|
906 temporary hacks. However, the Emacs command language is not powerful
|
|
|
907 enough as a programming language to be useful for writing anything
|
|
|
908 general or complex. For such things, Lisp must be used.
|
|
|
909
|
|
|
910 You define a keyboard macro by executing the commands which are its
|
|
|
911 definition. Put differently, as you are defining a keyboard macro, the
|
|
|
912 definition is being executed for the first time. This way, you see
|
|
|
913 what the effects of your commands are, and don't have to figure
|
|
|
914 them out in your head. When you are finished, the keyboard macro is
|
|
|
915 defined and also has been executed once. You can then execute the same
|
|
|
916 set of commands again by invoking the macro.
|
|
|
917
|
|
|
918 @menu
|
|
|
919 * Basic Kbd Macro:: Defining and running keyboard macros.
|
|
|
920 * Save Kbd Macro:: Giving keyboard macros names; saving them in files.
|
|
|
921 * Kbd Macro Query:: Keyboard macros that do different things each use.
|
|
|
922 @end menu
|
|
|
923
|
|
|
924 @node Basic Kbd Macro
|
|
|
925 @subsection Basic Use
|
|
|
926
|
|
|
927 @kindex C-x (
|
|
|
928 @kindex C-x )
|
|
|
929 @kindex C-x e
|
|
|
930 @findex start-kbd-macro
|
|
|
931 @findex end-kbd-macro
|
|
|
932 @findex call-last-kbd-macro
|
|
|
933 To start defining a keyboard macro, type @kbd{C-x (}
|
|
|
934 (@code{start-kbd-macro}). From then on, anything you type continues to be
|
|
|
935 executed, but also becomes part of the definition of the macro. @samp{Def}
|
|
|
936 appears in the mode line to remind you of what is going on. When you are
|
|
|
937 finished, the @kbd{C-x )} command (@code{end-kbd-macro}) terminates the
|
|
1137
|
938 definition, without becoming part of it.
|
|
428
|
939
|
|
|
940 For example,
|
|
|
941
|
|
|
942 @example
|
|
|
943 C-x ( M-f foo C-x )
|
|
|
944 @end example
|
|
|
945
|
|
|
946 @noindent
|
|
|
947 defines a macro to move forward a word and then insert @samp{foo}.
|
|
|
948
|
|
|
949 You can give @kbd{C-x )} a repeat count as an argument, in which case it
|
|
|
950 repeats the macro that many times right after defining it, but defining
|
|
|
951 the macro counts as the first repetition (since it is executed as you
|
|
|
952 define it). If you give @kbd{C-x )} an argument of 4, it executes the
|
|
|
953 macro immediately 3 additional times. An argument of zero to @kbd{C-x
|
|
|
954 e} or @kbd{C-x )} means repeat the macro indefinitely (until it gets an
|
|
|
955 error or you type @kbd{C-g}).
|
|
|
956
|
|
|
957 Once you have defined a macro, you can invoke it again with the
|
|
|
958 @kbd{C-x e} command (@code{call-last-kbd-macro}). You can give the
|
|
|
959 command a repeat count numeric argument to execute the macro many times.
|
|
|
960
|
|
|
961 To repeat an operation at regularly spaced places in the
|
|
|
962 text, define a macro and include as part of the macro the commands to move
|
|
|
963 to the next place you want to use it. For example, if you want to change
|
|
|
964 each line, you should position point at the start of a line, and define a
|
|
|
965 macro to change that line and leave point at the start of the next line.
|
|
|
966 Repeating the macro will then operate on successive lines.
|
|
|
967
|
|
|
968 After you have terminated the definition of a keyboard macro, you can add
|
|
|
969 to the end of its definition by typing @kbd{C-u C-x (}. This is equivalent
|
|
|
970 to plain @kbd{C-x (} followed by retyping the whole definition so far. As
|
|
|
971 a consequence it re-executes the macro as previously defined.
|
|
|
972
|
|
|
973 @node Save Kbd Macro
|
|
|
974 @subsection Naming and Saving Keyboard Macros
|
|
|
975
|
|
|
976 @findex name-last-kbd-macro
|
|
|
977 To save a keyboard macro for longer than until you define the
|
|
|
978 next one, you must give it a name using @kbd{M-x name-last-kbd-macro}.
|
|
|
979 This reads a name as an argument using the minibuffer and defines that name
|
|
|
980 to execute the macro. The macro name is a Lisp symbol, and defining it in
|
|
|
981 this way makes it a valid command name for calling with @kbd{M-x} or for
|
|
|
982 binding a key to with @code{global-set-key} (@pxref{Keymaps}). If you
|
|
|
983 specify a name that has a prior definition other than another keyboard
|
|
|
984 macro, Emacs prints an error message and nothing is changed.
|
|
|
985
|
|
|
986 @findex insert-kbd-macro
|
|
|
987 Once a macro has a command name, you can save its definition in a file.
|
|
|
988 You can then use it in another editing session. First visit the file
|
|
|
989 you want to save the definition in. Then use the command:
|
|
|
990
|
|
|
991 @example
|
|
|
992 M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET}
|
|
|
993 @end example
|
|
|
994
|
|
|
995 @noindent
|
|
|
996 This inserts some Lisp code that, when executed later, will define the same
|
|
|
997 macro with the same definition it has now. You need not understand Lisp
|
|
|
998 code to do this, because @code{insert-kbd-macro} writes the Lisp code for you.
|
|
|
999 Then save the file. You can load the file with @code{load-file}
|
|
|
1000 (@pxref{Lisp Libraries}). If the file you save in is your initialization file
|
|
442
|
1001 (@pxref{Init File}), then the macro will be defined each
|
|
428
|
1002 time you run Emacs.
|
|
|
1003
|
|
|
1004 If you give @code{insert-kbd-macro} a prefix argument, it creates
|
|
|
1005 additional Lisp code to record the keys (if any) that you have bound to the
|
|
|
1006 keyboard macro, so that the macro is reassigned the same keys when you
|
|
|
1007 load the file.
|
|
|
1008
|
|
|
1009 @node Kbd Macro Query
|
|
|
1010 @subsection Executing Macros With Variations
|
|
|
1011
|
|
|
1012 @kindex C-x q
|
|
|
1013 @findex kbd-macro-query
|
|
|
1014 You can use @kbd{C-x q} (@code{kbd-macro-query}), to get an effect similar
|
|
|
1015 to that of @code{query-replace}. The macro asks you each time
|
|
|
1016 whether to make a change. When you are defining the macro, type @kbd{C-x
|
|
|
1017 q} at the point where you want the query to occur. During macro
|
|
|
1018 definition, the @kbd{C-x q} does nothing, but when you invoke the macro,
|
|
|
1019 @kbd{C-x q} reads a character from the terminal to decide whether to
|
|
|
1020 continue.
|
|
|
1021
|
|
|
1022 The special answers to a @kbd{C-x q} query are @key{SPC}, @key{DEL},
|
|
|
1023 @kbd{C-d}, @kbd{C-l}, and @kbd{C-r}. Any other character terminates
|
|
|
1024 execution of the keyboard macro and is then read as a command.
|
|
|
1025 @key{SPC} means to continue. @key{DEL} means to skip the remainder of
|
|
|
1026 this repetition of the macro, starting again from the beginning in the
|
|
|
1027 next repetition. @kbd{C-d} means to skip the remainder of this
|
|
|
1028 repetition and cancel further repetition. @kbd{C-l} redraws the frame
|
|
|
1029 and asks you again for a character to specify what to do. @kbd{C-r} enters
|
|
|
1030 a recursive editing level, in which you can perform editing that is not
|
|
|
1031 part of the macro. When you exit the recursive edit using @kbd{C-M-c},
|
|
|
1032 you are asked again how to continue with the keyboard macro. If you
|
|
|
1033 type a @key{SPC} at this time, the rest of the macro definition is
|
|
|
1034 executed. It is up to you to leave point and the text in a state such
|
|
|
1035 that the rest of the macro will do what you want.@refill
|
|
|
1036
|
|
|
1037 @kbd{C-u C-x q}, which is @kbd{C-x q} with a numeric argument, performs a
|
|
|
1038 different function. It enters a recursive edit reading input from the
|
|
|
1039 keyboard, both when you type it during the definition of the macro and
|
|
|
1040 when it is executed from the macro. During definition, the editing you do
|
|
|
1041 inside the recursive edit does not become part of the macro. During macro
|
|
|
1042 execution, the recursive edit gives you a chance to do some particularized
|
|
|
1043 editing. @xref{Recursive Edit}.
|
|
|
1044
|
|
|
1045 @node Key Bindings
|
|
|
1046 @section Customizing Key Bindings
|
|
|
1047
|
|
|
1048 This section deals with the @dfn{keymaps} that define the bindings
|
|
|
1049 between keys and functions, and shows how you can customize these bindings.
|
|
|
1050 @cindex command
|
|
|
1051 @cindex function
|
|
|
1052 @cindex command name
|
|
|
1053
|
|
|
1054 A command is a Lisp function whose definition provides for interactive
|
|
|
1055 use. Like every Lisp function, a command has a function name, which is
|
|
|
1056 a Lisp symbol whose name usually consists of lower case letters and
|
|
|
1057 hyphens.
|
|
|
1058
|
|
|
1059 @menu
|
|
|
1060 * Keymaps:: Definition of the keymap data structure.
|
|
|
1061 Names of Emacs's standard keymaps.
|
|
|
1062 * Rebinding:: How to redefine one key's meaning conveniently.
|
|
|
1063 * Disabling:: Disabling a command means confirmation is required
|
|
|
1064 before it can be executed. This is done to protect
|
|
|
1065 beginners from surprises.
|
|
|
1066 @end menu
|
|
|
1067
|
|
|
1068 @node Keymaps
|
|
|
1069 @subsection Keymaps
|
|
|
1070 @cindex keymap
|
|
|
1071
|
|
|
1072 @cindex global keymap
|
|
|
1073 @vindex global-map
|
|
|
1074 The bindings between characters and command functions are recorded in
|
|
|
1075 data structures called @dfn{keymaps}. Emacs has many of these. One, the
|
|
|
1076 @dfn{global} keymap, defines the meanings of the single-character keys that
|
|
|
1077 are defined regardless of major mode. It is the value of the variable
|
|
|
1078 @code{global-map}.
|
|
|
1079
|
|
|
1080 @cindex local keymap
|
|
|
1081 @vindex c-mode-map
|
|
|
1082 @vindex lisp-mode-map
|
|
|
1083 Each major mode has another keymap, its @dfn{local keymap}, which
|
|
|
1084 contains overriding definitions for the single-character keys that are
|
|
|
1085 redefined in that mode. Each buffer records which local keymap is
|
|
|
1086 installed for it at any time, and the current buffer's local keymap is
|
|
|
1087 the only one that directly affects command execution. The local keymaps
|
|
|
1088 for Lisp mode, C mode, and many other major modes always exist even when
|
|
|
1089 not in use. They are the values of the variables @code{lisp-mode-map},
|
|
|
1090 @code{c-mode-map}, and so on. For less frequently used major modes, the
|
|
|
1091 local keymap is sometimes constructed only when the mode is used for the
|
|
|
1092 first time in a session, to save space.
|
|
|
1093
|
|
|
1094 @cindex minibuffer
|
|
|
1095 @vindex minibuffer-local-map
|
|
|
1096 @vindex minibuffer-local-ns-map
|
|
|
1097 @vindex minibuffer-local-completion-map
|
|
|
1098 @vindex minibuffer-local-must-match-map
|
|
|
1099 @vindex repeat-complex-command-map
|
|
|
1100 @vindex isearch-mode-map
|
|
|
1101 There are local keymaps for the minibuffer, too; they contain various
|
|
|
1102 completion and exit commands.
|
|
|
1103
|
|
|
1104 @itemize @bullet
|
|
|
1105 @item
|
|
|
1106 @code{minibuffer-local-map} is used for ordinary input (no completion).
|
|
|
1107 @item
|
|
|
1108 @code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
|
|
|
1109 just like @key{RET}. This is used mainly for Mocklisp compatibility.
|
|
|
1110 @item
|
|
|
1111 @code{minibuffer-local-completion-map} is for permissive completion.
|
|
|
1112 @item
|
|
|
1113 @code{minibuffer-local-must-match-map} is for strict completion and
|
|
|
1114 for cautious completion.
|
|
|
1115 @item
|
|
|
1116 @code{repeat-complex-command-map} is for use in @kbd{C-x @key{ESC}}.
|
|
|
1117 @item
|
|
|
1118 @code{isearch-mode-map} contains the bindings of the special keys which
|
|
|
1119 are bound in the pseudo-mode entered with @kbd{C-s} and @kbd{C-r}.
|
|
|
1120 @end itemize
|
|
|
1121
|
|
|
1122 @vindex ctl-x-map
|
|
|
1123 @vindex help-map
|
|
|
1124 @vindex esc-map
|
|
|
1125 Finally, each prefix key has a keymap which defines the key sequences
|
|
|
1126 that start with it. For example, @code{ctl-x-map} is the keymap used for
|
|
|
1127 characters following a @kbd{C-x}.
|
|
|
1128
|
|
|
1129 @itemize @bullet
|
|
|
1130 @item
|
|
|
1131 @code{ctl-x-map} is the variable name for the map used for characters that
|
|
|
1132 follow @kbd{C-x}.
|
|
|
1133 @item
|
|
|
1134 @code{help-map} is used for characters that follow @kbd{C-h}.
|
|
|
1135 @item
|
|
|
1136 @code{esc-map} is for characters that follow @key{ESC}. All Meta
|
|
|
1137 characters are actually defined by this map.
|
|
|
1138 @item
|
|
|
1139 @code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}.
|
|
|
1140 @item
|
|
|
1141 @code{mode-specific-map} is for characters that follow @kbd{C-c}.
|
|
|
1142 @end itemize
|
|
|
1143
|
|
|
1144 The definition of a prefix key is the keymap to use for looking up
|
|
|
1145 the following character. Sometimes the definition is actually a Lisp
|
|
|
1146 symbol whose function definition is the following character keymap. The
|
|
|
1147 effect is the same, but it provides a command name for the prefix key that
|
|
|
1148 you can use as a description of what the prefix key is for. Thus the
|
|
|
1149 binding of @kbd{C-x} is the symbol @code{Ctl-X-Prefix}, whose function
|
|
|
1150 definition is the keymap for @kbd{C-x} commands, the value of
|
|
|
1151 @code{ctl-x-map}.@refill
|
|
|
1152
|
|
|
1153 Prefix key definitions can appear in either the global
|
|
|
1154 map or a local map. The definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h},
|
|
|
1155 and @key{ESC} as prefix keys appear in the global map, so these prefix
|
|
|
1156 keys are always available. Major modes can locally redefine a key as a
|
|
|
1157 prefix by putting a prefix key definition for it in the local
|
|
|
1158 map.@refill
|
|
|
1159
|
|
|
1160 A mode can also put a prefix definition of a global prefix character such
|
|
|
1161 as @kbd{C-x} into its local map. This is how major modes override the
|
|
|
1162 definitions of certain keys that start with @kbd{C-x}. This case is
|
|
|
1163 special, because the local definition does not entirely replace the global
|
|
|
1164 one. When both the global and local definitions of a key are other
|
|
|
1165 keymaps, the next character is looked up in both keymaps, with the local
|
|
|
1166 definition overriding the global one. The character after the
|
|
|
1167 @kbd{C-x} is looked up in both the major mode's own keymap for redefined
|
|
|
1168 @kbd{C-x} commands and in @code{ctl-x-map}. If the major mode's own keymap
|
|
|
1169 for @kbd{C-x} commands contains @code{nil}, the definition from the global
|
|
|
1170 keymap for @kbd{C-x} commands is used.@refill
|
|
|
1171
|
|
|
1172 @node Rebinding
|
|
|
1173 @subsection Changing Key Bindings
|
|
|
1174 @cindex key rebinding, this session
|
|
|
1175 @cindex rebinding keys, this session
|
|
|
1176
|
|
|
1177 You can redefine an Emacs key by changing its entry in a keymap.
|
|
|
1178 You can change the global keymap, in which case the change is effective in
|
|
|
1179 all major modes except those that have their own overriding local
|
|
|
1180 definitions for the same key. Or you can change the current buffer's
|
|
|
1181 local map, which affects all buffers using the same major mode.
|
|
|
1182
|
|
|
1183 @menu
|
|
1137
|
1184 * Interactive Rebinding:: Changing Key Bindings Interactively
|
|
438
|
1185 * Programmatic Rebinding:: Changing Key Bindings Programmatically
|
|
1137
|
1186 * Key Bindings Using Strings:: Using Strings for Changing Key Bindings
|
|
428
|
1187 @end menu
|
|
|
1188
|
|
|
1189 @node Interactive Rebinding
|
|
|
1190 @subsubsection Changing Key Bindings Interactively
|
|
|
1191 @findex global-set-key
|
|
|
1192 @findex local-set-key
|
|
|
1193 @findex local-unset-key
|
|
|
1194
|
|
|
1195 @table @kbd
|
|
|
1196 @item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}
|
|
|
1197 Defines @var{key} globally to run @var{cmd}.
|
|
1137
|
1198 @item M-x local-set-key @key{RET} @var{keys} @var{cmd} @key{RET}
|
|
428
|
1199 Defines @var{key} locally (in the major mode now in effect) to run
|
|
|
1200 @var{cmd}.
|
|
|
1201 @item M-x local-unset-key @key{RET} @var{keys} @key{RET}
|
|
|
1202 Removes the local binding of @var{key}.
|
|
|
1203 @end table
|
|
|
1204
|
|
|
1205 @var{cmd} is a symbol naming an interactively-callable function.
|
|
|
1206
|
|
|
1207 When called interactively, @var{key} is the next complete key sequence
|
|
|
1208 that you type. When called as a function, @var{key} is a string, a
|
|
|
1209 vector of events, or a vector of key-description lists as described in
|
|
|
1210 the @code{define-key} function description. The binding goes in
|
|
|
1211 the current buffer's local map, which is shared with other buffers in
|
|
|
1212 the same major mode.
|
|
|
1213
|
|
|
1214 The following example:
|
|
|
1215
|
|
|
1216 @example
|
|
|
1217 M-x global-set-key @key{RET} C-f next-line @key{RET}
|
|
|
1218 @end example
|
|
|
1219
|
|
|
1220 @noindent
|
|
|
1221 redefines @kbd{C-f} to move down a line. The fact that @var{cmd} is
|
|
|
1222 read second makes it serve as a kind of confirmation for @var{key}.
|
|
|
1223
|
|
|
1224 These functions offer no way to specify a particular prefix keymap as
|
|
|
1225 the one to redefine in, but that is not necessary, as you can include
|
|
|
1226 prefixes in @var{key}. @var{key} is read by reading characters one by
|
|
|
1227 one until they amount to a complete key (that is, not a prefix key).
|
|
|
1228 Thus, if you type @kbd{C-f} for @var{key}, Emacs enters
|
|
|
1229 the minibuffer immediately to read @var{cmd}. But if you type
|
|
|
1230 @kbd{C-x}, another character is read; if that character is @kbd{4},
|
|
|
1231 another character is read, and so on. For example,@refill
|
|
|
1232
|
|
|
1233 @example
|
|
|
1234 M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET}
|
|
|
1235 @end example
|
|
|
1236
|
|
|
1237 @noindent
|
|
|
1238 redefines @kbd{C-x 4 $} to run the (fictitious) command
|
|
|
1239 @code{spell-other-window}.
|
|
|
1240
|
|
|
1241 @findex define-key
|
|
|
1242 @findex substitute-key-definition
|
|
|
1243 The most general way to modify a keymap is the function
|
|
442
|
1244 @code{define-key}, used in Lisp code (such as your init file).
|
|
428
|
1245 @code{define-key} takes three arguments: the keymap, the key to modify
|
|
|
1246 in it, and the new definition. @xref{Init File}, for an example.
|
|
|
1247 @code{substitute-key-definition} is used similarly; it takes three
|
|
|
1248 arguments, an old definition, a new definition, and a keymap, and
|
|
|
1249 redefines in that keymap all keys that were previously defined with the
|
|
|
1250 old definition to have the new definition instead.
|
|
|
1251
|
|
|
1252 @node Programmatic Rebinding
|
|
|
1253 @subsubsection Changing Key Bindings Programmatically
|
|
|
1254
|
|
|
1255 You can use the functions @code{global-set-key} and @code{define-key}
|
|
|
1256 to rebind keys under program control.
|
|
|
1257
|
|
|
1258 @findex define-key
|
|
|
1259 @findex global-set-key
|
|
|
1260
|
|
|
1261 @table @kbd
|
|
|
1262 @item @code{(global-set-key @var{keys} @var{cmd})}
|
|
|
1263 Defines @var{keys} globally to run @var{cmd}.
|
|
|
1264 @item @code{(define-key @var{keymap} @var{keys} @var{def})}
|
|
|
1265 Defines @var{keys} to run @var{def} in the keymap @var{keymap}.
|
|
|
1266 @end table
|
|
1137
|
1267
|
|
428
|
1268 @var{keymap} is a keymap object.
|
|
|
1269
|
|
|
1270 @var{keys} is the sequence of keystrokes to bind.
|
|
|
1271
|
|
|
1272 @var{def} is anything that can be a key's definition:
|
|
|
1273
|
|
|
1274 @itemize @bullet
|
|
|
1275 @item
|
|
|
1276 @code{nil}, meaning key is undefined in this keymap
|
|
|
1277 @item
|
|
|
1278 A command, that is, a Lisp function suitable for interactive calling
|
|
|
1279 @item
|
|
|
1280 A string or key sequence vector, which is treated as a keyboard macro
|
|
|
1281 @item
|
|
|
1282 A keymap to define a prefix key
|
|
|
1283 @item
|
|
|
1284 A symbol so that when the key is looked up, the symbol stands for its
|
|
|
1285 function definition, which should at that time be one of the above,
|
|
|
1286 or another symbol whose function definition is used, and so on
|
|
|
1287 @item
|
|
|
1288 A cons, @code{(string . defn)}, meaning that @var{defn} is the definition
|
|
|
1289 (@var{defn} should be a valid definition in its own right)
|
|
|
1290 @item
|
|
|
1291 A cons, @code{(keymap . char)}, meaning use the definition of
|
|
|
1292 @var{char} in map @var{keymap}
|
|
|
1293 @end itemize
|
|
|
1294
|
|
|
1295 For backward compatibility, XEmacs allows you to specify key
|
|
|
1296 sequences as strings. However, the preferred method is to use the
|
|
|
1297 representations of key sequences as vectors of keystrokes.
|
|
|
1298 @xref{Keystrokes}, for more information about the rules for constructing
|
|
|
1299 key sequences.
|
|
|
1300
|
|
1137
|
1301 Emacs allows you to abbreviate representations for key sequences in
|
|
428
|
1302 most places where there is no ambiguity.
|
|
|
1303 Here are some rules for abbreviation:
|
|
|
1304
|
|
|
1305 @itemize @bullet
|
|
|
1306 @item
|
|
|
1307 The keysym by itself is equivalent to a list of just that keysym, i.e.,
|
|
|
1308 @code{f1} is equivalent to @code{(f1)}.
|
|
|
1309 @item
|
|
|
1310 A keystroke by itself is equivalent to a vector containing just that
|
|
|
1311 keystroke, i.e., @code{(control a)} is equivalent to @code{[(control a)]}.
|
|
|
1312 @item
|
|
|
1313 You can use ASCII codes for keysyms that have them. i.e.,
|
|
|
1314 @code{65} is equivalent to @code{A}. (This is not so much an
|
|
|
1315 abbreviation as an alternate representation.)
|
|
|
1316 @end itemize
|
|
|
1317
|
|
|
1318 Here are some examples of programmatically binding keys:
|
|
|
1319
|
|
|
1320 @example
|
|
|
1321
|
|
|
1322 ;;; Bind @code{my-command} to @key{f1}
|
|
1137
|
1323 (global-set-key 'f1 'my-command)
|
|
428
|
1324
|
|
|
1325 ;;; Bind @code{my-command} to @kbd{Shift-f1}
|
|
|
1326 (global-set-key '(shift f1) 'my-command)
|
|
|
1327
|
|
|
1328 ;;; Bind @code{my-command} to @kbd{C-c Shift-f1}
|
|
1137
|
1329 (global-set-key '[(control c) (shift f1)] 'my-command)
|
|
428
|
1330
|
|
|
1331 ;;; Bind @code{my-command} to the middle mouse button.
|
|
|
1332 (global-set-key 'button2 'my-command)
|
|
|
1333
|
|
|
1334 ;;; Bind @code{my-command} to @kbd{@key{META} @key{CTL} @key{Right Mouse Button}}
|
|
|
1335 ;;; in the keymap that is in force when you are running @code{dired}.
|
|
|
1336 (define-key dired-mode-map '(meta control button3) 'my-command)
|
|
|
1337
|
|
|
1338 @end example
|
|
|
1339
|
|
|
1340 @comment ;; note that these next four lines are not synonymous:
|
|
|
1341 @comment ;;
|
|
|
1342 @comment (global-set-key '(meta control delete) 'my-command)
|
|
|
1343 @comment (global-set-key '(meta control backspace) 'my-command)
|
|
|
1344 @comment (global-set-key '(meta control h) 'my-command)
|
|
|
1345 @comment (global-set-key '(meta control H) 'my-command)
|
|
1137
|
1346 @comment
|
|
428
|
1347 @comment ;; note that this binds two key sequences: ``control-j'' and ``linefeed''.
|
|
|
1348 @comment ;;
|
|
|
1349 @comment (global-set-key "\^J" 'my-command)
|
|
|
1350
|
|
|
1351 @node Key Bindings Using Strings
|
|
1137
|
1352 @subsubsection Using Strings for Changing Key Bindings
|
|
428
|
1353
|
|
|
1354 For backward compatibility, you can still use strings to represent
|
|
|
1355 key sequences. Thus you can use commands like the following:
|
|
|
1356
|
|
|
1357 @example
|
|
|
1358 ;;; Bind @code{end-of-line} to @kbd{C-f}
|
|
|
1359 (global-set-key "\C-f" 'end-of-line)
|
|
|
1360 @end example
|
|
|
1361
|
|
|
1362 Note, however, that in some cases you may be binding more than one
|
|
1137
|
1363 key sequence by using a single command. This situation can
|
|
428
|
1364 arise because in ASCII, @kbd{C-i} and @key{TAB} have
|
|
|
1365 the same representation. Therefore, when Emacs sees:
|
|
|
1366
|
|
|
1367 @example
|
|
|
1368 (global-set-key "\C-i" 'end-of-line)
|
|
|
1369 @end example
|
|
|
1370
|
|
|
1371 it is unclear whether the user intended to bind @kbd{C-i} or @key{TAB}.
|
|
|
1372 The solution XEmacs adopts is to bind both of these key
|
|
|
1373 sequences.
|
|
|
1374
|
|
|
1375 @cindex redefining keys
|
|
|
1376 After binding a command to two key sequences with a form like:
|
|
|
1377
|
|
|
1378 @example
|
|
440
|
1379 (define-key global-map "\^X\^I" 'command-1)
|
|
428
|
1380 @end example
|
|
|
1381
|
|
|
1382 it is possible to redefine only one of those sequences like so:
|
|
|
1383
|
|
|
1384 @example
|
|
440
|
1385 (define-key global-map [(control x) (control i)] 'command-2)
|
|
|
1386 (define-key global-map [(control x) tab] 'command-3)
|
|
428
|
1387 @end example
|
|
|
1388
|
|
|
1389 This applies only when running under a window system. If you are
|
|
|
1390 talking to Emacs through an ASCII-only channel, you do not get any of
|
|
|
1391 these features.
|
|
|
1392
|
|
|
1393 Here is a table of pairs of key sequences that behave in a
|
|
|
1394 similar fashion:
|
|
|
1395
|
|
|
1396 @example
|
|
1137
|
1397 control h backspace
|
|
428
|
1398 control l clear
|
|
1137
|
1399 control i tab
|
|
|
1400 control m return
|
|
|
1401 control j linefeed
|
|
428
|
1402 control [ escape
|
|
|
1403 control @@ control space
|
|
|
1404 @end example
|
|
|
1405
|
|
|
1406 @node Disabling
|
|
|
1407 @subsection Disabling Commands
|
|
|
1408 @cindex disabled command
|
|
|
1409
|
|
|
1410 Disabling a command marks it as requiring confirmation before it
|
|
|
1411 can be executed. The purpose of disabling a command is to prevent
|
|
|
1412 beginning users from executing it by accident and being confused.
|
|
|
1413
|
|
|
1414 The direct mechanism for disabling a command is to have a non-@code{nil}
|
|
|
1415 @code{disabled} property on the Lisp symbol for the command. These
|
|
442
|
1416 properties are normally set by the user's init file with
|
|
428
|
1417 Lisp expressions such as:
|
|
|
1418
|
|
|
1419 @example
|
|
|
1420 (put 'delete-region 'disabled t)
|
|
|
1421 @end example
|
|
|
1422
|
|
442
|
1423 @xref{Init File}.
|
|
|
1424
|
|
428
|
1425 If the value of the @code{disabled} property is a string, that string
|
|
|
1426 is included in the message printed when the command is used:
|
|
|
1427
|
|
|
1428 @example
|
|
|
1429 (put 'delete-region 'disabled
|
|
|
1430 "Text deleted this way cannot be yanked back!\n")
|
|
|
1431 @end example
|
|
|
1432
|
|
|
1433 @findex disable-command
|
|
|
1434 @findex enable-command
|
|
442
|
1435 You can disable a command either by editing the init file
|
|
428
|
1436 directly or with the command @kbd{M-x disable-command}, which edits the
|
|
442
|
1437 init file for you. @xref{Init File}.
|
|
428
|
1438
|
|
|
1439 When you attempt to invoke a disabled command interactively in Emacs,
|
|
|
1440 a window is displayed containing the command's name, its
|
|
|
1441 documentation, and some instructions on what to do next; then
|
|
|
1442 Emacs asks for input saying whether to execute the command as requested,
|
|
|
1443 enable it and execute, or cancel it. If you decide to enable the
|
|
|
1444 command, you are asked whether to do this permanently or just for the
|
|
|
1445 current session. Enabling permanently works by automatically editing
|
|
442
|
1446 your init file. You can use @kbd{M-x enable-command} at any
|
|
428
|
1447 time to enable any command permanently.
|
|
|
1448
|
|
|
1449 Whether a command is disabled is independent of what key is used to
|
|
|
1450 invoke it; it also applies if the command is invoked using @kbd{M-x}.
|
|
|
1451 Disabling a command has no effect on calling it as a function from Lisp
|
|
|
1452 programs.
|
|
|
1453
|
|
|
1454 @node Syntax
|
|
|
1455 @section The Syntax Table
|
|
|
1456 @cindex syntax table
|
|
|
1457
|
|
|
1458 All the Emacs commands which parse words or balance parentheses are
|
|
|
1459 controlled by the @dfn{syntax table}. The syntax table specifies which
|
|
|
1460 characters are opening delimiters, which are parts of words, which are
|
|
|
1461 string quotes, and so on. Actually, each major mode has its own syntax
|
|
|
1462 table (though sometimes related major modes use the same one) which it
|
|
|
1463 installs in each buffer that uses that major mode. The syntax table
|
|
|
1464 installed in the current buffer is the one that all commands use, so we
|
|
|
1465 call it ``the'' syntax table. A syntax table is a Lisp object, a vector of
|
|
|
1466 length 256 whose elements are numbers.
|
|
|
1467
|
|
|
1468 @menu
|
|
|
1469 * Entry: Syntax Entry. What the syntax table records for each character.
|
|
|
1470 * Change: Syntax Change. How to change the information.
|
|
|
1471 @end menu
|
|
|
1472
|
|
|
1473 @node Syntax Entry
|
|
|
1474 @subsection Information About Each Character
|
|
|
1475
|
|
|
1476 The syntax table entry for a character is a number that encodes six
|
|
|
1477 pieces of information:
|
|
|
1478
|
|
|
1479 @itemize @bullet
|
|
|
1480 @item
|
|
|
1481 The syntactic class of the character, represented as a small integer
|
|
|
1482 @item
|
|
|
1483 The matching delimiter, for delimiter characters only
|
|
|
1484 (the matching delimiter of @samp{(} is @samp{)}, and vice versa)
|
|
|
1485 @item
|
|
|
1486 A flag saying whether the character is the first character of a
|
|
|
1487 two-character comment starting sequence
|
|
|
1488 @item
|
|
|
1489 A flag saying whether the character is the second character of a
|
|
|
1490 two-character comment starting sequence
|
|
|
1491 @item
|
|
|
1492 A flag saying whether the character is the first character of a
|
|
|
1493 two-character comment ending sequence
|
|
|
1494 @item
|
|
|
1495 A flag saying whether the character is the second character of a
|
|
|
1496 two-character comment ending sequence
|
|
|
1497 @end itemize
|
|
|
1498
|
|
|
1499 The syntactic classes are stored internally as small integers, but are
|
|
|
1500 usually described to or by the user with characters. For example, @samp{(}
|
|
|
1501 is used to specify the syntactic class of opening delimiters. Here is a
|
|
|
1502 table of syntactic classes, with the characters that specify them.
|
|
|
1503
|
|
|
1504 @table @samp
|
|
871
|
1505 @item @w{-}
|
|
2736
|
1506 The class of whitespace characters. Avoid use of the formerly
|
|
|
1507 advertised @w{ }, because it is not supported by GNU Emacs.
|
|
428
|
1508 @item w
|
|
|
1509 The class of word-constituent characters.
|
|
|
1510 @item _
|
|
|
1511 The class of characters that are part of symbol names but not words.
|
|
|
1512 This class is represented by @samp{_} because the character @samp{_}
|
|
|
1513 has this class in both C and Lisp.
|
|
|
1514 @item .
|
|
|
1515 The class of punctuation characters that do not fit into any other
|
|
|
1516 special class.
|
|
|
1517 @item (
|
|
|
1518 The class of opening delimiters.
|
|
|
1519 @item )
|
|
|
1520 The class of closing delimiters.
|
|
|
1521 @item '
|
|
|
1522 The class of expression-adhering characters. These characters are
|
|
|
1523 part of a symbol if found within or adjacent to one, and are part
|
|
|
1524 of a following expression if immediately preceding one, but are like
|
|
|
1525 whitespace if surrounded by whitespace.
|
|
|
1526 @item "
|
|
|
1527 The class of string-quote characters. They match each other in pairs,
|
|
|
1528 and the characters within the pair all lose their syntactic
|
|
|
1529 significance except for the @samp{\} and @samp{/} classes of escape
|
|
|
1530 characters, which can be used to include a string-quote inside the
|
|
|
1531 string.
|
|
|
1532 @item $
|
|
|
1533 The class of self-matching delimiters. This is intended for @TeX{}'s
|
|
|
1534 @samp{$}, which is used both to enter and leave math mode. Thus,
|
|
|
1535 a pair of matching @samp{$} characters surround each piece of math mode
|
|
|
1536 @TeX{} input. A pair of adjacent @samp{$} characters act like a single
|
|
|
1537 one for purposes of matching.
|
|
|
1538
|
|
|
1539 @item /
|
|
|
1540 The class of escape characters that always just deny the following
|
|
|
1541 character its special syntactic significance. The character after one
|
|
|
1542 of these escapes is always treated as alphabetic.
|
|
|
1543 @item \
|
|
|
1544 The class of C-style escape characters. In practice, these are
|
|
|
1545 treated just like @samp{/}-class characters, because the extra
|
|
|
1546 possibilities for C escapes (such as being followed by digits) have no
|
|
|
1547 effect on where the containing expression ends.
|
|
|
1548 @item <
|
|
|
1549 The class of comment-starting characters. Only single-character
|
|
|
1550 comment starters (such as @samp{;} in Lisp mode) are represented this
|
|
|
1551 way.
|
|
|
1552 @item >
|
|
|
1553 The class of comment-ending characters. Newline has this syntax in
|
|
|
1554 Lisp mode.
|
|
|
1555 @end table
|
|
|
1556
|
|
|
1557 @vindex parse-sexp-ignore-comments
|
|
|
1558 The characters flagged as part of two-character comment delimiters can
|
|
|
1559 have other syntactic functions most of the time. For example, @samp{/} and
|
|
|
1560 @samp{*} in C code, when found separately, have nothing to do with
|
|
|
1561 comments. The comment-delimiter significance overrides when the pair of
|
|
|
1562 characters occur together in the proper order. Only the list and sexp
|
|
|
1563 commands use the syntax table to find comments; the commands specifically
|
|
|
1564 for comments have other variables that tell them where to find comments.
|
|
|
1565 Moreover, the list and sexp commands notice comments only if
|
|
|
1566 @code{parse-sexp-ignore-comments} is non-@code{nil}. This variable is set
|
|
|
1567 to @code{nil} in modes where comment-terminator sequences are liable to
|
|
|
1568 appear where there is no comment, for example, in Lisp mode where the
|
|
|
1569 comment terminator is a newline but not every newline ends a comment.
|
|
|
1570
|
|
|
1571 @node Syntax Change
|
|
|
1572 @subsection Altering Syntax Information
|
|
|
1573
|
|
|
1574 It is possible to alter a character's syntax table entry by storing a new
|
|
|
1575 number in the appropriate element of the syntax table, but it would be hard
|
|
|
1576 to determine what number to use. Emacs therefore provides a command that
|
|
|
1577 allows you to specify the syntactic properties of a character in a
|
|
|
1578 convenient way.
|
|
|
1579
|
|
|
1580 @findex modify-syntax-entry
|
|
|
1581 @kbd{M-x modify-syntax-entry} is the command to change a character's
|
|
|
1582 syntax. It can be used interactively and is also used by major
|
|
|
1583 modes to initialize their own syntax tables. Its first argument is the
|
|
|
1584 character to change. The second argument is a string that specifies the
|
|
|
1585 new syntax. When called from Lisp code, there is a third, optional
|
|
|
1586 argument, which specifies the syntax table in which to make the change. If
|
|
|
1587 not supplied, or if this command is called interactively, the third
|
|
|
1588 argument defaults to the current buffer's syntax table.
|
|
|
1589
|
|
|
1590 @enumerate
|
|
|
1591 @item
|
|
|
1592 The first character in the string specifies the syntactic class. It
|
|
|
1593 is one of the characters in the previous table (@pxref{Syntax Entry}).
|
|
|
1594
|
|
|
1595 @item
|
|
|
1596 The second character is the matching delimiter. For a character that
|
|
|
1597 is not an opening or closing delimiter, this should be a space, and may
|
|
|
1598 be omitted if no following characters are needed.
|
|
|
1599
|
|
|
1600 @item
|
|
|
1601 The remaining characters are flags. The flag characters allowed are:
|
|
|
1602
|
|
|
1603 @table @samp
|
|
|
1604 @item 1
|
|
|
1605 Flag this character as the first of a two-character comment starting sequence.
|
|
|
1606 @item 2
|
|
|
1607 Flag this character as the second of a two-character comment starting sequence.
|
|
|
1608 @item 3
|
|
|
1609 Flag this character as the first of a two-character comment ending sequence.
|
|
|
1610 @item 4
|
|
|
1611 Flag this character as the second of a two-character comment ending sequence.
|
|
|
1612 @end table
|
|
|
1613 @end enumerate
|
|
|
1614
|
|
|
1615 @kindex C-h s
|
|
|
1616 @findex describe-syntax
|
|
|
1617 Use @kbd{C-h s} (@code{describe-syntax}) to display a description of
|
|
|
1618 the contents of the current syntax table. The description of each
|
|
|
1619 character includes both the string you have to pass to
|
|
|
1620 @code{modify-syntax-entry} to set up that character's current syntax,
|
|
|
1621 and some English to explain that string if necessary.
|
|
|
1622
|
|
|
1623 @node Init File
|
|
442
|
1624 @section The Init File
|
|
428
|
1625 @cindex init file
|
|
|
1626 @cindex Emacs initialization file
|
|
|
1627 @cindex key rebinding, permanent
|
|
|
1628 @cindex rebinding keys, permanently
|
|
|
1629
|
|
442
|
1630 When you start Emacs, it normally loads either @file{.xemacs/init.el}
|
|
|
1631 or the file @file{.emacs} (whichever comes first) in your home directory.
|
|
|
1632 This file, if it exists, should contain Lisp code. It is called your
|
|
|
1633 initialization file or @dfn{init file}. Use the command line switch
|
|
|
1634 @samp{-q} to tell Emacs whether to load an init file (@pxref{Entering
|
|
|
1635 Emacs}). Use the command line switch @samp{-user-init-file}
|
|
|
1636 (@pxref{Command Switches}) to tell Emacs to load a different file
|
|
|
1637 instead of @file{~/.xemacs/init.el}/@file{~/.emacs}.
|
|
|
1638
|
|
|
1639 When the init file is read, the variable @code{user-init-file} says
|
|
|
1640 which init file was loaded.
|
|
428
|
1641
|
|
|
1642 At some sites there is a @dfn{default init file}, which is the
|
|
|
1643 library named @file{default.el}, found via the standard search path for
|
|
|
1644 libraries. The Emacs distribution contains no such library; your site
|
|
|
1645 may create one for local customizations. If this library exists, it is
|
|
|
1646 loaded whenever you start Emacs. But your init file, if any, is loaded
|
|
|
1647 first; if it sets @code{inhibit-default-init} non-@code{nil}, then
|
|
|
1648 @file{default} is not loaded.
|
|
|
1649
|
|
442
|
1650 If you have a large amount of code in your init file, you should
|
|
|
1651 byte-compile it to @file{~/.xemacs/init.elc} or @file{~/.emacs.elc}.
|
|
428
|
1652
|
|
|
1653 @menu
|
|
|
1654 * Init Syntax:: Syntax of constants in Emacs Lisp.
|
|
|
1655 * Init Examples:: How to do some things with an init file.
|
|
|
1656 * Terminal Init:: Each terminal type can have an init file.
|
|
|
1657 @end menu
|
|
|
1658
|
|
|
1659 @node Init Syntax
|
|
|
1660 @subsection Init File Syntax
|
|
|
1661
|
|
442
|
1662 The init file contains one or more Lisp function call
|
|
428
|
1663 expressions. Each consists of a function name followed by
|
|
|
1664 arguments, all surrounded by parentheses. For example, @code{(setq
|
|
|
1665 fill-column 60)} represents a call to the function @code{setq} which is
|
|
|
1666 used to set the variable @code{fill-column} (@pxref{Filling}) to 60.
|
|
|
1667
|
|
|
1668 The second argument to @code{setq} is an expression for the new value
|
|
|
1669 of the variable. This can be a constant, a variable, or a function call
|
|
442
|
1670 expression. In the init file, constants are used most of the time.
|
|
428
|
1671 They can be:
|
|
|
1672
|
|
|
1673 @table @asis
|
|
|
1674 @item Numbers
|
|
|
1675 Integers are written in decimal, with an optional initial minus sign.
|
|
|
1676
|
|
|
1677 If a sequence of digits is followed by a period and another sequence
|
|
|
1678 of digits, it is interpreted as a floating point number.
|
|
|
1679
|
|
|
1680 The number prefixes @samp{#b}, @samp{#o}, and @samp{#x} are supported to
|
|
|
1681 represent numbers in binary, octal, and hexadecimal notation (or radix).
|
|
|
1682
|
|
|
1683 @item Strings
|
|
|
1684 Lisp string syntax is the same as C string syntax with a few extra
|
|
|
1685 features. Use a double-quote character to begin and end a string constant.
|
|
|
1686
|
|
|
1687 Newlines and special characters may be present literally in strings. They
|
|
|
1688 can also be represented as backslash sequences: @samp{\n} for newline,
|
|
|
1689 @samp{\b} for backspace, @samp{\r} for return, @samp{\t} for tab,
|
|
|
1690 @samp{\f} for formfeed (control-l), @samp{\e} for escape, @samp{\\} for a
|
|
|
1691 backslash, @samp{\"} for a double-quote, or @samp{\@var{ooo}} for the
|
|
|
1692 character whose octal code is @var{ooo}. Backslash and double-quote are
|
|
|
1693 the only characters for which backslash sequences are mandatory.
|
|
|
1694
|
|
|
1695 You can use @samp{\C-} as a prefix for a control character, as in
|
|
|
1696 @samp{\C-s} for ASCII Control-S, and @samp{\M-} as a prefix for
|
|
|
1697 a Meta character, as in @samp{\M-a} for Meta-A or @samp{\M-\C-a} for
|
|
|
1698 Control-Meta-A.@refill
|
|
|
1699
|
|
|
1700 @item Characters
|
|
|
1701 Lisp character constant syntax consists of a @samp{?} followed by
|
|
|
1702 either a character or an escape sequence starting with @samp{\}.
|
|
|
1703 Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}. Note that
|
|
|
1704 strings and characters are not interchangeable in Lisp; some contexts
|
|
|
1705 require one and some contexts require the other.
|
|
|
1706
|
|
|
1707 @item True
|
|
|
1708 @code{t} stands for `true'.
|
|
|
1709
|
|
|
1710 @item False
|
|
|
1711 @code{nil} stands for `false'.
|
|
|
1712
|
|
|
1713 @item Other Lisp objects
|
|
|
1714 Write a single-quote (') followed by the Lisp object you want.
|
|
|
1715 @end table
|
|
|
1716
|
|
|
1717 @node Init Examples
|
|
|
1718 @subsection Init File Examples
|
|
|
1719
|
|
|
1720 Here are some examples of doing certain commonly desired things with
|
|
|
1721 Lisp expressions:
|
|
|
1722
|
|
|
1723 @itemize @bullet
|
|
|
1724 @item
|
|
|
1725 Make @key{TAB} in C mode just insert a tab if point is in the middle of a
|
|
|
1726 line.
|
|
|
1727
|
|
|
1728 @example
|
|
|
1729 (setq c-tab-always-indent nil)
|
|
|
1730 @end example
|
|
|
1731
|
|
|
1732 Here we have a variable whose value is normally @code{t} for `true'
|
|
|
1733 and the alternative is @code{nil} for `false'.
|
|
|
1734
|
|
|
1735 @item
|
|
|
1736 Make searches case sensitive by default (in all buffers that do not
|
|
|
1737 override this).
|
|
|
1738
|
|
|
1739 @example
|
|
|
1740 (setq-default case-fold-search nil)
|
|
|
1741 @end example
|
|
|
1742
|
|
|
1743 This sets the default value, which is effective in all buffers that do
|
|
|
1744 not have local values for the variable. Setting @code{case-fold-search}
|
|
|
1745 with @code{setq} affects only the current buffer's local value, which
|
|
|
1746 is probably not what you want to do in an init file.
|
|
|
1747
|
|
|
1748 @item
|
|
|
1749 Make Text mode the default mode for new buffers.
|
|
|
1750
|
|
|
1751 @example
|
|
|
1752 (setq default-major-mode 'text-mode)
|
|
|
1753 @end example
|
|
|
1754
|
|
|
1755 Note that @code{text-mode} is used because it is the command for entering
|
|
|
1756 the mode we want. A single-quote is written before it to make a symbol
|
|
|
1757 constant; otherwise, @code{text-mode} would be treated as a variable name.
|
|
|
1758
|
|
|
1759 @item
|
|
|
1760 Turn on Auto Fill mode automatically in Text mode and related modes.
|
|
|
1761
|
|
|
1762 @example
|
|
|
1763 (setq text-mode-hook
|
|
|
1764 '(lambda () (auto-fill-mode 1)))
|
|
|
1765 @end example
|
|
|
1766
|
|
|
1767 Here we have a variable whose value should be a Lisp function. The
|
|
|
1768 function we supply is a list starting with @code{lambda}, and a single
|
|
|
1769 quote is written in front of it to make it (for the purpose of this
|
|
|
1770 @code{setq}) a list constant rather than an expression. Lisp functions
|
|
|
1771 are not explained here; for mode hooks it is enough to know that
|
|
|
1772 @code{(auto-fill-mode 1)} is an expression that will be executed when
|
|
|
1773 Text mode is entered. You could replace it with any other expression
|
|
|
1774 that you like, or with several expressions in a row.
|
|
|
1775
|
|
|
1776 @example
|
|
|
1777 (setq text-mode-hook 'turn-on-auto-fill)
|
|
|
1778 @end example
|
|
|
1779
|
|
|
1780 This is another way to accomplish the same result.
|
|
|
1781 @code{turn-on-auto-fill} is a symbol whose function definition is
|
|
|
1782 @code{(lambda () (auto-fill-mode 1))}.
|
|
|
1783
|
|
|
1784 @item
|
|
|
1785 Load the installed Lisp library named @file{foo} (actually a file
|
|
|
1786 @file{foo.elc} or @file{foo.el} in a standard Emacs directory).
|
|
|
1787
|
|
|
1788 @example
|
|
|
1789 (load "foo")
|
|
|
1790 @end example
|
|
|
1791
|
|
|
1792 When the argument to @code{load} is a relative pathname, not starting
|
|
|
1793 with @samp{/} or @samp{~}, @code{load} searches the directories in
|
|
|
1794 @code{load-path} (@pxref{Loading}).
|
|
|
1795
|
|
|
1796 @item
|
|
|
1797 Load the compiled Lisp file @file{foo.elc} from your home directory.
|
|
|
1798
|
|
|
1799 @example
|
|
|
1800 (load "~/foo.elc")
|
|
|
1801 @end example
|
|
|
1802
|
|
|
1803 Here an absolute file name is used, so no searching is done.
|
|
|
1804
|
|
|
1805 @item
|
|
|
1806 Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}.
|
|
|
1807
|
|
|
1808 @example
|
|
|
1809 (global-set-key "\C-xl" 'make-symbolic-link)
|
|
|
1810 @end example
|
|
|
1811
|
|
|
1812 or
|
|
|
1813
|
|
|
1814 @example
|
|
|
1815 (define-key global-map "\C-xl" 'make-symbolic-link)
|
|
|
1816 @end example
|
|
|
1817
|
|
|
1818 Note once again the single-quote used to refer to the symbol
|
|
|
1819 @code{make-symbolic-link} instead of its value as a variable.
|
|
|
1820
|
|
|
1821 @item
|
|
|
1822 Do the same thing for C mode only.
|
|
|
1823
|
|
|
1824 @example
|
|
|
1825 (define-key c-mode-map "\C-xl" 'make-symbolic-link)
|
|
|
1826 @end example
|
|
|
1827
|
|
|
1828 @item
|
|
|
1829 Bind the function key @key{F1} to a command in C mode.
|
|
|
1830 Note that the names of function keys must be lower case.
|
|
|
1831
|
|
|
1832 @example
|
|
|
1833 (define-key c-mode-map 'f1 'make-symbolic-link)
|
|
|
1834 @end example
|
|
|
1835
|
|
|
1836 @item
|
|
|
1837 Bind the shifted version of @key{F1} to a command.
|
|
|
1838
|
|
|
1839 @example
|
|
|
1840 (define-key c-mode-map '(shift f1) 'make-symbolic-link)
|
|
|
1841 @end example
|
|
|
1842
|
|
|
1843 @item
|
|
|
1844 Redefine all keys which now run @code{next-line} in Fundamental mode
|
|
|
1845 to run @code{forward-line} instead.
|
|
|
1846
|
|
|
1847 @example
|
|
|
1848 (substitute-key-definition 'next-line 'forward-line
|
|
|
1849 global-map)
|
|
|
1850 @end example
|
|
|
1851
|
|
|
1852 @item
|
|
|
1853 Make @kbd{C-x C-v} undefined.
|
|
|
1854
|
|
|
1855 @example
|
|
|
1856 (global-unset-key "\C-x\C-v")
|
|
|
1857 @end example
|
|
|
1858
|
|
|
1859 One reason to undefine a key is so that you can make it a prefix.
|
|
|
1860 Simply defining @kbd{C-x C-v @var{anything}} would make @kbd{C-x C-v}
|
|
|
1861 a prefix, but @kbd{C-x C-v} must be freed of any non-prefix definition
|
|
|
1862 first.
|
|
|
1863
|
|
|
1864 @item
|
|
|
1865 Make @samp{$} have the syntax of punctuation in Text mode.
|
|
|
1866 Note the use of a character constant for @samp{$}.
|
|
|
1867
|
|
|
1868 @example
|
|
|
1869 (modify-syntax-entry ?\$ "." text-mode-syntax-table)
|
|
|
1870 @end example
|
|
|
1871
|
|
|
1872 @item
|
|
|
1873 Enable the use of the command @code{eval-expression} without confirmation.
|
|
|
1874
|
|
|
1875 @example
|
|
|
1876 (put 'eval-expression 'disabled nil)
|
|
|
1877 @end example
|
|
|
1878 @end itemize
|
|
|
1879
|
|
|
1880 @node Terminal Init
|
|
|
1881 @subsection Terminal-Specific Initialization
|
|
|
1882
|
|
|
1883 Each terminal type can have a Lisp library to be loaded into Emacs when
|
|
|
1884 it is run on that type of terminal. For a terminal type named
|
|
|
1885 @var{termtype}, the library is called @file{term/@var{termtype}} and it is
|
|
|
1886 found by searching the directories @code{load-path} as usual and trying the
|
|
|
1887 suffixes @samp{.elc} and @samp{.el}. Normally it appears in the
|
|
|
1888 subdirectory @file{term} of the directory where most Emacs libraries are
|
|
|
1889 kept.@refill
|
|
|
1890
|
|
|
1891 The usual purpose of the terminal-specific library is to define the
|
|
|
1892 escape sequences used by the terminal's function keys using the library
|
|
|
1893 @file{keypad.el}. See the file
|
|
|
1894 @file{term/vt100.el} for an example of how this is done.@refill
|
|
|
1895
|
|
|
1896 When the terminal type contains a hyphen, only the part of the name
|
|
|
1897 before the first hyphen is significant in choosing the library name.
|
|
|
1898 Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
|
|
|
1899 the library @file{term/aaa}. The code in the library can use
|
|
|
1900 @code{(getenv "TERM")} to find the full terminal type name.@refill
|
|
|
1901
|
|
|
1902 @vindex term-file-prefix
|
|
|
1903 The library's name is constructed by concatenating the value of the
|
|
442
|
1904 variable @code{term-file-prefix} and the terminal type. Your init
|
|
428
|
1905 file can prevent the loading of the terminal-specific library by setting
|
|
442
|
1906 @code{term-file-prefix} to @code{nil}. @xref{Init File}.
|
|
428
|
1907
|
|
|
1908 @vindex term-setup-hook
|
|
|
1909 The value of the variable @code{term-setup-hook}, if not @code{nil}, is
|
|
|
1910 called as a function of no arguments at the end of Emacs initialization,
|
|
442
|
1911 after both your init file and any terminal-specific library have been
|
|
|
1912 read. @xref{Init File}. You can set the value in the init file to
|
|
|
1913 override part of any of the terminal-specific libraries and to define
|
|
428
|
1914 initializations for terminals that do not have a library.@refill
|
|
|
1915
|
|
|
1916 @node Audible Bell
|
|
|
1917 @section Changing the Bell Sound
|
|
|
1918 @cindex audible bell, changing
|
|
|
1919 @cindex bell, changing
|
|
|
1920 @vindex sound-alist
|
|
|
1921 @findex load-default-sounds
|
|
|
1922 @findex play-sound
|
|
|
1923
|
|
|
1924 You can now change how the audible bell sounds using the variable
|
|
|
1925 @code{sound-alist}.
|
|
|
1926
|
|
|
1927 @code{sound-alist}'s value is an list associating symbols with, among
|
|
|
1928 other things, strings of audio-data. When @code{ding} is called with
|
|
|
1929 one of the symbols, the associated sound data is played instead of the
|
|
|
1930 standard beep. This only works if you are logged in on the console of a
|
|
|
1931 machine with audio hardware. To listen to a sound of the provided type,
|
|
|
1932 call the function @code{play-sound} with the argument @var{sound}. You
|
|
1137
|
1933 can also set the volume of the sound with the optional argument
|
|
428
|
1934 @var{volume}.@refill
|
|
|
1935 @cindex ding
|
|
|
1936
|
|
|
1937 Each element of @code{sound-alist} is a list describing a sound.
|
|
|
1938 The first element of the list is the name of the sound being defined.
|
|
|
1939 Subsequent elements of the list are alternating keyword/value pairs:
|
|
|
1940
|
|
|
1941 @table @code
|
|
|
1942 @item sound
|
|
1137
|
1943 A string of raw sound data, or the name of another sound to play.
|
|
428
|
1944 The symbol @code{t} here means use the default X beep.
|
|
|
1945
|
|
|
1946 @item volume
|
|
|
1947 An integer from 0-100, defaulting to @code{bell-volume}.
|
|
|
1948
|
|
|
1949 @item pitch
|
|
|
1950 If using the default X beep, the pitch (Hz) to generate.
|
|
|
1951
|
|
|
1952 @item duration
|
|
|
1953 If using the default X beep, the duration (milliseconds).
|
|
|
1954 @end table
|
|
|
1955
|
|
|
1956 For compatibility, elements of `sound-alist' may also be of the form:
|
|
|
1957
|
|
|
1958 @example
|
|
|
1959 ( @var{sound-name} . @var{<sound>} )
|
|
|
1960 ( @var{sound-name} @var{<volume>} @var{<sound>} )
|
|
|
1961 @end example
|
|
|
1962
|
|
|
1963 You should probably add things to this list by calling the function
|
|
|
1964 @code{load-sound-file}.
|
|
|
1965
|
|
|
1966 Note that you can only play audio data if running on the console screen
|
|
|
1967 of a machine with audio hardware which emacs understands, which at this
|
|
|
1968 time means a Sun SparcStation, SGI, or HP9000s700.
|
|
|
1969
|
|
|
1970 Also note that the pitch, duration, and volume options are available
|
|
|
1971 everywhere, but most X servers ignore the `pitch' option.
|
|
|
1972
|
|
|
1973 @vindex bell-volume
|
|
|
1974 The variable @code{bell-volume} should be an integer from 0 to 100,
|
|
|
1975 with 100 being loudest, which controls how loud the sounds emacs makes
|
|
|
1976 should be. Elements of the @code{sound-alist} may override this value.
|
|
|
1977 This variable applies to the standard X bell sound as well as sound files.
|
|
|
1978
|
|
|
1979 If the symbol @code{t} is in place of a sound-string, Emacs uses the
|
|
1137
|
1980 default X beep. This allows you to define beep-types of
|
|
428
|
1981 different volumes even when not running on the console.
|
|
|
1982
|
|
|
1983 @findex load-sound-file
|
|
|
1984 You can add things to this list by calling the function
|
|
|
1985 @code{load-sound-file}, which reads in an audio-file and adds its data to
|
|
|
1986 the sound-alist. You can specify the sound with the @var{sound-name}
|
|
|
1987 argument and the file into which the sounds are loaded with the
|
|
|
1988 @var{filename} argument. The optional @var{volume} argument sets the
|
|
|
1989 volume.
|
|
|
1990
|
|
|
1991 @code{load-sound-file (@var{filename sound-name} &optional @var{volume})}
|
|
|
1992
|
|
|
1993 To load and install some sound files as beep-types, use the function
|
|
|
1994 @code{load-default-sounds} (note that this only works if you are on
|
|
|
1995 display 0 of a machine with audio hardware).
|
|
|
1996
|
|
|
1997 The following beep-types are used by Emacs itself. Other Lisp
|
|
|
1998 packages may use other beep types, but these are the ones that the C
|
|
|
1999 kernel of Emacs uses.
|
|
|
2000
|
|
|
2001 @table @code
|
|
|
2002 @item auto-save-error
|
|
|
2003 An auto-save does not succeed
|
|
|
2004
|
|
|
2005 @item command-error
|
|
|
2006 The Emacs command loop catches an error
|
|
|
2007
|
|
|
2008 @item undefined-key
|
|
|
2009 You type a key that is undefined
|
|
|
2010
|
|
440
|
2011 @item undefined-click
|
|
428
|
2012 You use an undefined mouse-click combination
|
|
|
2013
|
|
440
|
2014 @item no-completion
|
|
428
|
2015 Completion was not possible
|
|
|
2016
|
|
440
|
2017 @item y-or-n-p
|
|
428
|
2018 You type something other than the required @code{y} or @code{n}
|
|
|
2019
|
|
1137
|
2020 @item yes-or-no-p
|
|
428
|
2021 You type something other than @code{yes} or @code{no}
|
|
|
2022 @end table
|
|
|
2023
|
|
|
2024 @comment node-name, next, previous, up
|
|
|
2025 @node Faces
|
|
|
2026 @section Faces
|
|
|
2027
|
|
|
2028 XEmacs has objects called extents and faces. An @dfn{extent}
|
|
|
2029 is a region of text and a @dfn{face} is a collection of textual
|
|
|
2030 attributes, such as fonts and colors. Every extent is displayed in some
|
|
|
2031 face; therefore, changing the properties of a face immediately updates the
|
|
|
2032 display of all associated extents. Faces can be frame-local: you can
|
|
|
2033 have a region of text that displays with completely different
|
|
|
2034 attributes when its buffer is viewed from a different X window.
|
|
|
2035
|
|
|
2036 The display attributes of faces may be specified either in Lisp or through
|
|
|
2037 the X resource manager.
|
|
|
2038
|
|
3387
|
2039 Basic Xft support has been merged into the mainline, and it looks pretty
|
|
|
2040 good. However, customization UI and documentation still leaves a lot to
|
|
|
2041 be desired. Here's a first cut, as a separate node.
|
|
|
2042
|
|
|
2043 @menu
|
|
|
2044 * Xft Font Customization::
|
|
|
2045 @end menu
|
|
|
2046
|
|
428
|
2047 @subsection Customizing Faces
|
|
|
2048
|
|
|
2049 You can change the face of an extent with the functions in
|
|
|
2050 this section. All the functions prompt for a @var{face} as an
|
|
|
2051 argument; use completion for a list of possible values.
|
|
|
2052
|
|
|
2053 @table @kbd
|
|
|
2054 @item M-x invert-face
|
|
|
2055 Swap the foreground and background colors of the given @var{face}.
|
|
|
2056 @item M-x make-face-bold
|
|
|
2057 Make the font of the given @var{face} bold. When called from a
|
|
|
2058 program, returns @code{nil} if this is not possible.
|
|
|
2059 @item M-x make-face-bold-italic
|
|
1137
|
2060 Make the font of the given @var{face} bold italic.
|
|
428
|
2061 When called from a program, returns @code{nil} if not possible.
|
|
|
2062 @item M-x make-face-italic
|
|
1137
|
2063 Make the font of the given @var{face} italic.
|
|
428
|
2064 When called from a program, returns @code{nil} if not possible.
|
|
|
2065 @item M-x make-face-unbold
|
|
1137
|
2066 Make the font of the given @var{face} non-bold.
|
|
428
|
2067 When called from a program, returns @code{nil} if not possible.
|
|
|
2068 @item M-x make-face-unitalic
|
|
|
2069 Make the font of the given @var{face} non-italic.
|
|
|
2070 When called from a program, returns @code{nil} if not possible.
|
|
|
2071 @item M-x make-face-larger
|
|
|
2072 Make the font of the given @var{face} a little larger.
|
|
|
2073 When called from a program, returns @code{nil} if not possible.
|
|
|
2074 @item M-x make-face-smaller
|
|
|
2075 Make the font of the given @var{face} a little smaller.
|
|
|
2076 When called from a program, returns @code{nil} if not possible.
|
|
1137
|
2077 @item M-x set-face-background
|
|
428
|
2078 Change the background color of the given @var{face}.
|
|
|
2079 @item M-x set-face-background-pixmap
|
|
|
2080 Change the background pixmap of the given @var{face}.
|
|
1137
|
2081 @item M-x set-face-background-pixmap-file
|
|
|
2082 A simpler version but with filename completion.
|
|
|
2083 @item M-x set-face-font
|
|
428
|
2084 Change the font of the given @var{face}.
|
|
|
2085 @item M-x set-face-foreground
|
|
|
2086 Change the foreground color of the given @var{face}.
|
|
|
2087 @item M-x set-face-underline-p
|
|
|
2088 Change whether the given @var{face} is underlined.
|
|
|
2089 @end table
|
|
|
2090
|
|
|
2091 @findex make-face-larger
|
|
|
2092 @findex make-face-smaller
|
|
|
2093
|
|
|
2094 @findex invert-face
|
|
|
2095 You can exchange the foreground and background color of the selected
|
|
|
2096 @var{face} with the function @code{invert-face}. If the face does not
|
|
|
2097 specify both foreground and background, then its foreground and
|
|
|
2098 background are set to the background and foreground of the default face.
|
|
1137
|
2099 When calling this from a program, you can supply the optional argument
|
|
428
|
2100 @var{frame} to specify which frame is affected; otherwise, all frames
|
|
|
2101 are affected.
|
|
|
2102
|
|
1142
|
2103 @findex make-face-bold
|
|
|
2104 @findex make-face-bold-italic
|
|
|
2105 @findex make-face-italic
|
|
|
2106 @findex make-face-unbold
|
|
|
2107 @findex make-face-unitalic
|
|
|
2108 @vindex face-frob-from-locale-first
|
|
|
2109 The work of @code{make-face-bold}, @code{make-face-bold-italic},
|
|
|
2110 @code{make-face-italic}, @code{make-face-unbold},
|
|
|
2111 @code{make-face-unitalic} functions is affected by
|
|
|
2112 @code{face-frob-from-locale-first} variable. If it is @code{nil}, those
|
|
|
2113 functions first try to manipulate device specific data like X font names
|
|
|
2114 to obtain the desired font face specification. This may be unsuitable
|
|
|
2115 in environments using different font face specifications for different
|
|
|
2116 frames, non-Mule environments in particular.
|
|
|
2117
|
|
|
2118 If the variable is non-@code{nil}, those functions first try to figure
|
|
|
2119 out whether the face font is the same as one of predefined faces:
|
|
|
2120 @code{default}, @code{bold}, @code{italic}, @code{bold-italic}. If it
|
|
|
2121 is the same, then the new face font specification is set to be the same
|
|
|
2122 as that of a corresponding predefined face. Thus if the predefined face
|
|
|
2123 is set up properly for different frames, the same will hold for the face
|
|
|
2124 being changed by the functions. This is the behavior one might desire
|
|
|
2125 in non-Mule environments mentioned above: face being changed still looks
|
|
|
2126 right in all frames.
|
|
|
2127
|
|
|
2128 How predefined faces might be set up for different frames in such an
|
|
|
2129 environments is described in @ref{Face Resources}.
|
|
|
2130
|
|
428
|
2131 @findex set-face-background
|
|
|
2132 You can set the background color of the specified @var{face} with the
|
|
|
2133 function @code{set-face-background}. The argument @code{color} should
|
|
|
2134 be a string, the name of a color. When called from a program, if the
|
|
1137
|
2135 optional @var{frame} argument is provided, the face is changed only
|
|
428
|
2136 in that frame; otherwise, it is changed in all frames.
|
|
|
2137
|
|
|
2138 @findex set-face-background-pixmap
|
|
|
2139 You can set the background pixmap of the specified @var{face} with the
|
|
|
2140 function @code{set-face-background-pixmap}. The pixmap argument
|
|
|
2141 @var{name} should be a string, the name of a file of pixmap data. The
|
|
|
2142 directories listed in the @code{x-bitmap-file-path} variable are
|
|
|
2143 searched. The bitmap may also be a list of the form @code{(@var{width
|
|
|
2144 height data})}, where @var{width} and @var{height} are the size in
|
|
|
2145 pixels, and @var{data} is a string containing the raw bits of the
|
|
|
2146 bitmap. If the optional @var{frame} argument is provided, the face is
|
|
|
2147 changed only in that frame; otherwise, it is changed in all frames.
|
|
|
2148
|
|
|
2149 The variable @code{x-bitmap-file-path} takes as a value a list of the
|
|
|
2150 directories in which X bitmap files may be found. If the value is
|
|
|
2151 @code{nil}, the list is initialized from the @code{*bitmapFilePath}
|
|
|
2152 resource.
|
|
|
2153
|
|
|
2154 If the environment variable @b{XBMLANGPATH} is set, then it is consulted
|
|
|
2155 before the @code{x-bitmap-file-path} variable.
|
|
|
2156
|
|
1137
|
2157 @findex set-face-background-pixmap
|
|
|
2158 Alternately, you can use a simpler version of
|
|
|
2159 @code{set-face-background-pixmap} called
|
|
|
2160 @code{set-face-background-pixmap-file}. This function does not give you
|
|
3111
|
2161 as much control on the pixmap instantiator, but provides filename
|
|
1137
|
2162 completion.
|
|
|
2163
|
|
428
|
2164 @findex set-face-font
|
|
|
2165 You can set the font of the specified @var{face} with the function
|
|
|
2166 @code{set-face-font}. The @var{font} argument should be a string, the
|
|
|
2167 name of a font. When called from a program, if the
|
|
1137
|
2168 optional @var{frame} argument is provided, the face is changed only
|
|
428
|
2169 in that frame; otherwise, it is changed in all frames.
|
|
|
2170
|
|
3111
|
2171 The syntax of the @var{font} argument varies according to platform. In
|
|
|
2172 each of the following syntaxes, the example shows how to specify a
|
|
|
2173 14-point upright bold Courier font.
|
|
|
2174
|
|
|
2175 @table @strong
|
|
|
2176 @item X11
|
|
|
2177 The X11 syntax is defined by the @dfn{X Logical Font Descriptor} (XLFD)
|
|
|
2178 standard. An XLFD contains 14 fields each preceded by a hyphen:
|
|
|
2179 foundry, family, weight, slant, swidth, adstyle, pixelsize, pointsize,
|
|
|
2180 xresolution, yresolution, spacing, averagewidth, registry, and encoding.
|
|
|
2181 It is usually sufficient to specify family, weight, slant, pointsize,
|
|
|
2182 registry, and encoding, wildcarding the rest with @samp{*}. If you're
|
|
|
2183 not sure what's available, you can wildcard some of the fields usually
|
|
|
2184 specified, too. Here's our example font in XLFD syntax:
|
|
|
2185 @code{"-*-courier-bold-r-*-*-*-140-*-*-*-*-iso8859-*"}.
|
|
|
2186 The XLFD syntax is also used for GTK+ version 1. XLFD names must be
|
|
3510
|
2187 encoded in ISO-8859-1.
|
|
3111
|
2188
|
|
|
2189 @item Xft
|
|
|
2190 The Xft syntax is defined by the @file{fontconfig} library
|
|
|
2191 @ref{Font Names,,,fontconfig}. It is less a font naming convention than
|
|
|
2192 a way to express any arbitrary subset of the font's properties in a
|
|
|
2193 syntax that is both human- and machine-readable. A @file{fontconfig}
|
|
|
2194 font name contains the family, a hyphen, and the pointsize, followed by
|
|
|
2195 an arbitrary sequence of properties. Each property consists of a colon,
|
|
|
2196 a keyword, an equals sign, and the property value. Here's our example
|
|
|
2197 font in @file{fontconfig} syntax: @code{"Courier-14:weight=bold"}. This
|
|
|
2198 syntax admits ``style abbreviations'' which can be user-defined. A
|
|
|
2199 style is a single keyword denoting a sequence of properties. So the
|
|
|
2200 example font may be abbreviated to @code{"Courier-14:bold"} ("bold" is a
|
|
|
2201 standard abbreviation for "weight=bold"). The @file{fontconfig} syntax
|
|
|
2202 is also used for GTK+ version 2. @file{fontconfig} names must be
|
|
|
2203 encoded in UTF-8.
|
|
|
2204
|
|
|
2205 @item MS-Windows
|
|
|
2206 The MS Windows syntax is superficially similar to that of Xft but
|
|
|
2207 actually is more like XLFD. A font name consists of five fields,
|
|
|
2208 family, size, slant, weight, and encoding, each expressed as a keyword
|
|
|
2209 taking on standardized values (except family, which is just a name).
|
|
|
2210 Here's our example font in MS Windows syntax:
|
|
|
2211 @code{"Courier:14:Bold:Western"}.
|
|
|
2212 @end table
|
|
|
2213
|
|
1137
|
2214 @findex set-face-foreground
|
|
428
|
2215 You can set the foreground color of the specified @var{face} with the
|
|
|
2216 function @code{set-face-foreground}. The argument @var{color} should be
|
|
|
2217 a string, the name of a color. If the optional @var{frame} argument is
|
|
|
2218 provided, the face is changed only in that frame; otherwise, it is
|
|
|
2219 changed in all frames.
|
|
|
2220
|
|
|
2221 @findex set-face-underline-p
|
|
|
2222 You can set underline the specified @var{face} with the function
|
|
|
2223 @code{set-face-underline-p}. The argument @var{underline-p} can be used
|
|
|
2224 to make underlining an attribute of the face or not. If the optional
|
|
|
2225 @var{frame} argument is provided, the face is changed only in that
|
|
|
2226 frame; otherwise, it is changed in all frames.
|
|
|
2227
|
|
3387
|
2228
|
|
|
2229 @node Xft Font Customization, , , Faces
|
|
|
2230 @section Xft Font Customization
|
|
|
2231
|
|
|
2232 This section was written by @email{stephen@@xemacs.org,Stephen Turnbull},
|
|
|
2233 and is very much a work in progress. I've tried to provide pointers to
|
|
|
2234 as much of the relevant information as possible, but many of the APIs
|
|
|
2235 and UIs are in flux, so it seemed more work than it was worth to
|
|
|
2236 completely translate the tables of constants, and so on. Feel free to
|
|
|
2237 ask for clarifications, @emph{etc.} Please Cc
|
|
|
2238 @email{xemacs-beta@@xemacs.org,the XEmacs Beta Testers' mailing list},
|
|
|
2239 as that is the issue tracking channel of record, and there are a few
|
|
|
2240 others who can answer the questions or improve documentation when I'm
|
|
|
2241 not able to respond quickly.
|
|
|
2242
|
|
|
2243 @c Don't blame Ben (or Eric and Matthias, for that matter). Feel free to
|
|
|
2244 @c add, edit, and share the blame, everybody!
|
|
|
2245
|
|
|
2246 @c #### Make these @urlref's!!
|
|
|
2247 As of mid-2005, we have added support for the
|
|
|
2248 @file{Xft} library, which provides a more robust @emph{font
|
|
|
2249 configuration} mechanism via Keith Packard's @file{fontconfig} library;
|
|
|
2250 improved glyph rendering, including antialiasing, via the
|
|
|
2251 @file{freetype} library; and client-side rendering (saving bandwidth and
|
|
|
2252 server memory) via the @file{XRender extension}.
|
|
|
2253
|
|
|
2254 @c #### Describe Alexey Gladkov and Yury Konovalov's work.
|
|
|
2255
|
|
|
2256 @subheading Font configuration
|
|
|
2257
|
|
|
2258 In XEmacs, font configuration is handled via @emph{faces}. Currently
|
|
|
2259 XEmacs uses a special type of @emph{font specifier} to map XEmacs
|
|
|
2260 locales to font names. Especially under X11, this can cause annoying
|
|
|
2261 problems because of the unreliability of X servers' mappings from
|
|
|
2262 @samp{XLFD} names to X11 fonts, over which XEmacs has no influence
|
|
|
2263 whatsoever. However, the @file{fontconfig} library which is used with
|
|
|
2264 @file{Xft} provides much more reliable mapping, along with a more
|
|
|
2265 reliably parsable naming scheme similar to that used by TrueType fonts
|
|
|
2266 on MS Windows and the Macintosh.
|
|
|
2267
|
|
|
2268 @subheading fontconfig
|
|
|
2269
|
|
|
2270 Fontconfig is dramatically different from the X model in several ways.
|
|
|
2271 In particular, when queried for a font @emph{fontconfig always returns a
|
|
|
2272 font}, whereas X queries may return ``not found.'' However, the font
|
|
|
2273 returned need not be anything like the desired font. This is not really
|
|
|
2274 a problem in practice, because users generally have a pretty good idea
|
|
|
2275 of what fonts are available on their display. However, users should be
|
|
|
2276 aware that as of XEmacs 21.5.26 the font selection internals have not
|
|
|
2277 been revised to account for this radically different model, so some
|
|
|
2278 surprising results are possible.
|
|
|
2279
|
|
|
2280 From the user's point of view, @file{fontconfig} provides a naming
|
|
|
2281 convention which is @emph{precise}, @emph{accurate}, and
|
|
|
2282 @emph{convenient}. Precision means that all properties available in the
|
|
|
2283 programming API can be individually specified. Accuracy means that the
|
|
|
2284 truename of the font is exactly the list of all properties specified by
|
|
|
2285 the font. Thus, the anomolies that occur with XLFDs on many servers
|
|
|
2286 (including modern Linux distributions with XFree86 or X.org servers)
|
|
|
2287 cannot occur. Convenience is subjective, of course. However,
|
|
|
2288 @file{fontconfig} provides a configuration system which (1) explicitly
|
|
|
2289 specifies the defaults and substitutions that will be made in processing
|
|
|
2290 user queries, (2) allows the user to specify search configuration,
|
|
|
2291 abbreviations, substitutions, and defaults that override the system's,
|
|
|
2292 in the same format as used by system files, and (3) allows flexible
|
|
|
2293 aliases that can resolve to any of several actual fonts depending on
|
|
|
2294 which fonts are installed.
|
|
|
2295
|
|
|
2296 Further, a @dfn{standard minimal configuration} is defined that ensures
|
|
|
2297 that at least the @emph{serif}, @emph{sans-serif}, and @emph{monospace}
|
|
|
2298 font aliases are available on all @file{fontconfig} systems.
|
|
|
2299
|
|
|
2300 @subheading fontconfig font names
|
|
|
2301
|
|
|
2302 @file{fontconfig} font names are very regular, and constitute a precise
|
|
|
2303 and extensible specification of a font's properties.
|
|
|
2304
|
|
|
2305 The basic @file{fontconfig} font name has three components: the font
|
|
|
2306 family name, the size, and a list of named attribute fields. All
|
|
|
2307 attribute names and values are strings encoded in Unicode UTF-8, or
|
|
|
2308 decimal numbers with optional decimal point and fraction. The
|
|
|
2309 characters @samp{-}, @samp{:}, @samp{,}, @samp{=}, and @samp{\} are
|
|
|
2310 syntactically significant to @file{fontconfig}. They may be used in
|
|
|
2311 font name components by the familiar mechanism of backslash escaping.
|
|
|
2312 This simply removes any special meaning from the following character.
|
|
|
2313 It is always safe to use an escape even if it is not needed.
|
|
|
2314
|
|
|
2315 Most string values are case-insensitive, but this is attribute-specific.
|
|
|
2316
|
|
|
2317 The @dfn{font family name} is an arbitrary string, which may contain any
|
|
|
2318 character, including spaces, hyphens, and commas. Don't forget to
|
|
|
2319 escape hyphens, colons, commas, and backslashes!
|
|
|
2320
|
|
|
2321 The @dfn{size} is a decimal number with optional decimal point and
|
|
|
2322 fractional part. It is interpreted as point size.
|
|
|
2323
|
|
|
2324 A @dfn{named attribute field} is a key-value pair separated by an equal
|
|
|
2325 sign. Some attributes have predefined semantics. (These include such
|
|
|
2326 familiar attributes as @samp{slant} and @samp{dpi} -- note that
|
|
|
2327 @file{fontconfig} does not distinguish between vertical and horizontal
|
|
|
2328 resolution!
|
|
|
2329
|
|
|
2330 The basic syntax of a font name is simple and regular. The @emph{font
|
|
|
2331 family name} comes first, followed by a hyphen and the @emph{size},
|
|
|
2332 followed by a list of @emph{named attribute fields}, each introduced by
|
|
|
2333 a colon:
|
|
|
2334
|
|
|
2335 @example
|
|
|
2336 @var{font family name}-@var{size}:@var{key1}=@var{value1}:@var{key2}=@var{value2}...
|
|
|
2337 @end example
|
|
|
2338
|
|
|
2339 There are four extensions to the basic syntax. First, all of the
|
|
|
2340 fields are optional. If size is omitted, the hyphen should be omitted
|
|
|
2341 as well. There should never be a trailing colon. Note that
|
|
|
2342 @file{fontconfig} does @emph{not} interpret an omitted field as
|
|
|
2343 ``default to current.'' @file{fontconfig} does not have access to that
|
|
|
2344 context. Instead, omitted fields are filled in according to a set of
|
|
|
2345 defaults specified in the system @file{fonts.conf} file and in the
|
|
|
2346 user's @file{.fonts.cont} file. The user's configuration gets
|
|
|
2347 precedence, of course.
|
|
|
2348
|
|
|
2349 The second is that the @emph{font family name}, the @emph{size}, and the
|
|
|
2350 @emph{value} component of a @emph{named attribute field} may be a
|
|
|
2351 comma-separated list of values. This is called a @dfn{pattern}. In
|
|
|
2352 queries, @file{fontconfig} tries to match each entry in the list in
|
|
|
2353 order. (I suspect that order of attributes is also significant.
|
|
|
2354 @emph{I.e.}, font family always gets highest precedence, followed by
|
|
|
2355 size, followed by the remaining named attributes. Testing and reports
|
|
|
2356 to the @email{xemacs-beta@@xemacs.org,XEmacs Beta Testers mailing list}
|
|
|
2357 are very welcome!)
|
|
|
2358
|
|
|
2359 The third is the definition of @dfn{constants} to represent numerical
|
|
|
2360 values. For example, both @samp{slant} and @samp{weight} are defined as
|
|
|
2361 integer attributes, but the magnitudes are arbitrary; only the ordering
|
|
|
2362 and relative distances are useful. (``Relative distance'' is used to
|
|
|
2363 implement the concept that although strictly speaking @emph{italic} and
|
|
|
2364 @emph{oblique} are different faces, most users don't know the
|
|
|
2365 difference, and even professional typographers would agree that they are
|
|
|
2366 much closer to each other than either is to @emph{roman}.) So
|
|
|
2367 @emph{constants} like @samp{roman} (0) and @samp{italic} (100) are
|
|
|
2368 defined for @samp{slant}, and @samp{medium} (100) and @samp{bold} (200)
|
|
|
2369 are defined for @samp{weight}.
|
|
|
2370
|
|
|
2371 The fourth is that a @dfn{style} may be defined as an alias for an
|
|
|
2372 instance of a @emph{named attribute field}, that is, specifying both key
|
|
|
2373 and value. The @emph{styles} @samp{bold}, an alias for
|
|
|
2374 @samp{weight=200}, and @samp{italic}, an alias for @samp{slant=100}, are
|
|
|
2375 commonly used.
|
|
|
2376
|
|
|
2377 Styles and constants can be defined by the application. XEmacs
|
|
|
2378 currently defines none, but suggestions are welcome if some convenient
|
|
|
2379 alias is lacking from @file{fontconfig}. Note that we will not provide
|
|
|
2380 additional aliases where standard ones exist, @emph{e.g.}, @samp{heavy}
|
|
|
2381 as an additional alias for @samp{bold} would almost certainly be
|
|
|
2382 rejected. These cause more confusion than they are worth, and would
|
|
|
2383 decrease portability of user specifications to other applications.
|
|
|
2384
|
|
|
2385 (Attributes can also be defined, but they must be implemented by the
|
|
|
2386 fonts to be useful. Until XEmacs provides its own fonts with
|
|
|
2387 non-standardized attributes, this is not useful.)
|
|
|
2388
|
|
|
2389 Here are some examples of font names and query patterns:
|
|
|
2390
|
|
|
2391 @example
|
|
|
2392 Times-12 12-point Times Roman
|
|
|
2393 Times-12:bold 12-point Times Bold
|
|
|
2394 Courier:italic Courier Italic in the default size
|
|
|
2395 Monospace:matrix=1 .1 0 1 The user's preferred monospace font
|
|
|
2396 with artificial obliquing
|
|
|
2397 Mikachan\-PB-16 16-point Mikachan-PB
|
|
|
2398 LucidaTypewriter,Courier-9 9-point LucidaTypewriter if available,
|
|
|
2399 otherwise 9-point Courier
|
|
|
2400 @end example
|
|
|
2401
|
|
|
2402 Note how @emph{styles} are used in the second and third examples, how
|
|
|
2403 @samp{matrix} has a complex value containing spaces, and the
|
|
|
2404 escaped hyphen in the font family name @samp{Mikachan\-PB}.
|
|
|
2405
|
|
|
2406 @c #### FIXME here and also in fontconfig.texi (in general-docs package).
|
|
|
2407 Here is a (somewhat outdated) list of current standard named attributes:
|
|
|
2408
|
|
|
2409 @example
|
|
|
2410 Property CPP symbol Type Description
|
|
|
2411
|
|
|
2412 family FC_FAMILY String Font family name
|
|
|
2413 style FC_STYLE String Font style. Overrides weight and slant
|
|
|
2414 slant FC_SLANT Int Italic, oblique or roman
|
|
|
2415 weight FC_WEIGHT Int Light, medium, demibold, bold or black
|
|
|
2416 size FC_SIZE Double Point size
|
|
|
2417 aspect FC_ASPECT Double Stretch glyphs horizontally, then hint
|
|
|
2418 pixelsize FC_PIXEL_SIZE Double Pixel size
|
|
|
2419 spacing FC_SPACING Int Proportional, monospace or charcell
|
|
|
2420 foundry FC_FOUNDRY String Font foundry name
|
|
|
2421 antialias FC_ANTIALIAS Bool Should glyphs be antialiased?
|
|
|
2422 hinting FC_HINTING Bool Should the rasterizer use hinting?
|
|
|
2423 verticallayout FC_VERTICAL_LAYOUT Bool Use vertical layout
|
|
|
2424 autohint FC_AUTOHINT Bool Use autohinter instead of normal hinter
|
|
|
2425 globaladvance FC_GLOBAL_ADVANCE Bool Use font global advance data
|
|
|
2426 file FC_FILE String The filename holding the font
|
|
|
2427 index FC_INDEX Int The index of the font within the file
|
|
|
2428 ftface FC_FT_FACE FT_Face Use the specified FreeType face object
|
|
|
2429 rasterizer FC_RASTERIZER String Which rasterizer is in use
|
|
|
2430 outline FC_OUTLINE Bool Whether the glyphs are outlines
|
|
|
2431 scalable FC_SCALABLE Bool Whether glyphs can be scaled
|
|
|
2432 scale FC_SCALE Double Point->pixel conversion scale factor
|
|
|
2433 dpi FC_DPI Double Target dots per inch
|
|
|
2434 rgba FC_RGBA Int unknown, rgb, bgr, vrgb, vbgr, none
|
|
|
2435 - subpixel geometry
|
|
|
2436 source FC_SOURCE String X11, freetype
|
|
|
2437 minspace FC_MINSPACE Bool Eliminate leading from line spacing
|
|
|
2438 charset FC_CHARSET CharSet Unicode chars encoded by the font
|
|
|
2439 lang FC_LANG String List of RFC-3066-style languages
|
|
|
2440 this font supports
|
|
|
2441 fontversion FC_FONTVERSION Int From 'head' table
|
|
|
2442 @end example
|
|
|
2443
|
|
|
2444 Here is a list of current standard constants:
|
|
|
2445
|
|
|
2446 @example
|
|
|
2447 Constant Property CPP symbol
|
|
|
2448
|
|
|
2449 light weight FC_WEIGHT_LIGHT
|
|
|
2450 medium weight FC_WEIGHT_MEDIUM
|
|
|
2451 demibold weight FC_WEIGHT_DEMIBOLD
|
|
|
2452 bold weight FC_WEIGHT_BOLD
|
|
|
2453 black weight FC_WEIGHT_BLACK
|
|
|
2454 roman slant FC_SLANT_ROMAN
|
|
|
2455 italic slant FC_SLANT_ITALIC
|
|
|
2456 oblique slant FC_SLANT_OBLIQUE
|
|
|
2457 proportional spacing FC_PROPORTIONAL
|
|
|
2458 mono spacing FC_MONO
|
|
|
2459 charcell spacing FC_CHARCELL
|
|
|
2460 unknown rgba FC_RGBA_UNKNOWN
|
|
|
2461 rgb rgba FC_RGBA_RGB
|
|
|
2462 bgr rgba FC_RGBA_BGR
|
|
|
2463 vrgb rgba FC_RGBA_VRGB
|
|
|
2464 vbgr rgba FC_RGBA_VBGR
|
|
|
2465 none rgba FC_RGBA_NONE
|
|
|
2466 @end example
|
|
|
2467
|
|
|
2468 Note that this is the @file{fontconfig} API list; you can expect that
|
|
|
2469 XEmacs will define corresponding keywords by substituting @samp{:} for
|
|
|
2470 the leading @samp{FC_}, @samp{-} for @samp{_}, removing the key of the
|
|
|
2471 attribute if present, and lowercasing the name. Thus
|
|
|
2472 @samp{FC_WEIGHT_BOLD} becomes @samp{:bold}.
|
|
|
2473 @kbd{M-x apropos RET fc-.*-mapping} will give a list of variables each
|
|
|
2474 of which lists such keywords and their meanings.
|
|
|
2475
|
|
|
2476 @subheading Font menus
|
|
|
2477
|
|
|
2478 The @samp{Options->Font} and @samp{Options->Font Sizes} menus are
|
|
|
2479 broken, by design, not just by @file{Xft}. The problem is that many
|
|
|
2480 fonts are unavailable because they don't match the current size---which
|
|
|
2481 is very strange, since @file{Xft} fonts are of course scalable. But the
|
|
|
2482 whole idea of requiring that the font match the size is strange. And
|
|
|
2483 the @samp{Options->Font Weights} menu is just disabled, and has been for
|
|
|
2484 eons.
|
|
|
2485
|
|
|
2486 @subheading X resources
|
|
|
2487
|
|
|
2488 Currently there are @emph{four} treatments of font resources. There are
|
|
|
2489 the @samp{XEmacs.@var{face}.attributeFont} resources used to set a
|
|
|
2490 single global font specification. In the widgets, some (still) have a
|
|
|
2491 @samp{font} resource using the automatic @file{Xt} resource conversion
|
|
|
2492 to X's @samp{FontStruct}, some have separate @samp{font} and @samp{xftFont}
|
|
|
2493 resources with the former automatically converted to @samp{FontStruct}
|
|
|
2494 by @file{Xt} and the latter left as a string, to be converted to a
|
|
|
2495 fontconfig @samp{FcPattern} by
|
|
|
2496 @samp{FcParseName} later, and some have a single @samp{font} resource
|
|
|
2497 which is converted to @samp{FontStruct} by @file{Xt} or the latter left
|
|
|
2498 as a string, depending on whether @file{Xft} was enabled by
|
|
|
2499 @samp{configure} or not.
|
|
|
2500
|
|
|
2501 Eventually these should be converted to use the face
|
|
|
2502 approach, perhaps with some way to set specifications for individual
|
|
|
2503 widgets, frames, or buffers. This will require some careful design work
|
|
|
2504 to incorporate face support in the widgets. Stephen's current thinking
|
|
|
2505 is that XEmacs should just accept any
|
|
|
2506 or all of @samp{font}, @samp{fontSet}, and @samp{fontList} resources,
|
|
|
2507 treat them all as lists of font names, either @samp{XLFD}- or
|
|
|
2508 @file{fontconfig}-style, parse them ourselves (ie, not use the @file{Xt}
|
|
|
2509 resource manager), and add them to font specifiers as appropriate. But
|
|
|
2510 this will require a bit of thought to obey POLA vis-a-vis usual @file{Xt}
|
|
|
2511 conventions.
|
|
|
2512
|
|
|
2513 @subheading Specifiers, charsets, and languages
|
|
|
2514
|
|
|
2515 Traditionally Mule uses a rather rigid and low-level abstraction, the
|
|
|
2516 @emph{charset}, to characterize font repertoires. Unfortunately,
|
|
|
2517 support for a given charset is generally neither necessary nor
|
|
|
2518 sufficient to support a language. Worse, in XEmacs's current
|
|
|
2519 implementation Xft doesn't help much. Instead you need to add the fonts
|
|
|
2520 for different charsets to the font specifier in the right order.
|
|
|
2521
|
|
|
2522 There currently is no explicit way to specify that a particular font be
|
|
|
2523 used only for a given language. However, since many fonts support only
|
|
|
2524 a limited repertoire such as ISO 8859/1, you can use the precedence of
|
|
|
2525 specifications for a given specifier locale to get something of this
|
|
|
2526 effect for non-Latin character sets. This will normally work rather
|
|
|
2527 poorly for multiple Latin character sets, however, because the
|
|
|
2528 repertoires tend to have large amounts of overlap. Support for
|
|
|
2529 specifying font by @emph{language} as well as by character set is
|
|
|
2530 planned.
|
|
|
2531
|
|
|
2532 Because fonts supporting other languages tend to support English as
|
|
|
2533 well, if you want to use one font for English and another for the other
|
|
|
2534 language, you must use the @code{append} method when adding font
|
|
|
2535 specifications for the @emph{other} language.
|
|
|
2536
|
|
|
2537 However, this simple method leaves you with a problem if you want to
|
|
|
2538 change the other language's font: you have to remove the existing
|
|
|
2539 specification so it won't shadow the new one when you append.
|
|
|
2540
|
|
|
2541 In order to provide a convenient way to change ``other-language fonts'',
|
|
|
2542 I use @code{remove-tag-set-append} and @code{define-specifier-tag} like
|
|
|
2543 this:
|
|
|
2544
|
|
|
2545 @example
|
|
|
2546 (define-specifier-tag 'lang-ja)
|
|
|
2547 ;; No, I don't try to do real work with this font! But it makes it
|
|
|
2548 ;; obvious that I got the requested font. :-)
|
|
|
2549 (set-face-font 'default "AirCut-14")
|
|
|
2550 (set-face-font 'default "Kochi Mincho-14" nil '(lang-ja) 'append)
|
|
|
2551 ;; Oops, too sober. Try something to match AirCut.
|
|
|
2552 (set-face-font 'default "Mikachan-14"
|
|
|
2553 nil '(lang-ja) 'remove-tag-set-append)
|
|
|
2554 @end example
|
|
|
2555
|
|
|
2556 The only way to configure widget fonts at the present time is to use X
|
|
|
2557 resources (or hack the source and rebuild). Currently supported widgets
|
|
|
2558 are
|
|
|
2559 @itemize
|
|
|
2560 @item
|
|
|
2561 menubars
|
|
|
2562 @item
|
|
|
2563 tab controls
|
|
|
2564 @end itemize
|
|
|
2565
|
|
|
2566 Here are the resources I use. @strong{Warning:} @emph{This interface
|
|
|
2567 will change. Pay attention to beta announcements, and complain loudly
|
|
|
2568 if changes aren't documented here!} The tab control and menubar have
|
|
|
2569 separate Font and XftFont resources, and use the X resource manager to
|
|
|
2570 instantiate a FontStruct from the Font resource. There is no converter
|
|
|
2571 facility for XftFont yet, and creating one that handles both FontStruct
|
|
|
2572 and XftFont depending on XEmacs's configuration and the font name seems
|
|
|
2573 error-prone at best. Probably we will use a simple string
|
|
|
2574 representation for this resource, and convert to a face in XEmacs rather
|
|
|
2575 than a font in Xt/Xft.
|
|
|
2576 @example
|
|
|
2577 XEmacs*Tabs.xftFont: Bitstream Vera Sans-16
|
|
|
2578 XEmacs*menubar*xftFont: Bitstream Vera Sans-16
|
|
|
2579 XEmacs.modeline.attributeFont: Bitstream Charter-16
|
|
|
2580 XEmacs.default.attributeFont: Bitstream Vera Sans Mono-16
|
|
|
2581 @end example
|
|
|
2582 I highly recommend use of a proportional font in the modeline because it
|
|
|
2583 allows a lot more text to fit there.
|
|
|
2584 @c Previously the font sizes were quite varied, and there was a comment
|
|
|
2585 @c that this weirdness gave good balance. This isn't true on my main
|
|
|
2586 @c platform, Mac OS X, and needs to be rechecked on Linux, where it was
|
|
|
2587 @c observed.
|
|
|
2588
|
|
|
2589 @subheading Known Problems
|
|
|
2590
|
|
|
2591 @table @code
|
|
|
2592 @item Options->Font
|
|
|
2593 @itemx Options->Font Size
|
|
|
2594 These menus don't work. All fonts are greyed out. All sizes are
|
|
|
2595 available, but many (most?) faces don't change size, in particular,
|
|
|
2596 @samp{default} does not.
|
|
|
2597
|
|
|
2598 @item Antialiased text bleeding outside of reported extent
|
|
|
2599 This is most obvious with the underscore character in that
|
|
|
2600 font, and with cursors. The bottom of the underscore is antialiased,
|
|
|
2601 and insertions or deletions in the same line before the underscore leave
|
|
|
2602 a series of "phantom" underlines.
|
|
|
2603
|
|
|
2604 I think this is probably an Xft bug, but I'm not sure.
|
|
|
2605 @end table
|
|
|
2606
|
|
|
2607 @subheading Variables Used with Xft and Fontconfig
|
|
|
2608
|
|
|
2609 @defvar xft-debug-level
|
|
|
2610
|
|
|
2611 Level of debugging messages to issue to stderr for @var{Xft}.
|
|
|
2612 A nonnegative integer. Set to 0 to suppress all warnings.
|
|
|
2613 Default is 1 to ensure a minimum of debugging output at initialization.
|
|
|
2614 Higher levels give more information.
|
|
|
2615 @end defvar
|
|
|
2616
|
|
|
2617 @defvar xft-version
|
|
|
2618
|
|
|
2619 The major version number of the Xft library compiled with.
|
|
|
2620 @end defvar
|
|
|
2621
|
|
|
2622 @defvar xft-xlfd-font-regexp
|
|
|
2623
|
|
|
2624 Regular expression matching XLFD font names.
|
|
|
2625 @end defvar
|
|
|
2626
|
|
|
2627
|
|
442
|
2628 @node Frame Components
|
|
|
2629 @section Frame Components
|
|
|
2630
|
|
|
2631 You can control the presence and position of most frame components, such
|
|
|
2632 as the menubar, toolbars, and gutters.
|
|
|
2633
|
|
|
2634 This section is not written yet. Try the Lisp Reference Manual:
|
|
|
2635 @ref{Menubar,,,lispref,}, @ref{Toolbar Intro,,,lispref,}, and
|
|
|
2636 @ref{Gutter Intro,,,lispref,}.
|
|
|
2637
|
|
428
|
2638 @node X Resources
|
|
|
2639 @section X Resources
|
|
|
2640 @cindex X resources
|
|
|
2641 @findex x-create-frame
|
|
|
2642
|
|
2681
|
2643 Historically, XEmacs used the X resource application class @samp{Emacs}
|
|
2736
|
2644 for its resources. Unfortunately, GNU Emacs's usage of resources has
|
|
|
2645 evolved differently from XEmacs's, and especially in the case of fonts
|
|
|
2646 semantics are not compatible between the two Emacsen. Thus, sharing of
|
|
|
2647 the application class can easily lead to trouble.
|
|
428
|
2648
|
|
2681
|
2649 XEmacs now uses the X resource application class @samp{XEmacs}.
|
|
2736
|
2650 Versions since 21.5.21 do this unconditionally. To attempt to maintain
|
|
|
2651 some backward compatibility, previous versions checked the X resource
|
|
|
2652 database for resources starting in @samp{XEmacs}, and if none were
|
|
|
2653 found, @samp{Emacs} was used. This behavior is likely to be obsoleted,
|
|
|
2654 so you should move your X resources to using the @samp{XEmacs} class.
|
|
|
2655 In the short term, to stay with the old behavior, start XEmacs with the
|
|
|
2656 environment variable @b{USE_EMACS_AS_DEFAULT_APPLICATION_CLASS} set to
|
|
|
2657 some non-empty value; this will restore the pre-21.5.21 behavior.
|
|
|
2658 @c #### is this documented in the Lispref?
|
|
|
2659 Lisp programs can examine the variable @code{x-emacs-application-class}
|
|
|
2660 to determine which is being used in the running application.
|
|
2681
|
2661
|
|
|
2662 The examples in this section assume the application class is
|
|
2736
|
2663 @samp{XEmacs}.
|
|
|
2664
|
|
|
2665 Most of XEmacs's resources are set per-frame. Each XEmacs frame can
|
|
2681
|
2666 have its own name or the same name as another, depending on the name
|
|
|
2667 passed to the @code{make-frame} function. Up until 21.5.21, the default
|
|
|
2668 frame name was @samp{emacs}; since then, it has been @samp{XEmacs}, but
|
|
|
2669 in the short term the old default can be restored by the
|
|
|
2670 @b{USE_EMACS_AS_DEFAULT_APPLICATION_CLASS} environment variable
|
|
2736
|
2671 mentioned above.
|
|
|
2672 @c #### Cheesy. Variable should be documented here.
|
|
|
2673 See the docstring for the Lisp variable `default-frame-name'.
|
|
428
|
2674
|
|
|
2675 You can specify resources for all frames with the syntax:
|
|
|
2676
|
|
|
2677 @example
|
|
2681
|
2678 XEmacs*parameter: value
|
|
428
|
2679 @end example
|
|
|
2680 @noindent
|
|
|
2681
|
|
|
2682 or
|
|
|
2683
|
|
|
2684 @example
|
|
2681
|
2685 XEmacs*EmacsFrame.parameter:value
|
|
428
|
2686 @end example
|
|
|
2687 @noindent
|
|
|
2688
|
|
|
2689 You can specify resources for a particular frame with the syntax:
|
|
|
2690
|
|
|
2691 @example
|
|
2681
|
2692 XEmacs*FRAME-NAME.parameter: value
|
|
428
|
2693 @end example
|
|
|
2694 @noindent
|
|
|
2695
|
|
|
2696 @menu
|
|
|
2697 * Geometry Resources:: Controlling the size and position of frames.
|
|
440
|
2698 * Iconic Resources:: Controlling whether frames come up iconic.
|
|
|
2699 * Resource List:: List of resources settable on a frame or device.
|
|
|
2700 * Face Resources:: Controlling faces using resources.
|
|
|
2701 * Widgets:: The widget hierarchy for XEmacs.
|
|
|
2702 * Menubar Resources:: Specifying resources for the menubar.
|
|
428
|
2703 @end menu
|
|
|
2704
|
|
|
2705 @node Geometry Resources
|
|
|
2706 @subsection Geometry Resources
|
|
|
2707
|
|
2681
|
2708 To make the default size of all XEmacs frames be 80 columns by 55 lines,
|
|
428
|
2709 do this:
|
|
|
2710
|
|
|
2711 @example
|
|
2681
|
2712 XEmacs*EmacsFrame.geometry: 80x55
|
|
428
|
2713 @end example
|
|
|
2714 @noindent
|
|
|
2715
|
|
|
2716 To set the geometry of a particular frame named @samp{fred}, do this:
|
|
|
2717
|
|
|
2718 @example
|
|
2681
|
2719 XEmacs*fred.geometry: 80x55
|
|
428
|
2720 @end example
|
|
|
2721 @noindent
|
|
|
2722
|
|
|
2723 Important! Do not use the following syntax:
|
|
|
2724
|
|
|
2725 @example
|
|
2681
|
2726 XEmacs*geometry: 80x55
|
|
428
|
2727 @end example
|
|
|
2728 @noindent
|
|
|
2729
|
|
|
2730 You should never use @code{*geometry} with any X application. It does
|
|
2681
|
2731 not say "make the geometry of XEmacs be 80 columns by 55 lines." It
|
|
|
2732 really says, "make XEmacs and all subwindows thereof be 80x55 in whatever
|
|
428
|
2733 units they care to measure in." In particular, that is both telling the
|
|
2681
|
2734 XEmacs text pane to be 80x55 in characters, and telling the menubar pane
|
|
428
|
2735 to be 80x55 pixels, which is surely not what you want.
|
|
|
2736
|
|
|
2737 As a special case, this geometry specification also works (and sets the
|
|
2681
|
2738 default size of all XEmacs frames to 80 columns by 55 lines):
|
|
428
|
2739
|
|
|
2740 @example
|
|
2681
|
2741 XEmacs.geometry: 80x55
|
|
428
|
2742 @end example
|
|
|
2743 @noindent
|
|
|
2744
|
|
|
2745 since that is the syntax used with most other applications (since most
|
|
2681
|
2746 other applications have only one top-level window, unlike XEmacs). In
|
|
428
|
2747 general, however, the top-level shell (the unmapped ApplicationShell
|
|
2681
|
2748 widget named @samp{XEmacs} that is the parent of the shell widgets that
|
|
428
|
2749 actually manage the individual frames) does not have any interesting
|
|
|
2750 resources on it, and you should set the resources on the frames instead.
|
|
|
2751
|
|
|
2752 The @code{-geometry} command-line argument sets only the geometry of the
|
|
2681
|
2753 initial frame created by XEmacs.
|
|
428
|
2754
|
|
|
2755 A more complete explanation of geometry-handling is
|
|
|
2756
|
|
|
2757 @itemize @bullet
|
|
|
2758 @item
|
|
2681
|
2759 The @code{-geometry} command-line option sets the @code{XEmacs.geometry}
|
|
428
|
2760 resource, that is, the geometry of the ApplicationShell.
|
|
|
2761
|
|
|
2762 @item
|
|
|
2763 For the first frame created, the size of the frame is taken from the
|
|
|
2764 ApplicationShell if it is specified, otherwise from the geometry of the
|
|
|
2765 frame.
|
|
|
2766
|
|
|
2767 @item
|
|
|
2768 For subsequent frames, the order is reversed: First the frame, and then
|
|
|
2769 the ApplicationShell.
|
|
|
2770
|
|
|
2771 @item
|
|
|
2772 For the first frame created, the position of the frame is taken from the
|
|
2681
|
2773 ApplicationShell (@code{XEmacs.geometry}) if it is specified, otherwise
|
|
428
|
2774 from the geometry of the frame.
|
|
|
2775
|
|
|
2776 @item
|
|
1137
|
2777 For subsequent frames, the position is taken only from the frame, and
|
|
428
|
2778 never from the ApplicationShell.
|
|
|
2779 @end itemize
|
|
|
2780
|
|
|
2781 This is rather complicated, but it does seem to provide the most
|
|
|
2782 intuitive behavior with respect to the default sizes and positions of
|
|
|
2783 frames created in various ways.
|
|
|
2784
|
|
|
2785 @node Iconic Resources
|
|
|
2786 @subsection Iconic Resources
|
|
|
2787
|
|
|
2788 Analogous to @code{-geometry}, the @code{-iconic} command-line option
|
|
2681
|
2789 sets the iconic flag of the ApplicationShell (@code{XEmacs.iconic}) and
|
|
428
|
2790 always applies to the first frame created regardless of its name.
|
|
|
2791 However, it is possible to set the iconic flag on particular frames (by
|
|
2681
|
2792 name) by using the @code{XEmacs*FRAME-NAME.iconic} resource.
|
|
428
|
2793
|
|
|
2794 @node Resource List
|
|
|
2795 @subsection Resource List
|
|
|
2796
|
|
2681
|
2797 XEmacs frames accept the following resources:
|
|
428
|
2798
|
|
|
2799 @table @asis
|
|
|
2800 @item @code{geometry} (class @code{Geometry}): string
|
|
|
2801 Initial geometry for the frame. @xref{Geometry Resources}, for a
|
|
|
2802 complete discussion of how this works.
|
|
|
2803
|
|
|
2804 @item @code{iconic} (class @code{Iconic}): boolean
|
|
|
2805 Whether this frame should appear in the iconified state.
|
|
|
2806
|
|
|
2807 @item @code{internalBorderWidth} (class @code{InternalBorderWidth}): int
|
|
1137
|
2808 How many blank pixels to leave between the text and the edge of the
|
|
428
|
2809 window.
|
|
|
2810
|
|
|
2811 @item @code{interline} (class @code{Interline}): int
|
|
|
2812 How many pixels to leave between each line (may not be implemented).
|
|
|
2813
|
|
|
2814 @item @code{menubar} (class @code{Menubar}): boolean
|
|
|
2815 Whether newly-created frames should initially have a menubar. Set to
|
|
|
2816 true by default.
|
|
|
2817
|
|
|
2818 @item @code{initiallyUnmapped} (class @code{InitiallyUnmapped}): boolean
|
|
|
2819 Whether XEmacs should leave the initial frame unmapped when it starts
|
|
|
2820 up. This is useful if you are starting XEmacs as a server (e.g. in
|
|
|
2821 conjunction with gnuserv or the external client widget). You can also
|
|
|
2822 control this with the @code{-unmapped} command-line option.
|
|
|
2823
|
|
|
2824 @item @code{barCursor} (class @code{BarColor}): boolean
|
|
|
2825 Whether the cursor should be displayed as a bar, or the traditional box.
|
|
|
2826
|
|
|
2827 @item @code{cursorColor} (class @code{CursorColor}): color-name
|
|
|
2828 The color of the text cursor.
|
|
|
2829
|
|
|
2830 @item @code{scrollBarWidth} (class @code{ScrollBarWidth}): integer
|
|
|
2831 How wide the vertical scrollbars should be, in pixels; 0 means no
|
|
|
2832 vertical scrollbars. You can also use a resource specification of the
|
|
|
2833 form @code{*scrollbar.width}, or the usual toolkit scrollbar resources:
|
|
|
2834 @code{*XmScrollBar.width} (Motif), @code{*XlwScrollBar.width} (Lucid),
|
|
|
2835 or @code{*Scrollbar.thickness} (Athena). We don't recommend that you
|
|
|
2836 use the toolkit resources, though, because they're dependent on how
|
|
|
2837 exactly your particular build of XEmacs was configured.
|
|
|
2838
|
|
|
2839 @item @code{scrollBarHeight} (class @code{ScrollBarHeight}): integer
|
|
|
2840 How high the horizontal scrollbars should be, in pixels; 0 means no
|
|
|
2841 horizontal scrollbars. You can also use a resource specification of the
|
|
|
2842 form @code{*scrollbar.height}, or the usual toolkit scrollbar resources:
|
|
|
2843 @code{*XmScrollBar.height} (Motif), @code{*XlwScrollBar.height} (Lucid),
|
|
|
2844 or @code{*Scrollbar.thickness} (Athena). We don't recommend that you use
|
|
|
2845 the toolkit resources, though, because they're dependent on how exactly
|
|
|
2846 your particular build of XEmacs was configured.
|
|
|
2847
|
|
|
2848 @item @code{scrollBarPlacement} (class @code{ScrollBarPlacement}): string
|
|
|
2849 Where the horizontal and vertical scrollbars should be positioned. This
|
|
|
2850 should be one of the four strings @samp{BOTTOM_LEFT},
|
|
|
2851 @samp{BOTTOM_RIGHT}, @samp{TOP_LEFT}, and @samp{TOP_RIGHT}. Default is
|
|
|
2852 @samp{BOTTOM_RIGHT} for the Motif and Lucid scrollbars and
|
|
|
2853 @samp{BOTTOM_LEFT} for the Athena scrollbars.
|
|
|
2854
|
|
|
2855 @item @code{topToolBarHeight} (class @code{TopToolBarHeight}): integer
|
|
|
2856 @itemx @code{bottomToolBarHeight} (class @code{BottomToolBarHeight}): integer
|
|
|
2857 @itemx @code{leftToolBarWidth} (class @code{LeftToolBarWidth}): integer
|
|
|
2858 @itemx @code{rightToolBarWidth} (class @code{RightToolBarWidth}): integer
|
|
|
2859 Height and width of the four possible toolbars.
|
|
|
2860
|
|
|
2861 @item @code{topToolBarShadowColor} (class @code{TopToolBarShadowColor}): color-name
|
|
|
2862 @itemx @code{bottomToolBarShadowColor} (class @code{BottomToolBarShadowColor}): color-name
|
|
|
2863 Color of the top and bottom shadows for the toolbars. NOTE: These resources
|
|
|
2864 do @emph{not} have anything to do with the top and bottom toolbars (i.e. the
|
|
|
2865 toolbars at the top and bottom of the frame)! Rather, they affect the top
|
|
|
2866 and bottom shadows around the edges of all four kinds of toolbars.
|
|
|
2867
|
|
|
2868 @item @code{topToolBarShadowPixmap} (class @code{TopToolBarShadowPixmap}): pixmap-name
|
|
|
2869 @itemx @code{bottomToolBarShadowPixmap} (class @code{BottomToolBarShadowPixmap}): pixmap-name
|
|
|
2870 Pixmap of the top and bottom shadows for the toolbars. If set, these
|
|
|
2871 resources override the corresponding color resources. NOTE: These
|
|
|
2872 resources do @emph{not} have anything to do with the top and bottom
|
|
|
2873 toolbars (i.e. the toolbars at the top and bottom of the frame)!
|
|
|
2874 Rather, they affect the top and bottom shadows around the edges of all
|
|
|
2875 four kinds of toolbars.
|
|
|
2876
|
|
|
2877 @item @code{toolBarShadowThickness} (class @code{ToolBarShadowThickness}): integer
|
|
|
2878 Thickness of the shadows around the toolbars, in pixels.
|
|
|
2879
|
|
|
2880 @item @code{visualBell} (class @code{VisualBell}): boolean
|
|
|
2881 Whether XEmacs should flash the screen rather than making an audible beep.
|
|
|
2882
|
|
|
2883 @item @code{bellVolume} (class @code{BellVolume}): integer
|
|
|
2884 Volume of the audible beep.
|
|
|
2885
|
|
|
2886 @item @code{useBackingStore} (class @code{UseBackingStore}): boolean
|
|
|
2887 Whether XEmacs should set the backing-store attribute of the X windows
|
|
|
2888 it creates. This increases the memory usage of the X server but decreases
|
|
|
2889 the amount of X traffic necessary to update the screen, and is useful
|
|
|
2890 when the connection to the X server goes over a low-bandwidth line
|
|
|
2891 such as a modem connection.
|
|
|
2892 @end table
|
|
|
2893
|
|
2681
|
2894 XEmacs devices accept the following resources:
|
|
428
|
2895
|
|
|
2896 @table @asis
|
|
|
2897 @item @code{textPointer} (class @code{Cursor}): cursor-name
|
|
|
2898 The cursor to use when the mouse is over text. This resource is used to
|
|
|
2899 initialize the variable @code{x-pointer-shape}.
|
|
|
2900
|
|
|
2901 @item @code{selectionPointer} (class @code{Cursor}): cursor-name
|
|
|
2902 The cursor to use when the mouse is over a selectable text region (an
|
|
|
2903 extent with the @samp{highlight} property; for example, an Info
|
|
|
2904 cross-reference). This resource is used to initialize the variable
|
|
|
2905 @code{x-selection-pointer-shape}.
|
|
|
2906
|
|
|
2907 @item @code{spacePointer} (class @code{Cursor}): cursor-name
|
|
|
2908 The cursor to use when the mouse is over a blank space in a buffer (that
|
|
|
2909 is, after the end of a line or after the end-of-file). This resource is
|
|
|
2910 used to initialize the variable @code{x-nontext-pointer-shape}.
|
|
|
2911
|
|
|
2912 @item @code{modeLinePointer} (class @code{Cursor}): cursor-name
|
|
|
2913 The cursor to use when the mouse is over a modeline. This resource is
|
|
|
2914 used to initialize the variable @code{x-mode-pointer-shape}.
|
|
|
2915
|
|
|
2916 @item @code{gcPointer} (class @code{Cursor}): cursor-name
|
|
|
2917 The cursor to display when a garbage-collection is in progress. This
|
|
|
2918 resource is used to initialize the variable @code{x-gc-pointer-shape}.
|
|
|
2919
|
|
|
2920 @item @code{scrollbarPointer} (class @code{Cursor}): cursor-name
|
|
|
2921 The cursor to use when the mouse is over the scrollbar. This resource
|
|
|
2922 is used to initialize the variable @code{x-scrollbar-pointer-shape}.
|
|
|
2923
|
|
|
2924 @item @code{pointerColor} (class @code{Foreground}): color-name
|
|
|
2925 @itemx @code{pointerBackground} (class @code{Background}): color-name
|
|
|
2926 The foreground and background colors of the mouse cursor. These
|
|
|
2927 resources are used to initialize the variables
|
|
|
2928 @code{x-pointer-foreground-color} and @code{x-pointer-background-color}.
|
|
|
2929 @end table
|
|
|
2930
|
|
|
2931 @node Face Resources
|
|
|
2932 @subsection Face Resources
|
|
|
2933
|
|
|
2934 The attributes of faces are also per-frame. They can be specified as:
|
|
|
2935
|
|
|
2936 @example
|
|
2681
|
2937 XEmacs.FACE_NAME.parameter: value
|
|
428
|
2938 @end example
|
|
|
2939 @noindent
|
|
|
2940
|
|
|
2941 or
|
|
|
2942
|
|
|
2943 @example
|
|
2681
|
2944 XEmacs*FRAME_NAME.FACE_NAME.parameter: value
|
|
428
|
2945 @end example
|
|
|
2946 @noindent
|
|
|
2947
|
|
|
2948 Faces accept the following resources:
|
|
|
2949
|
|
|
2950 @table @asis
|
|
|
2951 @item @code{attributeFont} (class @code{AttributeFont}): font-name
|
|
|
2952 The font of this face.
|
|
|
2953
|
|
|
2954 @item @code{attributeForeground} (class @code{AttributeForeground}): color-name
|
|
|
2955 @itemx @code{attributeBackground} (class @code{AttributeBackground}): color-name
|
|
|
2956 The foreground and background colors of this face.
|
|
|
2957
|
|
|
2958 @item @code{attributeBackgroundPixmap} (class @code{AttributeBackgroundPixmap}): file-name
|
|
2681
|
2959 The name of an @sc{xbm} file (or @sc{xpm} file, if your version of XEmacs
|
|
428
|
2960 supports @sc{xpm}), to use as a background stipple.
|
|
|
2961
|
|
|
2962 @item @code{attributeUnderline} (class @code{AttributeUnderline}): boolean
|
|
|
2963 Whether text in this face should be underlined.
|
|
|
2964 @end table
|
|
|
2965
|
|
|
2966 All text is displayed in some face, defaulting to the face named
|
|
|
2967 @code{default}. To set the font of normal text, use
|
|
2681
|
2968 @code{XEmacs*default.attributeFont}. To set it in the frame named
|
|
|
2969 @code{fred}, use @code{XEmacs*fred.default.attributeFont}.
|
|
428
|
2970
|
|
|
2971 These are the names of the predefined faces:
|
|
|
2972
|
|
|
2973 @table @code
|
|
|
2974 @item default
|
|
|
2975 Everything inherits from this.
|
|
|
2976
|
|
|
2977 @item bold
|
|
2681
|
2978 If this is not specified in the resource database, XEmacs tries to find a
|
|
428
|
2979 bold version of the font of the default face.
|
|
|
2980
|
|
|
2981 @item italic
|
|
2681
|
2982 If this is not specified in the resource database, XEmacs tries to find
|
|
428
|
2983 an italic version of the font of the default face.
|
|
|
2984
|
|
|
2985 @item bold-italic
|
|
2681
|
2986 If this is not specified in the resource database, XEmacs tries to find a
|
|
428
|
2987 bold-italic version of the font of the default face.
|
|
|
2988
|
|
|
2989 @item modeline
|
|
|
2990 This is the face that the modeline is displayed in. If not specified in
|
|
|
2991 the resource database, it is determined from the default face by
|
|
|
2992 reversing the foreground and background colors.
|
|
|
2993
|
|
|
2994 @item highlight
|
|
|
2995 This is the face that highlighted extents (for example, Info
|
|
|
2996 cross-references and possible completions, when the mouse passes over
|
|
|
2997 them) are displayed in.
|
|
|
2998
|
|
|
2999 @item left-margin
|
|
|
3000 @itemx right-margin
|
|
|
3001 These are the faces that the left and right annotation margins are
|
|
|
3002 displayed in.
|
|
|
3003
|
|
|
3004 @item zmacs-region
|
|
|
3005 This is the face that mouse selections are displayed in.
|
|
1137
|
3006
|
|
428
|
3007 @item isearch
|
|
|
3008 This is the face that the matched text being searched for is displayed
|
|
|
3009 in.
|
|
|
3010
|
|
|
3011 @item info-node
|
|
|
3012 This is the face of info menu items. If unspecified, it is copied from
|
|
|
3013 @code{bold-italic}.
|
|
|
3014
|
|
|
3015 @item info-xref
|
|
|
3016 This is the face of info cross-references. If unspecified, it is copied
|
|
|
3017 from @code{bold}. (Note that, when the mouse passes over a
|
|
|
3018 cross-reference, the cross-reference's face is determined from a
|
|
|
3019 combination of the @code{info-xref} and @code{highlight} faces.)
|
|
|
3020 @end table
|
|
|
3021
|
|
|
3022 Other packages might define their own faces; to see a list of all faces,
|
|
|
3023 use any of the interactive face-manipulation commands such as
|
|
|
3024 @code{set-face-font} and type @samp{?} when you are prompted for the
|
|
|
3025 name of a face.
|
|
|
3026
|
|
|
3027 If the @code{bold}, @code{italic}, and @code{bold-italic} faces are not
|
|
|
3028 specified in the resource database, then XEmacs attempts to derive them
|
|
|
3029 from the font of the default face. It can only succeed at this if you
|
|
|
3030 have specified the default font using the XLFD (X Logical Font
|
|
|
3031 Description) format, which looks like
|
|
|
3032
|
|
|
3033 @example
|
|
|
3034 *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
|
|
|
3035 @end example
|
|
|
3036 @noindent
|
|
|
3037
|
|
3711
|
3038 All X fonts can be referred to via XLFD-style names, and you should use
|
|
|
3039 those forms. See the man pages for @samp{X(1)}, @samp{xlsfonts(1)}, and
|
|
|
3040 @samp{xfontsel(1)}.
|
|
|
3041
|
|
428
|
3042 If you use any of the other, less strict font name formats, some of which
|
|
|
3043 look like
|
|
|
3044
|
|
|
3045 @example
|
|
|
3046 lucidasanstypewriter-12
|
|
|
3047 fixed
|
|
|
3048 9x13
|
|
|
3049 @end example
|
|
|
3050
|
|
|
3051 then XEmacs won't be able to guess the names of the bold and italic
|
|
3711
|
3052 versions, and on a build with internationalization support, it will
|
|
|
3053 refuse to use them. (Since only the XLFD form includes information as
|
|
|
3054 to which character set the font coverage.)
|
|
|
3055
|
|
|
3056 If it is very important to you to use the short form names, you can
|
|
|
3057 override this for ASCII, and for ASCII alone, by passing the
|
|
|
3058 @samp{FORCE} argument to @samp{set-charset-registries}, and specifying
|
|
|
3059 an empty string as one of the charset registries.
|
|
428
|
3060
|
|
|
3061 @node Widgets
|
|
|
3062 @subsection Widgets
|
|
|
3063
|
|
|
3064 There are several structural widgets between the terminal EmacsFrame
|
|
|
3065 widget and the top level ApplicationShell; the exact names and types of
|
|
|
3066 these widgets change from release to release (for example, they changed
|
|
|
3067 between 19.8 and 19.9, 19.9 and 19.10, and 19.10 and 19.12) and are
|
|
|
3068 subject to further change in the future, so you should avoid mentioning
|
|
|
3069 them in your resource database. The above-mentioned syntaxes should be
|
|
|
3070 forward- compatible. As of 19.13, the exact widget hierarchy is as
|
|
|
3071 follows:
|
|
|
3072
|
|
|
3073 @example
|
|
|
3074 INVOCATION-NAME "shell" "container" FRAME-NAME
|
|
|
3075 x-emacs-application-class "EmacsShell" "EmacsManager" "EmacsFrame"
|
|
|
3076 @end example
|
|
|
3077
|
|
|
3078 where INVOCATION-NAME is the terminal component of the name of the
|
|
|
3079 XEmacs executable (usually @samp{xemacs}), and
|
|
2736
|
3080 @samp{x-emacs-application-class} is generally @samp{XEmacs}.
|
|
428
|
3081
|
|
|
3082 @node Menubar Resources
|
|
|
3083 @subsection Menubar Resources
|
|
|
3084
|
|
|
3085 As the menubar is implemented as a widget which is not a part of XEmacs
|
|
442
|
3086 proper, it does not use the face mechanism for specifying fonts and
|
|
428
|
3087 colors: It uses whatever resources are appropriate to the type of widget
|
|
|
3088 which is used to implement it.
|
|
|
3089
|
|
2681
|
3090 If XEmacs was compiled to use only the Lucid Motif-lookalike menu widgets,
|
|
442
|
3091 then one way to specify the font of the menubar would be
|
|
428
|
3092
|
|
|
3093 @example
|
|
2681
|
3094 XEmacs*menubar*font: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
|
|
428
|
3095 @end example
|
|
|
3096
|
|
1137
|
3097 If both the Lucid Motif-lookalike menu widgets and X Font Sets are
|
|
442
|
3098 configured to allow multilingual menubars, then one uses
|
|
|
3099
|
|
|
3100 @example
|
|
|
3101 *menubar*FontSet: -*-helvetica-bold-r-*-*-*-120-*-*-*-*-iso8859-*, \
|
|
|
3102 -*-*-*-*-*-*-*-120-*-jisx0208.1983-0
|
|
|
3103 @end example
|
|
|
3104
|
|
|
3105 That would specify fonts for a Japanese menubar. Specifying only one
|
|
|
3106 XLFD is acceptable; specifying more than one for a given registry
|
|
|
3107 (language) is also allowed. When X Font Sets are configured, some .font
|
|
|
3108 resources (eg, menubars) are ignored in favor of the corresponding
|
|
|
3109 .fontSet resources.
|
|
|
3110
|
|
1137
|
3111 If the Motif library is being used, then one would have to use
|
|
428
|
3112
|
|
|
3113 @example
|
|
2681
|
3114 XEmacs*menubar*fontList: *-courier-medium-r-*-*-*-120-*-*-*-*-*-*
|
|
428
|
3115 @end example
|
|
|
3116
|
|
|
3117 because the Motif library uses the @code{fontList} resource name instead
|
|
|
3118 of @code{font}, which has subtly different semantics.
|
|
|
3119
|
|
1137
|
3120 The same is true of the scrollbars: They accept whichever resources are
|
|
428
|
3121 appropriate for the toolkit in use.
|
