TIP #167: Add a New Option for Context Help for Windows
_____________________________________________________________________________
TIP:	167
Title:	Add a New Option for Context Help for Windows
Version:	$Revision: 1.9 $
Authors:	Ramon Ribó <ramsan@cimne.upc.es>
State:	Draft
Type:	Project
Tcl-Version:	8.7
Vote:	Pending
Created:	Wed Nov 19 00:00:00 UTC 2003
Abstract
This TIP proposes adding a new option to wm attributes for the Windows version of Tk that offers contextual help in that window. Additionally, a new event type <Help> 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.
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 <Help> 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.
Specification
A new option will be added to wm attributes with the following syntax:
wm attributes window -contexthelp ?boolean?
If set and if the window is transient, the question mark button will appear in the window title bar.
A new event <Help> is added to the event list so as a user can do:
  bind $w <Help> puts "You pressed widget %W"
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.
Reference Implementation
http://sf.net/tracker/?func=detail&atid=312997&aid=845248&group_id=12997
Comments
It would be preferable to use a virtual event '<<Help>> instead of extending the set of X events. (In particular, adding a new <Help> event means there has to be a new HelpMask bit flag to select for it, and we're running out of event mask bits).
Copyright
This document has been placed in the public domain.
_____________________________________________________________________________
Colophon
TIP AutoGenerator - written by Donal K. Fellows