\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#433: Add \%M binding substitution}
\date{February 25, 2015}
\author{Joe Mistachkin, Brian Griffin, Don Porter}
\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 \#433}&\textbf{Add \%M binding substitution}\\\hline
Author&

Joe Mistachkin \tipmail{joe}{mistachkin.com}
\par
Brian Griffin \tipmail{brian_griffin}{mentor.com}
\par
Don Porter \tipmail{dgp}{users.sf.net}
\\
Created&Wednesday, \(\text{25}^{\text{th}}\) February 2015\\
Type&Project\\
Tcl Version&\(8.6.4\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.7 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes one new binding substitution, \textbf{\%M}, to access the number of script-based binding patterns matched so far for the event.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Background}

In a presentation at the 2012 Tcl Conference (\url{http://www.tclcommunityassociation.org/wub/proceedings/Proceedings-2012/RonWold/Customizable-Keyboard-Shortcuts.pdf}), Ron Wold pointed out that coding global catch-all scripts bound to the same event in many widgets is complicated because Tk's \textbf{bind} machinery allows any bind script to use \textbf{break} to prevent later bind scripts from evaluating. Among a known set of bind scripts, this is a useful technique, but it interferes with the non-coordinated introduction of additional bind scripts on the same event.

An alternative strategy is to avoid any bind script using \textbf{break}, but to give the latter scripts the means to detect when an earlier script has run so it can defer its own operations. That motivates the introduction of a means by which a bind script can discover something about the history of other bind script evaluations on the same event.

\section{Specification}

Add to the set of substitutions made in scripts passed to \textbf{bind} the new one, \textbf{\%M}. When the substring \textbf{\%M} appears in a binding script, it will be replaced with a count of the number of binding script evaluations that have already been performed in the handling of the current event.

\section{Simple Example}

The script...
\begingroup\small\begin{verbatim}
   pack [entry .e]
   bind all <Key> {set z %M}
   bind Entry <Key> {set y %M}
   bind .e <Key> {set x %M}
   event generate .e <Key-a>
   list $x $y $z
\end{verbatim}
\endgroup

will produce the result:
\begingroup\small\begin{verbatim}
   0 1 2
\end{verbatim}
\endgroup

\section{Use Case Example}

One of the default bind scripts in Tk is
\begingroup\small\begin{verbatim}
 event add <<NextWindow>> <Tab>
 bind all <<NextWindow>> {tk::TabToWindow [tk_focusNext %W]}
\end{verbatim}
\endgroup

which permits a \textbf{\tiplangle{}Tab\tiprangle{}} anywhere in Tk to shift the focus.

Some widgets have their own uses for \textbf{\tiplangle{}Tab\tiprangle{}}, though, notably
\begingroup\small\begin{verbatim}
 bind Text <Tab> {
     if {[%W cget -state] eq "normal"} {
         tk::TextInsert %W \t
         focus %W
         break
     }
 }
\end{verbatim}
\endgroup

where a text widget in normal state accepts \textbf{Tab}s as entered text like any other keypresses. The \textbf{break} in this script serves to prevent the focus shift that would otherwise take place. Since the same Tk developers coded both bind scripts, the global knowledge can make the system work as a whole.

However, a third party facility trying to join the party has difficulty. Consider a simple key logging facility,
\begingroup\small\begin{verbatim}
 bind all <Key> {log_key %W %k %s %x %y %X %Y %A}
\end{verbatim}
\endgroup

This will fail to log \textbf{Tab}s typed in a Text due to the \textbf{break} noted above.

With the \textbf{\%M} binding proposed here, an alternative set of bind scripts is possible.
\begingroup\small\begin{verbatim}
 bind all <<NextWindow>> {if {%M==0} {tk::TabToWindow [tk_focusNext %W]}}
\end{verbatim}
\endgroup
\begingroup\small\begin{verbatim}
 bind Text <Tab> {
     if {[%W cget -state] eq "normal"} {
         tk::TextInsert %W \t
         focus %W
     }
 }
\end{verbatim}
\endgroup

In fact with the revised script bound to \textbf{all} it may be that the script bound to \textbf{\tiplangle{}Tab\tiprangle{}} is no longer needed at all and the general default binding
\begingroup\small\begin{verbatim}
 bind Text <KeyPress> {tk::TextInsert %W %A}
\end{verbatim}
\endgroup

is sufficient.

With this alternative in place the third-party keylogger would work.

\section{Compatibility}

Any \textbf{\%M} in an existing bind script will now stop reproducing itself literally, and will result in the new substitution. This has the potential to cause trouble with any bind scripts that themselves make use of \textbf{clock scan} or \textbf{clock format} or any other command that invites the use of the literal string \textbf{\%M}. Dealing with such a situation is not difficult, but it is still a potential incompatibility.

\section{Prototype}

This feature is already implemented and committed to both the core-8-5-branch and the trunk, and is poised to be released as part of Tk 8.5.18 and Tk 8.6.4. Any objections to that should be raised in TIP discussion and voting.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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