TIP 167: Add a New Option for Context Help for Windows

EuroTcl/OpenACS 11 - 12 JULY 2024, VIENNA
Author:         Ramon Rib√≥ <[email protected]>
State:          Rejected
Type:           Project
Vote:           Done
Created:        19-Nov-2003
Tcl-Version:    9.0
Tk-Branch:      tip-167
Vote-Summary:   Rejected 1/2/1
Votes-For:      KW
Votes-Against:  FV, JN
Votes-Present:  SL


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.


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.


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 virtual 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

Tk branch tip-167 or Sourceforge #145


It is 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).


This document has been placed in the public domain.