27.4.2.2 Changing Key Bindings Programmatically

You can use the functions global-set-key and define-key to rebind keys under program control.

(global-set-key keys cmd)

Defines keys globally to run cmd.

(define-key keymap keys def)

Defines keys to run def in the keymap keymap.

keymap is a keymap object.

keys is the sequence of keystrokes to bind.

def is anything that can be a key’s definition:

• nil, meaning key is undefined in this keymap
• A command, that is, a Lisp function suitable for interactive calling
• A string or key sequence vector, which is treated as a keyboard macro
• A keymap to define a prefix key
• A symbol so that when the key is looked up, the symbol stands for its function definition, which should at that time be one of the above, or another symbol whose function definition is used, and so on
• A cons, (string . defn), meaning that defn is the definition (defn should be a valid definition in its own right)
• A cons, (keymap . char), meaning use the definition of char in map keymap

For backward compatibility, SXEmacs allows you to specify key sequences as strings. However, the preferred method is to use the representations of key sequences as vectors of keystrokes. See Keystrokes, for more information about the rules for constructing key sequences.

Emacs allows you to abbreviate representations for key sequences in most places where there is no ambiguity. Here are some rules for abbreviation:

• The keysym by itself is equivalent to a list of just that keysym, i.e., f1 is equivalent to (f1).
• A keystroke by itself is equivalent to a vector containing just that keystroke, i.e., (control a) is equivalent to [(control a)].
• You can use ASCII codes for keysyms that have them. i.e., 65 is equivalent to A. (This is not so much an abbreviation as an alternate representation.)

Here are some examples of programmatically binding keys:

;;;  Bind my-command to f1
(global-set-key 'f1 'my-command)

;;;  Bind my-command to Shift-f1
(global-set-key '(shift f1) 'my-command)

;;; Bind my-command to C-c Shift-f1
(global-set-key '[(control c) (shift f1)] 'my-command)

;;; Bind my-command to the middle mouse button.
(global-set-key 'button2 'my-command)

;;; Bind my-command to META CTL Right Mouse Button
;;; in the keymap that is in force when you are running dired.
(define-key dired-mode-map '(meta control button3) 'my-command)