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:
  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 "<drive>:\workspace\<project name>\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.

prem	Copyright © 2012 Kony, Inc. All rights reserved.

prem	Copyright © 2012 Kony, Inc. All rights reserved.