com.sap.ui.commons.client
Class ListBox

java.lang.Object
  com.google.gwt.core.client.JavaScriptObject
      com.sap.ui.core.client.Element
          com.sap.ui.core.client.Control
              com.sap.ui.commons.client.ListBox

public class ListBox
extends com.sap.ui.core.client.Control

The class ListBox is the GWT wrapper for the Phoenix control: sap.ui.commons.ListBox.

Provides a list of items from which users can choose an item. For the design of the listbox, features such as defining the listbox height, fixing the number of visible items, choosing one item to be the item that is marked by default when the listbox is shown, or a scrollbar for large listboxes are available.

• Properties
  • editable : boolean
    Value "true" makes the listbox interactive.
  • enabled : boolean
    Disabled controls have another color display depending on custom settings.
  • allowMultiSelect : boolean
    Specifies whether multiple selection is allowed.
  • visible : boolean
    Invisible controls are not rendered.
  • width : String
    Control width as common CSS-size (px or % as unit, for example). The setting overrides any definitions made for the setVisibleItems() method.
  • height : String
    Control height as common CSS-size (px or % as unit, for example). The setting overrides any definitions made for the setVisibleItems() method.
  • scrollTop : int
    Scrollbar position from the top. Setting the scrollTop property and calling scrollToIndex are two operations influencing the same "physical" property, so the last call "wins".
  • displayIcons : boolean
    Defines whether the icons of the list items should also be displayed. Enabling icons causes some space to be reserved for them, regardless of how many of the items actually have icons assigned. Displaying icons can also influence the width and height of a single item, which affects the height of the ListBox when it is defined in number of items. In particular with differently-sized icons the total ListBox height will not accomodte exactly the given number of items, then.
  • displaySecondaryValues : boolean
    Indicates whether the additionalText property that can be set on sap.ui.core.ListItems shall be displayed, or not.
  • valueTextAlign : com.sap.ui.core.client.TextAlign
    The text alignment in the primary column of the ListBox.
  • secondaryValueTextAlign : com.sap.ui.core.client.TextAlign
    The text alignment in the secondary (optional) text column of the ListBox.
  • minWidth : String
    The minimum width of the ListBox. If not set, there is no minimum width.
  • maxWidth : String
    The maximum width of the ListBox. If not set, there is no maximum width.
  • visibleItems : int
    The control height in number of items to be completely displayed without scrolling. Setting this overwrites any height in terms of CSS size previously set. When items have different heights, the height of the first item is used for all calculations. If between the visible ListBox items there are one or more separators, the specified number of items will not exactly fit. If the value is retrieved it will equal the previously set value if it was set, otherwise it will be the number of items completely fitting into the ListBox without scrolling if the control was already rendered. If the control was not rendered, the behavior is undefined, it may return -1 or any other number.
• Aggregations
  • items : com.sap.ui.core.client.Item
    Aggregation of items to be displayed. Must be either of type sap.ui.core.ListItem or sap.ui.core.SeparatorItem.
• Associations
• Events
  • select Event is fired when selection is changed by user interaction.

Version:

0.18.0-SNAPSHOT

Author:

GENERATOR (JavaScript control: sap.ui.commons.ListBox)

Constructor Summary

protected

ListBox() constructs the class ListBox hidden due to JavaScriptObject restriction

Method Summary

