Commands in the User Interface

Exactly where commands are displayed in the UI depends mainly on how the phone is configured and how the commands are configured.

Phones may differ in ways that influence how commands are distributed:

• UI configurations such as Softkey, Pen and Softkey-Touch,

• Screen furniture such as softkey labels, Button bar and Application-title bar,

• Hardware keys such as back and clear,

• Algorithms for how commands are placed and ordered.

You have to consider this diversity when creating your commands. If you twist and tweak them to end up where you want them for one phone model, the result might not work very well on other phone models. So try to set up your commands in the correct way for the best total user experience.

A command can have a text label and an optional short text label. The short text label is used where space is limited, such as for a softkey label or on a button in the Button bar. Commands can also have a graphical presentation in the form of an icon.

A command can be dimmed, which still shows the command to the user but the user cannot initiate its action. If the user should not be able to see the command at all, it can be made invisible.

The most influential setting, in terms of determining where a command will end up in the UI, is its type. The type indicates the purpose of the command on a conceptual level. These are the available types:

Item

Used for acting on the control having focus. Views and dialogs do not normally use commands with the type Item; instead, controls add commands of type Item when they gain focus.

Screen

Used for actions relevant for the whole view or dialog, that is, actions that do not depend on which control or item has focus. Most of the commands owned by a view or a dialog are of type Screen.

Done

Used to leave the current view or dialog when the user has completed an action. In editable views or dialogs, "Save" is normally a command of type Done. In information dialogs a command of type Done is often used to close the dialog; in contrast, a command of type Cancel is normally used in a view.

Cancel

Used to leave the current view or dialog unaffected, when the user chooses to not complete an action. Views normally have a command of type Cancel. In editable views or dialogs, a command of type Cancel is often used to cancel changes. If a view does not define its own command of type Cancel, the view framework adds one, which must be explicitly removed if it is not wanted.

Yes

Used to answer a direct question, such as "Do you really want to abort?" A command of type Yes is normally used together with a command of type No.

No

Used to answer a direct question, such as “Do you really want to abort?” A command of type No is normally used together with a command of type Yes.

Help

Used to bring up help texts.

Clear

Used for removing text.

Delete

Used for deleting items, such as selected items in a list box.

Category

Used for selecting and managing categories of the view framework's category model.

Commands related to each other, such as a text editor's edit commands, can be grouped so they will be shown together in the UI. There are two ways of grouping commands: unnamed groups and named groups. Commands in unnamed groups are just grouped together in menu panes, using dividers to separate them from other commands, whereas commands in named groups are shown as submenus. Unnamed groups can only be shown in the menu whereas named groups can appear in most places, such as in menus, on softkeys and in the button bar. Commands in unnamed groups must be of the same type.

If you have more than one command of the same type, you can set the priority for each command. Higher prioritized commands, indicated by a lower numerical value, are placed where users are more likely to see them and use them.

Most of the settings that are available for commands are the ones mentioned above, such as, text label, icon, dimmed, invisible, type, grouping and priority. However, there are a few special cases where more settings are needed; flags are used for dealing with these cases.

State flags

Flags are divided into two groups; the first group is state flags:

EQikCmdFlagDimmed

Dims a command

EQikCmdFlagInvisible

Makes a command invisible

EQikCmdFlagUnavailable

Makes a command unavailable (invisible in Softkey style)

EQikCmdFlagCheckBox

Indicates that the command should be shown as a checkbox

EQikCmdFlagRadioStart, EQikCmdFlagRadioMiddle and EQikCmdFlagRadioEnd

Used for commands in a radio button group where only one can be selected at any given time. EQikCmdFlagRadioStart is used on the first command, EQikCmdFlagRadioEnd on the last, and EQikCmdFlagRadioMiddle on the rest of the commands.

EQikCmdFlagSymbolOn

For a check box command, EQikCmdFlagSymbolOn indicates that the check box is marked. For a radio button command EQikCmdFlagSymbolOn indicates that the radio button is selected.

EQikCmdFlagInlinePane

Displays the command as a divider with textual representation

EQikCmdFlagDebugOnly

Hides commands in release builds

EQikCmdFlagSortAlphabetic

Used for commands that are sorted by their textual representation instead of their priority

CPF flags

The other group of flags is CPF (Command Processing Framework) flags:

EQikCpfFlagPreferToBePlacedInButtonbar

Displays commands in the button bar together with the default button bar commands

EQikCpfFlagDuplicateInMenuPane

Makes a command appear in the More menu or application menu when it normally is only placed somewhere else, such as on a hardware key

EQikCpfFlagIsDefault

Indicates that the command is the primary action of the view or dialog

EQikCpfFlagExecuteRepeat

Executes the command repeatedly as long as the hardware key it is mapped to is pressed

EQikCpfFlagOkToExclude

Used on commands that are less important. On a phone with a small screen, these commands might not be available to the user.

EQikCpfFlagHardwarekeyOnly

Used on commands that should only be available on hardware keys

