QCommands
QCommands should not be looked upon as an ordinary application; its purpose is instead to present the features for 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, where each page has its own topic or highlight within the commands area:
Page 1 - This page don't have any page specific command, it only contains the view specific commands, which 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 and 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 usage of the option button list and 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 and remove command icons.
Page 4 - The commands on this page show how commands can be sorted alphabetically or by priority.
Commands
Page 1 View specific commands
Close (debug) is only available in debug mode; it closes the application. This command shall only be visible in debug mode because it is only used to find memory leaks during development of the application.
Change UI style makes it possible to toggle between pen style UI and softkey style UI.
Expand commands show how you can add and remove commands that are defined in the resource file during runtime. It adds two cascade items, Current state and Set current state.
In Set current state, two checkboxes change application states (ECommandsApplicationState1 and ECommandsApplicationState2) in the command state monitor. The command state monitor then changes the availability to the commands in the 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 which UI style is used. In pen style, the commands will be dimmed. If all of the commands in the menu are dimmed, the cascade menu itself will also be dimmed. It is possible to open the cascade 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 cascade menu will also be invisible.
Page 2 specific commands
The option buttons in Set cascade determine if the commands in Cascade are available or not. For example if command Cascade item 1 on is activated the command Cascade item 1 is available and Cascade item 2 is not.
Turn on cascade is a checkbox that decides the availability of the cascade menu. When a cascade menu is unavailable in pen style, the cascade menu and its commands will be dimmed; in softkey style they will be invisible. You can change the availability of the commands in the cascade menu but it will not change in the UI until the cascade menu is available again, commands will then have the present state.
For example when option button Cascade item 1 on is marked, it is possible to activate Cascade item 1. Unmark Turn on cascade to make the cascade menu unavailable. None of the commands in Cascade will then be available. Changing option button Cascade item 2 on to marked will not change anything in the UI. Make the cascade menu available by activating Turn on cascade. When this is marked, Cascade item 2 can be activated again.
Page 3 specific commands
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 checkboxes in Set visibility ending with "visible" decide if the command is visible or not. For example Yes visible indicates if the command of type Yes (EQikCommandTypeYes) is be visible or not.
Checkboxes in Set visibility ending with "icon" decide if 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 style. This page can, however, make it easier for a developer to figure out which type of commands to use and to see how they will interact with each other in different UI styles.
The delete command will not be visible in the buttonbar and the highest prioritezed delete command is assigned to the delete key. In this project there only exist one delete command, so it will be assigned to the delete key.
Page 4 specific commands
When page 4 is opened for the first time, the commands in the cascade menu Sort order are sorted alphabetically. In Set sort order you can decide whatever 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 priority is sorted first, which means that B - Priority 1 is placed at the top of the list.
Class summary
CCommandsApplication: 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.
CCommandsAppU: represents the application UI in Commands application. It has responsibility to create the view.
CCommandsView: view that contains four pages showing the usage of commands. All command handling in this view is passed over to the CCommandsViewModel. Demonstrates how the command handling can be seperated from the view specific parts.
CCommandsViewModel: takes care of all view specific commands for CCommandsView. For each page that has page specific commands there exist one class that handles all their commands. This demonstrates how the responsibility for the commands can be divided. For example all page commands for page 2 is handled by CCommandsHandlerPage2.
CCommandsHandlerPage2: takes care of all page 2 specific commands for CCommandsView. This to separate the different page specific commands from each other.
CCommandsHandlerPage3: takes care of all page 3 specific commands for CCommandsView. This to separate the different page specific commands from each other.
CCommandsHandlerPage4: takes care of all page 4 specific commands for CCommandsView. This to separate the different page specific commands from each other.
Usage
Build the QCommands project in the normal way.
First, run bldmake from the projects group directory where the bld.inf file is located:
This creates a batch file, called abld.bat, which you use in the next step. To build the project, you call abld build which will build the project for all default targets in both release and debug variants. To build for a particular target and variant, use abld build target-name variant, for example,
builds the project for the debug variant of WINSCW only. To run it, choose the application name from the Launcher.
Changes in This Version
Version 0.3 2006/04/19
Removed functionality to change UI configuration from the application. Small updates have been made in the code and comments so all UIQ examples are consistent with each other. The most common change has been include order in header and cpp-files, system includes shall be included before the user includes.
Reverted change to include header file for UID3 in the mmp file. This due to Carbide.VS (plugin that enable Symbian OS C++ application development using the Microsoft Visual Studio .NET 2003 IDE) doesn't support to include header files in mmp file.
Version 0.2 2006/01/23
Added a header file that defines the UID3 value. The UID3 is needed in three files (Commands.mmp, CommandsExternalInterface.h and Commands_reg.rss). Instead of define the UID3 value three times, each file only includes the UID header file and uses the define. This makes it easier to change the UID3, when there is only one place to update.
Version 0.1 2005/12/01:
First release.
Download:
QCommands
You need to be a registered member of the UIQ Developer Community and logged in to be able to download this file.