ListBox	addItem(com.sap.ui.core.client.Item item) Appends a item to the aggregation items.
void	addSelectedIndex(int index) Adds the given index to current selection.
void	addSelectedIndices(Integer[] indices) Adds the given indices to selection.
ListBox	attachSelectEvent(com.sap.ui.core.client.event.EventListener listener) attach an EventListener Event is fired when selection is changed by user interaction.
void	clearSelection() Removes complete selection.
static ListBox	create() creates a new instance of the class ListBox
static ListBox	create(String idOrConfig) creates a new instance of the class ListBox
static ListBox	create(String id, String config) creates a new instance of the class ListBox
ListBox	destroyItems() Destroys all the items in the Items-aggregation.
ListBox	detachSelectEvent(com.sap.ui.core.client.event.EventListener listener) detach an EventListener Event is fired when selection is changed by user interaction.
String	getHeight() Getter for property height Control height as common CSS-size (px or % as unit, for example).
com.sap.ui.core.client.js.JsArray<com.sap.ui.core.client.Item>	getItems() Getter for aggregation items Aggregation of items to be displayed.
String	getMaxWidth() Getter for property maxWidth The maximum width of the ListBox.
String	getMinWidth() Getter for property minWidth The minimum width of the ListBox.
int	getScrollTop() Getter for property scrollTop Scrollbar position from the top.
com.sap.ui.core.client.TextAlign	getSecondaryValueTextAlign() Getter for property secondaryValueTextAlign The text alignment in the secondary (optional) text column of the ListBox.
int	getSelectedIndex() Zero-based index of selected item.
Integer[]	getSelectedIndices() Zero-based indices of selected items, wrapped in an array.
com.sap.ui.core.client.Item	getSelectedItem() Returns selected item.
com.sap.ui.core.client.js.JsArray<com.sap.ui.core.client.Item>	getSelectedItems() Returns an array containing the selected items.
com.sap.ui.core.client.TextAlign	getValueTextAlign() Getter for property valueTextAlign The text alignment in the primary column of the ListBox.
int	getVisibleItems() Getter for property visibleItems The control height in number of items to be completely displayed without scrolling.
String	getWidth() Getter for property width Control width as common CSS-size (px or % as unit, for example).
int	indexOfItem(com.sap.ui.core.client.Item item) Checks for the provided com.sap.ui.core.client.Item in the items-aggregation and returns its index if found or -1 otherwise.
ListBox	insertItem(com.sap.ui.core.client.Item item, int index) Inserts some item into the aggregation named items.
boolean	isAllowMultiSelect() Getter for property allowMultiSelect Specifies whether multiple selection is allowed.
boolean	isDisplayIcons() Getter for property displayIcons Defines whether the icons of the list items should also be displayed.
boolean	isDisplaySecondaryValues() Getter for property displaySecondaryValues Indicates whether the additionalText property that can be set on sap.ui.core.ListItems shall be displayed, or not.
boolean	isEditable() Getter for property editable Value "true" makes the listbox interactive.
boolean	isEnabled() Getter for property enabled Disabled controls have another color display depending on custom settings.
boolean	isIndexSelected(int index) Returns whether the given index is selected.
boolean	isVisible() Getter for property visible Invisible controls are not rendered.
com.sap.ui.core.client.js.JsArray<com.sap.ui.core.client.js.JsArray<com.sap.ui.core.client.Item>>	removeAllItems() Removes all the items in the items-aggregation.
com.sap.ui.core.client.js.JsArray<com.sap.ui.core.client.Item>	removeItem(int index) Removes a item from the aggregation named items.
void	removeSelectedIndex(int index) Removes the given index from this selection.
void	scrollToIndex(int index, boolean lazy) If the ListBox has a scrollbar because the number of items is larger than the number of visible items, this method scrolls to the item with the given index.
ListBox	setAllowMultiSelect(boolean value) Setter for property allowMultiSelect Default value is: false
ListBox	setDisplayIcons(boolean value) Setter for property displayIcons Default value is: false
ListBox	setDisplaySecondaryValues(boolean value) Setter for property displaySecondaryValues Default value is: false
ListBox	setEditable(boolean value) Setter for property editable Default value is: true
ListBox	setEnabled(boolean value) Setter for property enabled Default value is: true
ListBox	setHeight(String value) Setter for property height
ListBox	setItems(com.sap.ui.core.client.js.JsArray<com.sap.ui.core.client.ListItem> items, boolean destroyItems) Allows setting the list items for this instance of ListBox as array.
ListBox	setMaxWidth(String value) Setter for property maxWidth
ListBox	setMinWidth(String value) Setter for property minWidth
ListBox	setScrollTop(int value) Setter for property scrollTop Default value is: -1
ListBox	setSecondaryValueTextAlign(com.sap.ui.core.client.TextAlign value) Setter for property secondaryValueTextAlign Default value is: Begin
void	setSelectedIndex(int index) Sets the zero-based index of the currently selected item.
void	setSelectedIndices(Integer[] indices) Zero-based indices of selected items, wrapped in an array.
ListBox	setValueTextAlign(com.sap.ui.core.client.TextAlign value) Setter for property valueTextAlign Default value is: Begin
ListBox	setVisible(boolean value) Setter for property visible Default value is: true
ListBox	setVisibleItems(int value) Setter for property visibleItems Default value is:
ListBox	setWidth(String value) Setter for property width

Methods inherited from class com.sap.ui.core.client.Control

