Emacs Lisp: Create Keymap for Major Mode

By Xah Lee. Date: . Last updated: .

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 xx-mode-cmd1 ()
  "do something"
  (interactive)
  (message "cmd1 called"))

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

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

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

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

(defvar xx-mode-map nil "Keymap for `xx-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 xx-mode-map (make-sparse-keymap))
  (define-key xx-mode-map (kbd "C-c C-a") 'xx-mode-cmd1)
  (define-key xx-mode-map (kbd "C-c C-b") 'xx-mode-cmd2)
  (define-key xx-mode-map (kbd "C-c C-c") 'xx-mode-cmd3)
  (define-key xx-mode-map (kbd "C-c C-d") 'xx-mode-cmd4)
  ;; by convention, major mode's keys should begin with the form C-c C-‹key›
  )

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

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

\\{xx-mode-map}"

  ;; actually no need
  (use-local-map xx-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. Alt+x xx-mode to activate it.
  4. Then, Alt+x describe-mode.

You'll see this:

emacs sample-describe-mode

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 xx-mode-map nil "keymap for `xx-mode-mode'")

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

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

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

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

;; and more

Keybinding Syntax

For key syntax and related question about keys, see:

Emacs: Define Keybinding

Reference