Class

WebListBox

Description

A scrollable, multicolumn listbox control.

Events

Name

Parameters

Returns

Closed

ContextualMenuSelected

hitItem As WebMenuItem

CustomCellAction

row As Integer, column As Integer, identifier As Variant, value As Variant

DoublePressed

row As Integer

Error

error As RuntimeException

Hidden

Opening

Pressed

row As Integer, column As Integer

SelectionChanged

rows() As Integer

Shown

Enumerations

WebListBox.RowSelectionTypes

RowSelectionTypes

Indicates how many rows can be selected at a time.

Enum

Description

Multiple

Any number of rows can be selected.

None

No rows can be selected.

Single

Only one row at a time can be selected.

WebListBox.SortDirections

SortDirections

Indicates the various directions upon which rows can be sorted.

Enum

Description

Ascending

The rows will be sorted in A-Z order.

Descending

The rows will e sorted in Z-A order.

None

The rows will not be sorted.

WebListBox.SortTypes

SortTypes

Indicates whether or not the column can be sorted.

Enum

Description

Sortable

A widget appears in the column header allowing the user to sort the column.

Unsortable

The column cannot be sorted by the user, thus no sort widget appears in the column header.

Property descriptions

WebListBox.ColumnCount

ColumnCount As Integer

Gets or sets the number of columns in the ListBox. ColumnCount is 1-based.

Setting the number of columns to 2 in the Open event:

Me.ColumnCount = 2

Iterating through the rows and columns to set the cell values:

// Add 5 Rows
For i As Integer = 1 To 5
  ListBox1.AddRow("")
Next

For row As Integer = 0 To ListBox1.RowCount - 1
  For col As Integer = 0 To ListBox1.ColumnCount - 1
    ListBox1.CellTextAt(row, col) = row.ToString + "," + col.ToString
  Next
Next

WebListBox.ColumnWidths

ColumnWidths As String

A list of comma separated values, with each value controlling the width of the associated column. A value can be an absolute value (in pixels), a percentage, a relative length expressed as "i*" where i is an integer, or an "*" that indicates "fill in the remaining width". If you use percentages, you can use non-integer values to specify fractions of a percent, e.g., 43.52%. The percentage value can be greater than 100%.

If you use pixels, the last column doesn't grow to the size of the rest of the ListBox. You should set the width of the last column to "*" and it will automatically take up the remaining width of the ListBox.

Without any column width specifications, the headers will be divided evenly. If there are fewer column widths specified than the total number of columns, the remaining columns will divide up the remaining width equally.

The following creates two columns with 100 pixels per column:

Me.ColumnCount = 2
Me.ColumnWidths = "100,100"

The following uses the * to specify the last column's width:

Me.ColumnCount = 3
Me.ColumnWidths = "100,100,*"

WebListBox.ContextualMenu

ContextualMenu As WebMenuItem

If you assign a WebMenuItem to the control, it will be displayed when the user right-clicks the control.

On a WebPage, you can disable/remove the default contextual menu by an empty WebMenuItem class object to this property.

This code populates a contextual menu in the Shown event of the control.

Var menu As New WebMenuItem

menu.AddMenuItem("One")
menu.AddMenuItem("Two")
menu.AddMenuItem("Three")
Me.ContextualMenu = menu

The menu selection is then handled by the ContextualMenuSelected event when the user right-clicks on the control. For example, it can be of the form:

Select case hitItem.Value
Case "One"
  MessageBox("One")
Case "Two"
  MessageBox("Two")
Case "Three"
  MessageBox("Three")
End Select

WebListBox.ControlID

ControlID As String

Identifies the control on a per session basis.

This property is read-only.

WebListBox.DataSource

DataSource As WebDataSource

An optional data source to use to populate the list box.

WebListBox.Enabled

Enabled As Boolean

When True the WebControl is drawn enabled and responds to user action. When False, the control appears as disabled and does not respond to user actions.

In the case of WebTimer, when set to False this disables and stops the WebTimer. When set to True, it starts the WebTimer.

Disable a button when a check box value changes:

If AllowSaveCheckBox.Value Then
  SaveButton.Enabled = True
Else
  AllowSaveButton.Enabled = False
End If

