From: "Drew Adams" <drew.adams@oracle.com>
To: <emacs-devel@gnu.org>
Cc: "Kim F. Storm" <storm@cua.dk>
Subject: RE: keypad-*-setup
Date: Wed, 12 Sep 2007 10:22:23 -0700 [thread overview]
Message-ID: <BNELLINCGFJLDJIKDGACCEJBCCAA.drew.adams@oracle.com> (raw)
In-Reply-To: <87fy1k3m2s.fsf@kfs-lx.testafd.dk>
[-- Attachment #1: Type: text/plain, Size: 1807 bytes --]
I've tried to improve the doc for this feature (library keypad.el) - both
the Emacs manual and the doc strings and Customize tags.
I have not tried to mess with texinfo. I will make any changes people think
are needed to the attached doc and code files, and I will then pass the
result on to someone else to modify the texinfo and install in CVS.
Attached is a patch for keypad.el. I did not change the behavior of the
code; I made only cosmetic changes, e.g. doc and Commentary.
Attached is a text file for the Emacs manual. I propose these changes:
- Node "Function Keys": Remove all text starting with "Many keyboards have a
"numeric keypad...". Put that topic in its own node (see next).
- New node, "Numeric Keypad", child of "Key Bindings", Next node after
"Function Keys". See attached file keypad-doc.txt for the text.
Some questions:
1. A nil ("No change (keep existing bindings)") value for the setup options
seems to be a no-op. What is its use; what does it do (change)? If it does
nothing, then perhaps we should remove it (and modify the doc accordingly).
Here is the :set code for `defcustom' - it seems to do nothing if `value' is
nil. Am I reading this wrong?
:set (lambda (symbol value) (when value (keypad-setup value nil nil value)))
2. Do we really need a separate `numeric' choice? Why not always specify an
explicit decimal-point? That is, why not get rid of the value `numeric'
("Numeric with standard decimal point") and just use the version that
specifies a decimal-point character - it uses `.' as the default value,
which is the same as choosing the option value `numeric'.
3. Shouldn't `integerp' be `char-valid-p' in the test for the value? :match
(lambda (widget value) (integerp value)). In function `keypad-setup',
`char-valid-p' is used to test the character.
[-- Attachment #2: keypad-2007-09-12.patch --]
[-- Type: application/octet-stream, Size: 22736 bytes --]
*** keypad-patched-2007-09-11a.el Wed Sep 12 09:46:36 2007
--- keypad-CVS-2007-09-11.el Tue Sep 11 08:27:10 2007
***************
*** 25,92 ****
;;; Commentary:
! ;; The keypad package allows easy binding of the numeric keypad keys
! ;; to various commonly used sets of commands. It does this by binding
! ;; those keys in `function-key-map'.
;;
! ;; By `keypad' is meant here the 11 keys of the numeric keypad. Each
! ;; of these keys typically has two physical labels, one of which is a
! ;; decimal digit (0-9) or the decimal point (`.'), and the other of
! ;; which is a cursor-movement arrow (left, right, up, down), `Home',
! ;; `End', `Ins', `Del', `PgUp', `PgDn', or space (empty).
;;
! ;; You can define four keypad setups, one for each combination of
! ;; NumLock and the Shift key: NumLock on or off and Shift key pressed
! ;; or not. These setups are customizable user options:
! ;;
! ;; `keypad-setup' - NumLock off, unshifted
! ;; `keypad-numlock-setup' - NumLock on, unshifted
! ;; `keypad-shifted-setup' - NumLock off, shifted
! ;; `keypad-numlock-shifted-setup' - NumLock on, shifted
! ;;
! ;; You can customize *each* of these setups to *any* of the following
! ;; behaviors. Each behavior affects all keypad keys in the same way
! ;; (see exception for the decimal-point key). As an example, consider
! ;; the `<kp-8>' key, which is the key labeled with `8' and an up
! ;; arrow.
! ;;
! ;; 1. Use the numeric value. E.g., do what the main-keyboard `8' key
! ;; does.
! ;;
! ;; 2. Same as #1, except the decimal-point key (`.') is mapped to
! ;; another character, which is typically a different decimal-point
! ;; character (e.g. `,').
! ;;
! ;; 3. Use the non-numeric value. E.g., do what the main-keyboard `up'
! ;; key (up arrow) does.
! ;;
! ;; 4. Use the numeric value as a prefix argument for an Emacs command.
! ;; E.g., do what `M-8' does. The decimal-point key, `.', acts like
! ;; `M--'.
! ;;
! ;; 5. Use the shifted non-numeric value. E.g., do what `S-up' does.
! ;;
! ;; 6. Unspecified (user-defined) behavior. E.g. make `<kp-8>'
! ;; undefined in `function-key-map'. Choose this to define a custom
! ;; behavior for a keypad setup.
! ;;
! ;; 7. Do nothing special - do whatever the keypad key would normally
! ;; do. E.g., if `<kp-8>' is not itself bound, then it is, by
! ;; default, translated to the `8' key. This is the default
! ;; behavior for each keypad setup.
! ;;
! ;; Here are a few possibilities, as examples.
! ;;
! ;; 1. Define `keypad-setup' as `numeric' ("Numeric with standard
! ;; decimal-point key"). Define `keypad-numlock-setup' as `prefix'
! ;; ("Prefix argument"). With these setups, the keypad can be used
! ;; for numeric data entry when NumLock is off, and to provide
! ;; numeric prefix arguments to emacs commands, when NumLock is on.
! ;; Ignoring the shifted possibilities, this is the picture:
;;
;; +--------+--------+--------+
! ;; | M-7 | M-8 | M-9 | <- keypad-numlock-setup: NumLock on
! ;; | 7 | 8 | 9 | <- keypad-setup: NumLock off
;; +--------+--------+--------+
;; | M-4 | M-5 | M-6 |
;; | 4 | 5 | 6 |
--- 25,43 ----
;;; Commentary:
! ;; The keypad package allows easy binding of the keypad keys to
! ;; various commonly used sets of commands.
;;
! ;; With the following setup, the keypad can be used for numeric data
! ;; entry when NumLock is off, and to give numeric prefix arguments to
! ;; emacs commands, when NumLock on on.
;;
! ;; keypad-setup => Plain Numeric Keypad
! ;; keypad-numlock-setup => Prefix numeric args
;;
;; +--------+--------+--------+
! ;; | M-7 | M-8 | M-9 | <- numlock on
! ;; | 7 | 8 | 9 | <- numlock off
;; +--------+--------+--------+
;; | M-4 | M-5 | M-6 |
;; | 4 | 5 | 6 |
***************
*** 97,118 ****
;; | M-0 | M-- |
;; | 0 | . |
;; +-----------------+--------+
;;
! ;; Could you define these two options the other way around, so that
! ;; NumLock off means prefix arguments? Yes.
! ;;
! ;; 2. Define `keypad-setup' as `cursor' ("Non-numeric"), which is
! ;; generally for cursor movement. Define `keypad-shifted-setup' as
! ;; `S-cursor' ("Shifted non-numeric"). With both of these setups,
! ;; keys have their non-numeric meaning. By default, that means
! ;; generally cursor movement. The shifted movement keys are useful
! ;; for modes such as Delete Selection and CUA that use them to
! ;; extend the region. Ignoring the NumLock possibilities, this is
! ;; the picture:
;;
;; +--------+--------+--------+
! ;; | S-home | S-up | S-PgUp | <- keypad-shifted-setup: shifted
! ;; | Home | up | PgUp | <- keypad-setup: unshifted
;; +--------+--------+--------+
;; | S-left |S-space |S-right |
;; | left | space | right |
--- 48,64 ----
;; | M-0 | M-- |
;; | 0 | . |
;; +-----------------+--------+
+
+ ;; The following keypad setup is used for navigation together with
+ ;; modes like cua-mode which uses shifted movement keys to extend the
+ ;; region.
;;
! ;; keypad-setup => Cursor keys
! ;; keypad-shifted-setup => Shifted cursor keys
;;
;; +--------+--------+--------+
! ;; | S-home | S-up | S-PgUp | <- shifted, numlock off
! ;; | Home | up | PgUp | <- unshifted, numlock off
;; +--------+--------+--------+
;; | S-left |S-space |S-right |
;; | left | space | right |
***************
*** 123,148 ****
;; | S-insert |S-delete|
;; | insert | delete |
;; +-----------------+--------+
! ;;
! ;; Again, however, there is no necessary relation between the setup
! ;; name and the chosen behavior. You could choose the "Shifted
! ;; non-numeric" behavior for the (unshifted) `keypad-setup'.
! ;;
! ;; 3. Define `keypad-setup' as `numeric' ("Numeric with standard
! ;; decimal point"). Define `keypad-numlock-setup' as `,' ("Numeric
! ;; with customized decimal point: ,"), that is, as 44, which is the
! ;; decimal value of the comma character. With these setups,
! ;; unshifted keypad keys are decimal digits, but the decimal-point
! ;; key (`.') is mapped to a different character for each setup.
! ;; With NumLock off, the decimal point is `.'; with NumLock on, it
! ;; is `,'.
;;
;; keypad-setup => Plain Numeric Keypad
;; keypad-numlock-setup => Numeric Keypad with Decimal key: ,
;;
;; +--------+--------+--------+
! ;; | 7 | 8 | 9 | <- keypad-numlock-setup: NumLock on
! ;; | 7 | 8 | 9 | <- keypad-setup: NumLock off
;; +--------+--------+--------+
;; | 4 | 5 | 6 |
;; | 4 | 5 | 6 |
--- 69,87 ----
;; | S-insert |S-delete|
;; | insert | delete |
;; +-----------------+--------+
!
! ;; The following setup binds the unshifted keypad keys to plain
! ;; numeric keys when NumLock is either on or off, but the decimal key
! ;; produces either a . (NumLock off) or a , (NumLock on). This is
! ;; useful for e.g. Danish users where the decimal separator is a
! ;; comma.
;;
;; keypad-setup => Plain Numeric Keypad
;; keypad-numlock-setup => Numeric Keypad with Decimal key: ,
;;
;; +--------+--------+--------+
! ;; | 7 | 8 | 9 | <- numlock on
! ;; | 7 | 8 | 9 | <- numlock off
;; +--------+--------+--------+
;; | 4 | 5 | 6 |
;; | 4 | 5 | 6 |
***************
*** 150,160 ****
;; | 1 | 2 | 3 |
;; | 1 | 2 | 3 |
;; +--------+--------+--------+
! ;; | 0 | , | <- comma
! ;; | 0 | . | <- period
;; +-----------------+--------+
- ;;
- ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; Code:
--- 89,97 ----
;; | 1 | 2 | 3 |
;; | 1 | 2 | 3 |
;; +--------+--------+--------+
! ;; | 0 | , |
! ;; | 0 | . |
;; +-----------------+--------+
;;; Code:
***************
*** 164,277 ****
;;;###autoload
(defcustom keypad-setup nil
! "Numeric keypad setup for unshifted keys when NumLock is off."
! :set (lambda (symbol value) (when value (keypad-setup value nil nil value)))
:initialize 'custom-initialize-default
:link '(emacs-commentary-link "keypad.el")
:version "22.1"
! :type '(choice
! (const :tag "Numeric with standard decimal point" numeric)
! (character :tag "Numeric with customized decimal point"
:match (lambda (widget value) (integerp value))
:value ?.)
! (const :tag "Prefix argument" prefix)
! (const :tag "Non-numeric" cursor)
! (const :tag "Shifted non-numeric" S-cursor)
! (const :tag "Unspecified (user-defined)" none)
! (other :tag "No change (keep existing bindings)" nil))
:require 'keypad
:group 'keyboard)
;;;###autoload
(defcustom keypad-numlock-setup nil
! "Numeric keypad setup for unshifted keys when NumLock is on."
! :set (lambda (symbol value) (when value (keypad-setup value t nil value)))
:initialize 'custom-initialize-default
:link '(emacs-commentary-link "keypad.el")
:version "22.1"
! :type '(choice
! (const :tag "Numeric with standard decimal point" numeric)
! (character :tag "Numeric with customized decimal point"
:match (lambda (widget value) (integerp value))
:value ?.)
! (const :tag "Prefix argument" prefix)
! (const :tag "Non-numeric" cursor)
! (const :tag "Shifted non-numeric" S-cursor)
! (const :tag "Unspecified (user-defined)" none)
! (other :tag "No change (keep existing bindings)" nil))
:require 'keypad
:group 'keyboard)
;;;###autoload
(defcustom keypad-shifted-setup nil
! "Numeric keypad setup for shifted keys when NumLock is off."
! :set (lambda (symbol value) (when value (keypad-setup value nil t value)))
:initialize 'custom-initialize-default
:link '(emacs-commentary-link "keypad.el")
:version "22.1"
! :type '(choice
! (const :tag "Numeric with standard decimal point" numeric)
! (character :tag "Numeric with customized decimal point"
:match (lambda (widget value) (integerp value))
:value ?.)
! (const :tag "Prefix argument" prefix)
! (const :tag "Non-numeric" cursor)
! (const :tag "Shifted non-numeric" S-cursor)
! (const :tag "Unspecified (user-defined)" none)
! (other :tag "No change (keep existing bindings)" nil))
:require 'keypad
:group 'keyboard)
;;;###autoload
(defcustom keypad-numlock-shifted-setup nil
! "Numeric keypad setup for shifted keys when NumLock is on."
! :set (lambda (symbol value) (when value (keypad-setup value t t value)))
:initialize 'custom-initialize-default
:link '(emacs-commentary-link "keypad.el")
:version "22.1"
! :type '(choice
! (const :tag "Numeric with standard decimal point" numeric)
! (character :tag "Numeric with customized decimal point"
:match (lambda (widget value) (integerp value))
:value ?.)
! (const :tag "Prefix argument" prefix)
! (const :tag "Non-numeric" cursor)
! (const :tag "Shifted non-numeric" S-cursor)
! (const :tag "Unspecified (user-defined)" none)
! (other :tag "No change (keep existing bindings)" nil))
:require 'keypad
:group 'keyboard)
;;;###autoload
(defun keypad-setup (setup &optional numlock shift decimal)
! "Set bindings for numeric keypad in `function-key-map'.
! Argument SETUP determines the keypad key bindings as follows:
!
! Setup Binding
! -------------------------------------------------------------
! 'numeric Numeric keypad keys: `.' (or DECIMAL) plus `0' through `9'.
! 'prefix Command prefix argument: `M--' and `M-0' through `M-9'.
! 'cursor Non-numeric keypad keys: `<home>', `up', and so on.
! 'S-cursor Shifted non-numeric keypad keys.
! 'none Removes all bindings for keypad keys in `function-key-map'.
! Enables any user-defined bindings for the keypad keys in
! the global and local keymaps.
!
If optional second argument NUMLOCK is non-nil, the NumLock On bindings
are changed. Otherwise, the NumLock Off bindings are changed.
-
If optional third argument SHIFT is non-nil, the shifted keypad
keys are bound.
! If SETUP is `numeric' and optional fourth argument DECIMAL is non-nil,
! then the keypad decimal-point key is mapped to DECIMAL (a character)
! instead of `.'"
(let* ((i 0)
! (var (cond ((and (not numlock) (not shift)) 'keypad-setup)
((and (not numlock) shift) 'keypad-shifted-setup)
((and numlock (not shift)) 'keypad-numlock-setup)
((and numlock shift) 'keypad-numlock-shifted-setup)))
! (kp (cond ((eq var 'keypad-setup)
[kp-delete kp-insert kp-end kp-down kp-next kp-left
kp-space kp-right kp-home kp-up kp-prior])
((eq var 'keypad-shifted-setup)
--- 101,225 ----
;;;###autoload
(defcustom keypad-setup nil
! "Specifies the keypad setup for unshifted keypad keys when NumLock is off.
! When selecting the plain numeric keypad setup, the character returned by the
! decimal key must be specified."
! :set (lambda (symbol value)
! (if value
! (keypad-setup value nil nil value)))
:initialize 'custom-initialize-default
:link '(emacs-commentary-link "keypad.el")
:version "22.1"
! :type '(choice (const :tag "Plain numeric keypad" numeric)
! (character :tag "Numeric Keypad with Decimal Key"
:match (lambda (widget value) (integerp value))
:value ?.)
! (const :tag "Numeric prefix arguments" prefix)
! (const :tag "Cursor keys" cursor)
! (const :tag "Shifted cursor keys" S-cursor)
! (const :tag "Unspecified/User-defined" none)
! (other :tag "Keep existing bindings" nil))
:require 'keypad
:group 'keyboard)
;;;###autoload
(defcustom keypad-numlock-setup nil
! "Specifies the keypad setup for unshifted keypad keys when NumLock is on.
! When selecting the plain numeric keypad setup, the character returned by the
! decimal key must be specified."
! :set (lambda (symbol value)
! (if value
! (keypad-setup value t nil value)))
:initialize 'custom-initialize-default
:link '(emacs-commentary-link "keypad.el")
:version "22.1"
! :type '(choice (const :tag "Plain numeric keypad" numeric)
! (character :tag "Numeric Keypad with Decimal Key"
:match (lambda (widget value) (integerp value))
:value ?.)
! (const :tag "Numeric prefix arguments" prefix)
! (const :tag "Cursor keys" cursor)
! (const :tag "Shifted cursor keys" S-cursor)
! (const :tag "Unspecified/User-defined" none)
! (other :tag "Keep existing bindings" nil))
:require 'keypad
:group 'keyboard)
;;;###autoload
(defcustom keypad-shifted-setup nil
! "Specifies the keypad setup for shifted keypad keys when NumLock is off.
! When selecting the plain numeric keypad setup, the character returned by the
! decimal key must be specified."
! :set (lambda (symbol value)
! (if value
! (keypad-setup value nil t value)))
:initialize 'custom-initialize-default
:link '(emacs-commentary-link "keypad.el")
:version "22.1"
! :type '(choice (const :tag "Plain numeric keypad" numeric)
! (character :tag "Numeric Keypad with Decimal Key"
:match (lambda (widget value) (integerp value))
:value ?.)
! (const :tag "Numeric prefix arguments" prefix)
! (const :tag "Cursor keys" cursor)
! (const :tag "Shifted cursor keys" S-cursor)
! (const :tag "Unspecified/User-defined" none)
! (other :tag "Keep existing bindings" nil))
:require 'keypad
:group 'keyboard)
;;;###autoload
(defcustom keypad-numlock-shifted-setup nil
! "Specifies the keypad setup for shifted keypad keys when NumLock is off.
! When selecting the plain numeric keypad setup, the character returned by the
! decimal key must be specified."
! :set (lambda (symbol value)
! (if value
! (keypad-setup value t t value)))
:initialize 'custom-initialize-default
:link '(emacs-commentary-link "keypad.el")
:version "22.1"
! :type '(choice (const :tag "Plain numeric keypad" numeric)
! (character :tag "Numeric Keypad with Decimal Key"
:match (lambda (widget value) (integerp value))
:value ?.)
! (const :tag "Numeric prefix arguments" prefix)
! (const :tag "Cursor keys" cursor)
! (const :tag "Shifted cursor keys" S-cursor)
! (const :tag "Unspecified/User-defined" none)
! (other :tag "Keep existing bindings" nil))
:require 'keypad
:group 'keyboard)
+
;;;###autoload
(defun keypad-setup (setup &optional numlock shift decimal)
! "Set keypad bindings in `function-key-map' according to SETUP.
If optional second argument NUMLOCK is non-nil, the NumLock On bindings
are changed. Otherwise, the NumLock Off bindings are changed.
If optional third argument SHIFT is non-nil, the shifted keypad
keys are bound.
! Setup Binding
! -------------------------------------------------------------
! 'prefix Command prefix argument, i.e. M-0 .. M-9 and M--
! 'S-cursor Bind shifted keypad keys to the shifted cursor movement keys.
! 'cursor Bind keypad keys to the cursor movement keys.
! 'numeric Plain numeric keypad, i.e. 0 .. 9 and . (or DECIMAL arg)
! 'none Removes all bindings for keypad keys in function-key-map;
! this enables any user-defined bindings for the keypad keys
! in the global and local keymaps.
!
! If SETUP is 'numeric and the optional fourth argument DECIMAL is non-nil,
! the decimal key on the keypad is mapped to DECIMAL instead of `.'"
(let* ((i 0)
! (var (cond
! ((and (not numlock) (not shift)) 'keypad-setup)
((and (not numlock) shift) 'keypad-shifted-setup)
((and numlock (not shift)) 'keypad-numlock-setup)
((and numlock shift) 'keypad-numlock-shifted-setup)))
! (kp (cond
! ((eq var 'keypad-setup)
[kp-delete kp-insert kp-end kp-down kp-next kp-left
kp-space kp-right kp-home kp-up kp-prior])
((eq var 'keypad-shifted-setup)
***************
*** 283,311 ****
((eq var 'keypad-numlock-shifted-setup)
[S-kp-delete S-kp-insert S-kp-end S-kp-down S-kp-next S-kp-left
S-kp-space S-kp-right S-kp-home S-kp-up S-kp-prior])))
! (bind (cond ((or (eq setup 'numeric) (char-valid-p setup))
! (when (eq decimal 'numeric) (setq decimal nil))
(vector (or decimal ?.) ?0 ?1 ?2 ?3 ?4 ?5 ?6 ?7 ?8 ?9))
((eq setup 'prefix)
! [?\M-- ?\M-0 ?\M-1 ?\M-2 ?\M-3 ?\M-4 ?\M-5 ?\M-6 ?\M-7 ?\M-8 ?\M-9])
((eq setup 'cursor)
! [delete insert end down next left space right home up prior])
((eq setup 'S-cursor)
[S-delete S-insert S-end S-down S-next S-left
S-space S-right S-home S-up S-prior])
! ((eq setup 'none) nil)
! (t (signal 'error (list "Unknown keypad setup: " setup))))))
(set var setup)
! ;; Bind the keys in KP list to BIND list in `function-key-map'.
! ;; If BIND is nil, then all bindings for the keys are removed.
! (unless (boundp 'function-key-map) (setq function-key-map (make-sparse-keymap)))
(while (< i 11)
! (define-key function-key-map (vector (aref kp i)) (and bind (vector (aref bind i))))
! (when (= i 6)
(cond ((eq (aref kp i) 'kp-space)
! (define-key function-key-map [kp-begin] (and bind (vector (aref bind i)))))
((eq (aref kp i) 'S-kp-space)
! (define-key function-key-map [S-kp-begin] (and bind (vector (aref bind i)))))))
(setq i (1+ i)))))
;;; arch-tag: 0899d2bd-9e12-4b4e-9aef-d0014d3b6414
--- 231,275 ----
((eq var 'keypad-numlock-shifted-setup)
[S-kp-delete S-kp-insert S-kp-end S-kp-down S-kp-next S-kp-left
S-kp-space S-kp-right S-kp-home S-kp-up S-kp-prior])))
! (bind
! (cond
! ((or (eq setup 'numeric)
! (char-valid-p setup))
! (if (eq decimal 'numeric)
! (setq decimal nil))
(vector (or decimal ?.) ?0 ?1 ?2 ?3 ?4 ?5 ?6 ?7 ?8 ?9))
((eq setup 'prefix)
! [?\M-- ?\M-0 ?\M-1 ?\M-2 ?\M-3 ?\M-4
! ?\M-5 ?\M-6 ?\M-7 ?\M-8 ?\M-9])
((eq setup 'cursor)
! [delete insert end down next left
! space right home up prior])
((eq setup 'S-cursor)
[S-delete S-insert S-end S-down S-next S-left
S-space S-right S-home S-up S-prior])
! ((eq setup 'none)
! nil)
! (t
! (signal 'error (list "Unknown keypad setup: " setup))))))
!
(set var setup)
!
! ;; Bind the keys in KP list to BIND list in function-key-map.
! ;; If BIND is nil, all bindings for the keys are removed.
! (if (not (boundp 'function-key-map))
! (setq function-key-map (make-sparse-keymap)))
!
(while (< i 11)
! (define-key function-key-map (vector (aref kp i))
! (if bind (vector (aref bind i))))
! (if (= i 6)
(cond ((eq (aref kp i) 'kp-space)
! (define-key function-key-map [kp-begin]
! (if bind (vector (aref bind i)))))
((eq (aref kp i) 'S-kp-space)
! (define-key function-key-map [S-kp-begin]
! (if bind (vector (aref bind i)))))))
!
(setq i (1+ i)))))
;;; arch-tag: 0899d2bd-9e12-4b4e-9aef-d0014d3b6414
[-- Attachment #3: keypad-doc.txt --]
[-- Type: text/plain, Size: 8928 bytes --]
Emacs-manual node "Function Keys"
---------------------------------
Remove all text starting with "Many keyboards have a "numeric
keypad...". Put that topic in its own node (see below).
New Emacs-manual node (child of node "Key Bindings", Next node after
"Function Keys")
Numeric Keypad
--------------
Many keyboards have a numeric keypad, which is typically to the right
of the main keyboard (main set of keys). For simplicity, in this
section, "keypad" means this numeric keypad.
More precisely, "keypad" refers here only to the 11 keys that each
have two physical labels, one of which is a decimal digit (0-9) or the
decimal point (`.'), and the other of which is a cursor-movement arrow
(left, right, up, down), `Home', `End', `Ins', `Del', `PgUp', `PgDn',
or space (empty).
Other keys that might be physically nearby, such as the keypad PF keys
(e.g. `<kp-f3>') and the keys labeled `/', `*', `-', `+', and `Enter',
are not considered part of the keypad, as the term is understood
here.
This means that only some of the keys with names starting with `kp-'
are considered "keypad" keys in this section. For example, the nearby
key labeled `/' is often named `<kp-divide>', but it is not a numeric
keypad key. Be aware that in some other contexts any key whose Emacs
name starts with `kp-' might be considered a "keypad" key. See, for
instance, (elisp) "Function Keys".
The Shift key and the NumLock key modify the behavior of keys on the
numeric keypad. The Shift key acts as usual. The NumLock key is
usually near the keypad keys. It acts similarly to the Caps Lock key,
but instead of toggling between uppercase and lowercase for the main
keyboard it toggles the keypad keys between two possible modes:
numeric and non-numeric. Like the Caps Lock key, and unlike the Shift
key, NumLock is modal: hitting it once enters a mode that stays active
until you hit it again to change the mode. NumLock is not a modifier
key: you do not hold it down while hitting other keys.
The keypad keys thus each have two possible NumLock behaviors. For
example, a key labeled both `7' and `Home' might act alternately as a
`7' key (in numeric mode) and a `Home' key (in non-numeric mode).
Combining this with the possibility of two different behaviors
provided by the Shift key, there are four possible behaviors for any
keypad key: NumLock off, shifted or unshifted, or NumLock on, shifted
or unshifted.
A physical keypad key labeled `7' and `Home' represents the Emacs keys
`<kp-7>' and `<kp-home>', depending on whether NumLock is on or off.
These two Emacs keys need not be bound to the same commands as the
keys `7' and `<home>' of the main keyboard. By default, Emacs does
translate keypad keys to the corresponding keys of the main keyboard,
however (see (elisp) "Function Keys").
So, for instance, when NumLock is on, hitting the keypad `7' and
`Home' physical key produces the Emacs key sequence `<kp-7>', which is
translated to `7', by default. When NumLock is off, hitting the same
key produces `<kp-home>', which is translated to `<home>', by default.
Because of this automatic key translation, if you rebind a main
keyboard key such as `7' or `<home>', then your binding affects the
equivalent keypad key too, `<kp-7>' or `<kp-home>'. Rebinding a
keypad key such as `<kp-7>' directly does not, however, affect the
corresponding key on the main keyboard (`7').
Besides this automatic translation, you can define four keypad setups,
one for each combination of NumLock and the Shift key: NumLock on or
off and Shift key pressed or not. These setups are customizable user
options:
`keypad-setup' - NumLock off, unshifted
`keypad-numlock-setup' - NumLock on, unshifted
`keypad-shifted-setup' - NumLock off, shifted
`keypad-numlock-shifted-setup' - NumLock on, shifted
You can customize *each* of these setups to *any* of the following
behaviors. Each behavior affects all keypad keys in the same way (see
exception for the decimal-point key). As an example, consider the
`<kp-8>' key, which is the key labeled with `8' and an up arrow.
1. Use the numeric value. E.g., do what the main-keyboard `8' key
does.
2. Same as #1, except the decimal-point key (`.') is mapped to a
specific character, which is typically a different decimal-point
character (e.g. `,').
3. Use the non-numeric value. E.g., do what the main-keyboard `up'
key (up arrow) does.
4. Use the numeric value as a prefix argument for an Emacs command.
E.g., do what `M-8' does. The decimal-point key, `.', acts like
`M--'.
5. Use the shifted non-numeric value. E.g., do what `S-up' does.
6. Unspecified (user-defined) behavior. E.g. make `<kp-8>' undefined
in `function-key-map'. Choose this to define a custom behavior for
a keypad setup.
7. Do nothing special - do whatever the keypad key would normally do.
E.g., if `<kp-8>' is not itself bound, then it is, by default,
translated to the `8' key. This is the default behavior for each
keypad setup option.
Here are a few possibilities, as examples.
1. Define `keypad-setup' as `numeric' ("Numeric with standard
decimal-point key"). Define `keypad-numlock-setup' as `prefix'
("Prefix argument"). With these setups, the keypad can be used for
numeric data entry when NumLock is off, and to provide numeric
prefix arguments to emacs commands, when NumLock is on. Ignoring
the shifted possibilities, this is the picture:
+--------+--------+--------+
| M-7 | M-8 | M-9 | <- keypad-numlock-setup: NumLock on
| 7 | 8 | 9 | <- keypad-setup: NumLock off
+--------+--------+--------+
| M-4 | M-5 | M-6 |
| 4 | 5 | 6 |
+--------+--------+--------+
| M-1 | M-2 | M-3 |
| 1 | 2 | 3 |
+--------+--------+--------+
| M-0 | M-- |
| 0 | . |
+-----------------+--------+
Could you define these two options the other way around, so that
NumLock off means prefix arguments? Yes.
2. Define `keypad-setup' as `cursor' ("Non-numeric"), which is
generally for cursor movement. Define `keypad-shifted-setup' as
`S-cursor' ("Shifted non-numeric"). With both of these setups,
keys have their non-numeric meaning. By default, that means
generally cursor movement. The shifted movement keys are useful
for modes such as Delete Selection and CUA that use them to extend
the region. Ignoring the NumLock possibilities, this is the
picture:
+--------+--------+--------+
| S-home | S-up | S-PgUp | <- keypad-shifted-setup: shifted
| Home | up | PgUp | <- keypad-setup: unshifted
+--------+--------+--------+
| S-left |S-space |S-right |
| left | space | right |
+--------+--------+--------+
| S-end | S-down | S-PgDn |
| end | down | PgDn |
+--------+--------+--------+
| S-insert |S-delete|
| insert | delete |
+-----------------+--------+
Again, however, there is no necessary relation between the setup name
and the chosen behavior. You could choose the "Shifted non-numeric"
behavior for the (unshifted) `keypad-setup'.
3. Define `keypad-setup' as `numeric' ("Numeric with standard decimal
point"). Define `keypad-numlock-setup' as `,' ("Numeric with
customized decimal point: ,"), that is, as 44, which is the decimal
value of the comma character. With these setups, unshifted keypad
keys are decimal digits, but the decimal-point key (`.') is mapped
to a different character for each setup. With NumLock off, the
decimal point is `.'; with NumLock on, it is `,'.
keypad-setup => Plain Numeric Keypad
keypad-numlock-setup => Numeric Keypad with Decimal key: ,
+--------+--------+--------+
| 7 | 8 | 9 | <- keypad-numlock-setup: NumLock on
| 7 | 8 | 9 | <- keypad-setup: NumLock off
+--------+--------+--------+
| 4 | 5 | 6 |
| 4 | 5 | 6 |
+--------+--------+--------+
| 1 | 2 | 3 |
| 1 | 2 | 3 |
+--------+--------+--------+
| 0 | , | <- comma
| 0 | . | <- period
+-----------------+--------+
DOC STRINGS
-----------
`keypad-numlock-shifted-setup' corrected - should be "when NumLock is
on" (not off).
QUESTIONS
---------
1. nil value for the options: "No change (keep existing bindings)"
seems to be a no-op. What is its use?
2. Do we need a separate `numeric' choice? Why not always specify an
explicit decimal-point?
3. Should integerp be char-valid-p in the test for
the value? :match (lambda (widget value) (integerp value))
[-- Attachment #4: Type: text/plain, Size: 142 bytes --]
_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel
next prev parent reply other threads:[~2007-09-12 17:22 UTC|newest]
Thread overview: 15+ messages / expand[flat|nested] mbox.gz Atom feed top
2007-09-05 6:11 keypad-*-setup Drew Adams
2007-09-10 1:12 ` keypad-*-setup Richard Stallman
2007-09-10 1:24 ` keypad-*-setup Drew Adams
2007-09-10 23:54 ` keypad-*-setup Richard Stallman
2007-09-10 23:54 ` keypad-*-setup Richard Stallman
2007-09-11 12:13 ` keypad-*-setup Kim F. Storm
2007-09-11 19:51 ` keypad-*-setup Drew Adams
2007-09-11 21:54 ` keypad-*-setup Kim F. Storm
2007-09-12 17:22 ` Drew Adams [this message]
2007-09-13 16:29 ` keypad-*-setup Richard Stallman
2007-09-17 22:04 ` keypad-*-setup Kim F. Storm
2007-09-17 22:30 ` keypad-*-setup Drew Adams
2007-09-18 12:25 ` keypad-*-setup Kim F. Storm
2007-09-18 15:11 ` keypad-*-setup Drew Adams
2007-09-18 4:16 ` keypad-*-setup tomas
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=BNELLINCGFJLDJIKDGACCEJBCCAA.drew.adams@oracle.com \
--to=drew.adams@oracle.com \
--cc=emacs-devel@gnu.org \
--cc=storm@cua.dk \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.