Listbox

Creates a listbox.

Syntax

HTML	<div cordysType="wcp.library.ui.ListBox" id=listID> <div> ... </div> </div>

The listbox component consists of a<div cordysType="wcp.library.ui.ListBox">tag and a collection of<DIV>tags inside them. Each<div>tag represents an option. The component can be used to display a list of items in a select box. The users can then select the item from the list for their own use.

To dynamically add and initialize this component, you can use theinitializeHTMLElementsoraddTypemethods of the Application object.

The properties, methods, and events defined for this component are as follows:

Table 1. List of Attributes

Attribute

Property

Description

enabled

N/A

Sets the enabled property that denotes whether the listbox is enabled or not. The values can be:

true: Default. List box is enabled.
false: List box is disabled.

multipleSelect

N/A

Sets the multipleSelect property that denotes whether the user can select single or multiple options. The values can be:

true: The user can select one or more options from the listbox.
false: Default. The user can select only one option from the list box.

options

Array that retrieves the collection of DIV objects in a listbox.

Table 2. List of Methods

Method	Description
add	Adds an option to the Listbox. Adding an option can be done either by passing an option node, or by passing a string and a value.
focus()	Sets the focus on the listbox.
getEnabled()	Gets the value of the enabled property.
getMultipleSelect()	Gets the value of the multipleSelect property.
getOptions()	Returns an array with all the options available.
getSelectedIndex()	Gets the index of the selected option. If no option is selected it returns -1
getSelectedIndices()	Returns an array with all the indices of the selected options.
getSelectedOptions()	Returns an array with all the selected options. For a listbox the array has a maximum length of one.
getSelectValue()	Gets the value of the selected option.
remove(iOption)	Removes an element from the listbox.iOptionis a required parameter that denotes the index of the element or the option node that is to be removed. iOption: Required: the index of the option to be removed, OR the option node itself.
removeAll()	Clears all the options in the listbox.
resizeToContent()	Resizes the listbox to the size of the largest option.
setEnabled(bEnabled)	Sets the enabled property that denotes whether the listbox is enabled or not. bEnabled: Required. Possible values are: true: Default. Listbox is enabled. false: Listbox is disabled.
setMultipleSelect(bMultipleSelect)	Sets themultipleSelectproperty that denotes whether the user can select single or multiple options. bMultipleSelect: Required. Possible values are: true: Default. The user can select one or more options from the list. false: The user can select only one option from the list box.
setSelectedIndex(iIndex)	Selects the option with the index passed. iIndex: Required. When set to -1 all options are unselected. When an index is passed larger than the number of options, the last option is selected.
setSelectedIndices(iIndecesArray)	Selects the options of indexes as passed in the array. iIndecesArray: Required. An array with indeces of options which need to be selected.
setSelectValue(iValue)	Selects the first option with the passed value. iValue: Required. Refers to the value of an option.
setSelectValues(iValuesArray)	Selects the first option of all the passed values. iValuesArray: Required. Refers to the array of option values.
sort(property,bAscending)	Sorts the options in the control. property: Refers to any attribute of the option. The default value is the option's description. bAscending: Boolean that indicates the sorting order. Possible values are: true: Sorts in the ascending order. false: Default. Sorts in the descending order.

Table 3. List of Events

Event	Description
onchange	Fires when the contents of the object selected have changed.
onselectchange	Fires before the contents of the object selected are changed.

Key-control

The following keys are supported to provide easy navigation to the user in the listbox.

[arrow-up]: selects previous option, all other options deselected.
[arrow-down]: selects next option, all other options deselected.
Shift + [arrow-up]: selects previous option and current option remains selected (if multipleSelect=true).
Shift + [arrow-down]: selects next option and current option remains selected (if multipleSelect=true).
Ctrl + [arrow-up]: selects previous option, current deselected, but other options not altered.
Ctrl + [arrow-down]: selects next option, current deselected, but other options not altered.
Page Up: Selects and scrolls to the top option so that selected option is shown in the visible listbox items list.
Page Down: Selects and scrolls to the bottom option so that selected option is shown in the visible listbox items list.
Shift + Page Up: Selects all options from current option to top option in the visible listbox items list (if multipleSelect=true).
Shift + Page Down: Selects all options from current option to bottom option in the visible listbox items list (if multipleSelect=true).

Mouse-control

A mouse click on an option selects the option and deselects the other options. With the shift and ctrl keys multiple options can be selected. Tooltips show the full text of an option.
Note: This component deprecates the select component. The component can be used as a replacement to the Microsoft's SELECT component because the SELECT component is a window control. Using a window control will make the control appear above all the HTML controls even if the z-index property is set to a higher value.

Example

The following example shows the usage of the behavior:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
	<head>
		<title>List Box Demo</title>
		<script src="/cordys/wcp/application.js"> </script>
		<script type="text/javascript">
			function addItem()
			{
				var itemName = prompt("Enter a name for the item", "Mango");
				if (itemName)
				{
					var itemValue = prompt("Enter a value for the item", "50");
					if (itemValue)
					{
						document.getElementById("myFruitList").add(itemName, itemValue);
						application.notify("Added" + itemName + "!");
					}
				}
			}
			function removeItem()
			{
				var itemIndex = prompt("Enter the index of the item to remove", 2);
				var itemName = document.getElementById("myFruitList").getOptions()[itemIndex].innerText;
				if (itemIndex)
				{
					document.getElementById("myFruitList").remove(itemIndex);
					application.notify("Removed" + itemName + "!");
				}
	 }
			function getOptions()
			{
				listOptions = document.getElementById("myFruitList").getOptions();
				str = "List Options \n\n";
				for (var i=0 ; i<listOptions.length ; i++)
				{
					str += listOptions[i].innerHTML + "\n";
				}
				application.notify(str);
			}
		</script>
	</head>
	<body>
		<h4>List Box Component</h4>
		<br/><br/><br/>
			My Fruit List :
		<br/><br/>
		<div cordysType="wcp.library.ui.ListBox" id="myFruitList" style="height:150px;width:100px">
			<div value="10" > Apple </div>
			<div value="20" > Pear </div>
			<div value="30" > Durian </div>
			<div value="40" > Jackfruit </div>
		</div>
		<br/><br/>
		<button class="medium" onclick="addItem()" >Add</button>
		<button class="medium" onclick="removeItem()" >Remove</button>
		<button class="medium" onclick="getOptions()" >Options</button>
	</body>
</html>

pp108 : Listbox