@node Key bindings, Mail with Gnus, Indentation, Top
@comment  node-name,  next,  previous,  up
@chapter Key bindings

Binding functions to keys is something most new users of Emacs probably
do rather soon.  This subject has also been discussed to quite some
extent in the FAQ, so be sure to look there as well as the chapter on
customizing key bindings in the Emacs manual.

@c ------------------------------------------------------------ 
@section Online help for key bindings
@c ------------------------------------------------------------ 

A key binding is an association between a key (sequence) and a Lisp
command.  You can type @kbd{C-h c @var{x}} to find out which command is
invoked by the key (sequence) @var{x} in the current major mode.  You
can get more help about @var{x} with @kbd{C-h k @var{x}}.  You can type
@kbd{C-h w @var{f} @key{RET}} to find out which key bindings exist for
the given function @var{f}.  Another very useful keybinding is @kbd{C-h
b} which gives you a list of all key bindings currently in effect.

So, maybe @kbd{C-h w} tells you that the function you want already has a
key binding, so you don't need your own?


@c ------------------------------------------------------------ 
@section A warning about own key bindings
@c ------------------------------------------------------------ 

Of course, many people prefer their own key bindings rather than the
standard ones.  Since no two people work alike, it is a Good Thing that
Emacs allows you to choose your own bindings, of course.  However, a few
rules should be obeyed for choosing your own key bindings:

@itemize @bullet
@item
All key bindings of the form @kbd{C-c @var{x}} where @var{x} is any
letter are reserved for the user.  This means that you can count on all
well-behaved packages not to clobber these bindings.  Please note that
bindings for non-letters might be used by major modes.  (AUC-TeX uses
@kbd{C-c ;} for @code{comment-region}, for instance.)  The bindings
@kbd{C-c C-@var{x}} where @var{x} is a letter are reserved for the major
modes.

@item
Most control key combinations (such as @kbd{C-f}) and most meta key
combinations (such as @kbd{M-f}) are already used by Emacs.  A few modes
change the meanings of a few standard key bindings, so it is advisable
to stay away from the standard key bindings in the beginning, until one
gets a feel for the kinds of standard key bindings which are most
useful.

As an example, @kbd{M-a} normally moves backward a sentence, but in C
mode it moves backward a statement.

It might be best if you get into the habit of doing @kbd{C-h b} in the
major modes you use.
@end itemize


@c ------------------------------------------------------------ 
@section Simple key bindings
@c ------------------------------------------------------------ 

Even though the function in question might already have a key binding,
you may prefer your own, because it is more easily reachable on your
keyboard, say.  As an example, the following line makes it so that
@kbd{C-c f} invokes @code{forward-paragraph} in all modes:

