Progress
Language Reference


SYSTEM-HELP Statement

Interfaces
OS
SpeedScript
All
Windows only
No

The SYSTEM-HELP statement calls the Microsoft Windows Help engine to display Windows Help topics, and the HTML Help engine to display HTML Help topics.

SYNTAX

SYSTEM-HELP file-string
  [ WINDOW-NAME window-name ]
  {   CONTEXT int-expr
    | CONTENTS
    | SET-CONTENTS int-expr
    | FINDER
    | CONTEXT-POPUP int-expr
    | KEY string
    | PARTIAL-KEY string
    | MULTIPLE-KEY char TEXT string
    | COMMAND string
    | POSITION X x Y y WIDTH dx HEIGHT dy
    | POSITION MAXIMIZE
    | FORCE-FILE
    | HELP
    | QUIT
    | HELP-TOPIC string
    | ALTERNATE-KEY string
  } 

file-string

The file-string parameter is a character expression that specifies the pathname of a help file. If the file has a .hlp file extension, the Microsoft Windows Help viewer is launched. If the file has a .chm extension (the extension for compiled Microsoft HTML Help files), the Microsoft HTML Help viewer is launched.

WINDOW-NAME window-name

The window-name parameter is a character expression that evaluates to the primary or secondary window name as defined in the [WINDOWS] section of the help project file. If the window name is omitted, or if “main” is specified, the primary help window is used.

This option is supported for Windows Help only.

CONTEXT int-expr

Displays the help topic that the context number identifies. You define context numbers in the [MAP] section of the help project file.

The int-expr parameter is the context number for the help topic.

CONTENTS

For Windows Help, this option displays the help topic defined as the contents in the [OPTIONS] section of the help project file.

For HTML Help, this option displays the Microsoft HTML Help viewer with the default topic in the content pane. Use the HELP-TOPIC option to specify the topic to display.

Progress supports this option for backward compatibility only.

SET-CONTENTS int-expr

Dynamically re-maps the contents help topic from what is defined in the [OPTIONS] section of the help project file. When a CONTENTS call is made, the new contents help topic is displayed.

The int-expr parameter is the context number for the new contents help topic.

This option is supported for Windows Help only. Progress supports this option for backward compatibility only.

FINDER

Displays the Help Topics: Windows Help Topics dialog box, which contains an Index Tab, a Find Tab, and optionally a Contents Tab, with the most recently used tab displayed on top.

If a Contents Tab file (.CNT file) is present when you initially call the Help Topics: Windows Help dialog box, then the Content Tab displays on top. However, if a .CNT file is not present, then the dialog box displays with the Index Tab on top; the Contents Tab is not available.

This option is supported for Windows Help only.

CONTEXT-POPUP int-expr

Displays the help topic in a pop-up window that the context number identifies. You define context numbers in the [MAP] section of the help project file.

The int-expr parameter is the context number for the help topic.

This option is supported for Windows Help only.

KEY string

For Windows Help, this option displays the help topic matching the string found in the index keyword list. If there is more than one match, it displays the first topic containing the keyword. If there is no match or the string is omitted, a message is displayed indicating that the keyword is invalid. The string parameter is a character expression that evaluates to a keyword for the desired help topic.

For HTML Help, this option displays the topic matching the string found in the keyword index. Use semicolons in the string parameter to delimit multiple keywords. If no match is found, Microsoft HTML Help displays the help viewer with the Index tab on top.

PARTIAL-KEY string

Displays the help topic matching the string found in the keyword list. On Windows, if there is more than one match, no match, or if the string is omitted, it displays the Help Topics: Window Help Topics dialog box with the Index Tab on top.

The string parameter is a character expression that evaluates to a partial key for the desired help topic.

This option is supported for Windows Help only.

MULTIPLE-KEY char TEXT string

Displays the help topic matching a keyword from an alternate keyword table.

The char parameter is a character expression that evaluates to the single character keyword table identifier for the required table.

The string parameter is a character expression that evaluates to the keyword that is located in the keyword table.

This option is supported for Windows Help only. For HTML Help, see the ALTERNATE-KEY option.

COMMAND string

Executes a help macro. For more information on help macros, see the Progress Help Development Guide.

The string parameter is a character expression that evaluates to the help macro to execute.

This option is supported for Windows Help only.

POSITION X x Y y WIDTH dx HEIGHT dy

Displays and positions the help window as specified.

The x parameter is an integer expression that specifies the x coordinate for the help window.

The y parameter is an integer expression that specifies the y coordinate for the help window.

The dx parameter is an integer expression that specifies the width of the help window.

The dy parameter is an integer expression that specifies the height of the help window.

POSITION MAXIMIZE

Displays and maximizes the help window.

FORCE-FILE

Ensures that the correct help file is open and displayed.

This option is supported for Windows Help only.

HELP

Displays the contents of the Progress Help-on-Help file. On Windows, HELP displays the Help Topics: Windows Help Topics dialog box.

This option is supported for Windows Help only.

QUIT

Informs the help application that help is no longer required. If no other applications are using help, the operating system closes the help application.

