TIP: 167
Title: Add a New Option for Context Help for Windows
Version: $Revision: 1.5 $
Author: Ramon Rib� <[email protected]>
State: Draft
Type: Project
Vote: Pending
Created: 19-Nov-2003
Post-History:
Tcl-Version: 8.5
~ 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.