Test Driver
Considering the number of unit tests that need to be run on a device to ensure the quality of any production code being released, you will need to give yourself the means to achieve this as smoothly and as swiftly as possible. Running test code on a device and getting the results of the tests fed back to the developer so that he or she can process and use them can be a mammoth task if undertaken manually. In this particular case, automation is the solution and Test Driver provides the...
Videos
icon, as well as general information about the phone, for instance the signal strength. It consists of six subpanes. These are laid out from left to right or from right to left in some cases, for instance in Arabic and Hebrew layouts, in which the ordering of many controls is reversed signal pane signal strength indicator context pane displays the application's icon title pane displays the application's title navigation pane may contain tabs, images, or text, or can be empty battery pane...
Introduction
UIQ and Series 60 are the only two user interfaces available for Symbian OS for which third-party developers can write C applications. Both provide a framework, built on top of Symbian OS, that can be reused by application writers, and a set of standard applications, for instance PIM applications, multimedia and email. The purpose of this chapter is to compare and contrast the two UIs, in particular their application framework APIs. Series 60 is one of a range of developer platforms created by...
Vertical option button listHorizontal option button list
Class name Resource Struct QIK_VERTOPBUT HOROPBUT Control type EQikCtVertOptionButtonList EEikCtHorOptionButList Option buttons are defined by OPBUT resources which have an id and a label. The option button list classes' SetButtonById function is used to change the selected button. Option buttons can be used in menus as well as dialogs. This is done using the MENU_ITEM's flags field, specifying one of the flags EEikMe-nuItemRadioStart, EEikMenuItemRadioMiddle or EEikMenu-ItemRadioEnd defined in...
Note Dialogs and Wrappers
Note dialogs display a warning, a question or a progress indicator. They do not need a menu bar and most are timed so do not even need softkeys. Because of this, the note dialog base class, CAknNoteDialog, is derived from CEikDialog rather than CAknDialog. You can define your own notes using an AVKON_NOTE resource and assigning it to the control field in the dialog's DLG_LINE, but because note dialogs are so commonly used, note wrappers, which use predefined resources, are provided. Wrappers...
Video Playback
The video player utility CVideoPlayerUtility is defined in Video-Player.h, and provides the ability to play video clips. The functionality of the video player utility is broadly similar to that of the audio player utility. For example, it allows the source data to be supplied in a file, in a TDesC8 descriptor or at a specified URL address, it includes basic playback functionality and it allows you to modify a variety of playback settings. It also supplies video-specific functionality, such as...
Stores and the Application Architecture
In UIQ, the application architecture provides support for an application to save its data in a direct file store. The majority of Series 60 applications don't need to access an application document file and such access is disabled. If necessary, you can enable it in a Series 60 application by supplying an implementation of the application document's OpenFileL function, as illustrated by the noughts and crosses application, whose document class definition, in oandxdocument.h, contains the...
Key Events 1
A key event is represented by an instance of a TKeyEvent and a key event type, which may be one of EEventKeyDown, EEventKey or EEventKeyUp. Unless your application is particularly interested in detecting when a key is pressed or released, you can safely ignore key events of types other than EEventKey. The TKeyEvent class has four data members iCode, iModifiers, iRepeats and iScanCode. Of these, iCode, containing the key's character code, is usually of most significance to an application. The...
List Boxes
List boxes display information in columns. All list boxes in UIQ and Series 60 are ultimately derived from CEikListBox. The main types of list boxes defined by Uikon are text list boxes - CEikTextListBox column list boxes- CEikColumnListBox hierarchical list boxes- CEikHierarchicalListBox. The Series 60 UI is designed with an emphasis on viewing rather than creating data and lists are the main way in which data is displayed. Series 60, unlike UIQ, defines many of its own specialized list box...
Progress Bars
In both UIs, a progress bar can be defined in a resource file using a PROGRESSINFO resource struct. This has a control type of EEikCt-ProgInfo, which corresponds to CEikProgressInfo in C . The progress bar can contain text showing the progress as a fraction or a percentage Figure 2.12 , or it can be divided up by vertical lines. To update and redraw the progress bar, call CEikProgressInfo IncrementAndDraw orCEikProgressInfo SetAndDraw . In Series 60, progress bars are usually displayed using...
Elisabeth Mwe
Elisabeth joined the system documentation team in 2000 and has since been designing and writing the Symbian Developer Library, specializing in operating system customization, kits, emulators, test, build and release tools. She has also been involved in training and usability management. Elisabeth has a BA in Technical Communication Information Design from Malardalens Hogskola and Coventry University, as well as an MA in Contemporary English Language and Linguistics from Reading University....
Global Notes and Queries
Global note and query dialogs are similar to standard note and query dialogs except that they are displayed even ifthe application that launched them is switched away from or closed down. They can be used by UI or engine components, and are not defined by resources. They are used only in unusual circumstances, for example to display the error that caused an application to shut down. A global note is a CAknGlobalNote. After initialization, call Show-NoteL , specifying the type of note enumerated...
The Image Conversion Library ICL
In previous versions of Symbian OS all image conversion and manipulation had been performed via client APIs interacting with the Media Server. This was no longer possible since the Media Server had been removed, so a new library had to be created to handle this functionality. At around the same time that work was progressing on the MMF, another team was set up to provide a new framework that would provide similar image conversion functionality to that of the Media Server, but in a more...
Using ini Files
In addition to an application's document file, the application architecture provides support for an application to open, read and modify a second file. By convention, the file has the same name as the application, but has a .ini extension hence such files are known as .ini files. The intention is that a .ini file should be used to store global settings and preferences that are independent of the document data that the application is processing. An application can then, in principle, open a...
Drawing and the Window Server
Before continuing with the practical issues of drawing a control, it will be useful to explain a bit more about how Symbian OS supports drawing. If you wish, you can skip to Section 4.7.7 and read this and the following sections at a later time. It is virtually axiomatic that all window-owning controls must create the window they own, and this is normally done from the control's ConstructL function. Most controls will use a standard window, of type RWindow, created with the CreateWindowL...
Messages and Notifications
Every control in a GUI application has a member called iEikonEnv, which is a pointer to the GUI environment, CEikonEnv. CEikonEnv is common to both UIs and provides many useful functions, including access to information and busy messages. CAknEnv is a Series 60 extension to CEikonEnv. A CAknEnv instance is created at the same time as CEikonEnv and is owned by CEikonEnv. All applications have access to it through a global pointer called iAvkonEnv, although iEikonEnv is much more useful to...
Views on the Series Platform
When implementing the view architecture on the Series 60 platform, the main deviation from the generic Symbian OS implementation is the use of the additional UI layer called Avkon. The process of creating views using Avkon is as follows Create the application views and app UI classes by deriving them from CAknView and CAknViewAppUi. Register the views with the app UI. Enable view-switching behavior by packaging data and sending it. Handle activation and deactivation of the views. The major...
The Noughts and Crosses Application
Before looking at the behavior of controls in more detail, we'll introduce the Noughts and Crosses example application, OandX. Figure 4.2 illustrates the appearance of the application, running on a phone using the Series 60 user interface. This application runs a game of noughts and crosses between two players, who take turns to make their moves. We've kept the logic Figure 4.2 The Noughts and Crosses application Figure 4.2 The Noughts and Crosses application relating to the game itself very...
Greg Zaoui
Gregory Zaoui first joined Symbian in 1998, as a graduate software engineer with a 'Licence de Math matiques' from the University of Strasbourg. He has been working on various projects for System Integration on build tools and release management. He then joined the newly created Test Solutions group in 2002, as a technical architect for TechView and other test tools. His interests range from skiing and windsurfing to talmudic studies. Gregory would like to thank Richard Harrison and Paul Treacy...
Grids
Grids are a type of two-dimensional list box with columns and rows. They are more commonly used in Series 60 than in UIQ, so Series 60 provides special support for them. CAknGrid is the base class for Series 60 grids. Because it is derived from CEikListBox and its model CAknGridM is derived from CText-ListBoxModel, grids are used in a similar way to lists. A grid is defined by a GRID resource and constructed using CAkn-Grid ConstructFromResourceL ,or in C using CAknGrid ConstructL . You can...
Bluetooth
Bluetooth is a short-range radio communications technology, standardized by the Bluetooth SIG. Symbian OS has a Bluetooth stack that is fully compliant with the Bluetooth v1.1 specifications. The services that a Bluetooth implementation can offer are characterized by the Bluetooth standards as a number of profiles. The Symbian OS Bluetooth stack fully implements the Generic Access Profile, the Serial Port Profile and the General Object Exchange Protocol. All other Bluetooth profiles are...
Onboard Camera API ECam
The ECam API constitutes the final piece of the multimedia architecture. This is a header file with appropriate library definition files shipped by Symbian to define a standard API for the usage of camera hardware. The ECam API allows an application to access and control any camera hardware that is attached to a device. It provides functions to query the status of the camera, adjust camera settings and capture images and video. The actual implementation of the underlying camera software is...
Application Startup
Being an executable, Apprun.exe has a single main entry point, E32Main . When Apprun.exe is launched, the system creates a new process and within it a new thread, initially called 'Main'. We now discuss each system call shown in the code example. E32Main is defined in app-framework uikon apprun apprun.cpp and takes no arguments. The entry point for processes. Called by the operating system to start the program. Gets the command line arguments of Apprun.exe, such as the name of the application....
Multipage Dialogs
If you need to use a dialog that has more lines than can comfortably fit the screen of a Symbian OS phone, you can split the dialog into a number of pages and display it as a multi-page dialog. It obviously makes sense to ensure, if at all possible, that the items on each page are more closely related to each other than they are to the items on other pages. Each page of a multi-page dialog has a labeled tab, used to navigate from page tp page. The appearance and positioning of the tabs is...
Skins
Skins also called themes are used to customize a phone UI's appearance at runtime. Both UIs support them, but they are implemented differently. Support for skins was introduced in Series 60 v2.0 and in UIQ 2.1. In both UIs, skins specify a color scheme and optionally a bitmap to display in the background. In UIQ the background bitmap, if specified, is displayed only in the application launcher while in Series 60 it is displayed in all applications. UIQ skins can customize the system sounds, for...
ICL framework
The ICL framework provides a communication layer between the client APIs and the actual ICL plugins, and all plugin control is performed via this layer. The underlying architecture is subdivided into two further layers. The relay layer provides a connection between the underlying client API classes and the core framework. The relay is mainly used to provide thread encapsulation for the ICL when threaded decoding or encoding is employed. All inter-thread communication is performed by this layer,...
Creating a Camera Device
The first step is to create an instance of the CCamera class to represent the camera that you want to use. You do this by calling the NewL function, which is prototyped as static CCamera NewL MCameraObserver amp aObserver,TInt aCameraIndex Note that the NewL will instantiate a derived class, but this normally should be accessed through the CCamera API. The aObserver parameter is a reference to the camera observer class, derived from MCameraObserver. You must ensure that the value of...
Check Boxes
If multiple list options can be selected, then check boxes should be used instead of option buttons. Figure 2.18 shows a dialog from UIQ's Agenda application that uses seven dialog lines, each of which has a prompt that is the day of the week and a control of type EikCtCheckBox, which in C corresponds to a CEikCheckBox. Series 60 supports multiple selection in markable list dialogs and list boxes.
Observing a Control
It is frequently useful for a control to be able to notify some other class of significant events, and the standard mechanism for doing this is to use an observer interface. The control framework defines the MCoeControlObserver interface class with a single member function, HandleControlEventL , to provide the mechanism for receiving and processing notification of a range of common control events. Any class that derives from this interface is known as a control observer. A control's observer is...
Encoding Images
The image encoder class CImageEncoder is defined in imageconver-sion.h, and provides the ability to encode CFbsBitmap encapsulated bitmaps into images stored in a variety of formats. The destination can be a file or a descriptor. The functionality of CImageEncoder basically mirrors the decoder class but is much more limited in its use. It is designed to perform only two tasks the saving of a bitmap from screen and the saving of a photo. Unlike the image decoder, CImageEncoder does not support...
Obex
We've seen that APIs exist for OBEX over infrared and Bluetooth. An OBEX MTM also exists to integrate OBEX functionality into the messaging framework, so that, for example, an object sent to a phone shows up as an attachment to a message in the user's inbox. The classes CIrClientMtm and CBtClientMtm provide client-side functionality for OBEX messaging over infrared and Bluetooth respectively. Headers for such messages can be accessed through CIrHeader infrared and CBtHeader Bluetooth . This...
Video Recording
The video recorder utility CVideoRecorderUtility is defined in VideoRecorder.h and provides the ability to record video clips. The functionality of the video recorder utility is broadly similar to that of the audio recorder utility. For example, it allows the data to be recorded to a file, a TDesC8 descriptor or a specified URL address, it includes basic recording functionality and it allows you to modify a variety of audio and video recorder settings. As with the video player utility, the...
The Observer Pattern
Before proceeding, it is worth mentioning a design pattern common across the entire MMF. This is known as the 'observer pattern' and uses observer classes to provide feedback to the API user. These classes are implemented as 'mixin' classes and define a set of pure virtual observer functions. This pattern is not restricted to the MMF, but is widely used in Symbian OS. In Chapter 4, for example, we saw the use of observer classes to report significant events to a control. In order to use an MMF...
Choice Lists and Combo Boxes
Choice lists are a type of single selection text list box that display a single list item only, but can use a popout box to display the whole list. In UIQ they are often used where space is limited, for instance in dialogs. Choice lists are not supported in Series 60 the custom list dialogs provide similar behavior. A choice list is defined using a CHOICELIST resource. This has a control type of EEikCtChoiceList and corresponds to a CEik-ChoiceList in C . You can specify its width using the...
Forms
A form is a type of dialog specific to Series 60 that looks like a list box, but which allows list items to be edited. Forms support two modes of operation - view mode and edit mode - which users can switch between. Forms can alternatively support edit mode only. Forms are defined in resource files using a FORM resource which can be assigned to the form field in a DIALOG or to the form field in a PAGE. In either case, the softkeys are defined in the dialog. FORM flags are defined in uikon.hrh...
IMAP Client MTM
The IMAP4 Client MTM, CImap4ClientMtm, provides IMAP-specific operations, the most important of which are synchronizing with a remote server, or a folder on a remote server. Some generic messaging operations, such as sending messages for which you should use SMTP , are not supported by the MTM. Extra functions are provided for obtaining and setting IMAP4 service settings. As for POP3, a helper class is available that wraps up many individual IMAP operations into a single call. A large number of...
Pointer Events
As with key events, the UI framework ensures that pointer events are sent to the right control for handling. CCoeControl HandlePointer-EventL takes a TPointerEvent parameter that packages information about the event. This includes the event's type, for instance pen down and pen up, any keyboard modifiers, and the event's position on the screen. In UIQ, items are selected and activated by a single pen tap, so pen down events of type TPointerEvent EButton1Down and drag events TPointerEvent EDrag...
Preliminary Information
The Test Driver tool is provided on the CD and can be found in a zip format in the bin epoc32 tools TestDriver directory. Your PC will need to have the following minimum specifications You will also need the following to run your tests on a device not necessary if running your tests on emulator Assabet Lubbock development board provided by Intel 1 x Compact Flash CF card, 32 MB. If running the tool on a Symbian OS emulator, you will need to launch
Edit View
The point to make about the Edit view see Figure 5.4 is to show how you can further specialize the behavior of an existing view, in this case the List view. The Edit view makes it possible for the user to edit data within a list and then switch back to the Custom view. Within our example we have used all the standard behavior in the List view, to avoid writing the same code all over again. The view switching behavior is inherited from the List view, enabling the user to go back to the Custom...
SMS and EMS
The Short Messaging System SMS is used to send and receive short text messages between mobile phones. It is defined as part of the ETSI's GSM telephony standards 03.40 . Symbian OS implements an SMS stack that offers functionality to send and receive SMS messages, including concatenated messages enumerate, read, write and delete access to the SMS storage areas of the phone and SIM receive messages that match a specified text. Seven-bit SMS alphabet, 8-bit SMS alphabet and the UCS2 data coding...
Resource Files
The resource compiler generates a Symbian OS resource file from a plain text source file, or resource script, which - by convention - has a .rss extension. The first stage of processing uses a standard C preprocessor, so a resource script has the same lexical conventions as a C program, including source file comments and C preprocessor directives. The output of the compilation process is a binary resource file with the same name as the source file, but a .rsc extension, and a generated header...
Navigation Tabs
In Series 60, tabs in the navigation pane can be used to switch between application views. Figure 2.13 shows an example. UIQ also supports navigation tabs which are located at the bottom of the screen, in the area occupied by the toolbar see Figure 2.14 . They are not used to switch view in UIQ, but to switch between pages in the same view. A page may be a scrollable container, for instance. Series 60 navigation pane tabs can be confused with multi-page dialog tabs, which are also displayed in...
Decoding Images
The image decoder class, CImageDecoder, is defined in imagecon-version.h and provides the ability to decode images. The source image data may be in a variety of formats, and can be stored in either a file or a descriptor. Unlike with the MMF utility classes, a new instance of the image decoder class must be created for each image that is to be decoded. There are four suitable XxxNewL functions, two of which are shown below The only parameter that differs between the two is the one that...
Application Closedown
When the active scheduler's wait loop terminates, the following functions are called. is a public EXPORTed function declared in called by CCoeEnv ExecuteD in coemain.cpp when the active scheduler's wait loop terminates. Deletes resources owned by the CEikonEnv object. Calls the following major functions is a public EXPORTed function declared in app-framework cone inc coemain.h. called by CEikonEnv DestroyEnvironment in eikenv. cpp. Deletes the specified resource file from the list maintained by...
Input Streaming
The audio input stream utility CMdaAudioInputStream is defined in mdaaudioinputstream.h and provides the ability to stream audio from a sound input device. As with output streaming, the audio data must be in the PCM16 format, and you can specify the sample rate and number of channels, and adjust the volume and balance of the audio stream. In fact, the input streaming utility works in exactly the same way as the output streaming utility but in reverse . In consequence, there is no need to...
Output Streaming
The audio output stream CMdaAudioOutputStream class is defined in mdaaudiooutputstream.h and provides the ability to stream audio to an output device. The audio data must be in the PCM16 format, although the sample rate and number of channels can be specified. As with the clip-based utilities, you can adjust the volume and balance of the audio output. The observer class for the audio output stream utility is MMdaAudio-OutputStreamCallback, whose definition is class MMdaAudioOutputStreamCallback...
DoubleBuffering
One final point to discuss before examining the streaming APIs themselves is the concept of 'double-buffering'. This is a methodology that is very useful when dealing with the real-time processing of data, and is widely used across the audio processing code in Symbian OS as well as in other areas, such as graphics . The basic strategy with regard to audio is as follows. 1. Prepare a buffer of audio data for an audio stream. 2. Pass this buffer to the audio stream and immediately start preparing...
Command Buttons
Command buttons are often used in UIQ's toolbar and in dialogs. Different types are available Standard command buttons class CEikCommandButton resource struct CMBUT contain text, or an icon, or both. Their control type is Two picture command buttons CEikTwoPictureCommandBut-ton PICMBUT contain text, or an icon that changes when the button is pressed, or both. Their type is EEikCtTwoPictureCommand-Button. Bitmap buttons CEikBitmapButton BMPBUT contain no text, just one or two bitmaps. Their type...
The Start Flashing Example
The Start flashing menu item starts the Hello world text in the center of the display flashing, and Stop flashing stops it. The flashing is implemented by an active object that creates regular timer events and then handles them. Its event handling changes the visibility of the Hello world text, and redraws the view. The behavior that we see when the Start flashing menu item is selected is handled by the CFlashingHello class. This is slightly more complex than CDelayedHello because the RunL...
Compound Controls
To illustrate some of the differences between simple and compound controls, I'll use the Console Application Launcher ConsLauncher example. The purpose of this application is to provide a simple means of running text-based, or console, applications on target phones. By convention, console application files have a .exe filename extension and reside in a system programs directory. Most current Symbian OS phones do not expose the filing system to the user, so once you have downloaded a console...