Function: tutorial--describe-nonstandard-key

tutorial--describe-nonstandard-key is a byte-compiled function defined in tutorial.el.gz.

Signature

(tutorial--describe-nonstandard-key VALUE)

Documentation

Give more information about a changed key binding.

This is used in help-with-tutorial. The information includes the key sequence that no longer has a default binding, the default binding and the current binding. It also tells in what keymap the new binding has been done and how to access the function in the default binding from the keyboard.

For cua-mode(var)/cua-mode(fun) key bindings that try to combine CUA key bindings with default Emacs bindings information about this is shown.

VALUE should have either of these formats:

  (cua-mode)
  (current-binding KEY-FUN DEF-FUN KEY WHERE)

Where
  KEY is a key sequence whose standard binding has been changed
  KEY-FUN is the actual binding for KEY
  DEF-FUN is the standard binding of KEY
  WHERE is a text describing the key sequences to which DEF-FUN is
              bound now (or, if it is remapped, a key sequence
              for the function it is remapped to)

Source Code

;; Defined in /usr/src/emacs/lisp/tutorial.el.gz
(defun tutorial--describe-nonstandard-key (value)
  "Give more information about a changed key binding.
This is used in `help-with-tutorial'.  The information includes
the key sequence that no longer has a default binding, the
default binding and the current binding.  It also tells in what
keymap the new binding has been done and how to access the
function in the default binding from the keyboard.

For `cua-mode' key bindings that try to combine CUA key bindings
with default Emacs bindings information about this is shown.

VALUE should have either of these formats:

  (cua-mode)
  (current-binding KEY-FUN DEF-FUN KEY WHERE)

Where
  KEY         is a key sequence whose standard binding has been changed
  KEY-FUN     is the actual binding for KEY
  DEF-FUN     is the standard binding of KEY
  WHERE       is a text describing the key sequences to which DEF-FUN is
              bound now (or, if it is remapped, a key sequence
              for the function it is remapped to)"
  (with-output-to-temp-buffer (help-buffer)
    (help-setup-xref (list #'tutorial--describe-nonstandard-key value)
                     (called-interactively-p 'interactive))
    (with-current-buffer (help-buffer)
      (insert
       "Your Emacs customizations override the default binding for this key:"
       "\n\n")
      (let ((inhibit-read-only t))
        (cond
         ((eq (car value) 'cua-mode)
          (insert
           "CUA mode is enabled.

When CUA mode is enabled, you can use C-z, C-x, C-c, and C-v to
undo, cut, copy, and paste in addition to the normal Emacs
bindings.  The C-x and C-c keys only do cut and copy when the
region is active, so in most cases, they do not conflict with the
normal function of these prefix keys.

If you really need to perform a command which starts with one of
the prefix keys even when the region is active, you have three
options:
- press the prefix key twice very quickly (within 0.2 seconds),
- press the prefix key and the following key within 0.2 seconds, or
- use the SHIFT key with the prefix key, i.e. C-S-x or C-S-c."))
         ((eq (car value) 'current-binding)
          (let ((cb    (nth 1 value))
                (db    (nth 2 value))
                (key   (nth 3 value))
                (where (nth 4 value))
                map
                (maps (current-active-maps))
                mapsym)
            ;; Look at the currently active keymaps and try to find
            ;; first the keymap where the current binding occurs:
            (while maps
              (let* ((m (car maps))
                     (mb (lookup-key m key t)))
                (setq maps (cdr maps))
                (when (eq mb cb)
                  (setq map m)
                  (setq maps nil))))
            ;; Now, if a keymap was found we must found the symbol
            ;; name for it to display to the user.  This can not
            ;; always be found since all keymaps does not have a
            ;; symbol pointing to them, but here they should have
            ;; that:
            (when map
              (mapatoms (lambda (s)
                          (and
                           ;; If not already found
                           (not mapsym)
                           ;; and if s is a keymap
                           (and (boundp s)
                                (keymapp (symbol-value s)))
                           ;; and not the local symbol map
                           (not (eq s 'map))
                           ;; and the value of s is map
                           (eq map (symbol-value s))
                           ;; then save this value in mapsym
                           (setq mapsym s)))))
            (insert
             (format-message
              "The default Emacs binding for the key %s is the command `%s'.  "
              (key-description key)
              db))
            (insert "However, your customizations have "
                    (if cb
                        (format-message "rebound it to the command `%s'" cb)
                      "unbound it"))
            (insert ".")
            (when mapsym
              (insert "  (For the more advanced user:"
                      (format-message
                       " This binding is in the keymap `%s'.)" mapsym)))
            (if (string= where "")
                (unless (keymapp db)
                  (insert "\n\nYou can use M-x "
                          (format "%s" db)
                          " RET instead."))
              (insert "\n\nWith your current key bindings"
                      " you can use "
                      (if (string-match-p "^the .*menus?$" where)
                          ""
                        "the key")
                      where
                      (format-message " to get the function `%s'." db))))
          (fill-region (point-min) (point)))))
      (help-print-return-message))))