\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#419: A New Command for Binding to Tk Events}
\date{August 28, 2012}
\author{Jeff Rogers}
\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 \#419}&\textbf{A New Command for Binding to Tk Events}\\\hline
Author&

Jeff Rogers \tipmail{dvrsn}{diphi.com}
\\
Created&Tuesday, \(\text{28}^{\text{th}}\) August 2012\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.2 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes a more modern mechanism for binding callbacks to Tk's events.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

The Tk \textbf{bind}' command passes details about an event to a callback script by doing a textual substitution of percent markers. This has worked well for years, however most recent code prefers to use command prefixes to which set arguments are appended rather than scripts which are evaluated. This TIP proposes such an approach for tk event binding.

\section{Specification}

A new command, ``tkevent'' is introduced with the following syntax:

\begin{quote}
\textbf{tkevent} \textit{tag} \textit{sequence} \textit{cmd}
\end{quote}

The \textit{tag} and \textit{sequence} arguments are the same as used in the \textbf{bind} command. The \textit{cmd} is evaluated by appending a single argument which is a dictionary containing the event details. The implementation of \textit{cmd} can retrieve details of the event using that dictionary.

Bindings created by \textbf{tkevent} are compatible with those created by \textbf{bind}. When a sequence is bound to a tag using \textbf{tkevent}, it replaces any previous binding, and vice versa. Appending to a binding with ``bind tag sequence +script'' may not work as expected.

The possible keys in the dict passed to the handler are:
\begingroup\small\begin{verbatim}
        serial        above         button
        count         detail        focus
        height        window        keycode
        mode          override_redirect
        place         state         time
        width         x             y
        character     border_width  delta
        send_event    keysym        keysym_num
        property      root          subwindow
        type          window        xroot
        yroot
\end{verbatim}
\endgroup

These keys are intended to be be the same as the options to \textbf{event generate} where applicable.

Not all values are legal for all event types; where a key is not legal for an event type, it will not be present in the dictionary when the \textit{cmd} bound to that event is evaluated.

\section{Reference Implementation}

A sample implementation of these commands in pure tcl is available at \url{http://wiki.tcl.tk/tkevent}

\section{Cross-Compatibility with Bind}

Except for the ``+script'' feature, \textbf{bind} and \textbf{tkevent} support identical functionality, and either could be implemented in terms of the other. If \textbf{bind} as a core command was dropped in favor of \textbf{tkevent}, it could be provided as a library implementation.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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