Introduction to EPOC OPL Development

Photo of author

By Miro Stoichev


The Symbian EPOC operating system is a powerful platform for the development of palmtop and wireless applications. It’s robust object orientated architecture makes efficient use of the reduced processing power and memory available on portable devices.

The developer has three options with which to exploit EPOCs power, OPL, Java and C++. Each language provides the ability to develop and deliver fully featured robust applications, however each language involves a compromise between the access to EPOC functionality, performance and development time.

OPL is a Basic like language that appeared on the Psion Organiser in 1991. It’s subsequent implementation on the Psion Series 3 created a loyal following because of it’s power, ease of use and the fact that programs could be developed directly on the Series 3. OPL migrated to the EPOC operating system and has been used to develop a wide range of applications.

OPL is the obvious choice where development time needs to be minimised, optimal performance is not critical and direct access to all of EPOCs functionality is not essential. However despite it’s limitations OPL is capable of delivering rich and functional applications.

In this article we will explore:

  • what hardware and software you need to start developing in OPL
  • the OPL development process
  • the key elements of the OPL language (supported by an example application)
  • how to create icons, graphics, help and resource files as well as application delivery packages, and
  • review what additional OPL resources are available and where they can be found.

Getting Started

OPL applications can be developed either using the OPL environment on an EPOC device or the Symbian OPL SDK that runs on a PC. Currently the Psion 5mx and 7, Oregon Scientific Osaris and Ericsson MC218 all include the OPL development environment. Generally however most development will be undertaken (or at least completed) using the SDK which can be obtained by either:

  • registering on the Symbian Developer Network and download the SDK. (You can also order the SDKs on CD-ROM from Symbian for a small handling charge.) or
  • purchasing the Wrox press book Professional Symbian Programming book which comes with a CD containing all four SDKs (the fourth being the EPOC Connect SDK for PC connectivity development).

The Wrox book contains a chapter on OPL, but mainly concentrates on C++ and is therefore probably not worthwhile unless you also have an interest in C++ development. Even if you buy the book registration at Symbian’s developer network is worthwhile as the site contains a number of other useful resources, including OPL extensions (OPMs and OPXs), OPL knowledgebase and a resource file tutorial amongst others.

The SDK contains an emulator for 1/2 VGA (640×240), full VGA (640×480) and large (800×600) EPOC screens and includes all the standard EPOC functionality and applications along with full documentation and some example programs. It also contains a number of useful utilities for creating resource, graphic, help and installation files that can not be undertaken on an EPOC machine unless you use third party tools.

To run the SDK you will require a Pentium PC running Windows 95 or above. (Incidentally the SDK also provides an excellent free route to evaluate the core EPOC applications if you were thinking of buying an EPOC machine.)

The Development Process

The process of developing an OPL program or application can consist of simply writing, translating and running the code directly on your EPOC machine. However the production of a fully featured application is a little more involved.

(The distinction between a program and an application is really whether an Icon appears on the Extras bar, similar to the Windows Start menu, from which the application can be run. A program can only be run by finding and executing the compiled code.)

The process of developing an application has five elements:

  • writing and testing the OPL code
  • preparing a resource file (primarily for multiple lingual versions)
  • developing and packaging bit map icons or other graphical program elements
  • writing the help documentation
  • packaging the final application in an installation file.

OPL Overview

OPL is a rich and extensive language, even before the additional capabilities added by OPXs and OPMs. In this section we will examine some key elements of an OPL application or program by reviewing the example program accompanying this article.

We have skipped over some fundamentals, such as datatypes and basic programming constructs such as loops and conditional statements (although these are present in the example). These items should either be familiar or are easily found in the SDK documentation.

  • Basic OPL Structure
  • The Event Loop
  • Menus
  • Dialogs
  • Database
  • Graphics

Example Application

The example application displays and allows the manipulation of two windows.

The example program

The program can be exited by pressing CTRL-E or activating the menu, from the menu key or screen key and using File | Exit. The windows can be manipulated in the following ways:

  • switching between windows by selecting any point in the window
  • once selected, moving using the window by dragging it from the window header or
  • resizing the window using the edges and corners outside the header
  • hiding the first window from either the main menu or a popup menu activated by selecting in the body (wallpapered area) of the window, then restoring the window from the main menu.

The first window displays wallpaper made up of the EPOC logo with the wallpaper shrinking and growing with changes to the window. The second window shows 4 lines of text which can be zoomed with the screen key zoom buttons. Text row can be selected and edited with any changes being stored in a database.