WebListBox.HasHeader

HasHeader As Boolean

If True, the header row is displayed.

This property is False by default.

WebListBox.Height

Height As Integer

The height (in pixels) of the control.

WebListBox.HighlightSortedColumn

HighlightSortedColumn As Boolean

If True, the sorted column will be highlighted.

WebListBox.Indicator

Indicator As WebUIControl.Indicators

The color scheme for the control.

When a WebButton's Default or Cancel properties are True, the Indictor property is ignored as Default and Cancel buttons have a default indicator.

WebListBox.LastAddedRowIndex

LastAddedRowIndex As Integer

The index of the last row added with the AddRow or AddRowAt method.

This property is read-only.

WebListBox.LastRowIndex

LastRowIndex As Integer

The index of the last row in the WebListBox.

This property is read-only.

WebListBox.Left

Left As Integer

The position of the left side of the WebUIControl in pixels, relative to the web page.

WebListBox.LockBottom

LockBottom As Boolean

Determines whether the bottom edge of the control should stay at a set distance from the bottom edge of the parent control, if there is one, or the owning web page.

This property is read-only.

WebListBox.LockHorizontal

LockHorizontal As Boolean

LockHorizontal overrides LockLeft and LockRight. It allows you to proportionally lock a control's position to the center of its parent control (or web page).

This property is read-only.

For example, if you place a control in the center of the page and sets both LockHorizontal and LockVertical, the control will stay in the center of the page.

WebListBox.LockLeft

LockLeft As Boolean

Determines whether the left edge of the control should stay at a set distance from the left edge of the parent control, if there is one, or the owning web page.

This property is read-only.

WebListBox.LockRight

LockRight As Boolean

Determines whether the right edge of the control should stay at a set distance from the right edge of the parent control, if there is one, or the owning web page.

This property is read-only.

WebListBox.LockVertical

LockVertical As Boolean

LockVertical overrides LockTop and LockBottom. It allows you to proportionally lock a control's position to keep it centered within the parent control or web page.

This property is read-only.

For example, if you place a control in the center of the page, and sets both LockHorizontal and LockVertical, the control will stay in the center of the page.

WebListBox.Name

Name As String

The name of the control.

This property is read-only.

WebListBox.NoRowsMessage

NoRowsMessage As String

The text that appears when the WebListBox has no rows displayed.

WebListBox.Page

Page As WebPage

Identifies the web page that contains the control.

This property is read-only.

WebListBox.Parent

Parent As WebControl

Used to get the control's parent control or page. If the parent control is a WebContainer, then it returns the WebContainer. If it is on a WebPage, it returns the WebPage.

This property is read-only.

WebListBox.RowCount

RowCount As Integer

Returns the number of rows in the WebListBox, not including the header row.

This property is read-only.

This example loops through all the rows in the Listbox and clears the second column:

For row As Integer = 0 To WebListBox1.RowCount - 1
  WebListBox.CellTextAt(row, 1) = ""
Next

WebListBox.RowSelectionType

RowSelectionType As RowSelectionTypes

Dictates the type of row selection: none, single or multiple.

In this example, the RowSelectionType is set to multiple in the Opening event of the WebListBox:

Me.RowSelectionType = WebListBox.RowSelectionTypes.Multiple

WebListBox.SearchCriteria

SearchCriteria As String

Used to filter rows based upon the value assigned.

If this property is assigned a value, the WebListBox will perform a full-text search on all rows and columns. The contents of the WebListBox will be reduced to only those rows with a column value that matches the search criteria assigned to this property.

The keyword AND can be used to find rows that include multiple words. For example, Baggins AND Brandybuck will find rows that contain both words. It must be entered in all uppercase letters or it will be treated as a search value rather than as a keyword.

They keyword OR can be used to find rows that include any one of multiple words. For example, Baggins AND Brandybuck will find rows that contain either word. It must be entered in all uppercase letters or it will be treated as a search value rather than as a keyword.

The * symbol can be used to find rows with values that begin with a set of characters. For example, Bag* will find rows where a value begins with Bag.

Searching is case-insenstive.

Because the data in a WebListBox is stored in a SQLite Database behind the scenes, the full-text search is done by SQLite and thus you can use the full-text search filtering capabilities of SQLite.

