Author:         Jan Nijtmans <[email protected]>
State:          Draft
Type:           Project
Tcl-Version:    9.1
Tk-Branch:     tip-708

Abstract

This TIP is inspired by ticket #3119824: "Enter doesn't work in text input box".

After TIP #158, the handling of the <KP_Enter> key (and all other Numeric-keyboard keys) is different on Windows compared to UNIX/macOS. On Windows, the <KP_???> keysyms are not used, they must be handled as <Extended_????> keysyms. Applications which want the same behavior on UNIX/macOS as on Windows must do one of the followings:

Either <KP_Enter> and <Return> is expected to behave the same. Then two bindings must be provided. The second binding is only useful on UNIX/macOS:
```
bind ... <Return>  "pressReturn"
bind ... <KP_Enter>  "pressReturn" ; # only useful on UNIX
```

Or, a different action is expected from those. The only way to do that for all platforms is:

bind ... <Return>  "pressReturn"
bind ... <KP_Enter>  "pressEnter" ; # only useful on Unix
bind ... <Extended-Return>  "pressEnter" ; # only useful on Windows

After this TIP. The first set of bindings can be simplified to:

 bind ... <Return>  "pressReturn"

The second situation can be simplified to:

 bind ... <Return>  "pressReturn"
 bind ... <Num-Return>  "pressEnter"

The <KP_Enter> and <Extended-Return> bindings will be handled as alias for <Num-Return>, so no current code needs to be modified.

The challenge in this TIP implementation is getting the modifiers right for UNIX and macOS, the same as on Windows. for hardware-generated events. This is certainly not right yet in the current implementation! Be warned!

Rationale

TODO

Specification

Currently, the "Num" and "Fn" modifiers are aliases for "Mod3" and "Mod4". This TIP proposes to invert that: "Mod3" and "Mod4" will be aliases for "Num" and "Fn". This makes it much more clear what those modifiers are meant for, and those are the same on all platforms.

The "Extended" modifier will be an alias for "Num". Currently this is for Windows only, joining it with "Num" makes it available for all platforms. Since, on Windows, "Mod3" is used for the "Scroll Lock" functionality, this is moved to "Mod5".

All <KP_????> bindings will be deprecated, and translated to <Num-????> bindings. For example specifying a binding for <KP_Enter> will be automatically translated to a <Num-Return> binding. The UNIX and macOS native code will not generate any keycodes any more. The non-keypath keycode with the "Num" modifier will be generated in stead.

Compatibility

When specifying bindings, this is 100% upwards compatible. All binding will continue to work as before. Only when getting back the binding, the result will be different. For example:

Current behavior:

$ text .t
$ bind .t <Return>  "pressReturn"
$ bind .t <KP_Enter>  "pressEnter"; # Does nothing on Windows
$ bind .t <Extended-Return>  "pressEnter"; # Does nothing on UNIX
$ bind .t
<Return> <KP_Enter> <Extended-Return>

New behavior (same bindings):

$ text .t
$ bind .t <Return>  "pressReturn"
$ bind .t <KP_Enter>  "pressEnter"; # Does nothing on Windows
$ bind .t <Extended-Return>  "pressEnter"; # Does nothing on UNIX
$ bind .t
<Return> <Num-Return>

New behavior, which new bindings:

$ text .t
$ bind .t <Return>  "pressReturn"
$ bind .t <Num-Return>  "pressEnter";
$ bind .t
<Return> <Num-Return>

Also it has effect on the %k (keycode) and %s (state). For %s, <Extended> had the numerical value of 262144, which will become 32. For %s, the ScrollLock value changes from 32 to 128.

Implementation

See the tip-708 branch.

Copyright