ComboBox Widget

A ComboBox is a widget that allows you to select a single item from a drop-down list.

If you select the drop-down arrow on a ComboBox, a drop-down list containing a list of items (values) are displayed. When you select an item from the drop-down list, the selected item is displayed on the ComboBox.

A ComboBox is similar to a ListBox. However, unlike the ListBox, you can only select a single item at a time.

You can use a ComboBox widget when you require a user to select a single item from a list of items (greater than 1 item) while occupying relatively lesser space as compared to a RadioButton widget (a radio button displays all the available options to make a single selection and hence takes more space).

You can add the ComboBox Widget only to the VBox form. This widget will be available in the Widgets palette when the VBox form is selected in the app canvas.

The ComboBox widget capabilities can be broadly categorized into the following:

• Layout
• Animations
• Data Management
• 3D Touch
• User Input Handling
• UI Appearance
• Miscellaneous
• Configurations Common To All Widgets

Layout

UI Appearance

Animations

Data Management

3D Touch

User Input Handling

Miscellaneous

Configurations Common To All Widgets

ComboBox Widget Basics

Creating a ComboBox Using a Constructor: voltmx.ui.ComboBox

var mycombobox = new voltmx.ui.ComboBox (basicConf, layoutConf, pspConf);

• basicConf is an object with basic properties.
• layoutConf is an object with layout properties.
• pspConf is an object with platform specific properties.

Note: The configuration properties should be passed only in the respective configuration objects otherwise they are ignored

Example

//The below function is preOnclickJS event callback function
function preOnclickJSCallBck(combobox) {
    alert("Inside preOnclickJS event callback");
}

//The below function is postOnclickJS event callback function
function postOnclickJSCallBck(combobox) {
    alert("Inside postOnclickJS event callback");
}

//The below function is onSelection event callback function
function onSelCallBck(combobox) {
    alert("Inside onSelection event callback");
}

//Creating the ComboBox
var comboBasic = {
    id: "combobox1",
    isVisible: true,
    masterDataMap: [
        [{
            "mykey": "key1",
            "myvalue": "value1"
        }, {
            "mykey": "key2",
            "myvalue": "value2"
        }],
        "mykey", "myvalue"
    ],
    skin: "comboSkin",
    selectedKey: "key1",
    onSelection: onSelCallBck
};

var comboLayout = {
    containerWeight: 80,
    widgetAlignment: constants.WIDGET_ALIGN_MIDDLE_LEFT,
    padding: [10, 10, 10, 10],
    margin: [10, 10, 10, 10],
    hExpand: true,
    vExpand: false
};

var comboPSP = {
    viewType: constants.COMBOBOX_VIEW_TYPE_TABLEVIEW,
    contentAlignment: constants.CONTENT_ALIGN_MIDDLE_LEFT,
    placeholder: "Please select a value",
    placeholderI18NKey: "plcHolder",
    popupTitle: "ComboPopUp",
    groupCells: true,
    preOnclickJS: preOnclickJSCallBck,
    postOnclickJS: postOnclickJSCallBck
};

combo = new voltmx.ui.ComboBox(comboBasic, comboLayout, comboPSP);

//Reading the selectedKeyValue of the ComboBox
alert("ComboBox selectedKeyValue is ::" + .combo.selectedKeyValue);

Customizing Appearance

You can customize the appearance of the ComboBox using the following properties:

• widgetAlignment: To specify the alignment of the widget.
• margin: Defines the space around a widget.
• padding: Defines the space between the content of the widget and the widget boundaries.
• skin: Used to specify the skin.
• focusSkin: Used to specify the focus skin.

Important Considerations

The following are the issues to avoid for a ComboBox:

• You must not use a ComboBox if you require the user to make multiple selections. If you require a user to make multiple selections, use a CheckBox or a ListBox widget.
• (Optional) You must first fetch the data for the ComboBox before showing the form. You must do so because if a form is shown and the ComboBox has no values, an empty ComboBox is displayed resulting in a bad user experience.

Limitations

The following are the limitations of the ComboBox widget across all platforms and individual platforms:

• All platforms:

  • You cannot add a ComboBox Widget to a Flex Form.

  • You cannot place a ComboBox inside a Segment and images inside a ComboBox.

• iOS:
  • When the viewType is set as COMBOBOX_VIEW_TYPE_ONSCREENWHEEL, the skin supports only backgroundcolor and style as one color.
  • Multistep Gradient is not supported when groupCells property is set to true.

• Android: The skin and focusSkin are not applied to the default ComboBox that appears on a Form when rendered. These skins are applied to the ComboBox items in the popup (appears when you click the ComboBox widget). Work Around: To apply the skin and focusSkin to the default appearance of the ComboBox widget, do the following:

  1. Create two NinePatchDrawable images and name them as “combo_box_normal_skin.9.png” for Normal skin and “combo_box_focus_skin.9.png” for Focus skin. Place these images in “_:\\workspace\\\\resources\\mobilerichclient\\Android\\_" directory.

  2. Build the Application for Android. The Normal and Focus skins will be applied to the default ComboBox appearance.

  For information on NinePatchDrawable images, see the following links:

  • http://developer.Android.com/guide/topics/graphics/2d-graphics.html#nine-patch
  • http://developer.Android.com/guide/developing/tools/draw9patch.html
• J2ME platform: If you do not specify the focusSkin, it is not possible to identify the traversal.
• Mobile Web:
  • The onSelection event is not supported on the Basic version of Mobile Web as the Java script is not supported on browsers of basic devices. To achieve the functionality similar to an onSelection event, you must create an additional button for the Basic version of the Mobile Web with an onclick event and attach an onSelection closure.
  • Due to Browser restriction, you cannot apply padding for a ComboBox.
  • The hExpand property is not applicable.
  • focusSkin is not supported.