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.
CLX: Numeric help contexts are the default form of Help requests in applications running under Windows, which use the WinHelp system; while CLX supports them, they are not recommended for use in CLX applications because most Linux Help systems do not understand them.
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:
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.
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.
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 UnderstandsKeyword is invoked first.
Displaying tables of contents
ICustomHelpViewer provides two methods relating to displaying tables of contents:
The theory behind their operation is similar to the operation of the keyword Help request functions: the Help Manager first queries all Help viewers by calling ICustomHelpViewer::CanShowTableOfContents() and then invokes a particular Help viewer by calling ICustomHelpViewer::ShowTableOfContents().
It is reasonable for a particular viewer to refuse to allow requests to support a table of contents. The Man page viewer does this, for example, because the concept of a table of contents does not map well to the way Man pages work; the HyperHelp viewer supports a table of contents, on the other hand, by passing the request to display a table of contents directly to HyperHelp on Linux and WinHelp on Windows. It is not reasonable, however, for an implementation of ICustomHelpViewer to respond to queries through CanShowTableOfContents with the answer true, and then ignore requests through ShowTableOfContents.