Tutorial: EggTimer-Application for UIQ 3

Tutorial: EggTimer-Application for UIQ 3

-

English
34 Pages
Read
Download
Downloading requires you to have access to the YouScribe library
Learn all about the services we offer

Description

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

Subjects

Informations

Published by
Reads 89
Language English
Document size 1 MB
Report a problem
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. However, the scrollable container resource type is different. Therefore, change it from: RESOURCE QIK_CONTAINER_SETTINGS r_EggTimer_page_control to: RESOURCE QIK_SCROLLABLE_CONTAINER_SETTINGS r_EggTimer_page_control If you compile the application now, it should still work fine. You won’t notice any changes, as the label control still takes the whole screen and no scrolling is required. The first building block We will add our first building block to the UI layout. It should allow the user to enter a reminder text that is to be displayed after the egg timer has finished. An example could be “Eat the cake!”. For the reminder, we will choose one of the UIQ standard building blocks: The first line will contain the caption, the second one an editor control to enter the text. For an overview of available building block types, see the SDK help: » UIQ 3 SDK » UIQ Developer Library » UIQ How-To Guides » Controls » System Building Blocks For our application, we do not need the grid layout manager that was defined by the sample application. A row layout manager is the default; it’s better suited to have a number of controls below each other. Therefore, delete the settings for the layout manager in the QIK_SCROLLABLE_CONTAINER_SETTINGS structure. If you want, you can remove the label control as well, as it is no longer needed. Find the new code after the next paragraph. Andreas Jakl – FH Hagenberg, 2008 6 Ch ap te r: L ay o u t M o d ifi cati o n s 7 Tutorial: EggTimer-Application for UIQ 3 In any case, the QIK_SCROLLABLE_CONTAINER_SETTINGS resource definition has to be extended to contain the new item, our building block. It’s as simple as adding the definition, with the type EQikCtCaptionedOnelineBuildingBlock. The name of the type is rather self-explanatory; in the SDK help you can find the complete list. RESOURCE QIK_SCROLLABLE_CONTAINER_SETTINGS r_EggTimer_page_control { controls = { QIK_CONTAINER_ITEM_CD_LI { type = EQikCtCaptionedOnelineBuildingBlock; control = { QIK_SYSTEM_BUILDING_BLOCK { content = { }; } }; } }; } Make sure that you get the brackets right. Take special care to add the semicolons (;) at the places where they are required. The container does now contain one item of the type QIK_CONTAINER_ITEM_CD_LI. This name is slightly different to the label definition (…_CI_LI). The new definition means that the control is defined directly and the layout is defined indirectly. The sample label was defined in an extra resource (indirectly). However, the definition of the item we’re about to add will happen right at the same place (directly). In both cases, the layout is not directly specified by us ( indirectly). The content of the QIK_SYSTEM_BUILDING_BLOCK is intentionally left empty. Start the application now and you won’t see anything. This is because building blocks are just placeholders for controls; they are invisible and used for layouting. Create the control The building block we just added can contain two controls (a textual caption and any content-control, according to its type). We will first create the caption for the first slot. Extend the code from above so that the according part now looks like this: QIK_SYSTEM_BUILDING_BLOCK { content = { QIK_SLOT_CONTENT { slot_id = EQikItemSlot1; caption = "Reminder Text:"; } }; } Andreas Jakl – FH Hagenberg, 2008 7 Ch ap te r: L ay o u t M o d ifi cati o n s 8 Tutorial: EggTimer-Application for UIQ 3 A screenshot of the new application (if you removed the label control): Up to now, you might have gotten the feeling that it was a lot of work for a rather unspectacular result. It’ll get a lot more interesting as soon as we add the editor control in the next step. Editor control The building block we have added has two slots, up to now we have just used the first one. Let’s stick the editor into the second slot, so that the first one is the caption (as hinted by the name of the building block we have used). This works similar to the first slot, except that we use a QIK_SLOT_CONTENT_DIRECT this time. This type is to be used if the control we add to the slot is defined directly (inline). This might seem strange as the caption looks like it’s defined inline as well, but it does not have the _DIRECT type. The reason is that the caption isn’t really defined inline; the building block expected a caption in the first slot, so the type and the other formatting options are already predefined for your convenience, making the slot an indirect one. QIK_SYSTEM_BUILDING_BLOCK { content = { QIK_SLOT_CONTENT { slot_id = EQikItemSlot1; caption = "Reminder Text:"; }, QIK_SLOT_CONTENT_DIRECT { slot_id = EQikItemSlot2; type = EEikCtEdwin; control = EDWIN { }; } }; } We’re satisfied with the standard settings, therefore no further definition is needed – except that we have to set the type of control. After this tiny change, you can start the application again and you’ll notice a huge difference. Andreas Jakl – FH Hagenberg, 2008 8 Ch ap te r: L ay o u t M o d ifi cati o n s 9 Tutorial: EggTimer-Application for UIQ 3 With just a few lines of resource definitions, your application now features a fully functional text editor that supports: - Pen and softkey interaction (Note: if you draw letters with the mouse, the handwriting recognition just returns random characters. The emulator does not come with a recognition engine). - A menu / softkey menu for copying and pasting text - An overview state and an edit state - Automatic text-truncation (We chose the OnelineBuildingBlock. A TwolineBuildingBlock would wrap once and then truncate, for example). Duration Editor Now that we know how simple it is to add complex controls, we’ll try it once again and add another building block, which will allow the user to set the time for the egg timer. This time, we don’t define the building block directly (inline), but instead create an extra resource for it. For longer definitions, this makes the code easier to read and it has the additional advantage that the indirectly defined controls can be used at multiple places. The definition for the new building block resource is strikingly similar to the first one. The only difference is that we now use the EQikCtDurationEditor instead of an EEikCtEdwin. Andreas Jakl – FH Hagenberg, 2008 9 Ch ap te r: L ay o u t M o d ifi cati o n s 10 Tutorial: EggTimer-Application for UIQ 3 RESOURCE QIK_SYSTEM_BUILDING_BLOCK r_EggTimer_building_block { content = { QIK_SLOT_CONTENT { slot_id = EQikItemSlot1; caption = STRING_r_EggTimer_text; }, QIK_SLOT_CONTENT_DIRECT { slot_id = EQikItemSlot2; type = EQikCtDurationEditor; control = QIK_DURATION_EDITOR { minDuration = { DURATION { seconds = 0; } }; maxDuration = { DURATION { seconds = 36000; } }; flags = 0; }; } }; } Note that the text of the caption isn’t defined directly in the resource file this time. Text that is displayed to the user should normally not be defined in source code or directly in the resource files, as it will make maintenance a lot more difficult and doesn’t allow localization. To define the caption string, add the following definition to the EggTimer.rls-file: // Text showed in the view rls_string STRING_r_EggTimer_text "EggTimer" To display the new building block in our scrollable container, just add it to its control list: RESOURCE QIK_SCROLLABLE_CONTAINER_SETTINGS r_EggTimer_page_control { controls = { QIK_CONTAINER_ITEM_CD_LI { // [...] }, QIK_CONTAINER_ITEM_CI_LI { type = EQikCtCaptionedOnelineBuildingBlock; control = r_EggTimer_building_block; } }; } Andreas Jakl – FH Hagenberg, 2008 10 Ch ap te r: L ay o u t M o d ifi cati o n s