Quickoffice Premier is an award-winning mobile office suite application for Symbian OS phones and the Quickoffice development team share their experiences, and solutions, of how they ported this successful UIQ 2.1 application to UIQ 3.

Jelte Liebrand, Director of Engineering at Quickoffice, Inc. passes on advice for getting the most out of UIQ 3 with two specific framework examples: the layout manager and command processing framework.

• Quickword
  Quickword is a fully functional word processor with Microsoft Word compatibility, allowing the end-user to view, edit and format documents on their P990 or M600, complete with rich formatting and complete data integrity back to laptop or desktop. Edited Word files are saved as *.doc files, ready to share via beaming, Bluetooth, or e-mail.
• Quicksheet
  Quicksheet is a fully functional spreadsheet with Microsoft Excel compatibility and allows the end-user to have multiple sheets per workbook, including linked sheets. The application supports creating desktop compatible *.xls files and has full integration with P990 and M600 e-mail applications.
• Quickpoint
  Quickpoint is a presentation viewing and editing application that includes slide views, speaking notes, and outline mode. The application provides full PowerPoint presentation and is fully integrated with the P990 and M600 e-mail applications. Files can also be shared with others using beaming or Bluetooth connectivity.   

Porting from UIQ 2.1: what to look out for

Platform security 
Quickoffice considers the security capabilities introduced with UIQ 3 to be rather straight forward: either you receive the security capabilities needed, or you don't. What developers need to be mindful of is calling methods that can now fail with KErrAccessDenied, but as most developers have proper error handling this should not cause many issues.

However, the Quickoffice team found data caging to be more problematic, since many applications access Symbian OS files directly. Developers and their applications will no longer be able to do so in the new Symbian OS v9.1 environment. Also, file handling is slightly different with UIQ 3. You now get open file handles passed as arguments, and not filenames as in the past.

UIQ 3 framework changes and challenges
When porting Quickoffice Premier to Symbian OS v9.1 and UIQ 3, the team faced big changes within the UIQ framework. Quickoffice Premier is a very UI intensive application and therefore it leverages much of the UIQ 3 framework.

The new UIQ 3 framework is designed to be a more intelligent in design than UIQ 2.1, which means that developers have to do less in the application. Unfortunately this sometimes results in the 'Microsoft paperclip syndrome'.

"That is to say that the framework tries to be smart, but sometimes comes up short," Jelte Liebrand explains, "This shows itself most when the UIQ 3 framework does something, with regard to layout, command handling or focusing of controls, that you did not expect. The tricky part is then to work out why it's doing what it's doing, rather than just to modify or hack your code to get it to do what you want."  

Developers may be tempted to do random experimentation in order to achieve desired behavior when the framework is not cooperating. The Quickoffice team recommends that you don't do this:

"Although it might work in that particular case, it probably won't work on another UIQ 3 device or even for other execution paths on the same device," Liebrand clarifies, "We recommend that instead you work out why it's doing what its doing and then change your code to work with the framework." 

Although the "don't hack it but fix it" mantra applies to any code, the team found that the consequences of this "modifying" are significantly greater in UIQ 3. Here are two examples of how the Quickoffice team worked with the framework to resolve problems:

Example 1: Layout manager problems and solutions
In UIQ 3, the applications have a layout manager which is responsible for putting the controls on the view. In other words, developers no longer construct the controls and place them in specific pixel positions, but rather tell the layout manager what type of layout is required.

The Quickoffice team had an issue where the layout manager kept 're-aligning' some of their controls in an undesirable manner. The net result was that they got blank spaces between the controls. Since the layout manager only seemed to do this if one of their controls was taller in height than 23 pixels, they could have worked around this by adjusting the minimum and maximum sizes of those controls. That's exactly what they did and it seemed to work.

But then the team started to look at landscape and fullscreen modes. The layout manager misbehaved again. Clearly the 23 pixels were not working for those particular UI configurations. The team could have tried:

