Introduction

From UIQ Books

UIQ 3: The Complete Guide

Forewords

Peter Molin, Chief Technology Officer, UIQ Technology

‘I learn it from a book!’ is my favorite quote by Manuel in Fawlty Towers¹. As a matter of fact, I really believe that reading books is an excellent way of learning. Today, when 'everything' is available on the Internet, it is important to appreciate the power and magic of a book; that besides providing factual information organized in a structured way, a book also gives you the possibility to browse around and pick the areas you want to learn more about. With a book you can sit in your favorite chair and let the author explain the concepts using a clear step-by-step approach. I am convinced that this book will make it easier and more enjoyable for you to learn about UIQ programming.

I am especially glad to see Mark Wright as the editor of this book. Mark and I worked together in the early days of defining the Quartz UI – a predecessor to UIQ – and making it all come together. Mark has had good help from many talented people within UIQ Technology, Sony Ericsson, Symbian and other companies to put this project together; not least John Holloway, who has written most of the content of this book, and is someone whom I hold in high esteem. John has been part of the Symbian world since its creation and I have struggled a lot with his chess game, which beats me more often than I am willing to confess to anybody!

Mobile phones are getting more advanced all the time and allow you to create amazing applications for them. Some very exciting UIQ phones have already reached the market and more are to come. A key aspect of UIQ programming is the framework to help you write flexible applications that can run on the diverse phones from both Motorola and Sony Ericsson. This book will show you how to take advantage of that feature and many others, and provide you with a set of illustrative examples. The more complex concepts are explained in a way that will help you achieve your programming goals. I am also convinced that you will use some of the chapters in this book to support you making your first steps on UIQ, and others to find out how everything works in detail when you need to optimize your application.

Finally, I wish you a happy reading, and look forward to the time when, after learning UIQ from this book, you will be one of the developers that will amaze us with great applications.

Peter Molin

Chief Technology Officer

UIQ Technology

¹ For more information on Fawlty Towers see for instance this tribute site: www.fawltysite.net. As I write this, a video of Manuel saying ‘I learn it from a book!’ is available at www.youtube.com/watch?v=xX85Y5Zb7sw.

Mats Blomberg, Manager, Software Strategy, Sony Ericsson CTO Office

It’s a great pleasure to see the first book written specifically for UIQ 3 developers. Having worked with Symbian OS since the very beginning in 1998, I’ve seen many different efforts to establish a credible platform for Open OS phones. It has been a long and winding road but we are very pleased to see the new UIQ 3 establishing its place in the mobile phone market and being adopted by top tier mobile phone manufacturers.

UIQ was defined in the past as the Quartz UI meaning a fixed screen resolution of a quarter VGA assisted by a touchscreen for advanced user navigation. The first Symbian OS phone, the Ericsson R380, was more of a PDA with GSM phone call capability. Learning from that, Sony Ericsson created the first phone-oriented device, the P800, using the second release of Quartz, now named UIQ 2.1. Now we have the third generation of UIQ defined with several phones already coming out like the P990, M600, W950, W960 and P1 from Sony Ericsson and the MOTO Z8 from Motorola. By the time you read this hopefully many more phones will be available. UIQ as a configurable UI and platform is more flexible than ever, enabling many different form factors while still maintaining a platform approach for application developers.

Developing for UIQ 3 has been somewhat challenging in the past. Learning new development tools, new C++ methods and new user interface paradigms have been tough, even for experienced application developers. The lack of a UIQ development guide has been obvious and has actually limited a wider uptake of the platform amongst developers.

Now, with this book, it is possible to get a head start to develop for UIQ, either from scratch or by porting an existing application from another platform to UIQ. There is a lot of commonality between UIQ 3 and S60 3rd Edition since they are both based upon the same Symbian OS v9. Developers targeting different phone UIs but using Symbian OS benefit a lot from that commonalty. Porting from other platforms like Palm and Microsoft to UIQ 3 may benefit from the similar pen navigation UI on those platforms.

This book attempts to fill the gap between the Symbian Press books covering generic Symbian OS topics and the UIQ SDK which contains the API reference guides. However it’s recommended that the reader be familiar with Symbian OS, for which we suggest the Symbian OS Explained book by Jo Stichbury. See developer.symbian.com for further Symbian Press titles.

Readers of UIQ 3: The Complete Guide will find a comprehensive guide to developing applications. Starting with Symbian OS essentials and UIQ 3 basics, readers will be guided through the development tools and SDK to create a first UIQ 3 application and to understand and use the many features of UIQ through detailed examples. Building an application and taking it through the Symbian Signed process is explained step by step. Advanced platform features in multimedia and telecommunications areas are covered as well.

Readers interested in porting existing applications to UIQ 3 will find expert guidance in the Porting section of the book. Porting from S60 and other platforms is covered.

Further books in the Symbian Press series provide complementary information in areas such as Platform Security and Multimedia.

I’m very pleased to see this book finally being written and would like to thank all authors, reviewers, sponsors and publishers putting their efforts together. It’s a big milestone in the evolution of UIQ.

