The quickstart slides contain a quick walkthrough for creating your first project using Carbide.c++ Edition and its new UI-designer (available as a free trial version). The final project will display an image, offer the possibility to enter text and display this text on the screen. A very short overview of relevant Symbian OS topics is given at the appropriate locations. To train your Symbian OS skills, you have to option to complete the challenge, which is a "Guess-a-number"-game. Basic knowledge about Symbian OS is recommended to complete this challenge. Contents * Symbian OS naming conventions * Working with Carbide.c++ Developer Edition * Creating an S60 project * Application structure * Topics: Image control, menu definition, text query dialog, label control * Short overview about descriptors and leaves

1. Symbian OS Quickstart andCarbide.c++ UI-Design v2.0a – 21 March 2008

2. 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 andreas.jakl@fh-hagenberg.at 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 2

3. Contents Short overviewofbasicconcepts Installingtherequiredtools HelloWorld, Workflow Andreas Jakl, 2007 3

4. Conventions Symbian OS andtheworldof C++ Andreas Jakl, 2007 4

5. Whyis 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 Andreas Jakl, 2007 5

6. Data Types Own data types to be 100% independent from the compiler (like in OpenGL, ...) Andreas Jakl, 2007 6

7. NamingConventions 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 Andreas Jakl, 2007 7

8. 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 Andreas Jakl, 2007 8

9. 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 9

10. 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) Andreas Jakl, 2007 10

11. 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 Andreas Jakl, 2007 11

12. 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) Andreas Jakl, 2007 12

13. Jump-Start Symbian OS Andreas Jakl, 2007 13

14. 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

15. Carbide.c++ Andreas Jakl, 2007 15

16. S60 SDKs Choose SDK depending on required compatibility and features Binary compatibility break with Symbian OS 9 www.forum.nokia.com Andreas Jakl, 2007 Commonly used for maximum compatibility

17. Installation Carbide.c++ 1.3 Developer Edition (orlater / better)http://www.forum.nokia.com/main/resources/tools_and_sdks/carbide/index.html Perl 5.6.x (Set thepath variable!) – not 5.8!http://downloads.activestate.com/ActivePerl/Windows/5.6/ActivePerl-5.6.1.638-MSWin32-x86.msi SDK(s) (S60 3rd Ed. MR)http://forum.nokia.com/info/sw.nokia.com/id/4a7149a5-95a5-4726-913a-3c6f21eb65a5/S60-SDK-0616-3.0-mr.html Andreas Jakl, 2007 17

18. 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! Andreas Jakl, 2007 18 ! !

