Symbian OS - Quick Start

  • 2,796 views
Uploaded on

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 …

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

More in: Technology
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
No Downloads

Views

Total Views
2,796
On Slideshare
0
From Embeds
0
Number of Embeds
1

Actions

Shares
Downloads
0
Comments
0
Likes
2

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 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:SymbianMCxxxxx
    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 "Symbian9.1S60_3rd_MREPOC32" 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]Dataepoc.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 gfx-folder 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