addStyleClass, hasStyleClass, invalidate, placeAt, placeAt, removeStyleClass, rerender

Methods inherited from class com.sap.ui.core.client.Element

_convertArray, _convertArray, _convertArray, _convertArray, _convertArray, attachBrowserEvent, attachEvent, bindAggregation, bindContext, bindProperty, bindProperty, destroy, detachBrowserEvent, detachEvent, getDomRef, getElementName, getId, getLibraryName, getModel, getParent, getProperty, getTooltip_AsString, getTooltip_Text, getTooltip, isActive, setModel, setProperty, setTooltip, setTooltip, unbindAggregation, unbindContext, unbindProperty

Methods inherited from class com.google.gwt.core.client.JavaScriptObject

cast, createArray, createFunction, createObject, equals, hashCode, toSource, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ListBox

protected ListBox()

constructs the class ListBox
hidden due to JavaScriptObject restriction

Method Detail

create

public static ListBox create()

creates a new instance of the class ListBox

create

public static ListBox create(String idOrConfig)

creates a new instance of the class ListBox

Parameters:

id - id of the ListBox or configuration JSON string

create

public static ListBox create(String id,
                             String config)

creates a new instance of the class ListBox

Parameters:

id - id of the ListBox

config - configuration JSON string

isEditable

public final boolean isEditable()

Getter for property editable Value "true" makes the listbox interactive.

Returns:

the value of property editable

setEditable

public final ListBox setEditable(boolean value)

Setter for property editable
Default value is: true

Parameters:

value - boolean

Returns:

this to allow method chaining

isEnabled

public final boolean isEnabled()

Getter for property enabled Disabled controls have another color display depending on custom settings.

Returns:

the value of property enabled

setEnabled

public final ListBox setEnabled(boolean value)

Setter for property enabled
Default value is: true

Parameters:

value - boolean

Returns:

this to allow method chaining

isAllowMultiSelect

public final boolean isAllowMultiSelect()

Getter for property allowMultiSelect Specifies whether multiple selection is allowed.

Returns:

the value of property allowMultiSelect

setAllowMultiSelect

public final ListBox setAllowMultiSelect(boolean value)

Setter for property allowMultiSelect
Default value is: false

Parameters:

value - boolean

Returns:

this to allow method chaining

isVisible

public final boolean isVisible()

Getter for property visible Invisible controls are not rendered.

Returns:

the value of property visible

setVisible

public final ListBox setVisible(boolean value)

Setter for property visible
Default value is: true

Parameters:

value - boolean

Returns:

this to allow method chaining

getWidth

public final String getWidth()

Getter for property width Control width as common CSS-size (px or % as unit, for example). The setting overrides any definitions made for the setVisibleItems() method.

Returns:

the value of property width

setWidth

public final ListBox setWidth(String value)

Setter for property width

Parameters:

value - String

Returns:

this to allow method chaining

getHeight

public final String getHeight()

Getter for property height Control height as common CSS-size (px or % as unit, for example). The setting overrides any definitions made for the setVisibleItems() method.

Returns:

the value of property height

setHeight

public final ListBox setHeight(String value)

Setter for property height

Parameters:

value - String

Returns:

this to allow method chaining

getScrollTop

public final int getScrollTop()

Getter for property scrollTop Scrollbar position from the top. Setting the scrollTop property and calling scrollToIndex are two operations influencing the same "physical" property, so the last call "wins".

Returns:

the value of property scrollTop

setScrollTop

public final ListBox setScrollTop(int value)

Setter for property scrollTop
Default value is: -1

Parameters:

value - int

Returns:

this to allow method chaining

isDisplayIcons

public final boolean isDisplayIcons()

Getter for property displayIcons Defines whether the icons of the list items should also be displayed. Enabling icons causes some space to be reserved for them, regardless of how many of the items actually have icons assigned. Displaying icons can also influence the width and height of a single item, which affects the height of the ListBox when it is defined in number of items. In particular with differently-sized icons the total ListBox height will not accomodte exactly the given number of items, then.

Returns:

the value of property displayIcons

setDisplayIcons

public final ListBox setDisplayIcons(boolean value)

Setter for property displayIcons
Default value is: false

Parameters:

value - boolean

Returns:

this to allow method chaining

isDisplaySecondaryValues

public final boolean isDisplaySecondaryValues()

