1 This is ../info/xemacs.info, produced by makeinfo version 4.0b from
4 INFO-DIR-SECTION XEmacs Editor
6 * XEmacs: (xemacs). XEmacs Editor.
9 This file documents the XEmacs editor.
11 Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
12 1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
13 Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
15 Permission is granted to make and distribute verbatim copies of this
16 manual provided the copyright notice and this permission notice are
17 preserved on all copies.
19 Permission is granted to copy and distribute modified versions of
20 this manual under the conditions for verbatim copying, provided also
21 that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
22 General Public License" are included exactly as in the original, and
23 provided that the entire resulting derived work is distributed under the
24 terms of a permission notice identical to this one.
26 Permission is granted to copy and distribute translations of this
27 manual into another language, under the above conditions for modified
28 versions, except that the sections entitled "The GNU Manifesto",
29 "Distribution" and "GNU General Public License" may be included in a
30 translation approved by the author instead of in the original English.
33 File: xemacs.info, Node: Mode Line, Next: GUI Components, Prev: Echo Area, Up: Frame
38 Each text window's last line is a "mode line" which describes what is
39 going on in that window. When there is only one text window, the mode
40 line appears right above the echo area. The mode line is in inverse
41 video if the terminal supports that, starts and ends with dashes, and
42 contains text like `XEmacs: SOMETHING'.
44 If a mode line has something else in place of `XEmacs: SOMETHING',
45 the window above it is in a special subsystem such as Dired. The mode
46 line then indicates the status of the subsystem.
48 Normally, the mode line has the following appearance:
50 --CH-XEmacs: BUF (MAJOR MINOR)----POS------
52 This gives information about the buffer being displayed in the window:
53 the buffer's name, what major and minor modes are in use, whether the
54 buffer's text has been changed, and how far down the buffer you are
57 CH contains two stars (`**') if the text in the buffer has been
58 edited (the buffer is "modified"), or two dashes (`--') if the buffer
59 has not been edited. Exception: for a read-only buffer, it is `%%'.
61 BUF is the name of the window's chosen "buffer". The chosen buffer
62 in the selected window (the window that the cursor is in) is also
63 XEmacs's selected buffer, the buffer in which editing takes place. When
64 we speak of what some command does to "the buffer", we mean the
65 currently selected buffer. *Note Buffers::.
67 POS tells you whether there is additional text above the top of the
68 screen or below the bottom. If your file is small and it is completely
69 visible on the screen, POS is `All'. Otherwise, POS is `Top' if you
70 are looking at the beginning of the file, `Bot' if you are looking at
71 the end of the file, or `NN%', where NN is the percentage of the file
72 above the top of the screen.
74 MAJOR is the name of the "major mode" in effect in the buffer. At
75 any time, each buffer is in one and only one major mode. The available
76 major modes include Fundamental mode (the least specialized), Text
77 mode, Lisp mode, and C mode. *Note Major Modes::, for details on how
78 the modes differ and how you select one.
80 MINOR is a list of some of the "minor modes" that are turned on in
81 the window's chosen buffer. For example, `Fill' means that Auto Fill
82 mode is on. `Abbrev' means that Word Abbrev mode is on. `Ovwrt' means
83 that Overwrite mode is on. *Note Minor Modes::, for more information.
84 `Narrow' means that the buffer being displayed has editing restricted
85 to only a portion of its text. This is not really a minor mode, but is
86 like one. *Note Narrowing::. `Def' means that a keyboard macro is
87 being defined. *Note Keyboard Macros::.
89 Some buffers display additional information after the minor modes.
90 For example, Rmail buffers display the current message number and the
91 total number of messages. Compilation buffers and Shell mode display
92 the status of the subprocess.
94 If XEmacs is currently inside a recursive editing level, square
95 brackets (`[...]') appear around the parentheses that surround the
96 modes. If XEmacs is in one recursive editing level within another,
97 double square brackets appear, and so on. Since information on
98 recursive editing applies to XEmacs in general and not to any one
99 buffer, the square brackets appear in every mode line on the screen or
100 not in any of them. *Note Recursive Edit::.
102 XEmacs can optionally display the time and system load in all mode
103 lines. To enable this feature, type `M-x display-time'. The
104 information added to the mode line usually appears after the file name,
105 before the mode names and their parentheses. It looks like this:
109 (Some fields may be missing if your operating system cannot support
110 them.) HH and MM are the hour and minute, followed always by `am' or
111 `pm'. L.LL is the average number of running processes in the whole
112 system recently. D is an approximate index of the ratio of disk
113 activity to CPU activity for all users.
115 The word `Mail' appears after the load level if there is mail for
116 you that you have not read yet.
118 Customization note: the variable `mode-line-inverse-video' controls
119 whether the mode line is displayed in inverse video (assuming the
120 terminal supports it); `nil' means no inverse video. The default is
121 `t'. For X frames, simply set the foreground and background colors
125 File: xemacs.info, Node: GUI Components, Next: XEmacs under X, Prev: Mode Line, Up: Frame
130 When executed in a graphical windowing environment such as the X
131 Window System or Microsoft Windows, XEmacs displays several graphical
132 user interface components such as scrollbars, menubars, toolbars, and
133 gutters. By default there is a vertical scrollbar at the right of each
134 frame, and at the top of the frame there is a menubar, a toolbar, and a
135 gutter, in that order. Gutters can contain any of several widgets, but
136 the default configuration puts a set of "notebook tabs" which you can
137 use as a shortcut for selecting any of several related buffers in a
138 given frame. Operating the GUI components is "obvious": click on the
139 menubar to pull down a menu, on a button in the toolbar to invoke a
140 function, and on a tab in the gutter to switch buffers.
144 * Menubar Basics:: How XEmacs uses the menubar.
145 * Scrollbar Basics:: How XEmacs uses scrollbars.
146 * Toolbar Basics:: How XEmacs uses toolbars.
147 * Gutter Basics:: How XEmacs uses gutters.
148 * Inhibiting:: What if you don't like GUI?
149 * Customizing:: Position, orientation, and appearance of GUI objects.
152 File: xemacs.info, Node: Menubar Basics, Next: Scrollbar Basics, Up: GUI Components
157 The XEmacs menubar is intended to be conformant to the usual
158 conventions for menubars, although conformance is not yet perfect. The
159 menu at the extreme right is the `Help' menu, which should always be
160 available. It provides access to all the XEmacs help facilities
161 available through `C-h', as well as samples of various configuration
162 files like `~/.Xdefaults' and `~/.emacs'. At the extreme left is the
163 `Files' menu, which provides the usual file reading, writing, and
164 printing operations, as well as operations like revert buffer from most
165 recent save. The next menu from the left is the `Edit' menu, which
166 provides the `Undo' operation as well as cutting and pasting,
167 searching, and keyboard macro definition and execution.
169 XEmacs provides a very dynamic environment, and the Lisp language
170 makes for highly flexible applications. The menubar reflects this:
171 many menus (eg, the `Buffers' menu, *note Buffers Menu::) contain items
172 determined by the current state of XEmacs, and most major modes and many
173 minor modes add items to menus and even whole menus to the menubar. In
174 fact, some applications like w3.el and VM provide so many menus that
175 they define a whole new menubar and add a button that allows convenient
176 switching between the "XEmacs menubar" and the "application menubar".
177 Such applications normally bind themselves to a particular frame, and
178 this switching only takes place on frames where such an application is
179 active (ie, the current window of the frame is displaying a buffer in
180 the appropriate major mode).
182 Other menus which are typically available are the `Options',
183 `Tools', `Buffers', `Apps', and `Mule' menus. For detailed
184 descriptions of these menus, *Note Pull-down Menus::. (In 21.2
185 XEmacsen, the `Mule' menu will be moved under `Options'.)
188 File: xemacs.info, Node: Scrollbar Basics, Next: Toolbar Basics, Prev: Menubar Basics, Up: GUI Components
193 XEmacs scrollbars provide the usual interface. Arrow buttons at
194 either end allow for line by line scrolling, including autorepeat.
195 Clicking in the scrollbar itself provides scrolling by windowsfull,
196 depending on which side of the slider is clicked. The slider itself
197 may be dragged for smooth scrolling.
199 The position of the slider corresponds to the position of the window
200 in the buffer. In particular, the length of the slider is proportional
201 to the fraction of the buffer which appears in the window.
203 The presence of the scrollbars is under control of the application or
204 may be customized by the user. By default a vertical scrollbar is
205 present in all windows (except the minibuffer), and there is no
206 horizontal scrollbar.
209 File: xemacs.info, Node: Toolbar Basics, Next: Gutter Basics, Prev: Scrollbar Basics, Up: GUI Components
214 XEmacs has a default toolbar which provides shortcuts for some of the
215 commonly used operations (such as opening files) and applications (such
216 as the Info manual reader). Operations which require arguments will pop
217 up dialogs to get them.
219 The position of the default toolbar can be customized. Also, several
220 toolbars may be present simultaneously (in different positions). VM,
221 for example, provides an application toolbar which shortcuts for
222 mail-specific operations like sending, saving, and deleting messages.
225 File: xemacs.info, Node: Gutter Basics, Next: Inhibiting, Prev: Toolbar Basics, Up: GUI Components
230 Gutters are the most flexible of the GUI components described in this
231 section. In theory, the other GUI components could be implemented by
232 customizing a gutter, but in practice the other components were
233 introduced earlier and have their own special implementations. Gutters
234 tend to be more transient than the other components. Buffer tabs, for
235 example, change every time the selected buffer in the frame changes.
236 And for progress gauges a gutter to contain the gauge is typically
237 created on the fly when needed, then destroyed when the operation whose
238 staus is being displayed is completed.
240 Buffer tabs, having somewhat complex behavior, deserve a closer look.
241 By default, a row of buffer tabs is displayed at the top of every frame.
242 (The tabs could be placed in the bottom gutter, but would be oriented
243 the same way and look rather odd. The horizontal orientation makes
244 putting them in a side gutter utterly impractical.) The buffer
245 displayed in the current window of a frame can be changed to a specific
246 buffer by clicking [mouse-1] on the corresponding tab in the gutter.
248 Each tab contains the name of its buffer. The tab for the current
249 buffer in each frame is displayed in raised relief. The list of buffers
250 chosen for display in the buffer tab row is derived by filtering the
251 buffer list (like the `Buffers' menu). The list starts out with all
252 existing buffers, with more recently selected buffers coming earlier in
255 Then "uninteresting" buffers, like internal XEmacs buffers, the
256 `*Message Log*' buffer, and so on are deleted from the list. Next, the
257 frame's selected buffer is determined. Buffers with a different major
258 mode from the selected buffer are removed from the list. Finally, if
259 the list is too long, the least recently used buffers are deleted from
260 the list. By default up to 6 most recently used buffers with the same
261 mode are displayed on tabs in the gutter.
264 File: xemacs.info, Node: Inhibiting, Next: Customizing, Prev: Gutter Basics, Up: GUI Components
266 Inhibiting Display of GUI Components
267 ====================================
269 Use of GUI facilities is a personal thing. Almost everyone agrees
270 that drawing via keyboard-based "turtle graphics" is acceptable to
271 hardly anyone if a mouse is available, but conversely emulating a
272 keyboard with a screenful of buttons is a painful experience. But
273 between those extremes the complete novice will require a fair amount
274 of time before toolbars and menus become dispensable, but many an
275 "Ancien Haquer" sees them as a complete waste of precious frame space
276 that could be filled with text.
278 Display of all of the GUI components created by XEmacs can be
279 inhibited through the use of Customize. Customize can be accessed
280 through `Options | Customize' in the menu bar, or via `M-x customize'.
281 Then navigate through the Customize tree to `Emacs | Environment'.
282 Scrollbar and toolbar visibility is controlled via the `Display' group,
283 options `Scrollbars visible' and `Toolbar visible' respectively.
284 Gutter visibility is controlled by group `Gutter', option `Visible'.
286 Or they can be controlled directly by `M-x customize-variable', by
287 changing the values of the variables `menubar-visible-p',
288 `scrollbars-visible-p', `toolbar-visible-p', or
289 `gutter-buffers-tab-visible-p' respectively. (The strange form of the
290 last variable is due to the fact that gutters are often used to display
291 transient widgets like progress gauges, which you probably don't want
292 to inhibit. It is more likely that you want to inhibit the default
293 display of the buffers tab widget, which is what that variable controls.
294 This interface is subject to change depending on developer experience
297 Control of frame configuration can controlled automatically
298 according to various parameters such as buffer or frame because these
299 are "specifiers" *Note Specifiers: (lispref)Specifiers. Using these
300 features requires programming in Lisp; Customize is not yet that
301 sophisticated. Also, components that appear in various positions and
302 orientations can have display suppressed according to position. `C-h a
303 visible-p' gives a list of variables which can be customized. E.g., to
304 control the visibility of specifically the left-side toolbar only,
305 customize `left-toolbar-visible-p'.
308 File: xemacs.info, Node: Customizing, Prev: Inhibiting, Up: GUI Components
310 Changing the Position, Orientation, and Appearance of GUI Components
311 ====================================================================
313 #### Not documented yet.
316 File: xemacs.info, Node: XEmacs under X, Next: XEmacs under MS Windows, Prev: GUI Components, Up: Frame
318 Using XEmacs Under the X Window System
319 ======================================
321 XEmacs can be used with the X Window System and a window manager like
322 MWM or TWM. In that case, the X window manager opens, closes, and
323 resizes XEmacs frames. You use the window manager's mouse gestures to
324 perform the operations. Consult your window manager guide or reference
325 manual for information on manipulating X windows.
327 When you are working under X, each X window (that is, each XEmacs
328 frame) has a menu bar for mouse-controlled operations (*note Pull-down
331 XEmacs under X is also a multi-frame XEmacs. You can use the New
332 Frame menu item from the File menu to create a new XEmacs frame in a
333 new X window from the same process. The different frames will share the
334 same buffer list, but you can look at different buffers in the different
337 The function `find-file-other-frame' is just like `find-file', but
338 creates a new frame to display the buffer in first. This is normally
339 bound to `C-x 5 C-f', and is what the Open File, New Frame menu item
342 The function `switch-to-buffer-other-frame' is just like
343 `switch-to-buffer', but creates a new frame to display the buffer in
344 first. This is normally bound to `C-x 5 b'.
346 You can specify a different default frame size other than the one
347 provided. Use the variable `default-frame-alist', which is an alist of
348 default values for frame creation other than the first one. These may
349 be set in your init file, like this:
351 (setq default-frame-alist '((width . 80) (height . 55)))
353 For values specific to the first XEmacs frame, you must use X
354 resources. The variable `x-frame-defaults' takes an alist of default
355 frame creation parameters for X window frames. These override what is
356 specified in `~/.Xdefaults' but are overridden by the arguments to the
357 particular call to `x-create-frame'.
359 When you create a new frame, the variable `create-frame-hook' is
360 called with one argument, the frame just created.
362 If you want to close one or more of the X windows you created using
363 New Frame, use the Delete Frame menu item from the File menu.
365 If you are working with multiple frames, some special information
367 * Two variables, `frame-title-format' and `frame-icon-title-format'
368 determine the title of the frame and the title of the icon that
369 results if you shrink the frame.
371 * The variables `auto-lower-frame' and `auto-raise-frame' position a
372 frame. If true, `auto-lower-frame' lowers a frame to the bottom
373 when it is no longer selected. If true, `auto-raise-frame' raises
374 a frame to the top when it is selected. Under X, most
375 ICCCM-compliant window managers will have options to do this for
376 you, but these variables are provided in case you are using a
377 broken window manager.
379 * There is a new frame/modeline format directive, %S, which expands
380 to the name of the current frame (a frame's name is distinct from
381 its title; the name is used for resource lookup, among other
382 things, and the title is simply what appears above the window.)
385 File: xemacs.info, Node: XEmacs under MS Windows, Prev: XEmacs under X, Up: Frame
387 Using XEmacs Under Microsoft Windows
388 ====================================
390 Use of XEmacs under MS Windows is not separately documented here, but
391 most operations available under the X Window System are also available
394 Where possible, native MS Windows GUI components and capabilities are
398 File: xemacs.info, Node: Keystrokes, Next: Pull-down Menus, Prev: Frame, Up: Top
400 Keystrokes, Key Sequences, and Key Bindings
401 *******************************************
405 * Intro to Keystrokes:: Keystrokes as building blocks of key sequences.
406 * Representing Keystrokes:: Using lists of modifiers and keysyms to
407 represent keystrokes.
408 * Key Sequences:: Combine key strokes into key sequences you can
410 * String Key Sequences:: Available for upward compatibility.
411 * Meta Key:: Using <ESC> to represent <Meta>
412 * Super and Hyper Keys:: Adding modifier keys on certain keyboards.
413 * Character Representation:: How characters appear in Emacs buffers.
414 * Commands:: How commands are bound to key sequences.
417 File: xemacs.info, Node: Intro to Keystrokes, Next: Representing Keystrokes, Prev: Keystrokes, Up: Keystrokes
419 Keystrokes as Building Blocks of Key Sequences
420 ==============================================
422 Earlier versions of Emacs used only the ASCII character set, which
423 defines 128 different character codes. Some of these codes are
424 assigned graphic symbols like `a' and `='; the rest are control
425 characters, such as `Control-a' (also called `C-a'). `C-a' means you
426 hold down the <CTRL> key and then press `a'.
428 Keybindings in XEmacs are not restricted to the set of keystrokes
429 that can be represented in ASCII. XEmacs can tell the difference
430 between, for example, `Control-h', `Control-Shift-h', and `Backspace'.
432 A keystroke is like a piano chord: you get it by simultaneously
433 striking several keys. To be more precise, a keystroke consists of a
434 possibly empty set of modifiers followed by a single "keysym". The set
435 of modifiers is small; it consists of `Control', `Meta', `Super',
436 `Hyper', and `Shift'.
438 The rest of the keys on your keyboard, along with the mouse buttons,
439 make up the set of keysyms. A keysym is usually what is printed on the
440 keys on your keyboard. Here is a table of some of the symbolic names
458 upstroke on the left mouse button
461 upstroke on the middle mouse button
464 upstroke on the right mouse button
469 Use the variable `keyboard-translate-table' only if you are on a
470 dumb tty, as it cannot handle input that cannot be represented as ASCII.
471 The value of this variable is a string used as a translate table for
472 keyboard input or `nil'. Each character is looked up in this string
473 and the contents used instead. If the string is of length `n',
474 character codes `N' and up are untranslated. If you are running Emacs
475 under X, you should do the translations with the `xmodmap' program
479 File: xemacs.info, Node: Representing Keystrokes, Next: Key Sequences, Prev: Intro to Keystrokes, Up: Keystrokes
481 Representing Keystrokes
482 -----------------------
484 XEmacs represents keystrokes as lists. Each list consists of an
485 arbitrary combination of modifiers followed by a single keysym at the
486 end of the list. If the keysym corresponds to an ASCII character, you
487 can use its character code. (A keystroke may also be represented by an
488 event object, as returned by the `read-key-sequence' function;
489 non-programmers need not worry about this.)
491 The following table gives some examples of how to list
492 representations for keystrokes. Each list consists of sets of
493 modifiers followed by keysyms:
496 Pressing <CTRL> and `a' simultaneously.
499 Another way of writing the keystroke `C-a'.
502 Yet another way of writing the keystroke `C-a'.
505 Pressing the <BREAK> key.
507 `(control meta button2up)'
508 Release the middle mouse button, while pressing <CTRL> and <META>.
509 Note: As you define keystrokes, you can use the `shift' key only as a
510 modifier with characters that do not have a second keysym on the same
511 key, such as `backspace' and `tab'. It is an error to define a
512 keystroke using the <shift> modifier with keysyms such as `a' and `='.
513 The correct forms are `A' and `+'.
516 File: xemacs.info, Node: Key Sequences, Next: String Key Sequences, Prev: Representing Keystrokes, Up: Keystrokes
518 Representing Key Sequences
519 --------------------------
521 A "complete key sequence" is a sequence of keystrokes that Emacs
522 understands as a unit. Key sequences are significant because you can
523 bind them to commands. Note that not all sequences of keystrokes are
524 possible key sequences. In particular, the initial keystrokes in a key
525 sequence must make up a "prefix key sequence".
527 Emacs represents a key sequence as a vector of keystrokes. Thus, the
528 schematic representation of a complete key sequence is as follows:
530 [(modifier .. modifier keysym) ... (modifier .. modifier keysym)]
532 Here are some examples of complete key sequences:
534 `[(control c) (control a)]'
535 Typing `C-c' followed by `C-a'
537 `[(control c) (control 65)]'
538 Typing `C-c' followed by `C-a'. (Using the ASCII code for the
541 `[(control c) (break)]'
542 Typing `C-c' followed by the `break' character.
544 A "prefix key sequence" is the beginning of a series of longer
545 sequences that are valid key sequences; adding any single keystroke to
546 the end of a prefix results in a valid key sequence. For example,
547 `control-x' is standardly defined as a prefix. Thus there is a
548 two-character key sequence starting with `C-x' for each valid
549 keystroke, giving numerous possibilities. Here are some samples:
551 * `[(control x) (c)]'
553 * `[(control x) (control c)]'
555 Adding one character to a prefix key does not have to form a complete
556 key. It could make another, longer prefix. For example, `[(control x)
557 (\4)]' is itself a prefix that leads to any number of different
558 three-character keys, including `[(control x) (\4) (f)]', `[(control x)
559 (\4) (b)]' and so on. It would be possible to define one of those
560 three-character sequences as a prefix, creating a series of
561 four-character keys, but we did not define any of them this way.
563 By contrast, the two-character sequence `[(control f) (control k)]'
564 is not a key, because the `(control f)' is a complete key sequence in
565 itself. You cannot give `[(control f (control k)]' an independent
566 meaning as a command while `(control f)' is a complete sequence,
567 because Emacs would understand <C-f C-k> as two commands.
569 The predefined prefix key sequences in Emacs are `(control c)',
570 `(control x)', `(control h)', `[(control x) (\4)]', and `escape'. You
571 can customize Emacs and could make new prefix keys or eliminate the
572 default key sequences. *Note Key Bindings::. For example, if you
573 redefine `(control f)' as a prefix, `[(control f) (control k)]'
574 automatically becomes a valid key sequence (complete, unless you define
575 it as a prefix as well). Conversely, if you remove the prefix
576 definition of `[(control x) (\4)]', `[(control x) (\4) (f)]' (or
577 `[(control x) (\4) ANYTHING]') is no longer a valid key sequence.
579 Note that the above paragraphs uses \4 instead of simply 4, because
580 \4 is the symbol whose name is "4", and plain 4 is the integer 4, which
581 would have been interpreted as the ASCII value. Another way of
582 representing the symbol whose name is "4" is to write ?4, which would be
583 interpreted as the number 52, which is the ASCII code for the character
584 "4". We could therefore actually have written 52 directly, but that is
588 File: xemacs.info, Node: String Key Sequences, Next: Meta Key, Prev: Key Sequences, Up: Keystrokes
593 For backward compatibility, you may also represent a key sequence
594 using strings. For example, we have the following equivalent
598 `[(control c) (control c)]'
604 File: xemacs.info, Node: Meta Key, Next: Super and Hyper Keys, Prev: String Key Sequences, Up: Keystrokes
606 Assignment of the <META> Key
607 ----------------------------
609 Not all terminals have the complete set of modifiers. Terminals
610 that have a <Meta> key allow you to type Meta characters by just
611 holding that key down. To type `Meta-a', hold down <META> and press
612 `a'. On those terminals, the <META> key works like the <SHIFT> key.
613 Such a key is not always labeled <META>, however, as this function is
614 often a special option for a key with some other primary purpose.
616 If there is no <META> key, you can still type Meta characters using
617 two-character sequences starting with <ESC>. To enter `M-a', you could
618 type `<ESC> a'. To enter `C-M-a', you would type `ESC C-a'. <ESC> is
619 allowed on terminals with Meta keys, too, in case you have formed a
622 If you are running under X and do not have a <META> key, it is
623 possible to reconfigure some other key to be a <META> key. *Note Super
626 Emacs believes the terminal has a <META> key if the variable
627 `meta-flag' is non-`nil'. Normally this is set automatically according
628 to the termcap entry for your terminal type. However, sometimes the
629 termcap entry is wrong, and then it is useful to set this variable
630 yourself. *Note Variables::, for how to do this.
632 Note: If you are running under the X window system, the setting of
633 the `meta-flag' variable is irrelevant.
636 File: xemacs.info, Node: Super and Hyper Keys, Next: Character Representation, Prev: Meta Key, Up: Keystrokes
638 Assignment of the <SUPER> and <HYPER> Keys
639 ------------------------------------------
641 Most keyboards do not, by default, have <SUPER> or <HYPER> modifier
642 keys. Under X, you can simulate the <SUPER> or <HYPER> key if you want
643 to bind keys to sequences using `super' and `hyper'. You can use the
644 `xmodmap' program to do this.
646 For example, to turn your <CAPS-LOCK> key into a <SUPER> key, do the
649 Create a file called `~/.xmodmap'. In this file, place the lines
651 remove Lock = Caps_Lock
652 keysym Caps_Lock = Super_L
655 The first line says that the key that is currently called `Caps_Lock'
656 should no longer behave as a "lock" key. The second line says that
657 this should now be called `Super_L' instead. The third line says that
658 the key called `Super_L' should be a modifier key, which produces the
661 To create a <META> or <HYPER> key instead of a <SUPER> key, replace
662 the word `Super' above with `Meta' or `Hyper'.
664 Just after you start up X, execute the command `xmodmap /.xmodmap'.
665 You can add this command to the appropriate initialization file to have
666 the command executed automatically.
668 If you have problems, see the documentation for the `xmodmap'
669 program. The X keyboard model is quite complicated, and explaining it
670 is beyond the scope of this manual. However, we reprint the following
671 description from the X Protocol document for your convenience:
673 A list of keysyms is associated with each keycode. If that list
674 (ignoring trailing `NoSymbol' entries) is a single keysym `K', then the
675 list is treated as if it were the list ```K NoSymbol K NoSymbol'''. If
676 the list (ignoring trailing `NoSymbol' entries) is a pair of keysyms
677 `K1 K2', then the list is treated as if it were the list ```K1 K2 K1
678 K2'''. If the list (ignoring trailing `NoSymbol' entries) is a triple
679 of keysyms `K1 K2 K3', then the list is treated as if it were the list
680 ```K1 K2 K3 NoSymbol'''.
682 The first four elements of the list are split into two groups of
683 keysyms. Group 1 contains the first and second keysyms; Group 2 contains
684 third and fourth keysyms. Within each group, if the second element of
685 the group is NoSymbol, then the group should be treated as if the second
686 element were the same as the first element, except when the first
687 element is an alphabetic keysym `K' for which both lowercase and
688 uppercase forms are defined. In that case, the group should be treated
689 as if the first element were the lowercase form of `K' and the second
690 element were the uppercase form of `K'.
692 The standard rules for obtaining a keysym from a KeyPress event make
693 use of only the Group 1 and Group 2 keysyms; no interpretation of other
694 keysyms in the list is given here. (That is, the last four keysyms are
697 Which group to use is determined by modifier state. Switching between
698 groups is controlled by the keysym named `Mode_switch'. Attach that
699 keysym to some keycode and attach that keycode to any one of the
700 modifiers Mod1 through Mod5. This modifier is called the "group
701 modifier". For any keycode, Group 1 is used when the group modifier is
702 off, and Group 2 is used when the group modifier is on.
704 Within a group, which keysym to use is also determined by modifier
705 state. The first keysym is used when the `Shift' and `Lock' modifiers
706 are off. The second keysym is used when the `Shift' modifier is on, or
707 when the `Lock' modifier is on and the second keysym is uppercase
708 alphabetic, or when the `Lock' modifier is on and is interpreted as
709 `ShiftLock'. Otherwise, when the `Lock' modifier is on and is
710 interpreted as `CapsLock', the state of the `Shift' modifier is applied
711 first to select a keysym, but if that keysym is lower-case alphabetic,
712 then the corresponding upper-case keysym is used instead.
714 In addition to the above information on keysyms, we also provide the
715 following description of modifier mapping from the InterClient
716 Communications Conventions Manual:
718 X11 supports 8 modifier bits, of which 3 are pre-assigned to
719 `Shift', `Lock', and `Control'. Each modifier bit is controlled by the
720 state of a set of keys, and these sets are specified in a table
721 accessed by `GetModifierMapping()' and `SetModifierMapping()'.
723 A client needing to use one of the pre-assigned modifiers should
724 assume that the modifier table has been set up correctly to control
725 these modifiers. The `Lock' modifier should be interpreted as `Caps
726 Lock' or `Shift Lock' according to whether the keycodes in its
727 controlling set include `XK_Caps_Lock' or `XK_Shift_Lock'.
729 Clients should determine the meaning of a modifier bit from the
730 keysyms being used to control it.
732 A client needing to use an extra modifier, for example `Meta',
735 1. Scan the existing modifier mappings.
737 1. If it finds a modifier that contains a keycode whose set of
738 keysyms includes `XK_Meta_L' or `XK_Meta_R', it should use
741 2. If there is no existing modifier controlled by `XK_Meta_L' or
742 `XK_Meta_R', it should select an unused modifier bit (one with
743 an empty controlling set) and:
745 2. If there is a keycode with `XL_Meta_L' in its set of keysyms, add
746 that keycode to the set for the chosen modifier, and then:
748 1. If there is a keycode with `XL_Meta_R' in its set of keysyms,
749 add that keycode to the set for the chosen modifier, and then:
751 2. If the controlling set is still empty, interact with the user
752 to select one or more keys to be `Meta'.
754 3. If there are no unused modifier bits, ask the user to take
757 This means that the `Mod1' modifier does not necessarily mean
758 `Meta', although some applications (such as twm and emacs 18) assume
759 that. Any of the five unassigned modifier bits could mean `Meta'; what
760 matters is that a modifier bit is generated by a keycode which is bound
761 to the keysym `Meta_L' or `Meta_R'.
763 Therefore, if you want to make a <META> key, the right way is to
764 make the keycode in question generate both a `Meta' keysym and some
765 previously-unassigned modifier bit.
768 File: xemacs.info, Node: Character Representation, Next: Commands, Prev: Super and Hyper Keys, Up: Keystrokes
770 Representation of Characters
771 ============================
773 This section briefly discusses how characters are represented in
774 Emacs buffers. *Note Key Sequences::, for information on representing
775 key sequences to create key bindings.
777 ASCII graphic characters in Emacs buffers are displayed with their
778 graphics. <LFD> is the same as a newline character; it is displayed by
779 starting a new line. <TAB> is displayed by moving to the next tab stop
780 column (usually every 8 spaces). Other control characters are
781 displayed as a caret (`^') followed by the non-control version of the
782 character; thus, `C-a' is displayed as `^A'. Non-ASCII characters 128
783 and up are displayed with octal escape sequences; thus, character code
784 243 (octal), also called `M-#' when used as an input character, is
787 The variable `ctl-arrow' may be used to alter this behavior. *Note
791 File: xemacs.info, Node: Commands, Prev: Character Representation, Up: Keystrokes
796 This manual is full of passages that tell you what particular keys
797 do. But Emacs does not assign meanings to keys directly. Instead,
798 Emacs assigns meanings to "functions", and then gives keys their
799 meanings by "binding" them to functions.
801 A function is a Lisp object that can be executed as a program.
802 Usually it is a Lisp symbol that has been given a function definition;
803 every symbol has a name, usually made of a few English words separated
804 by dashes, such as `next-line' or `forward-word'. It also has a
805 "definition", which is a Lisp program. Only some functions can be the
806 bindings of keys; these are functions whose definitions use
807 `interactive' to specify how to call them interactively. Such
808 functions are called "commands", and their names are "command names".
809 More information on this subject will appear in the XEmacs Lisp
812 The bindings between keys and functions are recorded in various
813 tables called "keymaps". *Note Key Bindings::, for more information on
814 key sequences you can bind commands to. *Note Keymaps::, for
815 information on creating keymaps.
817 When we say "`C-n' moves down vertically one line" we are glossing
818 over a distinction that is irrelevant in ordinary use but is vital in
819 understanding how to customize Emacs. The function `next-line' is
820 programmed to move down vertically. `C-n' has this effect because it
821 is bound to that function. If you rebind `C-n' to the function
822 `forward-word' then `C-n' will move forward by words instead.
823 Rebinding keys is a common method of customization.
825 The rest of this manual usually ignores this subtlety to keep things
826 simple. To give the customizer the information needed, we often state
827 the name of the command that really does the work in parentheses after
828 mentioning the key that runs it. For example, we will say that "The
829 command `C-n' (`next-line') moves point vertically down," meaning that
830 `next-line' is a command that moves vertically down and `C-n' is a key
831 that is standardly bound to it.
833 While we are on the subject of information for customization only,
834 it's a good time to tell you about "variables". Often the description
835 of a command will say, "To change this, set the variable `mumble-foo'."
836 A variable is a name used to remember a value. Most of the variables
837 documented in this manual exist just to facilitate customization: some
838 command or other part of Emacs uses the variable and behaves
839 differently depending on its setting. Until you are interested in
840 customizing, you can ignore the information about variables. When you
841 are ready to be interested, read the basic information on variables, and
842 then the information on individual variables will make sense. *Note
846 File: xemacs.info, Node: Pull-down Menus, Next: Entering Emacs, Prev: Keystrokes, Up: Top
848 XEmacs Pull-down Menus
849 ======================
851 If you are running XEmacs under X, a menu bar on top of the Emacs
852 frame provides access to pull-down menus of file, edit, and
853 help-related commands. The menus provide convenient shortcuts and an
854 easy interface for novice users. They do not provide additions to the
855 functionality available via key commands; you can still invoke commands
856 from the keyboard as in previous versions of Emacs.
859 Perform file and buffer-related operations, such as opening and
860 closing files, saving and printing buffers, as well as exiting
864 Perform standard editing operations, such as cutting, copying,
865 pasting, and killing selected text.
868 Access to sub-applications implemented within XEmacs, such as the
869 mail reader, the World Wide Web browser, the spell-checker, and
870 the calendar program.
873 Control various options regarding the way XEmacs works, such as
874 controlling which elements of the frame are visible, selecting the
875 fonts to be used for text, specifying whether searches are
879 Present a menu of buffers for selection as well as the option to
880 display a buffer list.
883 Perform various actions designed to automate software development
884 and similar technical work, such as searching through many files,
885 compiling a program, and comparing or merging two or three files.
888 Access to Emacs Info.
890 There are two ways of selecting an item from a pull-down menu:
892 * Select an item in the menu bar by moving the cursor over it and
893 click the left mouse-button. Then move the cursor over the menu
894 item you want to choose and click left again.
896 * Select an item in the menu bar by moving the cursor over it and
897 click and hold the left mouse-button. With the mouse-button
898 depressed, move the cursor over the menu item you want, then
899 release it to make your selection.
901 If a command in the pull-down menu is not applicable in a given
902 situation, the command is disabled and its name appears faded. You
903 cannot invoke items that are faded. For example, many commands on the
904 Edit menu appear faded until you select text on which they are to
905 operate; after you select a block of text, edit commands are enabled.
906 *Note Mouse Selection::, for information on using the mouse to select
907 text. *Note Using X Selections::, for related information.
909 There are also `M-x' equivalents for each menu item. To find the
910 equivalent for any left-button menu item, do the following:
912 1. Type `C-h k' to get the `Describe Key' prompt.
914 2. Select the menu item and click.
916 Emacs displays the function associated with the menu item in a
917 separate window, usually together with some documentation.
921 * File Menu:: Items on the File menu.
922 * Edit Menu:: Items on the Edit menu.
923 * Apps Menu:: Items on the Apps menu.
924 * Options Menu:: Items on the Options menu.
925 * Buffers Menu:: Information about the Buffers menu.
926 * Tools Menu:: Items on the Tools menu.
927 * Help Menu:: Items on the Help menu.
928 * Menu Customization:: Adding and removing menu items and related
932 File: xemacs.info, Node: File Menu, Next: Edit Menu, Up: Pull-down Menus
937 The File menu bar item contains the items New Frame, Open File...,
938 Save Buffer, Save Buffer As..., Revert Buffer, Print Buffer, Delete
939 Frame, Kill Buffer and Exit Emacs on the pull-down menu. If you select
940 a menu item, Emacs executes the equivalent command.
942 Open File, New Frame...
943 Prompts you for a filename and loads that file into a new buffer
944 in a new Emacs frame, that is, a new X window running under the
945 same Emacs process. You can remove the frame using the Delete
946 Frame menu item. When you remove the last frame, you exit Emacs
947 and are prompted for confirmation.
950 Prompts you for a filename and loads that file into a new buffer.
951 Open File... is equivalent to the Emacs command `find-file' (`C-x
955 Prompts you for a filename and inserts the contents of that file
956 into the current buffer. The file associated with the current
957 buffer is not changed by this command. This is equivalent to the
958 Emacs command `insert-file' (`C-x i').
961 Writes and saves the current Emacs buffer as the latest version of
962 the current visited file. Save Buffer is equivalent to the Emacs
963 command `save-buffer' (`C-x C-s').
966 Writes and saves the current Emacs buffer to the filename you
967 specify. Save Buffer As... is equivalent to the Emacs command
968 `write-file' (`C-x C-w').
971 Restores the last saved version of the file to the current buffer.
972 When you edit a buffer containing a text file, you must save the
973 buffer before your changes become effective. Use Revert Buffer if
974 you do not want to keep the changes you have made in the buffer.
975 Revert Buffer is equivalent to the Emacs command `revert-file'
976 (`M-x revert-buffer').
979 Kills the current buffer, prompting you first if there are unsaved
980 changes. This is roughly equivalent to the Emacs command
981 `kill-buffer' (`C-x k'), except that `kill-buffer' prompts for the
982 name of a buffer to kill.
985 Prints a hardcopy of the current buffer. Equivalent to the Emacs
986 command `print-buffer' (`M-x print-buffer').
989 Creates a new Emacs frame displaying the `*scratch*' buffer. This
990 is like the Open File, New Frame... menu item, except that it does
991 not prompt for or load a file.
994 Allows you to close all but one of the frames created by New Frame.
995 If you created several Emacs frames belonging to the same Emacs
996 process, you can close all but one of them. When you attempt to
997 close the last frame, Emacs informs you that you are attempting to
998 delete the last frame. You have to choose Exit Emacs for that.
1001 Divides the current window on the current frame into two
1002 equal-sized windows, both displaying the same buffer. Equivalent
1003 to the Emacs command `split-window-vertically' (`C-x 2').
1005 Un-split (Keep This)
1006 If the frame is divided into multiple windows, this removes all
1007 windows other than the selected one. Equivalent to the Emacs
1008 command `delete-other-windows' (`C-x 1').
1010 Un-split (Keep Others)
1011 If the frame is divided into multiple windows, this removes the
1012 selected window from the frame, giving the space back to one of the
1013 other windows. Equivalent to the Emacs command `delete-window'
1017 Shuts down (kills) the Emacs process. Equivalent to the Emacs
1018 command `save-buffers-kill-emacs' (`C-x C-c'). Before killing the
1019 Emacs process, the system asks which unsaved buffers to save by
1020 going through the list of all buffers in that Emacs process.
1023 File: xemacs.info, Node: Edit Menu, Next: Apps Menu, Prev: File Menu, Up: Pull-down Menus
1028 The Edit pull-down menu contains the Undo, Cut, Copy, Paste, and
1029 Clear menu items. When you select a menu item, Emacs executes the
1030 equivalent command. Most commands on the Edit menu work on a block of
1031 text, the X selection. They appear faded until you select a block of
1032 text (activate a region) with the mouse. *Note Using X Selections::,
1033 *note Killing::, and *note Yanking:: for more information.
1036 Undoes the previous command. Undo is equivalent to the Emacs
1037 command `undo' (`C-x u').
1040 Removes the selected text block from the current buffer, makes it
1041 the X clipboard selection, and places it in the kill ring. Before
1042 executing this command, you have to select a region using Emacs
1043 region selection commands or with the mouse.
1046 Makes a selected text block the X clipboard selection, and places
1047 it in the kill ring. You can select text using one of the Emacs
1048 region selection commands or by selecting a text region with the
1052 Inserts the current value of the X clipboard selection in the
1053 current buffer. Note that this is not necessarily the same as the
1054 Emacs `yank' command, because the Emacs kill ring and the X
1055 clipboard selection are not the same thing. You can paste in text
1056 you have placed in the clipboard using Copy or Cut. You can also
1057 use Paste to insert text that was pasted into the clipboard from
1061 Removes the selected text block from the current buffer but does
1062 not place it in the kill ring or the X clipboard selection.
1064 Start Macro Recording
1065 After selecting this, Emacs will remember every keystroke you type
1066 until End Macro Recording is selected. This is the same as the
1067 Emacs command `start-kbd-macro' (`C-x (').
1070 Selecting this tells emacs to stop remembering your keystrokes.
1071 This is the same as the Emacs command `end-kbd-macro' (`C-x )').
1074 Selecting this item will cause emacs to re-interpret all of the
1075 keystrokes which were saved between selections of the Start Macro
1076 Recording and End Macro Recording menu items. This is the same as
1077 the Emacs command `call-last-kbd-macro' (`C-x e').
1080 File: xemacs.info, Node: Apps Menu, Next: Options Menu, Prev: Edit Menu, Up: Pull-down Menus
1085 The Apps pull-down menu contains the Read Mail (VM)..., Read Mail
1086 (MH)..., Send Mail..., Usenet News, Browse the Web, Gopher, Spell-Check
1087 Buffer and Emulate VI menu items, and the Calendar and Games sub-menus.
1088 When you select a menu item, Emacs executes the equivalent command.
1089 For some of the menu items, there are sub-menus which you will need to