The example program has been supplied as a text file, this allows it to be reviewed without the emulator or an EPOC machine. If you wish to run the code copy it to the emulator or EPOC device then use File | More | Import Text in the program editor to load it.

Basic structure

Each OPL program has the same basic structure. The initial portion of the program contains any constant definitions, either edited directly or included from other files, and procedure prototypes.

In the example we have used the standard Const.oph and defined a number of constants defining attributes and elements of the windows.

Then if the program is to be an application this is defined as follows:

APP OPLExamp, &01000001
     ICON "Z:\System\OPL\TDemo.mbm"
     CAPTION "OPL Example", KlangEnglish%

The first point to note is the UID. Each EPOC application is assigned a unique identifier. EPOC then uses this to associate files with applications (rather than relying on file extensions). A range of UIDs is available for use during development (hexadecimal &01000000 to &0fffffff), however if your application is going to be released the development UID should be replaced with one provided by Symbian.

The remainder of this statement defines the icon used for the application, the extra bar caption and its associated language (one for each language the application is delivered in).

The example application on the Extra bar.

This will now be followed by the first procedure. It is this procedure, regardless of name, which will be executed first when the program or application is run. In the example this procedure is Main.

The Event Loop

The core of virtually any OPL program will be an event driven loop using the GETEVENT32 statement. GETEVENT32 reports all keyboard and screen activity as well as a number of system events.

     GETEVENT32 evt&()
     IF ..........
     ELSEIF evt&(KEvAType%)=KEvPtrEnter&
REM act on a pen event

Keyboard events

Keyboard events return the key code and key position, whether any modifiers (control, shift or function) were active and the number of repeats.

Screen events

Screen events return the window in which the event occurred, the position within the window and absolute screen position, the pen action (down, drag and up) and any modifier keys used.

System Events

The system events detected include the following:

  • the program coming to the foreground or going to the background
  • the machine being turned on
  • EPOC has issued the program a command e.g. switch file, exit application


OPL provides for two types of menu, the fixed menu that is normally called from the menu screen key or keyboard and popup menus.

Fixed menus are defined in two parts, being cascades and card menu items. The example only uses card menu items.

mCARD "File","Exit",%e
mCARD "Window","Show",DisableShow% OR %s,"Hide",DisableHide% OR %h

In this code we have used the facility to disable menu items to ensure that the options to show or hide the first window are only available in context.

The example applications standard menu.

Menu definition also provides for the definition of choice groups and use of a check to show selected items.

Popup menus are defined in a similar manner to the standard menu, with two differences. A popup menu can be placed anywhere on the screen and it can only contain a single menu column i.e. no cascade menus.


The example popup includes one option (to hide the first window) which is positioned in the top left of the window.

The example applications popup menu.


OPL provides for Data entry using dialogs. In the example we have a simple dialog which allows a text line to be edited.

dINIT "Line Text"
dEDIT EditText$,"Text",20
dBUTTONS "Save",%s,"Cancel",-%c

Firstly the dialog is initialised with dINIT which defines the dialogs title. This is followed by the dialog elements, which can include:

  • static text, short (single line up to 255 characters) editable text and long multiple line text
  • check boxes
  • floating point and long integer numbers
  • dates and times
  • selection list
  • file selection
  • password (hidden text)

In this case we have simply defined a short text field of up to 40 characters, which is edited in a field 20 characters long.

Finally we define the buttons and their associated key codes, “Save” with a shortcut from CTRL+s and “Cancel” with a shortcut from CTRL+c. The cancel button is also the dialog escape button, achieved by negating the key variable. This returns 0 from the dialog command rather than the button keycode and does not update the dialog variables. The escape key is also available as a default.

The example applications dialog.


EPOC includes a built in relational database that can be accessed using SQL statements and includes powerful features such as keys, indexes and transaction control. OPL does not directly harness all of the Databases power, but OPXs are available to provide the missing access. However the basic features still allow the development of useful database applications.

In the example application we have made use of the database functionality to store the content of the four text lines in window 2.

A database table is created with the keyword CREATE (which also creates the database file if it does not exist).

CREATE "c:\LineData FIELDS LineText TO LineData",A,LineTextItem$

The first portion of the statement defines the database file location, the fields and the table name. The next parameter defines the internal file handle the table is assigned to, then the program variables that the fields are assigned to. After the create statement has executed the table is available for use.

