(Fmodify_frame_parameters): Doc fix.
[emacs.git] / man / commands.texi
blob717a87b419bca29a3ba3df7c49e0f5dab5f0409c
1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002,
3 @c   2003, 2004, 2005, 2006, 2007, 2008  Free Software Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
5 @iftex
6 @chapter Characters, Keys and Commands
8   This chapter explains the character sets used by Emacs for input
9 commands and for the contents of files, and the fundamental concepts of
10 @dfn{keys} and @dfn{commands}, whereby Emacs interprets your keyboard
11 and mouse input.
12 @end iftex
14 @ifnottex
15 @raisesections
16 @end ifnottex
18 @node User Input, Keys, Screen, Top
19 @section Kinds of User Input
20 @cindex input with the keyboard
21 @cindex keyboard input
22 @cindex character set (keyboard)
23 @cindex @acronym{ASCII}
24 @cindex C-
25 @cindex Control
26 @cindex control characters
28   GNU Emacs is designed for use with keyboard commands because that is
29 the most efficient way to edit.  You can do editing with the mouse, as
30 in other editors, and you can give commands with the menu bar and tool
31 bar, and scroll with the scroll bar.  But if you keep on editing that
32 way, you won't get the benefits of Emacs.  Therefore, this manual
33 documents primarily how to edit with the keyboard.  You can force
34 yourself to practice using the keyboard by using the shell command
35 @samp{emacs -nw} to start Emacs, so that the mouse won't work.
37   Emacs uses an extension of the @acronym{ASCII} character set for
38 keyboard input; it also accepts non-character input events including
39 function keys and mouse button actions.
41   @acronym{ASCII} consists of 128 character codes.  Some of these codes are
42 assigned graphic symbols such as @samp{a} and @samp{=}; the rest are
43 control characters, such as @kbd{Control-a} (usually written @kbd{C-a}
44 for short).  @kbd{C-a} gets its name from the fact that you type it by
45 holding down the @key{CTRL} key while pressing @kbd{a}.
47   Some @acronym{ASCII} control characters have special names, and most
48 terminals have special keys you can type them with: for example,
49 @key{RET}, @key{TAB}, @key{DEL} and @key{ESC}.  The space character is
50 usually known as @key{SPC}, even though strictly speaking it is a
51 graphic character that is blank.
53   Emacs extends the @acronym{ASCII} character set with thousands more printing
54 characters (@pxref{International}), additional control characters, and a
55 few more modifiers that can be combined with any character.
57   On @acronym{ASCII} terminals, there are only 32 possible control characters.
58 These are the control variants of letters and @samp{@@[]\^_}.  In
59 addition, the shift key is meaningless with control characters:
60 @kbd{C-a} and @kbd{C-A} are the same character, and Emacs cannot
61 distinguish them.
63   The Emacs character set has room for control variants of all
64 printing characters, and distinguishes @kbd{C-A} from @kbd{C-a}.
65 Graphical terminals make it possible to enter all these characters.
66 For example, @kbd{C--} (that's Control-Minus) and @kbd{C-5} are
67 meaningful Emacs commands on a graphical terminal.
69   Another Emacs character-set extension is additional modifier bits.
70 Only one modifier bit is commonly used; it is called Meta.  Every
71 character has a Meta variant; examples include @kbd{Meta-a} (normally
72 written @kbd{M-a}, for short), @kbd{M-A} (different from @kbd{M-a},
73 but they are normally equivalent in Emacs), @kbd{M-@key{RET}}, and
74 @kbd{M-C-a}.  That last means @kbd{a} with both the @key{CTRL} and
75 @key{META} modifiers.  We usually write it as @kbd{C-M-a} rather than
76 @kbd{M-C-a}, for reasons of tradition.
78 @cindex Meta
79 @cindex M-
80 @cindex @key{ESC} replacing @key{META} key
81   Some terminals have a @key{META} key, and allow you to type Meta
82 characters by holding this key down.  Thus, you can type @kbd{Meta-a}
83 by holding down @key{META} and pressing @kbd{a}.  The @key{META} key
84 works much like the @key{SHIFT} key.  In fact, this key is more often
85 labeled @key{ALT} or @key{EDIT}, instead of @key{META}; on a Sun
86 keyboard, it may have a diamond on it.
88   If there is no @key{META} key, you can still type Meta characters
89 using two-character sequences starting with @key{ESC}.  Thus, you can
90 enter @kbd{M-a} by typing @kbd{@key{ESC} a}.  You can enter
91 @kbd{C-M-a} by typing @kbd{@key{ESC} C-a}.  Unlike @key{META}, which
92 modifies other characters, @key{ESC} is a separate character.  You
93 don't hold down @key{ESC} while typing the next character; instead,
94 you press it and release it, then you enter the next character.
95 @key{ESC} is allowed on terminals with @key{META} keys, too, in case
96 you have formed a habit of using it.
98   Emacs defines several other modifier keys that can be applied to any
99 input character.  These are called @key{SUPER}, @key{HYPER} and
100 @key{ALT}.  We write @samp{s-}, @samp{H-} and @samp{A-} to say that a
101 character uses these modifiers.  Thus, @kbd{s-H-C-x} is short for
102 @kbd{Super-Hyper-Control-x}.  Not all graphical terminals actually
103 provide keys for these modifier flags---in fact, many terminals have a
104 key labeled @key{ALT} which is really a @key{META} key.  The standard
105 key bindings of Emacs do not include any characters with these
106 modifiers.  But you can assign them meanings of your own by
107 customizing Emacs.
109   If your keyboard lacks one of these modifier keys, you can enter it
110 using @kbd{C-x @@}: @kbd{C-x @@ h} adds the ``hyper'' flag to the next
111 character, @kbd{C-x @@ s} adds the ``super'' flag, and @kbd{C-x @@ a}
112 adds the ``alt'' flag.  For instance, @kbd{C-x @@ h C-a} is a way to
113 enter @kbd{Hyper-Control-a}.  (Unfortunately there is no way to add
114 two modifiers by using @kbd{C-x @@} twice for the same character,
115 because the first one goes to work on the @kbd{C-x}.)
117   Keyboard input includes keyboard keys that are not characters at
118 all, such as function keys and arrow keys.  Mouse buttons are also not
119 characters.  However, you can modify these events with the modifier
120 keys @key{CTRL}, @key{META}, @key{SUPER}, @key{HYPER} and @key{ALT},
121 just like keyboard characters.
123 @cindex input event
124   Input characters and non-character inputs are collectively called
125 @dfn{input events}.  @xref{Input Events,,, elisp, The Emacs Lisp
126 Reference Manual}, for the full Lisp-level details.  If you are not
127 doing Lisp programming, but simply want to redefine the meaning of
128 some characters or non-character events, see @ref{Customization}.
130   @acronym{ASCII} terminals cannot really send anything to the computer except
131 @acronym{ASCII} characters.  These terminals use a sequence of characters to
132 represent each function key.  But that is invisible to the Emacs user,
133 because the keyboard input routines catch these special sequences
134 and convert them to function key events before any other part of Emacs
135 gets to see them.
137 @cindex keys stolen by window manager
138 @cindex window manager, keys stolen by
139   On graphical displays, the window manager is likely to block the
140 character @kbd{Meta-@key{TAB}} before Emacs can see it.  It may also
141 block @kbd{Meta-@key{SPC}}, @kbd{C-M-d} and @kbd{C-M-l}.  If you have
142 these problems, we recommend that you customize your window manager to
143 turn off those commands, or put them on key combinations that Emacs
144 does not use.
146 @node Keys, Commands, User Input, Top
147 @section Keys
149 @cindex key sequence
150 @cindex key
151   A @dfn{key sequence} (@dfn{key}, for short) is a sequence of input
152 events that is meaningful as a unit---a ``single command.''  Some
153 Emacs command sequences are invoked by just one character or one
154 event; for example, just @kbd{C-f} moves forward one character in the
155 buffer.  But Emacs also has commands that take two or more events to
156 invoke.
158 @cindex complete key
159 @cindex prefix key
160   If a sequence of events is enough to invoke a command, it is a
161 @dfn{complete key}.  Examples of complete keys include @kbd{C-a},
162 @kbd{X}, @key{RET}, @key{NEXT} (a function key), @key{DOWN} (an arrow
163 key), @kbd{C-x C-f}, and @kbd{C-x 4 C-f}.  If it isn't long enough to be
164 complete, we call it a @dfn{prefix key}.  The above examples show that
165 @kbd{C-x} and @kbd{C-x 4} are prefix keys.  Every key sequence is either
166 a complete key or a prefix key.
168   Most single characters constitute complete keys in the standard Emacs
169 command bindings.  A few of them are prefix keys.  A prefix key combines
170 with the following input event to make a longer key sequence, which may
171 itself be complete or a prefix.  For example, @kbd{C-x} is a prefix key,
172 so @kbd{C-x} and the next input event combine to make a two-event
173 key sequence.  Most of these key sequences are complete keys, including
174 @kbd{C-x C-f} and @kbd{C-x b}.  A few, such as @kbd{C-x 4} and @kbd{C-x
175 r}, are themselves prefix keys that lead to three-event key
176 sequences.  There's no limit to the length of a key sequence, but in
177 practice people rarely use sequences longer than four events.
179   You can't add input events onto a complete key.  For example, the
180 two-event sequence @kbd{C-f C-k} is not a key, because the @kbd{C-f}
181 is a complete key in itself.  It's impossible to give @kbd{C-f C-k} an
182 independent meaning as a command.  @kbd{C-f C-k} is two key sequences,
183 not one.@refill
185   All told, the prefix keys in Emacs are @kbd{C-c}, @kbd{C-h},
186 @kbd{C-x}, @kbd{C-x @key{RET}}, @kbd{C-x @@}, @kbd{C-x a}, @kbd{C-x
187 n}, @w{@kbd{C-x r}}, @kbd{C-x v}, @kbd{C-x 4}, @kbd{C-x 5}, @kbd{C-x
188 6}, @key{ESC}, @kbd{M-g}, and @kbd{M-o}.  (@key{F1} and @key{F2} are
189 aliases for @kbd{C-h} and @kbd{C-x 6}.)  This list is not cast in stone;
190 it describes the standard key bindings.  If you customize Emacs, you can make
191 new prefix keys, or eliminate some of the standard ones (not
192 recommended for most users).  @xref{Key Bindings}.
194   If you make or eliminate prefix keys, that changes the set of
195 possible key sequences.  For example, if you redefine @kbd{C-f} as a
196 prefix, @kbd{C-f C-k} automatically becomes a key (complete, unless
197 you define that too as a prefix).  Conversely, if you remove the
198 prefix definition of @kbd{C-x 4}, then @kbd{C-x 4 f} and @kbd{C-x 4
199 @var{anything}} are no longer keys.
201   Typing the help character (@kbd{C-h} or @key{F1}) after a prefix key
202 displays a list of the commands starting with that prefix.  There are
203 a few prefix keys after which @kbd{C-h} does not work---for historical
204 reasons, they define other meanings for @kbd{C-h} which are painful to
205 change.  @key{F1} works after all prefix keys.
207 @node Commands, Text Characters, Keys, Top
208 @section Keys and Commands
210 @cindex binding
211 @cindex command
212 @cindex function definition
213   This manual is full of passages that tell you what particular keys
214 do.  But Emacs does not assign meanings to keys directly.  Instead,
215 Emacs assigns meanings to named @dfn{commands}, and then gives keys
216 their meanings by @dfn{binding} them to commands.
218   Every command has a name chosen by a programmer.  The name is
219 usually made of a few English words separated by dashes; for example,
220 @code{next-line} or @code{forward-word}.  A command also has a
221 @dfn{function definition} which is a Lisp program; this is how the
222 command does its work.  In Emacs Lisp, a command is a Lisp function with
223 special options to read arguments and for interactive use.  For more
224 information on commands and functions, see @ref{What Is a Function,,
225 What Is a Function, elisp, The Emacs Lisp Reference Manual}.  (The
226 definition here is simplified slightly.)
228   The bindings between keys and commands are recorded in tables called
229 @dfn{keymaps}.  @xref{Keymaps}.
231   When we say that ``@kbd{C-n} moves down vertically one line'' we are
232 glossing over a subtle distinction that is irrelevant in ordinary use,
233 but vital for Emacs customization.  The command @code{next-line} does
234 a vertical move downward.  @kbd{C-n} has this effect @emph{because} it
235 is bound to @code{next-line}.  If you rebind @kbd{C-n} to the command
236 @code{forward-word}, @kbd{C-n} will move forward one word instead.
237 Rebinding keys is an important method of customization.
239   In the rest of this manual, we usually ignore this distinction to
240 keep things simple.  We will often speak of keys like @kbd{C-n} as
241 commands, even though strictly speaking the key is bound to a command.
242 Usually we state the name of the command which really does the work in
243 parentheses after mentioning the key that runs it.  For example, we
244 will say that ``The command @kbd{C-n} (@code{next-line}) moves point
245 vertically down,'' meaning that the command @code{next-line} moves
246 vertically down, and the key @kbd{C-n} is normally bound to it.
248   Since we are discussing customization, we should tell you about
249 @dfn{variables}.  Often the description of a command will say, ``To
250 change this, set the variable @code{mumble-foo}.''  A variable is a
251 name used to store a value.  Most of the variables documented in this
252 manual are meant for customization: some command or other part of
253 Emacs examines the variable and behaves differently according to the
254 value that you set.  You can ignore the information about variables
255 until you are interested in customizing them.  Then read the basic
256 information on variables (@pxref{Variables}) and the information about
257 specific variables will make sense.
259 @node Text Characters, Entering Emacs, Commands, Top
260 @section Character Set for Text
261 @cindex characters (in text)
263   Text in Emacs buffers is a sequence of characters.  In the simplest
264 case, these are @acronym{ASCII} characters, each stored in one 8-bit
265 byte.  Both @acronym{ASCII} control characters (octal codes 000
266 through 037, and 0177) and @acronym{ASCII} printing characters (codes
267 040 through 0176) are allowed.  The other modifier flags used in
268 keyboard input, such as Meta, are not allowed in buffers.
270   Non-@acronym{ASCII} printing characters can also appear in buffers,
271 when multibyte characters are enabled.  They have character codes
272 starting at 256, octal 0400, and each one is represented as a sequence
273 of two or more bytes.  @xref{International}.  Single-byte characters
274 with codes 128 through 255 can also appear in multibyte buffers.
275 However, non-@acronym{ASCII} control characters cannot appear in a
276 buffer.
278   Some @acronym{ASCII} control characters serve special purposes in text, and have
279 special names.  For example, the newline character (octal code 012) is
280 used in the buffer to end a line, and the tab character (octal code 011)
281 is used for indenting to the next tab stop column (normally every 8
282 columns).  @xref{Text Display}.
284   If you disable multibyte characters, then you can use only one
285 alphabet of non-@acronym{ASCII} characters, which all fit in one byte.
286 They use octal codes 0200 through 0377.  @xref{Unibyte Mode}.
288 @ifnottex
289 @lowersections
290 @end ifnottex
292 @ignore
293    arch-tag: 9be43eef-d1f4-4d03-a916-c741ea713a45
294 @end ignore