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.

Online help for key bindings
============================

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

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

A warning about own key bindings
================================

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:

  * All key bindings of the form C-c X where 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 C-c ; for comment-region, for instance.)  The bindings C-c C-X where X is a letter are reserved for the major modes.

  * Most control key combinations (such as C-f) and most meta key combinations (such as 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, 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 C-h b in the major modes you use.

Simple key bindings
===================

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 C-c f invokes forward-paragraph in all modes:

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

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

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

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

     (require 'cc-mode)

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

The syntax for kbd
==================

What kind of string should you use between the double quotes after 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 kbd is the same as the syntax used by Emacs to describe key bindings (in C-h c and C-h b, among other places), with one exception.  The exception concerns function key names, which should be enclosed in angle brackets.  Compare (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 C-<f1> if you want the Ctrl key to be pressed while hitting F1.

Why aren't RET and 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: RET (ASCII 13), DEL (ASCII 127), LFD (ASCII 10), SPC (ASCII 32), ESC (ASCII 27) and 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 RET and the function key return: On a serial terminal or using a terminal emulation like xterm, Emacs cannot tell the difference between the user hitting return and the user hitting C-m, so there is only RET.  Changing the key binding for RET also changes it for 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 C-m behave different from return.  Another area where the difference becomes important is with additional modifiers: (kbd "C-<return>") makes perfect sense, but (kbd "C-RET") is not meaningful since this would be the same as (kbd "C-C-m") which in turn is clearly bogus---you cannot ``double-press'' the control key, so 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 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:

The delete and backspace keys
=============================

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

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

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

Binding C-u SOMETHING to a different key
========================================

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

Thus, one question which comes up a few times is how to make the F9 key do what 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 C-c C-c does in C mode, so we type C-h k C-c C-c, which produces the following help:

     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.

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 comment-region, except that it passes a negative ARG:

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

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

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

Complex key bindings
====================

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.

Complex key bindings with kbd macros
------------------------------------

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

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 ftp.gnu.org and its mirrors, as well as the section in the Emacs manual on the .emacs file.

TODO
====

  * Add xref to (emacs)Init File.