Author:         Ramon Ribó <ramsan@cimne.upc.es>
State:          Draft
Type:           Project
Vote:           Pending
Created:        19-Nov-2003
Post-History:   
Tcl-Version:    8.7

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 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 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 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 <>_ instead of extending the set of X events. (In particular, adding a new ** 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