List Box

A set of choices from which a user can select one items. If the number of text lines exceeds the control size, a vertical scrollbar is activated. An item in the listBox is called listBoxItem. ListBoxItems are explained above - after the dropdownListBox description. The listBox control can be for client side eventing. See the EventValidationComponent description for more details.

enabled - inherited from EventValidationComponent.
A boolean value that defines if the listBox is click able. If the listBox is disabled (enabled = false) it is not selectable. A disabled listBox has a different color for the displayed listBoxItem.
id
Identification name of the listBox.
jsObjectNeeded - inherited from Component.
A boolean value that defines if a JavaScript object has to be generated for the listBox component.
labeled
Enables or disables the notification when the control has a label assigned to it.
model
Defines the model which provides the listBox with data. How to work with the IListModel.
nameOfKeyColumn
Specifies the name of the column that contains the key. This is used when you use an underlying table in the model.
nameOfValueColumn
Specifies the name of the column that contains the visible text. This is used when you use an underlying table in the model.
onClientSelect
Defines the JavaScript fragment that is executed when the user clicks on the dropdownListbox. If both events ('onSelect' and 'onClientSelect') are specified, the 'onClientSelect' event handling method is activated first. By default the 'onSelect' event handling method is activated afterwards. In the JavaScript fragment you can cancel the activation of the 'onSelect' event handling method with the command

htmlbevent.cancelSubmit=true;

The 'onClientSelect' event is useful to pre process the form and only send the form to client if the preprocessing was successful (for example, date validation, valid number format etc.) to save client/server interaction.

Example
A listbox click usually activates the client/server interaction. If an input field has to be filled out for further processing, the JavaScript fragment can check the necessary input on the client side and display a message if the necessary input is missing, without server interaction.

End of the example.

Note

To use JavaScript the JSP has to use the page tag (see page tag).

End of the note.
onSelect
Defines the event handling method that will be processed when the user clicks on the enabled listBox. If you do not define a 'onSelect' event the listBox can be clicked but no event is generated.
selection
Specifies the key of the listBoxItem which is displayed in the listBox.
size
Sets the number of lines displayed for the listBox. If the number of text lines for listBox is higher then the size attribute a vertical scrollbar is activated - the width of the listBox is not changed, the text display window becomes smaller.
tooltip
Defines the hint of the listBox which is displayed as the mouse cursor passes over the listBox, or as the mouse button is pressed but not released.
width
Defines the width of the listBox. Text lines are truncated if the length of the string extends the width.

Attributes	M	Values	Usage
enabled		FALSE TRUE (d)	Taglib `disabled="TRUE"` Classlib `setEnabled(false)`
id	*	String (cs)	Taglib `id="listbox_te"` Classlib `setId("listbox_te")`
jsObjectNeeded		FALSE (d) TRUE	Taglib `jsObjectNeeded="TRUE"` Classlib `setJsObjectNeeded(true)`
labeled		FALSE (d) TRUE	Taglib `jsObjectNeeded="TRUE"` Classlib `setJsObjectNeeded(true)`
model		String (cs)	Taglib `model="`myBean.model`"` Classlib `setModel((`IListModel`) model)`
nameOfKeyColumn		String (cs)	Taglib `nameOfKeyColumn="k1"` Classlib `setNameOfKeyColumn("k1")`
nameOfValueColumn		String (cs)	Taglib `nameOfValueColumn="v1"` Classlib `setNameOfValueColumn("v1")`
selection		String (cs)	Taglib `selection="HD"` Classlib `setSelection("HD")`
size		Numeric (4)	Taglib `size="10"` Classlib `setSize("10")`
tooltip		String	Taglib `tooltip="select an item"` Classlib `setTooltip("select an item")`
width		Unit (max. item length)	Taglib `width="100"` Classlib `setWidth("100")`

* Method is inherited from the EventValidationComponent component. Therefor the attribute is different between the taglib and the classlib.

** Method is inherited from the Component component.

See the JavaScript API description for details how to access the component in JavaScript.

Events	M	Values	Usage
onClientSelect		String (cs)	Taglib `onClientSelect="alert('Click')"` Classlib `setOnClientSelect("alert('Click')")`
onSelect		String (cs)	Taglib `onSelect="proc_listbox"` Classlib `setOnSelect("proc_listbox")`

Events

Values

Usage

onClientSelect

String (cs)

Taglib

onClientSelect="alert('Click')"

Classlib

setOnClientSelect("alert('Click')")

onSelect

String (cs)

Taglib

onSelect="proc_listbox"

Classlib

setOnSelect("proc_listbox")

To define items in the list box without a model, see listBoxItem.

Example

using the taglib

Syntax Syntax

 <hbj:listBox 
    id="LB_CitiesNearby"
    tooltip="Cities surounding SAP"
    selection="WD"
    disabled="false"
    nameOfKeyColumn="KeyCol"
    nameOfValueColumn="KeyVal"
    onSelect="ProcessCity"
    onClientSelect="PreprocessCity"
    >
    <hbj:listBoxItem 
        key="HD"
        value="Heidelberg"
        selected="true"
        />
    <hbj:listBoxItem 
        key="HK"
        value="Hockenheim"
        />
    <hbj:listBoxItem 
        key="WD"
        value="Walldorf"
        selected="true"
        />
    <hbj:listBoxItem 
        key="WL"
        value="Wiesloch"
        />
 </hbj:listBox>

End of the code.

using the classlib

Syntax Syntax

    Form form = (Form) this.getForm();
    ListBox lb = new ListBox("LB_CitiesNearby");
    lb.setTooltip("Cities surounding SAP");
    lb.setWidth("300");
    lb.addItem("HD", "Heidelberg");
    lb.addItem("HK", "Hockenheim");
    lb.addItem("WD", "Walldorf");
    lb.addItem("WL", "Wiesloch");
    lb.setOnSelect("ProcessCity");
    lb.setOnClientSelect("PreprocessCity");
    lb.setTooltip("Cities nearby");
    lb.addSelection("WD");
    lb.addSelection("HD");
    form.addComponent(lb);

End of the code.

Result

This graphic is explained in the accompanying text.