---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`.
This property is read-only.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.Left
**Left** As `Integer`
The left side of the control in local coordinates (relative to the window).
The following example moves the control 100 points from the left side of the window:
``` xojo
Me.Left = 150
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.List
**List** As `String`
The list of items. List takes one parameter, the row index. The first row is numbered zero. Use it to get or set the contents of that cell, or, in multi-column ListBoxes, the contents of the first column.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.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 window.
This property can be set in the control's Inspector. The following example sets it in code.
``` xojo
Me.LockBottom = True
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.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 window.
Beginning with version 2009r5, LockLeft and Locktop default to `True` when you add a new control to a window. Existing controls will be altered only if LockRight and/or LockBottom are not set. *LockLeft* has no effect unless *LockRight* is `True`.
This property can be set in the control's Inspector. The following example sets it in code.
``` xojo
Me.LockLeft = True
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.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 window.
This property can be set in the control's Inspector. The following example sets it in code.
``` xojo
Me.LockRight = True
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.LockTop
**LockTop** As `Boolean`
Determines whether the top edge of the control should stay at a set distance from the top edge of the parent control, if there is one, or the owning window.
Beginning with version 2009r5, LockTop and LockLeft default to `True` when you add a control to a window. Existing controls will be altered only if LockRight and/or LockBottom are not set. *LockTop* has no effect unless *LockBottom* is `True`.
This property can be set in the control's Inspector. The following example sets it in code.
``` xojo
Me.LockTop = True
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.MouseCursor
**MouseCursor** As `MouseCursor`
The cursor to be displayed while the mouse is within the control and both the `DesktopApplication` and `Window` class's MouseCursor properties are `Nil`.
If the `DesktopApplication` class's MouseCursor property is not `Nil` or the `Window`'s MouseCursor property is not `Nil`, then any control's MouseCursor property is ignored. You can use a cursor stored in the `Cursors` module. On Macintosh, you can also obtain a `MouseCursor` from a resource file.
This line in the Open event of the control sets the default cursor to the finger pointer.
``` xojo
Me.MouseCursor = System.Cursors.FingerPointer
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.MouseX
**MouseX** As `Integer`
The X coordinate of the mouse (points). Measured from the top-left corner of the control.
This property is read-only.
This code is in the MouseDown event of a `TextField` and displays the X-coordinate at the point of the MouseDown event.
``` xojo
Me.Value = Str(Me.MouseX)
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.MouseY
**MouseY** As `Integer`
The Y coordinate of the mouse (points). Measured from the top-left corner of the control.
This property is read-only.
This code is in the MouseDown event of a `TextField` and displays the Y-coordinate at the point of the MouseDown event.
``` xojo
Me.Value = Str(Me.MouseY)
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.Name
**Name** As `String`
The name of the control. Set the name of the control in the Inspector.
This property is read-only.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.PanelIndex
**PanelIndex** As `Integer`
If the control has been placed on a `TabPanel` or `PagePanel` control, this is the panel (page/tab) that the control is on. If the control is not on a panel, it returns -1.
The first panel is numbered zero. If the control has been placed on a panel of a `TabPanel` or `PagePanel` control, it returns the panel number. If the control is not on a `PagePanel` or `TabPanel`, it returns -1. If you change the PanelIndex to a nonexistent panel, the control will disappear until you give it a PanelIndex value that corresponds to a panel that exists.
If you are looking to change the currently selected panel (page/tab), use `PagePanel`.
This code displays the panel index of the control that is on the page.
``` xojo
Label3.Value = Str(Me.PanelIndex)
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.Parent
**Parent** As `Control`
Used to get and set the control's parent control or window.
Returns `Nil` if the parent is the window. Assign `Nil` to make the control's parent the window, even if it is enclosed by another control. The child control's behavior in the IDE will reflect the parent's state. If the parent control is somehow in another window, an `InvalidParentException` will occur.
The following example sets the parent of the control to the window.
``` xojo
Me.Parent = Nil
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.RequiresSelection
**RequiresSelection** As `Boolean`
If `True`, users will not be able to deselect the last row by clicking below the last visible row or by dragging. You can still deselect the last row by setting the SelectedRowIndex property to ListBox.NoSelection.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.RowCount
**RowCount** As `Integer`
The number of rows in the ListBox.
This property is read-only.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.RowHeight
**RowHeight** As `Integer`
Gets the ListBox row height. All rows in a ListBox are always the same height, which you can change using `DefaultRowHeight`.
This property is read-only.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.RowSelectionType
**RowSelectionType** As `Integer`
Indicates the type of row selection allowed via mouse gestures.
The type of allowed row selection is set via `ListBox`.
The default is single-row selection. If multiple row selection is on, a ListBox will handle Edit \> Select All menu item commands by default as long as the Select All menu item is named **EditSelectAll**.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.Scope
**Scope** As `Integer`
Used to determine whether access to the control is Public (0) or Private (2). The default is Public.
This property is read-only.
If the Scope of a control is set to Private, it cannot be accessed from outside its parent window.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.ScrollPosition
**ScrollPosition** As `Integer`
Zero-based index of the top visible row in the ListBox.
Read ScrollPosition to determine the top visible row; write to ScrollPosition to scroll the ListBox. When the scrollbar thumb is scrolled to the bottom, ScrollPosition cannot be incremented any further.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.ScrollPositionX
**ScrollPositionX** As `Integer`
Zero-based index of the horizontal position of the ListBox.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.Selected
**Selected** As `Boolean`
Gets or sets the selection status of the passed *Row*. *Row* is zero-based.
Selected is `True` if the row passed is selected. This property can be used to determine if the row is selected and to select the row. For example,
``` xojo
Listbox1.Selected(1) = True //selects the second item in the first column.
```
In order to select multiple row, the `SelectionType` must be set to Multiple. This code selects only the even-numbered rows:
``` xojo
ListBox1.ListIndex = -1 ' Deselect all rows
For i As Integer = 0 To ListBox1.LastRowIndex
If i Mod 2 = 0 Then
ListBox1.Selected(i) = True
End If
Next
```
If you allow the ListBox to have multiple items selected (see `SelectionType`), you may want to establish a list of all the rows selected. The following example shows how to achieve that. The ListBox is named *ListBox1*.
``` xojo
Var selectedRows() As Integer ' Will hold the index of each selected row
For row As Integer = 0 To ListBox1.LastRowIndex
If ListBox1.Selected(row) Then
selectedRows.AddRow(row) ' This row is selected
End If
Next
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.SelectedRowCount
**SelectedRowCount** As `Integer`
The number of rows selected (highlighted).
This property is read-only.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.SelectedRowIndex
**SelectedRowIndex** As `Integer`
The number of the selected row.
If no item is selected, SelectedRowIndex returns ListBox.NoSelection. If the ListBox is in multiple-row selection mode, then the number of the lowest selected row is returned. For example, if rows 1, 3, and 4 are selected, SelectedRowIndex returns 1.
You can put the ListBox into multiple-row selection mode by changing the `RowSelectionType` property.
The following code in the `Change` event handler displays the text in the first column of the selected row:
``` xojo
If Me.SelectedRowIndex >= 0 Then
MessageBox(Me.CellValueAt(Me.SelectedRowIndex, 0))
End If
```
The following code displays a message if no row is selected:
``` xojo
If ListBox1.SelectedRowIndex = ListBox.NoSelection Then
MessageBox("Please select a row first.")
End If
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.SelectedRowValue
**SelectedRowValue** As `String`
The value of the currently selected item.
In the case of multi-column ListBoxes, the value of the cell in the first column is returned.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.SortingColumn
**SortingColumn** As `Integer`
Gets or sets the current sort column but doesn't do the sort. The first column is numbered zero. If no column is sorted then it returns -1. Call the `Sort` method to sort the ListBox based on the values of SortingColumn and `ColumnSortDirectionAt`.
The following code in the Pressed event of a Pushbutton asks the user to sort on a column if the ListBox is not sorted by any column:
``` xojo
If Listbox1.SortingColumn = ListBox.None then
System.Beep
MessageBox("Please sort the rows by one of the columns.")
End If
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.TabIndex
**TabIndex** As `Integer`
The **RectControl's** position in the Tab Order. It is 0-based. A TabIndex of 0 is the first **RectControl** to get the focus.
On the Mac you need Full Keyboard Access turned on in System Preferences (Keyboard-\>Shortcuts) in order to manually set focus to non-text controls.
This example sets the control's TabIndex.
``` xojo
Me.TabIndex = 2
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.Tooltip
**Tooltip** As `String`
Text of help message displayed as a Windows or Linux "tooltip" or macOS help tag.
The tip/tag is displayed when the user hovers the mouse cursor over the control.
This example adds a tooltip to a `BevelButton` that has an icon.
``` xojo
Me.CaptionAlignment = 0 ' left
Me.CaptionDelta = 10
Me.Tooltip = "Click to bark."
Me.Icon = Woof ' added to the project
Me.CaptionPosition = 2
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.Top
**Top** As `Integer`
The top of the control in local coordinates (relative to the window).
This example sets the top of the control to 140 points from the top of the window:
``` xojo
Me.Top = 140
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.Transparent
**Transparent** As `Boolean`
Determines whether the control is transparent on Windows. The default is `False`. Has no effect on macOS or Linux.
Transparent controls draw more slowly and use more memory in order to cache the background. Unless you absolutely require transparency, leave this set to False.
For projects that were created prior to 2018r1, this property defaults to True to emulate previous behavior. Consider changing it to False to improve performance if you do not require transparency.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.TrueWindow
**TrueWindow** As `Window`
Returns a reference to the actual enclosing `Window`.
This property is read-only.
TrueWindow walks up the window hierarchy and finds the actual enclosing window regardless of how deeply nested the `RectControl` or `DesktopContainer` hierarchy is.
`Window` also has a TrueWindow property.
This example accesses the TrueWindow and displays its Title property in a `TextField`.
``` xojo
TextField1.Text = Me.TrueWindow.Title
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.Underline
**Underline** As `Boolean`
If `True`, applies the underline style to the control's caption and/or its text content if any.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.Visible
**Visible** As `Boolean`
Determines whether the control is visible when its owning window is opened. The default is `True`: the control is visible.
The following code in the DisclosureTriangle Action event handler displays or hides a ListBox on the window:
``` xojo
ListBox1.Value = Me.Visible
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.Width
**Width** As `Integer`
The width (in points) of the control.
The following example resizes the control:
``` xojo
Me.Width = 200
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.Window
**Window** As `Window`
The control's parent window.
This property is read-only.
This code gets the parent window's Title property.
``` xojo
TextField1.Text = Me.Window.Title
```
## Method descriptions
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.AcceptFileDrop
**AcceptFileDrop**(FileType As `String`)
Permits documents of type *FileType* to be dropped on the control. *FileType* must be a file type that you defined in via the `FileType` class or the File Type Sets Editor.
This code in the Open event of an `ImageWell` makes it possible for the user to drop either a picture or a file that is a jpeg image. The File Type Sets editor was used to define the “image/jpeg” file type. It is one of the “Common File Types” that is available in the editor.
``` xojo
Me.AcceptPictureDrop
Me.AcceptFileDrop("image/jpeg")
```
To restrict file drops to just folders (and not files), you can put this code in the `DragEnter` event:
``` xojo
If Not obj.FolderItem.IsFolder Then Return True
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.AcceptPictureDrop
**AcceptPictureDrop**
Permits pictures to be dropped on the control.
If a control should accept pictures in a drag and drop, then AcceptPictureDrop needs to be called prior to the drop. Typically, it is in the Open event of the control itself. For example, the line:
``` xojo
Me.AcceptPictureDrop
```
in the Open event of the control that will receive the dragged pictures is needed. When the picture is dropped, the `DropObject` event is called and this is where you will put your code to handle the drop.
Canvas.Open:
``` xojo
Me.AcceptPictureDrop
```
Canvas.DropObject:
``` xojo
If obj.PictureAvailable Then
Me.Backdrop = obj.Picture
End If
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.AcceptRawDataDrop
**AcceptRawDataDrop**(Type As `String`)
Permits data (of the Type specified) to be dropped on the control.
The following specfies a generic file type defined in the File Type Sets editor.
``` xojo
Me.AcceptRawDataDrop("????")
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.AcceptTextDrop
**AcceptTextDrop**
Permits text to be dropped on the control.
This line in the Open event of a control that can accept dragged text.
``` xojo
Me.AcceptTextDrop
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.AddAllRows
**AddAllRows**(items() As `String`)
Creates a new row for every value in the items array.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.AddExpandableRow
**AddExpandableRow**(text As `String`)
Appends *text* in a new row to the end of the list and adds disclosure triangle only if the AllowExpandableRows property is set to `True`.
For multi-column ListBoxes, *Item* is always assigned to column zero. In the case of hierarchical ListBoxes, AddExpandableRow appends *Item* to the subitems of the expanded row when called in the ExpandRow event.
The following example adds creates a hierarchical ListBox. Note that AddExpandableRow must be called to create the hierarchical relationship.
``` xojo
Var s1, sub1 As String
Me.ColumnWidths = "150,0"
s1 = "Michigan,Ohio,Minnesota"
sub1 = "Grand Blanc,Bad Axe,Flint,Benton Harbor,"_
+ "Detroit;Cleveland,Columbus,Akron,Pleasantville;St. Paul,Frostbite Falls"
For i As Integer = 1 To s1.Split(",").Count
If NthField(sub1, ";", i) <> "" Then
Me.AddExpandableRow("")
Me.CellValueAt(i - 1, 1) = NthField(sub1, ";", i)
End If
Me.CellValueAt(i - 1, 0) = NthField(s1, ",", i)
Next
Me.ColumnCount = 1
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.AddExpandableRowAt
**AddExpandableRowAt**(index As `Integer`, text As `String`)
Creates a new expandable row at *row* (zero-based), moving the existing rows down. The *text* is always assigned to column zero. The optional parameter *indent* specifies the amount of indentation of the row in a ListBox where `AllowExpandableRows` (sometimes called a *hierarchical* ListBox) is `True`. The default is zero. It has no effect on a ListBoxe where `AllowExpandableRows` is `False`.
The following example in a `PushButton` adds a row to the ListBox with expandable rows that is used for the example in `AddExpandableRow`. It adds a new state to the list of cities and states.
``` xojo
Listbox1.AddExpandableRowAt(1, "New Hampshire")
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.AddRow
**AddRow**(`ParamArray` Item As `String`)
Appends a new blank row to the end of the list.
Adding the string "October" to a new row in a ListBox named Listbox1:
``` xojo
ListBox1.AddRow("October")
```
The following line adds a row of months to a ListBox that has four columns:
``` xojo
Listbox1.AddRow("Sept", "Oct", "Nov", "Dec")
```
The following line adds a row of months to a ListBox that has four columns using an array:
``` xojo
Var months() As String = Array("Sept", "Oct", "Nov", "Dec")
ListBox1.AddRow(months)
```
The following adds a blank row then sets values for column 3:
``` xojo
ListBox1.AddRow
ListBox1.CellValueAt(ListBox1.LastAddedRowIndex, 2) = "Col 3"
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.AddRowAt
**AddRowAt**(RowNumber As `Integer`, Item As `String`, \[Indent As `Integer`\])
Creates a new row at *row* (zero-based), moving the existing rows below *row* down. For multicolumn ListBoxes, *text* is always assigned to column zero. The optional parameter *indent* specifies the amount of indentation of the row in hierarchical ListBoxes. The default is zero. It has no effect on non-hierarchical ListBoxes.
The following example inserts a row in the ListBox. The code is in a `PushButton`.
``` xojo
Listbox1.AddRowAt(1, "Steven")
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.CellBold
**CellBold**(RowNumber As `Integer`, ColumnNumber As `Integer`) As `Boolean`
Used to add or remove the bold style from the text of the specified cell. Note that *row* and *column* are zero-based.
Assign `True` to add the bold style and `False` to remove the bold style. For example:
``` xojo
ListBox1.CellBold(1, 1) = True
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.CellCheckBoxStateAt
**CellCheckBoxStateAt**(Row As `Integer`, Column As `Integer`) As `CheckBox`
Used to get or set the state of the cell with the coordinates of *row*, *column* (zero-based). This assumes that the passed cell is a CheckBox cell. Use the CellType property to set a cell to a CheckBox cell. `CheckBox` is an `Enum` of the `CheckBox` class.
The CellCheckBoxStateAt method enables you to get or set the value of a tri-state Checkbox cell. Any cell of type TypeCheckbox box can store one of three values: Checked, Unchecked, and Indeterminate.
To set up a cell as TypeCheckbox, use code such as this in the Open event:
``` xojo
Me.CellTypeAt(1, 0) = ListBox.CellTypes.CheckBox
```
To change the state of the cell, use the `VisualStates` enum of the `CheckBox` control:
``` xojo
ListBox1.CellCheckBoxStateAt(1, 0) = Checkbox.VisualStates.Indeterminate
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.CellItalic
**CellItalic**(RowNumber As `Integer`, ColumnNumber As `Integer`) As `Boolean`
Used to add or remove the italic style from the text of the specified cell. *row* and *column* are zero-based.
This example assigns `True` to apply the italic style.
``` xojo
ListBox1.CellItalic(1, 1) = True
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.CellTagAt
**CellTagAt**(Row As `Integer`, Column As `Integer`) As `Variant`
Gets or sets a "hidden" identifier associated with the cell identified by its parameters. *Row* and *Column* are zero-based.
This example sets a tag for a cell.
``` xojo
Me.CellTagAt(1, 4) = "My Cell Tag"
```
This example displays the tag for a cell:
``` xojo
MessageBox(Me.CellTagAt(1, 4))
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.CellToolTipAt
**CellToolTipAt**(RowNumber As `Integer`, ColumnNumber As `Integer`) As `String`
Used to set or get the help tag (i.e. tooltip) for a ListBox cell. *row* and *column* are zero-based.
The following adds a tip to cell 0,0. The tip is visible when the user moves the pointer over the cell.
``` xojo
Listbox1.CellToolTipAt(0, 0) = "Enter your full name."
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.CellUnderline
**CellUnderline**(RowNumber As `Integer`, ColumnNumber As `Integer`) As `Boolean`
Used to add or remove the underline style from the text of the specified cell. *row* and *column* are zero-based.
Assign `True` to add the underline style and `False` to remove the underline style. For example:
``` xojo
ListBox1.CellUnderline(1, 1) = True
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.CellValueAt
**CellValueAt**
Used to set the text of the cell based on the row and column numbers passed.
*row* and *column* are zero-based. The top-left cell is 0,0. The class constants AllColumns and AllRows can be used to specify that you wish to get or set all the values columns or rows. For example, the following specifies all columns in the last row added using AddRow or AddRowAt:
``` xojo
Me.CellValueAt(Me.LastAddedRowIndex, ListBox.AllColumns)
```
If you set this equal to a tab-delimited string, you can update the row with one line of code.
This example copies all cells from one ListBox into another:
``` xojo
ListBox2.CellValueAt(ListBox.AllRows, ListBox.AllColumns) = ListBox1.CellValueAt(ListBox.AllRows, ListBox.AllColumns)
```
The destination ListBox will have the same number of rows and columns as the source. Headers, CellTags, RowTags and ColumnTags are not copied.
In this example, the following code populates a two-column ListBox with the names of the controls in the window and their indexes.
``` xojo
Var i As Integer
For i = 0 To Self.ControlCount - 1 ' number of controls in window
ListBox1.AddRow(Str(i)) ' first column
ListBox1.CellValueAt(Listbox1.LastAddedRowIndex, 1) = Control(i).Name ' second column
Next
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.Close
**Close**
Closes a control.
Closing a control permanently removes the control from memory, making it impossible to access. You can close both non-indexed controls and indexed controls. When you close an indexed control, the indexes for the remaining controls will shift downward so that the indexes start with zero and are consecutive.
The following code closes the control. When this is executed from a visible control, the control disappears from the window.
``` xojo
Me.Close
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.ColumnFromXY
**ColumnFromXY**(X As `Integer`, Y As `Integer`) As `Integer`
Returns the column index from the passed mouse x, y pixel coordinates.
The parameters *X* and *Y* are relative to the top, left corner of the ListBox. If you use `System` or `System` to get the mouse coordinates to use with this method, you'll need to take into account that those System values are relative to the top-left corner of the entire screen.
This code in the DoubleClick event of a ListBox obtains the indexes of the cell that was double-clicked:
``` xojo
Var xValue As Integer
xValue = System.MouseX - Me.Left - Self.Left ' Calculate current mouse position relative to top left of ListBox
Var yValue As Integer
yValue = System.MouseY - Me.Top - Self.Top ' Calculate current mouse position relative to top of ListBox.
Var row, column As Integer
row = Me.RowFromXY(xValue, yValue)
column=Me.ColumnFromXY(xValue, yValue)
MessageBox("You double-clicked in cell " + row.ToString + ", " + column.ToString)
```
If you use the ListBox on a ContainerControl, then you need to also take into account the Container size:
``` xojo
Var xValue As Integer
xValue = System.MouseX - Me.Left - Self.Left - Me.TrueWindow.Left ' Calculate current mouse position relative to top left of ListBox
Var yValue As Integer
yValue = System.MouseY - Me.Top - Self.Top - Me.TrueWindow.Top ' Calculate current mouse position relative to top of ListBox.
Var row, column As Integer
row = Me.RowFromXY(xValue, yValue)
column=Me.ColumnFromXY(xValue, yValue)
MessageBox("You double-clicked in cell " + row.ToString + ", " + column.ToString)
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.ColumnSortTypeAt
**ColumnSortTypeAt**(Column As `Integer`) As `ListBox`
{
The default is Sortable. Sortable means that the column can be clicked on and will display mouse over events. If the column is NotSortable, then the header cannot be clicked on and will not display mouse over events. Setting *Column* to ListBox.AllColumns affects the header type of all columns.
The following code in the Open event of the ListBox sets the first two columns as sortable and the third column as non-sortable.
``` xojo
Me.ColumnSortTypeAt(0) = ListBox.SortTypes.Sortable
Me.ColumnSortTypeAt(1) = ListBox.SortTypes.Sortable
Me.ColumnSortTypeAt(2) = ListBox.SortTypes.NotSortable
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.ColumnTagAt
**ColumnTagAt**(Column As `Integer`) As `Variant`
Gets and sets the ColumnTag for each column. Column is zero-based. ColumnTagAt can be viewed in the Debugger.
``` xojo
Me.ColumnTagAt(4) = "Enter your birthdate."
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.DrawInto
**DrawInto**(g As `Graphics`, x As `Integer`, y As `Integer`)
Draws the contents of the RectControl into the specified `Graphics` context. The parameters *x* and *y* are the coordinates of the top, left corner.
This method does not work with `HTMLViewer` and `OpenGLSurface`.
This example draws the current control into the Graphics of a Picture and then displays it as the Backdrop of a Canvas:
``` xojo
Var p As New Picture(Me.Width, Me.Height)
Me.DrawInto(p.Graphics, 0, 0)
Canvas1.Backdrop = p
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.EditCellAt
**EditCellAt**(Row As `Integer`, Column As `Integer`)
Scrolls the *row*, *column* cell into view (if necessary) and temporarily makes the cell editable. *row* and *column* are zero-based. It sets the focus within the ListBox to the *row*, *column* cell and selects its contents, if any. The editable cell has a focus ring around it.
Use the `CellTypeAt` or `ColumnTypeAt` properties to change a cell or column to “inline editable” when you want the user to be able to edit the contents of the ListBox. Then call the EditCellAt method for each cell. This gives the editable cell the focus and selects the current text of the cell, if any. Typing replaces the cell's contents. When the user presses Tab or Return or clicks in another cell, the cell loses the focus and the contents of the cell are saved (this also calls the `CellAction` event handler).
When a cell is editable, the `ActiveTextControl` property is the `TextEdit` that contains the contents of that cell. This may be a `TextField` or a `TextArea` depending on the specified column type. You can use this property to set or get the text of the ListBox cell, set the selection, or change other properties of the ListBox's TextField or TextArea.
The following code in the CellClick event makes the cell the user pressed on editable. The parameters *row* and *column* are passed to the function.
``` xojo
Me.CellTypeAt(row, column) = Listbox.CellTypes.TextField
Me.EditCellAt(row, column)
```
This code marks an entire column as editable:
``` xojo
ListBox1.ColumnTypeAt(3) = ListBox.CellTypes.TextArea
```
In the `CellClick` event handler, you can then check if the column was pressed and then enable editing:
``` xojo
If column = 3 Then
Me.EditCellAt(row, column)
End If
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.ExpandableRowAt
**ExpandableRowAt**(row As `Integer`) As `Boolean`
For hierarchical ListBoxes, is used to get or set whether the row should be displayed as expandable.
``` xojo
Me.AddExpandableRow("Players")
Me.ExpandableRowAt(Me.LastAddedRowIndex) = False ' Disable expandable indicator
```
forsearch
ListBox.HeaderAt
**HeaderAt** As `String`
Returns the header for the column whose index is passed.
If you assign values to both HeaderAt and InitialValue, the first row of InitialValue is interpreted as the first row of data; otherwise, it is used as the header and the second row of InitialValue is used as the first row of data.
You can set the headers in a multi-column ListBox by assigning to HeaderAt(ListBox.AllColumns) the text of the headings separated by the tab character, e.g.,
``` xojo
Me.HeaderAt(ListBox.AllColumns) = "FirstName" + Chr(9) + "LastName"
```
You must use a space if you want an empty header; empty strings will use the default header.
``` xojo
ListBox1.HeaderAt(ListBox.AllColumns) = "" ' sets all headers of ListBox1 to their defaults.
ListBox1.HeaderAt(5) = "" ' sets column 5's header to its default heading
ListBox1.HeaderAt(5) = " " ' sets column 5's header to empty.
```
This example populates a three-column ListBox with headers:
``` xojo
ListBox1.HasHeader = True
ListBox1.HeaderAt(0) = "ID"
ListBox1.HeaderAt(1) = "JobTitle"
ListBox1.HeaderAt(2) = "Name"
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.Invalidate
**Invalidate**(\[EraseBackground As `Boolean`\])
Similar to RefreshRect, but causes the specified region of the RectControl to be marked dirty and to be redrawn when the window contents need to be redrawn. The region to be redrawn is specified by the *X*, *Y*, *Width*, and *Height* parameters. This form of Invalidate was formerly called InvalidateRect.
The following code refreshes the control. EraseBackground defaults to `True`.
``` xojo
Me.Invalidate(False)
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.InvalidateCell
**InvalidateCell**(Row As `Integer`, Column As `Integer`)
Redraws the specified cell "from scratch" rather than using the data in the internal buffer.
*row* and *column* are zero-based. If you pass a -1 as the *row* or *column* parameter, it will redraw the specified entire row or column, i.e., Invalidate(2, -1) redraws row number 2. The CellBackgroundPaint and CellTextPaint events execute when InvalidateCell is called.
InvalidateCell should be necessary only if you are using a custom storage mechanism for your ListBox data. If the contents of the ListBox are stored in the ListBox cells, the ListBox will update automatically as needed.
This method doesn't have a high overhead if used unnecessarily since nothing will happen if the specified cell is not visible.
The following example redraws the specified cell.
``` xojo
Listbox1.InvalidateCell(1, 0)
```
forsearch
ListBox.PressHeader
**PressHeader**(Column As `Integer`)
Causes the specified ListBox header to be pressed at column *v* (zero-based), causing a HeaderPressed event to occur. Calling this method does not update the sort direction.
This example presses the first column.
``` xojo
Listbox1.PressHeader(0)
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.Refresh
**Refresh**(eraseBackground As `Boolean`)
Repaints the portion specified of the contents of the control immediately.
Calling this frequently can cause the code executing to slow down. It is often preferable to call `RectControl` instead.
Refresh the entire area:
``` xojo
Me.Refresh(False)
```
Refresh a portion of the area:
``` xojo
Me.Refresh(100, 150, 200, 300)
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.RemoveAllRows
**RemoveAllRows**
Removes all rows in the ListBox, including any initial values that were specified in the IDE.
This example removes all the rows in ListBox1.
``` xojo
Listbox1.RemoveAllRows
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.RemoveRowAt
**RemoveRowAt**(RowNumber As `Integer`)
Removes the specified row at *index* (zero-based).
This example removes the second row.
``` xojo
Listbox1.RemoveRowAt(1)
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.RowDepthAt
**RowDepthAt**(row As `Integer`) As `Integer`
For hierarchical ListBoxes, this is the depth of the specified row in the hierarchy. A top-level row has RowDepth = 0.
Get depth of selected row:
``` xojo
Var row As Integer = ListBox1.RowCount
Var depth As Integer = ListBox1.RowDepthAt(row)
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.RowExpandedAt
**RowExpandedAt**(RowNumber As `Integer`) As `Boolean`
Used to get or set the expanded state of the row passed.
The row must have been added with the AddExpandableRow method.
This example expands the first row of ListBox1 (if it is collapsed) or collapses it (if it was expanded). The row must have been added with the AddExpandableRow method:
``` xojo
ListBox1.RowExpandedAt(1) = Not ListBox1.RowExpandedAt(1)
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.RowFromXY
**RowFromXY**(X As `Integer`, Y As `Integer`) As `Integer`
Returns the row index from the passed mouse x, y pixel coordinates.
The parameters *X* and *Y* are relative to the top, left corner of the ListBox. If you use `System` or `System` to get the mouse coordinates to use with this method, you'll need to take into account that those System values are relative to the top-left corner of the entire screen.
This code in the DoubleClick event of a ListBox added to a Window obtains the indexes of the cell that was double-clicked:
``` xojo
Var xValue As Integer
xValue = System.MouseX - Me.Left - Self.Left ' Calculate current mouse position relative to top left of ListBox
Var yValue As Integer
yValue = System.MouseY - Me.Top - Self.Top ' Calculate current mouse position relative to top of ListBox.
Var row, column As Integer
row = Me.RowFromXY(xValue, yValue)
column=Me.ColumnFromXY(xValue, yValue)
MessageBox("You double-clicked in cell " + row.ToString + ", " + column.ToString)
```
If the ListBox code is not on the window (perhaps it is in a subclass or ContainerControl), then you need to be sure to calculate the correct offsets. This code would be used for a ListBox on a ContainerControl:
``` xojo
Var xValue As Integer
xValue = System.MouseX - Me.Left - Self.Left - Me.TrueWindow.Left ' Calculate current mouse position relative to top left of ListBox
Var yValue As Integer
yValue = System.MouseY - Me.Top - Self.Top - Me.TrueWindow.Top ' Calculate current mouse position relative to top of ListBox.
Var row, column As Integer
row = Me.RowFromXY(xValue, yValue)
column=Me.ColumnFromXY(xValue, yValue)
MessageBox("You double-clicked in cell " + row.ToString + ", " + column.ToString)
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.RowImageAt
**RowImageAt**(RowNumber As `Integer`) As `Picture`
Adds the image/picture assigned to the passed row *index* (zero-based).
The ListBox row does not resize to accommodate the `Picture`. If your picture does not fit via RowImageAt, use CellTextPaint or CellBackgroundPaint to draw the picture yourself.
The following example draws a picture in the first cell. The picture has been added to the project.
``` xojo
Listbox1.RowImageAt(0) = UserPhotoImage
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.Rows
**Rows** As `ListBoxRow`
Allows you to iterate through all the rows in a ListBox.
In this example, the Tag of each row is examined and if it's found to be "Taxable", the ComputeTaxes method is called and passed the value of the row.
``` xojo
For Each row As ListBoxRow In ListBox1.Rows
If row.Tag = "Taxable" then ComputeTaxes(row.ColumnValueAt(0))
Next
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.RowTagAt
**RowTagAt**(Row As `Integer`) As `Variant`
Gets and sets the RowTag for the *row* (zero-based).
To set the tag:
``` xojo
ListBox1.RowTagAt(row) = "MyTag"
```
To get the tag:
``` xojo
myTag = ListBox1.RowTagAt(row)
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.SetFocus
**SetFocus**
If applicable, sets the focus to the RectControl. KeyDown events are directed to the control.
If the control cannot get the focus on the platform on which the application is running, SetFocus does nothing. The SetFocus method of the `Window` class or the `ClearFocus` method can be used to remove the focus from the control that currently has the focus, leaving no control with the focus.
On the Mac you need Full Keyboard Access turned on in System Preferences (Keyboard-\>Shortcuts) in order to manually set focus to non-text controls.
The following example sets the focus to TextField1. If another control has the focus when this line is executed, then the user sees that TextField1 gets the focus.
``` xojo
TextField1.SetFocus
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.Sort
**Sort**
Sorts the rows based on the current values of the `SortingColumn` and `ColumnSortDirectionAt` properties.
When `AllowExpandableRows` is `True` and a ListBox is sorted, the rows are sorted at all levels of the hierarchy, not just the base level.
To ensure the sort indicator displays after sorting you can force the header to refresh like this:
``` xojo
Listbox1.HasHeader = True
```
The following code sorts a ListBox in descending order on the first column.
``` xojo
' first column, descending order
ListBox1.ColumnSortDirectionAt(0) = ListBox.SortDirections.Descending
ListBox1.SortingColumn = 0 ' first column is the sort column
ListBox1.Sort
```
## Event descriptions
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.CellAction
**CellAction**(Row As `Integer`, Column As `Integer`)
If a cell is editable, a CellAction event occurs when the user finishes editing a cell. *Row* and *Column* are zero-based.
“Finishing editing” is defined as exiting the cell after clicking in it. Tabbing out of the editable cell or clicking another cell triggers this event. Clicking a checkbox in a checkbox cell also qualifies as "finishing editing".
The user doesn't necessarily have to change the contents.
This code will display changes made to an editable cell when the user finishes editing (by either pressing return or switching to a different cell):
``` xojo
If column = 2 Then ' Is this the editable column?
MessageBox("You entered: " + Me.Cell(row, column))
End If
```
This event handler is also called when the user clicks a CheckBox cell:
``` xojo
If column = 3 Then ' Is this the CheckBox column?
If Me.CellCheckBoxAt(row, column) Then
MessageBox("You checked the checkbox in row " + row.ToString)
Else
MessageBox("You unchecked the checkbox in row " + row.ToString)
End If
End If
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.CellBackgroundPaint
**CellBackgroundPaint**(g As `Graphics`, Row As `Integer`, Column As `Integer`) As `Boolean`
The parameter *g* is a `Graphics` object that corresponds to the content area of the cell identified by the parameters *Row*, *Column*. 0,0 is the upper left of the cell. Returns a `Boolean`. `True` means the user has handled the background paint and no other processing is to be done with the background. In this case the user is responsible for all highlighting. `False` means the user wants the default background; this will overwrite your drawing on the row that needs to be highlighted as the row or column will be highlighted as appropriate (according to the platform and the hierarchical style).
This code can be used to do alternate row highlighting:
``` xojo
If row Mod 2 = 0 Then
g.DrawingColor = &cf3f6fA
g.FillRectangle(0, 0, g.Width, g.Height)
End If
```
This example paints the cell background red if the CellTag contains the string "Red":
``` xojo
If Me.CellTagAt(row, column ) = "Red" Then
g.DrawingColor =Color.RGB(255, 0, 0)
g.FillRectangle(0, 0, g.Width, g.Height)
End If
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.CellClick
**CellClick**(Row As `Integer`, Column As `Integer`, X As `Integer`, Y As `Integer`) As `Boolean`
The user has clicked on the *Row*, *Column* cell. *Row* and *Column* are zero-based. The parameters *X* and *Y* are the x and y coordinates of the mouse click relative to the top-left corner of the cell that was clicked. *X* and *Y* are on the same scale of reference as the coordinates used by the `Graphics` property of the CellBackgroundPaint event.
To give the user the ability to edit the cell, change the CellType to Editable (ListBox.TypeEditable) and then call the EditCell method. The user will then get a focusing ring around the cell and the current text will become editable. When the user tabs out of the cell, the changes will be saved. You will get the CellAction event.
CellClick returns a `Boolean`. Returning `True` means that the event will not be processed further (i.e., editable cells won't be editable and ListBox selection won't change).
This code makes a cell editable when it is clicked:
``` xojo
If column = 2 Then ' Is this the editable column?
Me.ColumnTypeAt(column) = ListBox.CellTypes.TextField
Me.CellEditTextAt(row, column)
Return True
End If
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.CellGotFocus
**CellGotFocus**(Row As `Integer`, Column As `Integer`)
The user has selected an editable cell of a ListBox. *Row* and *Column* are zero-based. The *Row* and *Column* parameters indicate which cell just got the focus.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.CellKeyDown
**CellKeyDown**(Row As `Integer`, Column As `Integer`, Key As `String`) As `Boolean`
The user has pressed a key while a cell in the ListBox is being edited. *Row* and *Column* are zero-based.
This cell is identified by the *Row* and *Column* parameters. *Key* is the key that the user pressed.
CellKeyDown returns a `Boolean`. Returning `True` prevents the text from changing automatically and prevents the CellTextChange event from firing.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.CellLostFocus
**CellLostFocus**(Row As `Integer`, Column As `Integer`)
The *Row*, *Column* cell has just lost the focus. *Row* and *Column* are zero-based. The user could have clicked on another cell or pressed Tab, Return, or Escape.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.CellTextChange
**CellTextChange**(Row As `Integer`, Column As `Integer`)
Occurs after the KeyDown event if the KeyDown event returns `False`.
The event is passed the *Row* and *Column* of the cell being edited.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.CellTextPaint
**CellTextPaint**(g As `Graphics`, Row As `Integer`, Column As `Integer`, x As `Integer`, y As `Integer`) As `Boolean`
The parameter g is a `Graphics` object that corresponds to the text drawing area of the cell identified by *Row*, *Column*. *Row* and *Column* are zero-based. This does not necessarily correspond to the entire cell content area, for example, if you use a row picture in the cell.
In order for this event handler to be called, the cell itself must have been given a value, even if it is blank.
The parameters *x* and *y* are the coordinates of the suggested ideal location to draw text based on the current value of ColumnAlignment or CellAlignment, as well as the cell's font, font size, and font style.
The drawing order of the cell is as follows, with the background first:
\* Background *Disclosure Triangle/Treebox*Checkbox *RowPicture*Text \*Border
Although the border is painted last, it isn't advisable to change the state of the border in the CellTextPaint event since the area is determined by the size of the border before the cell is painted. It could leave unpainted areas or possibly cover up some of the painting you have done.
Returning `True` means the user has handled the text paint and no other processing is to be done with the text. In this case, the user is responsible for text highlighting. Text highlighting is currently only done for the hierarchical ListBox style. Returning `False` means the user wants the default text drawing. In this case, the text will be highlighted as appropriate (according to platform) for you automatically.
This code draws a small triangle on the right side of the cell (the code is using column 3 as the cell to draw into):
``` xojo
Select Case column
Case 3 ' Is this the column to draw into?
' Draw an arrow to indicate that clicking this field will
' display a menu
g.DrawingColor = &c000000
' Points for a triangle on the right side of the cell
Var points(6) As Integer
points(1) = g.Width - 10
points(2) = 1
points(3) = g.Width
points(4) = 1
points(5) = g.Width - 5
points(6) = 10
g.FillPolygon(points)
Return True
End Select
```
Now you can display a menu when the user clicks in the cell by putting code in the MouseDown and MouseUp event handlers.
This goes in MouseDown to allow the MouseUp event handler to be called:
``` xojo
If Me.ColumnFromXY(x, y) = 3 Then
Return True
End If
```
This code in MouseUp displays a simple menu:
``` xojo
' Display menu if clicked in PopupMenu column
Var row As Integer = Me.RowFromXY(x, y)
Var col As Integer = Me.ColumnFromXY(x, y)
If col = 3 Then
Me.SelectedIndex = row
Me.Selected(row) = True
Var base As New MenuItem
base.AddMenu(New MenuItem("Red"))
base.AddMenu(New MenuItem("Green"))
base.AddMenu(New MenuItem("Blue"))
base.AddMenu(New MenuItem("Black"))
base.AddMenu(New MenuItem("White"))
Var selectedMenu As MenuItem
selectedMenu = base.PopUp
If selectedMenu <> Nil Then
MessageBox("You changed the color to " + selectedMenu.Value + ".")
End If
End If
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.Change
**Change**
The Change event is called when the row selection is changed by the user or by code.
The Change event handler is called when the row selection changes, not when cell contents change.
The Change event handler is called in response to the following user actions: \* When the ListBox is clicked to give it the focus \* When an empty row in the ListBox is clicked \* When a cell is clicked even if it already is selected and the column is not editable \* When a row is clicked to change the selection
If a column is editable, clicking in a cell calls the Change event but a second click to get an insertion point does not. Clicking on a header or a checkbox does not call the Change event.
Also, a programmatic change to `ListBox` also triggers the Change event.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.Close
**Close**
The control is about to close.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.CollapseRow
**CollapseRow**(Row As `Integer`)
The user has clicked on the disclosure triangle of the expanded *Row* passed or the rows expanded property was set false programmatically. *Row* is zero-based.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.CompareRows
**CompareRows**(Row1 As `Integer`, Row2 As `Integer`, Column As `Integer`, `ByRef` Result As `Integer`) As `Boolean`
The CompareRows event is used for sorting a column of a ListBox in a manner that is not provided by the default mechanism. *Row* and *Column* are zero-based. The result of the comparison is returned in the last parameter, *Result*, which is declared `Byref`. The default mechanism sorts cell values lexicographically. If you implement the event, it gets called during a ListBox sort, e.g., when a user clicks in the header area.
**Parameters**: \* Row1: Row number of one of the rows being compared. \* Row2: Row number of the other row being compared. \* Column: Number of column being sorted.
Set **Result** to: \* 0: If items in Row1 and Row2 in specified column are equal. \* -1: Contents of Row1 \< Contents of Row2. \* 1: Contents of Row1 \> Contents of Row2.
`Return` `True` if the returned *Result* parameter is accurate for sorting.
`Return` `False` if you want the ListBox to use the default lexicographic sorting of the column.
Suppose your ListBox contains a first column (numbered 0) which contains a string value. You can let the ListBox use the default lexicographic comparison for such a column. However, the second column (numbered 1) contains a numerical value that should be sorted as such. You can implement the RowCompared event as follows:
``` xojo
Function CompareRows(row1 As Integer, row2 As Integer, column As Integer, ByRef result As Integer) As Boolean
Select Case column
Case 0 ' This is a string column. Let the listbox manage it by returning false
Return False
Case 1 ' This is our numerical value column. Let's do the work ourselves
If Val(Me.CellValueAt(row1, column )) < Val(Me.CellValueAt(row2, column)) Then
result = -1
ElseIf Val(Me.CellValueAt(row1, column)) > Val(Me.CellValueAt(row2, column)) Then
result = 1
Else
result = 0
End If
Return True
Else //some other column for which we let the listbox handle comparison
Return False
End Select
End Function
```
or, more simply, using the `Sign` function:
``` xojo
Function CompareRows(row1 As Integer, row2 As Integer, column As Integer, ByRef result As Integer) As Boolean
Select Case column
Case 0 ' This is a string column. Let the listbox manage it by returning false
Return False
Case 1 ' This is our numerical value column. Let's do the work ourselves
result = Sign(Val(Me.CellValueAt(row1, column)) - Val(Me.CellValueAt( row2, column)))
Return True
Else //some other column for which we let the listbox handle comparison
Return False
End Select
End Function
```
To sort a column containing checkboxes use
``` xojo
Function CompareRows(row1 As Integer, row2 As Integer, column As Integer, ByRef result As Integer) As Boolean
' Column 0 contains checkboxes.
' We want to sort it by checkbox value, with unchecked rows before checked rows.
Select Case column
Case 0 ' column 0 contains our checkboxes
If Me.CellCheckBoxValueAt(row1, column) XOr Me.CellCheckBoxValueAt(row2, column) Then
' CellCheckBox values are unequal. If row1 is true, then row2 must be true and vice versa.
If Me.CellCheckBoxValueAt(row1, column) Then
' row1 < row2
result = 1
Else
' row1 < row2
result = -1
End If
Else
' CellCheckBox values are equal, so row1 = row2.
result = 0
End If
Return True
Else
' let the listbox do default comparison
Return False
End Select
End Function
```
forsearch
ListBox.ConstructContextualMenu
**ConstructContextualMenu**(Base As `MenuItem`, x As `Integer`, y As `Integer`) As `Boolean`
This event is called when it is appropriate to display a contextual menu for the control.
This event handler is the recommended way to handle contextual menus because this event figures out whether the user has requested the contextual menu, regardless of how they did it. Depending on platform, it might be in the MouseUp or MouseDown event and it might be a right+click or by pressing the contextual menu key on the keyboard, for example.
*Base* is analogous to the menu bar for the contextual menu. Any items you add to *Base* will be shown as menu items. If you return `False`, the event is passed up the parent hierarchy.
If you return `True`, the contextual menu is displayed. The parameters *x* and *y* are the mouse locations. If the event was fired because of a non-mouse event, then *x* and *y* are both set to -1. See the example of a contextual menu in the following section.
The following ConstructContextualMenu event handler builds a menu with three menu items plus a submenu with three additional menu items.
``` xojo
' Add some items
base.AddMenu(New MenuItem("Test 1"))
base.AddMenu(New MenuItem("Test 2"))
base.AddMenu(New MenuItem("Test 3"))
' Add a Separator
base.AddMenu(New MenuItem(MenuItem.TextSeparator))
' Add a sub menu
Var submenu As New MenuItem("SubMenu")
submenu.AddMenu(New MenuItem("SubMenu Test 1"))
submenu.AddMenu(New MenuItem("SubMenu Test 2"))
submenu.AddMenu(New MenuItem("SubMenu Test 3"))
base.AddMenu(submenu)
' Add a Separator
base.AddMenu(New MenuItem(MenuItem.TextSeparator))
Return True
```
forsearch
ListBox.ContextualMenuAction
**ContextualMenuAction**(HitItem As `MenuItem`) As `Boolean`
Fires when a contextual menuitem *hitItem* was selected but the Action event and the MenuHandler for the menuitem did not handle the menu selection.
This event gives you a chance to handle the menu selection by inspecting the menuitem's Text or Tag properties to see which item was selected. Use this in conjunction with ConstructContextualMenu if you have not specified the Action event or the Menu Handler for the items on the contextual menu. See the example of a contextual menu in the examples for the **RectControl** class.
`Return` `True` if this event has handled the item the user chose from the contextual menu. Returning `False` will cause the control's parent to execute its ContextualMenuAction event. This can be handy if you have the same contextual menu for several controls who share the same `Parent` (several on the same window for example). By returning `False` you can handle them all in a single event.
This simple event handler displays the value of the selected menu item.
``` xojo
If hitItem <> Nil Then MessageBox(hitItem.Value)
Return True
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.DisclosureWidgetPaint
**DisclosureWidgetPaint**(g As `Graphics`, row As `Integer`, `ByRef` x As `Integer`, `ByRef` y As `Integer`, `ByRef` width As `Integer`, `ByRef` height As `Integer`)
Invoked for hierarchical ListBoxes when the framework needs to draw the disclosure triangle for a folder row. This is invoked after CellBackgroundPaint and before CellTextPaint.
The left, top, width and height parameters: \* Default to the coordinates for drawing the built-in widget \* These coordinates are also used for hit testing to determine if a mousedown should toggle the row's expanded state. \* Are ByRef so the user can specify the location of the rectangle used for hit testing when drawing their own widget, if for instance the hit area is smaller than the drawn widget. \* Setting width or height to zero will completely hide the triangle and no hit testing will be done. \* Returning False causes the framework widget to be drawn. \* Returning True prevents the framework from drawing its own disclosure widget, signaling that the event has performed all of the necessary drawing. \* Changing the Width parameter and returning True will offset the graphic object that is provided in the following CellTextPaint event by the same offset. i.e. if the supplied Width is 10, but the code changes it to 5 the graphic object in the CellTextPaint event would be offset by 5 pixels to the left.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.DoubleClick
**DoubleClick**
The user has double-clicked on a row in the ListBox.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.DragEnter
**DragEnter**(obj As `DragItem`, Action As `Integer`) As `Boolean`
Fires when the passed `DragItem` enters the RectControl.
Returns a `Boolean`. Return `True` from this event to prevent the drop from occurring.
The Action parameter specifies the drag action. It can take the following class constants of the `DragItem` class:
| Value | Class Constant |
|-------|--------------------------------------------------------------------|
| 0 | `DragItem`.DragActionDefault |
| 1 | `DragItem`.DragActionCopy |
| 2 | `DragItem`.DragActionMove |
| 3 | `DragItem`.DragActionLink |
To restrict file drops to just folders (and not files), you can put this code in the DragEnter event:
``` xojo
If Not obj.FolderItem.IsFolder Then Return True
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.DragExit
**DragExit**(obj As `DragItem`, Action As `Integer`)
Fires when the passed `DragItem` exits the RectControl.
The *Obj* parameter is the item being dragged. The *Action* parameter specifies the drag action. It can take the following class constants of the `DragItem` class:
| Value | Constant |
|-------|--------------------------------------------------------------------|
| 0 | `DragItem`.DragActionDefault |
| 1 | `DragItem`.DragActionCopy |
| 2 | `DragItem`.DragActionMove |
| 3 | `DragItem`.DragActionLink |
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.DragOver
**DragOver**(x As `Integer`, y As `Integer`, obj As `DragItem`, Action As `Integer`) As `Boolean`
Fires when the `DragItem` is over the RectControl.
The *Obj* parameter is the object being dragged. The coordinates x and y are relative to the **RectControl**. Returns a `Boolean`. Return `True` from this event to prevent the drop from occurring.
The *Action* parameter specifies the drag action, which is typically done by holding down a modifier key (Shift, Alt, Option, Command, etc.) while doing the drag. It can take the following class constants of the `DragItem` class:
| Value | Constant |
|-------|--------------------------------------------------------------------|
| 0 | `DragItem`.DragActionDefault |
| 1 | `DragItem`.DragActionCopy |
| 2 | `DragItem`.DragActionMove |
| 3 | `DragItem`.DragActionLink |
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.DragOverRow
**DragOverRow**(x As `Integer`, y As `Integer`, obj As `DragItem`, action As `Integer`, `ByRef` row As `Integer`, `ByRef` parentRow As `Integer`, `ByRef` location As `ListBox`)
Invoked during dragging, similar to the DragOver event.
Event handlers can 'retarget' a drop by altering the row, parentRow, or location parameters.
- x: The x coordinate of the drop, relative to the left of the ListBox.
- y: The y coordinate of the drop, relative to the top of the ListBox.
- obj: The data actually being dropped.
- action: The drag action, which can be things like move or copy. Constants already exist in the DragItem class for this.
- row: The proposed target row for the drop.
- parentRow: When the ListBox is non-hierarchical, this will always be -1. When the ListBox is hierarchical, this is the row that the item is being dragged into. If the item is being dragged to the top level, parentRow will have a value of -1.
- location: Whether the drop is going between two rows, on the row itself or just on the control. Uses the ListBox.DropLocations enum.
Returning True prevents the drop from occurring and the DragOver event from firing. Otherwise the DragOver event fires.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.DragReorderRows
**DragReorderRows**(NewPosition As `Integer`, ParentRow As `Integer`) As `Boolean`
This event is called when one or more rows are selected then moved in the ListBox to a new position. The `ListBox` property must be `True` in order for this event to be called.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.DragRow
**DragRow**(Drag As `DragItem`, Row As `Integer`) As `Boolean`
The user is dragging a row. *Row* is zero-based.
*Drag* is the `DragItem` object that is created automatically. Assign the values to the `DragItem`'s properties that the user should drag. *Row* is the row of the ListBox that is being dragged. You must return `True` in this event handler to allow the drag to occur.
Setting up the DragRow event handler to allow the user to drag a value from a \`ListBox\`:
``` xojo
Function DragRow(drag As DragItem, row As Integer) As Boolean
drag.Text = ListBox1.List(row)
Return True
End Function
```
If you want to allow multiple row selection and dragging, then you need to process all the rows in the selection. This version of the DragRow event handler illustrates this.
``` xojo
Function DragRow(drag As DragItem, row As Integer) As Boolean
Dim nRows As Integer
Dim additionalItems As Boolean
For i As Integer = 0 To Me.RowCount - 1
If Me.Selected(i) Then
If Not additionalItems Then
additionalItems = True
Else
drag.AddItem(0, 0, 0, 0) ' No need to specify a rect for just text
End If
drag.Text = Me.List(i)
End If
Next
Return True
End Function
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.DropObject
**DropObject**(Obj As `DragItem` Action As `Integer`)
The item represented by *Obj* has been dropped on the control.
The *Obj* parameter is the object being dragged. The *Action* parameter specifies the drag action. It can take the following class constants of the `DragItem` class:
{\| class="genericTable" ! width=10% Class Constant 0 \| `DragItem`.DragActionDefault 1 \| `DragItem`.DragActionCopy 2 \| `DragItem`.DragActionMove 3 \| `DragItem`.DragActionLink }
The following DropObject event handler can handle either a dropped picture or a dropped file. The type of file that it can handle needs to have been specified in a call to AcceptFileDrop prior to the drop, for example, in the Open event.
``` xojo
If Obj.PictureAvailable Then
Me.Image = obj.Picture
ElseIf Obj.FolderItemAvailable Then
Me.Image = Picture.Open(obj.FolderItem)
End If
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.DropObjectOnRow
**DropObjectOnRow**(x As `Integer`, y As `Integer`, obj As `DragItem`, action As `Integer`, row As `Integer`, parentRow As `Integer`, location As `ListBox`)
Invoked when a drop has finished.
The row, parentRow, and `location` are the values previously set by the DragOverRow event handler.
The DropObject event fires after this event.
This code in the event handler shows the different values that can be passed for the Location parameter.
``` xojo
Select Case location
Case listbox.DropLocations.AfterAllRows
MessageBox "add row after all rows"
Case listbox.DropLocations.AfterRow
MessageBox "add row after rowindex = " + CStr(row)
Case listbox.DropLocations.OnControl
MessageBox "drop occurred ON control"
Case listbox.DropLocations.OnRow
MessageBox "add row to rowindex = " + CStr(row)
End Select
```
forsearch
ListBox.EnableMenuItems
**EnableMenuItems**
The control has received the focus. Menu handlers are invoked if the control has the focus.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.ExpandRow
**ExpandRow**(Row As `Integer`)
The user has clicked on the disclosure triangle, or the expanded property was set to true programmatically, for a collapsed row that was added using `AddFolder`. *Row* is zero-based.
The rows are not persisted when the folder is later collapsed. Use the ExpandRow event handler to re-add rows as necessary.
This code adds children to the expanded row:
``` xojo
For childRow As Integer = 0 To 5
Me.AddRow("Child " + Str(childRow) + " of row " + Me.CellValueAt(row, 0))
Next
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.GotFocus
**GotFocus**
The ListBox has received the focus and has a selection rectangle around it.
Note
On Macintosh, controls other than text fields and lists will accept focus only if the full keyboard access option is enabled in System Preferences/Keyboard.
forsearch
ListBox.HeaderBackgroundPaint
**HeaderBackgroundPaint**(g As `Graphics`, column As `Integer`)
Allow you to take control of drawing the background of the column headers.
Return `True` from this event to make any drawing you do in the `Graphics` parameter passed (*g*) take effect.
forsearch
ListBox.HeaderContentPaint
**HeaderContentPaint**(g As `Graphics`, column As `Integer`)
Allow you to take control of drawing the content of the column headers.
Return `True` from this event to make any drawing you do in the `Graphics` parameter passed (*g*) take effect.
forsearch
ListBox.HeaderPressed
**HeaderPressed**(Column As `Integer`) As `Boolean`
Runs after a ListBox header has been clicked/pressed. The index on *Column* is zero-based. You can use this event to specify whether you want to sort the column that was pressed. If you return `True`, the column is not sorted and it does not update the SortedColumn property.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.KeyDown
**KeyDown**(Key As `String`) As `Boolean`
The user has pressed the *Key* passed while the `control` has the focus.
How KeyDown works depends on the type of control.
**TextField and TextArea** Returning `True` means the key is intercepted, preventing the key from actually reaching the control at all. This would be useful if you want to override the behavior of the tab key for example. Returning `False` means the key reaches the control.
**All Other Controls** Returning `True` prevents the KeyDown event on the parent control (usually the window) from executing. Returning `False` results in the execution of the KeyDown event of the parent control.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.KeyUp
**KeyUp**(Key As `String`)
Fires when the passed *Key* is released in the RectControl that has the focus.
It is not guaranteed to be the same key that received the KeyDown event.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.LostFocus
**LostFocus**
The ListBox has lost the focus.
Note
On Macintosh, controls other than text fields and lists will accept and lose focus only if the full keyboard access option is enabled in System Preferences/Keyboard.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.MouseDown
**MouseDown**(x As `Integer`, y As `Integer`) As `Boolean`
The mouse button was pressed inside the control's region at the location passed in to *x*, *y*.
The coordinates *x* and *y* are local to the control, i.e. they represent the position of the mouse click relative to the upper-left corner or the ListBox.
`Return` `True` if you are going to handle the MouseDown. In such a case:
- The Action event, if any, will not execute and the state of the object will not change.
- You will receive the `MouseDrag` and `MouseUp` events.
If you return False, the system handles the MouseDown so the `MouseDrag` and `MouseUp` event handlers do not get called.
The MouseDown event uses the `DragItem` constructor when the user drags the contents of the control. It is:
``` xojo
Var d As DragItem
d = New DragItem(Self, Me.Left, Me.Top, Me.Width, Me.Height)
d.Picture = Me.Image
d.Drag ' Allow the drag
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.MouseDrag
**MouseDrag**(x As `Integer`, y As `Integer`)
This event fires continuously after the mouse button was pressed inside the ListBox. Mouse location is local to the control passed in to *x*, *y*.
Note
This event will not occur unless you return `True` in the `MouseDown
` event first.
The parameters *x* and *y* are local coordinates, i.e. they represent the position of the mouse relative to the upper-left corner of the ListBox.
As this event is fired continuously (hundreds of time per second), it is your responsibility to determine if the mouse has really moved.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.MouseEnter
**MouseEnter**
The mouse has entered the area of the control.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.MouseExit
**MouseExit**
The mouse has left the area of the control.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.MouseMove
**MouseMove**(X As `Integer`, Y As `Integer`)
The mouse has moved within the control to the coordinates passed. The coordinates are local to the control, not to the window.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.MouseUp
**MouseUp**(x As `Integer`, y As `Integer`)
The mouse button was released. Use the *x* and *y* parameters to determine if the mouse button was released within the control's boundaries.
Note
This event will not occur unless you return `True` in the MouseDown event. The return value is ignored.
The parameters *x* and *y* are local coordinates, i.e. they represent the position of the mouse click relative to the upper-left corner or the ListBox. Mouse clicks that are released to the left or above a control are negative.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.MouseWheel
**MouseWheel**(X As `Integer`, Y As `Integer`, DeltaX As `Integer`, DeltaY As `Integer`) As `Boolean`
The mouse wheel has been moved.
The parameters *X* and *Y* are the mouse coordinates relative to the control that has received the event. The parameters *DeltaX* and *DeltaY* hold the number of scroll lines the wheel has been moved horizontally and vertically, as defined by the operating system. *DeltaX* is positive when the user scrolls right and negative when scrolling to the left. *DeltaY* is positive when the user scrolls down and negative when scrolling up.
Returns a `Boolean`. Return `True` to prevent the event from propagating further.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.Open
**Open**
The control is about to be displayed. Use this event to initialize a control.
The Open event is called after the Constructor.
Be warned that initializing control property values using the Constructor instead of the Open event may result in those property values being overwritten by what is set in the Inspector. For best results, use the Open event for control initialization rather than the control Constructor.
If the control is supposed to handle drag and drop, you need to tell it which type of item it needs to be able to handle. The following example informs the control that pictures and files can be dropped on it. The type of the file it needs to support is specified via the File Types Editor.
``` xojo
Sub Open()
Me.AcceptPictureDrop
Me.AcceptFileDrop("JPEG")
End Sub
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
ListBox.SortColumn
**SortColumn**(Column As `Integer`) As `Boolean`
The user has clicked on the passed column header to sort that column or the Sort method was called. Column is zero-based.
`Return` `True` if you don't want the ListBox to be sorted.
Note that sorting is based on string comparisons. If you want to sort numbers, dates or CheckBoxes then you have to use a custom sort in the `ListBox` event.
If you're trying to prevent the user from sorting the column in the first place, use `ListBox`.
## Notes
Items in single-column ListBoxes can be accessed using the List property. The List property is an array. Arrays are zero-based. This means that the first row of the List property of a ListBox is row number 0 (zero).
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### Iterating through rows
The `Rows` method returns a `ListBoxRow` which allows you to easily iterate through rows. In this example, the Tag of each row is examined and if it's found to be "Taxable", the ComputeTaxes method is called and passed the value of the row.
``` xojo
For Each row As ListboxRow In Listbox1.Rows
If row.Tag = "Taxable" Then ComputeTaxes(row.Value)
Next
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### Configuring and accessing multiple columns
You can create multi-column ListBoxes by changing the ColumnCount property. The first column in a multi-column ListBox is column 0 (zero). This means that the ColumnCount property will always be one more than the number of the last column. The maximum number of columns is 256 (columns 0 through 255). You should set ColumnCount to the number of columns that you want to display. If you want to put data in an invisible column, set the column width to zero.
You can use the InitialValue property to set up the inital values of multi-column ListBoxes by separating the column values with tabs and row values with carriage returns.
The widths of columns in multi-column ListBoxes can be set by passing the widths as a list of values separated by commas to the ColumnWidths property. The widths can be passed in points or as percentages of the total width of the ListBox. If you don't pass widths for all the columns, the remaining columns will be evenly spaced over the remaining space. If too many widths are passed, the additional values are ignored. If the total of the widths passed is greater than the width of the ListBox, then the remaining columns will be truncated.
Specific cells in a multi-column ListBox can be accessed using the CellValueAt method. To populate a multi-column ListBox, first use the AddRow method to create the new row and populate the first column. Then use the CellValueAt method to add values to the other columns in the row. Use the LastAddedRowIndex property to get the index of the row you just added with AddRow.
For example, the following code populates a two-column ListBox with the names of the controls in the window and their indexes.
``` xojo
For i As Integer = 0 To Self.ControlCount - 1 ' number of controls in window
ListBox1.AddRow(Str(i)) ' first column
ListBox1.CellValueAt(Listbox1.LastAddedRowIndex, 1) = Control(i).Name ' second column
Next
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### Determining which cell was double-clicked
The DoubleClick event fires when the user double-clicks anywhere inside a ListBox, but the indexes of the cell that was double-clicked are not passed. You can determine which cell was double-clicked with the RowFromXY and ColumnFromXY methods. They use the x,y mouse coordinates where the double-click took place and translate them into the row and column indexes of the cell that was clicked. You need to adjust for the location of the ListBox on the screen relative to the top-left corner of the display.
This code in the MouseDown event obtains the indexes of the cell that was double-clicked.
``` xojo
Var row, column As Integer
row = Me.RowFromXY(x, y)
column = Me.ColumnFromXY(x, y)
MessageBox("You double-clicked in cell " + Str(row) + ", " + Str(column))
```
The parameters of RowFRomXY are relative to the top, left corner of the ListBox on a window. If you use the ListBox in a ContainerControl you have to take into account the distance of the container from the window edges.
``` xojo
Var row, column As Integer
row = Me.RowFromXY(System.MouseX - Me.Left - Self.Left - Me.TrueWindow.Left, System.MouseY - Me.Top - Self.Top - Me.TrueWindow.Top)
column = Me.ColumnFromXY(System.MouseX - Me.Left - Me.Parent.Left - Me.TrueWindow.Left, System.MouseY - Me.Top - Me.Parent.Top - Me.TrueWindow.Top)
MessageBox("You double-clicked in cell " + Str(row) + ", " + Str(column))
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### Making a cell editable
Use the CellTypeAt or ColumnTypeAt properties to change a cell or column to "inline editable" when you want the user to be able to edit the contents of the ListBox. Then call the EditCellAt method for each cell. This gives the focus to the editable cell and selects the current text of the cell, if any. Typing replaces the cell's contents. When the user presses Tab or Return or clicks in another cell, the cell loses the focus and the contents of the cell are saved.
The following code in the CellClick event makes the cell the user pressed on editable. The parameters row, and column are passed to the function.
``` xojo
Me.CellTypeAt(row, column) = ListBox.CellTypes.TextField
Me.EditCellAt(row, column)
```
When a cell is editable, the ActiveTextControl property is the `TextField` that contains the contents of that cell. You can use this property to set or get the text of the ListBox cell, set the selection, or change other properties of the ListBox's `TextField`.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### Decimal alignment
When you use decimal alignment in a cell or column, you must take into account the fact that the decimal separator is aligned with the right edge of the column or cell. You must pass a negative number to CellAlignmentOffsetAt or ColumnAlignmentOffsetAt to make room for the numbers to the right of the decimal place. The correct value to pass depends on the number of digits to the right of the decimal place in the column or cell.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### Resizing columns
There are two "modes" for column resizing. There is no formal mode property. Rather, the "mode" is implicitly set according to whether every column width is specified as an absolute amount. If you specify all columns either in points or as a percentage, you will be using the second mode. If you use an asterisk or leave a column width blank, you will be using the first mode.
- A change to one column width affects the width of another column.
If column i gets bigger, column i+1 gets smaller by the same amount. This mode is great when using a ListBox without a horizontal scrollbar. You turn this mode on when you have at least one column width that is blank, or specified using an asterisk (e.g. "", " ", "*", or "4*").
Note: By design you can't resize the right edge of the last column in this mode. To resize the last column you need to resize the previous column.
- Each column width is independent and can grow or shrink on its own.
You are responsible when the user does this, and you need to provide a horizontal scrollbar so that the user can get to the any headers that have been pushed out of view to the right. You enable this mode by making sure every column width is specified in terms of an absolute pixel width, or a percentage width (e.g. "20", or "35%"). If you use an asterisk or leave a column width blank, you will automatically be using the first mode.
You can switch between mode 1 and 2 at runtime using the same criteria as above.
The `ColumnWidths` property is equivalent to the concatenation of all of the ColumnWidthExpressions.
ColumnWidthExpressions are strings and they can represent several different types of column width calculations: absolute points (e.g., "45"), percentages (e.g. "22.3%"), and asterisk widths (or blanks), e.g. " ", "4\*". The value "*" is equivalent to "1*" and can be used to mean "fill the remaining space."
ColumnWidthExpressions retain their type even when a column is resized. This means that if you:
- Resize a window to which a ListBox is locked, it will grow or shrink. The columns grow or shrink as well if their expressions were *-based (unless you use "0*"), or percentage based (0%). If you want them to stay fixed, you need to express the ColumnWidthExpression as an absolute pixel value.
- Resize a column by dragging it internally, it will recompute its percentage or asterisk value. This is so that you can, say, start with a two-column ListBox with no column widths specified (each column will take up half the space). Then drag one column to take up 3/4 of the space, then enlarge the ListBox, and now both column widths will enlarge so that their widths remain in a 3/4 to 1/4 ratio.
Changing the pixel value of a column will not change its fundamental type, but will change the value of that type.
Finally, if you want to create columns that won't get resized, change the UserResizable property for each of the columns in question. If you are using mode 1, you will need to change the UserResizable property for both the column and the one to its left.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### Displaying data from a database
A ListBox is often used to display the results of database queries. A ListBox can be populated with the results of a query programmatically. See the example "Database Example" in the Examples folder.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### Creating checkbox cells
The CellCheckBoxStateAt method enables you to get or set the value of a tri-state Checkbox cell. Any cell of type `CheckBox` can store one of three values: Checked, Unchecked, and Indeterminate.
To set up a cell as a Checkbox, use code such as this in the Open event:
``` xojo
Me.CellTypeAt(1, 0) = ListBox.CellTypes.CheckBox
```
To change the state of the cell, use the `VisualStates` enumeration of the `CheckBox` control:
``` xojo
ListBox1.CellCheckBoxStateAt(1, 0) = CheckBox.VisualStates.Indeterminate
```
The Indeterminate state places a minus sign in the checkbox (macOS) or fills in checkbox (Windows and Linux).
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### Customized scroll controls
Suppose you want a horizontal scroll bar that leaves room for a pop-up menu. In this example, a `Scrollbar` control has been added to the bottom area of the ListBox and a `BevelButton` control has been added to its right. The two controls take up the area that would be used by the built-in horizontal scrollbar.
The `Scrollbar` control has the following code in its Open event handler:
``` xojo
Me.Maximum = 50
Me.Minimum = 0
Me.LineStep = 5
```
The values for Maximum and LineStep were chosen to match the total width of the ListBox's columns. Adjust these values to suit your ListBox. Its ValueChanged event handler has the following line of code:
``` xojo
ListBox1.ScrollPositionX = Me.Value
```
In this way, the user can scroll the ListBox horizontally, bringing all columns into view.
The `BevelButton` enables the user to switch the ListBox between single-line selection and multiple-line selection. The `BevelButton` is set to have a normal menu and its Open event handler populates the menu with two items:
``` xojo
Me.AddRow("Single-line")
Me.AddRow("Multiple-line")
```
The `BevelButton's` Action event sets the value of the ListBox's SelectionType property:
``` xojo
Select Case Me.MenuValue
Case 0
Listbox1.RowSelectionType = Listbox.RowSelectionTypes.Single
Case 1
ListBox1.RowSelectionType = Listbox.RowSelectionTypes.Multiple
End Select
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### Adding horizontal and vertical grid lines
You can show horizontal and vertical rules for the entire ListBox using the `GridLinesHorizontalStyle` and `GridLineVerticalStyle` properties. You can also display horizontal and verticals rules for specific cells by using the `CellBorderTopAt`, `CellBorderLeftAt`, `CellBorderRightAt`, and `CellBorderBottomAt` properties.
The Default value of these properties is equivalent to "None". Other choices are: ThinDotted, ThinSolid, ThickSolid and DoubleThinSolid.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### Displaying hierarchical rows
A hierarchical ListBox works like a tree view. Xojo uses the generic terms Expandable Rows to describe this style of ListBox. To allow for expandable rows, set the `AllowExpandableRows` property to true then rows can be expanded to display child content (and then collapsed later).
Windows uses plus and minus signs to indicate rows that are parents; macOS and Linux use disclosure triangles.
The following code, which is in the ListBox's Open event handler, populates a ListBox with expandable rows: The s1 string contains the parent level and sub1 contains the elements that are nested within each of s1's elements. It is a list of comma-delimited lists, with each list delimited by semicolons. The elements of sub1 are initially hidden because they are stored in a hidden column.
``` xojo
Var u As Integer
Var s1, sub1 As String
Me.ColumnWidths = "150,0"
s1 = "Michigan,Ohio,Minnesota"
sub1 = "Grand Blanc,Bad Axe,Flint,Benton Harbor,Detroit;Cleveland,Columbus,Akron,Pleasantville;St. Paul,Frostbite Falls"
u = CountFields(s1, ",")
For i As Integer =1 To u
If NthField(sub1, ";", i) <> "" Then
Me.AddExpandableRow("")
Me.CellValueAt(i - 1, 1) = NthField(sub1, ";", i)
End If
Me.CellValueAt(i - 1, 0) = NthField(s1, ",", i)
Next
Me.ColumnCount = 1
```
Note that the AddExpandableRow method, rather than AddRow, is used to add the State names.
The following line of code in the DoubleClick event handler toggles the expanded state of the row that was double-clicked:
``` xojo
Me.RowExpandedAt(Me.SelectedRowIndex) = Not Me.RowExpandedAt(Me.SelectedRowIndex)
```
The following code in the ExpandRow event handler runs when the user double-clicks a collapsed element:
``` xojo
Var s1 As String
Var u As Integer
s1 = Me.CellValueAt(row, 1)
u = CountFields(s1, ",")
For i As Integer = 1 To u
Me.AddRow("")
Me.CellValueAt(Me.LastAddedRowIndex, 0) = NthField(s1, ",", i)
Next
```
It creates the sublist rows each time the user double-clicks a collapsed state name.
If the ListBox has the `AllowExpandableRows` property selected, then collapsing is handled automatically when the user collapses an item. If `AllowExpandableRows` is false, then you need code such as this in the `CollapseRow` event handler:
``` xojo
Var u, numSubRows As Integer
numSubRows = CountFields(Me.Cell(row, 1), ",")
u = row + 1
For i As Integer = row + numSubRows DownTo u
Me.RemoveRowAt(i)
Next
```
It removes the rows that were created by the `ExpandRow` event handler.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### Drag and drop
The following example allows the user to drag one row from ListBox1 to ListBox2. ListBox1 has its `AllowRowDragging` property set to `True` and its `RowSelectionType` property set to `Single