The ListElement and Listbox classes enable you (and HAHTsite) to create list boxes that contain particular sets of list entries, or elements. An object of the Listbox class represents the list box itself, and each entry in the list is an object of type ListElement.
Note - List elements can also be added to combo boxes since Combo is a subclass of Listbox.
There are three possible types of list elements:
• Design-time list elements. HAHTsite creates design-time list elements when you use the IDE to create a list box and add list items to the list. For each list item, HAHTsite instantiates a list element with a type property whose value is STATIC_ELEMENT.
• Populater list elements. If you design a page so that a data agent is used to populate a list box or combo box, for each list item, HAHTsite instantiates a list element of type POPULATER_ELEMENT.
• Runtime list elements. These are elements — of type PAGE_RUN_ELEMENT — that you add to a list box or combo box by making calls to
ListElement and Listbox methods.
Any list box can contain any combination of these three types of elements. For information about creating list elements and working with list boxes, see the following sections:
• “Creating list elements” on page 169
• “Getting and setting ListElement properties” on page 171 • “Adding list elements to a list” on page 171
• “Selecting an element in a list” on page 172 • “Finding an item in a list” on page 173
• “Getting and setting Listbox properties” on page 173
List box List element
• An internal value. This is the value of the list box when the form containing the list box is submitted with a particular display value selected. Each display value has a corresponding internal value.
• A selected status. If a list element's selected status is set to true, the list element will be highlighted when the list box is displayed.
• An element type (or creation type). This type indicates whether the element was created at design time, by a populater, or by user-written code. The following constants represent these three types:
STATIC_ELEMENT, POPULATER_ELEMENT, and PAGE_RUN_ELEMENT. HAHTsite uses this type to determine when to remove elements from a list. Design-time elements are never removed; populater elements are removed each time the list box is populated; and page-run elements are removed each time the page is run.
To create a list element, you call one of the ListElement class's constructors. ListElement(String aDisplayVal)
ListElement(String aDisplayVal, String anInternalVal, boolean aSelOnOff, int aCreateFlag)
If you use the first form of the constructor, HAHTsite sets the list element's internal value to the empty string, its selection flag to false, and its type to STATIC_ELEMENT.
The code fragments below illustrate how to instantiate a list element in both Java and HAHTtalk Basic.
In this case, the list element’s display value is “Jane Doe,” its internal value is Jane’s employee number 12345, and the element will not be highlighted by default.
Java
ListElement element1 = new ListElement("JaneDoe", "12345", false, PAGE_RUN_ELEMENT);
HAHTtalk Basic
Dim element1 As Object
Set element1 = CreateJavaObject("ListElement", "Jane Doe", _ "12345", False, PAGE_RUN_ELEMENT)
Note - It's also possible to create a list element and insert that element into a list in a single step. For information on how to do this, see “Adding list elements to a list” on page 171. Getting and setting ListElement properties
Once you've created a ListElement, you can read or set the properties of this object using the methods listed in the table below.
Adding list elements to a list
This section covers how to insert list elements into a list box and how to remove them.
You have three options when you insert a list element (or elements) into a list box. You can:
Method Description
setCreateFlag Indicates whether this list element was created at design time, by a populater (a data agent), or by user code. In your code, you’ll want to set this flag to
PAGE_RUN_ELEMENT to indicate that you’re adding this item to the list at runtime.
setDisplayValue Sets a list element’s display value, the value that will be shown in the list box.
setInternalValue Sets a list element’s internal value. This value will be the list box’s value when the form is submitted.
setSelected Sets the list element’s selected flag, to determine whether the list element will be highlighted when the list box is displayed.
getCreateFlag Reads the list element’s element type: STATIC_ELEMENT, PAGE_RUN_ELEMENT, or POPULATER_ELEMENT.
getDisplayValue Reads the list element’s display value. getInternalValue Reads the list element’s internal value.
The prototypes for the methods that perform these tasks are shown below: int insertElementAt(ListElement anElement, int index)
int insertElementAt(String aDisplayVal, String an InternalVal, boolean aSelOnOff, int aCreateFlag, int index)
void insertElementAt(Vector aList, int index)
For each method, the index parameter indicates the point in the list at which the new element(s) should be added. For example, if you specify an index of 3, the new element will become the third item in the list box's list.
Note - You can replace an existing list item using the method setElementAt. (This method’s counterpart, getElementAt, returns the ListElement object at a particular index.)
To remove an item from a list box, use one of the methods shown in the table below.
Selecting an element in a list
Using methods of the Listbox class, you can specify:
• Whether the user can select only one value from the list box before submitting the form containing the list box, or whether the user can select several values.
• Which list element or elements (if any) should be highlighted (selected) when the list box is first displayed.
A Listbox object contains a member variable that determines whether multiple selections are allowed. You can read the value of this variable using the method isMultiple, and you can set the value using the method setMultiple. If the variable is set to true, multiple selections are allowed.
Note - One difference between list boxes and combo boxes is that combo boxes do not allow multiple selections.
To indicate that a list item should be selected — or deselected — when the list box is displayed, use one of the methods listed in the table below.
Method Description
removeAllElements Removes all of a list box’s list items.
removeElementAt Removes the list item at a particular index into the list. removeElements Removes all list items of a particular type:
STATIC_ELEMENT, PAGE_RUN_ELEMENT, or POPULATER_ELEMENT.
Finding an item in a list
The Listbox class contains several methods that enable you to determine the current location (index) of a list element within a list box. These methods are shown in the table below.
Getting and setting Listbox properties
The Listbox class also contains accessor methods that enable you to get or set a number of properties of the list box or of a list element contained in the list box. See the table below.
Method Description
selectIfDisplayValueIs Clears the existing selection, and then selects all of the items in the list whose display value matches a value you supply.
selectIfInternalValueIs Clears the existing selection, and then selects all of the items in the list whose internal value matches a value you supply.
selectItem Selects the item at the position you indicate. If this is a single-select list box, all other items are deselected.
deSelectAll Deselects all of the elements in the list.
deSelectItem Deselects the element at the position indicated by an index.
Method Description
findDisplayValue Finds an element with a display value equal to a value you supply. The comparison ignores case. findInternalValue Finds an element with an internal value equal to a
value you supply. The comparison ignores case. getSelected Finds the first selected item that follows an index
Method Description
setInsertPopulaterElementsFirst Moves any list elements of type POPULATER_ELEMENT to the beginning of the list. By default, such entries are placed at the end of the list.
setMultiple Sets or clears the HTML attribute multiple for this list box. This attribute controls whether or not multiple selections are allowed in the list box.
setSize Sets the HTML size attribute. The size attribute controls the number of elements that will be visible when the list box is displayed in the browser. getDisplayValue Returns the display value of the list
element at the index you supply. getElementCount Returns the number of list elements in
the list.
getInsertPopulaterElementsFirst Indicates whether list elements of type POPULATER_ELEMENT will be displayed in the list box first or last.
getInternalValue Returns the internal value of the list element at the index you supply. isMultiple Returns true if the multiple attribute
is set for this list box; otherwise, it returns false.
isSelected Returns true if the list element at the index you specify is selected. Returns false if the item is not selected or doesn't exist.
getSize Returns the value of the list box’s size (HTML) attribute. The size attribute controls the number of elements that will be visible when the list box is displayed in the browser.