Name 

Description 

Asking the Help Manager for Information 

Help viewers communicate with the Help Manager through the IHelpManager interface, an instance of which is returned to them when they register with the Help Manager. IHelpManager allows the Help viewer to communicate four things:

• A request for the window handle of the currently active control.
• A request for the name of the Help file which the Help Manager believes should contain help for the currently active control.
• A request for the path to that Help file.
• A notification that the Help viewer is shutting itself down in response to something other than a request from the Help Manager that... more 

Calling a Help System Directly 

For additional Help system functionality not provided by VCL applications, TApplication provides a read-only property that allows direct access to the Help system. This property is an instance of an implementation of the interface IHelpSystem. IHelpSystem and IHelpManager are implemented by the same object, but one interface is used to allow the application to talk to the Help Manager, and one is used to allow the Help viewers to talk to the Help Manager. 

Communicating with the Help Manager 

The ICustomHelpViewer provides four functions that can be used to communicate system information with the Help Manager:

• GetViewerName
• NotifyID
• ShutDown
• SoftShutDown

The Help Manager calls through these functions in the following circumstances:

• ICustomHelpViewer.GetViewerName : String is called when the Help Manager wants to know the name of the viewer (for example, if the application is asked to display a list of all registered viewers). This information is returned via a string, and is required to be logically static (that is, it cannot change during the operation of the application). Multibyte character sets are not supported.
• ICustomHelpViewer.NotifyID(const ViewerID: Integer) is called... more 

Customizing the IDE Help System 

The IDE supports multiple Help viewers in exactly the same way that a VCL application does: it delegates Help requests to the Help Manager, which forwards them to registered Help viewers. The IDE makes use of the same WinHelpViewer that the VCL uses.
The IDE comes with two Help viewers installed: the HyperHelp viewer, which allows Help requests to be forwarded to HyperHelp, an external WinHelp emulator under which the Kylix Help files are viewed, and the Man page viewer, which allows you to access the Man system installed on most Unix machines. Because it is necessary for Kylix... more 

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. 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... more 

Displaying Tables of Contents 

ICustomHelpViewer provides two methods relating to displaying tables of contents:

• CanShowTableOfContents
• ShowTableOfContents

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 : Boolean 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... more 

Enabling Help in Applications 

VCL applications support displaying Help using an object-based mechanism that allows Help requests to be passed on to one of multiple external Help viewers. To support this, an application must include a class that implements the ICustomHelpViewer interface (and, optionally, one of several interfaces descended from it), and registers itself with the global Help Manager.
VCL applications provide an instance of TWinHelpViewer, which implements all of these interfaces and provides a link between applications and WinHelp.
The Help Manager maintains a list of registered viewers and passes requests to them in a two-phase process: it first asks each viewer... more 

Help System Interfaces 

The Help system allows communication between your application and Help viewers through a series of interfaces. These interfaces are all defined in the HelpIntfs.pas, which also contains the implementation of the Help Manager.
ICustomHelpViewer provides support for displaying Help based upon a provided keyword and for displaying a table of contents listing all Help available in a particular viewer.
IExtendedHelpViewer provides support for displaying Help based upon a numeric Help context and for displaying topics; in most Help systems, topics function as high-level keywords (for example, "IntToStr" might be a keyword in the Help system, but "String manipulation... more 

How TApplication Processes VCL Help 

TApplication in the VCL provides four methods that are accessible from application code:
Help methods in TApplication  

How VCL Controls Process Help 

All VCL controls that derive from TControl expose several properties that are used by the Help system: HelpType, HelpContext, and HelpKeyword.
The HelpType property contains an instance of an enumerated type that determines if the control's designer expects help to be provided via keyword-based Help or context-based Help. If the HelpType is set to htKeyword, then the Help system expects the control to use keyword-based Help, and the Help system only looks at the contents of the HelpKeyword property. Conversely, if the HelpType is set to htContext, the Help system expects the control to use... more 

Implementing ICustomHelpViewer 

The ICustomHelpViewer interface contains three types of methods: methods used to communicate system-level information (for example, information not related to a particular Help request) with the Help Manager; methods related to showing Help based upon a keyword provided by the Help Manager; and methods for displaying a table of contents.
For information on ICustomHelpViewer methods, see

• Communicating with the Help Manager
• Displaying keyword-based Help
• Asking the Help Manager for information

 

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 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... more 

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... more 

Registering Help System Objects 

For the Help Manager to communicate with them, objects that implement ICustomHelpViewer, IExtendedHelpViewer, ISpecialWinHelpViewer, and IHelpSelector must register with the Help Manager.
To register Help system objects with the Help Manager, you need to:

• Register the Help viewer.
• Register the Help Selector.

 

Using Help in a VCL Application 

The following sections explain how to use Help within a VCL application.

• How TApplication Processes VCL Help
• How VCL controls process Help
• Calling a Help system directly
• Using IHelpSystem

 

Using IHelpSystem 

IHelpSystem allows an application to do three things:

• Provides path information to the Help Manager.
• Provides a new Help selector.
• Asks the Help Manager to display Help.

Providing path information is important because the Help Manager is platform-independent and Help system-independent and so is not able to ascertain the location of Help files. If an application expects Help to be provided by an external Help system that is not able to ascertain file locations itself, it must provide this information through the IHelpSystem's ProvideHelpPath method, which allows the information to become available through the IHelpManager's GetHelpPath method. (This information propagates... more