19. Workspace Workspace location: Has to be on the same drive as the SDK ( C: Must not contain space characters Example: C:ymbianCxxxxx Andreas Jakl, 2007 19 !!!

20. The Challenge Features: Displaying an image Text entry dialog Display text … possible (nearly) without coding with the new UI designer! Andreas Jakl, 2007 20

21. Create newproject File  New  C++ Applicationfor S60 Project Andreas Jakl, 2007 21 1 2

22. Create newproject Call it: HelloWorld Check againifthepathisreally on the SDK drive (C: anddoes not containspacecharacters! Andreas Jakl, 2007 22 !

23. 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 Andreas Jakl, 2007 23

24. Choose UI-Design Select the empty design The predefined ones don’t fit our requirements! Andreas Jakl, 2007 24

25. 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/ Andreas Jakl, 2007 25

26. Our Project Andreas Jakl, 2007 26

27. Compile First tests Andreas Jakl, 2007 27

28. ChooseBuild Target HelloWorld ActiveBuildConfiguration  Emulator Andreas Jakl, 2007 28

29. Compile Project (optional) Project  Build Project Run  Run HelloWorld Emulator Debug […] Or: Andreas Jakl, 2007 29 You can only use the mouse to navigate on the screen on touch-enabled emulators! Otherwise, use the buttons below.

30. Possible Problems Compilation error:  your workspace / project is not on the same drive as the Symbian OS SDK (usually C:(told you to put it there several times ) Andreas Jakl, 2007 30 ***Generating makefiles. bldmake.bat bldfiles WINSCW UDEB WARNING: EPOCROOT does not specify an existing directory BLDMAKE ERROR: Directory "ymbian.160_3rd_MRPOC32amp;quot; 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

31. Possible Problems II Emulator starts in text shell mode e.g. if configured like this by previous courses Open [SDK-directory]atapoc.ini Comment the entry textshell by putting a # in front of it  #textshell Andreas Jakl, 2007 31

32. 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 Andreas Jakl, 2007 32

33. 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 Andreas Jakl, 2007 33

34. 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 Andreas Jakl, 2007 34 Window  Preferences...  General  Workspace  Build automatically or: Project  Build automatically

35. Applicationstructure Applicationclass Entry pointfor OS Definesapplication UID CreatesDocumentclass Normallynochangesrequired in here. Andreas Jakl, 2007 35

36. Applicationstructure (2) Documentclass Takes careofdata model CreatesApplication UI (AppUI-class) Usuallynochangesrequired in thisclasseither. Andreas Jakl, 2007 36

37. Application structure (3) AppUI class “Controller” of the app. Not visible itself Manages views (container) General, application-wide event handling (exit, pause, ...) Andreas Jakl, 2007 37

38. Applicationstructure (4) Viewclass Handling of title- andstatuspane Command handling(forthisview) Andreas Jakl, 2007 38

39. Applicationstructure (5) Containerclass Handling of UI components Andreas Jakl, 2007 39

40. App Startup (S60 Views) Andreas Jakl, 2007 40 CreateDocumentL() CreateAppUiL() ConstructL() DoActivateL() RunApplication Avkon View SwitchingApplication CMyApplication CMyDocument CMyAppUi CMyView1 CMyContainer1 Avkon CAknViewAppUi CAknApplication CAknDocument CAknView CAknAppUi CAknAppUiBase Uikon CEikAppUi CEikDocument CEikApplication Cone AppArc CCoeAppUi CApaDocument CApaApplication CCoeControl

41. Displaying an Image UI-Design Andreas Jakl, 2007 41

42. 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 fxfolder of your project Andreas Jakl, 2007 42 1 2

43. Refresh the Project Within Carbide.c++, go to the gfx-folder and press F5 to refresh the directory contents Andreas Jakl, 2007 43

44. Image HelloWorldContainer.uidesign: 1.+2. addnewimagecontrol 3. Right-click: „Edit Image Property“ Andreas Jakl, 2007 44 1 2 3

45. 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 Andreas Jakl, 2007 45 4 5 7 6

46. Assign the Picture II 8. Select the picture 9. Update the size of the control to match your bitmap size ... that’s it!* Andreas Jakl, 2007 46 8 * if the colours are not displayed correctly in the emulator, set the colour depth of the image to 12 bit instead of 8 bit. 9

47. Definethemenu Interaction Andreas Jakl, 2007 47

48. Menu – Our Goal Dialog forenteringyourname Display dialog after selecting a menu item Andreas Jakl, 2007 48

49. Add a dialog Category: Notes and Dialogs Add: Single-line Data Query Edit properties: Name:queryName Prompt: Entername: Andreas Jakl, 2007 49

50. Edit Entry Field Select entryfield in the UI designer Adaptproperties: Name: editName Text: Maximum Length: 20 Andreas Jakl, 2007 50

51. Create Menu Item Click on optionsMenu Create item “Enter name …”by clicking into the menu Let Carbide write the code by selecting “Handle ‚selected‘ Event” Andreas Jakl, 2007 51 1 2 3

52. Display the Dialog Dialog display function created by Carbide: RunQueryNameL() Call from menu handler function (HandleEnter_name_MenuItemSelectedL()) through: TBuf<20> userName;TIntreturnCode = RunQueryNameL(userName, ETrue); Andreas Jakl, 2007 52

53. Descriptors Strings in Symbian OS Andreas Jakl, 2007 53

54. 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 :-) Andreas Jakl, 2007 54

55. Andreas Jakl, 2007 55 h e l l o Strings in C char* hello = "hello"; Memory view: Function strlen() Reads from the beginning to '' and counts number of chars char* 0x64243184

56. 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! Andreas Jakl, 2007 56 ‘H’ ‘e’ ‘l’ ‘l’ ‘o’ Constant: TPtrC 0x64243184 5 ROM, heaporstack iLength(TDesC) iPtr(TPtrC) ‘H’ ‘e’ ‘l’ ‘l’ ‘o’ TPtr Modifiable: 0x64243184 5 9 ROM, heaporstack iLength(TDesC) iPtr(TPtrC) iMaxLength(TDes)

57. Buffer Descriptors Comparable to (const) char[]of C Directly contain the string Use C++ templates to specify length (parameter) Andreas Jakl, 2007 57 TBufC<5> Constant: ‘H’ 5 ‘e’ ‘l’ ‘l’ ‘o’ iLength(TDesC) Modifiable: TBuf<9> 9 ‘H’ 5 ‘e’ ‘l’ ‘l’ ‘o’ iLength(TDesC) iMaxLength(TDes)

58. 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) Andreas Jakl, 2007 58 Heap ‘H’ 5 ‘e’ ‘l’ ‘l’ ‘o’ HBufC* 0x64243184 Same layout as TBufC

59. 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(), ...) Andreas Jakl, 2007 59 constant modifiable

