Context-Sensitive Help

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

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

Creating help text

To create help text to be read by the Photon Helpviewer, you'll need two types of files:

• the actual help files
• table-of-contents files

Help files

The help files are written in HTML, and have .html as an extension. The Helpviewer supports the following tags (with attributes):

The Helpviewer supports only GIF and BMP images.

The Helpviewer also supports the standard HTML1/ISO entities for characters, plus:

Table-of-content files

Table-of-contents (TOC) files define the list of products that have help information, and the hierarchy of topics for each product. They have .toc as a file extension.

All these have to be under the /usr/help/product directory. Each product has a level-1 TOC file, and a directory with everything else. For example, Photon help includes:

photon.toc
photon/

The photon.toc file consists of the following line:

1|Photon microGUI|./photon/bookset.html

where:

1

is the level in the topic hierarchy

|

delimits fields

Photon microGUI

is a topic title

./photon/bookset.html

is the Universal Resource Locator (URL) of the bookset description

Don't use the vertical bar (|) in topic titles, because it's used as a delimiter in the TOC files.

The photon directory contains a TOC file and a directory for each book. For example, it includes:

prog_guide.toc
prog_guide/

The prog_guide.toc file is similar to photon.toc:

2|Programmer's Guide|./prog_guide/about.html

The prog_guide directory contains the HTML files, and a book.toc file that identifies the topic titles in the HTML files:

3|About This Guide|about.html#ABOUTTHISGUIDE
4|Assumptions|#id3
4|Changes and corrections|#ChangesAndCorrections
3|Introduction|intro.html#id1
4|Photon Application Builder - PhAB|#PhABApplications
6|Get immediate results|#id3
...

The part of the URL following the # is an anchor defined in the HTML.

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)

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:

/usr/help/product/photon/run_inst/pdm.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

Composed of the 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/Installation & Configuration/pdm
      

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":

PxHelpUrl()

Display help for the URL.

PxHelpUrlRoot()

Set a URL root.

PxHelpTopic()

Display help for a topic path.

PxHelpTopicRoot()

Set a topic root.

PxHelpTopicTree()

Display help for the topic tree.

PxHelpSearch()

Search for a string.

PxHelpQuit()

Exit the Helpviewer.

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