Function: help--read-key-sequence

help--read-key-sequence is a byte-compiled function defined in help.el.gz.

Signature

(help--read-key-sequence &optional NO-MOUSE-MOVEMENT)

Documentation

Read a key sequence from the user.

Usually reads a single key sequence, except when that sequence might hide another one (e.g. a down event, where the user is interested in getting info about the up event, or a click event, where the user wants to get info about the double click). Return a list of elements of the form (SEQ . RAW-SEQ), where SEQ is a key sequence, and RAW-SEQ is its untranslated form. If NO-MOUSE-MOVEMENT is non-nil, ignore key sequences starting with mouse-movement events.

Source Code

;; Defined in /usr/src/emacs/lisp/help.el.gz
(defun help--read-key-sequence (&optional no-mouse-movement)
  "Read a key sequence from the user.
Usually reads a single key sequence, except when that sequence might
hide another one (e.g. a down event, where the user is interested
in getting info about the up event, or a click event, where the user
wants to get info about the double click).
Return a list of elements of the form (SEQ . RAW-SEQ), where SEQ is a key
sequence, and RAW-SEQ is its untranslated form.
If NO-MOUSE-MOVEMENT is non-nil, ignore key sequences starting
with `mouse-movement' events."
  (let ((enable-disabled-menus-and-buttons t)
        (cursor-in-echo-area t)
        (side-event nil)
        ;; Showing the list of key sequences makes no sense when they
        ;; asked about a key sequence.
        (echo-keystrokes-help nil)
        saved-yank-menu)
    (unwind-protect
        (let (last-modifiers key-list)
          ;; If yank-menu is empty, populate it temporarily, so that
          ;; "Select and Paste" menu can generate a complete event.
          (when (null (cdr yank-menu))
            (setq saved-yank-menu (copy-sequence yank-menu))
            (menu-bar-update-yank-menu "(any string)" nil))
          (while
              ;; Read at least one key-sequence.
              (or (null key-list)
                  ;; After a down event, also read the (presumably) following
                  ;; up-event.
                  (memq 'down last-modifiers)
                  ;; After a click, see if a double click is on the way.
                  (and (memq 'click last-modifiers)
                       (not (sit-for (/ (mouse-double-click-time) 1000.0) t))))
            (let* ((prompt
                    (propertize "\
Describe the following key, mouse click, or menu item: "
                                'face 'minibuffer-prompt))
                   (seq (read-key-sequence prompt
                                           nil nil 'can-return-switch-frame))
                   (raw-seq (this-single-command-raw-keys))
                   (keyn (when (> (length seq) 0)
                           (aref seq (1- (length seq)))))
                   (base (event-basic-type keyn))
                   (modifiers (event-modifiers keyn)))
              (cond
               ((zerop (length seq)))   ;FIXME: Can this happen?
               ((and no-mouse-movement (eq base 'mouse-movement)) nil)
               ((memq base '(mouse-movement switch-frame select-window))
                ;; Mostly ignore these events since it's sometimes difficult to
                ;; generate the event you care about without also generating
                ;; these side-events along the way.
                (setq side-event (cons seq raw-seq)))
               ((eq base 'help-echo) nil)
               (t
                (setq last-modifiers modifiers)
                (push (cons seq raw-seq) key-list)))))
          (if side-event
              (cons side-event (nreverse key-list))
            (nreverse key-list)))
      ;; Put yank-menu back as it was, if we changed it.
      (when saved-yank-menu
        (setq yank-menu (copy-sequence saved-yank-menu))
        (fset 'yank-menu (cons 'keymap yank-menu))))))