60. 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 Andreas Jakl, 2007 60

61. Displaying Text Label controlfor Andreas Jakl, 2007 61

62. Adding a Label Category: Controls Add: Label Adaptproperties: Name:labelName Text: AssignchangesbysavingtheUI design Andreas Jakl, 2007 62

63. 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); Andreas Jakl, 2007 63 !

64. Change Label Text Call our new function in Carbide’s menu item handler-function (in CHelloWorldContainerView): Andreas Jakl, 2007 64 if (returnCode == EAknSoftkeyOk) {iHelloWorldContainer-> SetLabelTextL(userName); }

65. Leaves & Panics Veryshortoverviewof… Andreas Jakl, 2007 65

66. Exceptions – Java Try & Catch for handling exceptions Functions can throw “Exceptions” Andreas Jakl, 2007 66 Calling function Try { int x = Integer.parseInt(“1234”); } catch (NumberFormatException e) { System.out.println(“Unable to convert this String to a number.”); } Integer Class … static intparseIntthrowsNumberFormatException { … } …

67. Leave – Symbian TRAP(D) catches exceptions (“Leave”) Functions send out leave Function name marked by an L-suffix Andreas Jakl, 2007 67 The TRAP(D) macros are defined in e32cmn.h Main-Function TRAPD(err, DoExampleL());if (err) { console->Printf(KTxtFailed, err); } DoExampleL()-Function voidDoExampleL() {RFsfsSession; // Connect to the file serverUser::LeaveIfError(fsSession.Connect()); // …fsSession.Close(); } TRAPD-Makro declares err as TInt and = KErrNone Leaves if the Connect() function does not return KErrNone

68. Central ExceptionHandling Andreas Jakl, 2007 68 New (ELeave) … … NewL() … … User::Leave() … … ConstructL() … F6L() F7L() F8L() F9L() F5L() F5L() … … F6L() …. … F8L() …. F3L() F4L() F0L() F2L() … F3L() … F4L() … F1L() TRAPD(err, F2L()); if(err) …

69. 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 Andreas Jakl, 2007 69

70. When can a function leave? Caused by your own code: User::Leave(), User::LeaveIfError(), User::LeaveNoMemory() or User::LeaveIfNull() Failed object-construction when using the “new (ELeave)”-operator Calling a function that potentially causes a leave e.g. x->DoSomethingL() Andreas Jakl, 2007 70

71. Details: Causing a Leave User::Leave(TIntaReason) Error code (aReason) = value that will be received by TRAP Causes leave in any case User::LeaveIfError(TIntaReason) Causes leave if parameter is negative, e.g.:TIntfoundAt = 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) Andreas Jakl, 2007 71

72. TRAP / TRAPD Two trap harness macros: TRAPD: declares the variable in which the leave code is returned TRAP: declare a TIntvariable yourself 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 KErrNoneif no leave occured Andreas Jakl, 2007 72 TRAPD(result, MayLeaveL()); if (KErrNone!=result) ... is equivalent to: TIntresult; TRAP(result, MayLeaveL()); if (KErrNone!=result) ...

73. 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 can’t handle it! Andreas Jakl, 2007 73 // Stray signal detected! _LIT(KMsgStraySignal, "Stray signal"); User::Panic(KMsgStraySignal, 1); // Panic with code 1

74. What does a leave look like? Adapt the code: Trap the leave: Andreas Jakl, 2007 74 void CHelloWorldContainer::SetLabelTextL(const TDesC& aText) { iLabelName->SetTextL (aText); User::Leave(KErrAccessDenied); } TBoolCHelloWorldContainerView::HandleEnter_name_MenuItemSelectedL( TIntaCommand ) { // […] TRAPD(err, iHelloWorldContainer->SetLabelTextL(userName)); // [...] }

75. What does a panic look like? Adapt the code:  Will crash the emulator in release mode Andreas Jakl, 2007 75 TBoolCHelloWorldContainerView::HandleEnter_name_MenuItemSelectedL( TIntaCommand ) { TBuf<20> userName; _LIT(KLongText, "This text is too long for a maximum length of 20, so a panic will occur."); userName.Copy(KLongText); // [...] }

76. What does a panic look like? In debug mode , your app. will be halted and you get more useful information: Andreas Jakl, 2007 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 SetLength() function. See TDes16.

77. Thanks for your attention That’s it! Andreas Jakl, 2007 77