AAS: Articles and Features: Devloper Full

What is GoDB and First Steps

Fri, 07 Oct 2005 17:56:46 +0100

GBasic (GoDB)

GoDB is a multi-platform rapid application development tool for developing handheld and wireless applications.

Applications developed once on the GoDB platform can run on devices ranging from Handheld to Laptops to Desktops and on all popular Operating Systems like Symbian (UIQ, Communicator series, Series 60, et cetera), Windows Mobile (Smart phone, Pocket PC, CE), Palm OS, Windows, Linux (Embedded & desktop), etc.

We call the language - GBasic

The GStudio IDE�has�the following�components.

Form Builder
Simulators for devices/PCs
Integrated source level debugger
Single click SIS Packaging

What�s GoDB Lite?

GoDB Lite is targeted at developers looking to develop simple applications, utilities and 2D Games for Symbian Series 60.

��Commands for sending receiving SMS, System Level notification (GPRS/IR/BLUETOOTH/BATTERY).

��Commands for Making Receiving Voice Calls, Playing Video and Audio (Embedded in the app / Launched separately).

��Commands for Switching to other Apps and views.

��Commands for Enumerating Contacts and Groups.

��Support for Sprite animation for Game development.

��Support for HTTP Web services, Native Device access (Comports, GPS, Bluetooth Smart Card etc.).

��Support for Push Services over SMS and TCP/IP.

��Support for external C++ Components controls to be embedded in forms and extending functionality.

Yes. You get to play around with your Symbian device. But note that for�any database/enterprise application, you require the GoDB Enterprise Edition.

For more details, see www.consigntech.com

Getting Started

Lesson 1:

Creating Hello World Application

http://www.go-db.com/GoDB_manual/NewTutorials/Lesson1(GoDB%20Lite%20Symbian).htm#CreatingaProject

Lesson 2:

SIS file creation:

Well, if you are happy with your creation,

http://www.go-db.com/GoDB_manual/Deployment/SymbianGoDBLite.htm

Programming with Spreadsheets - Part 2

Thu, 27 Jan 2005 15:24:30 +0100

Developing 'off-device' is an important part of any programming langauge. Almost every C++ or Java prorgammer of smartphones will do the majority of their work on a PC. It's a much larger screen, it's easier to see what's going on and type in a lot of information. And when things go wrong (which they will) all of that will let you focus on the real problem in the spreadsheet.

Developing on Your Desktop Computer

Using Microsoft Excel

Quickoffice, on both UIQ and Series 60 smartphones, can read in spreadsheets saved in the latest Microsoft Excel formats (mHTML).� And while the 9500 and 9300 Communicators can read in the Excel format, dragging and dropping Excel files onto these devices using their PC Suites will automatically convert them into the much more efficient Symbian Sheet format. If you can, you should always try to convert them as you move them over.

If you have a copy of Microsoft Office (available from all good computer retailers), then you should have Excel available. Quickoffice's spreadsheet saves and reads files in the standard Microsoft format of mHTML, which features in Office XP and Office 2003. Earlier versions of Office will require an Excel Plug-in (freely downloadable with Quickoffice) that adds a "Quickoffice" menu to your version of Excel.

Keep It Simple

Excel has a huge number of functions, graphical options, charting and other options. You may not find it surprising, but many of these are not part of the spreadsheet applications in your smartphone. So always follow the KISS rule - Keep It Simple, Stupid.

Stupid in this sense doesn't mean do a simple spreadsheet, but to keep what you do in the spreadsheets within the realms of what your smartphone can do. So feel free to format the colour of cells, but don't go overlaying jpeg impages along the top line showing a fancy title. If you start using some�wierd mathematical functions, then check that these commands are available on your smartphone.

Timesheet / Hours Calculator

Let's build our first spreadsheet using your desktop computer. Open up your spreadsheet program on your desktop, and use "File... New..." to create an empty spreadsheet. It might be an idea for you to check out how to add in information, edit the content of the cells, and do the basic formatting that you practiced on the Sales Tax calculator in part one.

Wages Spreadsheet

Let's look at another spreadsheet close to everyone's hearts. How much you get paid for your work. The aim here is to have a spreadsheet where we put in the number of hours that you work, and it then works out various deductions, to arrive at�your net pay for that week. As with any program, it's important to consider the information you are going to put into the spreadsheet, information that will change each time you want to do a calculation (and which numbers will stay the same), and what information we want to get out.

Information Going In - Variables

We'll be telling the spreadsheet how many hours a week I have worked. Now I have fixed shifts every week of four hours per shift, plus casual hours, so to save me some maths, I'll have two entries. The first will be the number of fixed shifts I work, and the second will be the number of extra hours I work.

Information Going In - Constants

What is my rate of pay?
Deduction 1: The rate of Income tax (22% of my wage)
Deduction 2: National Insurance Class 2 (8% of my wage)
Deduction 3: National Insurance Class 4 (�2.08 per week of my wage).

Obviously these are geared to my wages in the UK, but you will be able to adapt these to your own circumstances - which is one of the great things about programming something specifically for yourself.

Information Coming Out - More Variables

How much money I receive after all those deductions.

�

Constructing the Spreadsheet

With our blank spreadsheet now in front of us on the PC, we can add in all these variables and constants into column A, so we can see which number is which.

As well as our yellow bar to explain what each column is for, we have the first 'section' where I can input my hours, the second section where the deductions are carried out, and a final section of one line, showing the money I actually recieve.

Hours and Gross Wage

We work out the total hours by multiplying the number of shifts by the length of shifts (the variable is the hours in a single shift), and then adding in the number of single hours. The formula doing this is in cell B6, and is =(B4*C4)+B5. The brackets here are used to make sure the calculation inside the cell is done before any calculations. Just like you learned in your Maths classes. Then we take the hours worked and multiply this by the hourly rate (the variable in C7) to get the pay without any deductions. Note that we're using the result of a formula in B6, and it is treated as if it was a number.

Deductions

Percentage deductions act on the gross wage, so we can take the value in B7 and apply some percentage changes to it - just as we did in the VAT example in part one. We have two percentage deductions here, one for 22% and one for 8%: B9=B7*C9, and B10=B7*C10. The third deduction here is a fixed deduction, so we simply copy over the value from the variable into the B column.

Now let's add all these deductions together. How would you do it? If you said that cell B12 would be =B9+B10+B11, you'd be right. But imagine if we had to add up one hundred cells in a column. That's a lot of typing. But we can use a function. This is a special type of formula that has a command and some arguments (normally cell references). To add up a column or row of cells, we can type =SUM(B9:B11). This adds up the value of all the cells from the first cell referenced (B9 here) to the last cell (B11).

The Final Wage

So now we have my total wage earned (in cell B7) and the amount of deductions (B12) we can go =B7-B12 to get the wage I'll end up with after a week of work.

Transferring Files

Communicators
The easiest way to move your spreadsheet over to a communicator is using the bundled PC Suite, and its file transfer capability. This will convert the Excel spreadsheet into the Symbian Sheet format. Alternatively you can right click the spreadsheet file on your PC, and send via IR or Bluetooth.
Series 60 and UIQ
While the PC Suites and various add on�modules allow you to see the drives of your UIQ or Series 60 smartphones, the easiest way to move these files over is using IR or Bluetooth directly. Right click the spreadsheet file, and you can send it to your smartphone. It will appear�in the Messaging inbox and you can then save it�to disk, to appear in the main file lists of Quicksheet.

That's it for this week - you'll probably want to enter the spreadsheet, then tailor it for your own use. You might want to play around with the insert rows and insert column options on your PC spreadsheet when adding in cells. In part three we'll look at a much larger spreadsheet, and start to build up a simple Bank Account Tracker in a spreadsheet.

Programming With Spreadsheets - Part 1

Fri, 29 Oct 2004 14:45:25 +0100

What Is Programming?

So you're carrying around a computer in your pocket. Okay, people call them smartphones, communicators, PDA's or one of a million other names to try and pigeon hole them. No matter what you call them, it's a computer with a peripheral that allows you to take to other computers. Which means, like any computer, it's possible to write programs it.

Symbian OS has a large number of language choices, from C++ and Java, to OPL and Python (in some cases), along with AppForge's Visual Basic and scripting languages such as Simkin. But there is another way. A way which, while not as stylish and slick as some of the above, will still let you make use of the computing power available to you.

Here's a simple question, what is a computer program? Well, it's making your computer (smartphone / communicator / PDA / etc) do something for you. In the case of a complicated program like Opera, it's doing rather a lot of things at once: talking to other computers, laying out information, scaling pictures and images and�working out a good layout of all the elements. Because of the complexity of the programming involved, the C++ language is the best choice. But the program it's doing something you want it to do.

Let's look at a program called Convert, that comes bundled with many Series 60 devices. In this application, you give your computer a number, it does a calculation and displays a result. How many practical computer programs are based around this principle of taking in some information, processing it, and displaying a result?

Now think about how you could use this idea in real life,. We've seen one, the units convertor, but what other uses are there? How about working out sales tax on items? Or checking your wages slip when you get paid? Tracking expenses and bank accounts? Computers are supremely good at crunching through numbers.

But how do you get to a point where you can work purely with these numbers and ignore all these big scary words like SDK, API, C++, DLL, MIDP, JIT, RAD, IDE, CPP and my personal nightmare, OOP? Welcome to the world of spreadsheets.

Spreadsheets as a Programming Language

Let's make this clear right now, these articles aren't aimed at programmers. Everything you see in this series of articles is easily replicated in the big languages. I'm aiming these articles at Power Users who don't program their phones and want to do more. Over the next three articles, we'll start off by talking about how a spreadsheet works, and prgramming a sales tax calculator. Next week we'll look at doing larger spreadsheets on your PC and moving them to your phone. Finally, we'll do a spreadsheet that allows you to track your bank account, just like a full blown financial application.

