\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#165: A User-Data Field for Virtual Events}
\date{November 17, 2003}
\author{Donal K. Fellows}
\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 \#165}&\textbf{A User-Data Field for Virtual Events}\\\hline
Author&

Donal K. Fellows \tipmail{donal.k.fellows}{man.ac.uk}
\\
Created&Monday, \(\text{17}^{\text{th}}\) November 2003\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.6 $\\
Keywords&Tk, substitution\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes adding to virtual events a new field that is not interpreted by Tk. This will make it far easier for user-code to pass information between creators and consumers of events instead of forcing the use of fragile global variables for this purpose.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

Virtual events are a powerful mechanism in Tk for representing window-related occurrences which are not part of the underlying window system's basic event model. Examples of these higher-level events include \tiplangle{}\tiplangle{}MenuSelect\tiprangle{}\tiprangle{} and \tiplangle{}\tiplangle{}ListboxSelect\tiprangle{}\tiprangle{}, both of which may represent either particular key actions or particular mouse movements/clicks, but neither of which has deep significance to the windowing system. They are very important to the application though!

There is a problem with virtual events though, and that is that they do not provide a way of passing some kind of event-specific information via the event. This means, among other things, that neither of the events mentioned above can actually say what it was that was selected, despite the fact that that would be a natural piece of information to include.

Other potential uses include in a drag-and-drop system, where the information passed might be the data being dropped, and perhaps even inside Tk itself where refactoring many widgets (e.g. the spinbox or the scrollbar) to use virtual events for their semantic events would allow for programmers to track what is going on more easily, a refactoring which would require extra information describing which subcomponent of those widgets is being activated. (Actually doing such a refactoring is outside the scope of this TIP though.)

\section{Specification}

To make this happen, an extra field is required in the XVirtualEvent defined in \textit{generic/tk.h}, which will be placed at the end of the structure and which will be declared like this (in keeping with the field naming scheme in the rest of that structure):
\begingroup\small\begin{verbatim}
   Tcl_Obj *user_data;
\end{verbatim}
\endgroup

This field will normally be NULL, but if not it must be a pointer to a \textit{Tcl\_Obj} structure with a non-zero reference count. (This will still leave the XVirtualEvent structure smaller than an XCrossingEvent so no change to core structure sizes will be seen.) Once the event has had all its binding callbacks called on it, the reference count of the user\_data field will be decremented once (if it is non-NULL, of course.) It will be up to the caller of \textit{Tk\_HandleEvent()} or \textit{Tk\_QueueWindowEvent()} (depending on whether the event is being handled synchronously or asynchronously, respectively) to increment the reference count.

The contents of that field will be substituted in binding scripts using the \textbf{\%d} substitution (``d'' for ``data''), with a NULL being treated like an empty string. Empty strings (and NULLs) will be substituted as \{\}, similarly to the \textit{\%A} substitution when a key press does not have a character associated with it.

Generation of a virtual event with a non-NULL \textit{user\_data} field will be done using a new event-field option to \textbf{event generate}: \textbf{-data}. The value passed to that option will be the object to place inside the \textit{user\_data} field.

\section{Reference Implementation}

\url{http://sf.net/tracker/?func=detail&aid=1008975&group_id=12997&atid=312997}

\section{Copyright}

This document is placed in the public domain.

\section{Colophon}

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