QLayout

Found in: Examples\UIQ\QLayout

QLayout should not be looked upon as an ordinary application; its purpose is instead to present the features for layout handling in UIQ. This application should be used as a guide when you want to have a look at how to layout controls in a view. It presents the assistance available in UIQ to layout controls: building blocks and layout managers.

The application contains four views. Each page demonstrates one topic concerning layout.

• Start view

  Start view is a dummy view whose purpose is to activate different layout views. These layout views are activated by commands in the view. Each view that can be activated reveals specific features within layout handling in UIQ 3, for example, system building blocks.

• System building block

  All of the system building blocks are presented in the view. It gives an overall view of the different system building blocks and how they can be created.

• Custom building block

  Different custom building blocks are presented in the view. It gives an overall view of custom building blocks and how they can be created.

• Phone style

  This view is similar to a view in the Contact application. It changes layout depending on which phone style is currently running. You can switch between the five different UIQ phone styles: Pen Style, Pen Style Landscape, Softkey Style, Softkey-Touch Style and Softkey-Small Style. The application changes to a layout that fits the phone style.

The UI configuration that is used by the phone determines the look and feel of the application. Layout supports the reference UI Configurations that are supported in the UIQ 3 SDK. For development purposes, UiqEnv allows to change the UI Configuration in the emulator in order to develop and test the application with varying phone styles.

For an introduction to layout handling in UIQ 3 see Managed Layout in the Programmer's Guide.

Building blocks is a new concept introduced in UIQ 3 to expedite the creation of layouts in views. When you design a view, you choose the building blocks you want to use. Each building block has a number of slots. In each slot you can place any control, one control per slot. Each building block has settings for specific attributes like margins, alignment and size. Put simply, you choose your building blocks, fill the slots with controls, place the building blocks in the view and your layout is complete.

The layout manager, like building blocks, is a new concept in UIQ 3 which assists the layout of controls in views. The difference is, roughly, that building blocks are controls themselves, whereas layout managers are only a mechanism for laying out controls. Layout managers have no visual representation. Building blocks use layout managers internally, but this is of no concern for you as a user of building blocks. For a more thorough description of building blocks and layout managers, see Managed Layout in the Programmer's Guide.

All of the system building blocks are presented in this view. It gives an overall view of the different system building blocks and how they can be created.

These should be used whenever possible. System building blocks are designed to be suitable for most circumstances. The main advantages of using system building blocks are:

• When most, if not all, applications use the same building blocks, applications acquire a consistent look. It adopts and uses the device specific appearance, which can involve any number of settings for different phones.

• It is possible to predict the string size of controls placed in the building block. This reduces effort for translation and localization considerably.

When you are about to create a custom building block, you should start by reconsidering. It should only be a last resort when there is no system building block that suits your purpose.

There are three important resource structures: QIK_GENERIC_BUILDING_BLOCK, QIK_GENERIC_BUILDING_BLOCK_COLUMN and QIK_GENERIC_BUILDING_BLOCK_ROW.

QIK_GENERIC_BUILDING_BLOCK is the starting point. It contains flags, content and a number of columns. The flags are the same as for the system building blocks. The content, which fills the slots, works exactly in the same way as the system building blocks' content.

The column defines the building block layout and a certain number of slots where controls or captions can be inserted. Each column can also contain a number of rows. The settings for a row are the same as for a column, except that a row can contain columns and you can specify whether the columns placed in the row are able to wrap if they do not fit on the row horizontally. Since you can place rows in columns, and columns in rows, you can pretty much specify any structure.

A device based on UIQ 3 can implement one or several of the UI configurations. Implementing support for several UI configurations on a single phone means that the device can, at runtime, switch between the different UI configurations. UI configurations supported by a phone are called System UI configurations.

An application written or optimized for several UI configurations runs only in a UI configuration that is allowed by the phone. If the application does not directly support the UI configuration in use, the application framework selects a similar UI configuration to configure the application. If a similar configuration is not found, the application is not displayed in the configuration it requested. It should be noted, however, that even though the application is configured with a similar UI configuration, the phone itself does not change UI configuration.

For a more thorough description of UI configurations, see UI configurations in the Programmer's Guide and Migration guide - UI Configurations.

There are five different phone styles that you can change to. Four of the phones styles can be changed to with the commands in the view, Pen Style, Pen Style Landscape, Softkey Style and Softkey Style Touch. To set the application in Softkey Style Small you need to use a key combination. To enable and disable Softkey Style Small, the following shortcut keys should then be used <Ctrl><Alt><Shift> I.

The view can be divided into two areas: name container and information container. The purpose of the name container is to show the contact's name; it is always be visible in the view. The purpose of the information container is to show more detailed information about the contact. These controls do not necessarily always fit on the screen. This is remedied by adding the detail controls in a scrollable container. The difference between the different view layouts is how these two areas are placed and presented in the view.

The information container is the same for all view layouts; it is only the positioning of the container that differs.

The name container differs both in position and content from view layouts. In Pen Style, Pen Style Landscape, Softkey Style and Softkey Style Touch it consists of the contact's image, name and company name. In Softkey Style Small it only consists of the contact name.

Pen Style, Softkey Style and Softkey Style Touch use the same layout. A row-layout manager is used to position the two areas. At the top of the view, the name container is positioned and fills the entire horizontal application space. The information container is positioned below the name container. The name container consists of the contact's image, name and company name.

The building block is divided into two columns. The first one contains the image and the second column consists of the contact's name and company name that are positioned in two rows. The first row contains the contact name and the second holds the company name.

Softkey Style Small has nearly the same layout as above. The only difference is that the name container only consists of the contact's name.

Pen Style Landscape uses a column layout manager to position the two areas in two columns. The name container is placed in the first (left) column and the information container is placed in the second (right) column. The name container consists of the contact's image, name and company name. The building block is only one column that consists of three rows, where each row contains a control. The first row contains the image, the second row the contact's name and the third row the company name.

Build the QLayout project in the normal way. To run it, choose Layout from the Launcher.

CLayoutApplication is the entry point to the application. The application class defines the properties of the application, such as its UID and caption, and creates a new document.

CLayoutDocument represents the document in the Layout application.

CLayoutAppUi represents the application UI in the Layout application. It is responsible for creating the views.

CLayoutStartView is a dummy view activates the other layout views.

CLayoutSystemBuildingBlockView presents all of the system building blocks in the view. It gives an overall view of the different system building blocks and how they can be created.

CLayoutCustomBuildingBlockView presents different custom building blocks in the view. It gives an overall view of custom building blocks and how they can be created.

CLayoutPhoneStyleView presents how you can change the layout of a view depending on the phone style that is currently running.