## Editing Control Button Arrays

You can use the Properties view to edit Control Button Arrays (CBA). CBA's provide the basic soft-key controls for an application that appear at the bottom of a device’s display with names like Options/Exit, and Done/Cancel. The S60 SDK provides several combinations which can be chosen from the control button array property dropdown menu (Figure 1).

When it comes to editing a CBA, there are two options:

- If using a standard CBA combination, UI Designer automatically fills in the left and right custom text and id properties, then generates the appropriate source code to handle the events.
- If a custom CBA item is desired, the left and right custom text properties must be entered and the id properties for each set using either a predefined soft key event by defining a new one to handle the custom event. UI Designer then adds the new events to evant handler when it next generates the sources.

Figure 1 - Control button array selection dropdown

#### Editing a Control Button Array

1. Select the CBA component in the editor view

The Properties view shows the component properties.

2. For a standard CBA combination:
   - Click the Behavior > control button array property, then select a standard CBA combination from the dropdown list

   The left and right custom text properties and left and right id properties are automatically set.

3. For a custom CBA combination:
   - Edit one of the CBA custom text items either in the editor or properties view

The associated custom text property displays the new text and the control button array property changes to CUSTOM.

NOTE If you decide to change a custom CBA into a standard one, the left and right custom text properties will be cleared. You will need to re-enter the CBA’s default text.

### Middle Soft Key

An additional middle soft key (MSK) is available in S60 SDKs greater or equal to 3.2. The middle soft key is only available and visible in Portrait layout mode, not Landscape. The MSK feature is enabled by default. However, it can be disabled in a properties setting. There is no impact to having MSK enabled by default; if you do not set the properties, it will not be displayed.

To enable/disable the MSK feature, open the project's application.uidesign file in the Carbide.c++ Application Editor (double-click on file in Project Explorer). Select the AppUi tab and select the complete UI design (topmost selection in Outline view). In the properties tab, select Appearance > enable middle soft key and select true or false as desired; as shown in Figure 2.

Figure 2 - MSK Enable or Disable Option

Additional property settings that support the MSK feature are visible in the Behavior > control button array property settings for a Control Pane in a UI design; as shown in Figure 3. The control button array property should be set to CUSTOM when defining the middle key as a context menu.

NOTE If CUSTOM is not displayed for control button array property, you can select None for the left id. CUSTOM will appear and you can then reset left id to desired setting.

There are essentially four modes of MSK operation. They include:

- no MSK (middle id property set to none)
- a single command
- MSK context menu (middle id set to Context Options)
- or Options menu (identical setting as left soft key)

Figure 3 - Control Button Array with Middle Soft Key properties

#### Single Command

The MSK can be used to execute a single command or action, for example, Open, Change, etc., and contains a text label.

#### Context Menu

When the MSK is used to open a context specific options menu, the label is an icon referring to more commands (as shown in Figure 4). As a context menu, this typically involves the menu to be dynamically generated depending on application context. For this option, use the Context Options id in the Behavior > control button array > middle id property settings.

NOTE If the Middle custom text is empty and the control button array is not CUSTOM, then no MSK (CBA_BUTTON resource) button will be generated.

When the MSK is used in Context Options mode (MSK menu contains items different from the left soft key) an additional property will need to be set on the control pane. The middle soft key in the control pane will need to reference an alternate menu bar.

Figure 4 - Middle Soft Key Context Icon

For example, you could add a Menu Bar (menuBar1) and items (labeled A, B, and C) to the UI design and assign this menu bar to the left soft key labeled Options. Then add another Menu Bar (menuBar2) and create items labeled A and B, and assign it as the MSK context menu.

To assign a menu to the left soft key, select the entire UI design view (topmost selection in Outline view) and select View > options menu in the Properties tab. Then select menuBar1 as shown in Figure 5.

Figure 5 - Left Soft Key Menu Assignment

To assign menuBar2 to the MSK context menu, select the control pane (as shown above in Figure 3) in the UI design or Outline view. Then select menuBar2 from the list of menus in the Middle Soft Key Menu property settings (Figure 6). The Middle Soft Key Menu > middle soft context options menu property provides a dropdown list of all available Menu Bar components you have added to the project.

Figure 6 - Middle Soft Key Menu Selection

The left soft key (Options) will display menu items A, B, and C and the middle soft key will display menu items A and B.

#### Options Menu

As an Options menu, the middle soft key is meant to duplicate the left soft key (e.g. OK in queries), and the MSK label is an icon (dot) referring to Select. In this case, make the middle id the same as the left id.

The list of available ids are the same ids available for the left and right soft keys, including “Generated command”. Generated commands will add the proper enumeration to the project’s HRH file.

Preset options exist in the Behavior > control button array properties setting. The option syntax is read as Left_Right__Middle. For example, OK_CANCEL__SELECT would assign OK to the left key, Cancel to the right soft key, and Select to the middle soft key.

##### Related tasks

- Editing Array Properties
- Editing Color Data
- Editing Date Data
- Editing Enumerated Data
- Editing Image Property Data
- Editing Location/Size Data
- Editing Numeric Data
- Editing String List Data
- Editing Text Data
- Editing Time Data
- Restoring Default Values

##### Related references

- Properties View