Accessing Help from OPL ApplicationsSummary: This article explains how OPL applications can correctly manage help files.
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":
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.
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
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
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.
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.