Displaying Keyword-based Help

Help requests typically come through to the Help viewer as either keyword-based Help, in which case the viewer is asked to provide help based upon a particular string, or as context-based Help, in which case the viewer is asked to provide help based upon a particular numeric identifier.

Note: Numeric Help contexts are the default form of Help requests in applications running under Windows, which use the WinHelp system.

ICustomHelpViewer implementations are required to provide support for keyword-based Help requests, while IExtendedHelpViewer implementations are required to support context-based Help requests.

ICustomHelpViewer provides three methods for handling keyword-based Help:

UnderstandsKeyword
GetHelpStrings
ShowHelp

Copy Code

ICustomHelpViewer.UnderstandsKeyword(const HelpString: String): Integer

Copy Code

int__fastcall ICustomHelpViewer::UnderstandsKeyword(const AnsiString HelpString)

is the first of the three methods called by the Help Manager, which will call each registered Help viewer with the same string to ask if the viewer provides help for that string; the viewer is expected to respond with an integer indicating how many different Help pages it can display in response to that Help request. The viewer can use any method it wants to determine this—inside the IDE, the HyperHelp viewer maintains its own index and searches it. If the viewer does not support help on this keyword, it should return zero. Negative numbers are currently interpreted as meaning zero, but this behavior is not guaranteed in future releases.

Copy Code

ICustomHelpViewer.GetHelpStrings(const HelpString: String): TStringList

Copy Code

Classes::TStringList*__fastcall ICustomHelpViewer::GetHelpStrings(const AnsiString HelpString)

is called by the Help Manager if more than one viewer can provide Help on a topic. The viewer is expected to return a TStringList, which is freed by the Help Manager. The strings in the returned list should map to the pages available for that keyword, but the characteristics of that mapping can be determined by the viewer. In the case of the WinHelp viewer on Windows and the HyperHelp viewer on Linux, the string list always contains exactly one entry. HyperHelp provides its own indexing, and duplicating that elsewhere would be pointless duplication. In the case of the Man page viewer (Linux), the string list consists of multiple strings, one for each section of the manual which contains a page for that keyword.

Copy Code

ICustomHelpViewer.ShowHelp(const HelpString: String)

Copy Code

void__fastcall ICustomHelpViewer::ShowHelp(const AnsiString HelpString)

is called by the Help Manager if it needs the Help viewer to display help for a particular keyword. This is the last method call in the operation; it is guaranteed to never be called unless the UnderstandsKeyword method is invoked first.