IntroductionIn this tutorial you will get to know some of the basics of developing for mobile phones using C++. All the examples target Symbian OS and the Series 60 UI platform. Instead of long, theoretical explanations, a more practical approach is used. First, you will learn how to create your own mobile project. Then, you will add the prewritten game logic of a small Arkanoid-like game called Mopoid. This provides an interesting way to get to know important aspects of developing for Symbian OS, including: •defining and using menus, •handling and displaying text, •loading and showing images, •writing and reading data to/from files, •using a timer for periodic events, •and many more smaller, but equally important topics.... You will see the results of your actions right away. Whenever some Symbian OS specifics comes into sight (like memory handling), a short explanation will give you a brief overview of why it is this way and how to work with it. Of course, only the surface of all those topics can be scratched, as each of them would easily fill a tutorial of their own of this size. However, this tutorial will give you a basic understanding of how developing for mobile phones using C++ works, and it is a good starting point for your own projects. I hope that you have fun working your way through the tutorial and that you will get a nice game out of it! - Andreas Jakl
Symbian OS Workshop Step 12 - Displaying text ................................................................................................... 31Setting a font ................................................................................................................. 31Reading text from the resource file ........................................................................... 32Formatting and displaying the text ............................................................................ 32Aligning text .................................................................................................................. 32Step 13 - Reading and writing files .................................................................................. 34Preparation .................................................................................................................... 34Setting the file name..................................................................................................... 34Opening the file ............................................................................................................ 35Creating the stream ...................................................................................................... 35Writing the data ............................................................................................................ 35Closing the file .............................................................................................................. 36The Cleanup Stack ....................................................................................................... 36Loading .......................................................................................................................... 37Cleanup when your application is uninstalled .......................................................... 38Building from the command line ............................................................................... 40Step 14 - Setting the application icon.............................................................................. 40Step 15 - Handling being in the background ................................................................. 42Step 16 - Periodic Events.................................................................................................. 44Keeping the backlight on ............................................................................................ 44Using a timer ................................................................................................................. 45Stopping the timer........................................................................................................ 45Step 17 - Final notes .......................................................................................................... 46About the author .......................................................................................................... 46Contact........................................................................................................................... 46Copyright ....................................................................................................................... 47Step 18 - Exercises ............................................................................................................. 48Alternative key handling .............................................................................................. 48Define more levels ....................................................................................................... 48Saving the game progress ............................................................................................ 48
Step 0 -Preparation Download the following components: •ActivePerl: needed by the Symbian OS tool chain to compile your project http://www.activestate.com/•Symbian OS SDK:uses the Series 60 SDK 1.2 for Symbian OS,this tutorial Nokia Edition to provide the best compatibility with older Series 60 devices http://www.symbian.com/developer/sdks_series60.asp•Microsoft Debugging Tools:needed to debug applications in the emulator through Borlands C++BuilderX http://www.microsoft.com/whdc/devtools/debugging/•Visual C++ Toolkit:only needed if you dont have Visual Studio 6 or .net installed. Its free and needed to compile the projects for the emulator. Go to http://www.microsoft.com/downloads/and search for Visual C++ Toolkit to download it. •Borland C++BuilderX Mobile Edition (v1.5):get it for free by filling out the short survey athttp://info.borland.com/survey/cbx15_mobile_edition.htmlInstall the components in the order listed above. Allow all installations to add the programs to the systems path variable, in case they ask! Its recommended that you install the Series 60 SDK to its default location atC:\Symbian\! Getting started Should your application crash in the emulator, there is a way to make it display a more helpful error message. To activate this feature, create an empty file called ErrRd in the \s\cystsco23W\niataem\BootdnaibmyS\:CEp0\s6ieer\S.1\6 directory of your Series 60 SDK. Thats it. When you first start your copy of C++BuilderX Mobile Edition, it needs to be registered. Choose the activation file option, and locate the file that Borland sent you after you filled out its survey and registered for its development network.
Choosing an IDE The Symbian OS build tools are actually command line-based and would work without any IDE. However, development is more comfortable if you use one. There are several choices, each with advantages and disadvantages1: Microsoft Visual C++ 6
Symbian OS Workshop Choice of the Series 60 SDK The Series 60 SDK for Symbian OS is available in higher version numbers, which target newer Series 60 phones. Up to now, the devices have always been backward compatible, so an application developed for Symbian OS v6.x mobile phones (using the SDK v1.2) also works on newer Symbian OS v7.0s and v8.0 phones. While applications compiled using the SDK v2.0 (which mainly targets the Nokia 6600 with Symbian OS v7.0s) should still work on older devices, this can be a bit problematic. If the source code is compiled by even newer SDKs, the files are not backward compatible on a binary level any more. Which version of the SDK you use is entirely your choice. If you only want to develop for newer phones, or if you want to do new things that were not possible before, go with (at least) the SDK v2.0. Loading images and sounds has been specifically improved. Internet (HTTP) connections are easier to handle as well. If you want to develop a commercial application that should reach the broadest possible audience, you shouldnt exclude older Series 60 phones. By choosing to target Series 60 you already restrict your potential market. If you limit your target audience even more by making your program only compatible to the newest phones, you will have an even harder time selling it.
Symbian OS Workshop Step 1 - Defining the Symbian OS SDK
Fig. 1 Defining the Symbian OS SDK in Borland's C++BuilderX. Its time to start working! Open Borlands C++BuilderX Mobile Edition. Go to Tools→Configuration. Create a new SDK configuration, using theSymbian SDK SDK Template of the SDK you have installed, in this case: Symbian Series 60 1.x (Microsoft version). At least for the SDK v1.2, do not use the Borland SDK version, otherwise compiling the project wont work! Set the path as shown in the screenshot, and choose an appropriate name like Series 60 1.2. Step 2 -Creating a new project Create a new project: File→New...→Series 60→Series 60 GUI Application.
Fig. 2 Creating a new Symbian C++ project. Enter Mopoid as its name (dont use a different name for this project, otherwise some includes of the prewritten files we will include later on wont work). Place it in the C:/Symbian/dev directory and let C++BuilderX create a project subdirectory, so that all your projects will be kept separated from each other.
Fig. 3 Defining properties of the project (Step 1). Go to the next step. Enter the same name for the project, Mopoid. As we want to do a game, choose Full Screen as view type. The default UID3 proposed by C++BuilderX should NOT be used. Change the UID to something between 0x01000000 and 0x0FFFFFFF Symbian reserved those IDs for testing projects. Every application installed on a phone has to have its own unique UID. Therefore, if you want to release your game to the public, send a mail to uid@symbiandevnet.comcontaining your name and how many UIDs you need (5 should be sufficient for the beginning). They will send you the UIDs as soon as possible.
Fig. 4 Defining properties of the project (Step 2).
Step 3Testing the project -Your workspace should look similar to the screenshot in Fig. 5. Now is the time to test your project to see if everything is configured correctly. Press the Run Project button (F9).
Fig. 5 This is what the default workspace of Borland's C++BuilderX looks like. If everything works well, the emulator will show up after some time. Deactivate the memory resident virus scanner if you have one running to make this process a bit faster. Your own application will be located at the bottom of the menu, so move down using the cursor keys to select it. If you dont want to do this every time you test your game, select it, press the left softkey (Options), choose Move and move it to the upper left position of the menu. It will stay there even if you close the emulator and start it again. When you start the Mopoid application, you will only see a white screen. This is because we chose to create a full screen application, which does not have a visible status or menu bar. When you press the left softkey, a default menu will show up. In the next steps we will adapt it to our needs.