Symbian OS

Quickstart and Carbide.c++ UI-Design

v2.0a 22 May 2008

Disclaimer

These slides are provided free of charge at http://www.symbianresources.com and are used during Symbian OS courses at the University of Applied Sciences in Hagenberg, Austria ( http://www.fh-hagenberg.at/ )
Respecting the copyright laws, you are allowed to use them:
for your own, personal, non-commercial use in the academic environment

In all other cases (e.g. for commercial training), please contact [email protected] The correctness of the contents of these materials cannot be guaranteed. Andreas Jakl is not liable for incorrect information or damage that may arise from using the materials.

Parts of these materials are based on information from Symbian Press-books published by John Wiley & Sons, Ltd. This document contains copyright materials which are proprietary to Symbian, UIQ, Nokia and SonyEricsson. S60 is a trademark of Nokia. UIQ is a trademark of UIQ Technology. Pictures of mobile phones or applications are copyright their respective manufacturers / developers. Symbian , Symbian OS and all other Symbian-based marks and logos are trademarks of Symbian Software Limited and are used under license. Symbian Software Limited 2006.

Andreas Jakl, 2007

Contents

Short overview of basic concepts

Installing the required tools

HelloWorld, Workflow

Andreas Jakl, 2007

Symbian OS and the world of C++

Conventions

Andreas Jakl, 2007

Why is Symbian OS different?

Standard C++ is different to Symbian OS C++

C++ is too manifold for a mobile phone (e.g. complete multiple inheritance) C++ isn't enough for a mobile phone (no exactly defined data types, no DLLs)

Symbian OS was created before exceptions and smart pointers were introduced to C++
Different requirements concerning applications, error handling, clean-up and efficiency
5 Andreas Jakl, 2007

Data Types

Own data types to be 100% independent from the compiler (like in OpenGL, ...)
Standard ANSI Symbian OS

int
unsigend int float double boolean void* void

TInt
TUint TReal32 TReal64 TBool (ETrue, False) TAny* void

Andreas Jakl, 2007

Naming Conventions

