Naming Conventions
Like any system, Symbian OS uses naming conventions to indicate what is important. The Software Development Kit SDK and Symbian OS source code adhere to these conventions. Naming conventions are funny people tend either to love or hate them. Either way, I hope you'll find that the established naming conventions make understanding Symbian OS code much easier, and that, as these things go, they're not too burdensome. The fundamental rule is, use names to convey meaning. Don't abbreviate too much...
Modifying Symbian OS Strings
The strings example shows how to modify strings using descriptors. You can get a buffer suitable for appending one string to another by placing a TBuf on the stack _LIT KWorldRom, world TBuf lt 12 gt helloWorldStack KHelloRom TBuf lt l2 gt is a modifiable buffer with a maximum length of 12 characters. After the constructor has completed, the data is initialized to 'hello' and the current length is set to 5. The code is somewhat unsatisfactory in that I have used a magic number, 12, for the size...
Thread local storage
Thread Local Storage is the closest thing there is to global variables in Symbian OS. For each DLL, it is possible to register a pointer to a dynamically created struct or class object, and then to look it up whenever it is required. The basis of the technique is that having done this, all global variables are remapped to data fields within the structure. In fact, this is on a per thread, per DLL basis, with each thread potentially having its own globals. Indeed, this is how the STDLIB...
Where Threads Matter
Most tasks are event handlers. The design of Symbian OS is optimized for event handling, with good results for ease of programming, system efficiency, and robustness. But some tasks really are long-running threads. Game engine calculations, spreadsheet recalculation, background printing, and the like can be particularly long running. Status display updates, animations, and the like are only slightly less demanding. Symbian OS has broadly two approaches to handling tasks that really are...
RDebug Class
The RDebug class, defined in e32svr.h, includes a host of functions, of which the most interesting is Print . If you're debugging under the emulator, RDebug Print prints to the debug output window. If you're debugging on target hardware, RDebug Print uses a serial port, which you can connect to a PC, using a terminal emulator to view the debug output. The port can be set using HAL Set , specifying EDebugPort and the port number, or if you are using the eshell text shell, using the debugport...
Sound Effects
A view is primarily about displaying things, but it can be about interacting with the user through sounds too. Symbian OS can play audio files of various formats gsm 6.10,. au,. wav,. wve and raw audio data , as well as tones and streaming PCM audio. For tp-ships, I wanted to play three .wav files for hitting a ship, missing a ship, and sinking a ship, respectively. I encapsulated all the sound playing functionality in a class CSoundEffects. Its second- phase constructor sets up a...
How Does Leave Work
The User Leave function causes execution of the active function to terminate, and on through all calling functions, until the first function is found that contains a trap or trapdo macro. User Leave is defined in e32std.h you pass a single 32-bit integer error code. IMPORT C static Leave TInt aErrorCode The trap and trapdo macros are also defined in e32std.h edited slightly, they look like this
APIs Covered in the Book
Now we've reviewed the type of hardware on which Symbian OS operates, the base facilities for constructing programs, and the event- handling system including the client-server framework. Symbian OS APIs divide into categories corresponding to those we use for different types of program the kernel exposes an API through the user library system servers expose APIs through their client interfaces application engines expose APIs to the applications that use them middleware components are APIs in...
No Writable Static Data in DLLs
DLLs only support read-only data, and program code. Writable static data is supported only by .exe is. This imposes some design disciplines on native Symbian OS code. It also makes life more difficult when porting code, which often assumes the availability of writable static. A feasible workaround is to use a .exe to contain the ported code. The .exe is packaged as a Symbian OS server, which allows it to be shared between multiple programs. By using a separate process, we also gain the benefit...
Hh I Ihi
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 button iEikonEnv- gt QueryWinL returns ETrue if Yes is pressed, or EFalse otherwise. As I pointed out at the beginning of this chapter, the art is to ask truly Yes No questions - not to use the puzzling Windows-style Yes No Cancel....
APIs for reading resources
BAFL provides the basic APIs for reading resources The oddly named RResourceFile class, in barsc.h, is used for opening resource files, finding a numbered resource, and reading its data. RResourceFile behaves more like a c class than an r class. TResourceReader in barsread.h is a kind of stream-oriented reader for data in an individual resource. TResourceReader functions are provided that correspond to each of the resource compiler's built-in data types. As an example of the use of...
A Multipage Dialog
A sample multipage dialog taken from the UIQ Agenda application can be seen in Figure 10.4. I got this dialog by selecting the Preferences menu item on the Edit menu pane in Agenda. This allowed me to customize my Agenda view, such as the number of viewed hours in a day. However, there are more details that do not fit. This is a multipage dialog. I can tap with the pointer on either of the page tabs. Tapping with the pointer on the tab marked Alarm gives me a page on which I can change...
Id 1
IMPORT_C CBufBase inline Tint Size const IMPORT C void Reset IMPORT_C void Read TInt aPos, TDes8 amp aDes const IMPORT_C void Read TInt aPos, TDes8 amp aDes, Tint aLength const IMPORT_C void Read TInt aPos, TAny aPtr, Tint aLength const IMPORT C void Write TInt aPos, const TDesC8 amp aDes IMPORT_C void Write TInt aPos, const TDesC8 amp aDes, Tint aLength IMPORT_C void Write TInt aPos, const TAny aPtr, Tint aLength IMPORT C void InsertL TInt aPos, const TDesC8 amp aDes IMPORT_C void InsertL TInt...
User Class
User is a static class with more than 70 functions in various categories. We've already seen User Leave , User LeaveIfError ,and User Panic . To support memory handling, use User Alloc , which behaves like malloc in C. User Free behaves like free , while User Realloc behaves like realloc . Leaving variants User AllocL , User AllocLC etc. are also provided. Two major functions suspend a thread until a timer expires User After suspends until after a given number of microseconds has elapsed. User...
Sourcefile Syntax
Because processing starts with the C preprocessor, a resource file has the same lexical conventions as a C program, including source-file comments and C preprocessor directives. The built-in data types are as follows The built-in data types are as follows A single byte that may be interpreted as a signed or unsigned integer value. Two bytes that may be interpreted as a signed or unsigned integer value. Four bytes that may be interpreted as a signed or unsigned integer value. Eight byte real,...
Hh Wot
An older technique is to override PrepareForFocusTransitionL , which is virtual, more or less by accident. It has a nontrivial default implementation, but note that it does not include a parameter specifying the line that is currently focused. Start your overridden function with Call the base class implementation first this leaves if the control with the current focus isn't valid, and is unable to lose focus. Then call idofFocusControl to get the control ID that's currently focused. Then decide...
Stack size
One limitation you might come across is if the original program places large variables on the run-time stack - if it uses large arrays as local variables, for example. The standard Symbian OS C programming style is to use pointers to heap-based objects rather than having those objects as local variables, and to reflect this the default stack is comparatively small at 8k. On target hardware, this size is fixed for applications, although for executables, you can increase the stack size this is an...
Fleet Views
The main task was to modify Solo Ship's fleet view class. It ended up looking like this class CFleetView public CCoeControl, public MCoeView void GetCursor TInt amp aX, Tints aY const Incremental drawing void DrawTilesNow const void ExplSound void MissSound void SunkSound CFleetView CFleetViewData amp aFleetViewData, TFleet amp aFleet From CCoeControl void Draw const TRect amp const From MCoeView TVwsViewId Viewld const void ViewActivatedL const TVwsViewId amp aPrevViewId, TUid...
Localizable Strings
If you intend to translate your application into other languages, then you should put all text strings that need to be localized into one or more separate files, with a .rls resource localizable string extension. A .rls file defines symbolic identifiers for strings, to which the resource file refers when it needs the associated string. As an example, consider the following two resources taken from HelloGui.rss RESOURCE MENU_PANE r_hellogui_edit_menu command EHelloGuiCmdl txt Item 1 , RESOURCE...