\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#167: Add a New Option for Context Help for Windows}
\date{November 19, 2003}
\author{Ramon Rib\'{o}}
\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 \#167}&\textbf{Add a New Option for Context Help for Windows}\\\hline
Author&

Ramon Rib\'{o} \tipmail{ramsan}{cimne.upc.es}
\\
Created&Wednesday, \(\text{19}^{\text{th}}\) November 2003\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.9 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes adding a new option to \textbf{wm attributes} for the Windows version of Tk that offers contextual help in that window. Additionally, a new event type \textbf{\tiplangle{}Help\tiprangle{}} is defined, that will be delivered when the user picks the Help button in the window and picks over a widget. The event will be also hitted when user presses F1 over one window.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

Contextual help is very important in a program to help users to interactively learn to use the software capabilities. Windows offers a powerful mechanism to facilite the implementation of this contextual help but current versions of Tk do not take advantage of this feature. The feature cannot be implemented as an extension as a new event type is needed so as to be informed from the OS that the user has chosen to ask for help over that widget.

This contextual help is offered in the following way: when a window is configured to have this option, a small question mark button is displayed in the window title bar near the close button. If users pick that button, a question mark cursor is actived and the user can pick a widget (or location in a widget.) The typical program reaction to this is to offer a pop-up window with some short help text or to open the program help in the relevant section.

Additionally, the new proposed event \textbf{\tiplangle{}Help\tiprangle{}} can also get information when user presses key F1 over one window.

This implementation is proposed for the Windows OS only, though in the future some Window Managers like KDE (in Linux) have the same feature and could be also implemented. In any case, this TIP only proposes implementation on Windows.

\section{Specification}

A new option will be added to \textbf{wm attributes} with the following syntax:

\begin{quote}
\textbf{wm attributes} \textit{window} \textbf{-contexthelp} ?\textit{boolean}?
\end{quote}

If set and if the window is transient, the question mark button will appear in the window title bar.

A new event \textbf{\tiplangle{}Help\tiprangle{}} is added to the event list so as a user can do:
\begingroup\small\begin{verbatim}
  bind $w <Help> {puts "You pressed widget %W"}
\end{verbatim}
\endgroup

This event will hit in two situations: when the user presses the question mark in the title bar of the window and pick a widget; and when user presses the F1 key (or other platform-defined help key) over one window (this latter case only for bindings in the toplevel).

The event will support the usual \%W \%x \%y substitutions and other values.

\section{Reference Implementation}

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

\section{Comments}

It would be preferable to use a virtual event \textit{'\tiplangle{}\tiplangle{}Help\tiprangle{}\tiprangle{}} instead of extending the set of X events. (In particular, adding a new \textbf{\tiplangle{}Help\tiprangle{}} event means there has to be a new \textbf{HelpMask} bit flag to select for it, and we're running out of event mask bits).

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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