Updating the WebListBox will automatically reindex the data unless you are using the WebListBox.DataSource in which case you will have to perform the queries yourself.

WebListBox.SelectedRowColor

SelectedRowColor As Color

The color used to draw the background of a row when selected.

From the Opening event, set the SelectedRowColor property to blue:

Me.SelectedRowColor = Color.Blue

WebListBox.SelectedRowIndex

SelectedRowIndex As Integer

The index of the selected row.

If no row is selected SelectedRowIndex will be -1. If multiple rows are selected, SelectedRowIndex will be the index of the first selected row.

If the RowSelectionType is Multiple, you can use the Selected method to determine which rows are selected.

WebListBox.Style

Style As WebStyle

The WebStyle for the control.

In the Pressed event of a WebButton, set the text to bold:

Var style As New WebStyle
style.Bold = True
Me.Style = style

WebListBox.TabIndex

TabIndex As Integer

The WebUIControl's control's position in the Tab Order. The control with a TabIndex of 0 is the first WebUIControl to get the focus when the page opens in the browser.

This example sets the control's TabIndex.

Me.TabIndex = 2

WebListBox.Tooltip

Tooltip As String

Text of a message displayed as a tooltip.

The tip is displayed when the user places the mouse on the control and leaves it there.

This code in the Shown event of a Button sets the tooltip:

Me.Tooltip = "Save changes"

WebListBox.Top

Top As Integer

The top of the control in local coordinates relative to the web page.

WebListBox.Visible

Visible As Boolean

If True, the control is drawn. If False, it's not.

Hide a control based on a checkbox setting:

If ShowEmailCheckbox.Value Then
  EmailField.Visible = True
Else
  EmailField.Visible = False
End If

WebListBox.Width

Width As Integer

The width (in pixels) of the web control.

This code in the Shown event handler increases the size of the control:

Me.Width = Me.Width + 50

Method descriptions

WebListBox.AddRow

AddRow(ParamArray data As String)

Adds a new row to the WebListBox.

The AddRow method allows you to pass in multiple strings as separate parameters. Each parameter will be placed into the its corresponding column in the new row starting with the first column.

Adds a new row to the Listbox, not populate it with any values:

ListBox1.AddRow("")

Adds a new row to the Listbox, populating the first column:

ListBox1.AddRow("Hello")

Adds a new row and populates the three columns in a three-column Listbox:

ListBox1.AddRow("Col1", "Col2", "Col3")

WebListBox.AddRowAt

AddRowAt(index As Integer, ParamArray items() As String)

Creates a new row at the index passed, filling the columns with the items passed.

This example inserts a row at index 4 into a WebListBox and populates columns 0 and 1:

Listbox1.AddRowAt(4, "Trixie", "10")

WebListBox.CellTagAt

CellTagAt(row As Integer, column As Integer) As Variant

Allows you to get or set the Variant value associated with the cell at the row and column passed.

Passing an index that is outside the bounds of the rows and/or columns will result in an OutOfBoundsException.

WebListBox.CellTextAt

CellTextAt(row As Integer, column As Integer) As String

Allows you to get or set the value associated with the cell at the row and column passed.

This example sets the cell value at row 0, column 0 to "Trixie":

ListBox1.CellTextAt(0, 0) = "Trixie"

CellTextAt(row As Integer, column As Integer) As Variant

Allows you to get or set the WebListBoxCellRenderer to used to render custom a custom cell at the row and column passed.

Passing an index that is outside the bounds of the rows and/or columns will result in an OutOfBoundsException.

This example, called from the Opening event of a WebListBox, sets the cell value at row 0, column 2 to an instance of ButtonColumn which is a subclass of WebListBoxCellRenderer:

Me.CellTextAt(0,2) = New ButtonColumn("Edit", "Delete")

WebListBox.Close

Close

Removes the control from the page.

WebListBox.ColumnSortDirectionAt

ColumnSortDirectionAt(index As Integer) As WebListBox

Allows you to get or set the direction by which the rows will be sorted for the column specified.

This example sets the sort direction of column 0 to ascending:

ListBox1.ColumnSortDirectionAt(0) = WebListBox.SortDirections.Ascending

