Symbols
.hrh files 188 control IDs 289 resource scripts 96 and operators data exchange 412 data, internalizing and externalizing 432 when to use 438 _assert_always macro 174 _assert_debug macro 174
Deviceindependent Drawing
Device-independent drawing is largely conducted by the cExample-HelloView class. Here is its declaration class cExampleHelloView public cBase void SetTextL const TDesC amp aText void SetFullRedraw TBool aFullRedraw void DrawInRect const MGraphicsDeviceMap amp aMap, CGraphicsContext amp aGc, const TRect amp aDeviceRect, CFont aFont const Firstly, note that it's derived from CBase, not CCoeControl. No CCoeControl-derived class can be device-independent, because controls are heavily tied to the...
Key Mapping
The majority of the PC keyboard is mapped in a straightforward way to the Symbian OS keyboard. However, some special keys are available The majority of the PC keyboard is mapped in a straightforward way to the Symbian OS keyboard. However, some special keys are available Help key this doesn't work in the UIQ emulator as there isn't a system help file Case close toggle when case is closed, window title changes to indicate it, and emulated keyboard pointer becomes inactive In different UIs, there...
Handling Asynchronous Requests
Servers are often associated with asynchronous request functions. As we saw in the last chapter, when examining the client API to a server, you can tell asynchronous request functions by their TRequestStatus amp parameter. Asynchronous requests are handled by the client interface by using a form of RSessionBase SendReceive that also takes a TRequestStatus amp parameter. The server keeps the message corresponding to the asynchronous request until that request has been completed. When the server...
Drawing the text
Now we are going to draw the text, centered in the rectangle. For good measure, we start by shrinking the rectangle by one pixel each side so that we can afford to white it out without affecting the border we have just drawn Then, we get a font from the Uikon environment const CFont font iEikonEnv- gt TitleFont This is our first encounter with a CFont . In Chapter 15, we'll have a careful look at how to get a font of a desired face, size, bold italic attributes, and so on. To avoid these issues...
State Machines
Active objects can be used to implement state machines. As an example, say, we wish to amalgamate the CDelayedHello and CFlashingHello functionality and so produce the effect of the Hello world message flashing on off once followed by the info-message with the same greeting. This cycle repeats until cancelled. This behavior can be represented by the state diagram shown in Figure 17.11. The state machine is initially in the Idle state and starting the machine moves it into the Show Hello state....
A Graphical Hello World The Program
Our example program for this section is hellogui, a graphical version of 'Hello world '. With the aid of this example, you'll learn how to build an application for the Uikon GUI. Since the application is intended to run on a P800 phone, I've used UIQ classes instead of Uikon ones, but I'll point out the differences as they arise. It will take more time to learn how a GUI program works and in this chapter we'll only briefly comment on the C code itself. There's nothing particularly difficult...
ESOCK and Symbian OS Support for SMS
Prior to Symbian OS v6.0, SMS functionality was provided through ETEL, the telephony server. As well as providing the facility for Transmission Control Protocol Internet Protocol TCP IP and dial-up networking to establish a point-to-point PPP data connection, ETEL also provided access to the phone books stored on GSM phones. This method requires a detailed knowledge of the structure and format of an SMS message. From Symbian OS v6.0 on, an alternative approach is provided through ESOCK, the...
K
KErrDied return code server deaths 601 key events 108 control stack 388 e32keys.h 372 focus 390 dialogs 381 processing 387 focus 391 LaunchFromClient function 640 GSDP server, launching 673 leave 10, 150 error codes 152 L suffix 152 nested traps 153 vs. error code returns 170 LeaveWithInfoMsg function 422 user errors 172 leaving functions 59 C constructor 161 heap failure 148 descriptor data, retrieving 127 TDesC abstract class 118 LineChangedL function implementing 301 CRgcpSession class 748...
Dont use the cleanup stack when you dont need It
You only need to use the cleanup stack to prevent an object's destructor from being bypassed. If the object's destructor is going to be called anyway, then you must not use the cleanup stack. If an object is a member variable of another class rather than an automatic like x , then it will be destroyed by the class's destructor, so you should never push a member variable to the cleanup stack. Member variables are indicated by an i prefix, so a code like this is always wrong This is likely to...
Source Compatibility
C is a platform-independent language that can be compiled to any instruction set. Symbian OS currently supports three ARM instruction sets ARM4, THUMB, and ARMI. ARM4 is the StrongArm instruction set, THUMB is the 16-bit ARM instruction set, and ARMI is an interworking build not strictly a separate instruction set that allows programs to call DLLs that are built either in ARM or THUMB. The PCs used to develop Symbian OS use the x86 instruction set. So, a C program for the emulator is compiled...
Designing Applications for UIQ Some Guidelines
By now, you may feel that you're beginning to get used to the style of applications built using the UIQ GUI. Style here is not in the way you program, but in the way that users see your programs. Good application style like good programming is partly something provided and enabled by the system, and partly something you have to do yourself. The application style guidelines for UIQ are designed to take some fundamental things into account End users may not be very knowledgeable about computers....
Standard Menu Items
UIQ defines a set of standard items that appear on the Edit menu such as Cut, Copy, Paste, Zoom and Preferences. Ifa Folders menu is used, the standard items are Business, Personal and Unfiled, with slight variations depending on whether you are in a List view or a Detail view. Clearly, not all applications need to feature all these items on their menu lists. Equally clearly, most applications have their own menus too. The UIQ Style Guide recommends you provide your application-specific menu...
Binary Data
You can use descriptors just as well for data as you can for strings. The main reason you can do this is because descriptors include an explicit length, rather than using NUL as a terminator. The data API and string API offered by descriptors are almost identical. The main things to watch out for are the following Use TDesC8, TDes8, TBuf8, TPtr8, and so on rather than their equivalent TDesC, TDes, TBuf, and TPtr character classes. Use TUint8 or Tint8 for bytes rather than TText....
Handling Multiple Objects from One Session
Sometimes it is useful for a single client-side thread to have multiple sessions with a given server. A good example of this is the socket server each socket created by the client could be a separate session. However, creating a new session consumes resources in the server and in the kernel to support it. Therefore, creating many sessions for one client thread may be inefficient. An alternative approach is provided by the use of subsessions see Figure 18.4 . In general, if your client thread...
Compiling a Resource File
The resource compiler is invoked as part of the application build process, either from within the CodeWarrior iDe, or from the command line with, for example As we saw in Chapter 1, this command runs the build in six stages, one of which is resource compilation. From the command line, you can invoke the resource compiler alone with a command of the form but you must first have run the abld makefile command to ensure that the appropriate makefiles exist type abld on its own to get help on the...
Process launch on Symbian OS
On real Symbian OS platforms, a process is launched from gsdpexe.exe, whose E32Main function is also designed to pass the parameter quickly to CGsdpScheduler TServerStart start TInt r start.GetCommand if r KErrNone r CGsdpScheduler ThreadStart start The CGsdpScheduler TServerStart class is designed solely to allow the client thread to pass a TRequestStatus in such a way that it survives either the thread launch or the process launch above. This allows the server to signal success or failure...
Emulator Command Line Syntax
The command line for the emulator syntax is epoc -M lt machine name gt -T -C lt emulated C drive gt -Note that the command line must be terminated with two hyphens. These command line options are not available with the command line tools that get installed with the SDK. In order to use them, you need to invoke epoc .exe from the directory where it is located to prevent the developer kit tools being picked up. If you want the emulator to use console .ini, start it up with this and yes, you...
What Kinds of Error
It's easiest to start this chapter by focusing on out-of-memory OOM errors. These days, desktop PCs come with at least 256 MB RAM, virtual memory swapping out onto 20 GB or more of hard disk, and users, who expect to perform frequent reboots. In this environment, running out of memory is rare, so you can be quite cavalier about memory and resource management. You try fairly hard to release all the resources you can, but if you forget then it doesn't matter too much - things will get cleaned up...
Multitasking and Preemption
Symbian OS implements preemptive multithreading so that it can run multiple applications and servers simultaneously. Active objects are used to implement non-preemptive multitasking within the context of a single thread. Active objects, like threads, have priorities that affect their scheduling. On completion of its execution that's when the RunL function returns , control returns to the ActiveScheduler, which then schedules the active objects according to the following rules if there is just...
Why a Symbianspecific Resource Compiler
The Symbian OS resource compiler starts with a text source file and produces a binary data file that's delivered in parallel with the application's executable. Windows, on the other hand, uses a resource compiler that supports icons and graphics as well as text-based resources, and which builds the resources right into the application executable so that an application can be built as a single package. Furthermore, many Windows programmers never see the text resource script nowadays because...
Launching the Application
Don't launch hellogui yet. When you do launch the program, its functions will be called by the Uikon framework. For now, though, let's pretend that we don't know what will happen, and put a breakpoint on every function in hellogui.cpp, hellogui_application.cpp, hellogui_appui.cpp, hellogui_appview.cpp and hellogui_document.cpp, using the F9 key. When you've done that, launch hellogui from the application launcher. The first breakpoint to be hit is the one in E32Dll , which gets called twice...
Summary Dex
Dialogs are culturally similar to their cousins in other systems such as Windows. There are, however, many differences, designed to make life easier both for end users and for programmers. In this chapter, I'll be covering how to program dialogs in four stages Simple dialog programming getting to grips with the resource file and APIs for a simple dialog with just two text editor fields. Stock controls since dialog fields normally use stock controls, the stock controls' resource file and C APIs...
Shared Memory
If the techniques outlined above don't deliver the performance you need, you can as a last resort, use shared memory to avoid the transaction model of client-server communication altogether. You have to replace the transaction model with conventional mutex-type synchronization. The font and bitmap server FBS uses this design, in conjunction with a client program and the window server see Figure 18.7 . If Symbian OS had no FBS, then a client program that wanted to blit a bitmap to the screen...
Use the cleanup stack if you need it
What's actually happening here is that after this line has been executed The automatic x points to a cell on the heap. But after the leave, the stack frame containing x is abandoned without deleting x. That means the cx object is on the heap but no pointer can reach it and it will never get destroyed. That's why the heap check fails. The solution to this problem is to make use of the cleanup stack provided by the UIQ framework. The cleanup stack can be used to hold a pointer to an object like...
GDP State Machines
Here's CGdpstateMachine, the abstract state machine class I used class CGdpstateMachine public CActive virtual void EnterL 0 virtual TState CompleteL 0 virtual TState ErrorL TInt aCode 0 virtual void Cancel 0 CGdpStateMachine TPriority aPriority void ChangeState TState aNextState inline TState CurrentState void SetNextState TState aNextState void ReEnterCurrentState Methods to be implemented by concrete state machines Methods to be implemented by concrete state machines Overrides of CActive...
Queries
A query dialog enables a minimal form of interaction you can use one to ask a simple Yes No question. As we saw earlier in this chapter, the streams application contains an example iEikonEnv- gt LeaveWithInfoMsg 0 Let user try again You run a query by specifying a string in a resource file that will be used as a question. I happened to be able to find a resource string in the Symbian OS source, for this purpose often, you'll need to write your own. The query dialog has a Yes button and a No...
Sending a datagram
When a packet is sent, the GDP adapter is used to send the client's datagram along with the relevant game protocol and port information to the GDP destination address TInt CGsdpSession Send const TAny aData _ASSERT_ALWAYS iMyPort 0, iServer- iMyPort, The GDP adapter's SendL function is implemented as follows void CGsdpGdpAdapter SendL TUint32 aGameProtocol, TUint32 aFromPort, const TDesC amp aToAddress, TUint32 aToPort, const TDesC8 amp aData aToPort, aToAddress, If iLastError is KErrNone, then...
Installing SIS Files
Once you have a working .sis file, it's then incredibly easy to install this onto your Smartphone all you need to do is transfer it to your Smartphone and launch the .sis file There are several transfer methods available - choose what's best for you depending on what is supported on your PC or phone and what is most convenient for you at the time Serial or USB connection this means that you need to install the PC Connectivity software suite accompanying your phone and then send files across...
Direct File Stores
Let's consider the file format of the Boss Puzzle, that's delivered with the UIQ SDK. The Boss Puzzle is a single-player game in which you move the tiles around If you want to build and launch this yourself, you'll find it in the UIQ C SDK in the directory tree headed by UIQExamples papers boss. If you build the engine v1, view v3, and quartz v7 projects for the winscw udeb target, you'll then be able to run the application from the UIQ emulator's application launcher. I closed the application...
Embedded Stores
The code above was not specific to a direct file store. It would have worked equally well with any kind of persistent store. The stream store framework provides an embedded store type that is intended specifically for object embedding. Imagine you have a Symbian OS Word document like in the Nokia 9210 and Psion Series5 that embeds the Boss Puzzle. Here's what the store layout might look like, conceptually, with a Boss document inside the Word document Note Actually, the word processor's store...
Building in the CodeWarrior IDE
The main phase of real application development is writing, building, and debugging from within the Metrowerks CodeWarrior IDE - not the command line. To see how to build a GUI program from the IDE, let's start with a clean sheet. If you tried out the command-line build above, from the command line type which will get rid of all files from the build. It may also report errors and issue not-found messages as it tries to get rid of files that might have been produced, but weren't. You can then...
The Program hellotext
Here's the program we're going to build. It's your first example of Symbian OS C source code include lt e32base.h gt include lt e32cons.h gt gConsole- gt Printf _L Hello world n gConsole Console NewL _L Hello Text , TSize KConsFullScreen, KConsFullScreen CleanupStack PushL gConsole Pause before terminating User After 5000000 5 second delay CTrapCleanup cleanupStack CTrapCleanup New TRAPD error, ConsoleMainL _ASSERT_ALWAYS error, User Panic _L SCMP , error delete cleanupStack _UHEAP_MARKEND Our...
Dictionary Stores and ini Files
A persistent stream store includes a stream network in which streams may contain stream IDs that refer to other streams and which has a single root stream. In contrast, a dictionary store contains a list of streams, each of which is accessed using a UID, rather than a stream ID There is a small class hierarchy associated with dictionary stores, as seen in Figure 13.14. You write to a dictionary store using a dictionary write stream that you construct, specifying the dictionary store and a UID....
Creating the Bitmaps
The first step of the process is to create Windows bitmaps and convert them into the specific file format used by Symbian OS, called a 'multi- bitmap' file or MBM. The .mbm file, together with an associated .mbg file, is constructed from one or more Windows .bmp files using the tool bmconv Bitmap Converter , which is called during the main application build process Figure 14.2 . The .mbm format is also used when icons are required elsewhere in your application - for example, a splash screen on...
Creating the Icon
As when we added icons to the button bar of HelloGUI earlier, a UIQ application icon has to be created from up to four Windows bitmaps, made up of icon and bitmap pairs. As with the button icons, these will then be converted into a multibitmap format during the application build process. There is, however, a difference the .mbm file is only generated temporarily, and not stored - all the necessary image information is contained in the resulting .aif file. To create the icons, you can once again...
Parsing Filenames
The streams example shows how to use a TParsePtrc to crack a filename into its constituent parts. Here's some code to display all four parts of a filename in a dialog TParsePtrc parser iAppUi- gt iFileName cEikEdwin edwin static_cast lt cEikEdwin gt control EExamplecontrolIdDrive edwin- gt SetTextL Sparser.Path edwin- gt SetTextL Sparser.Name edwin- gt SetTextL Sparser.Ext The interesting thing here is that the TParsePtr constructor causes TParsePtr simply to store a reference to the filename...
Interthread Data Transfer and the Package Classes
In the Symbian OS documentation, interthread data transfer is referred to as interthread communication or ITC. I have used 'data transfer' rather than 'communication' here, because in reality communication is about much more than just data transfer. All transfer of data between threads is based on six member functions of RThread found in E32std.h Tint GetDesLength const TAny aPtr const Tint GetDesMaxLength const TAny aPtr const void ReadL const TAny aPtr, TDes8 amp aDes, Tint anOffset const...
Error Code Returns versus l Functions
RFs does not provide functions such as connectL or DeleteL that would leave with a Tint error code if an error was encountered. Instead, it provides connect and Delete ,which return a Tint error code including KErrNone if the function returned successfully . This means you have to check errors explicitly using User LeaveIfError , which does nothing if its argument is KErrNone or a positive number, but leaves with the value of its argument if the argument is negative. A few low-level Symbian OS...
Uikon Debug Keys 1
As we saw in Chapter 6, debug builds of Uikon in other words, on the emulator allow you to use various key combinations to control and test your application's use of memory. You can also use the following key combinations to control your program's drawing behavior As we saw in Chapter 6, debug builds of Uikon in other words, on the emulator allow you to use various key combinations to control and test your application's use of memory. You can also use the following key combinations to control...
C Standard Library
STDLIB is the Symbian OS implementation of the standard C library. It delivers standard C functions, which are in general thin layers over corresponding Symbian OS functions. This means, on the one hand, that you can use almost all your favorite C APIs, from strlen and malloc to fopen and quicksort , and on the other, that you can usually guess the behavior of functions such as User QuickSort because they're there to support standard library functions. The Symbian OS C standard library was...
Handling Key Events
Here's how COppFleetview handles key events generated via the keypad TKeyResponse COppFleetView OfferKeyEventL const TKeyEvent amp aKeyEvent, if aKeyEvent.iCode EQuartzKeyFourWayLeft MoveCursor -1, 0 else if aKeyEvent.iCode EQuartzKeyFourWayRight MoveCursor 1, 0 else if aKeyEvent.iCode EQuartzKeyFourWayUp MoveCursor 0, -1 else if aKeyEvent.iCode EQuartzKeyFourWayDown MoveCursor 0, 1 Redraw board DrawTilesNow else if aKeyEvent.iCode EQuartzKeyConfirm if iFleet.IsKnown iCursorX, iCursorY iCursorY...
Leave if you cant allocate memory
memorymagic has two menu items, New 2 and Delete 2, whose handlers are coded with all the lessons we learned earlier. In addition, we have an out-of-memory check. The command handlers look like this delete iObject2 iObject2 new ELeave CX iEikonEnv- gt infoMsg _L New 2 break case EMagicCmdDelete2 delete iObject2 iObject2 NULL iEikonEnv- gt infoMsg _L Delete 2 break Also, as you saw earlier, the CExampleAppUi destructor includes delete iobject2. User Leave KErrNoMemory Mem FillZ temp, sizeof CX...
Support for flickerfree drawing
As an application programmer, you should be aware of two aspects of the window server that promote flicker-free drawing. Firstly, the window server clips drawing down to the intersection of the invalid region and the begin-redraw region, so if your drawing code tends to flicker, the effect will be confined to the area being necessarily redrawn. You can exploit this in some draw-now situations. Imagine that I wanted to implement a cursor-movement function, but didn't want to alter my DrawTiles...
Setting Up MetroTRK
The MetroTRK Metrowerk's Target Resident Kernel software is the debug agent that handles the communication between the target and the Code- warrior Debugger on the host PC. First, you must install the MetroTRK software on your target device. MetroTRK is composed of 5 executables, and 1 .ini file. These are available on your SDK or from the Metrowerks web site www.metrowerks.com . The MetroTRK install package will place the following files on your device.
Blitting and Bitmaps
These days, displays are fundamentally bitmap-oriented. Graphics primitives such as DrawLine have to rasterize or render the line - that is, they must determine which pixels should be drawn in order to create a bitmap image that looks like the desired line. Rasterizing in the Symbian OS is the responsibility of the BITGDI, which implements all drawing functions specified by CGraphicsContext for drawing to onand offscreen bitmaps. Another approach to updating a bitmapped display is simply to...
String Formatting
Although Symbian OS is a GUI system, Printf -style formatting still has a useful role to play, and appears in a number of classes. We've already seen it in CConsoleBase Printf and CEikonEnv InfoMsg . There's another example of using it in buffers console- gt Printf KBufFormatString, amp temp As in C print formatting, the character is followed by a format character, which interprets the corresponding argument for formatting. Here are the main format types As in C print formatting, the character...
The Current Directory
Most RFs-related functions are stateless - that is, the results of a function don't depend on any functions previously called. That's why you can share CONE's RFs with other libraries used by your application. RFs has just one item of state its current directory. When you open an RFs, usually its current directory is set to c which as discussed, will be hidden from users in UIQ and may be just a ramdrive in some devices, or a flash-based drive in others. Indeed, c is always an internal read...
Server bootstrap
Whether on the emulator or a real Symbian OS machine, execution in the newly launched server thread now begins in earnest with CGsdp-Scheduler ThreadStart cTrapcleanup cleanup cTrapcleanup New ifdef _DEBUG TRAPD terr, for TInt i 0 i lt 20 i cleanupstack PushL TAny NULL cleanupstack Pop 20 initialize all up to and including starting scheduler Tint err KErrNoMemory First, the function constructs a cleanup stack. Next, the function pushes 20 items on to the cleanup stack and then pops them back...
Receiver
Receiving an SMS message is a bit more complex than sending an SMS message. Once the client issues a ReceiveAllL , we need to enter a wait state, and wait for SMS messages containing our GDP SMS specific pattern. In fact, this is all that we can do as all other SMS messages will be consumed by the messaging application. Once received, we can read the SMS message and then go back into the wait state and wait for the next GDP specific SMS message Figure 20.7 . Note If the SMS message is received...