\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#434: Specify Event Sources for 'vwait'}
\date{February 26, 2015}
\author{Jos Decoster}
\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 \#434}&\textbf{Specify Event Sources for 'vwait'}\\\hline
Author&

Jos Decoster \tipmail{jos.decoster}{gmail.com}
\\
Created&Thursday, \(\text{26}^{\text{th}}\) February 2015\\
Type&Project\\
Tcl Version&\(8.6\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.1 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes to extend the \textbf{vwait} Tcl command so the event sources can be specified, as is possible with the \textbf{Tcl\_DoOneEvent} C command.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

In some situations it can be required not to wait for specific event sources or to wait for specific events sources only. You might want the program to only react on timer events, and not on file or window events. You can write your own version of the \textbf{Tcl\_VwaitObjCmd} command in C, and call \textbf{Tcl\_DoOneEvent} with the flags you need. Making it possible to specify the event sources, i.e. the arguments for the call to \textbf{Tcl\_DoOneEvent} within \textbf{Tcl\_VwaitObjCmd}, from the Tcl \textbf{vwait} command would make this functionality available from the Tcl lebvel.

\section{Specification}

This document proposes to add optional arguments to the \textbf{vwait} command. If these arguments are not specified, the current event source \textbf{TCL\_ALL\_EVENTS} will be used. If the optinal arguments are specified, they are the event sources to be passed to \textbf{Tcl\_DoOneEvent} within \textbf{Tcl\_VwaitObjCmd}. The flags set with the optinal arguments will be or-ed. Possible flags are corresponding to the flags for the \textbf{Tcl\_DoOneEvent} command:
\begin{itemize}
\item{}
\textbf{-all} (default) --- process all events
\item{}
\textbf{-file} --- process file events
\item{}
\textbf{-idle} --- process idle events
\item{}
\textbf{-timer} --- process timer events
\item{}
\textbf{-window} --- process window system events
\end{itemize}

Example: wait until variable \textbf{a} is written and only allow timer events to be processed:
\begingroup\small\begin{verbatim}
 vwait a -timer
\end{verbatim}
\endgroup

\section{Alternatives}

A possible alternative is to add support for a \textbf{-events \tiplangle{}event\_list\tiprangle{}} argument.

A \textbf{-dont\_wait} argument is not added, a call to \textbf{update} will have the same effect.

\section{Compatibility}

No incompatibilities are introduced.

\section{Reference Implementation}

A reference implementation is available.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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