WebListBox.ColumnSortTypeAt

ColumnSortTypeAt(index As Integer) As WebListBox

Dictates whether or not the column indicated is sortable.

This example makes the first column sortable.

ListBox1.ColumnSortTypeAt(0) = WebListBox.SortTypes.Sortable

WebListBox.ExecuteJavaScript

ExecuteJavaScript(script As String)

Executes the JavaScript passed. The JavaScript passed can call a JavaScript function in a WebPageSource control.

The Xojo web framework uses EcmaScript 6 which is more strict than previous versions of JavaScript. For more details, see the EcmaScript 6 documentation.

This code in the Pressed event of a Button displays an alert using JavaScript:

Me.ExecuteJavaScript("alert('Hello!');")

This code will select the text in a WebTextField (or WebTextArea):

WebTextField1.ExecuteJavascript("document.getElementById('" + _
  WebTextField1.ControlID + "_inner').select();")

WebListBox.GotoURL

GotoURL(URL As String, inNewWindow As Boolean = False)

Opens the passed URL in place of the current web page or downloads a file. If InNewWindow is True, the browser is asked to open the URL in a new window.

If the browser has popup windows disabled and InNewWindow is True, the method silently fails and the page is not shown.

If InNewWindow is False, the running web app is replaced with the specified URL. If you want to display an external web site within your web app, use the WebHTMLViewer control.

Display a web site in a new popup window:

Me.GotoURL("http://www.wikipedia.org", True)

WebListBox.HeaderAt

HeaderAt(index As Integer) As String

Used to get and set the header at the Index passed.

WebListBox.ReloadData

ReloadData

Reloads the data into the WebListBox.

This is useful with the data in the WebListBox comes from a WebDataSource and that data has changed since it was last loaded into the WebListBox.

WebListBox.RemoveAllRows

RemoveAllRows

Removes all rows from the WebListBox.

WebListBox.RemoveRowAt

RemoveRowAt(index As Integer)

Removes the row at the Row passed.

WebListBox.RowTagAt

RowTagAt(index As Integer)

Allows you to set the Variant value associated with the row at the Index passed.

Passing an index that is outside the bounds of the rows and/or columns will result in an OutOfBoundsException.

This example sets the row tag at row 0, to the object Employee, an instance of a class:

ListBox1.RowTagAt(0) = Employee

WebListBox.ScrollTo

ScrollTo(rowIndex As Integer)

Scrolls the ListBox to the specified rowIndex position.

Warning

If rowIndex is greater than the last row in the ListBox (WebListBox.LastRowIndex), an OutOfBoundsException will occur.

This example scrolls to the last row of the ListBox:

ListBox1.Scrollto(ListBox1.LastRowIndex)

WebListBox.Selected

Selected(row As Integer) As Boolean

Used to set the selected value of a row.

WebListBox.Selected

Selected(row As Integer, Assigns selected As Boolean)

Used to set the selected value of a row.

The following tests whether the first row is selected.

If ListBox1.Selected(0) Then
  MessageBox("Selected")
Else
  MessageBox("Not Selected")
End If

WebListBox.SelectedRowCount

SelectedRowCount As Integer

The number of rows selected (highlighted) in the WebListBox.

WebListBox.SelectedRowValue

SelectedRowValue As String

Allows you to get value of the selected row.

Only the value in column 0 is returned.

WebListBox.SetFocus

SetFocus

Sets the focus to the Control.

This code checks for a required value when a button is pressed:

If UserNameField.Value = "" Then
  MessageBox("Please enter your UserName.")
  UserNameField.SetFocus
  Return
End If

WebListBox.UpdateBrowser

UpdateBrowser

Forces the current values of the control to be sent to the browser.

This method is useful when you are computing values in a loop and wish to update the browser immediately rather than wait until the current method ends.

This code iterates through a RowSet of database rows, updates a ProgressBar and then forces the updated ProgressBar to be sent to the browser via UpdateBrowser.

ProgressBar1.Maximum = SalesData.RowCount
For Each row As DatabaseRow in SalesData
 AnalyzeSales(row)
 ProgressBar1.Value = ProgressBar1.Value + 1
 ProgressBar1.UpdateBrowser
Next

