Elisp: How to 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.

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

;; sample major mode with its own keymap

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

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

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

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

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

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

(defvar my-mode-map nil "Keymap for `my-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 my-mode-map (make-sparse-keymap))

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

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

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

  (define-key my-mode-map (kbd "C-c C-d") 'my-mode-cmd4)

  ;; by convention, major mode's keys should begin with the form C-c C-‹key›
  ;; by convention, keys of the form C-c ‹letter› are reserved for user. don't define such keys in your major mode
  )

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

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

\\{my-mode-map}"

  ;; actually no need
  (use-local-map my-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 my-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 my-mode-map nil "keymap for `my-mode-mode'")

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

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

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

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

;; and more

Keybinding Syntax

For key syntax and related question about keys, see:

Emacs: How to Define Keys

See also:

Writing Major Mode

  1. How to Write a Emacs Major Mode for Syntax Coloring
  2. Elisp: html6-mode
  3. Elisp: Font Lock Mode Basics
  4. Elisp: How to Define Face
  5. Elisp: How to Color Comment in Major Mode
  6. Elisp: How to Write Comment Command in Major Mode
  7. Elisp: How to Write Your Own Comment Command from Scratch
  8. Elisp: How to Write Keyword Completion Command
  9. Elisp: How to Create Keymap for Major Mode
  10. Elisp: Create Abbrev and Templates for Major Mode
  11. Elisp: Text Properties
  12. Elisp: Overlay Highlighting
  13. Emacs: Lookup Google, Dictionary, Documentation
  14. Elisp: Syntax Table Tutorial

  1. Elisp: How to Name Your Major Mode
  2. Elisp: What's “feature”?
  3. Elisp: require, load, load-file, autoload, feature, Explained

Syntax Table

  1. Elisp: Syntax Table Tutorial
  2. Elisp: How to Find Syntax of a Character?
  3. Elisp: How to Modify Syntax Table Temporarily
  4. Elisp: How to Determine If Cursor is Inside String or Comment
  5. Elisp: Regex Patterns and Syntax Table
  6. Elisp: Find Matching Bracket Character
Liket it? Put $5 at patreon. Or Buy Xah Emacs Tutorial. Thanks.