In OPL each database table or view is assigned to a letter A to Z which is subsequently used to access the data. Existing tables are opened using the OPEN statement (or OPENR if read only is required). OPEN uses SQL syntax to allow either the whole table or a view to be opened.

OPEN "c:\LineData SELECT LineText FROM LineData ORDER BY LineText",A,LineTextItem$

So the code above the line text is extracted from the LineData file in order to file handle A.

Although it is possible to access data from several files to use the record handling commands a specific file must be elected. This is done using the USE command, however this is unnecessary in our case as we only have one active file.

To save the line data we use the following code:

     UNTIL i%>4
     UNTIL i%>4

Here we use FIRST to get the first record in the view. Then EOF (end of file) is tested to determine whether any record exist. Based on this we either add (INSERT) or change (UPDATE) records. Note the use of PUT which commits the record, the associated CANCEL allows changes to be aborted.

Finally once the changes or additions are complete the view is CLOSE(d).

You can go a stage further in controlling database updates using transactions. Using the BEGINTRANS followed by either COMMITTRANS or ROLLBACK as set of individual changes on a view or table can be controlled as a unit.

Graphic component

OPL provides a rich set of graphic manipulation statements that can be considered as part of four categories:

  • Windows
  • Bitmaps
  • graphic drawing
  • graphic text.


You can create and manipulate a total of 64 Windows and Bitmaps in OPL. For performance reasons the number of active Windows should be kept to a minimum (a restriction which does not apply to Bitmaps).

Windows are created as follows:

WinID%(1)=gCREATE(10, 10, 300, 150, KgCreateVisible%, $111)

This creates a window 300 pixels wide by 150 deep with the top left-hand corner at 10 pixels across and down from the top left of the screen. The fifth parameter indicates whether the window is created visible or not and the final parameter specifies the colours handled (2, 4 or 16 being available at present) and any shadowing applied. A handle for the window is returned.

The window can then receive graphic and text commands.

Various commands then allow for the window to be manipulated or to obtain information on it’s properties, including:

  • gSETWIN to alter the window size or position
  • gVISIBLE to show or hide the window
  • gUPDATE to turn off screen updating or force the window to be updated (which allows performance to be improved when significant updates to the window are made)
  • gWIDTH which returns the current windows width


Bitmaps are non-visible objects that allow bitmap images to be loaded, or created, manipulated and copied to the visible screen. Bitmaps can be manipulated with any of the windows, drawing and text graphic commands.

The following code opens a bitmap from an existing file:


This command identifies the TDemo file (which in this case is from the machines RAM), flags it as read only and loads the first (0 indexed) bitmap. In this case we obtain a bitmap of the EPOC logo.

The bitmap can then be copied to the current drawable with gCOPY or gPATT. The following code uses gPATT in the example program to wallpaper the first window:

gAT KWinBorder%,KWinTitleSize%+KWinBorder%
gPATT bit%,fillwidth%,fillheight%,KgrahicModeReplace%

Here we determine the height and width of the fill space to exclude the window header and border, set the drawing position and then fill the wallpaper space. The final parameter on gPATT determines that drawing the wallpaper clears any existing graphics.

Unlike windows there is no particular performance impact of having multiple bitmaps open concurrently.

Graphic Drawing

OPL provides a number of keywords for drawing graphics, including lines, circles, boxes, buttons and polygons.

In the following code we draw the border around a window and then clear the heading into which the window title will be printed.

gXBORDER 2,KBordSglShadow%
gAT 1,1
gFILL gWIDTH-2, KWinTitleSize%,KgrahicModeClear%

Graphic Text

The final category provides for the formatting and placement of text. Functionality covers setting text attributes, font, formatting, printing of text and information about text.

The following code continues building the basic window, the font and style (normal) are set before the drawing positioning set and the heading text printed.

gFONT 11
gAT 0,14
gPRINT " Window " + GEN$(Win%,2)

The final statement in the basic window construction is:

gAT 1,1
gFILL gWIDTH-2, KWinTitleSize%,KgrahicModeInvert%

that reverses the header area to show white text on a black background.

Extending OPL

In addition to “basic” OPL there are two mechanism by which OPL can be extended, these are OPMs and OPXs. Symbian supply a number of OPMs and OPXs that are freely available from the developer web site. In addition, several are available from third parties, details on these are also available on the Symbian developers web site.


