Accessing Help from OPL Applications

Contents

• 1. Accessing Help from OPL Applications
• 2. Opening the Help File
• 3. Closing the Help file when the Application closes
• 4. How Help's 'Quick find' mode is supported
• 5. Acknowledgements

1. Accessing Help from OPL Applications

Databases created with the DATA application and given file extension ".hlp" will be opened in a special mode within the Data application for reading Help files. This includes having the 'Find', 'Print' and 'Go back' buttons.

These help files can be easily launched from within an OPL program. The following line of code will launch the help database "C:\RunHelp.hlp":

RunApp&:("DATA","C:\RunHelp.hlp","",0)

N.B. RunApp&: is an OPX procedure from System.opx

However, problems arise when your application tries to run multiple instances of the help file - you get an ‘In Use’ error. You can avoid this by finding out whether the help file is already running. There is an OPX procedure in SysRAM1.opx called:

threadId& = GetThreadIdFromCaption&:  (Caption$,BYREF Prev&)

This procedure allows you to find the thread id of an open instance of a help file (or any application with a caption). Another command, SETFOREGROUNDBYTHREAD&:(threadId&, Prev&), brings the thread to the foreground. The Prev& would be used to detect multiple instances, although only one copy of a particular help file would need to be open at any time.

Captions for a help file are as follows:

"Help - "+<helpFileName>

That is, Help followed by space, hyphen, space, then <helpFileName>, which is the name of your help file, excluding the drive, path and .hlp extension.

2. Opening the Help File

The following procedure could be used within your application to run the help file. Note that GHelpThrdID&, GHelpLocation$ and GHelpFile$ are global variables defined elsewhere within your application. For example, if your help file is at "D:\System\Apps\MyApp\MyApp.hlp", GHelpLocation$ would be "D:\System\Apps\MyApp\", and GHelpFile$ would be "MyApp".

PROC HELP%:
 	EXTERNAL GHelpThrdID&, GHelpFile$, GHelpLocation$
 	LOCAL Prev&
 	IF EXIST(GHelpLocation$+GHelpFile$+".hlp")
 		ONERR NotRunning::
 		GHelpThrdID&=0
 		GHelpThrdID& = GetThreadIdFromCaption&:
 ("Help - "+GHelpFile$, prev&)
 NotRunning::
 		ONERR OFF
 		IF GHelpThrdID&<>0	REM help already running
 			SETFOREGROUNDBYTHREAD&:(GHelpThrdID&,0)	
 REM Bring help to foreground
 		ELSE
 			GHelpThrdID&=RUNAPP&:
 ("Data",GHelpLocation$+GHelpfile$+".hlp","",0)	
 REM Run the help application
 		ENDIF
 	ELSE
 		gIPRINT "Cannot locate the help file", KBusyTopRight%
 	ENDIF
 ENDP

3. Closing the Help file when the Application closes

It is good practice to close the help file when your application is closed. To do this you should use the following code before exiting your application:

 ONERR ExitAnyway::
 
 IF GHelpThrdID& <> 0		
 REM If a program help thread is running
 
 		ENDTASK&:(GHelpThrdID&,0)
 REM end the task using its thread ID
 
 	ENDIF
 
 ExitAnyway::
 
 ONERR OFF

4. How Help's 'Quick find' mode is supported

The default OPL help file contains the following fields:

The ‘number field is used to control the order of the records. The applications field has the name of the application followed by a '!'. (e.g. If the user enters data!, Help will only display help references to data). The synonym field is a cross reference field.

When creating a help database, add all records then sort by number then title. Mark the number, applications and synonym fields as hidden.

You can use the Aleppo tool to create a help file in the correct format.

5. Acknowledgements

Symbian is a trademark of Symbian Ltd.

The Symbian Developer Network logo is a trademark of Symbian Ltd.

This paper refers to trademarks of third parties and Symbian recognizes their rights.

Back to opl-dev project homepage