Why?
Make code more self-explaining (... and where's this variable coming from?) Get rid of references using this-> for instance variables

Important for clean-up (Instance variables stored on the heap have to be deleted in the destructor of your class) Common syntax no matter who developed the code
7 Andreas Jakl, 2007

Conventions: Variables

Enumeration constants
Enumeration itself: TDayOfWeek

e.g.: EMonday, ESolidBrush

Constants
Create with #define or const TInt ... e.g.: KMaxFileName, KRgbWhite

Instance variables (not static!)

e.g.: iPosition, iLabel
8 Andreas Jakl, 2007

Conventions: Variables

Parameters (Arguments)
a is for Argument. Therefore no an!

e.g.: aPosition, aText

Automatic variables
Without special prefix e.g.: position, text

Andreas Jakl, 2007

Conventions: Classes

Classification of categories
Indirectly describe properties and behavior

Important when creating an instance of the class and for clean-up!

No rule without exception (HBufC)

10

Andreas Jakl, 2007

Conventions: Classes

T-Classes
Must not own data on the heap: no destructor allowed

e.g.: Simple data types of Symbian OS (TBuf, TPoint, (TInt))

C-Classes
Always create them on the heap (using new()) Derived from CBase (compare to Java's Object)

e.g.: CEikLabel, CActive

11 Andreas Jakl, 2007

Conventions: Classes

R-Classes
R = Handle to an external Resource Typical functions: Open(), Create(), Initialize() Don't forget: Close with Close() or Release()! e.g.: RFile, RTimer, RWindow

M-Classes
For abstract interfaces (see Java)

Static Classes
Without prefix. E.g.: User::After(1000)
12 Andreas Jakl, 2007

Symbian OS

Jump-Start

13

Andreas Jakl, 2007

IDEs Carbide.c++

Carbide.c++ (based on Eclipse)

New main development platform Integrates Eclipse with required tools

Editions:
Express: free

Developer: 299, UI-designer, on-device debugging

Professional: 1.299, Performance tools OEM: 3999, ROM and JTAG support
Andreas Jakl, 2007

Carbide.c++

15

Andreas Jakl, 2007

S60 SDKs
SDK 1st Ed.

OS version v6.0 v6.1

Devices 7650 N-Gage, SX1, 3650, SendoX, 6600, 7610, 6670, 6260, 6630, 6680, 6681, N70, N90, E61, N73, N75, N95, E90, N96, N78, ? ?

Choose SDK depending on required compatibility and features Binary compatibility break with Symbian OS 9 www.forum.nokia.com
Commonly used for maximum compatibility

1st Ed, FP 1

2nd Ed

v7.0s

2nd Ed, FP 1 v7.0s 2nd Ed, FP 2 v8.0 2nd Ed, FP 3 v8.1 3rd Ed 3rd Ed, FP 1 3rd Ed, FP 2 5th Ed 5th Ed, FP1 v9.1 v9.2 v9.3 v9.4 v9.5?

Andreas Jakl, 2007

Installation
1.

Carbide.c++ 1.3 Developer Edition (or later / better)

http://www.forum.nokia.com/main/resources/tools_and_sdks/carb ide/index.html

2.

Perl 5.6.x (Set the path variable!) not 5.8!

http://downloads.activestate.com/ActivePerl/Windows/5.6/ActiveP erl-5.6.1.638-MSWin32-x86.msi

3.

SDK(s) (S60 3rd Ed. MR)

http://forum.nokia.com/info/sw.nokia.com/id/4a7149a5-95a54726-913a-3c6f21eb65a5/S60-SDK-0616-3.0-mr.html

17

Andreas Jakl, 2007

Updating Carbide.c++

Go to: Help Software Updates Find and Install... Choose: Search for new features to install Only use the Carbide.c++ Update Site do updating from other sites might overwrite Carbide.c++ settings!

18

Andreas Jakl, 2007

Workspace

Workspace location:
Has to be on the same drive as the SDK ( C:\)

Must not contain space characters

Example: C:\Symbian\MCxxxxx

19

Andreas Jakl, 2007

The Challenge

Features:
Displaying an image Text entry dialog Display text

possible (nearly) without coding with the new UI designer!

20

Andreas Jakl, 2007

Create new project

File New C++ Application for S60 Project

21

Andreas Jakl, 2007

Create new project

Call it: HelloWorld

Check again if the path is really on the SDK drive (C:\) and does not contain space characters!

22

Andreas Jakl, 2007

Phone Build

Build configurations:
WINSCW: Build for the windows-based emulator ARMV5: Optimized builds for the device using the ARM RealView-compiler (commercial) GCCE: Standard builds for the device using the free GCC(E) compiler. Comes with the SDK

23

Andreas Jakl, 2007

Choose UI-Design

Select the empty design

The predefined ones dont fit our requirements!

24

Andreas Jakl, 2007

Application UID (UID3)

Development for v9: 0xE0000000 - 0xEFFFFFFF

Development UID automatically assigned by Carbide

Get UIDs for public applications:

Different range for signed / unsigned
Get one for free at: http://www.symbiansigned.com/

Range 0x00000000 0x0FFFFFFF 0x10000000 0x1FFFFFFF 0x20000000 0x2FFFFFFF

Purpose Development use (< v9) Legacy UID (pre-v9) v9 protected UIDs

0xA0000000 0xAFFFFFFF v9 unprotected UIDs 0xE0000000 0xEFFFFFFF 0xF0000000 0xFFFFFFFF Development use (v9) Legacy UID (pre-v9)

25

Andreas Jakl, 2007

Our Project

26

Andreas Jakl, 2007

First tests

Compile

27

Andreas Jakl, 2007

Choose Build Target

HelloWorld Active Build Configuration Emulator

28

Andreas Jakl, 2007

Compile Project

You can only use the mouse to navigate on the screen on touch-enabled emulators! Otherwise, use the buttons below.

(optional) Project Build Project

Run Run HelloWorld Emulator Debug *+

Or:

29

Andreas Jakl, 2007

Possible Problems

Compilation error:

***Generating makefiles. bldmake.bat bldfiles WINSCW UDEB WARNING: EPOCROOT does not specify an existing directory BLDMAKE ERROR: Directory "\Symbian\9.1\S60_3rd_MR\EPOC32\" does not exist Total Time: 0 sec ===Build Command = build WINSCW UDEB -v=== Exec error:Launching failed***build returned with exit value = -1 ***Stopping. Check the Problems view or Console output for errors. -1

your workspace / project is not on the same drive as the Symbian OS SDK (usually C:\) (told you to put it there several times )
30 Andreas Jakl, 2007

Possible Problems II

Emulator starts in text shell mode

e.g. if configured like this by previous courses

Open [SDKdirectory]\Data\epoc.ini Comment the entry textshell by putting a # in front of it #textshell

31 Andreas Jakl, 2007

Emulator

Application added to the end of the list in the Installat. folder

Can be moved with Options Move *to folder+ Useful when working on the same project for more than 10 minutes

32

Andreas Jakl, 2007

Building for the Device

Change build configuration to Phone Release (GCCE)

.sisx-file created in /sis/-folder of your project

Send to device using PC Suite or Bluetooth

33

Andreas Jakl, 2007

Automatic Building

You might be used to Eclipse displaying errors as you type... ... but this is for Java, not for C++! You can still enable automatic compilation on resource change might be useful for smaller projects
Window Preferences... General Workspace Build automatically or: Project Build automatically
34 Andreas Jakl, 2007

Application structure
Application class

Entry point for OS

Defines application UID

Creates Document class Normally no changes required in here.

35

Andreas Jakl, 2007

Application structure (2)

Document class

Takes care of data model

Creates Application UI (AppUI-class)

Usually no changes required in this class either.

36

Andreas Jakl, 2007

Application structure (3)

AppUI class

Controller of the app.

Not visible itself

Manages views (container) General, application-wide event handling (exit, pause, ...)

37

Andreas Jakl, 2007

Application structure (4)

View class

Handling of title- and status pane Command handling (for this view)

38

Andreas Jakl, 2007

Application structure (5)

Container class

Handling of UI components

39

Andreas Jakl, 2007

App Startup (S60 Views)

RunApplication CreateDocumentL() CreateAppUiL() ConstructL() DoActivateL()

Avkon View Switching Application

CMyApplication CMyDocument CMyAppUi CMyView1 CMyContainer1

Avkon
CAknViewAppUi CAknApplication CAknDocument CAknAppUi CAknAppUiBase CAknView

Uikon
CEikApplication CEikDocument CEikAppUi

AppArc
CApaApplication
40

Cone
CApaDocument CCoeAppUi
Andreas Jakl, 2007

CCoeControl

UI-Design

Displaying an Image

41

Andreas Jakl, 2007

Create an Image

Use your favourite tool to create an image

e.g. 64x64 px (not 640x480 etc.!)

Save as .bmp (Windows Bitmap) to the \gfx\-folder of your project

42

Andreas Jakl, 2007

Refresh the Project

Within Carbide.c++, go to the gfxfolder and press F5 to refresh the directory contents

43

Andreas Jakl, 2007

Image

HelloWorldContainer.uidesign:
1.+2. add new image control

3. Right-click: Edit Image Property

44

Andreas Jakl, 2007

Assign the Picture

4. Switch to the .mbm-file (multi-bitmap, .mif is for vector graphics) 5. Edit MBM/MIF File...
6. Add From Project

7. Choose your picture

45

Andreas Jakl, 2007

Assign the Picture II

8. Select the picture

9. Update the size of the control to match your bitmap size ... thats it!*

* if the colours are not displayed correctly in the emulator, set the colour depth of the image to 12 bit instead of 8 bit.
46 Andreas Jakl, 2007

Interaction

Define the menu

47

Andreas Jakl, 2007

Menu Our Goal

Dialog for entering your name

Display dialog after selecting a menu item

48

Andreas Jakl, 2007

Add a dialog

Category: Notes and Dialogs

Add: Single-line Data Query

Edit properties:
Name: queryName Prompt: Enter name:

49

Andreas Jakl, 2007

Edit Entry Field

Select entry field in the UI designer

Adapt properties:
Name: editName Text:

Maximum Length: 20

50

Andreas Jakl, 2007

Create Menu Item

1.

Click on optionsMenu
Create item Enter name by clicking into the menu Let Carbide write the code by selecting Handle selected Event

2.

3.

51

Andreas Jakl, 2007

Display the Dialog

Dialog display function created by Carbide:

RunQueryNameL()

Call from menu handler function (HandleEnter_name_MenuItemSelectedL()) through:

TBuf<20> userName; TInt returnCode = RunQueryNameL(userName, ETrue);

52

Andreas Jakl, 2007

Strings in Symbian OS

Descriptors

53

Andreas Jakl, 2007

Descriptors

Why no standard strings?

Use minimal memory

Efficiency:

ROM (Literals: _LIT!) Stack Heap? Constant modifiable?

Unicode (TBuf16 TBuf8)

Takes several months to get used to descriptors :-)

54

Andreas Jakl, 2007

Strings in C

char* hello = "hello";

Memory view:
char* 0x64243184 h e l l o \0

Function strlen()
Reads from the beginning to '\0' and counts number of chars
55 Andreas Jakl, 2007

Pointer Descriptors

Comparable to (const) char* of C

Can point to text on the heap, stack or ROM Do NOT own the data they point to!
H e l l o 0x64243184
iPtr (TPtrC) ROM, heap or stack

Constant: TPtrC 5
iLength (TDesC)

Modifiable: TPtr 5 9 0x64243184

iPtr (TPtrC)

H e l l o
ROM, heap or stack

iLength iMaxLength (TDesC) (TDes) 56

Andreas Jakl, 2007

Buffer Descriptors

Comparable to (const) char[] of C

Directly contain the string

Use C++ templates to specify length (parameter)

5
iLength (TDesC)

Constant: TBufC<5> H e l l o

Modifiable: TBuf<9> 5
iLength (TDesC)

9
iMaxLength (TDes)

H e l l o

57

Andreas Jakl, 2007

Constant Heap Descriptor

Comparable to (char*) malloc(length+1) of C

Data is stored on the heap

New and easier to use: RBuf (see Descriptors section of this course)
Heap

HBufC* 0x64243184

H e l l o

Same layout as TBufC

58

Andreas Jakl, 2007

Inheritance Hierarchy

Abstract base class because of:

Generalisation (use base type for parameters!)

Provide basic functions shared by all types (e.g. Compare(), Find(), Mid(), ...)
59

constant

modifiable

Andreas Jakl, 2007

Literals

In reality _LIT is a macro, expands to create a:

Constant descriptor, compiled to program binary
Not localisable only use for testing, very simple applications or fixed strings (e.g. for protocols)!

_LIT(KHello, Hello);
Builds a named object called KHello of type TLitC16 Stores the string Hello into the object

The string is written to the program binary

60 Andreas Jakl, 2007

Label control for

Displaying Text

61

Andreas Jakl, 2007

Adding a Label

Category: Controls
Add: Label

Adapt properties:
Name: labelName Text:

Assign changes by saving the UI design

62

Andreas Jakl, 2007

Change Label Text

Text should be changed from within the source code

Define new public function in HelloWorldContainer.h:
void SetLabelTextL(const TDesC& aText);

In this function, set the text and adapt size:

iLabelName->SetTextL(aText);

63

Andreas Jakl, 2007

Change Label Text

Call our new function in Carbides menu item handlerfunction (in

CHelloWorldContainerView):
if (returnCode == EAknSoftkeyOk) { iHelloWorldContainer-> SetLabelTextL(userName); }

64

Andreas Jakl, 2007

Very short overview of

Leaves & Panics

65

Andreas Jakl, 2007

Exceptions Java

Try & Catch for handling exceptions

Functions can throw Exceptions
Calling function Try { int x = Integer.parseInt(1234); } catch (NumberFormatException e) { static int parseInt throws NumberFormatException { } Integer Class

System.out.println(Unable to convert this String to a number.);

}

66

Andreas Jakl, 2007

Leave Symbian

The TRAP(D) macros are defined in e32cmn.h

TRAP(D) catches exceptions (Leave)

Functions send out leave

Function name marked by an L-suffix

Main-Function TRAPD(err, DoExampleL()); if (err) { console->Printf(KTxtFailed, err); } TRAPD-Makro declares err as TInt and = KErrNone
67

DoExampleL()-Function void DoExampleL() { RFs fsSession; // Connect to the file server User::LeaveIfError(fsSession.Connect()); // fsSession.Close(); } Leaves if the Connect() function does not return KErrNone

Andreas Jakl, 2007

Central Exception Handling

New (ELeave) NewL() User::Leave() ConstructL()
F5L() F6L() . F8L() . F3L() F4L() TRAPD(err, F2L()); if (err)
68 Andreas Jakl, 2007

Handling Leaves

Try to implement central leave-handling

If leave not handled by your code error-message shown by the UI-framework! Therefore: Only handle leaves yourself if they influence your application

69

Andreas Jakl, 2007

When can a function leave?

1.

Caused by your own code:

User::Leave(), User::LeaveIfError(), User::LeaveNoMemory() or User::LeaveIfNull()

2.

Failed object-construction
when using the new (ELeave)-operator

3.

Calling a function that potentially causes a leave

e.g. x->DoSomethingL()
70 Andreas Jakl, 2007

Details: Causing a Leave

User::Leave(TInt aReason)
Error code (aReason) = value that will be received by TRAP Causes leave in any case

User::LeaveIfError(TInt aReason)
Causes leave if parameter is negative, e.g.:
TInt foundAt = iElementArray.Find(example, aRelation); User::LeaveIfError(foundAt); // Leaves if foundAt == KErrNotFound (-1)

User::LeaveNoMemory()
Is the same as: User:Leave(KErrNoMem);

User::LeaveIfNull(TAny* aPtr)
71 Andreas Jakl, 2007

TRAP / TRAPD

Two trap harness macros:

TRAPD: declares the variable in which the leave code is returned TRAP: declare a TInt variable yourself

TRAPD(result, MayLeaveL()); if (KErrNone!=result) ... is equivalent to: TInt result; TRAP(result, MayLeaveL()); if (KErrNone!=result) ...

If a leave occurs inside MayLeaveL(), which is executed inside the harness, the program code will return immediately to the TRAP harness macro

The variable result will contain the error code associated with the leave or will be KErrNone if no leave occured
72 Andreas Jakl, 2007

Panics

... cannot be caught and handled!

Terminates thread (= usually the whole application)

Use them for checking code logic only

Can also be sent out by the system for critical errors

If a panic happens:
Make sure you fix it, as you cant handle it!
// Stray signal detected! _LIT(KMsgStraySignal, "Stray signal\n"); User::Panic(KMsgStraySignal, 1); // Panic with code 1
73 Andreas Jakl, 2007

What does a leave look like?

Adapt the code:

void CHelloWorldContainer::SetLabelTextL(const TDesC& aText) { iLabelName->SetTextL (aText); User::Leave(KErrAccessDenied); }

Trap the leave:

TBool CHelloWorldContainerView::HandleEnter_name_MenuItemSelectedL( TInt aCommand ) { // *+ TRAPD(err, iHelloWorldContainer->SetLabelTextL(userName)); // [...] }

74 Andreas Jakl, 2007

What does a panic look like?

Adapt the code:

TBool CHelloWorldContainerView::HandleEnter_name_MenuItemSelectedL( TInt aCommand ) { TBuf<20> userName; _LIT(KLongText, "This text is too long for a maximum length of 20, so a panic will occur."); userName.Copy(KLongText); // [...] }

Will crash the emulator in release mode

75

Andreas Jakl, 2007

What does a panic look like?

In debug mode , your app. will be halted and you get more useful information:

76

USER 11 Panic: See SDK-Help Symbian OS v9.x Symbian OS reference System panic reference USER This panic is raised when any operation that moves or copies data to a 16-bit variant descriptor, causes the length of that descriptor to exceed its maximum length. It may be caused by any of the copying, appending or formatting member functions and, specifically, by the Insert(), Replace(), Fill(), Fillz() and ZeroTerminate() descriptor member functions. It can also be caused by the Andreas Jakl, 2007 SetLength() function. See TDes16.

Thats it!

Thanks for your attention

77

Andreas Jakl, 2007