Context-Sensitive Help

This chapter describes how to provide context-sensitive help in your application:

• Referring to help topics
• Connecting help to widgets
• Accessing help from your code

For information about creating help files for use with the helpviewer, see “Creating Help Files” in the helpviewer topic in the QNX Neutrino Utilities Reference.

Referring to help topics

The Helpviewer understands two distinct ways of specifying the location of the HTML help text to be displayed:

• Universal Resource Locator (URL)
• topic path

Universal Resource Locator (URL)

A URL specifies the filesystem path of the help-text file. It specifies this path in the standard HTML way, except that all files must reside on the local network. Here's a sample URL:

$QNX_TARGET/usr/help/product/photon/prog_guide/window_mgmt.html
      

---

URLs are case-sensitive. These URLs are restricted in scope to the help files; they can't be used to access the web.

---

Topic path

A topic path is a group of concatenated topic titles that are defined in the current topic tree. For example, here's the equivalent topic path to the above URL:

/Photon microGUI/Programmer's Guide/Window Management
      

For the Helpviewer, the topic path is case-insensitive (unlike other HTML browsers) and may contain the wildcard characters * or ?, where * matches a string and ? matches a character. The first matching topic is selected.

A topic tree used by the Helpviewer must have at least three hierarchical levels: the top level is known as the bookshelf, the second level as the book set, and the third level as the book. A book may contain further levels of chapters and sections.

Entries in a bookshelf or book set should not contain any HTML, only .toc entries for the next level; help text should only be found in books.

Connecting help to widgets

You can display help information for a widget in the Helpviewer or in a help balloon. You can even use both methods in an application. For example, you could use a balloon for short explanations and the Helpviewer for more detailed help.

No matter which method you choose, you need to do the following in each of your application's windows:

1. Set Ph_WM_HELP in the Flags: Managed (Pt_ARG_WINDOW_MANAGED_FLAGS) resource.
2. Set Ph_WM_RENDER_HELP in the Flags: Render (Pt_ARG_WINDOW_RENDER_FLAGS) resource. This will add a ? icon to the window frame. The user can click on it, and then click on a widget, and the help information will be displayed.

   If using the ? icon isn't suitable for your application, see “Help without the ? icon” later in this chapter.

For more information, see the Window Management chapter.

Displaying help in the Helpviewer

To use the Helpviewer to display help information for a widget, do the following:

1. Optionally, specify the Help Root (Pt_ARG_WINDOW_HELP_ROOT) resource for each window in your application. This allows you to specify relative topic paths for widgets inside the window.

   ---

   Use a topic path, not a URL.

   ---

   The topic root should start with a slash (/), and should be the top of all topics for the window, usually taken from a TOC file in the /usr/help/product directory. For example:

   /Photon microGUI/User's Guide

2. For each widget in the window, fill in the Help Topic (Pt_ARG_HELP_TOPIC) resource. If you specified a topic root for the window, this topic path can be relative to the window's topic root. For example:

   Introduction

When the user clicks on the ? icon and selects the widget, the help information is displayed in the Helpviewer.

---

If you get an error message about a bad link when you ask for help for a widget, make sure that the topic path is correct.

---

Displaying help in a balloon

To use a balloon to display help information for a widget:

1. Put the text you want displayed in the balloon into the widget's Help Topic (Pt_ARG_HELP_TOPIC) resource.
2. Set the Pt_INTERNAL_HELP flag in the widget's Extended Flags (Pt_ARG_EFLAGS) resource.

When the user clicks on the ? icon, and selects the widget, the help information appears in a balloon.

Help without the ? icon

In many applications the ? icon in the window frame isn't suitable. However, you may still want to use the Photon Helpviewer for displaying help. For example:

• For touch screens, the window's ? icon may be too small.
• You may want the mouse pointer to change to the Help pointer when a key is pressed.

To get the mouse pointer to change to the Help pointer, forward the Ph_WM_HELP event to the window manager. The following code would be in a callback attached to a PtButton widget labeled Help:

int
help_cb( PtWidget_t *widget, ApInfo_t *apinfo,
         PtCallbackInfo_t *cbinfo )
{
    PhWindowEvent_t winev;

    memset( &winev, 0, sizeof(winev) );
    winev.event_f = Ph_WM_HELP;
    winev.rid = PtWidgetRid( window );
    PtForwardWindowEvent( &winev );

    return( Pt_CONTINUE );
}

---

The window must have Ph_WM_HELP set in the Managed Flags (Pt_ARG_WINDOW_MANAGED_FLAGS) resource. You must also fill in the Help Topic (Pt_ARG_HELP_TOPIC) resource for the widgets that have help, as outlined above.

---

Accessing help from your code

Use the following functions (described in the Photon Library Reference) to access help from your application's code—you don't need them if you're using the method described in “Connecting help to widgets”:

PtHelpUrl()

Display help for the URL.

PtHelpUrlRoot()

Set a URL root.

PtHelpTopic()

Display help for a topic path.

PtHelpTopicRoot()

Set a topic root.

PtHelpTopicTree()

Display help for the topic tree.

PtHelpSearch()

Search for a string.

PtHelpQuit()

Exit the Helpviewer.

---

PtHelpUrlRoot() and PtHelpTopicRoot() don't save the passed string, so don't free it until you're finished using the help root.

---