Tutorial: EggTimer-Application for UIQ 3

1 Tutorial: EggTimer-Application for UIQ 3 EggTimer-Application for UIQ Table of contents Overview.................................................................................................................................................. 3 Creating the project ................................ 4 Layout Modifications ............................................................................................................................... 5 Scrollable Container ............................ 5 The first building block ........................................................................................................................ 6 Create the control ............................... 7 Editor control ....................................................................................................................................... 8 Duration Editor .... 9 Accessing the controls ....................................................................................................................... 11 Unique Handler definition ............. 11 Resource file definition ................. 12 Source code access ........................................................................................................................ 12 Commands ............................................. 13 The Close Command .......................... 13 Adapting Commands to Our Needs ................................................................................................... 14 Handling the Commands ................................................................................................................... 15 Command Visibility ............................ 16 Multiple Pages ....................................................................................................................................... 17 MultiPage Base Class ......................... 17 Progress Bar Building Block ............................................................................................................... 18 Adding a new page ............................ 19 Automated Page-Switching ............... 20 Asynchronous Timer .............................................................................................................................. 21 Reading the Control Values ............................................................................................................... 21 Setting the Progress Bar .................... 24 Periodic Timer ................................................................................................................................... 24 Testing ............... 26 Alarm Dialog .......................................................................................................................................... 26 Control Collections ............................ 27 Commands ......... 29 Displaying the Dialog ......................................................................................................................... 30 Andreas Jakl – FH Hagenberg, 2008 1 Ch ap te r: Ov erv i ew 2 Tutorial: EggTimer-Application for UIQ 3 Modifying the Dialog ......................................................................................................................... 31 Your Own Dialog Class ....................... 31 Include-Files ................................................................................................................................... 32 Class Definition .............................. 32 Displaying the Dialog ..................................................................................................................... 33 Conclusions ............................................ 34 Andreas Jakl – FH Hagenberg, 2008 2 Ch ap te r: Ov erv i ew 3 Tutorial: EggTimer-Application for UIQ 3 Overview The application that you will develop is based on a “Hello World”-template. The individual tasks introduce several key concepts of development for UIQ 3 and Symbian OS. These include: UIQ 3 user interface layout Building blocks and controls o Label o Editor (Text & Duration) o Progress bar Asynchronous progress bar updating Commands and command handling Multipage views Dialogs Each step is explained in a detailed way, including both the full source code plus explanations of the concepts behind the tasks. To work through the tasks, it’s an advantage if you know something about the basics of UIQ 3 development. The tutorial is based on Carbide.c++ 1.2, but it is not difficult to work through the text using another IDE like Metrowerks Codewarrior. Carbide.c++ 1.3 (and higher) feature an UI designer for UIQ – however, it’s not used by this tutorial. In many situations, the UI designer will not offer all the features you need, or you might want to do some small corrections or fix errors. In all those cases, you need to understand how to manually design a UI for UIQ 3 – and this is exactly what is covered in this tutorial. Parts of this document are based on the highly recommended UIQ White Papers written by Matthias “Maze” Reik, available from the UIQ Developer Portal ( http://developer.uiq.com/ ). Version: v1.0a, May 22, 2008 Andreas Jakl – FH Hagenberg, 2008 3 Ch ap te r: Ov erv i ew 4 Tutorial: EggTimer-Application for UIQ 3 Creating the project Let Carbide.c++ create a new “UIQ 3.x GUI Application” project for you – do not use the UI designer wizard! Remember that the workspace / project should be on the same drive where you installed the Symbian OS SDKs. The directory names for the project and the SDK should not contain spaces. Call the project “EggTimer”. If you do not use the Carbide.c++ IDE, then you can use the “Hello World” example application, which is installed with the UIQ 3 SDK. It’s identical to the project generated by the wizard, with the only difference that you cannot change the project name that easily. To test if everything worked out, compile and launch the application. It should contain a demo label and three normal menu commands (plus a “Close” menu command, which is only displayed in debug mode. In the world of UIQ, users usually don’t quit the applications themselves). The screenshots show the UIQ emulator in Pen-mode (portrait). If you select one of the three demo menu commands, a small info popup window will appear. The demo application is fully compatible to different UI configurations, like softkey or pen interaction modes. To change the settings of the emulator, either use the SDKConfig-tool that is installed with the UIQ3 SDK or modify the “Start in configuration”-setting of the UiConfigTest-application from within the emulator’s app launcher. We will start with this basic application and adapt it to our needs. Andreas Jakl – FH Hagenberg, 2008 4 Ch ap te r: C reating t h e p r o je ct 5 Tutorial: EggTimer-Application for UIQ 3 Layout Modifications If you take a look at the source code of the view (EggTimerView.cpp), you’ll notice that it doesn’t contain any layout code. It just handles menu commands and displays the small information pop-ups. This is because the whole layout is defined in the resource files. Open EggTimer.rss and you’ll see that it uses the same command_list and view for each UI configuration (defined in r_ui_configurations) – meaning that our program has basically the same interface, no matter which UI configuration is active. However, the controls will all adapt to the configuration, e.g. the softkey labels will automatically appear when the UI is set to Softkey-mode. Let’s take a look at the structure of the resource file that was created by the wizard: All View Configurations refer to the same command list, which contains the definitions of the commands. Those are displayed according to their type and the current UI configuration (e.g. as a menu item, but they could also be mapped directly to softkeys or to hardware keys). The view contains just one page, which in turn has the content defined in the QIK_CONTAINER_SETTINGS resource structure. The container is using a layout manager (in this case a grid layout) and includes the label resource. Scrollable Container As we can see by looking at the running application, our label takes the whole screen and the text is centered. We’d like to extend this screen and add more content. To achieve this, we will modify the container type. Currently the container is a standard container. If we add more controls to it than would fit on one screen, the user would simply not see the rest and would not have an option to get there. Therefore, this type of container is only recommended if you have one control on the screen – as it was the case for the label control. This control should then take the whole screen. A better, more real-life example than the label in our program would be a list box, which is usually displayed covering the full screen. Andreas Jakl – FH Hagenberg, 2008 5 Ch ap te r: L ay o u t M o d ifi cati o n s 6 Tutorial: EggTimer-Application for UIQ 3 A scrollable container is what we need. So, we first create a new resource for the container, which can be left empty – the default values are fine enough for us. RESOURCE QIK_SCROLLABLE_CONTAINER r_EggTimer_container { } Now we have to tell the rest of the application to use our new scrollable container. Modify the definition of the view page so that it defines the type of our container to EQikCtScrollableContainer and references our new container definition. QIK_VIEW_PAGE { page_id = EEggTimerViewPage; container_type = EQikCtScrollableContainer; container = r_EggTimer_container; page_content = r_EggTimer_page_control; } The last thing which should be modified is the definition of the container settings. This has already been defined – after all, the application did already display the label control.