context-sensitive-help

Arguments: owner-window dialog-item-or-window

This generic function is called whenever the user presses the F1 key, typically to receive context-sensitive help. It is also called if the user clicks the question mark button on the title-bar of a window that has been given the help-button property, and then clicks a dialog-item or child window in the window that has the question mark button. An application can add context-sensitive-help methods in order to handle these gestures and present help to the user.

The built-in Common Graphics methods do nothing, though the Tools | Options dialog in the IDE has the help-button property and implements a context-sensitive-help method to show HTML help on the configuration option represented by the selected widget.

When F1 is pressed, owner-window will be the owner window or screen of the window that currently has the keyboard focus. If the focus is in a dialog-item's widget-window or lisp-widget-window, then dialog-item-or-window will be that dialog-item object (rather than its window); otherwise dialog-item-or-window will be the actual child window that has the keyboard focus.

When the question mark button is used instead, owner-window will be the owner window or screen of the dialog-item or child window on which the user clicks. If the user clicks on a dialog-item of the window that has the question mark button, then dialog-item-or-window will be that dialog-item object (rather than its window); otherwise dialog-item-or-window will be the actual child window that the user clicks. (After clicking the question mark button, if the user then clicks somewhere other than on a dialog-item or child window of the window that has the question mark button, or presses the Escape key, then the operation is cancelled and context-sensitive-help is not called.)

The owner-window is intended to be useful for specialization, so that the individual dialog-items or child windows do not all need to be subclassed.

If the F1 key is also handled as an event-synonym of a menu-item, or is handled by a virtual-key-down method, or is a global keyboard accelerator (see add-global-keyboard-accelerator), then that behavior is done in addition to context-sensitive-help being called, rather than one overriding the other.

Due to operating system design, it is unfortunately not possible to tell which action the user performed (either pressing F1 or using the question mark button).

Also due to operating system design, it is not possible to use the help-button property along with the minimize-button or maximize-button property; if both are specified or defaulted, the window will show the help button but will not be given the minimize or maximize buttons.

See cg-application-help.htm for various ways of displaying help in an application.

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.