I want you to think about your phone as a true computer. Something you can control. Yes the majority of you are more than happy to grab programs by other people, but there always comes a point when you think 'I wish my phone could do that.' Hopefully, I can show you that you can program your phone. It's not something reserved for people who spend years learning languages, or take months of study in the evenings to be able to do it. Programming is something open to everyone.

Where To Get A Spreadsheet

Of course to program in spreadsheets, you'll need a spreadsheet application on your phone. Some phones have them built in, some will need you to download third party software and some (such as the P910) come bundled with the third party software you need.

Nokia Communicators

Luckily, the 9200's and the Series 80 powered follow ups both have a spreadsheet program (Sheet) built in.

Series 60 and UIQ

You're going to need to purchase a third party solution here, so there is going to be some initial outlay. We'd recommend Quickoffice (downloadable from http://www.quickoffice.com/). It's the nicest spreadsheet program out there, and you get a trial period before you have to buy it. The P910 comes with Quickoffice already bundled.

The Basics Of A Spreadsheet

So what exactly makes up a spreadsheet? Well, let's create a new spreadsheet inside your application. What you'll see will look something like this...

Cells

The first thing you can see is a grid of squares. Along the top and left edges you can see reference numbers and letters. These let you give each cell a unique reference of a letter and number combination. For example, the cell at the very top left is in column 'A' and row '1' so it is cell 'A1.' The cell below it is called 'A2' and the cell to the right of it is called 'B1'

Text Strings

The beauty of cells, is that you can put things in them. The simplest thing to put in them is text. Let's put some text in cell 'A1.' It's traditional for programming lanaguges to start with a 'Hello World' application where the computer displays the text 'Hello World' on the screen. Highlight the cell you want to place the text in, and then, depending on which application you have, let's enter the text.

Communicator (Built In)
Move the cursor to the cell you want to enter data, press enter, and start typing.
Series 60 (Quicksheet)
Move the cursor to the cell, and select edit. Type in the text using T9 or regular key taps. When finished, press in the cursor/stick again to accept the text.
UIQ (Quicksheet)
Tap the cell where you want to enter data. The cursor will move to that cell. Now tap in the text area at the bottom of the screen (to the left of the tick and cross). You can now enter text normally. When finished, tap the tick.

Numbers

Numbers are entered in exacty the same way as text (see above).

Formulas

The key to a spreadsheet is using the numbers you've entered in one cell, and crunching them to do something else. When you enter a formula in a cell, you signify this by making the first character the '=' sign. Now your spreadsheet knows that rather than show the contents of the cell (as it does with a text string or a number), it shows the result of the formula.

Open a blank spreadsheet and enter the number 5 in cell A1. Now move to cell B1, and enter the formula '=A1'. Rather than seeing '=A1' in the cell, you can see the number '5.' Cell B1 is now a simple formula that says 'this cell should show the contents of cell A1. '

Let's edit the formula now, by doing the same procedure you used to enter the formula. You'll see that while the contents of the cell in the spreadsheet show the result, the edit box still shows the formula. Edit the formula to read '=A1+4' and you should see the on screen result of '9'

Of course, we're not restricted to referencing one cell per formula. So let's edit our formula in B1 again to read '=A1+A2' You'll see the result is still '5', because we haven't put any information in cell A2. Let's put the number '4' in there.

Notice that once you entered the number and finished in the edit box, the formula in cell B1 re-calculates itself immediately to reflect the new numbers in the spreadsheet. This is one of the keys to spreadsheets. No matter how complicated a spreadsheet, no matter how complicated a spreadsheet you have, each time you make a change, it is instantly reflected through all the formulas in a spreadsheet.

Our First Spreadsheet

Time to do something practical. Obviously spreadsheets are never going to be good for any games programming, but if you are involved with numbers in any sense, you should be able to find a use for a spreadsheet. The following spreadsheet takes in a price, and then calculates what that cost will be if you add or remove the sales tax (VAT) to the price.

Here's the completed spreadsheet on UIQ Quicksheet. There are two formula (in cells A4 and C4), that will use the sales tax rate in cell A7. Now, sales takes are normally given as a percentage, so you will need to do a bit of crucnhing yourself. 1.175 would be the number used for a sales tax of 17.5% (which is the rate in the UK).

Cell C4 contains the formula that will add the sales tax to the price you enter in cell B4. This formula is '=B4*A7'. Cell A4 subtracts the sales tax, using the formula '=B4/A7'.

You'll also note I've added a bit of colour in the formatting of the cells so when I come to use the sheet it's easy for me to see where I want to enter my price, and where the results are. You can do this to your spreadsheet in the following way.

Communicators (Build in Sheet)
Highlight the cell(s) to edit, call up the menu and select the menu pane Format. The very bottom has the option Decorate, where you can select Background Colour.
Series 60 (Quicksheet)
Go in to edit the cell, and call up the menu with the left hand soft key. Scroll down to the 'colour' menu option, and�select cell background to change the colour.�
UIQ (Quicksheet)
Highlight the cell you want to edit. Press the third button in from the left on the bottom toolbar (the pencil over a line), and you can select the background colour.

That's it for this article. In part two, we'll look at some more spreadsheet techniques, and how to use a PC based spreadshet to make it easier to code larger sheets.

Tutorial - Installing the Nokia 9200 SDK and OPL SDK

Mon, 25 Aug 2003 22:10:13 +0100

Developing in OPL for the Nokia 92x0 can be done in two different ways:

Firstly using the PC based SDK (software development kit), with an extra OPL Devkit installed in addition to the C++ / Java SDK. This method uses the 92x0 emulator. Code is written within the OPL program in the emulator and programs can be translated and tested in the emulator. This method is entirely PC based.
Secondly using either a Nokia 9210, 9290 or 9210i device itself. In this case the OPL editor and OPL runtime must be installed on to the phone. Programs are written in the editor on the phone, translated via the editor in the phone and can be run on the phone using the OPL runtime.

This tutorial guides you through firstly PC based development (obtaining and installing the SDK and configuring it for OPL development use) and Device based development (installing the OPL editor and runtime). It is recommended that you have both option available when developing as both have their own advantages and disadvantages:

�	Advantages	Disadvantages
Device based	Feeling for how program will work on actual target device, mobile development solution (program on the way to work)	Small keyboard means inputting lots of code can be tricky, smaller screen is harder on the eyes.
PC based	Large keyboard and screen allow for easy inputting of code and is easier on the eyes. Emulator (depending on speed of computer) is often faster than 92x0.	Not as mobile as the 92x0, not the actual device so difficult to get a feel for how things will actually work. The computer which the emulator is installed on must be sufficiently powerful to run the emulator (Pentium 200 64MB Ram minimum). Emulator is a Windows only program (despite being intended for NT it will generally run on any Windows Installation of 96 and above).

Obtaining the SDK and Devkit

The Nokia 9200 SDK can be obtained from Forum Nokia. You must be a member of Forum Nokia in order to obtain the SDK. Joining Forum Nokia is free (some personal information is collected), and is worthwhile as it give you access to documentation and other useful tools for all Nokia Symbian devices.

The SDK can be ordered on a CD (allow upto 3 weeks for it to arrive), or it is available as a download within the Symbian section. The download is large and is therefore recommended only for people who have a fast internet connection. This SDK is for C++ and Java development. In order to use it for OPL development and OPL Devkit must be obtained.

The OPL Devkit contains the files necessary to add OPL to the C++/Java SDK and the files to allow for OPL development on the Nokia 92x0. The OPL Devkit is available from the Developer section of the Symbian website. There is a download for both the OPL runtime and the OPL Devkit. The second of these is for developers, but the first will be needed by users to run your OPL program on their machine. In addition Symbian have also made available on this page some updated OPX's, it is recommended you also download this file.

It should be noted that Symbian expressly warn you that installation is at your own risk and that OPL is unsupported (but we're here to help!). However there have been no reported problems from anyone installing the SDKs. You should download the SDK from the page above as it allows Symbian to track interest in OPL development.

Installing the SDK and Devkit on a PC

Full documentation comes with the Nokia C++/ Java SDK including installation instructions. You should follow these. In summary it as simple as installing any other program. (To install run setup.exe). After installation you will have a working Nokia 92x0 Emulator. In order to use this emulator for OPL development the OPL Devkit must be installed.

Once you have downloaded the ZIP file containing the OPL Devkit you should unzip it and read the readme.txt file. This contains instructions for installing the OPL Devkit. They may look long and complicated, but they are in fact very clear. Following the instructions takes around 10 minutes and adds the OPL runtime and OPL Editor to the Emulator.

It will also add the DemoOPL Program which is a Symbian version of the FreEPOC Event Core (although more complex and less easy to understand). DemoOPL is written in OPL and as can be seen from the screenshot below it demonstrates that OPL programs look and feel like the inbuilt applications and can used to create both complex and useful programs.

The OPL Devkit Zip file also contains some useful documents such as the OPL Porting Guide and OPL Documentation. The OPL Devkit ZIP file contains another ZIP file which contains documentation on OPL from Epoc Release 5 (the previous OPL release to that for the Nokia 92x0) and is very useful in understanding OPL as changes between the two versions are relatively minor.

Installing the Devkit on the 92x0 device

To be able to develop OPL on the Nokia 92x0 device both the OPL runtime and the OPL Editor and associated files must be installed. The instructions for doing this are in the same readme.txt file referenced above. If you have installed a previous version of the OPL runtime please pay careful attention to the note in the readme.txt file (just above the installation instruction for OPL on the 92x0 device) otherwise the OPL Devkit may not work.

One stage that may not be clear is the following: 'Install any of the OPX files in \Binaries\SIS Files\Target\OPX\ which you require'. OPX files are extension of the OPL language. It is recommended that you install all such files available (including the ones available in the updated ZIP file available from the Symbian site).

Once you have successfully installed the files you should be able see the OPL Editor (called Program) which will enable you to write and translate files on the 92x0 itself.

So now you are all set to get going? If you need more help you can follow Ewan's OPL tutorials which will take you though every step of learning about OPL and teach you how to use the OPL Event Core to write your own program...

�

Part 7: Thinking about thinking

Mon, 25 Aug 2003 19:56:00 +0100

Abstract Concepts
One of the main things that people have problems with when programming is begin able to take an idea in their head, and turn that idea into computer code that does exactly what they want it to do. What I want to show you in this chapter is how we take one concept and turn it into code.

The key (as always) is being able to break your idea into smaller and smaller rules. If you break it down far enough, then you'll have something that can easily be written in OPL. What you must remember is when writing these rules, you must mention everything you do. You can't say "compare this ball to those four," you need to say what you're comparing, to which ball, and what to do depending on the result.

Checking The Guess
Breaking It Down
Before we can tell the computer what to do, we need to have a clear understanding on the thought processes that that our brain goes through. If we were making a cup of tea, it's no good having a rule that goes:

Boil Kettle

You need something like:

Take kettle to tap
Remove lid
Put kettle under tap
Turn on tap
DO
���wait a bit
UNTIL kettle is full
Put lid on kettle
Put kettle on table
Plug in power cable to kettle (it's an old fashioned one)
Switch on power at mains
Switch on kettle
DO
���wait a bit
UNTIL kettle switch moves to off position

Of course, there's nothing to stop you calling the above PROC boil_kettle: is there.

Right, so this is the level of detail we'll need to break down any computer action. Let's now look at MASTER and how I've broken it down, although you might want to have a go yourself before having a look at my solution.

Again, remember there is no right or wrong way when doing routines like this. If your way works, great! Just because it's slightly different from mine, you understand it and the user gets the same end result.

Checking Those Balls
The routine in Master checks to see how many balls are the right colour in the right place, and how many are the right colour but in the wrong place. These two numbers will be used to display the 'hint' to the player so he or she can make another guess to try and logically work out the solution.

Always keep your overall goal of a procedure in mind. It helps immensely. Now�

Code Breakdown
So what we'll do here is break down exactly the thought processes that you go through when comparing a guess in Master to the correct four colour solution.

Some Counters
To keep track of things, we'll start with two 'counters' in our heads.. the number of balls that are the right colour in the right place, and the right colour but in the wrong place. So the first thing to do is

(Right Place)=0
(Wrong Place)=0

Check all balls are guessed (if not, return)
The guess button can be pressed at any time so we should check to see everything is in order before we process the guess.

(Counter)=0
DO
   (Counter) is increased by one
   IF guess position (counter) does not have a colour (ie it has a value of zero)
      Go back into game loop, print up warning message
   ENDIF
UNTIL (counter) equals four

Have we won?
This check is obvious. Have we got the solution correct? And as we're already thinking like a computer, we'll use a DO... UNTIL loop

(Counter)=0
DO
   (Counter) is increased by one
   IF guess position (counter) EQUALS colour in solution position (counter)
         (Right Place) is increased by one
   ENDIF
UNTIL (counter) equals four
IF (Right Place) equals four
   Then the guess is 100% correct, do the victory routine
ENDIF

All the above should be pretty obvious, and easy to code (now we've bbroken it down into the small logical steps computer programming requires).

How many balls are the right colour in the right place?
Well, we have the steps already don't we? We can use the code above because the (Right Place variable is going to carry the number of balls we need.

How many balls are the right colour, but in the wrong place?
Stop and think how you do this before we break it into steps. You take the first ball, and see if it matches anything in the solution (ignoring a ball if it is in the same postion (ioe the second guess compared to the second ball in the solution is something you don't do).

(Wrong Place)=0
(Counter One)=0
DO
   (Counter One) is increased by one
   (Counter Two)=0
   DO
      (Counter Two) is increased by one
      IF (Counter One) and (Counter Two) are different
         IF guess position (Counter One) equals solution position (Counter Two)
            Add one to (Wrong Place)
         ENDIF
      ENDIF
   UNTIL (Counter Two) equals four
UNTIL (Counter One) equals four

So now (Wrong Place) holds the number of balls that are the right colour, but in the wrong place.
Or does it?

The 'Gotcha'

PICTURE 1-2-3-4 Guess PICTURE 1-5-5-1 Solution

Have a look at this example. In your head, you know the correct solution is "one in the right place." But if you follow through the steps above, you 'll get "one in the right place and one in the wrong place." Why?

Because the red ball guessed in first place is not only counted in the 'right place' code, it is also counted in the 'wrong place' code by being matched up with forth ball in the solution.

One way to get round this is this simple rule that each guess ball can only be used once, as can each ball in the solution. So to facilitate this, we copy the guess and the solution into temporary arrays. When we match up balls in either the right place or the wrong place, we change the value in the array to something that wouldn't normally be there - we change a guess ball to 0, and a solution ball to 99. This way they cannot be counted again.

This is one example in how 'pseudo-code' can help you pick up bugs and logical flaws before you actually sit in front of the keyboard and start typing.

The Completed Code
So, here we have all the above in OPL.

LOCAL foo%, gnu%,right_place%,wrong_place%
LOCAL foobar%(4),guessbar%(4)
rem *** Create a copy of the solution so we can remove balls
rem *** as there position is noted. Ditto with guess array
foo%=0
DO
   foo%=foo%+1
   foobar%(foo%)=solution%(foo%)
   guessbar%(foo%)=guess%(foo%)
UNTIL foo%=4
                     
rem *** check all balls are guessed
foo%=0
DO
   foo%=foo%+1
   IF guessbar%(foo%)=0 : giPRINT "Not all spaces filled..." : RETURN : ENDIF
UNTIL foo%=4
breakout%=99 : rem *** Eventull incdrement turn counter
                     
rem *** right pieces in right place
foo%=0
DO
   foo%=foo%+1
   IF guessbar%(foo%)=foobar%(foo%)
      right_place%=right_place%+1
      foobar%(foo%)=0 : rem remove from stemp solution
      guessbar%(foo%)=99 : rem remove from guess
   ENDIF
UNTIL foo%=4
IF right_place%=4 : rem Victory
   m_victory:
   RETURN
ENDIF
                     
foo%=0
DO
   foo%=foo%+1
   gnu%=0
   DO
      gnu%=gnu%+1
      IF guessbar%(foo%)=foobar%(gnu%)
         wrong_place%=wrong_place%+1
         foobar%(gnu%)=0
         gnu%=4
      ENDIF
   UNTIL gnu%=4
UNTIL foo%=4

giPRINT NUM$(right_place%,1)+" in the right place, "+NUM$(wrong_place%,1)+" in the wrong place"
                     
m_showguess:(right_place%,wrong_place%,turn%)

It's not called from the event loop yet (but it shouldn't be that hard to figure out how), and we haven't yet got around to displaying the generated result. All that will be covered in Part 8.

But as with everything, you should be able to get down and do it yourself, so if you want a little challenge over the next fortnight... away you go!

Part 6: Cursor Control

Mon, 25 Aug 2003 19:44:21 +0100

Principles of Movement
How It Works, Part One, Playing in the Sand
Picture a children's play pit full of sand. It is perfectly smooth. Now, assuming you were invisible how would you make a small hole appear to run from one side of the pit to the other?

One way to do it would be this. Use your finger to make a hole and let everyone see it. Then, as quickly as possible, fill the hole in and make another one just to the side of where the first one was. If you do this over and over again, really quickly, what will someone watching the sand see?

A hole moving across the sand.

And that's exactly how movement and animation work in a computer program

How It Works, Part Two, Pixelating the Play Pit
So, if we have a blank (white) screen, how do we move a black spot around the screen? Have a look at this snippet of code...

 gUSE id%(9)
 foo%=0
 DO
    gAT 200,foo%
    gCOPY id%(1),0,0,20,20,1 : rem clear the 'older' spot
    foo%=foo%+5
    gAT 200,foo%
    gCOPY id%(1),0,0,20,20,0 : rem copy the 'new' spot
 UNTIL foo%=200

This code uses the basic building block of the DO... UNTIL... loop that increases a foo% counter. The first gAT... gCOPY clears away the old picture we've copied in (the picture being whatever mbm was gLOADED with id%(1) previously), and the second gCOPYs the mbm into the new location.

And that, in a nutshell, is how things move!

(I'll leave the relatively trivial exercise of how you'd adapt this to using a Mask and a Background Image to your imagination - it's not difficult to work out if you read Tutorial 5 closely).

What sort of things can move?
Have a think through the applications and you'll see movement in many different places. As with many of the principles you're seeing in this course, the above can be used in many different places.

Think of the tile blocks moving in Vexed. Think of the moving hand choosing cards in Card Deck. Think of the cursor moving through names and addresses in Contacts. All these use movements and masks - it's not difficult and it looks good. Which always key in a good application.

Displaying the Cursor in Master
As you'll remember, we've broken the writing of our application into small areas to work on. You'll remember that on the game grid, up and down will move an on-screen cursor in the corresponding direction, selecting where to place a colour.

So in essence, we're going to write a small routine to move the cursor!

Where are We Going to Go?
Firstly, we need to know if the up and down cursor keys have been pressed. As this is reading a keyboard event, we look in PROC g_kbddrv:(.........). At the end of the procedure, add in the following code...

 ELSEIF Key&=63593 : rem Cursor Up
    cursor%=cursor%-1
    IF cursor%=0 : cursor%=4 : ENDIF
    m_show_cursor:
ELSEIF Key&=63594 : rem Cursor Down
    cursor%=cursor%+1
    IF cursor%=5 : cursor%=1 : ENDIF
    m_show_cursor:

Okay, so we've introduced a new variable here. cursor% (which we set in PROC init_game: to be equal to 1) keeps track of which row the cursor is currently in (the top row is 1, the bottom row is 4). When we move the cursor up or down, we change the value of cursor% to represent the new row, and then call the procedure that will display the cursor.

The IF... ENDIF statement in the middle checks to see if we have moved down while on the bottom row, or moved up when on the top row. If we have, the value of cursor% is set to the opposite end, so the cursor effectively wraps round the rows.

Showing The Cursor
Once we move the cursor, we call this procedure...

PROC m_showcursor:
   gUSE id%(1) : rem Make sure we are using the main window
      rem *** clear the old cursor away by blanking the square, and
      rem *** copying the ball back into the square.
   m_showball:(turn%,old_cursor%,0)
   m_showball:(turn%,old_cursor%,guess%(old_cursor%))
      rem *** Now copy the cursor mask, and the cursor itself.
   gAT (turn%*36)+5,((cursor%-1)*36)+5
   gCOPY id%(11),36,0,36,36,1 : rem *** Copy the Mask, clearing pixels
   gCOPY id%(11),72,0,36,36,0 : rem *** Copy the cursor into the pixels
   old_cursor%=cursor%
ENDP

Time to Test!
If you were writing Master yourself, then now is a good time to translate and see if the cursor moves up and down. If you're keeping up with Master, have a look at the code at the end of the tutorial and you'll see where the above fits in.

The tutorials cannot explain everything, but I'm aiming to cover the broad principles here, and then hope you look at the downloadable source code at the end of the tutorials to see how it all fits together.

What we are doing in Master is creating a 'toolbox' of techniques that you'll hopefully be able to apply to your own programs.

Making a Guess
For each turn, we are going to hold the temporary guess an array called guess%(4). Once we've guess the four balls, we'll hit enter and see how good our guess is. At the start of the turn, we'll set the four array elements to zero. This is so we can check that the player actually puts 4 colours into the guess (i.e. all four values are non zero).

Left and Right, Red or White?
We've already got our cursor moving up and down, so now we add in the left and right cursors into the PROC g_kbddrv:...

ELSEIF Key&=63591 : rem Cursor Left
   guess%(cursor%)=guess%(cursor%)-1
   IF guess%(cursor%)<1 : guess%(cursor%)=(skill_level%*2)+2 : ENDIF
   m_showball:(turn%,cursor%,guess%(cursor%))
ELSEIF Key&=63594 : rem Cursor Down
   guess%(cursor%)=guess%(cursor%)+1
   IF guess%(cursor%)>(skill_level%*2)+2 : guess%(cursor%)=1 : ENDIF
   m_showball:(turn%,cursor%,guess%(cursor%))

This is going to look pretty familiar to the movement code. You'll see you increase or decrease the value of the guess%() depending on the current cursor% value (1 through 4). Where the value of guess% is more than the number of balls to choose from, it loops back to one, and if it drops below one, then it loops to the highest value.

Remember those Skill Levels
Yes, this highest value is determined by the skill level. The easy skill level (skill%=1) gives you 4 balls to choose from. Medium skill% (2) gives 6 balls, and Hard skill% (3) gives 8 balls.

In the same way we called the show cursor routine, we do the same here with the show ball routine, which we detailed off in the last tutorial. See, it's all falling into place now.

Conclusions
So, here's the OPL code as it stands just now. Copy this onto your Communicator (or into the emulator) and see how exactly we're doing everything.

MASTER is starting to look more and more like the finished product, isn't it? When you get to this part of your own future projects, you'll get a lovely thrill, because it's all working, and on the screen. If you've followed the course up to here, well done.

We're not stopping though. The next part is going to show us how to interpret the guess we've made, and then let the user have another guess.. and another... and another...

Source Code
You can download the OPL source code for Master as it is at the end of tutorial 5 here. You can download the opo program (the runtime file) as it is at the end of tutorial 6 here.

Part 5: Changing the Core

Mon, 25 Aug 2003 19:42:58 +0100

In which we'll make the first changes to Event Core and see the app starting to come together on our Communciators.

First Steps with the Event Core
Right, time to actually do some honest to goodness, real life coding. Either power up the emulator, or switch your phone on and set up the following using the File Manager.

Copy the master.mbm you created earlier into "\System\Apps\Master\" directory
You may need to make this directory. The System\Apps folder is like the "Program Files" folder on a PC - each app has it's own directory (which must be the same name as the files the translated application will have; in this case "master" ). In the File Manager application you may need to change the preferences so you can see the System directory.

Create a top level directory called "Programming"
Given time, you'll build your own programming practices and habits. In the meantime you'll be using a version of my own (with the arcane and obscure stuff removed). All my application work takes place in a Programming folder that is separate from the Documents folder.

Go into "Programming" and create a directory called "Master"
Each application or project gets its own folder to keep everything organised.

Copy core.opl into this directory and rename it "master.opl"
Now, you don't need to put that .opl at the back of the filename, but it means that code is easily recognisable from translated modules when you look at a directory. It is personal preference, and seeing as you're following me, you're stuck with it for a bit!
Oh and if you've forgotten, the core.opl is available from http://www.freepoc.org/core.htm

Editing core.opl to Make master.opl
Changing the identifiers
Thanks to the use of constants, it's actually quite easy to alter the core.opl into your application. Open up the (now renamed to) master.opl and look at the constants listed at the start of the app. AT the moment they read as follows...

CONST K_Author_Email$="ewan@freepoc.org"
CONST K_Author_Name$="Ewan Spence"
CONST K_App_Name$="Core OPL"
CONST K_App_Ver$="1.00"

These four are all pretty self explanatory. Your email and name are used in any copyright notices and in the About This Application box. The App name is used in the Menus, title bars, about boxes, and anywhere else.

Put in whatever you feel appropriate here - and don't forget they are easy to change!

A quick word about version numbers here, when developing it is always a good idea to start off with 0.01, and leave version 1.00 for your first release. Before releasing an app, I just increment the numbers (0.01 is the first, 0.07 is the seventh major revision, 0.23 is the twenty third, etc.).

On release of any bug fixes increment by 0.01, so 1.01 is the first version, but with one bug fix release. Any small improvements that don't change the main points of the app (e.g. adding in more tile sets in Vexed, or a new batch of colours in Clock6) would take the version up to the next tenth (i.e. 1.01 would jump to 1.1, not 1.11. 1.11 is for the first big fix!).

Right, translate that by hitting the translate CBA button. Have a look round all the menu system and suchlike and you'll see all the relevant names, numbers, and emails are in place!

Setting Toolbars and Titlebars.
As discussed before, these are set (and stored) in the .ini file. If you don't alter them from those set in the Event Core, then you'll get an app with the CBA always visible,The title bar on, and the large status bar on the left.

Having a look through the PROC init: you'll find this line...

AfSetTitle:(K_App_Name$,KAfTitleTypeMainTitle%)

...and because you've set K_App_Name$ in the constants section, you don't need to alter this either.

We'll get around to renaming the CBA's later on, but again you can see where they are set in PROC init: In the opl code at the end of the tutorial, you'll find the CBA's are working (so you can close the app) but I'll explain how in the next part. In the meantime, you can have a look at it yourself and see if you can work it out.

Loading Graphics
If you have a look back to Part 3, you'll recall how we gCREATE'd and gOPEN'd graphical windows and bitmaps. Any global graphics (windows or bitmaps) are created at the end of PROC init:. When I program, I usually use the GLOBAL id%(16) to hold all my graphical elements. I also tend to use id%(1) to id%(8) for windows and id%(9) to id%(16) for bitmaps.

It's always a good idea to use REM statements, but I think it doubly important here, because the graphical elements are something you may constantly use and need a ready reference for.

Translate and Check
Once you've edited PROC init: of the core, this is usually a good time to translate the OPL code and see that yo haven't made any mistakes. While you could write your whole app before translating, if you build up the app logically (remember the story analogy) you should be able to check it after each major section for change. Then if you do have problems, it's likely to be in the most recently typed in code.

Working With The Main Screen

Master has one main screen, displaying the ten guesses, the solution, and the winning pattern on the far right. What we'll do now is lay out these grids, ready to start playing in Part 6.

Showing balls

This section here is damm important. I've had a quick look back at my older Series 5mx apps, and a variant of this procedure features in the last 5 applications I've programmed, so in my mind it's an important principle, and the foundations have already been laid.

One key in computer code is being able to re-use code whenever possible, especially if you end up doing the same thing over and over again. In Master, you're going to be showing a lot of balls, all over the screen. How do we do this? Like this:

PROC m_showball:(foo_turn%,pos%,ball%)
   gUSE id%(1)
   gAT (foo_turn%*36)+5,((pos%-1)*36)+5
   gCOPY id%(10),36,0,36,36,1 : rem * Mask
   gCOPY id%(10),(ball%+1)*36,0,36,36,0 : rem * Ball
ENDP

Now whenever we need to print a ball, we call this procedure, and pass it three values.

The first is foo_turn%, which lets the procedure know what column of the grid to use (from 1 to 10), depending on what turn of the game it is. We don't use the main turn variable as we may want to print out of position at somepoint.

Value two (pos%) gives the row in which we should print the ball (1 to 4).

Ball% gives the number of the ball which is 1 to four (on easy skill) up to 8 (on hard skill). Ball%. Can also take the value of zero, which will display a blank square.

We then use those numbers in the gAT ( coordinate, y coordinate) to move the cursor to the correct starting pixel for our two gCOPY commands.

Why have we not used one gCOPY command? It's because we have a background. If you copy the square that contains the ball directly into the grid, (gCOPY with a (3) the in the white spaces around the ball are copied as well, obscuring the background.

If you use the gCOPY flag (0) that only sets the pixel, you'll fin the background image interferes with the colours.

The solution is in two steps - one per gCOPY command. Have a glance at the single mbm graphic that holds all the coloured balls. The first square is a ball that is all black, with no shading on markings. This is a mask. If you look at this next to one of the true ball icons, you'll see that every black pixel in the mask corresponds with a black or coloured pixel in the real graphic.

If we now use gCOPY flag (1) - which is 'clear pixels' all the pixels that are black in the mask will be cleared from the main window. This is our first gCOPY command above.

We can now safely use the gCOPY flag (0) that only sets the pixels, because the pixels that are being set, are all being set on cleared white pixels! And voila! We can now copy our coloured ball into place, and leave the rest of the background intact.

Showing Spaces

Hold on though. In the application the procedure looks like this.

PROC m_showball:(foo_turn%,pos%,ball%)
   gUSE id%(1)
   gAT (foo_turn%*36)+5,((pos%-1)*36)+5
   IF ball%=0
      gCOPY id%(9),foo_turn%*36)+5,((pos%-1)*36)+5,36,36,0
      gCOPY id%(10),0,0,36,36,0
   ELSE
      gCOPY id%(10),36,0,36,36,1 : rem * Mask
      gCOPY id%(10),(ball%+1)*36,0,36,36,0 : rem * Ball
   ENDIF
ENDP

This is because we need to do something slightly different when we want to clear a ball. We don't want to punch a hold in the background image (or overwrite a ball already there). What we want to do is restore a portion of the background image (the first gCOPY line) and then copy the grid line from the mbm (the second gCOPY).

Laying out all the Boxes

So, now we have all the elements to draw the grid on the screen. Almost. Two new commands for you to look at.

gBOX width,height

This draws a box, with the top left corner where your cursor is at (remember this is changed by gAT x,y).

gLINEBY x_distance,y_distance

This draws a line from the cursor to a point that is x_distance to the right, and y_distance down. If you use negative numbers, then it is to the left and up respectively.

Lets look at the procedure...

PROC init_display:
   LOCAL foo%
   rem *** Copy the background into the main window.
   gUSE id%(1)
   gAT 0,0
   gCOPY id%(9),0,0,548,200,3
   rem *** Draw the squares of the grid using supplied bitmap
   foo%=-1
   DO
      foo%=foo%+1
      m_showball:(foo%,1,0)
      m_showball:(foo%,2,0)
      m_showball:(foo%,3,0)
      m_showball:(foo%,4,0)
      m_showguess:(0,0,foo%)
   UNTIL foo%=9
   rem *** Draw the outside of the grid and the solution boxes
   gAT 5,5 : gBOX 360,145 : gAT 5,157 : gBOX 360,37
   gAT 398,5 : gBOX 37,145
   gAT 398,41 : gLINEBY 36,0
   gAT 398,77 : gLINEBY 36,0
   gAT 398,113 : gLINEBY 36,0
   gAT 398,157 : gBOX 37,37
   gVISIBLE ON
ENDP

The rem statements show what's happening in each section. Note the use of a DO... UNTIL... loop to make our life easier for the largest grid. In the loop, we draw both the guessing grid (on the top) and the how well we did grid (on the bottom). Because of how our mbm is laid out, we need to draw in manually the right hand edge and bottom edge.

Finally, we draw the column on the far right that we will use to show the correct solution when our ten guesses are up, or when we correctly guess the solution.

Showing Guesses
Have a quick look at PROC m_showguess%:(right_place%,wrong_place%,foo_turn%). When we come around to doing the part of the program that needs to show how accurate the guess is, we'll use this procedure.

But we'll also use it to show a blank space, and this is the only part of the procedure currently listed. It's the same theory as showing a blank space in the PROC m_showball:

Conclusion

So, if you run Master now, you should see the main grid. Okay we can't see any balls, even though we've discussed how we're going to do it in this part, but relax. Next week you'll see how to put a cursor onto the screen, move it around, and use it to select your four coloured balls to make a guess!

Source Code
You can download the OPL source code for Master as it is at the end of tutorial 5 here. You can download the opo program (the runtime file) as it is at the end of tutorial 5 here.

Part 4: Creating the MBM's

Mon, 25 Aug 2003 19:41:17 +0100

Creating MBM's

If you go back to our sketch of what we wanted Master to look like, then you should be able to break it down into windows and bitmaps. The window part is the easiest. The outside status bars, titles and CBA bars are something controlled from code, and do not need graphical windows. Our main display can be represented by one window (in fact, it needs to be as it will have the background).

Looking at the bitmaps we'll need, we find the following...

The FreEPOC Logo
Standard FreEPOC practice is to have the FreEPOC logo available as the first bitmap in any mbm, even if it is not shown in the program. If you have your own logo, this is a good place to put it.
The Program Icon
Used in the About box, this will be the same as the icon we eventually use to represent the program in the Extras screen. we'll do that later in the course, but for the meantime, we still need the large size available as a bitmap. This is it.
The Balls
Cunningly, we store all our balls in one strip, along with an initial blank grid square in the first space, and a 'mask' in the second space we can use to punch out a hole in the background wallpaper so the balls can be copied over to preserve the background. This technique will be discussed later in it's own section, because it's really important and something you can use in pretty much any application.
The Clues
In a similar way to the Balls bitmaps, this is the bitmap that gives the user the clues to what is in the right place and in the wrong place.
The Cursor
used to move up and down the grid so the user can see what ball they will change.
Background Wallpaper
Pretty self explanatory. The wallpaper here is a simple blue sheet of paper, but you can substitute whatever you want.

Create your bitmaps in any graphics application (personally I use Windows Paint, it gives you pixel perfect control - but anything will do). Save them as Windows/OS2 bitmaps into an easily findable folder. To get you started, here's a download of the bitmaps we'll use in Master, although you're free to design your own!

Using MBM Whizard

Dazler has programmed a GUI for the Symbian utility bmpconv.exe which is normally used for creating and opening mbm files on the PC. You can download MBM Wizard from Dazler's Nokia site. On this site there is the program itself as well as a very useful tutorial on how to use both bmpconv and MBM Whizard.

Using MBMWhizard is very straight forward. MBM Whizard is a Windows GUI for Bmconv. It allows you to quickly create/update archives and even browse them. All the functions of MBM Whizard are a combination of bmconv commands. Only the converting of images from Jpg,Gif and Bmp to bmp is done by MBM Whizard.

When you open MBM Whizard you will be presented with a new project. You can now include files in the project and specify their colour. After this you can use Save/Save as to make the mbm file. You can start a new project at all time by selecting New in the File menu.

Go and have a play with MBMWhizard - it should be obvious how everything works, and if it is now - then there is some great documentation with the program.

Conclusion

It's hard to belive, but you've now coded almost everything you will see in Master. Planning the program before starting to code means that all we have left is to change the Event Core to reflect the new app, add in the subroutines for key presses and events and we'll have the app running to a good standard. That should take us over the next two or three lessons!

Part 3: Designing the Application

Mon, 25 Aug 2003 19:39:25 +0100

Fail to Plan, Plan to Fail
It's an old adage, but it holds true in program design more than anywhere.

One of the aims of this tutorial series is to show you how to create your own OPL application that you can distribute yourself. To do this, we're going to design a game from scratch, and using the Event Core, build it up into a full application before your very eyes.

We're going to build a logic game called Master. Based on the board game Mastermind, there is a 4 colour code that you need to guess. When you make a guess, you are told how many colours are right in the right place, how many are in the wrong place (but are in the final code) and how many are colours are not in the final code. You get 10 guess and if you don't work out the code, then you loose!

Just to reiterate, there is no right or wrong way to go about designing and coding an application. This way is the way that I have found to be best for me. If you want to change anything, or do things in a different order, then feel free.

How to Play Master
What you need to do now is break down the application into smaller sections - each section will consist of a few procedures, and individual steps in these sections will probably be the individual Procedures.

If we go back to our story metaphor, you're breaking the application down into chapters and paragraphs so that the translation into OPL code is easier then if you tried to write it straight down onto a blank sheet of paper.

User Interface
Put simply, what does it look like? Take a few seconds to sketch some ideas out on some paper. Don't worry that you don't know how to work the graphics yet, what you want is a flavour of your aim. We can improve it later.

Master's initial UI sketch

One other thing you need to decide is what information bars will be permanently on screen. You can choose from the CBA side buttons (on the right), the Title bar (along the top), and the Status bar (on the left). For Master, we'll show all three, and these will be specified in the initial .ini file settings in the code (PROC LoadINIFile:)

Note that many applications allow you to change the toolbars being on or off from within the program. We will look at this at a later date, but for the moment, let's leave them fixed. Once you've worked on a few of your own applications, it will become a lot clearer.

Background Wallpaper
One thing that will make Master stand out is the program will not be played out on a white screen, but will have a background 'desktop' style image. Not only will this teach you different graphics techniques, but it also adds to the appeal of the application.

Never underestimate the power of something simple to improve an application in the eyes of the user. In the game Quad, at the last minute I added a small routine that showed (over 4 windows that displayed a simple graphics and a few lines of text) the basic principles of the game. It was only shown the first time the game was opened (although it could be called from the menu at any point). While all this information was in the help file (as it should be) almost every review highlighted this tutorial as an amazingly helpful feature. For the small amount of effort, the rewards to the user and the programmer were immense. Take note.

Controls
The user will have five controls, the cursor keys and space to select a colour. On the game grid, up and down will move an on-screen cursor up and down, selecting where to place a colour. Using left and right will cycle through the colours. Pressing space will make a guess with the listed colours.
As well as this, the menu will the basic menu entries that the Event Core has. In addition to this, it will also have options to select the difficulty level of the the game

Difficulty Levels
The easiest way to increase the difficulty of the game is to increase the number of coloured balls. So the easy skill level will have 4 colour, the medium will have 6, and difficult will have 8.

Using Graphics in OPL
It's been a long time since computers only had text characters to display on the screen. Now you can create and manipulate small pictures to create a much clearer display for the user. It has also made computers easier to use (although Command Line Interfaces like DOS and the Linux Console still have their place).

Anyway, you have two basic graphical elements in OPL. When you initialise them, each item is given a reference number by the computer. Rather than remember these arcane numbers (and they can change each time a program is run), you can hold them in an array. In the Event Core, the array id%() is used, so you can use id%(1), up to whatever the maximum number you defined in the GLOBAL id%(x). 16 is probably more than enough.

Windows
A window is where you will place your graphics. Consider it the sheet of paper you're going to work with. One of the great things about windows is you can have more than one of them, so if your screen is split into two views then you could have this made up by a window on the left, and a window on the right.

You must create a window before using it. When you create it, the window number is RETURNED from the command, and it is this number you store in the id%() array...

id%(1)=gCREATE 0,0,640,200,K_Const_256Colours,1

How it works. The first pair of numbers (0,0 in the example) represent the top left corner of the window. In the case of (0,0) this means the window starts at the very top left of the Communicator screen. These co-ordinates are in (x,y) format, so (320,20) is halfway across the screen, 20 pixels from the top of the screen.

The next pair of numbers (640,200) represent the width of the window (here 640 pixels) and the height of the window (200 pixels).

The second last number isn't a number at all! Here it's part of the default Constants. This number decides how many individual colours a window can show. While the Communicator can support up to 4096 colours, for all practical purposes 256 colours will be more than enough. There may even be circumstances where you want to allow less colour in a window, dropping to 16 colours, or even black and white monochrome if it is a text only window. The main reason for this is that the less colours required in a window, the less memory it takes up.

Bitmaps
Your bitmap is the graphic that you make up in a graphics package and include with your application. You can have lots of little pictures, or one big one and copy over only the part you need onto the paper (the window). The first thing you need to do is load the bitmap into the memory of the machine. Just because it has been copied onto the disk, that doesn't mean the program can see it.

id%(9)=gLOADBIT("D:\System\Apps\Master\Master.mbm",0,3)

This will load the bitmap from the file master.mbm in the directory D:\System\Apps\Master\ . The two numbers at the end are very important, and will change depending on the file.

The second number (3), tells the computer what bitmap to use from the MBM file. MBM files can hold Multiple Bitmaps (hence .mbm). The first bitmap is bitmap 0, the second is bitmap 1, and so on.

The first number determines if you can alter or edit the bitmap within the program. Unless you are doing an art package, or need to manipulate the mbm for some reason, you would leaves this as read only, which is 0. (to be able to edit, put a 1 here).

Closing Graphical Elements
Whenever you finish with a graphical Window or Bitmap, you should close it. This makes sure that memory is reclaimed by the computer, and your application is more effective. This is done simply by

gCLOSE id%(foo%)

Where foo% is the array index number. A good idea at the end of every application (in PROC exit:) is to double check all the elements are closed.

foo%=0
DO
   foo%=foo%+1
   TRAP gCLOSE id%(foo%)
UNTIL foo%=16
REM *** Where 16 is the number of elements defined in the id%() array.

TRAP will, of course, make sure an error is not raised if the graphical element isn't opened.

Copying MBM's To Windows
Let's break down the command that allows you to copy bitmaps to windows.

gUSE id%(1)
gCOPY id%(9),100,0,40,50,3

The first command (gUSE) tells the computer what graphical window is to be made the current window. When you gCREATE a new window, it is automatically made the current (or active) window, but it is always best to use the gUSE command before any graphical operation.

Now the gCOPY command. The first number, id%(9) tells the computer which bitmap is to be copied from, into the current window. You now specify an area of that bitmap to copy. The next two numbers (100,0) say where the top left corner is (in pixels), measured from the top left corner of the bitmap.

The next two numbers (40,50) specify the width and the height of the portion of the bitmap which is to be copied.

The image to the left shows an example of the gCOPY process described above.

�

The final number determines how the bitmap is to be copied. Here's the different ways you can copy images. The checkerbboard is being gCOPY'ed in these examples onto the straight lines, and only the final number is changed to show you what you can do.

Mode 0 (Set)	Mode 1 (Clear)	Mode 2 (Invert)	Mode 3 (Replace)
�	�	�

Time To Rest
It may seem like that for the last three lessons, you've been reading and there is very little practical examples of what I promised. Well, in the next lesson, we're going to construct the mbm file for Master, and start the coding in earnest!

�

Part 2: Understanding the Event Core

Mon, 25 Aug 2003 19:35:14 +0100

Where to get the Event Core
The Event Core we're using is provided by FreEPOC. It can be downloaded from their website (www.freepoc.org/core.htm). You should download this so you can look through the OPL code as we discuss it here. Intallation instructions (for OPL) are in this tutorial.

Building Blocks: Procedures (Again)
Right then, in the last lesson, you got to grips with procedures. Before we move on to look at the Event Core, I'm going to show you how to make Procedure a bit more efficient. Have a look at this.

PROC addition:(one%,two%)
   LOCAL foo%
   foo%=one%+two%
   RETURN foo%
ENDP

Now this is a silly simple procedure that doesn't do much that couldn't be done in a single line of code, but it shows you two more principles. And you should be able to see how more complicated work can be done inside the procedure.

Passing Variables to Procedures: Local Constants.
Where we've named the procedure we've added two integers inside some brackets. When you call the Procedure you need to supply these two numbers like this...

addition:(200,100)

or...

addition:(number%,300)

one% and two% don't need to defined as variables, because they aren't variables. They're constants that only exisit inside a single procedure. Think of them as the LOCAL variant of a constant. After you leave the procedure, their value is lost - and this is why you need to pass a number to the procedure every time you call it (although obviously it can be different every time!)

Returning Variables from Procedures
Here's something handy. If instead of calling our addition subroutine by a simple line, if we call it like this...

gnu%=addition:(100,200)

...we can make gnu% equal the number that we RETURN from the addition procedure. When you work through a procedure and come across the RETURN statement, the program does not read the rest of the lines in the procedure, but returns immediatly, as if the ENDP line had been ready.

If you don't give a RETURN and ENDP is reached, then ENDP will return the number 0.

How The Program Story Unfolds
In part one I asked you to think of OPL as a language. I want to continue this analogy and ask you to think of your program as a story. Like any good fictional construction, you need three parts to any story. The beginning, the middle and the end.

The begining of your OPL Program will gather information about the computer and about the personal preferences that the user is using in the program. It will then go on to set up any graphics the program needs. Finally, it will draw the main screen, and have everything ready for the middle.

The middle of the program is where all the fun happens. It's based round running a simple looping routine which checks for keypress and messages from the computer, processng these keypresses, checking the results, and going around the loop again until the program has to stop

The end of the program cleans up things that shouldn't be left behind, saves any changes to the preferences, saves any data that may need saved, and exits the program.

So, you'll get something like this in the main procedure...

PROC main:
   GLOBAL exit%
   initialise:
   exit%=0
   DO
      main_loop:
   UNTIL exit%=1
   clean_up:
ENDP

Notice how we use a variable that can be set anywhere within the main_loop: to exit the program. This is so that the computer can always finish what it needs to do, come back to the main procedure, and then move to the clean_up: procedure to make sure everything is saved.

Let's look at what happens in each section in more detail. It might be an idea to open the event core OPL code (core.opl) so you can follow the code through, we'll only brush on the highlights here.

The Begining
The majority of the work is carried in the Event Core's initialise: routine in the following order.

Where Are All The Files
First we check to see if we can locate the 'support' files for the running app. As almost every app you'll program will have some graphics, this section is dedicated to looking for the graphics .mbm file. Using the name of the applicaction specified in one of the constants (look at the very top of the code for these), we look through first the C: (internal disk) and then D: (the MMC card). If we find it, then we save the location in both path$ and data$. Path$ includes the drive the .mbm file is on, and data$ stores it without the drive information (you'll see why in a second).

You'll notice that this check uses the IF... ELSE... ENDIF... loop we discussed in part one, but we add in an extra IF check using ELSEIF. In this way you can have as many decisions as needed in an IF statement.

Personal Preferences - .ini Files
Now we load in the users personal preferences. These are stored in core.ini (or whatever the application's name is). We goto PROC LoadINIFile:. If the file exists, we open the file. If it doesn't exist, we enter some default values, and then immediatly save them.

This is where we use data$, as .ini files should always be stored on the internal disk (hence "C:"+data$). In the core, we only have one preference, which is the sound volume. The .ini file is in fact a small database. Each of these databases is allocated a letter when opened, and then each field is given a temporary label...

OPEN "C:"+data$,A,label%

So we're opening our applications .ini file on the c drive, we'll refer to it as database "A" and the only field is going to be temporarily refered to as sound_vol%.

We can now set the application variable to that in the database with the line...

sound_vol%=A.sound_vol%

Note how we use the database letter and the label. It's good practice to give the labels the same name as the variable in the application, but it is not a requirement.

And when we're finished, we CLOSE the database. You should always close things when you're finished with them. It means you use less memory, and your application will run faster.

Saving the preferences is a very similar process. Firstly we ake sure the directory exisits on the C drive. Once we're sure this is made, we DELETE the old (un-needed) .ini file, CREATE a new one and set the values.

Once all the values are set, we must save the changes into the database by using the APPEND function. This adds the information to the end of the database. As it is a new database (we deleted the old one) then it will always be the first record. We then CLOSE in the same way as before.

You'll notice the use of TRAP as a keyword. TRAP simply suppresses any error messages that may occur from the command on the rest of the line. This way, if the directory we are trying to create already exists, our program won't panic and stop, but will carry on.

Setting Screen Sizes and Toolbars
Whenever an OPL program is started, it will immediatly create for itself a blank window taking up the full size of the screen. Now, some programmers will use this window, others will leave it sitting in the background, and some will change its size so it hides anything behind it, but isn't actually used for anything. This is the approach our Event Core uses...

gDEFAULTWIN x,y,width,height

is where we alter the default window. (x,y) determines where the top left corner of the default window is (in relation to the top left of the screen), and width and height change the dimensions of the window.

The width of the whole screen is 640 pixels. Looking at the left hand toolbar, this can either be off (0) or on (1). The size is set by the type, small (1, which is 32 pixels wide) or standard (0, which is 96 pixels wide)...

AfSetStatus%:(AfStatusType%)
AfSetstatusVisible%:(AfStatusOn%)

The right hand CBA button can be either always visible (1), or only show up when a CBA button is pressed (0). The width is between 80 and 130 pixels, depending on how long the text labels for the buttons are.

AfSetCBAVisible%:(AfCVA%)

The title bar is the blue title that stretches along the top. It is XX pixels high. Set is as being visible (1) or hidden (0) with...

AfTitleVisible%:(AfTitleOn%)

You can also specify what text is shown in the title bar with the folowing command, Note that you would normally have the program's name in the title bar. Note the Constant used from the standard external file to say it is the main title.

AfSetTitle:("Title Here",KAfTitleTypeMainTitle%)

All the above values for these bars are held by Event Core in the .ini file. At the moment, you decide what bars are shown by your app when you code it, and they do not change. Later on, you may want the user to be able to decide what they want to see or not see, so you will need those values stored in the .ini. This is a good example of thinking ahead when programming, even if (in the end) it is something you never use.

Now, to start our display, we create one window that fits within the the tree bars (status, title, cba) if they are open or not. This is the primary screen and we'll do most of our work in here. Just to prove that it is working, we also copy the FreEPOC logo into the window from an external graphics file. We're taking a detailed look at graphics commands in the next part, so for the meantime I'll leave these unexplained. See if you can work out what's going on!

The Middle
Rather than the simple loop shown at the start of this part, our Event Core has two DO... UNTIL loops, one within the other (this is called a nested loop). This is to help with applications that are on a 'level by level' design (eg Vexed). What happens is the 'outside loop' reads something like this...

exit%=0
DO
   load_the_next_level:
   initialise_level:
   level_completed%=0
   DO
      play_the_game:
   UNTIL level_completed%=1
UNTIL exit%=1

From this, you'll see that this makes a lot more sense, is easier to read, and keeps your app as small and easy to follow (and program) as possible.

The Main Event Loop
This is scary stuff, and there is no simple way to ease you into it. The best you can do is understand what is going on, and leave it at that.

Commands From The System
Firstly, the program checks to see if it has been told to do anything by the computer. The computer sends messages in a text string, and you retrieve this with...

c$=GETCMD$

Three options concern you...

IF LEFT$(c$,1)=KGetCmdLetterExit$
   Exit:

This is self explanatory, and tells the app that it is to close immediatly. We could use the OPL command STOP here which closes everything, but we want to save our preferencesand exit gracefully. So we jump to our exit: procedure (which we talk about in a few paragraphs.

ELSEIF LEFT$(c$,1)=KGetCmdLetterBackup$
   Exit:

Pretty much the same as before. here the Communicator is being backed up. Again we want to gracefully exit, saving changes as we go, so the most recent version of the information has been saved.

ELSEIF LEFT$(c$,1)=KGetCmdLetterBroughtToFGround$

The program has been jumped to. Now in some programs, you'll need to update screens and variables, in others you won't need to alter anyting due to being in the background for some time. It depends on the application. If you needed to have a procedure when called back, you'd jump to it from here.

Reading Keypresses
Next the system decides if it has been sent a keypress to act on. If it has, it jumps to a procedure (PROC g_kbddrv: for keyboard driver) to process this key.

(If ER6 OPL is ever installed on devices such as the P800 or 7860, then a further check would be made here for pen taps. If this ever happens, I'll gladly write another tutorial on pen events!)

Acting on CBA Buttons
If a CBA button is pressed, then the application jumps to the XXXXX-CBA routines and decides what button was pressed (1, 2, 3, or 4), and jumps to the relative procedure. This is a call-back function and because of this, you cannot exit an application from within a call-back function. This is a problem if you press CLOSE. So rather than jump to the exit, we simply set the level_completed% flag (or whatever variable we are using to scan for "I want to exit now") and let the main loop routine exit that application gracefully.

Processing the Keypress (g_kbddrv:)
You'll spend a lot of time in this procedure. Here is the meat of your app. If a user presses a key, it's this bit of code (with a very long IF statement) that will call the correct procedures and carry out the relevant actions.

The first few sections of this procedure concern themselves with the modifier keys, such as Shift, Ctrl, Fn, and their various combinations.
The next line detects the menu key. If the menu key is pressed, then we jump to the g_menu: procedure, which will RETURN the equivalent keypress. (ie if we select Save-ctrl-s from a menu, then the procedure returns the letter s).

Now we look for two special events, the Infrared being switched on or off, or a request to add a shortcut to the application onto the desktop. You need to add these in the Menu subsystem (that's coming up!). Now, you'll see that the two procedures called are not in core.opl. Where are they?

The answer is hiding at the very top of the code in the lines...

INCLUDE "AppFrame.oxh"
INCLUDE "System.oxh"
INCLUDE "DBase.oxh"
INCLUDE "SendAs.oxh"

These OPL Extension Header files refer to things called OPX's. OPX's are small items of C++ machine code that can be called from OPL by a procedure call. OPX's usually deal with calls directly to the CPU to do specialist jobs - in this case the infrared and Desk screen. Any OPX's INCLUDED can be called at any time in the same way as normal.

We'll look at OPX's in a later tutorial.

And now we're at the part that actually does something...

ELSEIF Key&=%A
   g_About:

...and so on. This part of the statement checks if shift-a has been pressed. Two things to note. The first is the % in front of the letter. This is a bit of OPL shorthand that says (the computer code for the following letter). 'A' is represneted by the number 97, so %A=97. This makes your code easier to read, and still understandable to the computer.

The second is that %a is different to %A. The second is shifted, the first isn't.

The Menu Procedure - Showing What You Can Do
The menu procedure is a piece of cake. First you initialise the menu system with the command mINIT. You then define each top level menu (eg File... Edit...) in an mCARD command like this...

mCARD "File","Create new file...",%n,"Open File",%o

The first string is "File" and this is what appears in the top menu bar. The next pair of string and number is the first line, with the text of the option ("Create New File...") as the first, and the hotkey that this command represents the second.

You'll notice that these numbers (%n for New file) are the same numbers that we look for in the g_kdbdrv:. So you program once and get two outputs (hotkey and menu). This is what all the modifications are for.

We then use a temporary variable to store the result of the MENU command (which displays the menu and returns the simulated hot key).
Having a second menu come off one menu option (eg any menu with "More >") is something you may want to use. Fistly define the second menu (the one that is sprouting from the first) using mCASC. Then using a ">" symbol, refer to it in any mCARD line after the mCASC.

mCASC "Databases","Create",%c,"Query...",%u
mCARD "File","Databases>",16

The number 16 puts up the little arrow symbol where the hotkey definition would normally appear.

The End
At some point our application will need to stop. Those looking through an OPL command list will find the useful STOP command. But you need to do a few things first. This is why when our Event Core needs to stop, it calls PROC exit:

This routine does a few vital housekeeping tasks. Firstly it saves the current preferences. It then closes all the graphical windows (so the computer can reclaim the memory efficiently).

Only then can we safely STOP the application.

The First Preview!
Phew! There's a lot going on there. Hopefully you've been able to read through the code at the same time as this part. It does make it easier to understand, trust me.

Now you know what's going on, it's time to press the compile button. After a few moments, you'll be asked if you want to run the compiled program (if you get an error message, check carefully what you've typed and make sure everything is correct. even a stray comma can upset the translation). After a few moments you'll be presented with the FreEPOC logo on the screen, and the menu and Command Buttons at the side should response. Have a play around and see what happens.

You've just compiled the OPL code of the Event Core! Don't be afraid to change the code and experiment. You can't damage your Communicator doing this, so don't worry.

Part 1: A Crash Course in OPL

Mon, 25 Aug 2003 19:32:14 +0100

Where to Start
To begin, you should obtain a copy of the OPL manual for the Psion Series 5mx range. This is available in a ZIP file in the OPL Devkit. The majority of the language is unchanged from ER5 to ER6, major exceptions are noted in the Porting Guide supplied with the OPL ER6 SDK.

The important chapter is Chapter 15. This gives you the structure of each command, and a short explanation of what it does. You'll use this as a reference a lot during coding, keep it close at hand.

First Steps
Think of OPL as a story in a language that is almost, but not quite, English. It's easily readable by you, and if you translate this OPL code, it is easily read by your Communicator. Think of it as a halfway house between you and the computer.

As with any language, there are ways of speaking, and different elements. English has sentences, paragraphs, nouns, verbs and so on. OPL has it's own elements.

Procedures: Where you hang your Code.
When an OPL program is run, the frst procedure (here called PROC main:) is opened. The lines are then read and processed in the order they are listed, until ENDP is reached, at which point the program ends.

Now within a procedure, you can call another procedure. Do this by simply typing the name of the procedure you want to run next. All procedure names must have a colon after them (that's the two dots above each other).

PROC main:
setup_app:
do_something_nice:
save_status:
ENDP
PROC setup_app:
REM Do something interesting here
ENDP
etc...

So main: is opened, it calls three procedures in order, then reaches ENDP, and the program closes. Note that each procedure must start with PROC <a name>: and end with ENDP on seperate lines. When the end of the first procedure is reached, your OPL program stops. The only way t run other procedures is to call them.

Procedure names cannot have spaces, hence the use of the underscore. You'll see that underscore used a lot as a seperator!

Constants
Constants are exactly that. They are things that never change. You can use them so code is easier to read, for example rather than having to type the number 103782376892 every time you need to use it (assuming it is something that appears a lot in your app) you could put...

K_Big_Number%=103782376892

...at the start of your code, and then each time you need to use the number, use K_Big_Number% instead. By convention, you shuld prefix K_ in front of any contant name.

Once you see some example code, constants should be a lot clearer. One thing to point out now is that there are a lot of default constants. If you have the line...

INCLUDE "Const.oph"

...then these default constanst can all be used. They are detailed in the documentation provided with the OPL Development Kit from Symbian. You should print this out and keep it to hand. it will be useful later!

Variables
A variable is somewhere where you can tell your computer to remember a piece of information. This is normally a small number, a big number, or a string of letters and numbers. Each of these variables is given a name, and a small sign to indicate what type of information it is. You should also remember these names cannot have a space in them, which is why you'll see so many names with the underscore character in them!

Types of Variables
A small number (called an integer) is followed by a % sign. For example, high_score% is an integer that stores a number referred to as high_score. An integer has to be a whole number (ie you can't have high_score%=2.5, but you can have high_score%=2 or high_score%=3).

A large number is followed by a & sign. For example, big_number& is a large integer that stores a number referred to as big_number. Large integers can be fractions (so you could have high_score&=2.5).

A string of letters and numbers is called (funnilly enough) a string, and is followed by a $ symbol, For example, name$ cold be "ewanspence"

Defining a Variable
Before you can use a variable, you need to have told your program that you are going to use it. Think of it as making a little space to store the number. There are two ways of defining a variable.

A GLOBAL variable is a variable that ANY procedure can use.

A LOCAL procedures is a variable that only that specific procedure can use. When you leave the procedure, the little space for the number is reclaimed. Local variables are good for temporary counters and bits of info that are only needed for a few moments.

The command to set a variable needs to be the first lines of a procedure. Global definitions must be the first lines in your first procedure, and local procedure mus be the first lines in the relevant procedure.

You can put more than one definition on a line. Seperate them with a comma.

PROC main:
GLOBAL high_score%,big_number&

And...

PROC local:
LOCAL name$(20)

You'll note that after defining name$ we have a bracketed number. This tells the computer the maximum length (in characters) the string is going to be. You need to define the length of a string or when you translate the program for your computer, you'll get an error message.

Setting Variables
Variables are easy to set. Simply use the equals sign. For example

high_score%=56
big_number&=1383512467
name$="rafe blandford"

Setting a variable should be done on a seperate line for each command. Note that when setting a string, you have to use quotation marks. These don't appear as part of the string.

Arrays - Making a bigger Variable
One other tool you have in variables is an array. An array is a 'list of things. For example, if we wanted to have a table of 10 numbers, then instead of

GLOBAL table1%,table2%,table3%

Which would work (but will cause problems later), you can use

GLOBAL table%(10)

Which will create a table of 10 items. The first is called table%(1), then table%(2) and so on.

If you have a string table, then do

GLOBAL name_table$(10,20)

Which is a table of 10 strings, each a maximum of 20 characters long.

So why use name_table%(10) and not table1%,table2%, and so on? Because if you have another variable (eg lookupthisnumber%) then you can refer to name_table%(lookupthisnumber%). This is very useful if you think about it, as we're about to show you.

Loops
Loops are a great way to make your program do something over and over again, maybe with a few changes. Look at this code.

PROC loop:
LOCAL foo%
foo%=0
DO
foo%=foo%+1
table%(foo%)=foo%
UNTIL foo%=10
ENDP

Make sure you understand this code. The DO... UNTIL loop is a primary building block of code. Firstly we create a variable to act as a counter. In this case foo%. You'll see me use foo% (and gnu% and zsu%) as a temporary variable name a lot. If you do see it, you can assume it's a counter or another local variable.

Each time round the loop we add one to foo%, then make an entry in an array called table (which must be a Global variable as it's not listed as a local variable).

When foo% reaches ten, then the UNTIL stops the loop, and carries on with the procedure. As there is nothing left to do, ENDP will return the program back to wherever loop: was called.

Decisions
At many points in your program, you'll have to check something and do seperate commands depending on the outcome. To check things you use the IF command.

IF guess%=1
guess_right:
ELSEIF guess%=2
guess_close:
ELSE
guess_wrong%
ENDIF

Again, this is pretty easy to read. If the variable guess%=1, then goto a procedure called guess_right:. If guess%=2, then goto a procedure called guess_close: If guess% is anything else (a sort of catch all for any other condition, which is good programming practice to get into), then goto a procedure called guess_wrong:

The IF... ELSE... ENDIF is the second great building block of computing languages.

Making Sure You Don't Forget
Througout code you'll see lines like this...

REM This routine calculates the cursor position
or...
REM foo_x% represents the temporary x co-ordinate
REM foo_y% represents the temporary y co-ordinate

The power of the REM statement is in the fact it does absolutely nothing! Everything after the REM statement (until the next line of code) is ignored by the computer.

This means you can use it to leave notes for yourself, or to explain a bit of code to someone else who is going to read it. And if you come back to some code 6 months after writing it, wondering what PROC xyz_transposition: does, the REM statement you added will prove invaluable.

Summary
So, pretty easy? Of course it is! Although it is a lot to get around, so don't worry if it takes a few weeks to get to grips with it. In the next part, we'll have a look at the Event Core OPL code and see how it works. There's nothing to stop you having a look at it at the moment, and you can't break your machine by experimenting with the code. You'll find you can read and understand quite a bit of it. Some of it, especially the stuff dealing with getting keypresses and events from the keyboard, can be quite daunting... but this is the advantage of having a Core Framework to begin with, rather than a blank canvas!

Mobile Blogging

Mon, 25 Aug 2003 19:26:10 +0100

There�s a new world in cyberspace. It�s upsetting Search Engines. It�s moulding new opinions. It�s putting publishing power into the hands of individuals. It�s called blogging, and I�m going to look at how you can start your own blog � and use your Symbian phone to maintain it � no matter where you are in the world.

In the beginning there was notepad.exe and an ftp client. You manually hard coded your web page, adding in all the tags, formatting and info. Uploading them to a server, and voila. You had a website. You want to make a change? Dive back into the depths of the code, change it by hand, check it, and upload.

There was always a high barrier to starting your own website � but as the Internet became more pervasive, a new way to publish on the web came about. It started as Web Logging. A small application ran on a web server, so all the user had to do was type in the websites that they had visited, and it created a web page of those links. It didn�t stop at links. People started to post comments, what they thought about issues of the day, or perhaps they focused on one area (such as the current goings on in Eastenders). And another small app allowed people to leave comments at the bottom of the page for other visitors to read.

Thus blogging (weB LOGging) was born. Sites with short bursts of content, that rapidly changed. Daily updates is the aim of most blogs, although many are updated throughout the day. So, you want to join in? While you could start from scratch, download the Blog tools that run on your server, set it all up, fiddle about a bit, and finally get going, there is another option. There are many Blog communities out there that have everything set up for you to start blogging.

We�re going to look at Symbian Diaries. It�s specifically geared up to interact with your Symbian phone � and you can write about any topic under the sun. The front page (http://www.symbiandiaries.com/) has a list of popular sites on the right hand side. Browse them and you�ll find a wide variety of sites and uses. You�ll have personal sites where the topics can be wide ranging (such as my own at http://ewan.symbiandiaries.com/). You�ve got the Liverpool Java Users Group page (http://liverpooljug.symbiandiaries.com/) which keeps members of the User Group updated as to what is happening. How about a site to host an application? Same Game is a good example of this (http://samegame.symbiandiaries.com/). Symbian Diaries is flexible enough to allow all of these with very little set up work on your part.

First thing, of course, is to get yourself a blank Diary to work with. Symbian Diaries doesn�t have an automated system, so a short email to admin@symbaindiaries should see you sorted out. You�ll need to suggest a username and a password, and the return email will provide you a link to the Editing system. The front page of Symbian Diaries provides a link to the Tutorials section. In here you�ll find a few useful articles, but the one you�ll want to start with is called "How to Get A Symbian Diary." As well as the same information as the paragraph above, you�ll get information on configuring your Diary, helping you choose the look and feel of your diary, and how to make those all important entries. (Hint, it�s the button marked "New Entry" when you log in � Sophie).

The Tutorials also link to two pages that show you how to jump from blogging to moblogging. Mobloggin (MOBile weB LOGing� cripes!) is the new buzzwored. Put simply, it means making your blog mobile.

Symbian Diaries can do this in a few ways. The first (and unusually) is to provide your Blog to anyone out there who is mobile themselves. Symbian Diaries generates not just web pages, but pages for WAP and XML browsers as well. Have a look at http://ewan.symbiandiaries.com/index.wml on your Symbian Phone and compare it to my full blog on the web. All the content is still there. Making your WAP site is easy, just follow the tutorial provided!

The other service for Moblogging, is making posts to your Blog directly from your phone. Imagine you are at the Great British Beer Festival (it is next week at Kensington Olympia!), and you want to let the whole world (or at least those who read your blog) to know what you think about the Beer. With a mobile blogging tool, you can do just that.

Symbian Diaries provides a few ways of doing this. The first is to use your built in email client on your handset. You�ll need to ask the Admin team to set the address up for you, but once it is in place, you can do all the composing on the handset, and on sending the email, it will get turned into your latest post on your Blog. This has the advantage that MMS (which can be sent directly to an email address on most networks), can be used as well if you haven�t got email working - or you have a phone which only has MMS, though why you�d be reading Your Symbian if you didn�t have a Symbian phone�).

But one of the most powerful ways is to use an application called Azure. Azure (and surprisingly there is another template on how to use it!) allows you to log in from wherever you are, and not only create a new post, but edit your existing points (handy when you find a spelling mistake via WAP!), and work on entries, saving them as drafts as you go along. The majority of my site�s entries are drafted (at least in topics and areas to cover) over GPRS, and fleshed out at home. The great thing about using GPRS for this is that as you only pay for data transmitted, not time, you have a fraction of data as you log on, 15 minutes editing and typing, and another short data burst when you�re finished. Reckon on 4p at most for an update to your blog through Azure.

Some time ago, they said the Internet was mobile. Blogs are almost there, and Symbian Diaries has made it as easy as possible for you to join in the revolution.