Happy reading!

About the Authors

John Holloway, Lead Author

With over two decades experience of designing compact mobile software applications including a deep understanding of all the leading mobile operating systems, John Holloway is one of the most experienced mobile software architects in the world.

Having obtained a first class honours degree in Computer Engineering from City University, London, John commenced a ten year career with Psion Computers where he contributed significantly to the body of software code that now lies at the heart of Symbian OS.

John was a founder of Purple Software, one of the world's first mobile games companies, in 1995. Purple Software grew rapidly to become one of the industry's leading independent developer of software applications

for mobile devices. His role as Chief Technical Officer culminated in the company being awarded the first ever BAFTA for a mobile computer game in 2002.

John is currently the Chief Technical Officer at ZingMagic Limited (www.zingmagic.com), a mobile games development company, specializing in games that require substantial artificial intelligence in order to play well.

John is also the Director of Client Software Applications at Mobrio Limited (www.mobrio.com), the online social networking and UGC services company. Mobrio designs, builds, manages and moderates online communities built around user-generated content for third party brand owners.

Mark Wright

Mark joined Ericsson in 1997 and took a key role in defining the functional and user interface specifications for ‘Communicator’ class products. When Symbian was formed, Mark was seconded to the ‘Quartz’ team as Project Manager and managed the functional specification and definition of the GUI. The Ericsson Communicator Platform, shown at CeBIT 2000 was the first working UIQ device and served to build interest in UIQ products and also enabled early developers to test applications on a real machine.

Mark then worked with the R380 and P800 products with specific responsibility for improving ease of use and the out-of-the-box customer experience. He established the ‘over the air’ setup of WAP and Email for Ericsson phones.

Mark has extensive experience in communicating between different teams, notably Marketing and Development. He has provided third party support and written detailed White Papers for the Sony Ericsson P800 smartphone and Sony Ericsson’s range of PC Cards and broadband modems.

Mark is a graduate of Bath University with a BSc in Electrical and Electronic Engineering.

Matthew Hunt

Matthew joined Sony Ericsson in 2002 working on the company’s smartphone projects which include the P800, P900, P910, P990, M600 and W950. At Sony Ericsson Matthew has worked to establish and build the Enterprise and Partner Support Team which is responsible for providing Sony Ericsson, Symbian and UIQ technical and development support to software suppliers who are delivering software or services for Sony Ericsson smartphones. He is an accredited Symbian Developer.

Matthew studied Software Engineering at Manchester Metropolitan University, graduating in 1999. Following University he went straight in to a software development role for the GB Group in Chester writing C++ based data processing applications for major utilities, finance and government organizations. This involved writing software for limited resource devices which sparked an interest in the world of the mobile phone.

Outside work Matthew is a keen sailor, windsurfer, mountain biker and snowboarder. He has a small boat which is kept in the Solent and he enjoys competing in 'Cowes Week' and 'Round the Island Race'. Matthew lives in Cheshire with his partner Chloe and dog Charlie.

Simon Judge

Simon is a freelance mobile developer and has worked in mobile for over 11 years and IT for over 20 years.

Having obtained a BSc. and M Eng. at UMIST, Simon joined Logica where he worked on several space and defence projects. Simon contracted at Vodafone and Oracle working in Object Oriented Design and C++ before working full time in mobile.

Since then, Simon has been responsible for many Symbian projects for companies including Pixology, Boots, Jessops and Philips Research. More recently Sony Ericsson commissioned Simon to write UIQ tutorials for Sony Ericsson Developer World and he has worked at Symbian in the JAVA group that implements JSRs under Symbian. He is an accredited Symbian Developer.

You can find out more at www.simonjudge.com

About this Book

This book is all about UIQ! It’s aimed at C++ developers who wish to write applications for UIQ 3 or port from other environments to UIQ 3.

We start with a brief history of UIQ and an overview of the current UIQ 3 platform, the UIQ 3 application suite and the development environment. Next, we explain the how UIQ 3 supports a wide variety of different mobile phone styles in a single platform. We cover configuration and layout options for the user interface, which includes support for one-handed operation using softkeys and two-handed operation using a touchscreen. We explain how building blocks make it easy to lay out your application and introduce the UIQ Command Processing Framework (CPF). The CPF allows you to describe your commands in an abstract manner so that UIQ 3 can present them in an optimal way on different hardware configurations. For those of you who are familiar with UIQ 2, we summarize the main differences.

Now it’s time to code! We describe the UIQ 3 SDK and Carbide.c++ and walk you through the steps to build the QuickStart example application.

UIQ 3 is based on Symbian OS v9, which introduces new security architecture. We explain Platform Security and also provide an introduction to the key Symbian OS concepts that you will encounter as you work through the book. This serves as a useful refresher and reference, but is not intended to teach Symbian OS to newcomers.