Getter for property displaySecondaryValues Indicates whether the additionalText property that can be set on sap.ui.core.ListItems shall be displayed, or not.

Returns:

the value of property displaySecondaryValues

setDisplaySecondaryValues

public final ListBox setDisplaySecondaryValues(boolean value)

Setter for property displaySecondaryValues
Default value is: false

Parameters:

value - boolean

Returns:

this to allow method chaining

getValueTextAlign

public final com.sap.ui.core.client.TextAlign getValueTextAlign()

Getter for property valueTextAlign The text alignment in the primary column of the ListBox.

Returns:

the value of property valueTextAlign

setValueTextAlign

public final ListBox setValueTextAlign(com.sap.ui.core.client.TextAlign value)

Setter for property valueTextAlign
Default value is: Begin

Parameters:

value - com.sap.ui.core.client.TextAlign

Returns:

this to allow method chaining

getSecondaryValueTextAlign

public final com.sap.ui.core.client.TextAlign getSecondaryValueTextAlign()

Getter for property secondaryValueTextAlign The text alignment in the secondary (optional) text column of the ListBox.

Returns:

the value of property secondaryValueTextAlign

setSecondaryValueTextAlign

public final ListBox setSecondaryValueTextAlign(com.sap.ui.core.client.TextAlign value)

Setter for property secondaryValueTextAlign
Default value is: Begin

Parameters:

value - com.sap.ui.core.client.TextAlign

Returns:

this to allow method chaining

getMinWidth

public final String getMinWidth()

Getter for property minWidth The minimum width of the ListBox. If not set, there is no minimum width.

Returns:

the value of property minWidth

setMinWidth

public final ListBox setMinWidth(String value)

Setter for property minWidth

Parameters:

value - String

Returns:

this to allow method chaining

getMaxWidth

public final String getMaxWidth()

Getter for property maxWidth The maximum width of the ListBox. If not set, there is no maximum width.

Returns:

the value of property maxWidth

setMaxWidth

public final ListBox setMaxWidth(String value)

Setter for property maxWidth

Parameters:

value - String

Returns:

this to allow method chaining

getVisibleItems

public final int getVisibleItems()

Getter for property visibleItems The control height in number of items to be completely displayed without scrolling. Setting this overwrites any height in terms of CSS size previously set. When items have different heights, the height of the first item is used for all calculations. If between the visible ListBox items there are one or more separators, the specified number of items will not exactly fit. If the value is retrieved it will equal the previously set value if it was set, otherwise it will be the number of items completely fitting into the ListBox without scrolling if the control was already rendered. If the control was not rendered, the behavior is undefined, it may return -1 or any other number.

Returns:

the value of property visibleItems

setVisibleItems

public final ListBox setVisibleItems(int value)

Setter for property visibleItems
Default value is:

Parameters:

value - int

Returns:

this to allow method chaining

getItems

public final com.sap.ui.core.client.js.JsArray<com.sap.ui.core.client.Item> getItems()

Getter for aggregation items Aggregation of items to be displayed. Must be either of type sap.ui.core.ListItem or sap.ui.core.SeparatorItem.

Returns:

com.sap.ui.core.client.Item[]

insertItem

public final ListBox insertItem(com.sap.ui.core.client.Item item,
                                int index)

Inserts some item into the aggregation named items.

Parameters:

item - the item to insert

index - int the 0-based index the item should be inserted at.

Returns:

this to allow method chaining

addItem

public final ListBox addItem(com.sap.ui.core.client.Item item)

Appends a item to the aggregation items.

Parameters:

item - com.sap.ui.core.client.Item the item to add

Returns:

this to allow method chaining

removeItem

public final com.sap.ui.core.client.js.JsArray<com.sap.ui.core.client.Item> removeItem(int index)

Removes a item from the aggregation named items.

Parameters:

index - int the position of the item to remove.

Returns:

reference to this instance

removeAllItems

public final com.sap.ui.core.client.js.JsArray<com.sap.ui.core.client.js.JsArray<com.sap.ui.core.client.Item>> removeAllItems()

Removes all the items in the items-aggregation.

Returns:

an array of the removed elements (might be empty)

indexOfItem

public final int indexOfItem(com.sap.ui.core.client.Item item)

Checks for the provided com.sap.ui.core.client.Item in the items-aggregation and returns its index if found or -1 otherwise.

Parameters:

item - the item whose index is looked for.

Returns:

