Home>>Programming>>C++Builder>> » How to Implement IExtendedHelpViewer and IHelpSelector in C Builder

How to Implement IExtendedHelpViewer and IHelpSelector in C Builder

Last Updated on September 13, 2018 By hcyaobin

Implementing IExtendedHelpViewer

ICustomHelpViewer only provides direct support for keyword-based Help. Some Help systems (especially WinHelp) work by associating numbers (known as context IDs) with keywords in a fashion which is internal to the Help system and therefore not visible to the application. Such systems require that the application support context-based Help in which the application invokes the Help system with that context, rather than with a string, and the Help system translates the number itself.

Applications written in the VCL or CLX can talk to systems requiring context-based Help by extending the object that implements ICustomHelpViewer to also implement IExtendedHelpViewer. IExtendedHelpViewer also provides support for talking to Help systems that allow you to jump directly to high-level topics instead of using keyword searches. The built-in WinHelp viewer does this for you automatically.
IExtendedHelpViewer exposes four functions. Two of them–UnderstandsContext and DisplayHelpByContext–are used to support context-based Help; the other two–UnderstandsTopic and DisplayTopic–are used to support topics.

When an application user presses F1, the Help Manager calls

int__fastcallIExtendedHelpViewer::UnderstandsContext(const int ContextID, AnsiString HelpFileName)

and the currently activated control supports context-based, rather than keyword-based Help. As with ICustomHelpViewer::UnderstandsKeyword(), the Help Manager queries all registered Help viewers iteratively. Unlike the case with ICustomHelpViewer::UnderstandsKeyword(), however, if more than one viewer supports a specified context, the first registered viewer with support for a given context is invoked.
The Help Manager calls

void__fastcallIExtendedHelpViewer::DisplayHelpByContext(const int ContextID, AnsiString
HelpFileName)

after it has polled the registered Help viewers.
The topic support functions work the same way:

bool__fastcallIExtendedHelpViewer::UnderstandsTopic(const AnsiString Topic)

is used to poll the Help viewers asking if they support a topic;

void__fastcallIExtendedHelpViewer::DisplayTopic(const AnsiString Topic)

is used to invoke the first registered viewer which reports that it is able to provide help for that topic.

Implementing IHelpSelector

IHelpSelector is a companion to ICustomHelpViewer. When more than one registered viewer claims to provide support for a given keyword, context, or topic, or provides a table of contents, the Help Manager must choose between them. In the case of contexts or topics, the Help Manager always selects the first Help viewer that claims to provide support. In the case of keywords or the table of context, the Help Manager will, by default, select the first Help viewer. This behavior can be overridden by an application.

To override the decision of the Help Manager in such cases, an application must register a class that provides an implementation of the IHelpSelector interface. IHelpSelector exports two functions: SelectKeyword, and TableOfContents. Both take as arguments a TStrings containing, one by one, either the possible keyword matches or the names of the viewers claiming to provide a table of contents. The implementor is required to return the index (in the TStringList) that represents the selected string; the TStringList is then freed by the Help Manager.

Note: The Help Manager may get confused if the strings are rearranged; it is recommended that implementors of IHelpSelector refrain from doing this. The Help system only supports one HelpSelector; when new selectors are registered, any previously existing selectors are disconnected.

Add a Comment

Your email address will not be published. Required fields are marked *