Skip to content

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

Events Description
doLayout Invoked for every widget when the widget position and dimensions are computed or calculated.
Properties Description
anchorPoint Specifies the anchor point of the widget bounds rectangle using the widget's coordinate space.

UI Appearance

Properties Description
blockedUISkin Specifies the skin that must be used to block the interface until the action in progress (for example, a service call) is completed.
focusSkin Specifies the look and feel of the ComboBox when in focus.
hoverSkin Specifies the look and feel of a widget when the cursor hovers on the widget.
opacity Specifies the opacity of the widget.
popupFocusSkin Specifies the skin that is applied to each item in the native popup (list of options available) that appears when you select the ComboBox.
popupSkin Specifies the skin that is applied to each item in the native popup (list of options available) that appears when you select the ComboBox.
viewConfig Specifies the view configuration for different viewtypes.
viewType Specifies the view mode of the ComboBox.
wheelBackgroundColor Specifies the background color for the wheel that is displayed when you click the ComboBox.

Animations

Methods Description
animate Applies an animation to the widget.
Properties Description
transform Contains an animation transformation that can be used to animate the widget.
widgetSwipeMove Used to enable and configure the left or right swipe actions for a widget.

Data Management

Properties Description
lockTextScroll Allows you to enable/disable the horizontal scrolling for the selected item in the ComboBox Widget.
inputAccessoryViewType The extra buttons (or controls) allow specific operations needed by your application, such as moving to the next or previous text field, making the keyboard disappear and so on. The area above the keyboard is known as Input Accessory View.
masterData Specifies the set of values that must be displayed for the user to make a selection from the available choices.
masterDataMap Specifies the set of values from which you can make a selection.
popupTitle Specifies the title text to be displayed for the ComboBox.
placeholder Specifies the temporary or substitute text (a hint provided as a word or phrase) that must be displayed on the ComboBox until the actual selection is made.
singleLineText If the length of the text is more than the space available, the selected options text will be displayed truncated, in a single line with (...) ellipses.
singleLineTextInPopup If the length of the text is more than the space available, the popup options text will be displayed truncated, in a single line with (...) ellipses.
selectedKey Specifies the value to be shown as selected. If you do not select a value, the return value is null/nil.
selectedKeyValue Returns the array of selected key-value pair. If you do not select a value, the return value is null/nil.
textTruncatePosition When the property singleLineText is set to true, this property controls the position of the ellipses (...), in the selected option text.
textTruncatePositionInPopup When the property singleLineTextInPopup is set to true, this property controls the position of the ellipses (...), in the popup options text.
toolTip Specifies the hint text when the cursor hovers over a widget, without clicking it.

3D Touch

Methods Description
registerForPeekandPop Registers a widget to enable 3D Touch peek and pop gestures.
setOnPeek Sets and overrides the existing onPeekCallback for the widget.
setOnPop Overrides the existing onPopCallback for the widget.
unregisterForPeekandPop Unregisters a widget from 3D Touch peek and pop gestures.

User Input Handling

Events Description
onSelection Triggered when you select or unselect any item in ComboBox.
onScrollWidgetPosition Invoked by the platform when the widget location position gets changed on scrolling.
Methods Description
addGestureRecognizer Allows you to set a gesture recognizer for a specified gesture for a specified widget.
removeGestureRecognizer Allows you to remove the specified gesture recognizer for the specified widget.
setGestureRecognizer Allows you to set a gesture recognizer for a specified gesture for a specified widget.

Miscellaneous

Properties Description
dropDownImage Specifies the image to be used for the drop-down box indicator.
groupCells Specifies if the group cells style must be applied.
showAppMenu Provides you to show or hide the app menu when the dialog is open.
tickedImage Specifies the image to be displayed when you make a selection.
unTickedImage Specifies the image to be displayed when a selection is cleared.
Methods Description
convertPointFromWidget Allows you to convert the coordinate system from a widget to a point (receiver's coordinate system).
convertPointToWidget Allows you to convert the coordinate system from a point (receiver's coordinate system) to a widget.
getBadge Enables you to read the badge value (if any) attached to the specified widget.
setBadge Enables you to set the badge value to the given widget at the upper, right corner of the widget.

Configurations Common To All Widgets

Properties Description
accessibilityConfig Enables you to control accessibility behavior and alternative text for the widget.
enableCache Enables you to improve the performance of Positional Dimension Animations.
isVisible Controls the visibility of a widget on the form.
id id is a unique identifier of button consisting of alpha numeric characters.
info A custom JSObject with the key value pairs that a developer can use to store the context with the widget.
parent Helps you access the parent of the widget. If the widget is not part of the widget hierarchy, the parent property returns null.
Methods Description
removeFromParent Allows you to remove a child widget from a parent widget.
setEnabled Specifies the widget that must be enabled or disabled.
setFocus Specifies the widget on which there must be focus.
setVisibility Use this method to set the visibility of the widget.

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:

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

    • 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: