Writing Standard OPMs

Author: Tim Richardson, Symbian Developer Network, Symbian Ltd.

Summary: OPMs are OPL Modules that have been written for other developers to use within their own applications. This article helps developers to write OPMs according to a standard set of rules.

We encourage developers to write their own OPMs and allow other members of the OPL community to use them. To help their wide acceptance some standards have been written which should be adhered to where possible.

List of OPMs.

Contents

• 1. File location - where the OPM files should be put on the Symbian device
• 2. OPM naming conventions
• 3. OPM loading within an application
• 4. Distributing the OPM in an installation file
• 5. Acknowledgements

1. File location - where the OPM files should be put on the Symbian device

The standard location of all OPMs is \System\OPM\ on any drive. This is also where you should put any other files required by the OPM; for instance, bitmap files or non-changeable data files.

For the developer, the header file (.OMH) should be put into \System\OPL\ directory on any drive. The developer can then include this file with the usual INCLUDE command.

2. OPM naming conventions

Each OPM should have its own unique name. When compiled, the resulting opmname.opo file should be renamed to opmname.opm. Any header files for use by the developer should be named opmname.omh. Within the code itself the procedures that can be used by another developer should start with the same set of characters followed by an underscore (_).

For example, the progress bar procedures all start with PC_. Any procedures which are for use internally by your own procedures, and which the developer does not have access to, should be named with a double underscore followed by the same set of characters as used above. For example, __PC_. This naming convention avoids procedure name clashing as much as is possible, and is therefore one which is important to adhere to.

3. OPM loading within an application

The common OPM loader (written by the Symbian Developer Network) should be used and supplied to other developers. This is a set of procedures that load and unload the OPMs.

The OPM is loaded with a call to OPM_LoadModule:(modulename$), where modulename$ is the name of your module, omitting the .opm extension. When no longer required, it can be unloaded with OPM_UnloadModule:(modulename$).

The standard load procedures:

REM *************************************************************
REM * The routines below are the standard OPM Load routines and *
REM * should be copied to all applications which use OPMs       *
REM *************************************************************
REM Version: 3.0
REM Date: 3 October 2000

INCLUDE "Loader.oph"
REM --------------------------------------------------------
REM Returns the file position if the file exists on C: or D:
REM --------------------------------------------------------
PROC OPM_FileLoc$:(file$)
	LOCAL drive%, letter$(2)

	drive%=1
	WHILE drive%<=LEN(KOPMDrives$)
		letter$=MID$(KOPMDrives$,drive%,1)+":"
		IF EXIST (letter$+file$)
			RETURN letter$+file$
		ENDIF
		drive%=drive%+1
	ENDWH
ENDP

REM -------------------------------------
REM Loads in a module held in /System/Opm
REM -------------------------------------
PROC OPM_LoadModule:(modulename$)
	LOCAL f$(255)

	f$=OPM_FileLoc$:(KStandardOPMPath$+modulename$+KOPMExtension$)
	IF f$<>""
		TRAP LOADM f$ :REM Load the module
	ELSE
		ALERT("Cannot find the OPM:",
			KStandardOPMPath$+modulename$+KOPMExtension$)
		STOP
	ENDIF
ENDP

REM --------------------------------
REM Unloads in a modeule from memory
REM --------------------------------
PROC OPM_UnloadModule:(modulename$)
	TRAP UNLOADM OPM_FileLoc$:
		(KStandardOPMPath$+modulename$+KOPMExtension$)
ENDP

4. Distributing the OPM in an installation file

Where possible, the OPM should be distributed within a .SIS installation file. This will ensure both the user and developer installs the OPM into the correct place, and that the OPM is not removed prematurely if used by more than one application. The following is an example of a suitable package file. Note that you will need a unique ID (UID), available from The Symbian Developer Network.

;
;Create the package for the Pc_bar OPM
;
;date:28-1-1999
;
;language section
&EN

; installation header
#{"Progress bar OPM"},(0x100042D0),1,00,0
"PC_bar.opo"-"!:\System\OPM\PC_bar.opm",FF 

The makesis tool is included with all SDKs.

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.