EQikCpfFlagTouchscreenOnly, EQikCpfFlagNoTouchscreenOnly, EQikCpfFlagInteractionMenubarOnly, EQikCpfFlagInteractionSoftkeysOnly, EQikCpfFlagPortraitOnly and EQikCpfFlagLandscapeOnly

Indicate if a command should be visible or not in relation to the current UI configuration of the phone. For example, if a command is flagged EQikCpfFlagTouchscreenOnly it will only be visible if the current UI configuration has a touch screen.

EQikCpfFlagDoneCommandPreferToBePlacedOnPositiveSoftkey

Makes sure the Done command is not displayed as the primary action

EQikCpfFlagReplaceContainerPopoutDone

Replaces the default Done command added by the container pop out

This section describes the details of how commands are distributed, which can be helpful to understand the command processing framework. However, it is not a good idea to configure your commands using the wrong types just to get exactly the result you want since this will make supporting different configurations difficult. It is also worth noting that this section describes the default implementation provided by UIQ 3. Implementation is likely to differ between phone models from different manufacturers.

The commands are offered to each command operator, that is each possible location, such as hardware keys, softkeys, and Button bar. The command operators choose if they want to display the command, and whether or not to consume it; consumed commands are not offered to the other command operators.

Before the commands are distributed the ones that should not appear anywhere are removed from further consideration. This is the end station for:

• Invisible commands,

• Commands which do not match the current UI configuration when flagged EQikCpfFlagTouchscreenOnly, EQikCpfFlagNoTouchscreenOnly, EQikCpfFlagInteractionMenubarOnly, EQikCpfFlagInteractionSoftkeysOnly, EQikCpfFlagPortraitOnly or EQikCpfFlagLandscapeOnly,

• Commands flagged EQikCmdFlagDebugOnly in release builds.

When UIQ Technology delivers UIQ 3 to phone manufactures, four different hardware-key configurations are supported. However, phone manufactures usually develop their own hardware-key configurations for the UIQ 3 phones they bring to market.

A hardware key can either consume or use a command. If a command is used, the hardware key simply acts as a shortcut to the command; the command will still be available somewhere else in the UI. On the other hand, if a command is consumed it will not be available anywhere else.

Softkey style with softkey algorithm "Three softkeys"

The "Three softkeys" algorithm has one dedicated hardware key called the Clear key. This key consumes Clear commands. If there is no Clear command, this key acts as shortcut to the command that is placed on the right softkey.

Besides this hardware key provided on the phone, two additional hardware keys, Escape and Done, can be provided on a keyboard that is attached to the phone. If it is available, the Escape key uses Cancel commands. If it is available, the Done key uses Yes commands and Done commands. If neither Done or Yes is available, the Done key uses No commands and Cancel commands.

Softkey style with softkey algorithm "Three softkeys and Back key"

The "Three softkeys and Back key" algorithm has two dedicated hardware keys called the Clear key and the Back/Cancel key. The Clear key consumes Clear commands. If there is no such command it will use a Delete command. The Back/Cancel key consumes Cancel commands. If there is no such command it will use a No or Done command.

Besides the hardware keys provided on the phone, two additional keys, Escape and Done, can be provided on a keyboard that is attached to the phone. If it is available, the Escape key consumes Cancel commands. If it is available, the Done key uses Yes commands and Done commands. If neither Done or Yes is available, the Done key uses No commands and Cancel commands.

Softkey style Touch

The Softkey-style-Touch UI configuration has two dedicated hardware keys called the Clear key and the Back/Cancel key. The Clear key consumes Clear commands. If there is no such command it will use a Delete command. The Back/Cancel key uses Cancel commands. If there is no such command it will use a No or Done command.

Besides the hardware keys provided on the phone, two additional keys, Escape and Done, can be provided on a keyboard that is attached to the phone. If it is available, the Escape key uses Cancel commands. If it is available, the Done key uses Yes commands and Done commands. If neither Done or Yes is available, the Done key uses No commands and Cancel commands.

End station

Hardware keys are the end station for:

• Commands on hardware keys which consume the command, as opposed to just using the command,

• Commands flagged EQikCpfFlagHardwarekeyOnly,

• Commands that have no representation on the screen, that is, they have no text label and at the same time they have no icon.

However, if the command is flagged EQikCpfFlagDuplicateInMenuPane it will still show up in the More menu or in the application menu. Futhermore, if the command is flagged EQikCpfFlagPreferToBePlacedInButtonbar it will be available for other command operators as well and not end its journey here.

The AppTitle back button appears only in Softkey-style-Touch UI configuration and consumes Cancel commands.

The AppTitle back button is the end station for:

• A Cancel command

However, if the command is flagged EQikCpfFlagDuplicateInMenuPane it will show up in the More menu as well.

There are two softkey algorithms available in the UIQ product, "Three softkeys", introduced in UIQ 3.1, and "Three softkeys and Back key", introduced in UIQ 3.0. The main difference is that Three softkeys and Back key has a separate back hardware key, whereas "Three softkeys" uses the right softkey as a back key.

If a command is part of an unnamed group, it always ends up in the More menu. Named groups, however, can end up directly on a softkey.

The right softkey consumes No commands. If there is no No command it consumes a Cancel command.