Event descriptions

WebListBox.Closed

Closed

The control has been removed from the browser either because the page has closed or the control's Close method was called.

WebListBox.ContextualMenuSelected

ContextualMenuSelected(hitItem As WebMenuItem)

Called when a contextual menu item is selected. This selected item is contained in hitItem.

This code populates a contextual menu in the Opening event of a WebToolbar:

Var menu As New WebMenuItem

menu.AddMenuItem("One")
menu.AddMenuItem("Two")
menu.AddMenuItem("Three")
Me.ContextualMenu = menu

The menu selection is then handled by the ContextualMenuSelected event when the user right-clicks on the control. For example, it can be of the form:

Select case hitItem.Value
Case "One"
  MessageBox("One")
Case "Two"
  MessageBox("Two")
Case "Three"
  MessageBox("Three")
End Select

WebListBox.CustomCellAction

CustomCellAction(row As Integer, column As Integer, Identifier As Variant, Value As Variant)

The user has taken some action in a cell with a WebListBoxCellRenderer assigned to it that triggers this event.

The Identifier parameter is an arbitrary value assigned by the subclass of WebListBoxCellRenderer that is assigned to the cell. The purpose of the Identifier is to allow the developer to know what action the user took so that the code in this event can respond to it. For example, if the WebListBoxCellRenderer added two buttons, the Identifier could be set to the caption of the button that was pressed.

WebListBox.DoublePressed

DoublePressed(row As Integer)

The user has double-clicked or double-tapped on a row.

WebListBox.Error

Error(error As RuntimeException)

An exception has occurred.

WebListBox.Hidden

Hidden

The control is about to become no longer visible. This could be because the page is being closed, is being replaced as the foreground page by another page or because the control or a parent control's Visible property has been set to False.

Note

This event is equivalent to the DesktopWindow.Deactivated event in a desktop app.

WebListBox.Opening

Opening

The control has been created and the page is opening but has not been sent to the browser yet.

The Opening event handler can be used to initialize non-visual properties and settings for controls.

In most cases, you should use the Shown event to initialize controls.

WebListBox.Pressed

Pressed(row As Integer, column As Integer)

The user pressed (clicked or tapped) on the cell indicated by the parameters.

WebListBox.SelectionChanged

SelectionChanged(rows() As Integer)

The selection of rows has changed.

SelectionChanged is called in the following situations:

  • When the WebListBox is clicked to give it the focus

  • When a cell is clicked even if it already is selected

  • When a row is clicked to change the selection

  • When the selected row is removed

Clicking on a header does not call the SelectionChanged event.

Display data from the selected row in a TextField so it can be edited:

If Me.SelectedRowIndex >= 0 Then
  Var lastName As String
  lastName = Me.SelectedRowValue // Gets the first column

  LastNameField.Value = lastName
End If

WebListBox.Shown

Shown

The control has appeared on the currently displayed page. This could be because its parent page just finished loading, its parent page has come to the foreground or the control is now visible having been previously invisible because it or its parent control's Visible property has been set to True.

Use the Shown event for initializing your controls or doing anything that would interact with other controls or user interface elements on the web page instead of the Opening event.

Note

This event is the web equivalent to the DesktopWindow.Activated event.

This code in the Shown event of a WebListBox adds 2 rows with 3 columns:

Me.RemoveAllRows
Me.AddRow("Row 1", "Bob", "Roberts")
Me.AddRow("Row 2", "Barb", "Reynolds")

This example sets the text of a label:

If Session.LoggedIn Then
  Me.Value = "Welcome!"
Else
  Me.Value = "Welcome, " + Session.UserName
End If

Notes

To load rows dynamically, see the WebDataSource class.

To control the drawing style of individual cells, use WebListBoxStyleRenderer.

To draw pictures in a cell, use WebListBoxImageRenderer.

To display DateTime values in the user's time zone and locale, use WebListBoxDateTimeRenderer.

Sample code

This example adds 100 rows to a 5-column listbox:

For row As Integer = 1 To 100
  Listbox1.AddRow("Col1", "Col2", "Col3", "Col4", "Col5")
Next

Compatibility

Web projects on all supported operating systems.

See also

WebUIControl parent class; WebDataSource class.