Using a set of example applications, the core of the book, Chapters 6 to 11 discuss each aspect of UIQ 3 in detail. We recommend that all commercial grade applications should be Symbian Signed. Therefore, we build and Symbian Sign an application, SignedApp, in three phases. In Chapter 10 we create SignedAppPhase1 to establish a basic application outline. In SignedAppPhase2 we add simple file manager functions and assess the resulting code for defects against the Symbian Signed Test Criteria. In Chapter 11 we fix the defects in SignedAppPhase3 and add some multimedia functions.

We cover the implications of Symbian Signed at the relevant points throughout the book and provide a description of the scheme itself in Chapter 14.

Multimedia and communications programming in UIQ 3 follow standard Symbian OS practice. We provide a set of examples to demonstrate the typical functionality that you may need in your applications.

In Chapter 13 we show you how to localize your application and improve its performance and reliability. Chapter 15 guides you through testing, debugging and deploying your application.

Finally, we cover porting, with particular reference to Series 60 3rd Edition, Windows Mobile and Palm OS.

Who is this Book for?

This book is primarily for the following types of reader:

• Experienced C++ programmers who are new to UIQ. If you are new to Symbian OS, we recommend that you also read Symbian OS Explained.
• Programmers writing applications for other Symbian OS platforms such as Series 60, who wish to port them to UIQ 3 or write new applications for UIQ 3.
• UIQ 2 programmers wishing to port applications to UIQ 3, or to write new applications in UIQ 3.
• UIQ 3 programmers who wish to extend their knowledge.

For those involved in the wider process of software development, but who are not directly coding applications, Chapters 1 and 2 explain the principles behind UIQ 3 and how it supports a diverse range of mobile phone hardware.

How to use this Book

Besides reading the chapters in sequential order, the book can be used in other ways.

The example applications in the chapters in the User interface framework, Multimedia and communications, and Improving your applications sections provide example code using as much of the GUI as possible. If you want to learn more, for example, about the Command Processing Framework, you can go directly to that section, read about CPF and work with the Commands example applications.

The example applications frequently contain more than is described in the text. It would, for example, be very boring for the book to describe every building block in detail, since once the concept is understood it is easily applied to building block set provided in UIQ 3. However, the example applications cover most of the building blocks, giving you an opportunity to see them in an application play with them in code.

Readers interested in porting may start with Chapter 16 and then refer to the rest of the book to see examples of UIQ 3 code explained in detail.

Conventions

To help you get the most from the text and keep track of what’s happening, we have used a number of conventions throughout the book.

When we refer to words you use in your code such as variables, classes or functions, or refer to a filename, we use the style:

CQikAppUi::ConstructL()

ListView1.h

Blocks of code are presented like this.

void CAppSpecificUi::ConstructL()
  {
  CQikAppUi::ConstructL();
 
  // Create and set up an engine.
  iEngine=new(ELeave)CAppEngine(EQikCmdZoomLevel2);
  TBuf<KMaxListItemText>bb;
  const TInt KListView1Items=7;
  for (TInt i=0;i<KListView1Items;i++)
    {
    iEikonEnv->ReadResourceL(bb,R_STR_LIST_CONTENT_1+i);
    iEngine->SetListItem(bb);
    }
 
  // Create and set up the single view.
  CAppSpecificListView* q = new(ELeave)
                    CAppSpecificListView(*this,iEngine);
  CleanupStack::PushL(q);
  q->ConstructL();
  AddViewL(*q);
  CleanupStack::Pop(q);
  }

Commands typed at a command prompt are shown like this:

Abld build winscw udeb

From time to time our experts have added tips. These are identified in the text as:

'Pro tip:'

Example Application Code

The code for the example applications can be downloaded from each chapter at books.uiq.com and/or from the Example applications code page.

There are extra comments in the code itself. You may find it useful to read both the code sections in the book and the actual source.

The map below helps you to link the example applications to the chapters in this book.

Author Acknowledgements

This book would not exist without the determination of Mikael Nerde, Thomas Bailey, Jens Greve and Ulf Wretling at Sony Ericsson to assemble the necessary people and resources. We are also indebted to the Symbian Press team, especially Freddie Gjertsen, Jo Stichbury and Satu McNabb, for their support in the project.

We are very grateful to our reviewers for diligently reading through the manuscripts, checking code and answering questions.

John would particularly like to thank his children Alex and Jenna, his wife Alison and all her book club members for their endless support and encouragement, along with all those he has worked with, past and present, especially those that have shown him the error of his ways; please don’t stop!

Mark would like to thank his parents for suggesting a career in telecoms. Thanks also to the Communicators team in Ericsson for my first break in the mobile world, and to the many talented and fun people at Sony Ericsson and UIQ with whom it is a pleasure to work.

Symbian Press Acknowledgements

Experience has taught us that it’s hard to create a new book. Even harder when it must be created from nothing. Harder still when the topic to document is vast.

UIQ 3: The Complete Guide overcame all three difficulties, and thus its existence is a testament to the hard work, commitment and sheer determination of those who worked to make it happen. We’d like to thank them all.