The ListBox widget displays a list of items as a drop-down box and allows you to select a one or more items from the list.
The data model for the ListBox widget is a key value pair. The key is hidden part of the model while value is displayed to the user.
Following are the real-time use cases of ListBox widget:
To select your nationality while creating a user account in a travel application.
To choose a department of an employee in the employee profile.
To select your city name while providing the delivery address in shopping applications.
To apply filters. For instance, in social networking applications, users can choose the subjects of their choice such as nature, technology, health. User’s feed can then be customized as per the interests.
You can add or modify the UI of an application based on the option that you select from the list of identity services.
Widgets are normally added to your application using Quantum Visualizer, but can also be added from code. For general information on using widgets in Quantum Visualizer, see Designing an Application in the Visualizer User Guide.
For general information on the ListBox widget see the ListBox topic in the Quantum Visualizer User Guide.
The ListBox widget capabilities can be broadly categorized into the following:
Specifies the temporary or substitute text (a hint provided as a word or phrase) that must be displayed on the ListBox until the actual selection is made.
If the length of the text is more than the available space, the selected options text and the popup options text are displayed in a truncated manner, in a single line with ellipses (...). The position of the ellipses is controlled by the textTruncatePosition property.
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. The position of the ellipses is controlled by textTruncatePositionInPopup property.
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. The position of the ellipses is controlled by textTruncatePositionInPopup property. The default ellipses position is at the end of the line if textTruncatePositionInPopup property is not set.
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.
Allows the developer to execute custom javascript function before the onClick callback of the ListBox is invoked.
ListBox Widget Basics
NOTE: ListBox does not support multiple selection from Release 3.0 onwards. However, if you have upgraded from a version prior to Release 3.0 and used multiple selection, the backward compatibility will be maintained. If you require multiple selection capability, use either a CheckBox or a Segment with multiple selection enabled.
Creating a ListBox Using a Constructor: kony.ui.ListBox
var listbox1 = new kony.ui.ListBox (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
//Defining properties for a listbox.
var listBasic = {
id: "listbox",
isVisible: true,
masterData: [
["key1", "value1"],
["key2", "value2"],
["key3", "value3"]
],
skin: "listSkin",
focusSkin: "listFSkin"
};
var listLayout = {
widgetAlignment: constants.WIDGET_ALIGN_CENTER,
padding: [0, 0, 0, 0],
margin: [0, 0, 0, 0],
containerWeight: 100,
hExpand: false
};
var listPSP = {
applySkinsToPopup: true,
nativeListFieldSkin: "nativeListSkin",
viewType: constants.LISTBOX_VIEW_TYPE_SPINNER
};
//Creating the ListBox.
var listbx = new kony.ui.ListBox(listBasic, listLayout, listPSP);
//Reading the containerWeight of the listbox
alert("listbox containerWeight ::" + listbx.containerWeight);
Important Considerations
Shows dynamic set of data in a fixed space.
The master data of choices should be limited and fetched in a separate service call.
On iOS platform, when the viewType is set as LISTBOX_VIEW_TYPE_ONSCREENWHEEL, the skin supports only backgroundcolor and style as one color.
On iOS platform, Multistep Gradient is not supported when groupCells property is set to true.
On iOS , when the viewType is set as LISTBOX_VIEW_TYPE_LISTVIEW and the ListBox widget is in focus, if the orientation of the device is changed, the list is dismissed.