HELP-TOPIC string

Displays a help topic in the content pane of the Microsoft HTML Help viewer.

The string parameter is a character expression that indicates the topic (.htm/.html file) within the compiled Microsoft HTML Help (.chm) file to display.

This option is supported for HTML Help only.

ALTERNATE-KEY string

Displays a help topic matching the string found in the alternate keyword index.

The string parameter is a character expression that evaluates to a keyword in the alternate keyword index.

This option is supported for HTML Help only. For Windows Help, see the MULTIPLE–KEY option.

EXAMPLE

The following example demonstrates several features of the SYSTEM-HELP statement. This procedure displays buttons for each of the following SYSTEM-HELP parameters: FINDER, CONTENTS, CONTEXT, PARTIAL-KEY, HELP, and QUIT.

To execute this procedure, first copy the editeng.hlp and editeng.cnt files from DLC\prohelp to your current working directory. Then run the Procedure Editor and open r-syshlp.p.

When you run r-syshlp.p and select each button, you will experience the behavior defined for each parameter as described in the earlier part of this SYSTEM-HELP Statement section. For example, when you select the FINDER button, the Windows Help:Help Topics dialog box displays in its most recently used state. When you select the CONTENTS button, the main contents help topic displays. When you select the CONTEXT button, the help topic associated with the specific context number of a help topic (in this example, number 49154) displays, and so forth.

r-syshlp.p
/* r-syshlp.p */

DEFINE VAR helpfile as CHAR.

DEFINE BUTTON b_help LABEL "FINDER Call".
DEFINE BUTTON b_h6 LABEL "CONTENTS Call".
DEFINE BUTTON b_h5 LABEL "CONTEXT Call".
DEFINE BUTTON b_h4 LABEL "PARTIAL-KEY Call-’’".
DEFINE BUTTON b_h3 LABEL "PARTIAL-KEY Call-’Tools’".
DEFINE BUTTON b_h2 LABEL "PARTIAL-KEY Call-’Tools Menu’".
DEFINE BUTTON b_h1 LABEL "HELP Call".
DEFINE BUTTON b_quit LABEL "QUIT Call".

FORM 
    skip(1) space(1) b_help space(1)
    skip(1) space(1) b_h6 space(1)
    skip(1) space(1) b_h5 space(1)
    skip(1) space(1) b_h4 space(1)
    skip(1) space(1) b_h3 space(1)
    skip(1) space(1) b_h2 space(1)
    skip(1) space(1) b_h1 space(1)
    skip(1) space(1) b_quit space(1)
    skip(1) WITH FRAME x.
ENABLE ALL WITH FRAME x.

helpfile = "editeng.hlp".
 
/* The FINDER call brings up the Help Topics dialog box in its most 
   recently used state. */
ON CHOOSE OF b_help IN FRAME x
DO:
    SYSTEM-HELP helpfile FINDER.
END.

/* The CONTENTS call displays the main contents help topic. This 
   is for backward compatability with Windows 3.x. */
ON CHOOSE OF b_h6 IN FRAME x
DO:
    SYSTEM-HELP helpfile CONTENTS.
END.

/* The CONTEXT call displays the help topic associated with the
   specified context number of a help topic (in this case, 49154). */
ON CHOOSE OF b_h5 IN FRAME x
DO:
    SYSTEM-HELP helpfile CONTEXT 49154.
END. 
/* The PARTIAL-KEY call brings up the Help Topics dialog box with
   the Index tab on top. When the string parameter is empty or is 
   omitted altogether, the fill-in at the top of the Index tab is left blank.*/
ON CHOOSE OF b_h4 IN FRAME x
DO:
    SYSTEM-HELP helpfile PARTIAL-KEY "".
END.

/* In a PARTIAL-KEY call where the string parameter does not exactly
   match an index keyword of any help topic, the fill-in at the top
   of the Index tab is populated with the string that is passed in, 
   and no help topic is automatically displayed. */
ON CHOOSE OF b_h3 IN FRAME x
DO:
    SYSTEM-HELP helpfile PARTIAL-KEY "Tools".
END.

/* In a PARTIAL-KEY call where the string parameter exactly
   matches a unique index keyword of a help topic, the help engine 
   automatically launches a help viewer window and displays 
   the matching topic. */
ON CHOOSE OF b_h2 IN FRAME x
DO:
    SYSTEM-HELP helpfile PARTIAL-KEY "Tools Menu".
END.

/* The HELP call brings up the Help Topics dialog box for the help file 
   that explains how to use Windows Help (winhlp32.hlp). */
ON CHOOSE OF b_h1 IN FRAME x
DO:
    SYSTEM-HELP helpfile HELP.
END.

/* The QUIT call causes the help engine to terminate, unless another
   application is using help. */
ON CHOOSE OF b_quit IN FRAME x
DO: 
    SYSTEM-HELP helpfile QUIT.
    RETURN.
END.    

WAIT-FOR GO OF FRAME x. 

NOTES

SEE ALSO

FILE-INFO System Handle, SEARCH Function


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095