\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#245: Discover User Inactivity Time}
\date{April 15, 2005}
\author{Pascal Scheffers, Reinhard Max, Neil Madden}
\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 \#245}&\textbf{Discover User Inactivity Time}\\\hline
Author&

Pascal Scheffers \tipmail{pascal}{scheffers.net}
\par
Reinhard Max \tipmail{max}{tclers.tk}
\par
Neil Madden \tipmail{nem}{cs.nott.ac.uk}
\\
Created&Friday, \(\text{15}^{\text{th}}\) April 2005\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.12 $\\
Keywords&Tk\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes a new subcommand, \textbf{inactive}, to the \textbf{tk} command, as well as \textbf{Tk\_GetUserInactiveTime} and \textbf{Tk\_ResetUserInactiveTime} C functions to discover the number of milliseconds the user has been inactive and reset that timer to zero respectively. For most environments, this is the time since the user last used the keyboard or mouse.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

User inactivity is used by screen-savers, chat applications and for security conscious applications to quit or lock themselves after some inactive time has elapsed. It would make it easier for authors of these kinds of applications to use Tk if there was a simple way to get the length of time which the user has been inactive, which is information available on all supported platforms.

Applications that take some kind of user input from channels that bypass the system's mechanisms for detecting user activity might want to tell the system to reset the inactivity timer because they received input that has to be treated as user activity. An example for this would be barcode readers connected via serial lines that are read directly by the application.

\section{Specification}

\subsection{Tcl API}

A single new subcommand will be added to \textbf{tk}, \textbf{inactive}. This command takes an optional argument ?\textbf{-displayof} \textit{window}?. It returns a positive integer, the number of milliseconds since the last time the user interacted with the system. If the -displayof option is given then the return value refers to the display of \textit{window}; otherwise it refers to the display of the application's main window.

If querying the user inactive time is not supported by the system, \textbf{tk inactive} will return -1.

If the literal string \textbf{reset} is given as an additional argument, the timer is reset and an empty string is returned.

\begin{quote}
\textbf{tk} \textbf{inactive} ?\textbf{-displayof} \textit{window}? ?\textbf{reset}?
\end{quote}

\subsection{C API}

long \textbf{Tk\_GetUserInactiveTime}(\textit{display})
\begin{description}
\item[Display *display (in)]
used to determine which display to query for user inactive time.
\end{description}

\textbf{Tk\_GetUserInactiveTime()} returns a positive integer, the number of milliseconds since the last time the user interacted with the system (note that this is not necessarily the time since the user interacted with the application.)

void \textbf{Tk\_ResetUserInactiveTime}(\textit{display})
\begin{description}
\item[Display *display (in)]
used to determine on which display the user inactivity timer is to be reset.
\end{description}

\section{Safe Interpreters}

User inactive time can be used for timing attacks and will not be made available in safe interpreters, \textbf{tk inactive} will return -1 in safe interpreters. Calling \textbf{tk inactive reset} in a safe interpreter will throw an error.

\section{Implementation Notes}

Windows 2000 and later have \textit{GetLastInputInfo} to obtain the information, earlier platforms do not have this symbol in user32.dll. This symbol will be dynamically obtained upon the first call of \textit{Tk\_UserInactiveTime()} on windows. If the symbol is not available, \textit{Tk\_UserInactiveTime()} will return -1. \textit{GetLastInputInfo()} has no notion of displays, and as a result the display argument is ignored. The behaviour of the command is unknown for terminal services, remote desktop, VNC, Citrix and other remote screen systems.

For X, this patch introduces two additional library dependencies --- libXext and libXss. The authors do not know if a similar situation to Windows could exist on the X Window System, where the build host has libXss, and yet not all installations for that platform have libXss. A proper solution for that scenario would require an additional TIP to export TclLoadFile, Tcl\_FSLoadFile is not sufficient, to resolve the symbols at runtime. (The other library, libXext, is virtually universally available.)

For Win9x, Microsoft has published example code at [\url{http://www.microsoft.com/msj/0200/c/c0200.aspx}].

\section{Reference Implementation}

A reference implementation is available as Patch \#1185731 on SourceForge[\url{http://sf.net/support/tracker.php?aid=1185731}].

\section{Comments}

[ Insert here please ]

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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