The center softkey consumes Yes commands. If there is no Yes command it consumes an Item command. If there is no Item command it consumes a Done command. However, if the command is flagged EQikCpfFlagDoneCommandPreferToBePlacedOnPositiveSoftkey it will be consumed by the More menu of left softkey instead and the center softkey will be empty.

The left softkey's More menu consumes all remaining commands as well as commands that appear elsewhere but are flagged EQikCpfFlagDuplicateInMenuPane.

Placement order of commands in the More menu

The command that is placed on the center softkey is duplicated at the top of the More menu. Below this command, the rest of the commands are arranged according to type. From top to bottom, the types of commands are: Done, Yes, No, Item, Screen, Clear, Delete, Cancel, Category and Help.

When there are multiple commands of the same type, unnamed groups come first. The commands in each unnamed group are placed between dividers. Once unnamed groups are placed, the rest of the commands of the same type are sorted by priority. However, if they are flagged EQikCmdFlagSortAlphabetic then they are sorted alphabetically. If two commands of the same type should have the same priority, the command that was created first is placed above.

If there is only one single command to be placed in the More menu, the duplication of the command that is to be placed on the center softkey, the command will be shown directly on the left softkey and no More menu will be displayed. In this situation the command label will, however, not be displayed on the center softkey label. Instead, an icon will be shown on the center softkey label to indicate that center softkey activates the same command as the left softkey.

If there is no command to be placed on the center softkey and just one command is to be placed in the More menu, that one command will be placed directly on the softkey and no More menu will be displayed.

The center softkey consumes an Item command. If there is no Item command it consumes a Done command. However, if the command is flagged EQikCpfFlagDoneCommandPreferToBePlacedOnPositiveSoftkey, it will be consumed by the left softkey instead and the center softkey will be empty.

The left softkey consumes a Done command. If there is no Done command it consumes an Item command.

The right softkey's More menu consumes all remaining commands as well as commands that appear elsewhere but are flagged EQikCpfFlagDuplicateInMenuPane.

The commands in the More menu are ordered by type. From top to bottom, the types of commands are: Yes, No, Item, Done, Screen, Clear, Delete, Cancel, Category and Help. When there are multiple commands of the same type, unnamed groups come first. The commands in each unnamed group are placed between dividers. Once unnamed groups are placed, the rest of the commands of the same type are sorted by priority. However, if they are flagged EQikCmdFlagSortAlphabetic, then they are sorted alphabetically. If two commands of the same type should have the same priority, the command that was created first is placed above.

Special algorithm for Yes and No commands

If a Yes or a No command is to be placed on the center softkey, a special algorithm is used instead.

The left softkey consumes the Yes command.

The right softkey consumes the No command.

The center softkey's More menu consumes all remaining commands as well as commands that appear elsewhere but are flagged EQikCpfFlagDuplicateInMenuPane.

The order of the commands in the More menu is the same as when the More menu is placed on the right softkey. They are ordered by type. From top to bottom, the types of commands are: Yes, No, Item, Done, Screen, Clear, Delete, Cancel, Category and Help. When there are multiple commands of the same type, unnamed groups come first. The commands in each unnamed group are placed between dividers. Once unnamed groups are placed, the rest of the commands of the same type are sorted by priority. However, if they are flagged EQikCmdFlagSortAlphabetic, then they are sorted alphabetically. If two commands of the same type should have the same priority, the command that was created first is placed above.

If there is only one command in the More menu, it will be placed directly on the right softkey and no More menu will be displayed.

Softkeys are the end station for:

• All commands

It consumes Cancel, Yes, No and Done commands, as well as other commands flagged EQikCpfFlagPreferToBePlacedInButtonbar. However, it only accepts as many commands as will fit on the screen, three text buttons or nine icon buttons at the most. The buttons are ordered from left right by type: Yes, Done, No, Cancel and other.

If a command is flagged EQikCpfFlagIsDefault it gets a different border and is duplicated on the Action hardware key. But for this to work you must make sure that there no other commands on the action key!

The Button bar is the end station for:

• The commands that are shown as buttons in the button bar.

However, if the command is flagged EQikCpfFlagDuplicateInMenuPane it will show up in the application menu as well.

The category picker consumes all Category commands.

The application menu consumes all the remaining commands as well as commands that appear elsewhere but are flagged EQikCpfFlagDuplicateInMenuPane.

The commands are ordered by type. From top to bottom, the types of commands are: Yes, No, Item, Done, Screen, Clear, Delete, Cancel and Help. When there are multiple commands of the same type, unnamed groups come first. The commands in each unnamed group are placed between dividers. Once unnamed groups are placed, the rest of the commands of the same type are sorted by priority. However, if they are flagged EQikCmdFlagSortAlphabetic, then they are sorted alphabetically. If two commands of the same type should have the same priority, the command that was created first is placed above.

The AppTitle bar is the end station for:

• All commands.

See section 3.8, Examples of how to achieve standard presentations, in the Programmer's Guide to New Features in UIQ 3, for examples of command organization.

See UIQ Examples QCommands for an example application that presents the features of commands in UIQ 3.