GRAphical Programming for Eiffel index contents

Chapter X. Adding Help System

HELP

This chapter describes how to add some help to your applications.


What is Windows help file

Under Microsoft Windows there is the special format for the help files. You can find a lot of such files with .hlp extension in the Windows directory or in the "binary" directories for almost all the commercial products made for Windows.

A Help file consists of topics - one or more pages of text information dedicated to a topic. Usually every help file has contents or index topics that contain a list of all topics available. The Help files are organized as hypertext systems - some keywords are highlighted and you can jump to the corresponded topics by clicking them.

The Help files can be created using some special tools such as Forehelp or Robohelp or can be designed manually using the Microsoft Help Compiler from the Microsoft Windows SDK. Look at any of these products for more information if you are interested.

See directory EXAMPLES\HELPEX\HELP for the sources of a simple help file project.

Now lets look at GRAPE's help supporting system.


HELP

It's a simple class which has only one feature - the creation procedure that takes as the parameter the name of a Windows help file.

HELP.make ( file_name : STRING )

Class APPLICATION has a reference to the application help file as the help attribute. This class has two features dedicated to help supporting.

APPLICATION.make_help : HELP

Redefine this feature to specify the help object you want to use.

make_help : HELP is
   do
     !!Result.make ("windows.hlp")
   end

Note Any Help file must be placed in the application directory or somewhere in the path.


APPLICATION.invoke_help ( topic_index : INTEGER)

Call this feature when you want to call the Windows help system on the particular topic specified by the topic_index parameter.

invoke_help ( CTX_FILEOPEN )

Note A Windows help file error message occurs if you specify an incorrect topic_index value.


When to call help?

You can invoke the help from any place in your application. It's a good style to add the Help button to the application dialogs, to add the Help menu item and to display your help when User presses the F1 key.

on_key_down ( key_code : INTEGER ) : INTEGER is
   do
     if key_code = keyboard.VK_F1 then
       invoke_help ( context )
     end
   end;

on_clicked ( tile : TILE ) : INTEGER is
   do
     if tile.context = CTX_HELP_BUTTON then
       invoke_help ( CTX_SETUP_DIALOG )
     end
   end;

What else?

There are two additional components of any professional help system - hint strings on the status bar and hint messages for the speedbar buttons. See the chapters dedicated to speedbar and statusline for more information. The complete example of a help system is contained in the /EXAMPLES/HELPEX directory.


© Object Tools -- info@object-tools.com -- December 1999