QCommands

Found in: Examples\UIQ\QCommands

QCommands should not be looked upon as an ordinary application; its purpose is instead to present the features of commands in UIQ. This application should be used as a guide when you want to have a look at how commands can be used in different ways and how the commands are presented in the UI for the user. All of the commands that are used in this example are created by data from resource files.

The application contains four pages. Each page demonstrates one topic concerning commands.

• Page 1

  This page does not have any page specific commands; it contains only view specific commands. This means that all of these commands are also available on the other pages. The view specific commands are used to show how commands can be added and removed from a command list. The commands that are added or removed are defined in the resource file. The purpose of these added commands is to show how a command text can be changed and how to use a command state monitor.

• Page 2

  The commands on this page demonstrate the use of the option-button list and the cascading menu.

• Page 3

  The commands on this page show how different command types interact with each other and how it is possible to add or remove command icons.

• Page 4

  The commands on this page show how commands can be sorted alphabetically or by priority.

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

For an introduction to commands in UIQ 3 see Abstract commands in the Programmers Guide.

Close (debug) is only available in debug mode; it closes the application. This command is only visible in debug mode because it is only used to find memory leaks during development of the application.

Expand commands show how you can add and remove commands that are defined in the resource file during runtime. It adds two cascading menus, Current state and Set current state.

In Set current state, two check boxes change application states (ECommandsApplicationState1 and ECommandsApplicationState2) in the command state monitor. The command state monitor then changes the availability of the commands in Current state cascade. If ECommandsApplicationState1 is true, the command State 1 will be available. If ECommandsApplicationState2 is true, the command State 2 will be available. If both ECommandsApplicationState1 and ECommandsApplicationState2 are true the command State 1 & 2 will also be available.

Commands that are not available will be shown in different ways depending on the phone style that is used. In pen style, the commands will be dimmed. If all of the commands in the menu are dimmed, the cascading menu itself will also be dimmed. It is possible to open the cascading menu to see the dimmed commands, but it is not possible to activate them. In softkey style, the commands are invisible. If all of the commands in a menu are invisible the cascading menu will also be invisible.

The option buttons in Set cascade determine if the commands in Cascade are available or not. For example if command Cmd E available is activated the command Cmd E is available and Cmd F is not.

Cascading available is a check box that decides the availability of the cascading menu. When a cascading menu is unavailable in pen style, the cascading menu and its commands will be dimmed; in softkey style they will be invisible. You can change the availability of the commands in the cascading menu but it will not change in the UI until the cascading menu is available again, commands will then have the present state.

For example when option button Cmd E available is marked, it is possible to activate Cmd E. Unmark Cascading available to make the cascading menu unavailable. None of the commands in Cascade will then be available. Changing option button Cmd F available to marked will not change anything in the UI. Make the cascading menu available by activating Cascading available. When this is marked, Cmd F can be activated again.

In Set visibility, the visibility of commands can be changed, icons can be added or removed and the interaction between different types of commands can be studied.

All of the check boxes in Set visibility ending with "visible" determine whether the command is visible or not. For example, Yes visible indicates whether the command of type Yes (EQikCommandTypeYes) is visible or not.

Check boxes in Set visibility ending with "icon" determine whether the command has an icon or not. All of the commands have the same icon. When using an icon instead of a text, it is possible to add more buttons in pen style.

Page 3 demonstrates the different types for commands, but we do not recommend using all of these different types in the same command list; for more information see UIQ Style Guide - Interaction. This page can, however, make it easier for a developer to figure out which type of commands to use and to see how they interact with each other in different phone styles.

The delete command is not be visible in the button bar and the highest prioritized delete command is assigned to the delete key. In this project there is only one delete command, so it will be assigned to the delete key.

When page 4 is opened for the first time, the commands in the cascading menu Sort order are sorted alphabetically. In Set sort order you can decide whether the commands in Sort order are sorted alphabetically or by priority.

When the option button Alphabetically is marked the commands in Sort order are sorted alphabetically and when the option button Priority is marked they are sorted by priority. When the commands are sorted by priority the command with the lowest numerical value has the highest priority, which means that B - Priority 1 is placed at the top of the list.

Build the QCommands project in the normal way. To run it, choose Commands from the Launcher.

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

CCommandsDocument represents the document in the Commands application.

CCommandsAppUi represents the application UI in the Commands application. It is responsible for creating the view.

CCommandsView is a view that contains four pages showing the usage of commands. All command handling in this view is passed over to the CCommandsViewModel. This demonstrates how command handling can be separated from the view-specific parts.

CCommandsViewModel takes care of all view-specific commands for CCommandsView. For each page that has page-specific commands there is one class that handles all of their commands. This demonstrates how the responsibility for the commands can be divided. For example, all of the page commands for page 2 are handled by CCommandsHandlerPage2.

CCommandsHandlerPage2 takes care of all of the commands that are specific for page 2 for CCommandsView. This is to separate the different page-specific commands from each other.

CCommandsHandlerPage3 takes care of all of the commands that are specific for page 3 for CCommandsView. This is to separate the different page-specific commands from each other.

CCommandsHandlerPage4 takes care of all of the commands that are specific for page 4 for CCommandsView. This is to separate the different page-specific commands from each other.