\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#158: Distinguish the two 'Enter' keys on Windows}
\date{September 20, 2003}
\author{Wolfgang Großbauer, Kevin Kenny}
\urlstyle{sf}
\setlength{\parskip}{1ex}
\setlength{\parindent}{0pt}
\def\tipversion$#1${\texttt{\$#1\$}}
\def\tiplangle#1{\ensuremath{<}}
\def\tiprangle#1{\ensuremath{>}}
\def\tipbar#1{\ensuremath{|}}
\def\tipmail#1#2{\(\langle\){\small\expandafter\url{#1@#2}}\(\rangle\)}
\ifx\pdfoutput\undefined
\newcommand{\tipimage}[2]{\typeout{Make sure you download #1.eps}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.eps}}{\includegraphics[width=0.8\textwidth]{#1.eps}}}
\newcommand{\tipxref}[1]{}
\newcommand{\tipxrefend}{}
\else
\newcommand{\tipimage}[2]{\typeout{Make sure you create #1.pdf}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.pdf}}{\includegraphics[width=0.8\textwidth]{#1.pdf}}}
\pdfcatalog{/PageMode /UseOutlines}
\newcommand{\tipxref}[1]{\pdfannotlink attr {/C [0.5 0.5 1.0] /Border [0 0 1]} goto name {#1}}
\newcommand{\tipxrefend}{\pdfendlink}
\fi
\newenvironment{tipabstract}{\begin{abstract}}{\end{abstract}}
\begin{document}\maketitle
\begin{center}\begin{tabularx}{\linewidth}{|r@{: }X|}\hline
\textbf{TIP \#158}&\textbf{Distinguish the two 'Enter' keys on Windows}\\\hline
Author&

Wolfgang Großbauer \tipmail{Go2DevNull}{magro-soft.com}
\par
Kevin Kenny \tipmail{kennykb}{acm.org}
\\
Created&Saturday, \(\text{20}^{\text{th}}\) September 2003\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.9 $\\
Post History&\\
Discussions To&news:comp.lang.tcl\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes that the ``extended keys'' on a Windows keyboard be labeled with \tiplangle{}Mod4\tiprangle{} so that they can be distinguished from their counterparts on the main keyboard.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

Most US keyboards on Windows systems have two keys bearing the label, 'Enter'. The Tk system generates the events, \textit{\tiplangle{}KeyPress-Return\tiprangle{}} and \textit{\tiplangle{}KeyRelease-Return\tiprangle{}} for both of them; the two keys are indistinguishable. While this behavior is in keeping with the ``Microsoft Windows User Experience Guidelines,'' which explicitly state that the two keys should command identical functionality, it is inconvenient for developers who wish to port Unix applications that already have different actions bound to the \textit{\tiplangle{}KeyPress-Return\tiprangle{}} and \textit{\tiplangle{}KeyPress-KP\_Enter\tiprangle{}} events.

\section{Specification}

The solution that has been chosen supports the greatest possible backward compatibility. What is proposed is that 'tkWinX.c' will examine the \textit{KF\_EXTENDED} bit in the keyboard state (passed as \textit{lParam} to the \textit{GetState} function) and map it as modifier 4. (Modifiers 1 through 3, respectively, refer to the \textit{Num Lock}, \textit{Alt}, and \textit{Scroll Lock} keys.) An alias shall be added so that \textit{Extended} may be used in place of \textit{Mod4}.

This change has little if any impact on existing Windows code, since modifier 4 is not generated on Windows today. A binding to \textit{\tiplangle{}Return\tiprangle{}} will continue to fire for the numeric \textit{Enter} key, unless there is also a binding to \textit{\tiplangle{}Extended-Return\tiprangle{}} which will then take precedence.

Existing Unix code that binds \textit{\tiplangle{}Return\tiprangle{}} and \textit{\tiplangle{}KP\_Enter\tiprangle{}} to identical functionality (and does not bind \textit{\tiplangle{}Mod4-Return\tiprangle{}}) will also not need to change. Again, the existing \textit{\tiplangle{}Return\tiprangle{}} binding will fire for the \textit{Enter} keys on both the main keyboard and the numeric pad.

Unix code that has distinct bindings for \textit{\tiplangle{}Return\tiprangle{}} and \textit{\tiplangle{}KP\_Enter\tiprangle{}} does not function correctly on Windows today --- and cannot be made to do so without changing its specification. To port such code to Windows once this change is in place, a developer will have to add bindings to \textit{\tiplangle{}Extended-Return\tiprangle{}} that mirror those for \textit{\tiplangle{}KP\_Enter\tiprangle{}}. Once the developer has done this, the application will distinguish the two keys and fire the appropriate binding for each.

Although the immediate purpose of the change is to deal with the numeric \textit{Enter} key, the effect of the change will be to deal with the rest of the numeric pad the same way; rather than generating events such as \textit{\tiplangle{}KeyPress-KP\_0\tiprangle{}} or \textit{\tiplangle{}Keypress-KP\_Multiply\tiprangle{}}, the system will generate events representing the corresponding keys on the main keyboard, with modifier 4 set to distinguish them. These events are less likely to need to be rebound, since they correspond to printing characters and seldom if ever have different bindings between the numeric pad and the main keyboard.

\section{Reference Implementation}

The changes require to implement an earlier version of this proposal can be obtained from SourceForge as Tk Patch \#797404.

\section{Summary of Discussion}

This change has been discussed extensively on the tcl-core mailing list ([\url{http://aspn.activestate.com/ASPN/Mail/Message/tcl-core/1791694}] and several following threads) and the comp.lang.tcl newsgroup [\url{http://groups.google.com/groups?threadm=3F520749.8080808@acm.org}].

The chief proposed alternative to the use of modifier 4 was to modify \textit{tkWinX.c} so that the \textit{Enter} key on the numeric pad would generate the same \textit{\tiplangle{}KP\_Enter\tiprangle{}} event that it does on Unix. The drawback to this proposal, making it unacceptable to the authors of this TIP, is that existing user code on Windows that establishes bindings to \textit{\tiplangle{}Return\tiprangle{}} but not \textit{\tiplangle{}KP\_Enter\tiprangle{}} would no longer recognize the numeric \textit{Enter} key. This problem was seen as a far greater drawback than the need for those porting Unix applications (and wishing to continue to operate inconsistently with the Microsoft guidelines) to add an additional binding, particularly in light of the fact that those applications today can't implement the desired functionality on Windows at all.

One proposed workaround was to have a default \textit{all} binding for \textit{\tiplangle{}KP\_*\tiprangle{}} events on Windows fire the corresponding binding for a non-\textit{KP} keysym. Unfortunately, this solution introduces even worse surprising behavior. A conventional binding to the KP\_* keysym will have to include a \textbf{break} or \textbf{return -code break} in order to avoid having this \textit{all} binding fire --- and making it appear as if both keys had been pressed or released.

The open issue of what to do about the problem on the Macintosh platform remains. The authors of this TIP are too ignorant of Macintosh programming to address it.

This proposal has engendered a fair amount of controversy, as may be seen in the two threads of messages beginning from [\url{http://aspn.activestate.com/ASPN/Mail/Message/1811543}] and [\url{http://aspn.activestate.com/ASPN/Mail/Message/1820298}].

More recent additional discussion is archived at [\url{http://aspn.activestate.com/ASPN/Mail/Message/2032516}]. Vince Darley summarizes it:

For example, there is Benny's suggestion to your \textit{all} counterexample that the counterexample really contains a bug, since any key-binding ought to have \textbf{;break} to prevent exactly that problem. Do we guarantee backwards compatibility even with buggy code?

Second there is the suggestion that if you really don't want the \textit{all} binding to fire if another binding has triggered, you could actually check for that manually (scan the bindtags list, etc). This would reduce the backwards incompatibility of an overall cleaner solution to effectively nothing.

Third, the TIP contains no mention of what the result of this TIP is on the x-platform Tk developer. That they must now have this:
\begingroup\small\begin{verbatim}
 bind ... <Return>  "pressReturn"
 bind ... <KP_Enter>  "pressEnter" ; # only useful on Unix
 bind ... <Extended-Return>  "pressEnter" ; # only useful on Windows
\end{verbatim}
\endgroup

i.e. rather than making their life easier, it has been made more complex! (In fact the TIP as a whole seems to have a bias against anyone even considering writing the same application on multiple platforms, which seems v. odd for Tk)

\section{Copyright}

Copyright (c) 2003, 2004 by Kevin B. Kenny. All rights reserved.

Permission to use this document in accordance with the terms of Open Publication License [\url{http://www.opencontent.org/openpub/}] is herewith granted.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\end{document}