the index of the provided control in the aggregation.

destroyItems

public final ListBox destroyItems()

Destroys all the items in the Items-aggregation.

Returns:

this to allow method chaining

attachSelectEvent

public final ListBox attachSelectEvent(com.sap.ui.core.client.event.EventListener listener)

attach an EventListener Event is fired when selection is changed by user interaction.

Event Parameters:

{string} id ID of the ListBox which triggered the event.

{int} selectedIndex The currently selected index of the ListBox. In case of multiselect this is ONE of the selected indices (the one whose selection has triggered the selection change); use "selectedIndices" to get all currently selected indices.

{sap.ui.core/Item} selectedItem The currently selected item of the ListBox. In case of multiselect this is ONE of the selected items (the one whose selection has triggered the selection change).

{int[]} selectedIndices Array containing the indices which are selected.

Parameters:

listener - reference to the EventListener

Returns:

this to allow method chaining

detachSelectEvent

public final ListBox detachSelectEvent(com.sap.ui.core.client.event.EventListener listener)

detach an EventListener Event is fired when selection is changed by user interaction.

Parameters:

listener - reference to the EventListener

Returns:

this to allow method chaining

getSelectedIndex

public final int getSelectedIndex()

Zero-based index of selected item. Index value for no selection is -1. When multi-selection is enabled and multiple items are selected, the method returns the first selected item.

setSelectedIndex

public final void setSelectedIndex(int index)

Sets the zero-based index of the currently selected item. This method removes any previous selections. When the given index is invalid, the call is ignored.

Parameters:

index - Index to be selected.

addSelectedIndex

public final void addSelectedIndex(int index)

Adds the given index to current selection. When multi-selection is disabled, this replaces the current selection. When the given index is invalid, the call is ignored.

Parameters:

index - Index to add to selection.

removeSelectedIndex

public final void removeSelectedIndex(int index)

Removes the given index from this selection. When the index is invalid or not selected, the call is ignored.

Parameters:

index - Index that shall be removed from selection.

getSelectedIndices

public final Integer[] getSelectedIndices()

Zero-based indices of selected items, wrapped in an array. An empty array means "no selection".

setSelectedIndices

public final void setSelectedIndices(Integer[] indices)

Zero-based indices of selected items, wrapped in an array. An empty array means "no selection". When multi-selection is disabled and multiple items are given, the selection is set to the index of the first valid index in the given array. Any invalid indices are ignored.

Parameters:

indices - Indices of the items to be selected.

addSelectedIndices

public final void addSelectedIndices(Integer[] indices)

Adds the given indices to selection. Any invalid indices are ignored.

Parameters:

indices - Indices of the items that shall additionally be selected.

isIndexSelected

public final boolean isIndexSelected(int index)

Returns whether the given index is selected.

Parameters:

index - Index which is checked for selection state.

getSelectedItem

public final com.sap.ui.core.client.Item getSelectedItem()

Returns selected item. When no item is selected, "null" is returned. When multi-selection is enabled and multiple items are selected, only the first selected item is returned.

getSelectedItems

public final com.sap.ui.core.client.js.JsArray<com.sap.ui.core.client.Item> getSelectedItems()

Returns an array containing the selected items. In the case of no selection, an empty array is returned.

clearSelection

public final void clearSelection()

Removes complete selection.

scrollToIndex

public final void scrollToIndex(int index,
                                boolean lazy)

If the ListBox has a scrollbar because the number of items is larger than the number of visible items, this method scrolls to the item with the given index. If there are enough items, this item will then appear at the topmost visible position in the ListBox. If bLazy is true, it only scrolls as far as required to make the item visible. Setting the scrollTop property and calling scrollToIndex are two operations influencing the same "physical" property, so the last call "wins".

Parameters:

index - The index to which the ListBox should scroll.

lazy - If set to true, the ListBox only scrolls if the item is not completely visible, and it scrolls just enough to make it fully visible. If set to false (and by default), the item is scrolled to the top position if possible.

setItems

public final ListBox setItems(com.sap.ui.core.client.js.JsArray<com.sap.ui.core.client.ListItem> items,
                              boolean destroyItems)

Allows setting the list items for this instance of ListBox as array.

Parameters:

items - The items to set for this ListBox.

destroyItems - Optional boolean parameter to indicate that the formerly set items should be destroyed instead of just removed. If omitted defaults to false, i.e. no not destroy.