Application Techniques



Implementing Context-Sensitive Help

How to provide context-sensitive help when the user presses the F1 key and how to customize the way help is presented.

About this technique

Details

Category

Java Client Techniques> General techniques for controls

Description

You'll learn about:

You can run this technique code from:

Related reading

See the section on context-sensitive help in the advanced form techniques chapter in the Programmer's Guide

The example frmHelpTest has help information for the form as well as specific help for several controls. When the user presses F1, a page from the database is displayed in the browser or in a custom help dialog.

The table lists the form and controls, and their help pages. These pages are specified for the Help Page property in the Property Inspector.

Control

Help page

Form

pgHelpEmplForm.html

List1 list box

pgHelpListBox.html

stateid combobox

pgHelpState.html

uscitizen check box

pgHelpCitizen.html

deptid combobox

pgHelpListBox.html

rbtDefault radio button

pgHelpOnHelp.html

rbtCustom radio button

pgHelpOnHelp.html

It also provides two ways to display the help:

The custom dialog is a form called dialogHelp. It is a simple alternative to the default browser. You can program a custom help system for your application by implementing the processHelp() method in the form.

Changing the help information for a control   Top of page

This code for the valueChanged event of the list box changes the help page according to the item in the list that the user has selected. These help topics are called pgHelpItem1.html, pgHelpItem2.html, and so on. This event does not display the help; it changes the help page to be displayed when the user presses F1.

  private void handle_List1_valueChanged(AgoPropertyChangeEvent evt) 
  { 
     int index = List1.getSelectedIndex(); 
     if (index > -1) 
     { 
        int item = index + 1; 
        List1.setHelpInfo("pgHelpItem" + item + ".html"); 
     }  
     else 
     { 
        List1.setHelpInfo("pgHelpListBox.html"); 
     } 
  } 

Notes on the code

Implementing a custom help display   Top of page

When the custom help radio button is selected and the user presses F1, this method displays a dialog with and editor pane that displays the help page. The example avoids displaying more than one version of the dialog. If the user doesn't close the dialog, then when the user asks for help again, the code substitutes a new help page into the dialog.

  public boolean processHelp(Object obj, String sHelpPage) 
  { 
     if (b_defaultHelp == true) return false; 
     if (sHelpPage == null) return false; 
     try 
     { 
        if (dlgHelp == null) 
        { 
           dlgHelp = (com.sssw.gen.forms.dialogHelp)             agDialog.getForm("dialogHelp"); 
        } 
   
        dlgHelp.EditorPane1.setPage( 
              agGeneral.getDatabaseURL().toString() + 
              "SilverStream/Pages/" + sHelpPage); 
        dlgHelp.EditorPane1.setEditable(false); 
   
        if (b_dlgHelpVisible == false) 
        { 
           agDialog.showForm("Help", dlgHelp, 
                 agDialog.FORM_MODELESS, true, 50,50); 
           set_dlgHelpVisible(true); 
        } 
        return true; 
     }  
     catch (java.io.IOException e) 
     { 
        ... 
     } 
  } 

Notes on the code






Copyright © 2000, SilverStream Software, Inc. All rights reserved.