height = (ui == portrait) ? 23 : 24;

But you can see how this becomes, not only ugly, but it also quickly snowballs in to a lot more problems.

After some research into the issue, the Quickoffice developers found the problem was down to the type of layout manager they were using.

"The layout manager can be 'row based' or 'non-row based'. When it is the default row based, it has some complex heuristics to work out the sizes of each row depending on the controls on it. This is where the 'Microsoft paperclip syndrome' kicked in, and it got it all wrong, resulting in blank spaces between the rows and controls. Setting the layout manager to be 'non-row based' sorted out the problem," recollects Jelte Liebrand.

Example 2: UIQ 3 command processing framework problems and solutions
Unlike UIQ 2.1 where you tell the framework what menu items you have, UIQ 3 now has a concept of 'commands'. As you get used to using this, you will see that the command processing framework is a very powerful feature, and one that the Quickoffice team recommend that you should use in the correct way by letting the framework place and sort out your commands for you.

The team found that you should not try and change the type of a command (e.g. from TypeScreen to TypeYes) just to get it to appear where you want. Rather you should just accept that the command will be where the framework wants them to be.

"If you were to run your app on a different UIQ 3 mobile device, you'd not get the same result if you have been experimenting with the commands to get them to appear where you wanted them," Jelte Liebrand advises.

In other words, a 'positive command' should be of type "yes" and not of type "no" just to get it to appear somewhere else in the dialog.

Benefits of working with command processing framework
The Quickoffice developers consider the command processing framework to be a compelling feature, because it allows developers to look at their application with a whole new and more dynamic perspective. Previously in UIQ 2.1, you would simply have a menu bar. When the menu bar was brought up, you would dim menu items as necessary and execute functions when the menus were selected. Now you have a much wider concept: commands. Arguably, all the things your application does can be seen as execution of commands. Yet, not all will be coming from the menubar or the softkeys.

Here's where the team found UIQ 3 to be very powerful. Using an example from Quicksheet, Quicksheet has a 'format toolbar' with some options for setting the cell color, the text boldness, italics, etc. In the past that would be a class on its own, which (when certain icons are tapped) would do certain things. Now in UIQ 3, developers can just code those as commands by ensuring your toolbar (a Quickoffice internal class example) is deriving from MQikCommandOperator. This means it will handle all the commands you'd like it to.

"The added bonus becomes more obvious when you want your app to look different on different devices such as touch screen versus non-touch screen," Jelte Liebrand says.

"You can have separate MQikCommandOperator's for your commands which means that you don't actually have to modify a lot of code. Your controller/engine still does the same thing for the command, for example setting the text to bold, but the command is just coming from a different place, the menubar, softkeys or custom built toolbar."

By separating the command handling from the command displaying, Quickoffice's application became a lot more dynamic and easily accommodated different behaviors.

Concluding thoughts

Although it is easy enough to port an application from UIQ 2.1 and get it to run on UIQ 3, Quickoffice would argue that in many cases even a small redesign for UIQ 3 is a very valuable exercise. The team considers that just getting things to run is one thing, but redesigning your application to take full advantage of the features available in the UIQ 3 platform is probably the best option.

About Quickoffice
Quickoffice, Inc. is a world leader in providing mobile office document software for smartphones. The company's flagship product, Quickoffice Premier, continues to receive awards and recognition from industry analysts, the media and users alike. The software allows users to open, view, edit and send their original, native Microsoft files without the need for desktop conversion or synchronization. Quickoffice has been thoroughly tested by the rigorous quality standards of leading mobile phone manufacturers and ships through major carriers such as Vodafone, Orange, China Mobile, Cingular and many more. Fully localized in 36 languages, and shipping worldwide as a built-in solution on millions of smartphones, Quickoffice has been a top-selling mobile office application since its market introduction. Privately held, Quickoffice has offices based in Dallas, Texas and London, England.

Visit Quickoffice's website>>