OPMs are simply OPL programs that have been built to deliver common functionality. They are loaded by the main OPL program and their functionality accessed as OPL procedures. OPMs are currently available to implement:

  • the standard EPOC toolbar
  • a range of buttons and other functionality


OPXs are C++ DLLs that provide access to core EPOC functionality not directly accessible through the basic OPL keywords. The functionality provided by OPXs simply adds a number of key words to OPL.

There are a wide range of OPXs available to provide access to system information, comms, agenda, contact files and more. A number of third parties have developed OPXs which also assist the development of more feature rich applications with multi-page dialogs and vector printing.

One note with OPXs. As these are written in C++ the OPX delivered for use on an EPOC device will not work on the emulator. To run them on the emulator it is necessary to get a WINS version. For all the Symbian supported OPXs the WINS version is delivered with the native EPOC version. For some of the third party ones you may need to approach the developer to get the WINS version.

Graphics, Fonts, Help and Resource Files and Installation packages

The OPL SDKs contain a number of utilities which allow for the development of fonts, graphics, help and resource files along with EPOC installation files.


The current release of EPOC includes an architecture for the Open Font System. However at present the plug ins to implement this system are not yet available. In the meanwhile fonts can be created using either EPOCs proprietary font definition file or from existing fonts, for example Adobe Bitmap Distribution Format.

There is no mechanism to produce fonts directly on an EPOC device.


EPOC uses a unique file type for dealing with graphics, the mbm or multiple bit map file. This file format is able to deal with monochrome through to 24 bit colour, however current EPOC devices can deal with a maximum of 256 colours.

Content is created using any application capable of storing bit maps e.g. the Windows Paint application, and then converted using the bmconv utility.

System icons differ slightly from other multiple bit map file in that they contain only two bitmaps, the icon and a mask. The mask indicates which pixels the icon will effect, the main effect is to define whether the icon background is transparent or not.

mbm files can be created on an EPOC device with the standard Sketch application, however as this stores only one bitmap per file it can not be used to create icons. Icons and mbm file with multiple bitmaps can be created programmatically. In addition a number of third part tools exist to allow mbm file to be manipulated on an EPOC device.

Help Files

EPOC helps files are based on the EPOC data application and a help file is simply a data file with the extension hlp. The file contains fields for help title, help text, application name and synonyms to aid searching. The text can include embedded mbm graphics.

Help file can be created by directly editing a Data file and then changing the file extension, which allows these files to be created directly on an EPOC device. Alternatively a utility, aleppo, is provided on the SDK which allows help files to be created from rich-text files, edited using a Microsoft Word template, and mbm files. The utility provides functionality for ordering and formatting the help file.

Resource Files

If you are developing a program for use in only one language, resource files will be of limited use. However if you want to develop an application for international use, resource files provide a mechanism to eliminate re-coding for other languages.

The OPL resource file actually uses the C++ resource file converted using a piece of OPL code. Although part of the creation process involves OPL code, resource files can only be created using the SDK.

Installation Files

While applications can be installed by simply copying over the program elements the inclusion of OPXs, OPMs, help, bitmap and example files and the need for a de-install mechanism makes this an impractical approach. EPOC uses SIS file to package all the necessary elements into a single install file.

The install file creation utility, makesis, uses a package file to define the installation components. In addition to defining the component to install it provides some control over the install/de-install process, for example, licence text can be displayed on install or files created by the application can be deleted on de-install.

Third party utilities are also available to allow SIS file to be created directly on an EPOC device.

The Future of OPL

OPL is currently a core element of the EPOC operating system and will be included in the Crystal DFRD when EPOC release 6 is launched. However this is not a guarantee that OPL will be available on all future EPOC devices, as it’s delivery (as with any EPOC application) will be determined by the licensee. The Psion Revo, for example, does not include the OPL development environment (although the run time is present).

Currently it is likely that OPL will be absent from the Pearl and Quartz DFRD’s, if only because these devices form factor does not readily facilitate the intensity of text editing necessary for application development. However Symbian may include an OPL runtime in these DFRD’s.

So while OPL provides an easy entry point to EPOC development it may not provide a practical platform for commercial application development if only because OPL applications may not be deployable on all future EPOC devices.

Even so OPL provides a useful tool in the EPOC development armoury. The basics can be mastered in a few days and advanced development can be achieved in less than a month. Applications can be developed with relative speed and ideas trailed before transferring to either Java or C++.

Leave a Comment