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))