Common Desktop Environment: Help System Author's and Programmer's Guide

Programmer's Job

As a programmer, you add code into your application so that when a user requests context-sensitive help, the application displays help information that is relevant to what the application is doing at that time.

Note -

The/usr/dt/share/examples/dthelp directory contains source code for a sample program called dthelpdemo. It demonstrates how to add help dialogs to an OSF/Motif application.

Consider How Your Help Is Accessed

Providing useful information to the user requires considering the following:

Collaborate with the Help Author

Close collaboration with the online help author is needed because the author needs to know how each context-specific topic is reached and the programmer needs to know what is explained in each context-specific topic. Without such coordination, the user may see irrelevant, ambiguous, or misleading information.

Collaboration makes the best use of the programmer's understanding of the application and the author's understanding of how to best communicate relevant information to the user.

Identify Help Entry Points

An application provides online help by establishing help entry points. Entry points are defined in the application and associated with specific help topics. Each of the ways that a user can request help--the Help key, button, or menu--represent entry points. For example, consider an application with a Print dialog box that has a Help button. The author writes a help topic that describes the contents of the dialog box and supplies you with the ID of the topic. You can then associate the ID of the help topic with the Help button using a callback routine.

Create and Manage Help Dialogs

The Help System application program interface is designed especially for use with OSF/Motif applications. Specifically, Help extends the OSF/Motif widget set by providing two new widget classes (plus convenience functions to manipulate them):

You can use either or both of these types of help windows within your application. Once the application is compiled (with the Help library), the help windows become part of the application.

Chapter 9, Creating and Managing Help Dialog Boxes, describes the general help and quick help dialog boxes.

Package and Distribute Help

Your product package includes both the run-time help file (volume.sdl) and its graphics files. Additionally, you can provide a help family file that enables your volume to be viewed using the Front Panel Help Viewer.

If the help volume uses execution links, you should collaborate with the author to include the appropriate execution link resources in your application's application defaults file. Chapter 13, Preparing an Installation Package, discusses which help files are delivered with your application.