Introduction to EPOC OPL Development
by Richard Bloor
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.
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.
Download the example program here.
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%
ENDA
|
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 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.
DO
GETEVENT32 evt&()
IF ..........
ELSEIF evt&(KEvAType%)=KEvPtrEnter&
REM act on a pen event
PenEvent:
......
ENDIF
UNTIL Exit%
|
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.
mINIT
mCARD "File","Exit",%e
mCARD "Window","Show",DisableShow% OR %s,"Hide",DisableHide% OR %h
menuitem%=menu
|
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.
popupitem%=mPOPUP(gORIGINX,gORIGINY,KMPopupPosTopLeft%,"Hide",%h)
|
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
DialogKey%=DIALOG
|
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:
FIRST
i%=1
IF EOF
DO
INSERT
A.LineTextItem$=LineText$(i%)
PUT
i%=i%+1
UNTIL i%>4
ELSE
DO
MODIFY
A.LineTextItem$=LineText$(i%)
PUT
NEXT
i%=i%+1
UNTIL i%>4
ENDIF
CLOSE
|
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.
OPL provides a rich set of graphic manipulation statements that can be considered as part of four categories:
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:
bit%=gLOADBIT("Z:\System\OPL\TDemo.mbm",KgLoadBitReadOnly%,0)
|
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:
fillheight%=gHEIGHT-KWinTitleSize%-(2*KWinBorder%)
fillwidth%=gWidth-(2*KWinBorder%)
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.
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%
|
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
gSTYLE 1
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.)
Next: Extending OPL
|
