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
| 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: kony.ui.ComboBox
var mycombobox = new kony.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 kony.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 "<drive>:\workspace\<project name>\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:
- 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.