@lisp
(global-set-key (kbd "C-c f") 'forward-paragraph)
@end lisp

It is also rather simple to establish key bindings for particular modes,
for instance:

@lisp
(define-key c-mode-map (kbd "C-c <f1>") 'mark-whole-buffer)
@end lisp

Some modes aren't loaded when Emacs starts.  This means that Emacs might
not know about the variable @code{c-mode-map} when it starts.  A simple
solution exists: just load the package before using the variable.  C
mode is defined in the @samp{CC mode} package, so the following line
helps:

@lisp
(require 'cc-mode)
@end lisp

The normal rule is that @var{foo-mode} is defined in the package
@var{foo-mode} or possibly in @var{foo}.  The C-like modes are an
exception, they are defined in the package @code{cc-mode}.  You can type
@kbd{C-h f @var{foo-mode} RET} which will tell you which package the
function comes from.


@c ------------------------------------------------------------ 
@section The syntax for @samp{kbd}
@c ------------------------------------------------------------ 

What kind of string should you use between the double quotes after
@samp{kbd}?  Well, the syntax is not hard to figure out; explaining it
is a bit more difficult.  Well, anyway, here goes:

Basically, the syntax used by @samp{kbd} is the same as the syntax used
by Emacs to describe key bindings (in @kbd{C-h c} and @kbd{C-h b}, among
other places), with one exception.  The exception concerns function key
names, which should be enclosed in angle brackets.  Compare @code{(kbd
"C-c <f1>")} used above: F1 is a function key and thus its name is
enclosed in angle brackets.  By the way, you write @code{C-<f1>} if you
want the @key{Ctrl} key to be pressed while hitting F1.

Why aren't @key{RET} and @key{SPC} enclosed in angle brackets?  Well,
even though it might look as if they are function keys, we're really
talking about ASCII character, here.  A few ASCII characters aren't
printable and thus there are three-letter names for them: @key{RET}
(ASCII 13), @key{DEL} (ASCII 127), @key{LFD} (ASCII 10), @key{SPC}
(ASCII 32), @key{ESC} (ASCII 27) and @key{TAB} (ASCII 9).

In general, you can tell the symbolic name for an ASCII characters from
function key names by the case: function key names are lowercase, ASCII
characters have uppercase names.

Which leads us to the distinction between the ASCII key @key{RET} and
the function key @key{return}: On a serial terminal or using a terminal
emulation like @samp{xterm}, Emacs cannot tell the difference between
the user hitting @kbd{@key{return}} and the user hitting @kbd{C-m}, so
there is only @key{RET}.  Changing the key binding for @key{RET} also
changes it for @kbd{C-m} and vice versa.  But if you are using a
windowing system (such as X11), Emacs does know the difference, and
makes it available to you.  One way to use it is to make @kbd{C-m}
behave different from @kbd{@key{return}}.  Another area where the
difference becomes important is with additional modifiers: @code{(kbd
"C-<return>")} makes perfect sense, but @code{(kbd "C-RET")} is not
meaningful since this would be the same as @code{(kbd "C-C-m")} which in
turn is clearly bogus---you cannot ``double-press'' the control key, so
@kbd{C-RET} is double-plus ungood.

Whee.  More complex than you thought, right?  On the other hand, most of
the time you don't need to know all this---just look at the output from
@kbd{C-h c} and remember to enclose function key names in angle
brackets, and Bob will be your uncle.  But there is one area where the
previous paragraph becomes important, because these keys are so often
used:


@c ------------------------------------------------------------ 
@section The delete and backspace keys
@c ------------------------------------------------------------ 

Let's talk about windowing systems, first.  By default the @key{delete}
and @key{backspace} keys do the same thing: they generate the ASCII
character @key{DEL} which in turn is bound to
@code{backward-delete-char-untabify} in many modes.  But in quite a few
modes, @key{DEL} has a different binding which is normally useful.  For
example, in view mode, @key{DEL} is page-up, which is similar to the
Unix programs @samp{more} and @samp{less}, more or less.

Most people want the @key{backspace} key to delete backwards whereas the
@key{delete} key should delete forward.  But how to do that without
losing the useful @key{DEL} bindings?  Well, there are three potential
key bindings (@key{DEL}, @key{backspace}, @key{delete}) but only two
keys, so what you should do is to choose the right two key bindings, and
@key{DEL} should be among them.  The standard semantic of @key{DEL} is
vaguely ``backward'', so the natural thing to do is to let
@key{backspace} be @key{DEL} as is the default and to change the binding
of @key{delete}: @code{(global-set-key (kbd "<delete>") 'delete-char)}

If you don't like what the @key{backspace} key does, don't change its
binding directly.  Instead, change the binding for @key{DEL}:
@code{(global-set-key (kbd "DEL") 'backward-delete-char)}


@c ------------------------------------------------------------ 
@section Binding @kbd{C-u @var{something}} to a different key
@c ------------------------------------------------------------ 

@kbd{C-u} invokes @code{universal-argument}, which changes the behavior
of quite a few standard functions.  For example, in C mode the key
combination @kbd{C-c C-c} comments out the region.  For
@emph{uncommenting} the region, you have to use @kbd{C-u C-c C-c}.

Thus, one question which comes up a few times is how to make the F9 key
do what @kbd{C-u C-c C-c} does.

Sadly, it is not as simple as one might think.  You have to use some
Lisp for this.  First, let's have a look what @kbd{C-c C-c} does in C
mode, so we type @kbd{C-h k C-c C-c}, which produces the following help:

@example
C-c C-c runs the command comment-region
   which is an interactive compiled Lisp function in `simple'.
(comment-region BEG END &optional ARG)

Comment or uncomment each line in the region.
With just C-u prefix arg, uncomment each line in region.
Numeric prefix arg ARG means use ARG comment characters.
If ARG is negative, delete that many comment characters instead.
Comments are terminated on each line, even for syntax in which
newline does not end the comment.  Blank lines do not get comments.
@end example

Obviously, uncommenting is the same as deleting comment characters, so
the line about ARG being negative is the crucial line, here.  What you
want to do is to write a function which is the same as
@code{comment-region}, except that it passes a negative ARG:

@lisp
(defun uncomment-region (beg end)
  "Like `comment-region' invoked with a C-u prefix arg."
  (interactive "r")
  (comment-region beg end -1))
@end lisp

The part about invoking @code{comment-region} with @code{-1} as argument
should be clear, but the @code{interactive} line looks quite
obfuscated.  Well, you have to use @code{interactive} such that a
function can be invoked via @kbd{M-x} or a key binding.  And the string
@code{"r"} means that the two arguments of this function are the start
and the end of the region, respectively.  See the documentation of the
@code{interactive} function for more alternatives.

You can now bind @code{uncomment-region} to a key, just like any other
command.


@c ------------------------------------------------------------ 
@section Complex key bindings
@c ------------------------------------------------------------ 

There are two ways to bind complex actions to a single key.  One of them
is easy to use but is not easily maintainable, and the other requires a
bit of programming but is more flexible.  The easy way to do it is to
use keyboard macros, the flexible way is to write Lisp functions.

@subsection Complex key bindings with kbd macros

Type @kbd{C-x (} to start recording a kbd macro, use @kbd{C-x )} to stop
recording.  Use @kbd{M-x name-last-kbd-macro RET} to give a name to the
kbd macro just recorded.  Then, use @kbd{M-x insert-kbd-macro RET} to
insert the named kbd macro into your @file{.emacs} file.  The name of
the kbd macro can then be used just like any other command name in a
normal @samp{define-key} or @samp{global-set-key} statement.

@subsection Complex key bindings with Lisp functions

Teaching Lisp is out of the scope of this tutorial, but you may wish to
have a look at the Emacs Lisp Introduction, available from
@url{ftp.gnu.org} and its mirrors, as well as the section in the Emacs
manual on the @file{.emacs} file.

@c ------------------------------------------------------------
@section TODO
@c ------------------------------------------------------------

@itemize @bullet
@item
Add xref to (emacs)Init File.
@end itemize


@c Local Variables:
@c TeX-master: "tutorials.texi"
@c End:
