Emacs Lisp: How to Create Keymap for Major Mode

This page shows you how to define keys in your own major mode.

Each major mode typically define many of its own keys for calling the major mode's commands. (by convention, major mode's keys start with Ctrl+c Ctrl+key )

Here's how to define the keys for major mode:

;; sample major mode with its own keymap

;; ----------------------------------------
;; commands

(defun xyz-mode-cmd1 ()
  "do something"
  (interactive)
  (message "cmd1 called"))

(defun xyz-mode-cmd2 ()
  "do something"
  (interactive)
  (message "cmd2 called"))

(defun xyz-mode-cmd3 ()
  "do something"
  (interactive)
  (message "cmd3 called"))

(defun xyz-mode-cmd4 ()
  "do something"
  (interactive)
  (message "cmd4 called"))

;; ----------------------------------------
;; keybinding

(defvar xyz-mode-map nil "Keymap for `xyz-mode-mode'")
;; make sure that the var name is your mode name followed by -map. That way, define-derived-mode will automatically set it as local map

;; also, by convention, variable names for keymap should end in -map

(progn
  (setq xyz-mode-map (make-sparse-keymap))
  (define-key xyz-mode-map (kbd "C-c C-a") 'xyz-mode-cmd1)
  (define-key xyz-mode-map (kbd "C-c C-b") 'xyz-mode-cmd2)
  (define-key xyz-mode-map (kbd "C-c C-c") 'xyz-mode-cmd3)
  (define-key xyz-mode-map (kbd "C-c C-d") 'xyz-mode-cmd4)
  ;; by convention, major mode's keys should begin with the form C-c C-‹key›
  )

;; ----------------------------------------
;; define the mode

(define-derived-mode xyz-mode prog-mode "my"
  "xyz-mode is a major mode for editing language my.

\\{xyz-mode-map}"

  ;; actually no need
  (use-local-map xyz-mode-map) ; if your keymap name is modename follow by -map, then this line is not necessary, because define-derived-mode will find it and set it for you

  )

1. Copy and paste the above code into a buffer.
2. Then, Alt+x eval-buffer.
3. Then, open a new buffer. Call xyz-mode to activate it.
4. Then, Alt+x describe-mode.

You'll see this:

You can also press one of the keys to see the command being called.

How Does it Work?

To have keybinding for a major mode, the 2 essential steps are:

1. Define a keymap.
2. Use (use-local-map keymap_var_name) in your mode body, so that when the command is called, it sets a local keymap in user's current buffer. (this step may be implicitly done for you by define-derived-mode).

The typical way to define a keymap is this:

(defvar xyz-mode-map nil "keymap for `xyz-mode-mode'")

(setq xyz-mode-map (make-sparse-keymap))

(define-key xyz-mode-map (kbd "C-c C-a") 'xyz-mode-cmd1)

(define-key xyz-mode-map (kbd "C-c C-b") 'xyz-mode-cmd2)

(define-key xyz-mode-map (kbd "C-c C-c") 'xyz-mode-cmd3)

;; and more

Keybinding Syntax

For key syntax and related question about keys, see:

Emacs: How to Define Keybinding

See also:

• (info "(elisp) Keymaps")
• (info "(elisp) Key Binding Conventions")

• 
  Buy Xah Emacs Tutorial