Mercurial > hg > xemacs-beta
annotate man/xemacs/custom.texi @ 5640:e6b5c49f9e13
Add autoload cookie to custom-set-face-bold
| author | Vin Shelton <acs@xemacs.org> |
|---|---|
| date | Sun, 08 Jan 2012 22:29:06 -0500 |
| parents | 5502045ec510 |
| children | 9fae6227ede5 |
| rev | line source |
|---|---|
| 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 | |
| 4488 | 139 @c @defun enable-behavior behavior &optional force |
| 2736 | 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. | |
|
5080
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2083 @item M-x set-face-background-placement |
|
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2084 Change the placement of the background pixmap of the given @var{face}. |
| 1137 | 2085 @item M-x set-face-font |
| 428 | 2086 Change the font of the given @var{face}. |
| 2087 @item M-x set-face-foreground | |
| 2088 Change the foreground color of the given @var{face}. | |
| 2089 @item M-x set-face-underline-p | |
| 2090 Change whether the given @var{face} is underlined. | |
| 2091 @end table | |
| 2092 | |
| 2093 @findex make-face-larger | |
| 2094 @findex make-face-smaller | |
| 2095 | |
| 2096 @findex invert-face | |
| 2097 You can exchange the foreground and background color of the selected | |
| 2098 @var{face} with the function @code{invert-face}. If the face does not | |
| 2099 specify both foreground and background, then its foreground and | |
| 2100 background are set to the background and foreground of the default face. | |
| 1137 | 2101 When calling this from a program, you can supply the optional argument |
| 428 | 2102 @var{frame} to specify which frame is affected; otherwise, all frames |
| 2103 are affected. | |
| 2104 | |
| 1142 | 2105 @findex make-face-bold |
| 2106 @findex make-face-bold-italic | |
| 2107 @findex make-face-italic | |
| 2108 @findex make-face-unbold | |
| 2109 @findex make-face-unitalic | |
| 2110 @vindex face-frob-from-locale-first | |
| 2111 The work of @code{make-face-bold}, @code{make-face-bold-italic}, | |
| 2112 @code{make-face-italic}, @code{make-face-unbold}, | |
| 2113 @code{make-face-unitalic} functions is affected by | |
| 2114 @code{face-frob-from-locale-first} variable. If it is @code{nil}, those | |
| 2115 functions first try to manipulate device specific data like X font names | |
| 2116 to obtain the desired font face specification. This may be unsuitable | |
| 2117 in environments using different font face specifications for different | |
| 2118 frames, non-Mule environments in particular. | |
| 2119 | |
| 2120 If the variable is non-@code{nil}, those functions first try to figure | |
| 2121 out whether the face font is the same as one of predefined faces: | |
| 2122 @code{default}, @code{bold}, @code{italic}, @code{bold-italic}. If it | |
| 2123 is the same, then the new face font specification is set to be the same | |
| 2124 as that of a corresponding predefined face. Thus if the predefined face | |
| 2125 is set up properly for different frames, the same will hold for the face | |
| 2126 being changed by the functions. This is the behavior one might desire | |
| 2127 in non-Mule environments mentioned above: face being changed still looks | |
| 2128 right in all frames. | |
| 2129 | |
| 2130 How predefined faces might be set up for different frames in such an | |
| 2131 environments is described in @ref{Face Resources}. | |
| 2132 | |
| 428 | 2133 @findex set-face-background |
| 2134 You can set the background color of the specified @var{face} with the | |
| 2135 function @code{set-face-background}. The argument @code{color} should | |
| 2136 be a string, the name of a color. When called from a program, if the | |
| 1137 | 2137 optional @var{frame} argument is provided, the face is changed only |
| 428 | 2138 in that frame; otherwise, it is changed in all frames. |
| 2139 | |
| 2140 @findex set-face-background-pixmap | |
| 2141 You can set the background pixmap of the specified @var{face} with the | |
| 2142 function @code{set-face-background-pixmap}. The pixmap argument | |
| 2143 @var{name} should be a string, the name of a file of pixmap data. The | |
| 2144 directories listed in the @code{x-bitmap-file-path} variable are | |
| 2145 searched. The bitmap may also be a list of the form @code{(@var{width | |
| 2146 height data})}, where @var{width} and @var{height} are the size in | |
| 2147 pixels, and @var{data} is a string containing the raw bits of the | |
| 2148 bitmap. If the optional @var{frame} argument is provided, the face is | |
| 2149 changed only in that frame; otherwise, it is changed in all frames. | |
| 2150 | |
| 2151 The variable @code{x-bitmap-file-path} takes as a value a list of the | |
| 2152 directories in which X bitmap files may be found. If the value is | |
| 2153 @code{nil}, the list is initialized from the @code{*bitmapFilePath} | |
| 2154 resource. | |
| 2155 | |
| 2156 If the environment variable @b{XBMLANGPATH} is set, then it is consulted | |
| 2157 before the @code{x-bitmap-file-path} variable. | |
| 2158 | |
| 1137 | 2159 @findex set-face-background-pixmap |
| 2160 Alternately, you can use a simpler version of | |
| 2161 @code{set-face-background-pixmap} called | |
| 2162 @code{set-face-background-pixmap-file}. This function does not give you | |
| 3111 | 2163 as much control on the pixmap instantiator, but provides filename |
| 1137 | 2164 completion. |
| 2165 | |
|
5080
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2166 @findex set-face-background-placement |
|
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2167 You can set the placement of the background pixmap of the specified |
|
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2168 @var{face} with the function @code{set-face-background-placement}. The |
|
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2169 placement argument can be either @code{absolute} or @code{relative} (the |
|
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2170 default). A @code{relative} placement means that the pixmap is attached |
|
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2171 to the frame and moves with it. An @code{absolute} placement means that |
|
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2172 the pixmap is rather attached to the frame's root window, so that when |
|
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2173 you move the frame on the screen, it will appear to ``slide'' on the |
|
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2174 pixmap. This placement mode can be used to achieve pseudo-translucency |
|
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2175 for a frame, for example by setting the default face's background pixmap |
|
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2176 to the root window's one. |
|
5502045ec510
The background-placement face property.
Didier Verna <didier@lrde.epita.fr>
parents:
4666
diff
changeset
|
2177 |
| 428 | 2178 @findex set-face-font |
| 2179 You can set the font of the specified @var{face} with the function | |
| 2180 @code{set-face-font}. The @var{font} argument should be a string, the | |
| 2181 name of a font. When called from a program, if the | |
| 1137 | 2182 optional @var{frame} argument is provided, the face is changed only |
| 428 | 2183 in that frame; otherwise, it is changed in all frames. |
| 2184 | |
| 3111 | 2185 The syntax of the @var{font} argument varies according to platform. In |
| 2186 each of the following syntaxes, the example shows how to specify a | |
| 2187 14-point upright bold Courier font. | |
| 2188 | |
| 2189 @table @strong | |
| 2190 @item X11 | |
| 2191 The X11 syntax is defined by the @dfn{X Logical Font Descriptor} (XLFD) | |
| 2192 standard. An XLFD contains 14 fields each preceded by a hyphen: | |
| 2193 foundry, family, weight, slant, swidth, adstyle, pixelsize, pointsize, | |
| 2194 xresolution, yresolution, spacing, averagewidth, registry, and encoding. | |
| 2195 It is usually sufficient to specify family, weight, slant, pointsize, | |
| 2196 registry, and encoding, wildcarding the rest with @samp{*}. If you're | |
| 2197 not sure what's available, you can wildcard some of the fields usually | |
| 2198 specified, too. Here's our example font in XLFD syntax: | |
| 2199 @code{"-*-courier-bold-r-*-*-*-140-*-*-*-*-iso8859-*"}. | |
| 2200 The XLFD syntax is also used for GTK+ version 1. XLFD names must be | |
| 3510 | 2201 encoded in ISO-8859-1. |
| 3111 | 2202 |
| 2203 @item Xft | |
| 2204 The Xft syntax is defined by the @file{fontconfig} library | |
| 2205 @ref{Font Names,,,fontconfig}. It is less a font naming convention than | |
| 2206 a way to express any arbitrary subset of the font's properties in a | |
| 2207 syntax that is both human- and machine-readable. A @file{fontconfig} | |
| 2208 font name contains the family, a hyphen, and the pointsize, followed by | |
| 2209 an arbitrary sequence of properties. Each property consists of a colon, | |
| 2210 a keyword, an equals sign, and the property value. Here's our example | |
| 2211 font in @file{fontconfig} syntax: @code{"Courier-14:weight=bold"}. This | |
| 2212 syntax admits ``style abbreviations'' which can be user-defined. A | |
| 2213 style is a single keyword denoting a sequence of properties. So the | |
| 2214 example font may be abbreviated to @code{"Courier-14:bold"} ("bold" is a | |
| 2215 standard abbreviation for "weight=bold"). The @file{fontconfig} syntax | |
| 2216 is also used for GTK+ version 2. @file{fontconfig} names must be | |
| 2217 encoded in UTF-8. | |
| 2218 | |
| 2219 @item MS-Windows | |
| 2220 The MS Windows syntax is superficially similar to that of Xft but | |
| 2221 actually is more like XLFD. A font name consists of five fields, | |
| 2222 family, size, slant, weight, and encoding, each expressed as a keyword | |
| 2223 taking on standardized values (except family, which is just a name). | |
| 2224 Here's our example font in MS Windows syntax: | |
| 2225 @code{"Courier:14:Bold:Western"}. | |
| 2226 @end table | |
| 2227 | |
| 1137 | 2228 @findex set-face-foreground |
| 428 | 2229 You can set the foreground color of the specified @var{face} with the |
| 2230 function @code{set-face-foreground}. The argument @var{color} should be | |
| 2231 a string, the name of a color. If the optional @var{frame} argument is | |
| 2232 provided, the face is changed only in that frame; otherwise, it is | |
| 2233 changed in all frames. | |
| 2234 | |
| 2235 @findex set-face-underline-p | |
| 2236 You can set underline the specified @var{face} with the function | |
| 2237 @code{set-face-underline-p}. The argument @var{underline-p} can be used | |
| 2238 to make underlining an attribute of the face or not. If the optional | |
| 2239 @var{frame} argument is provided, the face is changed only in that | |
| 2240 frame; otherwise, it is changed in all frames. | |
| 2241 | |
| 3387 | 2242 |
| 2243 @node Xft Font Customization, , , Faces | |
| 2244 @section Xft Font Customization | |
| 2245 | |
| 2246 This section was written by @email{stephen@@xemacs.org,Stephen Turnbull}, | |
| 2247 and is very much a work in progress. I've tried to provide pointers to | |
| 2248 as much of the relevant information as possible, but many of the APIs | |
| 2249 and UIs are in flux, so it seemed more work than it was worth to | |
| 2250 completely translate the tables of constants, and so on. Feel free to | |
| 2251 ask for clarifications, @emph{etc.} Please Cc | |
| 2252 @email{xemacs-beta@@xemacs.org,the XEmacs Beta Testers' mailing list}, | |
| 2253 as that is the issue tracking channel of record, and there are a few | |
| 2254 others who can answer the questions or improve documentation when I'm | |
| 2255 not able to respond quickly. | |
| 2256 | |
| 2257 @c Don't blame Ben (or Eric and Matthias, for that matter). Feel free to | |
| 2258 @c add, edit, and share the blame, everybody! | |
| 2259 | |
| 2260 @c #### Make these @urlref's!! | |
| 2261 As of mid-2005, we have added support for the | |
| 2262 @file{Xft} library, which provides a more robust @emph{font | |
| 2263 configuration} mechanism via Keith Packard's @file{fontconfig} library; | |
| 2264 improved glyph rendering, including antialiasing, via the | |
| 2265 @file{freetype} library; and client-side rendering (saving bandwidth and | |
| 2266 server memory) via the @file{XRender extension}. | |
| 2267 | |
| 2268 @c #### Describe Alexey Gladkov and Yury Konovalov's work. | |
| 2269 | |
| 2270 @subheading Font configuration | |
| 2271 | |
| 2272 In XEmacs, font configuration is handled via @emph{faces}. Currently | |
| 2273 XEmacs uses a special type of @emph{font specifier} to map XEmacs | |
| 2274 locales to font names. Especially under X11, this can cause annoying | |
| 2275 problems because of the unreliability of X servers' mappings from | |
| 2276 @samp{XLFD} names to X11 fonts, over which XEmacs has no influence | |
| 2277 whatsoever. However, the @file{fontconfig} library which is used with | |
| 2278 @file{Xft} provides much more reliable mapping, along with a more | |
| 2279 reliably parsable naming scheme similar to that used by TrueType fonts | |
| 2280 on MS Windows and the Macintosh. | |
| 2281 | |
| 2282 @subheading fontconfig | |
| 2283 | |
| 2284 Fontconfig is dramatically different from the X model in several ways. | |
| 2285 In particular, when queried for a font @emph{fontconfig always returns a | |
| 2286 font}, whereas X queries may return ``not found.'' However, the font | |
| 2287 returned need not be anything like the desired font. This is not really | |
| 2288 a problem in practice, because users generally have a pretty good idea | |
| 2289 of what fonts are available on their display. However, users should be | |
| 2290 aware that as of XEmacs 21.5.26 the font selection internals have not | |
| 2291 been revised to account for this radically different model, so some | |
| 2292 surprising results are possible. | |
| 2293 | |
| 2294 From the user's point of view, @file{fontconfig} provides a naming | |
| 2295 convention which is @emph{precise}, @emph{accurate}, and | |
| 2296 @emph{convenient}. Precision means that all properties available in the | |
| 2297 programming API can be individually specified. Accuracy means that the | |
| 2298 truename of the font is exactly the list of all properties specified by | |
| 4488 | 2299 the font. Thus, the anomalies that occur with XLFDs on many servers |
| 3387 | 2300 (including modern Linux distributions with XFree86 or X.org servers) |
| 2301 cannot occur. Convenience is subjective, of course. However, | |
| 2302 @file{fontconfig} provides a configuration system which (1) explicitly | |
| 2303 specifies the defaults and substitutions that will be made in processing | |
| 2304 user queries, (2) allows the user to specify search configuration, | |
| 2305 abbreviations, substitutions, and defaults that override the system's, | |
| 2306 in the same format as used by system files, and (3) allows flexible | |
| 2307 aliases that can resolve to any of several actual fonts depending on | |
| 2308 which fonts are installed. | |
| 2309 | |
| 2310 Further, a @dfn{standard minimal configuration} is defined that ensures | |
| 2311 that at least the @emph{serif}, @emph{sans-serif}, and @emph{monospace} | |
| 2312 font aliases are available on all @file{fontconfig} systems. | |
| 2313 | |
| 2314 @subheading fontconfig font names | |
| 2315 | |
| 2316 @file{fontconfig} font names are very regular, and constitute a precise | |
| 2317 and extensible specification of a font's properties. | |
| 2318 | |
| 2319 The basic @file{fontconfig} font name has three components: the font | |
| 2320 family name, the size, and a list of named attribute fields. All | |
| 2321 attribute names and values are strings encoded in Unicode UTF-8, or | |
| 2322 decimal numbers with optional decimal point and fraction. The | |
| 2323 characters @samp{-}, @samp{:}, @samp{,}, @samp{=}, and @samp{\} are | |
| 2324 syntactically significant to @file{fontconfig}. They may be used in | |
| 2325 font name components by the familiar mechanism of backslash escaping. | |
| 2326 This simply removes any special meaning from the following character. | |
| 2327 It is always safe to use an escape even if it is not needed. | |
| 2328 | |
| 2329 Most string values are case-insensitive, but this is attribute-specific. | |
| 2330 | |
| 2331 The @dfn{font family name} is an arbitrary string, which may contain any | |
| 2332 character, including spaces, hyphens, and commas. Don't forget to | |
| 2333 escape hyphens, colons, commas, and backslashes! | |
| 2334 | |
| 2335 The @dfn{size} is a decimal number with optional decimal point and | |
| 2336 fractional part. It is interpreted as point size. | |
| 2337 | |
| 2338 A @dfn{named attribute field} is a key-value pair separated by an equal | |
| 2339 sign. Some attributes have predefined semantics. (These include such | |
| 2340 familiar attributes as @samp{slant} and @samp{dpi} -- note that | |
| 2341 @file{fontconfig} does not distinguish between vertical and horizontal | |
| 2342 resolution! | |
| 2343 | |
| 2344 The basic syntax of a font name is simple and regular. The @emph{font | |
| 2345 family name} comes first, followed by a hyphen and the @emph{size}, | |
| 2346 followed by a list of @emph{named attribute fields}, each introduced by | |
| 2347 a colon: | |
| 2348 | |
| 2349 @example | |
| 2350 @var{font family name}-@var{size}:@var{key1}=@var{value1}:@var{key2}=@var{value2}... | |
| 2351 @end example | |
| 2352 | |
| 2353 There are four extensions to the basic syntax. First, all of the | |
| 2354 fields are optional. If size is omitted, the hyphen should be omitted | |
| 2355 as well. There should never be a trailing colon. Note that | |
| 2356 @file{fontconfig} does @emph{not} interpret an omitted field as | |
| 2357 ``default to current.'' @file{fontconfig} does not have access to that | |
| 2358 context. Instead, omitted fields are filled in according to a set of | |
| 2359 defaults specified in the system @file{fonts.conf} file and in the | |
| 2360 user's @file{.fonts.cont} file. The user's configuration gets | |
| 2361 precedence, of course. | |
| 2362 | |
| 2363 The second is that the @emph{font family name}, the @emph{size}, and the | |
| 2364 @emph{value} component of a @emph{named attribute field} may be a | |
| 2365 comma-separated list of values. This is called a @dfn{pattern}. In | |
| 2366 queries, @file{fontconfig} tries to match each entry in the list in | |
| 2367 order. (I suspect that order of attributes is also significant. | |
| 2368 @emph{I.e.}, font family always gets highest precedence, followed by | |
| 2369 size, followed by the remaining named attributes. Testing and reports | |
| 2370 to the @email{xemacs-beta@@xemacs.org,XEmacs Beta Testers mailing list} | |
| 2371 are very welcome!) | |
| 2372 | |
| 2373 The third is the definition of @dfn{constants} to represent numerical | |
| 2374 values. For example, both @samp{slant} and @samp{weight} are defined as | |
| 2375 integer attributes, but the magnitudes are arbitrary; only the ordering | |
| 2376 and relative distances are useful. (``Relative distance'' is used to | |
| 2377 implement the concept that although strictly speaking @emph{italic} and | |
| 2378 @emph{oblique} are different faces, most users don't know the | |
| 2379 difference, and even professional typographers would agree that they are | |
| 2380 much closer to each other than either is to @emph{roman}.) So | |
| 2381 @emph{constants} like @samp{roman} (0) and @samp{italic} (100) are | |
| 2382 defined for @samp{slant}, and @samp{medium} (100) and @samp{bold} (200) | |
| 2383 are defined for @samp{weight}. | |
| 2384 | |
| 2385 The fourth is that a @dfn{style} may be defined as an alias for an | |
| 2386 instance of a @emph{named attribute field}, that is, specifying both key | |
| 2387 and value. The @emph{styles} @samp{bold}, an alias for | |
| 2388 @samp{weight=200}, and @samp{italic}, an alias for @samp{slant=100}, are | |
| 2389 commonly used. | |
| 2390 | |
| 2391 Styles and constants can be defined by the application. XEmacs | |
| 2392 currently defines none, but suggestions are welcome if some convenient | |
| 2393 alias is lacking from @file{fontconfig}. Note that we will not provide | |
| 2394 additional aliases where standard ones exist, @emph{e.g.}, @samp{heavy} | |
| 2395 as an additional alias for @samp{bold} would almost certainly be | |
| 2396 rejected. These cause more confusion than they are worth, and would | |
| 2397 decrease portability of user specifications to other applications. | |
| 2398 | |
| 2399 (Attributes can also be defined, but they must be implemented by the | |
| 2400 fonts to be useful. Until XEmacs provides its own fonts with | |
| 2401 non-standardized attributes, this is not useful.) | |
| 2402 | |
| 2403 Here are some examples of font names and query patterns: | |
| 2404 | |
| 2405 @example | |
| 2406 Times-12 12-point Times Roman | |
| 2407 Times-12:bold 12-point Times Bold | |
| 2408 Courier:italic Courier Italic in the default size | |
| 2409 Monospace:matrix=1 .1 0 1 The user's preferred monospace font | |
| 2410 with artificial obliquing | |
| 2411 Mikachan\-PB-16 16-point Mikachan-PB | |
| 2412 LucidaTypewriter,Courier-9 9-point LucidaTypewriter if available, | |
| 2413 otherwise 9-point Courier | |
| 2414 @end example | |
| 2415 | |
| 2416 Note how @emph{styles} are used in the second and third examples, how | |
| 2417 @samp{matrix} has a complex value containing spaces, and the | |
| 2418 escaped hyphen in the font family name @samp{Mikachan\-PB}. | |
| 2419 | |
| 2420 @c #### FIXME here and also in fontconfig.texi (in general-docs package). | |
| 2421 Here is a (somewhat outdated) list of current standard named attributes: | |
| 2422 | |
| 2423 @example | |
| 2424 Property CPP symbol Type Description | |
| 2425 | |
| 2426 family FC_FAMILY String Font family name | |
| 2427 style FC_STYLE String Font style. Overrides weight and slant | |
| 2428 slant FC_SLANT Int Italic, oblique or roman | |
| 2429 weight FC_WEIGHT Int Light, medium, demibold, bold or black | |
| 2430 size FC_SIZE Double Point size | |
| 2431 aspect FC_ASPECT Double Stretch glyphs horizontally, then hint | |
| 2432 pixelsize FC_PIXEL_SIZE Double Pixel size | |
| 2433 spacing FC_SPACING Int Proportional, monospace or charcell | |
| 2434 foundry FC_FOUNDRY String Font foundry name | |
| 2435 antialias FC_ANTIALIAS Bool Should glyphs be antialiased? | |
| 2436 hinting FC_HINTING Bool Should the rasterizer use hinting? | |
| 2437 verticallayout FC_VERTICAL_LAYOUT Bool Use vertical layout | |
| 2438 autohint FC_AUTOHINT Bool Use autohinter instead of normal hinter | |
| 2439 globaladvance FC_GLOBAL_ADVANCE Bool Use font global advance data | |
| 2440 file FC_FILE String The filename holding the font | |
| 2441 index FC_INDEX Int The index of the font within the file | |
| 2442 ftface FC_FT_FACE FT_Face Use the specified FreeType face object | |
| 2443 rasterizer FC_RASTERIZER String Which rasterizer is in use | |
| 2444 outline FC_OUTLINE Bool Whether the glyphs are outlines | |
| 2445 scalable FC_SCALABLE Bool Whether glyphs can be scaled | |
| 2446 scale FC_SCALE Double Point->pixel conversion scale factor | |
| 2447 dpi FC_DPI Double Target dots per inch | |
| 2448 rgba FC_RGBA Int unknown, rgb, bgr, vrgb, vbgr, none | |
| 2449 - subpixel geometry | |
| 2450 source FC_SOURCE String X11, freetype | |
| 2451 minspace FC_MINSPACE Bool Eliminate leading from line spacing | |
| 2452 charset FC_CHARSET CharSet Unicode chars encoded by the font | |
| 2453 lang FC_LANG String List of RFC-3066-style languages | |
| 2454 this font supports | |
| 2455 fontversion FC_FONTVERSION Int From 'head' table | |
| 2456 @end example | |
| 2457 | |
| 2458 Here is a list of current standard constants: | |
| 2459 | |
| 2460 @example | |
| 2461 Constant Property CPP symbol | |
| 2462 | |
| 2463 light weight FC_WEIGHT_LIGHT | |
| 2464 medium weight FC_WEIGHT_MEDIUM | |
| 2465 demibold weight FC_WEIGHT_DEMIBOLD | |
| 2466 bold weight FC_WEIGHT_BOLD | |
| 2467 black weight FC_WEIGHT_BLACK | |
| 2468 roman slant FC_SLANT_ROMAN | |
| 2469 italic slant FC_SLANT_ITALIC | |
| 2470 oblique slant FC_SLANT_OBLIQUE | |
| 2471 proportional spacing FC_PROPORTIONAL | |
| 2472 mono spacing FC_MONO | |
| 2473 charcell spacing FC_CHARCELL | |
| 2474 unknown rgba FC_RGBA_UNKNOWN | |
| 2475 rgb rgba FC_RGBA_RGB | |
| 2476 bgr rgba FC_RGBA_BGR | |
| 2477 vrgb rgba FC_RGBA_VRGB | |
| 2478 vbgr rgba FC_RGBA_VBGR | |
| 2479 none rgba FC_RGBA_NONE | |
| 2480 @end example | |
| 2481 | |
| 2482 Note that this is the @file{fontconfig} API list; you can expect that | |
| 2483 XEmacs will define corresponding keywords by substituting @samp{:} for | |
| 2484 the leading @samp{FC_}, @samp{-} for @samp{_}, removing the key of the | |
| 2485 attribute if present, and lowercasing the name. Thus | |
| 2486 @samp{FC_WEIGHT_BOLD} becomes @samp{:bold}. | |
| 2487 @kbd{M-x apropos RET fc-.*-mapping} will give a list of variables each | |
| 2488 of which lists such keywords and their meanings. | |
| 2489 | |
| 2490 @subheading Font menus | |
| 2491 | |
| 2492 The @samp{Options->Font} and @samp{Options->Font Sizes} menus are | |
| 2493 broken, by design, not just by @file{Xft}. The problem is that many | |
| 2494 fonts are unavailable because they don't match the current size---which | |
| 2495 is very strange, since @file{Xft} fonts are of course scalable. But the | |
| 2496 whole idea of requiring that the font match the size is strange. And | |
| 2497 the @samp{Options->Font Weights} menu is just disabled, and has been for | |
| 2498 eons. | |
| 2499 | |
| 2500 @subheading X resources | |
| 2501 | |
| 2502 Currently there are @emph{four} treatments of font resources. There are | |
| 2503 the @samp{XEmacs.@var{face}.attributeFont} resources used to set a | |
| 2504 single global font specification. In the widgets, some (still) have a | |
| 2505 @samp{font} resource using the automatic @file{Xt} resource conversion | |
| 2506 to X's @samp{FontStruct}, some have separate @samp{font} and @samp{xftFont} | |
| 2507 resources with the former automatically converted to @samp{FontStruct} | |
| 2508 by @file{Xt} and the latter left as a string, to be converted to a | |
| 2509 fontconfig @samp{FcPattern} by | |
| 2510 @samp{FcParseName} later, and some have a single @samp{font} resource | |
| 2511 which is converted to @samp{FontStruct} by @file{Xt} or the latter left | |
| 2512 as a string, depending on whether @file{Xft} was enabled by | |
| 2513 @samp{configure} or not. | |
| 2514 | |
| 2515 Eventually these should be converted to use the face | |
| 2516 approach, perhaps with some way to set specifications for individual | |
| 2517 widgets, frames, or buffers. This will require some careful design work | |
| 2518 to incorporate face support in the widgets. Stephen's current thinking | |
| 2519 is that XEmacs should just accept any | |
| 2520 or all of @samp{font}, @samp{fontSet}, and @samp{fontList} resources, | |
| 2521 treat them all as lists of font names, either @samp{XLFD}- or | |
| 2522 @file{fontconfig}-style, parse them ourselves (ie, not use the @file{Xt} | |
| 2523 resource manager), and add them to font specifiers as appropriate. But | |
| 2524 this will require a bit of thought to obey POLA vis-a-vis usual @file{Xt} | |
| 2525 conventions. | |
| 2526 | |
| 2527 @subheading Specifiers, charsets, and languages | |
| 2528 | |
| 2529 Traditionally Mule uses a rather rigid and low-level abstraction, the | |
| 2530 @emph{charset}, to characterize font repertoires. Unfortunately, | |
| 2531 support for a given charset is generally neither necessary nor | |
| 2532 sufficient to support a language. Worse, in XEmacs's current | |
| 2533 implementation Xft doesn't help much. Instead you need to add the fonts | |
| 2534 for different charsets to the font specifier in the right order. | |
| 2535 | |
| 2536 There currently is no explicit way to specify that a particular font be | |
| 2537 used only for a given language. However, since many fonts support only | |
| 2538 a limited repertoire such as ISO 8859/1, you can use the precedence of | |
| 2539 specifications for a given specifier locale to get something of this | |
| 2540 effect for non-Latin character sets. This will normally work rather | |
| 2541 poorly for multiple Latin character sets, however, because the | |
| 2542 repertoires tend to have large amounts of overlap. Support for | |
| 2543 specifying font by @emph{language} as well as by character set is | |
| 2544 planned. | |
| 2545 | |
| 2546 Because fonts supporting other languages tend to support English as | |
| 2547 well, if you want to use one font for English and another for the other | |
| 2548 language, you must use the @code{append} method when adding font | |
| 2549 specifications for the @emph{other} language. | |
| 2550 | |
| 2551 However, this simple method leaves you with a problem if you want to | |
| 2552 change the other language's font: you have to remove the existing | |
| 2553 specification so it won't shadow the new one when you append. | |
| 2554 | |
| 2555 In order to provide a convenient way to change ``other-language fonts'', | |
| 2556 I use @code{remove-tag-set-append} and @code{define-specifier-tag} like | |
| 2557 this: | |
| 2558 | |
| 2559 @example | |
| 2560 (define-specifier-tag 'lang-ja) | |
| 2561 ;; No, I don't try to do real work with this font! But it makes it | |
| 2562 ;; obvious that I got the requested font. :-) | |
| 2563 (set-face-font 'default "AirCut-14") | |
| 2564 (set-face-font 'default "Kochi Mincho-14" nil '(lang-ja) 'append) | |
| 2565 ;; Oops, too sober. Try something to match AirCut. | |
| 2566 (set-face-font 'default "Mikachan-14" | |
| 2567 nil '(lang-ja) 'remove-tag-set-append) | |
| 2568 @end example | |
| 2569 | |
| 2570 The only way to configure widget fonts at the present time is to use X | |
| 2571 resources (or hack the source and rebuild). Currently supported widgets | |
| 2572 are | |
| 2573 @itemize | |
| 2574 @item | |
| 2575 menubars | |
| 2576 @item | |
| 2577 tab controls | |
| 2578 @end itemize | |
| 2579 | |
| 2580 Here are the resources I use. @strong{Warning:} @emph{This interface | |
| 2581 will change. Pay attention to beta announcements, and complain loudly | |
| 2582 if changes aren't documented here!} The tab control and menubar have | |
|
4666
4c1a8323aa9a
Fix incorrect Xft resources in Info docs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
4488
diff
changeset
|
2583 separate @code{Font} and @code{FcFontName} resources, and use the X |
|
4c1a8323aa9a
Fix incorrect Xft resources in Info docs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
4488
diff
changeset
|
2584 resource manager to instantiate a FontStruct from the @code{Font} |
|
4c1a8323aa9a
Fix incorrect Xft resources in Info docs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
4488
diff
changeset
|
2585 resource. There is no converter facility for @code{FcFontName} yet, and |
|
4c1a8323aa9a
Fix incorrect Xft resources in Info docs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
4488
diff
changeset
|
2586 creating one that handles both FontStruct and XftFont depending on |
|
4c1a8323aa9a
Fix incorrect Xft resources in Info docs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
4488
diff
changeset
|
2587 XEmacs's configuration and the font name seems error-prone at best. |
|
4c1a8323aa9a
Fix incorrect Xft resources in Info docs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
4488
diff
changeset
|
2588 Probably we will use a simple string representation for this resource, |
|
4c1a8323aa9a
Fix incorrect Xft resources in Info docs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
4488
diff
changeset
|
2589 and convert to a face in XEmacs rather than a font in Xt/Xft. (The |
|
4c1a8323aa9a
Fix incorrect Xft resources in Info docs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
4488
diff
changeset
|
2590 older @code{XftFont} resource is deprecated. There is code intended to |
|
4c1a8323aa9a
Fix incorrect Xft resources in Info docs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
4488
diff
changeset
|
2591 implement backward compatibility, but there are repots that it doesn't |
|
4c1a8323aa9a
Fix incorrect Xft resources in Info docs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
4488
diff
changeset
|
2592 work properly.) |
| 3387 | 2593 @example |
|
4666
4c1a8323aa9a
Fix incorrect Xft resources in Info docs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
4488
diff
changeset
|
2594 XEmacs*Tabs.fcFontName: Bitstream Vera Sans-16 |
|
4c1a8323aa9a
Fix incorrect Xft resources in Info docs.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
4488
diff
changeset
|
2595 XEmacs*menubar*fcFontName: Bitstream Vera Sans-16 |
| 3387 | 2596 XEmacs.modeline.attributeFont: Bitstream Charter-16 |
| 2597 XEmacs.default.attributeFont: Bitstream Vera Sans Mono-16 | |
| 2598 @end example | |
| 2599 I highly recommend use of a proportional font in the modeline because it | |
| 2600 allows a lot more text to fit there. | |
| 2601 @c Previously the font sizes were quite varied, and there was a comment | |
| 2602 @c that this weirdness gave good balance. This isn't true on my main | |
| 2603 @c platform, Mac OS X, and needs to be rechecked on Linux, where it was | |
| 2604 @c observed. | |
| 2605 | |
| 2606 @subheading Known Problems | |
| 2607 | |
| 2608 @table @code | |
| 2609 @item Options->Font | |
| 2610 @itemx Options->Font Size | |
| 2611 These menus don't work. All fonts are greyed out. All sizes are | |
| 2612 available, but many (most?) faces don't change size, in particular, | |
| 2613 @samp{default} does not. | |
| 2614 | |
| 2615 @item Antialiased text bleeding outside of reported extent | |
| 2616 This is most obvious with the underscore character in that | |
| 2617 font, and with cursors. The bottom of the underscore is antialiased, | |
| 2618 and insertions or deletions in the same line before the underscore leave | |
| 2619 a series of "phantom" underlines. | |
| 2620 | |
| 2621 I think this is probably an Xft bug, but I'm not sure. | |
| 2622 @end table | |
| 2623 | |
| 2624 @subheading Variables Used with Xft and Fontconfig | |
| 2625 | |
| 2626 @defvar xft-debug-level | |
| 2627 | |
| 2628 Level of debugging messages to issue to stderr for @var{Xft}. | |
| 2629 A nonnegative integer. Set to 0 to suppress all warnings. | |
| 2630 Default is 1 to ensure a minimum of debugging output at initialization. | |
| 2631 Higher levels give more information. | |
| 2632 @end defvar | |
| 2633 | |
| 2634 @defvar xft-version | |
| 2635 | |
| 2636 The major version number of the Xft library compiled with. | |
| 2637 @end defvar | |
| 2638 | |
| 2639 @defvar xft-xlfd-font-regexp | |
| 2640 | |
| 2641 Regular expression matching XLFD font names. | |
| 2642 @end defvar | |
| 2643 | |
| 2644 | |
| 442 | 2645 @node Frame Components |
| 2646 @section Frame Components | |
| 2647 | |
| 2648 You can control the presence and position of most frame components, such | |
| 2649 as the menubar, toolbars, and gutters. | |
| 2650 | |
| 2651 This section is not written yet. Try the Lisp Reference Manual: | |
| 2652 @ref{Menubar,,,lispref,}, @ref{Toolbar Intro,,,lispref,}, and | |
| 2653 @ref{Gutter Intro,,,lispref,}. | |
| 2654 | |
| 428 | 2655 @node X Resources |
| 2656 @section X Resources | |
| 2657 @cindex X resources | |
| 2658 @findex x-create-frame | |
| 2659 | |
| 2681 | 2660 Historically, XEmacs used the X resource application class @samp{Emacs} |
| 2736 | 2661 for its resources. Unfortunately, GNU Emacs's usage of resources has |
| 2662 evolved differently from XEmacs's, and especially in the case of fonts | |
| 2663 semantics are not compatible between the two Emacsen. Thus, sharing of | |
| 2664 the application class can easily lead to trouble. | |
| 428 | 2665 |
| 2681 | 2666 XEmacs now uses the X resource application class @samp{XEmacs}. |
| 2736 | 2667 Versions since 21.5.21 do this unconditionally. To attempt to maintain |
| 2668 some backward compatibility, previous versions checked the X resource | |
| 2669 database for resources starting in @samp{XEmacs}, and if none were | |
| 2670 found, @samp{Emacs} was used. This behavior is likely to be obsoleted, | |
| 2671 so you should move your X resources to using the @samp{XEmacs} class. | |
| 2672 In the short term, to stay with the old behavior, start XEmacs with the | |
| 2673 environment variable @b{USE_EMACS_AS_DEFAULT_APPLICATION_CLASS} set to | |
| 2674 some non-empty value; this will restore the pre-21.5.21 behavior. | |
| 2675 @c #### is this documented in the Lispref? | |
| 2676 Lisp programs can examine the variable @code{x-emacs-application-class} | |
| 2677 to determine which is being used in the running application. | |
| 2681 | 2678 |
| 2679 The examples in this section assume the application class is | |
| 2736 | 2680 @samp{XEmacs}. |
| 2681 | |
| 2682 Most of XEmacs's resources are set per-frame. Each XEmacs frame can | |
| 2681 | 2683 have its own name or the same name as another, depending on the name |
| 2684 passed to the @code{make-frame} function. Up until 21.5.21, the default | |
| 2685 frame name was @samp{emacs}; since then, it has been @samp{XEmacs}, but | |
| 2686 in the short term the old default can be restored by the | |
| 2687 @b{USE_EMACS_AS_DEFAULT_APPLICATION_CLASS} environment variable | |
| 2736 | 2688 mentioned above. |
| 2689 @c #### Cheesy. Variable should be documented here. | |
| 2690 See the docstring for the Lisp variable `default-frame-name'. | |
| 428 | 2691 |
| 2692 You can specify resources for all frames with the syntax: | |
| 2693 | |
| 2694 @example | |
| 2681 | 2695 XEmacs*parameter: value |
| 428 | 2696 @end example |
| 2697 @noindent | |
| 2698 | |
| 2699 or | |
| 2700 | |
| 2701 @example | |
| 2681 | 2702 XEmacs*EmacsFrame.parameter:value |
| 428 | 2703 @end example |
| 2704 @noindent | |
| 2705 | |
| 2706 You can specify resources for a particular frame with the syntax: | |
| 2707 | |
| 2708 @example | |
| 2681 | 2709 XEmacs*FRAME-NAME.parameter: value |
| 428 | 2710 @end example |
| 2711 @noindent | |
| 2712 | |
| 2713 @menu | |
| 2714 * Geometry Resources:: Controlling the size and position of frames. | |
| 440 | 2715 * Iconic Resources:: Controlling whether frames come up iconic. |
| 2716 * Resource List:: List of resources settable on a frame or device. | |
| 2717 * Face Resources:: Controlling faces using resources. | |
| 2718 * Widgets:: The widget hierarchy for XEmacs. | |
| 2719 * Menubar Resources:: Specifying resources for the menubar. | |
| 428 | 2720 @end menu |
| 2721 | |
| 2722 @node Geometry Resources | |
| 2723 @subsection Geometry Resources | |
| 2724 | |
| 2681 | 2725 To make the default size of all XEmacs frames be 80 columns by 55 lines, |
| 428 | 2726 do this: |
| 2727 | |
| 2728 @example | |
| 2681 | 2729 XEmacs*EmacsFrame.geometry: 80x55 |
| 428 | 2730 @end example |
| 2731 @noindent | |
| 2732 | |
| 2733 To set the geometry of a particular frame named @samp{fred}, do this: | |
| 2734 | |
| 2735 @example | |
| 2681 | 2736 XEmacs*fred.geometry: 80x55 |
| 428 | 2737 @end example |
| 2738 @noindent | |
| 2739 | |
| 2740 Important! Do not use the following syntax: | |
| 2741 | |
| 2742 @example | |
| 2681 | 2743 XEmacs*geometry: 80x55 |
| 428 | 2744 @end example |
| 2745 @noindent | |
| 2746 | |
| 2747 You should never use @code{*geometry} with any X application. It does | |
| 2681 | 2748 not say "make the geometry of XEmacs be 80 columns by 55 lines." It |
| 2749 really says, "make XEmacs and all subwindows thereof be 80x55 in whatever | |
| 428 | 2750 units they care to measure in." In particular, that is both telling the |
| 2681 | 2751 XEmacs text pane to be 80x55 in characters, and telling the menubar pane |
| 428 | 2752 to be 80x55 pixels, which is surely not what you want. |
| 2753 | |
| 2754 As a special case, this geometry specification also works (and sets the | |
| 2681 | 2755 default size of all XEmacs frames to 80 columns by 55 lines): |
| 428 | 2756 |
| 2757 @example | |
| 2681 | 2758 XEmacs.geometry: 80x55 |
| 428 | 2759 @end example |
| 2760 @noindent | |
| 2761 | |
| 2762 since that is the syntax used with most other applications (since most | |
| 2681 | 2763 other applications have only one top-level window, unlike XEmacs). In |
| 428 | 2764 general, however, the top-level shell (the unmapped ApplicationShell |
| 2681 | 2765 widget named @samp{XEmacs} that is the parent of the shell widgets that |
| 428 | 2766 actually manage the individual frames) does not have any interesting |
| 2767 resources on it, and you should set the resources on the frames instead. | |
| 2768 | |
| 2769 The @code{-geometry} command-line argument sets only the geometry of the | |
| 2681 | 2770 initial frame created by XEmacs. |
| 428 | 2771 |
| 2772 A more complete explanation of geometry-handling is | |
| 2773 | |
| 2774 @itemize @bullet | |
| 2775 @item | |
| 2681 | 2776 The @code{-geometry} command-line option sets the @code{XEmacs.geometry} |
| 428 | 2777 resource, that is, the geometry of the ApplicationShell. |
| 2778 | |
| 2779 @item | |
| 2780 For the first frame created, the size of the frame is taken from the | |
| 2781 ApplicationShell if it is specified, otherwise from the geometry of the | |
| 2782 frame. | |
| 2783 | |
| 2784 @item | |
| 2785 For subsequent frames, the order is reversed: First the frame, and then | |
| 2786 the ApplicationShell. | |
| 2787 | |
| 2788 @item | |
| 2789 For the first frame created, the position of the frame is taken from the | |
| 2681 | 2790 ApplicationShell (@code{XEmacs.geometry}) if it is specified, otherwise |
| 428 | 2791 from the geometry of the frame. |
| 2792 | |
| 2793 @item | |
| 1137 | 2794 For subsequent frames, the position is taken only from the frame, and |
| 428 | 2795 never from the ApplicationShell. |
| 2796 @end itemize | |
| 2797 | |
| 2798 This is rather complicated, but it does seem to provide the most | |
| 2799 intuitive behavior with respect to the default sizes and positions of | |
| 2800 frames created in various ways. | |
| 2801 | |
| 2802 @node Iconic Resources | |
| 2803 @subsection Iconic Resources | |
| 2804 | |
| 2805 Analogous to @code{-geometry}, the @code{-iconic} command-line option | |
| 2681 | 2806 sets the iconic flag of the ApplicationShell (@code{XEmacs.iconic}) and |
| 428 | 2807 always applies to the first frame created regardless of its name. |
| 2808 However, it is possible to set the iconic flag on particular frames (by | |
| 2681 | 2809 name) by using the @code{XEmacs*FRAME-NAME.iconic} resource. |
| 428 | 2810 |
| 2811 @node Resource List | |
| 2812 @subsection Resource List | |
| 2813 | |
| 2681 | 2814 XEmacs frames accept the following resources: |
| 428 | 2815 |
| 2816 @table @asis | |
| 2817 @item @code{geometry} (class @code{Geometry}): string | |
| 2818 Initial geometry for the frame. @xref{Geometry Resources}, for a | |
| 2819 complete discussion of how this works. | |
| 2820 | |
| 2821 @item @code{iconic} (class @code{Iconic}): boolean | |
| 2822 Whether this frame should appear in the iconified state. | |
| 2823 | |
| 2824 @item @code{internalBorderWidth} (class @code{InternalBorderWidth}): int | |
| 1137 | 2825 How many blank pixels to leave between the text and the edge of the |
| 428 | 2826 window. |
| 2827 | |
| 2828 @item @code{interline} (class @code{Interline}): int | |
| 2829 How many pixels to leave between each line (may not be implemented). | |
| 2830 | |
| 2831 @item @code{menubar} (class @code{Menubar}): boolean | |
| 2832 Whether newly-created frames should initially have a menubar. Set to | |
| 2833 true by default. | |
| 2834 | |
| 2835 @item @code{initiallyUnmapped} (class @code{InitiallyUnmapped}): boolean | |
| 2836 Whether XEmacs should leave the initial frame unmapped when it starts | |
| 2837 up. This is useful if you are starting XEmacs as a server (e.g. in | |
| 2838 conjunction with gnuserv or the external client widget). You can also | |
| 2839 control this with the @code{-unmapped} command-line option. | |
| 2840 | |
| 2841 @item @code{barCursor} (class @code{BarColor}): boolean | |
| 2842 Whether the cursor should be displayed as a bar, or the traditional box. | |
| 2843 | |
| 2844 @item @code{cursorColor} (class @code{CursorColor}): color-name | |
| 2845 The color of the text cursor. | |
| 2846 | |
| 2847 @item @code{scrollBarWidth} (class @code{ScrollBarWidth}): integer | |
| 2848 How wide the vertical scrollbars should be, in pixels; 0 means no | |
| 2849 vertical scrollbars. You can also use a resource specification of the | |
| 2850 form @code{*scrollbar.width}, or the usual toolkit scrollbar resources: | |
| 2851 @code{*XmScrollBar.width} (Motif), @code{*XlwScrollBar.width} (Lucid), | |
| 2852 or @code{*Scrollbar.thickness} (Athena). We don't recommend that you | |
| 2853 use the toolkit resources, though, because they're dependent on how | |
| 2854 exactly your particular build of XEmacs was configured. | |
| 2855 | |
| 2856 @item @code{scrollBarHeight} (class @code{ScrollBarHeight}): integer | |
| 2857 How high the horizontal scrollbars should be, in pixels; 0 means no | |
| 2858 horizontal scrollbars. You can also use a resource specification of the | |
| 2859 form @code{*scrollbar.height}, or the usual toolkit scrollbar resources: | |
| 2860 @code{*XmScrollBar.height} (Motif), @code{*XlwScrollBar.height} (Lucid), | |
| 2861 or @code{*Scrollbar.thickness} (Athena). We don't recommend that you use | |
| 2862 the toolkit resources, though, because they're dependent on how exactly | |
| 2863 your particular build of XEmacs was configured. | |
| 2864 | |
| 2865 @item @code{scrollBarPlacement} (class @code{ScrollBarPlacement}): string | |
| 2866 Where the horizontal and vertical scrollbars should be positioned. This | |
| 2867 should be one of the four strings @samp{BOTTOM_LEFT}, | |
| 2868 @samp{BOTTOM_RIGHT}, @samp{TOP_LEFT}, and @samp{TOP_RIGHT}. Default is | |
| 2869 @samp{BOTTOM_RIGHT} for the Motif and Lucid scrollbars and | |
| 2870 @samp{BOTTOM_LEFT} for the Athena scrollbars. | |
| 2871 | |
| 2872 @item @code{topToolBarHeight} (class @code{TopToolBarHeight}): integer | |
| 2873 @itemx @code{bottomToolBarHeight} (class @code{BottomToolBarHeight}): integer | |
| 2874 @itemx @code{leftToolBarWidth} (class @code{LeftToolBarWidth}): integer | |
| 2875 @itemx @code{rightToolBarWidth} (class @code{RightToolBarWidth}): integer | |
| 2876 Height and width of the four possible toolbars. | |
| 2877 | |
| 2878 @item @code{topToolBarShadowColor} (class @code{TopToolBarShadowColor}): color-name | |
| 2879 @itemx @code{bottomToolBarShadowColor} (class @code{BottomToolBarShadowColor}): color-name | |
| 2880 Color of the top and bottom shadows for the toolbars. NOTE: These resources | |
| 2881 do @emph{not} have anything to do with the top and bottom toolbars (i.e. the | |
| 2882 toolbars at the top and bottom of the frame)! Rather, they affect the top | |
| 2883 and bottom shadows around the edges of all four kinds of toolbars. | |
| 2884 | |
| 2885 @item @code{topToolBarShadowPixmap} (class @code{TopToolBarShadowPixmap}): pixmap-name | |
| 2886 @itemx @code{bottomToolBarShadowPixmap} (class @code{BottomToolBarShadowPixmap}): pixmap-name | |
| 2887 Pixmap of the top and bottom shadows for the toolbars. If set, these | |
| 2888 resources override the corresponding color resources. NOTE: These | |
| 2889 resources do @emph{not} have anything to do with the top and bottom | |
| 2890 toolbars (i.e. the toolbars at the top and bottom of the frame)! | |
| 2891 Rather, they affect the top and bottom shadows around the edges of all | |
| 2892 four kinds of toolbars. | |
| 2893 | |
| 2894 @item @code{toolBarShadowThickness} (class @code{ToolBarShadowThickness}): integer | |
| 2895 Thickness of the shadows around the toolbars, in pixels. | |
| 2896 | |
| 2897 @item @code{visualBell} (class @code{VisualBell}): boolean | |
| 2898 Whether XEmacs should flash the screen rather than making an audible beep. | |
| 2899 | |
| 2900 @item @code{bellVolume} (class @code{BellVolume}): integer | |
| 2901 Volume of the audible beep. | |
| 2902 | |
| 2903 @item @code{useBackingStore} (class @code{UseBackingStore}): boolean | |
| 2904 Whether XEmacs should set the backing-store attribute of the X windows | |
| 2905 it creates. This increases the memory usage of the X server but decreases | |
| 2906 the amount of X traffic necessary to update the screen, and is useful | |
| 2907 when the connection to the X server goes over a low-bandwidth line | |
| 2908 such as a modem connection. | |
| 2909 @end table | |
| 2910 | |
| 2681 | 2911 XEmacs devices accept the following resources: |
| 428 | 2912 |
| 2913 @table @asis | |
| 2914 @item @code{textPointer} (class @code{Cursor}): cursor-name | |
| 2915 The cursor to use when the mouse is over text. This resource is used to | |
| 2916 initialize the variable @code{x-pointer-shape}. | |
| 2917 | |
| 2918 @item @code{selectionPointer} (class @code{Cursor}): cursor-name | |
| 2919 The cursor to use when the mouse is over a selectable text region (an | |
| 2920 extent with the @samp{highlight} property; for example, an Info | |
| 2921 cross-reference). This resource is used to initialize the variable | |
| 2922 @code{x-selection-pointer-shape}. | |
| 2923 | |
| 2924 @item @code{spacePointer} (class @code{Cursor}): cursor-name | |
| 2925 The cursor to use when the mouse is over a blank space in a buffer (that | |
| 2926 is, after the end of a line or after the end-of-file). This resource is | |
| 2927 used to initialize the variable @code{x-nontext-pointer-shape}. | |
| 2928 | |
| 2929 @item @code{modeLinePointer} (class @code{Cursor}): cursor-name | |
| 2930 The cursor to use when the mouse is over a modeline. This resource is | |
| 2931 used to initialize the variable @code{x-mode-pointer-shape}. | |
| 2932 | |
| 2933 @item @code{gcPointer} (class @code{Cursor}): cursor-name | |
| 2934 The cursor to display when a garbage-collection is in progress. This | |
| 2935 resource is used to initialize the variable @code{x-gc-pointer-shape}. | |
| 2936 | |
| 2937 @item @code{scrollbarPointer} (class @code{Cursor}): cursor-name | |
| 2938 The cursor to use when the mouse is over the scrollbar. This resource | |
| 2939 is used to initialize the variable @code{x-scrollbar-pointer-shape}. | |
| 2940 | |
| 2941 @item @code{pointerColor} (class @code{Foreground}): color-name | |
| 2942 @itemx @code{pointerBackground} (class @code{Background}): color-name | |
| 2943 The foreground and background colors of the mouse cursor. These | |
| 2944 resources are used to initialize the variables | |
| 2945 @code{x-pointer-foreground-color} and @code{x-pointer-background-color}. | |
| 2946 @end table | |
| 2947 | |
| 2948 @node Face Resources | |
| 2949 @subsection Face Resources | |
| 2950 | |
| 2951 The attributes of faces are also per-frame. They can be specified as: | |
| 2952 | |
| 2953 @example | |
| 2681 | 2954 XEmacs.FACE_NAME.parameter: value |
| 428 | 2955 @end example |
| 2956 @noindent | |
| 2957 | |
| 2958 or | |
| 2959 | |
| 2960 @example | |
| 2681 | 2961 XEmacs*FRAME_NAME.FACE_NAME.parameter: value |
| 428 | 2962 @end example |
| 2963 @noindent | |
| 2964 | |
| 2965 Faces accept the following resources: | |
| 2966 | |
| 2967 @table @asis | |
| 2968 @item @code{attributeFont} (class @code{AttributeFont}): font-name | |
| 2969 The font of this face. | |
| 2970 | |
| 2971 @item @code{attributeForeground} (class @code{AttributeForeground}): color-name | |
| 2972 @itemx @code{attributeBackground} (class @code{AttributeBackground}): color-name | |
| 2973 The foreground and background colors of this face. | |
| 2974 | |
| 2975 @item @code{attributeBackgroundPixmap} (class @code{AttributeBackgroundPixmap}): file-name | |
| 2681 | 2976 The name of an @sc{xbm} file (or @sc{xpm} file, if your version of XEmacs |
| 428 | 2977 supports @sc{xpm}), to use as a background stipple. |
| 2978 | |
| 2979 @item @code{attributeUnderline} (class @code{AttributeUnderline}): boolean | |
| 2980 Whether text in this face should be underlined. | |
| 2981 @end table | |
| 2982 | |
| 2983 All text is displayed in some face, defaulting to the face named | |
| 2984 @code{default}. To set the font of normal text, use | |
| 2681 | 2985 @code{XEmacs*default.attributeFont}. To set it in the frame named |
| 2986 @code{fred}, use @code{XEmacs*fred.default.attributeFont}. | |
| 428 | 2987 |
| 2988 These are the names of the predefined faces: | |
| 2989 | |
| 2990 @table @code | |
| 2991 @item default | |
| 2992 Everything inherits from this. | |
| 2993 | |
| 2994 @item bold | |
| 2681 | 2995 If this is not specified in the resource database, XEmacs tries to find a |
| 428 | 2996 bold version of the font of the default face. |
| 2997 | |
| 2998 @item italic | |
| 2681 | 2999 If this is not specified in the resource database, XEmacs tries to find |
| 428 | 3000 an italic version of the font of the default face. |
| 3001 | |
| 3002 @item bold-italic | |
| 2681 | 3003 If this is not specified in the resource database, XEmacs tries to find a |
| 428 | 3004 bold-italic version of the font of the default face. |
| 3005 | |
| 3006 @item modeline | |
| 3007 This is the face that the modeline is displayed in. If not specified in | |
| 3008 the resource database, it is determined from the default face by | |
| 3009 reversing the foreground and background colors. | |
| 3010 | |
| 3011 @item highlight | |
| 3012 This is the face that highlighted extents (for example, Info | |
| 3013 cross-references and possible completions, when the mouse passes over | |
| 3014 them) are displayed in. | |
| 3015 | |
| 3016 @item left-margin | |
| 3017 @itemx right-margin | |
| 3018 These are the faces that the left and right annotation margins are | |
| 3019 displayed in. | |
| 3020 | |
| 3021 @item zmacs-region | |
| 3022 This is the face that mouse selections are displayed in. | |
| 1137 | 3023 |
| 428 | 3024 @item isearch |
| 3025 This is the face that the matched text being searched for is displayed | |
| 3026 in. | |
| 3027 | |
| 3028 @item info-node | |
| 3029 This is the face of info menu items. If unspecified, it is copied from | |
| 3030 @code{bold-italic}. | |
| 3031 | |
| 3032 @item info-xref | |
| 3033 This is the face of info cross-references. If unspecified, it is copied | |
| 3034 from @code{bold}. (Note that, when the mouse passes over a | |
| 3035 cross-reference, the cross-reference's face is determined from a | |
| 3036 combination of the @code{info-xref} and @code{highlight} faces.) | |
| 3037 @end table | |
| 3038 | |
| 3039 Other packages might define their own faces; to see a list of all faces, | |
| 3040 use any of the interactive face-manipulation commands such as | |
| 3041 @code{set-face-font} and type @samp{?} when you are prompted for the | |
| 3042 name of a face. | |
| 3043 | |
| 3044 If the @code{bold}, @code{italic}, and @code{bold-italic} faces are not | |
| 3045 specified in the resource database, then XEmacs attempts to derive them | |
| 3046 from the font of the default face. It can only succeed at this if you | |
| 3047 have specified the default font using the XLFD (X Logical Font | |
| 3048 Description) format, which looks like | |
| 3049 | |
| 3050 @example | |
| 3051 *-courier-medium-r-*-*-*-120-*-*-*-*-*-* | |
| 3052 @end example | |
| 3053 @noindent | |
| 3054 | |
| 3711 | 3055 All X fonts can be referred to via XLFD-style names, and you should use |
| 3056 those forms. See the man pages for @samp{X(1)}, @samp{xlsfonts(1)}, and | |
| 3057 @samp{xfontsel(1)}. | |
| 3058 | |
| 428 | 3059 If you use any of the other, less strict font name formats, some of which |
| 3060 look like | |
| 3061 | |
| 3062 @example | |
| 3063 lucidasanstypewriter-12 | |
| 3064 fixed | |
| 3065 9x13 | |
| 3066 @end example | |
| 3067 | |
| 3068 then XEmacs won't be able to guess the names of the bold and italic | |
| 3711 | 3069 versions, and on a build with internationalization support, it will |
| 3070 refuse to use them. (Since only the XLFD form includes information as | |
| 3071 to which character set the font coverage.) | |
| 3072 | |
| 3073 If it is very important to you to use the short form names, you can | |
| 3074 override this for ASCII, and for ASCII alone, by passing the | |
| 3075 @samp{FORCE} argument to @samp{set-charset-registries}, and specifying | |
| 3076 an empty string as one of the charset registries. | |
| 428 | 3077 |
| 3078 @node Widgets | |
| 3079 @subsection Widgets | |
| 3080 | |
| 3081 There are several structural widgets between the terminal EmacsFrame | |
| 3082 widget and the top level ApplicationShell; the exact names and types of | |
| 3083 these widgets change from release to release (for example, they changed | |
| 3084 between 19.8 and 19.9, 19.9 and 19.10, and 19.10 and 19.12) and are | |
| 3085 subject to further change in the future, so you should avoid mentioning | |
| 3086 them in your resource database. The above-mentioned syntaxes should be | |
| 3087 forward- compatible. As of 19.13, the exact widget hierarchy is as | |
| 3088 follows: | |
| 3089 | |
| 3090 @example | |
| 3091 INVOCATION-NAME "shell" "container" FRAME-NAME | |
| 3092 x-emacs-application-class "EmacsShell" "EmacsManager" "EmacsFrame" | |
| 3093 @end example | |
| 3094 | |
| 3095 where INVOCATION-NAME is the terminal component of the name of the | |
| 3096 XEmacs executable (usually @samp{xemacs}), and | |
| 2736 | 3097 @samp{x-emacs-application-class} is generally @samp{XEmacs}. |
| 428 | 3098 |
| 3099 @node Menubar Resources | |
| 3100 @subsection Menubar Resources | |
| 3101 | |
| 3102 As the menubar is implemented as a widget which is not a part of XEmacs | |
| 442 | 3103 proper, it does not use the face mechanism for specifying fonts and |
| 428 | 3104 colors: It uses whatever resources are appropriate to the type of widget |
| 3105 which is used to implement it. | |
| 3106 | |
| 2681 | 3107 If XEmacs was compiled to use only the Lucid Motif-lookalike menu widgets, |
| 442 | 3108 then one way to specify the font of the menubar would be |
| 428 | 3109 |
| 3110 @example | |
| 2681 | 3111 XEmacs*menubar*font: *-courier-medium-r-*-*-*-120-*-*-*-*-*-* |
| 428 | 3112 @end example |
| 3113 | |
| 1137 | 3114 If both the Lucid Motif-lookalike menu widgets and X Font Sets are |
| 442 | 3115 configured to allow multilingual menubars, then one uses |
| 3116 | |
| 3117 @example | |
| 3118 *menubar*FontSet: -*-helvetica-bold-r-*-*-*-120-*-*-*-*-iso8859-*, \ | |
| 3119 -*-*-*-*-*-*-*-120-*-jisx0208.1983-0 | |
| 3120 @end example | |
| 3121 | |
| 3122 That would specify fonts for a Japanese menubar. Specifying only one | |
| 3123 XLFD is acceptable; specifying more than one for a given registry | |
| 3124 (language) is also allowed. When X Font Sets are configured, some .font | |
| 3125 resources (eg, menubars) are ignored in favor of the corresponding | |
| 3126 .fontSet resources. | |
| 3127 | |
| 1137 | 3128 If the Motif library is being used, then one would have to use |
| 428 | 3129 |
| 3130 @example | |
| 2681 | 3131 XEmacs*menubar*fontList: *-courier-medium-r-*-*-*-120-*-*-*-*-*-* |
| 428 | 3132 @end example |
| 3133 | |
| 3134 because the Motif library uses the @code{fontList} resource name instead | |
| 3135 of @code{font}, which has subtly different semantics. | |
| 3136 | |
| 1137 | 3137 The same is true of the scrollbars: They accept whichever resources are |
| 428 | 3138 appropriate for the toolkit in use. |