Class # DesktopListBox

forsearch

Listbox --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ## Description The scrollable DesktopListBox control is used to display one or more columns of information. ## Properties

table-centered_columns_3_and_4

| Name | Type | Read-Only | Shared | |-------------------------------------------------------------------|----------------------------------------------------------------------|-----------|--------| | `Active` | `Boolean` | ✓ | | | `ActiveTextControl` | `DesktopTextControl` | ✓ | | | `AllowAutoDeactivate` | `Boolean` | | | | `AllowAutoHideScrollbars` | `Boolean` | | | | `AllowExpandableRows` | `Boolean` | | | | `AllowFocusRing` | `Boolean` | | | | `AllowResizableColumns` | `Boolean` | ✓ | | | `AllowRowDragging` | `Boolean` | | | | `AllowRowReordering` | `Boolean` | | | | `AllowTabStop` | `Boolean` | | | | `Bold` | `Boolean` | | | | `ColumnCount` | `Integer` | | | | `ColumnWidths` | `String` | | | | `DefaultRowHeight` | `Integer` | | | | `DropIndicatorVisible` | `Boolean` | | | | `Enabled` | `Boolean` | | | | `FontName` | `String` | | | | `FontSize` | `Single` | | | | `FontUnit` | `FontUnits` | | | | `GridLineStyle` | `GridLineStyles` | | | | `Handle` | `Ptr` | ✓ | | | `HasBorder` | `Boolean` | | | | `HasHeader` | `Boolean` | | | | `HasHorizontalScrollbar` | `Boolean` | | | | `HasVerticalScrollbar` | `Boolean` | | | | `HeaderHeight` | `Integer` | | | | `HeadingIndex` | `Integer` | | | | `Height` | `Integer` | | | | `Index` | `Integer` | | | | `InitialValue` | `String` | | | | `Italic` | `Boolean` | | | | `LastAddedRowIndex` | `Integer` | ✓ | | | `LastColumnIndex` | `Integer` | ✓ | | | `LastRowIndex` | `Integer` | ✓ | | | `Left` | `Integer` | | | | `LockBottom` | `Boolean` | | | | `LockLeft` | `Boolean` | | | | `LockRight` | `Boolean` | | | | `LockTop` | `Boolean` | | | | `MouseCursor` | `MouseCursor` | | | | `Name` | `String` | ✓ | | | `PanelIndex` | `Integer` | | | | `Parent` | `Object` | | | | `RequiresSelection` | `Boolean` | | | | `RowCount` | `Integer` | ✓ | | | `RowHeight` | `Integer` | ✓ | | | `RowSelectionType` | `RowSelectionTypes` | | | | `Scope` | `Integer` | ✓ | | | `ScrollPosition` | `Integer` | | | | `ScrollPositionX` | `Integer` | | | | `SelectedRowCount` | `Integer` | ✓ | | | `SelectedRowIndex` | `Integer` | | | | `SelectedRowText` | `String` | | | | `SortingColumn` | `Integer` | | | | `TabIndex` | `Integer` | | | | `Tooltip` | `String` | | | | `Top` | `Integer` | | | | `Transparent` | `Boolean` | | | | `Underline` | `Boolean` | | | | `Visible` | `Boolean` | | | | `Width` | `Integer` | | | | `Window` | `DesktopWindow` | ✓ | | ## Methods

table-centered_column_4

Name	Parameters	Returns
`AcceptFileDrop<desktoplistbox.acceptfiledrop>`	FileType As `String</api/data_types/string>`
`AcceptPictureDrop<desktoplistbox.acceptpicturedrop>`
`AcceptRawDataDrop<desktoplistbox.acceptrawdatadrop>`	Type As `String</api/data_types/string>`
`AcceptTextDrop<desktoplistbox.accepttextdrop>`
`AddAllRows<desktoplistbox.addallrows>`	items() As `String</api/data_types/string>`
	rows As `RowSet</api/databases/rowset>`
`AddExpandableRow<desktoplistbox.addexpandablerow>`	text As `String</api/data_types/string>`
`AddExpandableRowAt<desktoplistbox.addexpandablerowat>`	row As `Integer</api/data_types/integer>`, text As `String</api/data_types/string>`, indent As `Integer</api/data_types/integer>` = 0
`AddListSelectionNotificationReceiver<desktoplistbox.addlistselectionnotificationreceiver>`	receiver As `ListSelectionNotificationReceiver</api/language/listselectionnotificationreceiver>`
`AddRow<desktoplistbox.addrow>`	`ParamArray</api/language/paramarray>` Item As `String</api/data_types/string>`
`AddRowAt<desktoplistbox.addrowat>`	row As `Integer</api/data_types/integer>`, text As `String</api/data_types/string>`, depth As `Integer</api/data_types/integer>` = 0
`CellAlignmentAt<desktoplistbox.cellalignmentat>`	row As `Integer</api/data_types/integer>`, column As `Integer</api/data_types/integer>`	`DesktopListBox.Alignments<desktoplistbox.alignments>`
	row As `Integer</api/data_types/integer>`, column As `Integer</api/data_types/integer>`, `Assigns</api/language/assigns>` value As `DesktopListBox.Alignments<desktoplistbox.alignments>`
`CellAlignmentOffsetAt<desktoplistbox.cellalignmentoffsetat>`	row As `Integer</api/data_types/integer>`, column As `Integer</api/data_types/integer>`	`Integer</api/data_types/integer>`
	row As `Integer</api/data_types/integer>`, column As `Integer</api/data_types/integer>`, `Assigns</api/language/assigns>` value As `Integer</api/data_types/integer>`
`CellBoldAt<desktoplistbox.cellboldat>`	row As `Integer</api/data_types/integer>`, column As `Integer</api/data_types/integer>`	`Boolean</api/data_types/boolean>`
`CellBorderColorAt<desktoplistbox.cellbordercolorat>`	row As `Integer</api/data_types/integer>`, column As `Integer</api/data_types/integer>`	`ColorGroup</api/graphics/colorgroup>`
	row As `Integer</api/data_types/integer>`, column As `Integer</api/data_types/integer>`, `Assigns</api/language/assigns>` value As `ColorGroup</api/graphics/colorgroup>`
`CellCheckBoxStateAt<desktoplistbox.cellcheckboxstateat>`	row As `Integer</api/data_types/integer>`, column As `Integer</api/data_types/integer>`	`DesktopCheckBox.VisualStates<desktopcheckbox.visualstates>`
`CellCheckBoxValueAt<desktoplistbox.cellcheckboxvalueat>`	row As `Integer</api/data_types/integer>`, column As `Integer</api/data_types/integer>`	`Boolean</api/data_types/boolean>`
	row As `Integer</api/data_types/integer>`, column As `Integer</api/data_types/integer>`, `Assigns</api/language/assigns>` value As `Boolean</api/data_types/boolean>`
`CellItalicAt<desktoplistbox.cellitalicat>`	row As `Integer</api/data_types/integer>`, column As `Integer</api/data_types/integer>`	`Boolean</api/data_types/boolean>`
`CellTagAt<desktoplistbox.celltagat>`	row As `Integer</api/data_types/integer>`, column As `Integer</api/data_types/integer>`	`Variant</api/data_types/variant>`
	row As `Integer</api/data_types/integer>`, column As `Integer</api/data_types/integer>`, `Assigns</api/language/assigns>` value As `Variant</api/data_types/variant>`
`CellTextAt<desktoplistbox.celltextat>`	row As `Integer</api/data_types/integer>`, column As `Integer</api/data_types/integer>` = 0	`String</api/data_types/string>`
	row As `Integer</api/data_types/integer>`, column As `Integer</api/data_types/integer>`, `Assigns</api/language/assigns>` value As `String</api/data_types/string>`
`CellTooltipAt<desktoplistbox.celltooltipat>`	row As `Integer</api/data_types/integer>`, column As `Integer</api/data_types/integer>`	`String</api/data_types/string>`
`CellTypeAt<desktoplistbox.celltypeat>`	row As `Integer</api/data_types/integer>`, column As `Integer</api/data_types/integer>`	`DesktopListBox.CellTypes<desktoplistbox.celltypes>`
	row As `Integer</api/data_types/integer>`, column As `Integer</api/data_types/integer>`, `Assigns</api/language/assigns>` value As `DesktopListBox.CellTypes<desktoplistbox.celltypes>`
`CellUnderlineAt<desktoplistbox.cellunderlineat>`	row As `Integer</api/data_types/integer>`, column As `Integer</api/data_types/integer>`	`Boolean</api/data_types/boolean>`
`Close<desktoplistbox.close>`
`ColumnAlignmentAt<desktoplistbox.columnalignmentat>`	column As `Integer</api/data_types/integer>`	`DesktopListBox.Alignments<desktoplistbox.alignments>`
	column As `Integer</api/data_types/integer>`, `Assigns</api/language/assigns>` value As `DesktopListBox.Alignments<desktoplistbox.alignments>`
`ColumnAlignmentOffsetAt<desktoplistbox.columnalignmentoffsetat>`	column As `Integer</api/data_types/integer>`	`Integer</api/data_types/integer>`
	column As `Integer</api/data_types/integer>`, `Assigns</api/language/assigns>` value As `Integer</api/data_types/integer>`
`ColumnAttributesAt<desktoplistbox.columnattributesat>`	column As `Integer</api/data_types/integer>`	`DesktopListBoxColumn</api/user_interface/desktop/desktoplistboxcolumn>`
""	column As `Integer</api/data_types/integer>`, `Assigns</api/language/assigns>` value As `DesktopListBoxColumn</api/user_interface/desktop/desktoplistboxcolumn>`
`ColumnFromXY<desktoplistbox.columnfromxy>`	X As `Integer</api/data_types/integer>`, Y As `Integer</api/data_types/integer>`	`Integer</api/data_types/integer>`
`ColumnSortDirectionAt<desktoplistbox.columnsortdirectionat>`	column As `Integer</api/data_types/integer>`	`DesktopListBox.SortDirections<desktoplistbox.sortdirections>`
	column As `Integer</api/data_types/integer>`, `Assigns</api/language/assigns>` value As `DesktopListBox.SortDirections<desktoplistbox.sortdirections>`
`ColumnSortTypeAt<desktoplistbox.columnsorttypeat>`	column As `Integer</api/data_types/integer>`	`DesktopListBox.SortTypes<desktoplistbox.sorttypes>`
	column As `Integer</api/data_types/integer>`, `Assigns</api/language/assigns>` value As `DesktopListBox.SortTypes<desktoplistbox.sorttypes>`
`ColumnTagAt<desktoplistbox.columntagat>`	column As `Integer</api/data_types/integer>`	`Variant</api/data_types/variant>`
	column As `Integer</api/data_types/integer>`, `Assigns</api/language/assigns>` value As `Variant</api/data_types/variant>`
`ColumnTypeAt<desktoplistbox.columntypeat>`	column As `Integer</api/data_types/integer>`	`DesktopListBox.CellTypes<desktoplistbox.celltypes>`
	column As `Integer</api/data_types/integer>`, `Assigns</api/language/assigns>` value As `DesktopListBox.CellTypes<desktoplistbox.celltypes>`
`Content<desktoplistbox.content>`		`String</api/data_types/string>`
`DrawInto<desktoplistbox.drawinto>`	g As `Graphics</api/graphics/graphics>`, x As `Integer</api/data_types/integer>`, y As `Integer</api/data_types/integer>`
`EditCellAt<desktoplistbox.editcellat>`	row As `Integer</api/data_types/integer>`, column As `Integer</api/data_types/integer>`
`HeaderAt<desktoplistbox.headerat>`	index As `Integer</api/data_types/integer>`	`String</api/data_types/string>`
	index As `Integer</api/data_types/integer>`, `Assigns</api/language/assigns>` value As `String</api/data_types/string>`
`PressHeader<desktoplistbox.pressheader>`	column As `Integer</api/data_types/integer>`
`Refresh<desktoplistbox.refresh>`	immediately As `Boolean</api/data_types/boolean>` = `False</api/language/false>`
	x As `Integer</api/data_types/integer>`, y As `Integer</api/data_types/integer>`, width As `Integer</api/data_types/integer>`, height As `Integer</api/data_types/integer>`, immediately As `Boolean</api/data_types/boolean>` = `False</api/language/false>`
`RefreshCell<desktoplistbox.refreshcell>`	row As `Integer</api/data_types/integer>`, column As `Integer</api/data_types/integer>`
`RemoveAllRows<desktoplistbox.removeallrows>`
`RemoveListSelectionNotificationReceiver<desktoplistbox.removelistselectionnotificationreceiver>`	receiver As `ListSelectionNotificationReceiver</api/language/listselectionnotificationreceiver>`
`RemoveRowAt<desktoplistbox.removerowat>`	index As `Integer</api/data_types/integer>`
`RowAt<desktoplistbox.rowat>`	row As `Integer</api/data_types/integer>`	`DesktopListBoxRow</api/user_interface/desktop/desktoplistboxrow>`
`RowDepthAt<desktoplistbox.rowdepthat>`	row As `Integer</api/data_types/integer>`	`Integer</api/data_types/integer>`
`RowExpandableAt<desktoplistbox.rowexpandableat>`	row As `Integer</api/data_types/integer>`	`Boolean</api/data_types/boolean>`
`RowExpandedAt<desktoplistbox.rowexpandedat>`	v As `Integer</api/data_types/integer>`	`Boolean</api/data_types/boolean>`
`RowFromXY<desktoplistbox.rowfromxy>`	X As `Integer</api/data_types/integer>`, Y As `Integer</api/data_types/integer>`	`Integer</api/data_types/integer>`
`RowImageAt<desktoplistbox.rowimageat>`	index As `Integer</api/data_types/integer>`	`Picture</api/graphics/picture>`
`Rows<desktoplistbox.rows>`		`Iterable</api/language/iterable>`
`RowSelectedAt<desktoplistbox.rowselectedat>`	index As `Integer</api/data_types/integer>`	`Boolean</api/data_types/boolean>`
	index As `Integer</api/data_types/integer>`, `Assigns</api/language/assigns>` value As `Boolean</api/data_types/boolean>`
`RowTagAt<desktoplistbox.rowtagat>`	row As `Integer</api/data_types/integer>`	`Variant</api/data_types/variant>`
`SetFocus<desktoplistbox.setfocus>`
`Sort<desktoplistbox.sort>`

## Events

table-centered_column_4

| Name | Parameters | Returns | |-------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------| | `CellAction` | row As `Integer`, column As `Integer` | | | `CellFocusLost` | row As `Integer`, column As `Integer` | | | `CellFocusReceived` | row As `Integer`, column As `Integer` | | | `CellKeyDown` | row As `Integer`, column As `Integer`, key As `String` | `Boolean` | | `CellPressed` | row As `Integer`, column As `Integer`, x As `Integer`, y As `Integer` | `Boolean` | | `CellTextChanged` | row As `Integer`, column As `Integer` | | | `Closing` | | | | `ColumnSorted` | column As `Integer` | `Boolean` | | `ConstructContextualMenu` | Base As `DesktopMenuItem`, x As `Integer`, y As `Integer` | `Boolean` | | `ContextualMenuItemSelected` | selectedItem As `DesktopMenuItem` | `Boolean` | | `DoublePressed` | | | | `DragEnter` | obj As `DragItem`, Action As `DragItem.Types` | `Boolean` | | `DragExit` | obj As `DragItem`, Action As `DragItem.Types` | | | `DragOver` | x As `Integer`, y As `Integer`, obj As `DragItem`, Action As `DragItem.Types` | `Boolean` | | `DragOverRow` | x As `Integer`, y As `Integer`, obj As `DragItem`, action As `Integer`, `ByRef` row As `Integer`, `ByRef` parentRow As `Integer`, `ByRef` location As `DesktopListBox` | `Boolean` | | `DragReorderRows` | NewPosition As `Integer`, ParentRow As `Integer` | `Boolean` | | `DragRow` | Drag As `DragItem`, Row As `Integer` | `Boolean` | | `DropObject` | Obj As `DragItem`, Action As `DragItem.Types` | | | `DropObjectOnRow` | x As `Integer`, y As `Integer`, obj As `DragItem`, action As `Integer`, row As `Integer`, parentRow As `Integer`, location As `DesktopListBox` | | | `FocusLost` | | | | `FocusReceived` | | | | `HeaderPressed` | Column As `Integer` | `Boolean` | | `KeyDown` | Key As `String` | `Boolean` | | `KeyUp` | Key As `String` | | | `MenuBarSelected` | | | | `MouseDown` | X As `Integer`, Y As `Integer` | `Boolean` | | `MouseDrag` | X As `Integer`, Y As `Integer` | | | `MouseEnter` | | | | `MouseExit` | | | | `MouseMove` | X As `Integer`, Y As `Integer` | | | `MouseUp` | X As `Integer`, Y As `Integer` | | | `MouseWheel` | X As `Integer`, Y As `Integer`, DeltaX As `Integer`, DeltaY As `Integer` | `Boolean` | | `Opening` | | | | `PaintCellBackground` | g As `Graphics`, Row As `Integer`, Column As `Integer` | `Boolean` | | `PaintCellText` | g As `Graphics`, Row As `Integer`, Column As `Integer`, x As `Integer`, y As `Integer` | `Boolean` | | `PaintDisclosureWidget` | g As `Graphics`, row As `Integer`, `ByRef` x As `Integer`, `ByRef` y As `Integer`, `ByRef` width As `Integer`, `ByRef` height As `Integer` | `Boolean` | | `PaintHeaderBackground` | g As `Graphics`, column As `Integer` | `Boolean` | | `PaintHeaderContent` | g As `Graphics`, column As `Integer` | `Boolean` | | `RowCollapsed` | row As `Integer` | | | `RowComparison` | Row1 As `Integer`, row2 As `Integer`, Column As `Integer`, `ByRef` Result As `Integer` | `Boolean` | | `RowExpanded` | row As `Integer` | | | `SelectionChanged` | | | ## Constants > These constants are designed to be used with some DesktopListbox methods to make code more readable. > > | Name | Description | > |-------------|-----------------------------------------------------------------------| > | AllColumns | A value that indicates all of the columns rather than a specific row. | > | AllRows | A value that indicates all of the rows rather than a specific row | > | NoSelection | A value that indicates that no row is selected. | ## Enumerations

forsearch

DesktopListBox.Alignments ### Alignments > Used to indicate how data in a column should be aligned. > > | Enum | Description | > |---------|------------------------------------------------------| > | Default | The OS-specific default alignment. | > | Left | The cell value will be left-justified. | > | Center | The cell value will be center-aligned. | > | Right | The cell value will be right-justified. | > | Decimal | The cell value will be aligned to the decimal point. |

forsearch

DesktopListBox.CellTypes ### CellTypes > Used to indicate what type a cell should be (Normal, CheckBox, TextField or TextArea). > > | Enum | Description | > |-----------|----------------------------------------------------------------------------| > | Default | The default type for a cell. The default is Normal. | > | Normal | A cell that can't be edited directly by the end user. | > | CheckBox | The cell contains only a checkbox. | > | TextField | A cell that can be edited by the end user allowing a single line of text. | > | TextArea | A cell that can be edited by the end user allowing multiple lines of text. |

forsearch

DesktopListBox.DropLocations ### DropLocations > Used to indicate where on the ListBox an object was dropped. > > | Enum | Description | > |--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| > | OnRow | The drop is occurring on the row itself. | > | AfterRow | The drop is occurring between rows, after the row specified. The row can be in the range of \[-1, RowCount-1\] and specifying -1 will insert it at the top of all the rows. This value will also be RowCount-1 if the user drags below the item list. | > | AfterAllRows | The drop is occurring after all rows in the list. | > | OnControl | The drop is occurring on the entire control, not on a particular row. This matches the previous behavior. |

forsearch

DesktopListBox.GridLineStyles ### GridLineStyles > Used to indicate if vertical and/or horizontal gridlines should appear or not. > > | Enum | Description | > |------------|-----------------------------------------| > | None | No gridlines. This is the default. | > | Horizontal | Horizontal gridlines only. | > | Vertical | Vertical gridlines only. | > | Both | Both horizontal and vertical gridlines. |

forsearch

DesktopListBox.RowSelectionTypes ### RowSelectionTypes > Used to indicate if the selection can be one or more rows. > > | Enum | Description | > |----------|------------------------------------------------------| > | Single | Only one row is selectable at a time. | > | Multiple | Any number of rows may be selected at the same time. |

forsearch

DesktopListBox.SortDirections ### SortDirections > Used to indicate if a column's sorting should be ascending, descending or none. > > | Enum | Description | > |------------|-----------------------------------------------------| > | Descending | Rows are sorted in reverse alphabetical order. | > | None | The rows are unsorted. | > | Ascending | The rows are sorted in standard alphabetical order. |

forsearch

DesktopListBox.SortTypes ### SortTypes > Used to indicate if a column is sortable or not. > > | Enum | Description | > |-------------|----------------------------------------------------------------------------------------------------------------| > | Sortable | The column header includes a widget allowing the end user to sort the contents of the column. | > | NotSortable | The column header does not include a sorting widget, preventing the end user from sorting the column contents. | ## Property descriptions

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

forsearch

DesktopListBox.Active **Active** As `Boolean` > Indicates whether the `control` is active. > > Active is `False` when the control's window is not in the foreground. When a `DesktopWindow` is deactivated, its controls are automatically deactivated unless `AllowAutoDeactivate` is set to `False`. > > This property is read-only.

forsearch

DesktopListBox.ActiveTextControl **ActiveTextControl** As `DesktopTextControl` > The `DesktopTextArea` or `DesktopTextField` that the **ListBox** uses for its editable cell operations. > > This property is read-only. > > The `DesktopTextControl` can be either a `DesktopTextField` or a `DesktopTextArea` control. To specify which one, the **ListBox** uses the two following `DesktopListBox` values: > > ``` xojo > DesktopListBox.CellTypes.TextArea > DesktopListBox.CellTypes.TextField > ``` > > For example, > > ``` xojo > ListBox1.CellTypeAt(1, 0) = DesktopListBox.CellTypes.TextField > ``` > > To get this `DesktopTextField`, you must put the cell into the Inline Editable mode via the `CellTypeAt` or `ColumnTypeAt` properties and make it editable by calling the `EditCellAt` method. You can use this property to set or get the text of the ListBox cell (using `SelectedText`), set the selection, or change other properties of the ListBox's `DesktopTextField`.

forsearch

DesktopListBox.AllowAutoDeactivate **AllowAutoDeactivate** As `Boolean` > Determines whether the control should be deactivated (on macOS) when the parent window is deactivated. The default is `True`.

forsearch

DesktopListBox.AllowAutoHideScrollbars **AllowAutoHideScrollbars** As `Boolean` > Controls whether scrollbars are shown when scrolling is not necessary to bring additional text into view. The default is `True`. > > The vertical scroll does not appear until there are more items in the **ListBox** than can be viewed at once. If AllowAutoHideScrollbars is `False`, then inactive scrollbars are shown until they are needed to bring additional text into view. AllowAutoHideScrollbars can be set at design time or runtime. > > This example turns off AllowAutoHideScrollbars. > > ``` xojo > Me.AllowAutoHideScrollbars = False > ```

forsearch

DesktopListBox.AllowExpandableRows **AllowExpandableRows** As `Boolean` > Allows for disclosure triangles for rows added via the AddExpandableRow method. > > On Windows, plus and minus signs are used instead of disclosure triangles.

forsearch

DesktopListBox.AllowFocusRing **AllowFocusRing** As `Boolean` > If `True`, the control indicates when it has the focus by drawing a ring around its border. If `False`, the appearance of the control does not change when it has the focus. > >

> >

> > Note > >

> > AllowFocusRing is not supported on Windows as this UI concept does not exist on Windows. > >

forsearch

DesktopListBox.AllowResizableColumns **AllowResizableColumns** As `Boolean` > If `True`, the user can resize columns by moving the pointer over a column divider and dragging to the left or right. > > This property is read-only. > > When the pointer is over a divider, it changes to an East-West Splitter pointer to indicate that the user can drag the divider. If AllowResizableColumns is `False`, the pointer does not change its shape. > > This example enables the resizable feature. > > ``` xojo > Me.AllowResizableColumns = True > ```

forsearch

DesktopListBox.AllowRowDragging **AllowRowDragging** As `Boolean` > Allows rows to be dragged. > > 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 zero (Single). Its DragRow event handler is as follows: > > ``` xojo > Function DragRow(drag As DragItem, row As Integer) As Boolean > drag.Text = Me.CellTextAt(row, 0) > Return True ' allow the drag > End Function > ``` > > ListBox2's Opening event handler has the line: > > ``` xojo > Me.AcceptTextDrop > ``` > > Its DropObject event handler is this: > > ``` xojo > Sub DropObject(obj As DragItem) > Me.AddRow(obj.Text) ' adds the dropped text as a new row > End Sub > ``` > > The following example allows the user to drag more than one row from ListBox1 to ListBox2. The dragged rows are added to the end of the list. > > ListBox1 has its AllowRowDragging property set to `True`, enabling items in its list to be dragged, and its RowSelectionType property set to 1 (Multiple row selection). Its DragRow event handler is as follows: > > ``` xojo > Function DragRow (drag As DragItem, row As Integer) As Boolean > Var nRows, i As Integer > nRows = Me.LastRowIndex > For i = 0 To nRows > If Me.RowSelectedAt(i) Then > drag.AddItem(0, 0, 20, 4) > drag.Text = Me.SelectedRowText ' get text > End If > Next > Return True ' allow the drag > End Function > ``` > > It uses the AddItem method of the `DragItem` to add an additional item to the DragItem each selected row. The DropObject event handler then cycles through all items to retrieve all dragged rows. > > ListBox2 has the following line of code in its Opening event handler. It permits it to receive dragged text. > > ``` xojo > Me.AcceptTextDrop > ``` > > Its DropObject event handler checks to see if the dragged object is text; if it is, it adds a row to the end of the list and assigns the text property of the dragged object to the new row: It loops through all items in the DragItem until NextItem returns `False`. > > ``` xojo > Sub DropObject(obj As DragItem) > Do > If obj.TextAvailable Then > Me.AddRow(obj.Text) > End If > Loop Until Not obj.NextItem > End Sub > ```

forsearch

DesktopListBox.AllowRowReordering **AllowRowReordering** As `Boolean` > If `True`, you can reorder rows within the DesktopListBox by dragging rows. > > An insertion line indicator appears when dragging within the DesktopListBox to provide you with visual feedback as to where the row would be dropped if you release the mouse button. > > This example enables the drag reorder feature. > > ``` xojo > Me.AllowRowReordering = True > ```

forsearch

DesktopListBox.AllowTabStop **AllowTabStop** As `Boolean` > If `True`, the control is in the Tab Order and accepts the focus when the user tabs into it. The default is `True`. If `False`, the user cannot tab into it to give it the focus. However, the control can gain the focus by other means, such as the user's clicking on it or by setting the focus in code. > > This example removes the control from the Tab Order: > > ``` xojo > Me.AllowTabStop = False > ```

forsearch

DesktopListBox.Bold **Bold** As `Boolean` > If `True`, applies the bold style to the DesktopListBox text content. > > Mac apps can only display font styles that are available. You cannot force a font to display in bold or italic if it does not have bold or italic variations available. In this situation, the Bold property will not affect the font. > > This example sets the text to Bold. > > ``` xojo > Me.Bold = True > ```

forsearch

DesktopListBox.ColumnCount **ColumnCount** As `Integer` > The number of columns the ListBox contains. The maximum number of columns is 256. > > Setting this value higher than 255, will result in the ColumnCount being set to 256. > > Adding a column to ListBox1 and setting the widths of the columns to 50 and 65 points, respectively: > > ``` xojo > ListBox1.ColumnCount = 2 > ListBox1.ColumnWidths = "50,65" > ``` > > Setting the number of columns of ListBox1 to three and setting the widths of the columns to 60%, 20% and 20% respectively: > > ``` xojo > ListBox1.ColumnCount = 3 > ListBox1.ColumnWidths = "60%,20%,20%" > ```

forsearch

DesktopListBox.ColumnWidths **ColumnWidths** As `String` > A list of comma-separated values, with each value controlling the width of the associated column. A value can be an absolute value (in points), a percentage, a relative length expressed as *i*\* where *i* is an integer, or an "\*" that indicates "fill in the remaining width." If you use percentages, you can use non-integer values to specify fractions of a percent, e.g., 43.52%. The percentage value can be greater than 100%. > > If you use points, the last column doesn't grow to the size of the rest of the ListBox. You should set the width of the last column to "\*" and it will automatically take up the remaining width of the DesktopListBox. > > Without any column width specifications, the headers will be divided evenly. If there are fewer column widths specified than the total number of columns, the remaining columns will divide up the remaining width equally. > > An element with a length of "3\*" will be allotted three times the space of an element with length "1\*". The value "*" is equivalent to "1*" and can be used to mean "fill the remaining space." > > You can use a mixture of points, percentages, and relative lengths. Column widths specified in points are guaranteed to have the specified width. Column widths specified in percentages are guaranteed to have that percentage of the visible width of the DesktopListBox. The column widths specified using the \* divide up the remaining width proportionally. For example, if there are four columns, the specification 20, 20%, *, 2* gives 20 points to the first column 20% of the total to the second column, and the last two columns divide up the remaining width in the ratio of 1:2, with the last column getting any remaining fractional points. > > Unrecognized or unsupported expressions (e.g. '2@')for the column width properties will result in an `UnsupportedFormatException`. The message of this exception describes in English what went wrong. > > Resizing a column will resize the value of the expression. If you resize the **ListBox**, both the percentage and relative lengths recompute their actual widths. There are two resizing "modes"; see notes. > > Header End caps are added for any additional unused space if headers are used. Header end caps do nothing when clicked. > > Adding a column to ListBox1 and setting the widths of the columns to 50 and 65 points, respectively: > > ``` xojo > ListBox1.ColumnCount = 2 > ListBox1.ColumnWidths = "50,65" > ``` > > Setting the number of columns of ListBox1 to three and setting the widths of the columns to 60%, 20% and 20% respectively: > > ``` xojo > ListBox1.ColumnCount = 3 > ListBox1.ColumnWidths = "60%,20%,20%" > ``` > > If ListBox1 is 100 points wide and has three columns, the following code will set the columns widths as indicated but the last column will only be 10 points wide instead of 20: > > ``` xojo > ListBox1.ColumnWidths = "60,30,20" > ``` > > If ListBox1 is 100 points wide and has three columns, the following code will set the columns widths but the last column will not be displayed: > > ``` xojo > ListBox1.ColumnWidths = "60,40,20" > ```

forsearch

DesktopListBox.DefaultRowHeight **DefaultRowHeight** As `Integer` > Determines the height of every row in the DesktopListBox in points. Every row in the ListBox is always the same height. > > Use a value of -1 to have the height automatically determined by the current font size. > > This example increases the default row height. > > ``` xojo > Me.DefaultRowHeight = 35 > ```

forsearch

DesktopListBox.DropIndicatorVisible **DropIndicatorVisible** As `Boolean` > Determines whether or not the drop indicators appears. This property changes the appearance of the listbox. It does not prevent the new events from firing.

forsearch

DesktopListBox.Enabled **Enabled** As `Boolean` > Determines if the control should be enabled when the owning window is opened. > > A disabled control cannot be clicked and cannot receive the focus. > > This example disables the control. > > ``` xojo > Me.Enabled = False > ```

forsearch

DesktopListBox.FontName **FontName** As `String` > Name of the font used to display text. > > You can enter any font that is installed on the computer or the names of the two metafonts, "System" and "SmallSystem". > > The System font is the font used by the system software as its default font. Different operating systems use different default fonts. If the system software supports both a large and small System font, you can also specify the "SmallSystem" font as your TextFont. > > On macOS, "SmallSystem" specifies the OS's smaller system font and may make the control smaller in size as well. On Windows and Linux, "SmallSystem" is the same as "System". > > This code sets the FontName property. > > ``` xojo > Me.FontName = "Helvetica" > ```

forsearch

DesktopListBox.FontSize **FontSize** As `Single` > Size of the font used to display text. > > If you enter zero as the FontSize, your app will use the font size that works best for the platform on which it is running. > > This code sets the font size to 16. > > ``` xojo > Me.FontSize = 16 > ```

forsearch

DesktopListBox.FontUnit **FontUnit** As `FontUnits` > The units in which FontSize is measured.

forsearch

DesktopListBox.GridLineStyle **GridLineStyle** As `GridLineStyles` > The orientations of gridlines that can be displayed.

forsearch

DesktopListBox.Handle **Handle** As `Ptr` > Returns a handle to the control. > > This property is read-only. > > For interfacing with macOS APIs using `Declares`, **DesktopControl.Handle** returns NSViews (except for `DesktopToolbar`). > > On Windows returns the HWND of the control. > > On Linux it returns a GtkWidget. > > The following gets a handle to the control. > > ``` xojo > Var p As Ptr = Me.Handle > ```

forsearch

DesktopListBox.HasBorder **HasBorder** As `Boolean` > Indicates whether or not the border is visible.

forsearch

DesktopListBox.HasHeader **HasHeader** As `Boolean` > If `True`, a row of column headers is added to the DesktopListBox. The user can sort the column by clicking the heading if `ColumnSortDirectionAt` is `True` not set to None for that column. > > This property is `True` by default. > > The following example shows the Headers row. The code is in the Opening event of the control. > > ``` xojo > Me.HasHeader = True > ```

forsearch

DesktopListBox.HasHorizontalScrollbar **HasHorizontalScrollbar** As `Boolean` > If `True`, adds a horizontal scrollbar to the DesktopListBox. > > The horizontal scrollbar only appears if the sum of the widths of the columns exceeds the width of the ListBox itself. If the widths of the columns is less than (or matches) the width of the DesktopListBox, then no horizontal scrollbar appears. > > The position of the thumb is indicated by ScrollPositionX. It is used to scroll the DesktopListBox horizontally without a separate `DesktopScrollbar` control.

forsearch

DesktopListBox.HasVerticalScrollbar **HasVerticalScrollbar** As `Boolean` > If `True`, adds a vertical scrollbar to the DesktopListBox. The position of the thumb is indicated by ScrollPosition. The default is `True`.

forsearch

DesktopListBox.HeaderHeight **HeaderHeight** As `Integer` > The height of the header row in points. > > This example displays the height of the header row. It is in the Pressed event of a `DesktopButton` control. > > ``` xojo > Var h As Integer = Listbox1.HeaderHeight > ```

forsearch

DesktopListBox.HeadingIndex **HeadingIndex** As `Integer` > Allows you to get and set the sort column in a DesktopListBox. The first column is numbered zero. > > Using this property sets the sort direction indicator in the header. > > You can also sort a ListBox by using the `SortingColumn` property to set the sort column and the `ColumnSortDirectionAt` property to set the direction of the sort. Then call the `Sort` method to do the sort. > > This code in the Opening event of a DesktopListBox sorts on the first column: > > ``` xojo > Me.SortingColumn = 0 > Me.ColumnSortDirectionAt(0) = DesktopListBox.SortDirections.Ascending > Me.HeadingIndex = 0 > Me.Sort > ```

forsearch

DesktopListBox.Height **Height** As `Integer` > The height (in points) of the control. > > This example sets the height of the control to 100: > > ``` xojo > Me.Height = 100 > ```

forsearch

DesktopListBox.Index **Index** As `Integer` > If the control is used in a control set, this specifies the control's index in the set.

forsearch

DesktopListBox.InitialValue **InitialValue** As `String` > A list of the default items separated by returns. > > If the DesktopListBox has more than one column (ColumnCount \> 1), separate column entries with Tabs within each row. If HasHeader is `True`, the first row of InitialValue is assumed to be the column headings -- unless the Heading array is also specified. > > This is a **design-time-only** property.

forsearch

DesktopListBox.Italic **Italic** As `Boolean` > If `True`, applies the italic style to the DesktopListBox text. > > Mac apps can only display font styles that are available. You cannot force a font to display in bold or italic if it does not have bold or italic variations available. In this situation, the Italic property will not affect the font. > > The following sets the Italic property for the DesktopListBox. > > ``` xojo > Me.Italic = True > ```

forsearch

DesktopListBox.LastAddedRowIndex **LastAddedRowIndex** As `Integer` > The number of the last row added with the AddRow, AddExpandableRow, or AddRowAt method. If no rows have been added, LastAddedRowIndex will be -1. Use this to get the row number when getting or setting values in a multi-column **ListBox**. See the section on Multi-column listboxes in the Notes section. > > This property is read-only. > > This example project consists of a two-column DesktopListBox and two `DesktopTextFields` for the entry of first and last names. A `DesktopButton` creates a new row in the DesktopListBox and adds the contents of the `DesktopTextFields` to the DesktopListBox. > > ``` xojo > PeopleList.Addrow("") > PeopleList.CellTextAt(PeopleList.LastAddedRowIndex, 0) = FirstNameField.Text > PeopleList.CellTextAt(PeopleList.LastAddedRowIndex, 1) = LastNameField.Text > PeopleList.SelectedRowIndex = PeopleList.LastAddedRowIndex ' select the newly added row > FirstNameField.SetFocus > ``` > > This code asks the user to add a row if they have not yet done so: > > ``` xojo > If ListBox1.LastAddedRowIndex = DesktopListBox.NoSelection then > System.Beep > MessageBox("Please add a row to continue.") > End If > ```

forsearch

DesktopListBox.LastColumnIndex **LastColumnIndex** As `Integer` > The number of the last column of the DesktopListBox. Because (like nearly all of Xojo) the DesktopListBox is zero-based, this value will be 1 less than the `DesktopListBox`. > > This property is read-only.

forsearch

DesktopListBox.LastRowIndex **LastRowIndex** As `Integer` > The number of the last row of the DesktopListBox. Like nearly all of Xojo, the DesktopListBox is zero-based which means this value will be 1 less than the `RowCount`. > > This property is read-only.

forsearch

DesktopListBox.Left **Left** As `Integer` > The distance from the left side of the control to the left side of its containing window or container. > > The following example moves the control 100 points from the left side of the window: > > ``` xojo > Me.Left = 150 > ```

forsearch

DesktopListBox.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

DesktopListBox.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. > > 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

DesktopListBox.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

DesktopListBox.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. > > 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

DesktopListBox.MouseCursor **MouseCursor** As `MouseCursor` > The cursor to be displayed while the mouse is within the control and both the `DesktopApplication` and `DesktopWindow` class's MouseCursor properties are `Nil`. > > If the `DesktopApplication` class's MouseCursor property is not `Nil` or the `DesktopWindow`'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 macOS, you can also obtain a `MouseCursor` from a resource file. > > This line in the Opening event of the control sets the default cursor to the finger pointer. > > ``` xojo > Me.MouseCursor = System.Cursors.FingerPointer > ```

forsearch

DesktopListBox.Name **Name** As `String` > The name of the control. Set the name of the control in the Inspector. > > This property is read-only.

forsearch

DesktopListBox.PanelIndex **PanelIndex** As `Integer` > If the control has been placed on a `DesktopTabPanel` or `DesktopPagePanel` 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 `DesktopTabPanel` or `DesktopPagePanel` control, it returns the panel number. If the control is not on a `DesktopPagePanel` or `DesktopTabPanel`, 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 `DesktopPagePanel`. > > This code displays the panel index of the control that is on the page. > > ``` xojo > MessageBox(Me.SelectedPanelIndex.ToString) > ```

forsearch

DesktopListBox.Parent **Parent** As `Object` > Used to get and set the control's parent control or window. > > If the control is on the window, the Parent will be the `Window`. If the control is on the container, the Parent will be the `container`. If the control is completed enclosed by another control, the Parent will be that `control`. > > If you do not want the enclosing control to be the parent, set the Parent property of that control to `Nil` to make it the `Window`. > > 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

DesktopListBox.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 DesktopListBox.NoSelection.

forsearch

DesktopListBox.RowCount **RowCount** As `Integer` > The number of rows in the DesktopListBox. > > This property is read-only.

forsearch

DesktopListBox.RowHeight **RowHeight** As `Integer` > Gets the DesktopListBox row height. All rows in a DesktopListBox are always the same height, which you can change using `DefaultRowHeight`. > > This property is read-only.

forsearch

DesktopListBox.RowSelectionType **RowSelectionType** As `RowSelectionTypes` > Indicates the type of row selection allowed via mouse gestures. > > The type of allowed row selection is set via `DesktopListBox`. > > The default is single-row selection. If multiple row selection is on, a DesktopListBox will handle Edit \> Select All menu item commands by default as long as the Select All menu item is named **EditSelectAll**.

forsearch

DesktopListBox.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. > >

> >

> > Note > >

> > This is a designtime-only property and thus can only be set in the Inspector and is not accessible via code. > >

> > If the Scope of a control is set to Private, it cannot be accessed from outside its parent window.

forsearch

DesktopListBox.ScrollPosition **ScrollPosition** As `Integer` > 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. > > This example, scrolls ListBox1 to the last visible row: > > ``` xojo > ListBox1.ScrollPosition = ListBox1.LastRowIndex > ```

forsearch

DesktopListBox.ScrollPositionX **ScrollPositionX** As `Integer` > Index of the horizontal position of the DesktopListBox.

forsearch

DesktopListBox.SelectedRowCount **SelectedRowCount** As `Integer` > The number of rows selected (highlighted). > > This property is read-only.

forsearch

DesktopListBox.SelectedRowIndex **SelectedRowIndex** As `Integer` > The number of the selected row. > > If no item is selected, SelectedRowIndex returns DesktopListBox.NoSelection. If the DesktopListBox 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 DesktopListBox into multiple-row selection mode by changing the `RowSelectionType` property. > > The following code in the `SelectionChanged` event handler displays the text in the first column of the selected row: > > ``` xojo > If Me.SelectedRowIndex >= 0 Then > MessageBox(Me.CellTextAt(Me.SelectedRowIndex, 0)) > End If > ``` > > The following code displays a message if no row is selected: > > ``` xojo > If ListBox1.SelectedRowIndex = DesktopListBox.NoSelection Then > MessageBox("Please select a row first.") > End If > ``` > > This example selects the first row in the ListBox: > > ``` xojo > ListBox1.SelectedRowIndex = 0 > ```

forsearch

DesktopListBox.SelectedRowText **SelectedRowText** As `String` > The text of the currently selected item. > > In the case of multi-column ListBoxes, the value of the cell in the first column is returned.

forsearch

DesktopListBox.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 DesktopButton asks the user to sort on a column if the DesktopListBox is not sorted by any column: > > ``` xojo > If Listbox1.SortingColumn = DesktopListBox.None then > System.Beep > MessageBox("Please sort the rows by one of the columns.") > End If > ```

forsearch

DesktopListBox.TabIndex **TabIndex** As `Integer` > The control's position in the Tab Order. The control with whose TabIndex is 0 will get the focus first. > > On macOS, only controls where you enter data from the keyboard typically get the focus. In order to manually set focus to controls that don't allow keyboard entry, go to System Preferences, click on the Keyboard icon then on the Shortcuts tab and then check the *Use keyboard navigation to move focus between controls* checkbox. > > This example sets the control's TabIndex. > > ``` xojo > Me.TabIndex = 2 > ```

forsearch

DesktopListBox.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 control: > > ``` xojo > Me.Tooltip = "Click to bark." > ```

forsearch

DesktopListBox.Top **Top** As `Integer` > The distance from the top of the control to the top of its containing window or container. > > This example sets the top of the control to 140 points from the top of the window: > > ``` xojo > Me.Top = 140 > ```

forsearch

DesktopListBox.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

DesktopListBox.Underline **Underline** As `Boolean` > If `True`, applies the underline style of the text. > > This code underlines the text in the control: > > ``` xojo > Me.Underline = True > ```

forsearch

DesktopListBox.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 makes the control invisible: > > ``` xojo > Me.Visible = False > ```

forsearch

DesktopListBox.Width **Width** As `Integer` > The width (in points) of the control. > > The following example resizes the control: > > ``` xojo > Me.Width = 200 > ```

forsearch

DesktopListBox.Window **Window** As `DesktopWindow` > The control's parent window. > > This property is read-only. > > This code gets the parent window's Title property. > > ``` xojo > MessageBox(Me.Window.Title) > ``` ## Method descriptions

forsearch

DesktopListBox.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 Opening event 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

DesktopListBox.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 Opening event of the control itself. For example, the line: > > ``` xojo > Me.AcceptPictureDrop > ``` > > in the Opening 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. > > Opening Event: > > ``` xojo > Me.AcceptPictureDrop > ``` > > DropObject Event: > > ``` xojo > If obj.PictureAvailable Then > Me.Backdrop = obj.Picture > End If > ```

forsearch

DesktopListBox.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

DesktopListBox.AcceptTextDrop **AcceptTextDrop** > Permits text to be dropped on the control. > > This line in the Opening event of a control that can accept dragged text. > > ``` xojo > Me.AcceptTextDrop > ```

forsearch

DesktopListBox.AddAllRows **AddAllRows**(`ParamArray` item As `String`) > Adds *item* in a new row to the end of the list. Because it is called as a ParamArray, you can pass several items causing each item to be the value for a new row. **AddAllRows**(items() As `String`) > Adds a new row to the end of the list with each element of *items* as a separate row. **AddAllRows**(rows As `RowSet`) > Adds *rows* from the RowSet to the ListBox. If the ListBox does not have enough columns, more columns will be added.

forsearch

DesktopListBox.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`. > > When configured to have more than one column, *text* is always assigned to column zero. In the case where `AllowExpandableRows` is `True`, AddExpandableRow adds *text* to the subitems of the expanded row when called in the `RowExpanded` event. > > The following example adds expandable rows. Note that AddExpandableRow must be called to create the hierarchical relationship. > > ``` xojo > Var s1, sub1 As String > > s1 = "Michigan,Ohio,Minnesota" > sub1 = "Grand Blanc,Bad Axe,Flint,Benton Harbor,"_ > + "Detroit;Cleveland,Columbus,Akron,Pleasantville;St. Paul,Frostbite Falls" > > Me.ColumnCount = 1 > Me.ColumnWidths = "150,0" > > For i As Integer = 1 To s1.ToArray(",").Count > If Not sub1.NthField(";", i).IsEmpty Then > Me.AddExpandableRow("") > Me.CellTextAt(i - 1, 1) = sub1.NthField(";", i) > End If > Me.CellTextAt(i - 1, 0) = s1.NthField(",", i) > Next > ```

forsearch

DesktopListBox.AddExpandableRowAt **AddExpandableRowAt**(row As `Integer`, text As `String`, indent As `Integer` = 0) > Creates a new expandable row at *row*, 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 ListBox where `AllowExpandableRows` is `False`. > > The following example in a `DesktopButton` 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

DesktopListBox.AddListSelectionNotificationReceiver **AddListSelectionNotificationReceiver**(receiver As `ListSelectionNotificationReceiver`) > The *receiver* passed is notified when the list selection changes.

forsearch

DesktopListBox.AddRow **AddRow**(`ParamArray` Item As `String`) > Appends a new blank row to the end of the ListBox. > > The AddRow method allows you to pass in multiple strings as separate parameters. Each parameter will be placed into the its corresponding column in the new row starting with the first column. > > 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.CellTextAt(ListBox1.LastAddedRowIndex, 2) = "Col 3" > ```

forsearch

DesktopListBox.AddRowAt **AddRowAt**(row As `Integer`, text As `String`, depth As `Integer` = 0) > Creates a new row at *row*, moving the existing rows below *row* down. For multicolumn ListBoxes, *text* is always assigned to column zero. The optional parameter *depth* 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 `DesktopButton`. > > ``` xojo > Listbox1.AddRowAt(1, "Steven") > ```

forsearch

DesktopListBox.CellAlignmentAt **CellAlignmentAt**(row As `Integer`, column As `Integer`) As `DesktopListBox.Alignments` > Returns the alignment of the specified cell. **CellAlignmentAt**(row As `Integer`, column As `Integer`, `Assigns` value As `DesktopListBox.Alignments`) > Assigns the alignment of the specified cell. > > This example aligns sets the alignment of a cell to right: > > ``` xojo > ListBox1.CellAlignmentAt(1,1) = DesktopListBox.Alignments.Right > ```

forsearch

DesktopListBox.CellAlignmentOffsetAt **CellAlignmentOffsetAt**(row As `Integer`, column As `Integer`) As `Integer` > Returns the distance in points from the right edge of the specified cell. **CellAlignmentOffsetAt**(row As `Integer`, column As `Integer`, `Assigns` value As `Integer`) > Assigns the distance in points from the right edge of the specified cell. > > Any value specified will be the valued used for `ColumnAlignmentOffsetAt`. > > This example moves the contents of a cell 10 points to the left: > > ``` xojo > Me.CellAlignmentOffsetAt(1, 3) = -10 > ```

forsearch

DesktopListBox.CellBoldAt **CellBoldAt**(row As `Integer`, column As `Integer`) As `Boolean` > Used to add or remove the bold style from the text of the specified cell. > > Assign `True` to add the bold style and `False` to remove the bold style. For example: > > ``` xojo > ListBox1.CellBoldAt(1, 1) = True > ```

forsearch

DesktopListBox.CellBorderColorAt **CellBorderColorAt**(row As `Integer`, column As `Integer`) As `ColorGroup` > Returns the color of the specified cell. **CellBorderColorAt**(row As `Integer`, column As `Integer`, `Assigns` value As `ColorGroup`) > Assigns the color to the specified cell. > > The following code in a DesktopListBox Opening event sets the border of the first cell in a DesktopListBox to red using the color `Red`: > > ``` xojo > Me.CellBorderColorAt(0, 0) = Color.Red > ``` > > The following code in a DesktopListBox Opening event sets the border of the first cell in a DesktopListBox to color defined in a `ColorGroup` in the project called BorderColor: > > ``` xojo > Me.CellBorderColorAt(0, 0) = BorderColor > ``` > > You can also check the color of a cell by comparing it either to `Color` or a `ColorGroup`: > > ``` xojo > If CustomerList.CellBorderColorAt(0, 0) = Color.Green Then > System.Beep > MessageBox("This customer's order is paid in full.") > End If > ```

forsearch

DesktopListBox.CellCheckBoxStateAt **CellCheckBoxStateAt**(row As `Integer`, column As `Integer`) As `DesktopCheckBox.VisualStates` > Used to get or set the state of the cell with the coordinates of *row*, *column*. This assumes that the passed cell is a DesktopCheckBox cell. Use the `CellTypeAt` method to set a cell to a CheckBox cell. > > The Indeterminate state places a minus sign in the checkbox (macOS) or filled in checkbox (Windows and Linux). > > 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 Opening event: > > ``` xojo > Me.CellTypeAt(1, 0) = DesktopListBox.CellTypes.CheckBox > ``` > > To change the state of the cell, use the `DesktopCheckBox.VisualStates` enumeration of the `DesktopCheckBox` control: > > ``` xojo > ListBox1.CellCheckBoxStateAt(1, 0) = DesktopCheckbox.VisualStates.Indeterminate > ```

forsearch

DesktopListBox.CellCheckBoxValueAt **CellCheckBoxValueAt**(row As `Integer`, column As `Integer`) As `Boolean` > Used to get or set the value of the checkbox in the cell at *row*, *column*.

forsearch

DesktopListBox.CellItalicAt **CellItalicAt**(row As `Integer`, column As `Integer`) As `Boolean` > Used to add or remove the italic style from the text of the specified cell. > > This example assigns `True` to apply the italic style. > > ``` xojo > ListBox1.CellItalicAt(1, 1) = True > ```

forsearch

DesktopListBox.CellTagAt **CellTagAt**(row As `Integer`, column As `Integer`) As `Variant` **CellTagAt**(row As `Integer`, column As `Integer`, `Assigns` value As `Variant`) > Gets or sets a "hidden" identifier associated with the cell identified by its parameters. > > 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

DesktopListBox.CellTextAt **CellTextAt**(row As `Integer`, column As `Integer` = 0) As `String` **CellTextAt**(row As `Integer`, column As `Integer` = 0, `Assigns` value As `String`) > Used to set or get the text of the cell based on the row and column numbers passed. > > The top-left cell is 0,0. > > Passing -1 as the row or column parameters will refer to the entire row or column. However, in order to assign values to every row, the *value* you assign must be `EndOfLine`-delimited. To assign values to every column, the *value* you assign must be tab-delimited. > > 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(i.ToString) ' first column > ListBox1.CellTextAt(Listbox1.LastAddedRowIndex, 1) = Self.ControlAt(i).Name ' second column > Next > ```

forsearch

DesktopListBox.CellTooltipAt **CellTooltipAt**(row As `Integer`, column As `Integer`) As `String` > Used to set or get the help tag (i.e. tooltip) for a ListBox cell. > > 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

DesktopListBox.CellTypeAt **CellTypeAt**(row As `Integer`, column As `Integer`) As `DesktopListBox.CellTypes` > Returns the type of the specified cell. **CellTypeAt**(row As `Integer`, column As `Integer`, `Assigns` value As `DesktopListBox.CellTypes`) > Assigns the type to the specified cell. > > This code shows a checkbox in a single cell: > > ``` xojo > ListBox1.CellTypeAt(0, 4) = DesktopListbox.CellTypes.Checkbox ' Cell in the 1st row, 5th column now shows a checkbox > ``` > > To set or use the value of the Cell's checkbox see both the `CellCheckBoxValueAt` property (boolean) and `CellCheckBoxStateAt` method (`Checked\\Unchecked\\Indeterminate`). This code uses CellCheckboxStateAt to set the cell to be checked: > > ``` xojo > ListBox1.CellCheckBoxStateAt(0, 4) = DesktopCheckBox.VisualStates.Checked > ```

forsearch

DesktopListBox.CellUnderlineAt **CellUnderlineAt**(row As `Integer`, column As `Integer`) As `Boolean` > Used to add or remove the underline style from the text of the specified cell. > > Assign `True` to add the underline style and `False` to remove the underline style. For example: > > ``` xojo > ListBox1.CellUnderlineAt(1, 1) = True > ```

forsearch

DesktopListBox.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

DesktopListBox.ColumnAlignmentAt **ColumnAlignmentAt**(column As `Integer`) As `DesktopListBox.Alignments` > Returns the alignment of the specified column. **ColumnAlignmentAt**(column As `Integer`, `Assigns` value As `DesktopListBox.Alignments`) > Assigns the alignment to the specified column. > > The example sets the column to right alignment: > > ``` xojo > ListBox1.ColumnAlignmentAt(1) = DesktopListBox.Alignments.Right > ``` > > This will align the decimal separator to the right edge of the column. You need to use `DesktopListBox.ColumnAlignmentOffsetAt` to move the alignment point in the column.

forsearch

DesktopListBox.ColumnAlignmentOffsetAt **ColumnAlignmentOffsetAt**(column As `Integer`) As `Integer` > Returns the decimal alignment point of the specified column. **ColumnAlignmentOffsetAt**(column As `Integer`, `Assigns` value As `Integer`) > Assigns the decimal alignment point to the specified column. > > The value is the distance in points from what is specified for the column alignment. > > For right alignment, a negative value moves the decimal separator to the left, i.e., into the body of the column. See the example in the Notes subsection `Aligning decimal values in a column`. > > This code sets the offset in a right-aligned column by 10 points: > > ``` xojo > Me.ColumnAlignmentOffsetAt(2) = -10 > ```

forsearch

DesktopListBox.ColumnAttributesAt **ColumnAttributesAt**(column As `Integer`) As `DesktopListBoxColumn` > Returns the `DesktopListBoxColumn` object of the specified column. **ColumnAttributesAt**(column As `Integer`, `Assigns` value As `DesktopListBoxColumn`) > Assigns the `DesktopListBoxColumn` object to the specified column. > > This method enables you to access the `DesktopListBoxColumn` properties of the specified column. > > Use DesktopListBox.AllColumns to refer to all columns.

forsearch

DesktopListBox.ColumnFromXY **ColumnFromXY**(X As `Integer`, Y As `Integer`) As `Integer` > Returns the column index from the passed mouse x, y point coordinates. > > The parameters *X* and *Y* are relative to the top, left corner of the **ListBox**. If you use `System.MouseX` or `System.MouseY` 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 method only returns a valid column index when the coordinates fall within a populated data row. Coordinates outside a populated data row — including the header row — return -1. > > This code in the DoublePressed 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.Window.Left ' Calculate current mouse position relative to top left of ListBox > > Var yValue As Integer > yValue = System.MouseY - Me.Top - Self.Top - Me.Window.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

DesktopListBox.ColumnSortDirectionAt **ColumnSortDirectionAt**(column As `Integer`) As `DesktopListBox.SortDirections` > Returns the sort direction of the specified column. **ColumnSortDirectionAt**(column As `Integer`, `Assigns` value As `DesktopListBox.SortDirections`) > Assigns the sort direction to the specified column. > > This example sets the sort direction for a column. > > ``` xojo > ListBox1.ColumnSortDirectionAt(2) = DesktopListBox.SortDirections.Descending > ``` > > ColumnSortDirectionAt doesn't actually sort the rows; it only establishes the sort direction that is used when the `DesktopListBox.Sort` method is called. The sort direction can be set even if there is no header for the ListBox. > > If you set ColumnSortDirectionAt to `DesktopListBox.SortDirections.None`, the user can't sort the column by clicking its header. This will block the usual calls to the `ColumnSorted` and `RowComparison` events.

forsearch

DesktopListBox.ColumnSortTypeAt **ColumnSortTypeAt**(column As `Integer`) As `DesktopListBox.SortTypes` > Returns the sort type (sortable or not sortable) of the specified column. **ColumnSortTypeAt**(column As `Integer`, `Assigns` value As `DesktopListBox.SortTypes`) > Assigns the sort type (sortable or not sortable) to the specified column. > > 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 DesktopListBox.AllColumns affects the header type of all columns. > > The following code in the Opening event of the DesktopListBox sets the first two columns as sortable and the third column as non-sortable. > > ``` xojo > Me.ColumnSortTypeAt(0) = DesktopListBox.SortTypes.Sortable > Me.ColumnSortTypeAt(1) = DesktopListBox.SortTypes.Sortable > Me.ColumnSortTypeAt(2) = DesktopListBox.SortTypes.NotSortable > ```

forsearch

DesktopListBox.ColumnTagAt **ColumnTagAt**(column As `Integer`) As `Variant` **ColumnTagAt**(column As `Integer`, `Assigns` value As `Variant`) > Gets and sets the column tag of the specified column.

forsearch

DesktopListBox.ColumnTypeAt **ColumnTypeAt**(column As `Integer`) As `DesktopListBox.CellTypes` > Returns the type of the specified column. **ColumnTypeAt**(column As `Integer`, `Assigns` value As `DesktopListBox.CellTypes`) > Assigns the type to the specified column. > > The following example makes a column editable: > > ``` xojo > lb1.ColumnTypeAt(1) = DesktopListBox.CellTypes.TextField > ``` > > Disclosure triangles don't work in hierarchical ListBoxes if the CellType is TextField or TextArea. ColumnTypeAt can be overridden by CellTypeAt. > > The following example makes a column a checkbox column and sets two of the values: > > ``` xojo > Me.ColumnTypeAt(4) = DesktopListbox.CellTypes.Checkbox > Me.CellCheckBoxStateAt(0, 4) = DesktopCheckBox.VisualStates.Indeterminate > Me.CellCheckBoxStateAt(1, 4) = DesktopCheckbox.VisualStates.Checked > ```

forsearch

DesktopListBox.Content **Content** As `String` > The text content of the entire DesktopListBox. > > If the string you assign to Content contains tabs and `EndOfLine` characters, rows and columns will be created to accommodate. > > This example copies all cells from one ListBox into another: > > ``` xojo > ListBox2.Content = ListBox1.Content > ``` > > The destination listbox will have the same number of rows and columns as the source. > >

> >

> > Warning > >

> > Headers, CellTags, RowTags and ColumnTags are not copied. > >

forsearch

DesktopListBox.DrawInto **DrawInto**(g As `Graphics`, x As `Integer`, y As `Integer`) > Draws the contents of the control into the specified `Graphics` context. The parameters *x* and *y* are the coordinates of the top, left corner. > >

> >

> > Note > >

> > DrawInto will only work if the control is on a window or container. > >

> > 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

DesktopListBox.EditCellAt **EditCellAt**(row As `Integer`, column As `Integer`) > Scrolls the *row*, *column* cell into view (if necessary) and temporarily makes the cell editable. It sets the focus within the DesktopListBox 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 DesktopListBox. 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 `DesktopTextControl` that contains the contents of that cell. This may be a `DesktopTextField` or a `DesktopTextArea` depending on the specified column type. You can use this property to set or get the text of the DesktopListBox cell, set the selection, or change other properties of the DesktopListBox's TextField or TextArea. > > The following code in the CellPressed event makes the cell the user pressed on editable. The parameters *row* and *column* are passed to the function. > > ``` xojo > Me.CellTypeAt(row, column) = DesktopListbox.CellTypes.TextField > Me.EditCellAt(row, column) > ``` > > This code marks an entire column as editable: > > ``` xojo > ListBox1.ColumnTypeAt(3) = DesktopListBox.CellTypes.TextArea > ``` > > In the `CellPressed` 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 > ```

Note

To take the cell out of editing mode, call `ListBox.SetFocus`.

forsearch

DesktopListBox.HeaderAt **HeaderAt**(index As `Integer`) As `String` > Returns the heading of the specified column. **HeaderAt**(index As `Integer`, `Assigns` value As `String`) > Assigns the heading to the specified column. > > 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(DesktopListBox.AllColumns) the text of the headings separated by the tab character, e.g., > > ``` xojo > Me.HeaderAt(DesktopListBox.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(DesktopListBox.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. > ```

forsearch

DesktopListBox.PressHeader **PressHeader**(column As `Integer`) > Causes the specified DesktopListBox header of the *column* passed to be pressed, 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

DesktopListBox.Refresh **Refresh**(immediately As `Boolean` = `False`) > Redraws the portion specified of the contents of the control the next time the OS redraws the control or immediately if `True` is passed. > > If you are calling this so frequently that you experience a slowdown in your code, pass `True` for the immediately parameter. > > Calling this method causes the Render event to fire. > > Refresh the entire area immediately: > > ``` xojo > Me.Refresh(True) > ``` ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

forsearch

DesktopListBox.Refresh **Refresh**(x As `Integer`, y As `Integer`, width As `Integer`, height As `Integer`, immediately As `Boolean` = `False`) > Redraws the portion specified of the contents of the control the next time the OS redraws the control or immediately if `True` is passed. > > Refresh a portion of the area the next time the OS redraws the control: > > ``` xojo > Me.Refresh(100, 150, 200, 300) > ```

forsearch

DesktopListBox.RefreshCell **RefreshCell**(row As `Integer`, column As `Integer`) > Redraws the specified cell from scratch. > > If you pass a -1 as the *row* or *column* parameter, it will redraw the specified entire *row* or *column*, i.e., RefreshCell(2, -1) redraws row number 2. The PaintCellBackground and PaintCellText events execute when RefreshCell is called. > > RefreshCell should be necessary only if you are using a custom storage mechanism for your DesktopListBox data. If the contents of the DesktopListBox are stored in the DesktopListBox cells, the DesktopListBox 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.RefreshCell(1, 0) > ```

forsearch

DesktopListBox.RemoveAllRows **RemoveAllRows** > Removes all rows in the DesktopListBox, including any initial values that were specified in the IDE. > > This example removes all the rows in ListBox1. > > ``` xojo > Listbox1.RemoveAllRows > ```

forsearch

DesktopListBox.RemoveListSelectionNotificationReceiver **RemoveListSelectionNotificationReceiver**(receiver As `ListSelectionNotificationReceiver`) > Removes the *receiver* passed so that it is no longer notified when the list selection changes.

forsearch

DesktopListBox.RemoveRowAt **RemoveRowAt**(index As `Integer`) > Removes the row at the index passed. > > This example removes the second row. > > ``` xojo > Listbox1.RemoveRowAt(1) > ```

forsearch

DesktopListBox.RowAt **RowAt**(row As `Integer`) As `DesktopListBoxRow` > Returns the `DesktopListBoxRow` for the row indicated by the index passed.

forsearch

DesktopListBox.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

DesktopListBox.RowExpandableAt **RowExpandableAt**(row As `Integer`) As `Boolean` > Allows you to get or set whether the row should be displayed as expandable when the `AllowExpandableRows` property is `True`. > > ``` xojo > Me.AddExpandableRow("Players") > Me.RowExpandableAt(Me.LastAddedRowIndex) = False ' Disable expandable indicator > ```

forsearch

DesktopListBox.RowExpandedAt **RowExpandedAt**(v 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

DesktopListBox.RowFromXY **RowFromXY**(X As `Integer`, Y As `Integer`) As `Integer` > Returns the row index from the passed mouse x, y point coordinates. > > The parameters *X* and *Y* are relative to the top, left corner of the control. If you use `System.MouseX` or `System.MouseY` 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 DoublePressed event 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 code is not in the control on the window (perhaps it is in a subclass or DesktopContainer), then you need to be sure to calculate the correct offsets. This code would be used for a DesktopListBox on a DesktopContainer: > > ``` xojo > Var xValue As Integer > xValue = System.MouseX - Me.Left - Self.Left - Me.Window.Left ' Calculate current mouse position relative to top left of ListBox > > Var yValue As Integer > yValue = System.MouseY - Me.Top - Self.Top - Me.Window.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

DesktopListBox.RowImageAt **RowImageAt**(index As `Integer`) As `Picture` > Adds the image/picture assigned to the passed row *index*. > > The **ListBox** row does not resize to accommodate the `Picture`. If your picture does not fit via RowImageAt, use PaintCellText or PaintCellBackground 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

DesktopListBox.Rows **Rows** As `Iterable` > Allows you to iterate through all the rows in a DesktopListBox. > > 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 DesktopListBoxRow In ListBox1.Rows > If row.Tag = "Taxable" Then ComputeTaxes(row.CellTextAt(0)) > Next > ```

forsearch

DesktopListBox.RowSelectedAt **RowSelectedAt**(index As `Integer`) As `Boolean` > Gets the selection status of the passed row *index*. ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

forsearch

DesktopListBox.RowSelectedAt **RowSelectedAt**(index As `Integer`, `Assigns` value As `Boolean`) > Sets the selection status of the passed row *index*. > > 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.RowSelectedAt(1) = True ' selects the second item in the first column. > ``` > > In order to select multiple row, the `RowSelectionType` must be set to Multiple. This code selects only the even-numbered rows: > > ``` xojo > ListBox1.SelectedRowIndex = DesktopListBox.NoSelection ' Deselect all rows > > For i As Integer = 0 To ListBox1.LastRowIndex > If i Mod 2 = 0 Then > ListBox1.RowSelectedAt(i) = True > End If > Next > ``` > > If you allow multiple rows to be selected (see `RowSelectionType`), you may want to establish a list of all the rows selected. The following example shows how to achieve that: > > ``` xojo > Var selectedRows() As Integer ' Will hold the index of each selected row > > For row As Integer = 0 To ListBox1.LastRowIndex > If ListBox1.RowSelectedAt(row) Then > selectedRows.AddRow(row) ' This row is selected > End If > Next > ```

forsearch

DesktopListBox.RowTagAt **RowTagAt**(row As `Integer`) As `Variant` > Gets and sets the RowTag for the passed *row*. > > To set the tag: > > ``` xojo > ListBox1.RowTagAt(row) = "MyTag" > ``` > > To get the tag: > > ``` xojo > myTag = ListBox1.RowTagAt(row) > ```

forsearch

DesktopListBox.SetFocus **SetFocus** > If applicable, sets the focus to the DesktopUIControl.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 `DesktopWindow` 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. > >

> >

> > Note > >

> > On macOS, 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 in the Opening event sets the focus to the that control. If another control has the focus when this line is executed, then the user sees this control gets the focus. > > ``` xojo > Me.SetFocus > ```

forsearch

DesktopListBox.Sort **Sort** > Sorts the rows based on the current values of the `SortingColumn` and `ColumnSortDirectionAt` properties. > > When `AllowExpandableRows` is `True` and a DesktopListBox 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) = DesktopListBox.SortDirections.Descending > ListBox1.SortingColumn = 0 ' first column is the sort column > ListBox1.Sort > ``` > >

> >

> > Tip > >

> > If you wish to have specific columns not included in the sort, use the `ColumnSortTypeAt` method. > >

## Event descriptions

forsearch

DesktopListBox.CellAction **CellAction**(row As `Integer`, column As `Integer`) > If a cell is editable, a CellAction event occurs when the user finishes editing a cell. > > “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.CellTextAt(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.CellCheckBoxValueAt(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

DesktopListBox.CellFocusLost **CellFocusLost**(row As `Integer`, column As `Integer`) > The *row*, *column* cell has just lost the focus. > > The user could have clicked on another cell or pressed Tab, Return, or Escape.

forsearch

DesktopListBox.CellFocusReceived **CellFocusReceived**(row As `Integer`, column As `Integer`) > The user has selected an editable cell of a ListBox. > > The *row* and *column* parameters indicate which cell just got the focus.

forsearch

DesktopListBox.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. > > 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 CellTextChanged event from firing.

forsearch

DesktopListBox.CellPressed **CellPressed**(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 `PaintCellBackground` event. > > To give the user the ability to edit the cell, change the CellType to Editable (DesktopListBox.TypeEditable) and then call the EditCellAt 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. > > CellPressed 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) = DesktopListBox.CellTypes.TextField > Me.EditCellAt(row, column) > > Return True > End If > ```

forsearch

DesktopListBox.CellTextChanged **CellTextChanged**(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

DesktopListBox.Closing **Closing** > The control is closing.

forsearch

DesktopListBox.ColumnSorted **ColumnSorted**(column As `Integer`) As `Boolean` > The user has clicked on the passed *column* header to sort that column or the Sort method was called. > > `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 `RowComparison` event. > > If you're trying to prevent the user from sorting the column in the first place, use `ColumnSortDirectionAt`.

forsearch

DesktopListBox.ConstructContextualMenu **ConstructContextualMenu**(Base As `DesktopMenuItem`, 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 DesktopMenuItem("Test 1")) > base.AddMenu(New DesktopMenuItem("Test 2")) > base.AddMenu(New DesktopMenuItem("Test 3")) > > ' Add a Separator > base.AddMenu(New DesktopMenuItem(DesktopMenuItem.TextSeparator)) > > ' Add a sub menu > Var submenu As New DesktopMenuItem("SubMenu") > submenu.AddMenu(New DesktopMenuItem("SubMenu Test 1")) > submenu.AddMenu(New DesktopMenuItem("SubMenu Test 2")) > submenu.AddMenu(New DesktopMenuItem("SubMenu Test 3")) > base.AddMenu(submenu) > > ' Add a Separator > base.AddMenu(New DesktopMenuItem(DesktopMenuItem.TextSeparator)) > > Return True > ```

forsearch

DesktopListBox.ContextualMenuItemSelected **ContextualMenuItemSelected**(selectedItem As `DesktopMenuItem`) As `Boolean` > Fires when a contextual menuitem *selectedItem* was selected but the `MenuItemSelected` event and the MenuHandler for the `DesktopMenuItem` 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 `MenuItemSelected` event or the Menu Handler for the items on the contextual menu. See the example of a contextual menu in the examples for the **DesktopUIControl** 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 ContextualMenuItemSelected 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 SelectedItem <> Nil Then MessageBox(selectedItem.Text) > Return True > ```

forsearch

DesktopListBox.DoublePressed **DoublePressed** > The user has double-pressed (clicked or tapped) on a row in the ListBox.

forsearch

DesktopListBox.DragEnter **DragEnter**(obj As `DragItem`, Action As `DragItem.Types`) As `Boolean` > Fires when the passed `DragItem` enters the DesktopUIControl. > > Returns a `Boolean`. Return `True` from this event to prevent the drop from occurring. > > The Action parameter specifies the type of drag action. > > 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

DesktopListBox.DragExit **DragExit**(obj As `DragItem`, Action As `DragItem.Types`) > Fires when the passed `DragItem` exits the DesktopUIControl. > > The *obj* parameter is the item being dragged. The *Action* parameter specifies the type of drag action.

forsearch

DesktopListBox.DragOver **DragOver**(x As `Integer`, y As `Integer`, obj As `DragItem`, Action As `DragItem.Types`) As `Boolean` > Fires when the `DragItem` is over the DesktopUIControl. > > The *obj* parameter is the object being dragged. The coordinates x and y are relative to the **DesktopUIControl**. Returns a `Boolean`. Return `True` from this event to prevent the drop from occurring. > > The *Action* parameter specifies the type of drag action, which is typically done by holding down a modifier key (Shift, Alt, Option, Command, etc.) while doing the drag.

forsearch

DesktopListBox.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 `DesktopListBox`) As `Boolean` > 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 DesktopListBox.DropLocations enum. > > Returning `True` prevents the drop from occurring and the DragOver event from firing. Otherwise the DragOver event fires.

forsearch

DesktopListBox.DragReorderRows **DragReorderRows**(NewPosition As `Integer`, ParentRow As `Integer`) As `Boolean` > This event is called when one or more rows are selected then moved to a new position. The `AllowRowReordering` property must be `True` in order for this event to be called. > > When no expandable rows are present: > > - The *newPosition* parameter is the row number at which the dragged row was dropped. Remember that the first row in a DesktopListBox is numbered zero. This row number is adjusted assuming that all selected rows will be moved as implied by the drag & drop action. > - The *parentRow* parameter will always be -1, because it has no significance for a non-hierarchical DesktopListBox. > > The row(s) to be reordered are selected before this event fires. If the `RowSelectionType` is set to single, you can use `SelectedRowIndex` to get the number of the only selected row. If the `RowSelectionType` is set to multiple, you must go through all rows in the list and check if `RowSelectedAt` is `True` for each row (see example in `RowSelectedAt`). > > When `AllowExpandableRows` is `False`, row reordering is done for you if you return `False`. To override the automatic behavior so you can do the row reordering yourself (for customization purposes), return `True`. > > When expandable rows are present: > > - The *newPosition* parameter is the row number at which the dragged row was dropped. Remember that the first row is numbered zero. > - If the *newPosition* is inside an expandable row (see `AddExpandableRow` and `AddExpandableRowAt`) the *parentRow* parameter is the row number that expandable row, i.e. the parent of the *newPosition*. Otherwise, *parentRow* will be -1. This happens if the *newPosition* is before the first expandable row in the list, i.e. the root level of the DesktopListBox. > - For both parameters, the row numbers are adjusted assuming that all selected rows will be moved as implied by the drag & drop action. > > The row(s) to be reordered are selected before this event fires. If the `RowSelectionType` is set to single, you can use `SelectedRowIndex` to get the number of the only one selected row. If the `RowSelectionType` is set to multiple, you must go through all rows in the list and check if `RowSelectedAt` is `True` for each row (see example in `RowSelectedAt`). > > When `AllowExpandableRows` is `True`, row reordering is NOT done for you, regardless of the value you return. You are responsible for writing the code for reordering the rows and you should return `True`.

forsearch

DesktopListBox.DragRow **DragRow**(Drag As `DragItem`, Row As `Integer`) As `Boolean` > The user is dragging a row. > > *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 > Var nRows As Integer > Var additionalItems As Boolean > For i As Integer = 0 To Me.LastRowIndex > If Me.RowSelectedAt(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.SelectedRowText > End If > Next > > Return True > End Function > ```

forsearch

DesktopListBox.DropObject **DropObject**(Obj As `DragItem`, Action As `DragItem.Types`) > The item represented by *Obj* has been dropped on the control. > > The *Obj* parameter is the object being dragged. The *Action* parameter specifies the type of drag action. > > 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 Opening event. > > ``` xojo > If Obj.PictureAvailable Then > Me.Image = obj.Picture > ElseIf Obj.FolderItemAvailable Then > Me.Image = Picture.Open(obj.FolderItem) > End If > ```

forsearch

DesktopListBox.DropObjectOnRow **DropObjectOnRow**(x As `Integer`, y As `Integer`, obj As `DragItem`, action As `Integer`, row As `Integer`, parentRow As `Integer`, location As `DesktopListBox`) > 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 DesktopListBox.DropLocations.AfterAllRows > MessageBox "add row after all rows" > Case DesktopListBox.DropLocations.AfterRow > MessageBox "add row after rowindex = " + row.ToString > Case DesktopListBox.DropLocations.OnControl > MessageBox "drop occurred ON control" > Case DesktopListBox.DropLocations.OnRow > MessageBox "add row to rowindex = " + row.ToString > End Select > ```

forsearch

DesktopListBox.FocusLost **FocusLost** > The `control` has lost the focus. > >

> >

> > Note > >

> > On macOS, 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

DesktopListBox.FocusReceived **FocusReceived** > The `control` has received the focus and has a selection rectangle around it. > >

> >

> > Note > >

> > On macOS, controls other than text fields and lists will accept focus only if the full keyboard access option is enabled in System Preferences/Keyboard. > >

forsearch

DesktopListBox.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 SortingColumn property.

forsearch

DesktopListBox.KeyDown **KeyDown**(Key As `String`) As `Boolean` > The user has pressed the *Key* passed while the `control` has the focus. > > 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

DesktopListBox.KeyUp **KeyUp**(Key As `String`) > Fires when the passed *Key* is released in the control that has the focus. > > It is not guaranteed to be the same key that received the KeyDown event.

forsearch

DesktopListBox.MenuBarSelected **MenuBarSelected** > The user has selected a menu while the listbox has the focus.

forsearch

DesktopListBox.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*. > > This event fires repeatedly while the mouse button is being held down. > > 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 of the `control`. > > `Return` `True` if you are going to handle the MouseDown. In such a case: > > - The Pressed event, if any, will not execute and the state of the object will not change. > - You will receive the `MouseUp` event. > > If you return False, the system handles the MouseDown so the `MouseUp` event handler does 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

DesktopListBox.MouseDrag **MouseDrag**(X As `Integer`, Y As `Integer`) > The mouse button was pressed inside the control and moved (dragged) at the location local to the control passed in to *x*, *y*. > > This event fires repeatedly while the mouse button is down regardless of whether or not the mouse coordinates are changing. > > This event will not occur unless you return `True` in the MouseDown event.

forsearch

DesktopListBox.MouseEnter **MouseEnter** > The mouse has entered the area of the control.

forsearch

DesktopListBox.MouseExit **MouseExit** > The mouse has left the area of the control.

forsearch

DesktopListBox.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

DesktopListBox.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 of the `control`. Mouse clicks that are released to the left or above a control are negative.

forsearch

DesktopListBox.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

DesktopListBox.Opening **Opening** > The control is about to be displayed. Use this event to initialize a control. > > The Opening event is called after the Constructor. > > Be warned that initializing control property values using the Constructor instead of the Opening event may result in those property values being overwritten by what is set in the Inspector. For best results, use the Opening 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 Opening() > Me.AcceptPictureDrop > Me.AcceptFileDrop("JPEG") > End Sub > ```

forsearch

DesktopListBox.PaintCellBackground **PaintCellBackground**(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 drawing of the background 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). > >

> >

> > Tip > >

> > Remember that the shared building setting *Supports Dark Mode* is on by default so you should plan accordingly when choosing colors. Call `Color.IsDarkMode` to determine if the device is currently running in Dark Mode. > >

> > 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

DesktopListBox.PaintCellText **PaintCellText**(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*. 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 > - RowImage > - Text > - Border > > Although the border is painted last, it isn't advisable to change the state of the border in the PaintCellText 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. > >

> >

> > Tip > >

> > 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 path As New GraphicsPath > path.MoveToPoint(g.Width - 10, 1) > path.AddLineToPoint(g.Width - 10, 1) > path.AddLineToPoint(g.Width, 1) > path.AddLineToPoint(g.Width - 5, 10) > > g.FillPath(path, True) > > 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.SelectedRowIndex = row > Me.RowSelectedAt(row) = True > > Var base As New DesktopMenuItem > base.AddMenu(New DesktopMenuItem("Red")) > base.AddMenu(New DesktopMenuItem("Green")) > base.AddMenu(New DesktopMenuItem("Blue")) > base.AddMenu(New DesktopMenuItem("Black")) > base.AddMenu(New MenuDesktopMenuItemItem("White")) > > Var selectedMenu As DesktopMenuItem > selectedMenu = base.PopUp > > If selectedMenu <> Nil Then > MessageBox("You changed the color to " + selectedMenu.Value + ".") > End If > End If > ```

forsearch

DesktopListBox.PaintDisclosureWidget **PaintDisclosureWidget**(g As `Graphics`, row As `Integer`, `ByRef` x As `Integer`, `ByRef` y As `Integer`, `ByRef` width As `Integer`, `ByRef` height As `Integer`) As `Boolean` > Invoked for hierarchical ListBoxes when the framework needs to draw the disclosure triangle for a folder row. This is invoked after PaintCellBackground and before PaintCellText. > > 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 PaintCellText 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 PaintCellText event would be offset by 5 points to the left.

forsearch

DesktopListBox.PaintHeaderBackground **PaintHeaderBackground**(g As `Graphics`, column As `Integer`) As `Boolean` > 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

DesktopListBox.PaintHeaderContent **PaintHeaderContent**(g As `Graphics`, column As `Integer`) As `Boolean` > 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

DesktopListBox.RowCollapsed **RowCollapsed**(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.

forsearch

DesktopListBox.RowComparison **RowComparison**(Row1 As `Integer`, Row2 As `Integer`, Column As `Integer`, `ByRef` Result As `Integer`) As `Boolean` > The RowComparison event is used for sorting a column of a DesktopListBox in a manner that is not provided by the default mechanism. 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 DesktopListBox 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 DesktopListBox contains a first column (numbered 0) which contains a string value. You can let the DesktopListBox 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 RowComparison event as follows: > > ``` xojo > Function RowComparison(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 Me.CellTextAt(row1, column ).Val < Me.CellTextAt(row2, column).Val Then > result = -1 > ElseIf Me.CellTextAt(row1, column).Val > Me.CellTextAt(row2, column).Val 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 RowComparison(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(Me.CellTextAt(row1, column).Val - Me.CellTextAt( row2, column).Val) > 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 RowComparison(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

DesktopListBox.RowExpanded **RowExpanded**(Row As `Integer`) > The user has clicked on the disclosure triangle, or the `RowExpandedAt` method was called, for a collapsed row that was added using `AddExpandableRow`. > > The rows are not persisted when the folder is later collapsed. Use the `RowExpanded` 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 " + childRow.ToString + " of row " + Me.CellTextAt(row, 0)) > Next > ```

forsearch

DesktopListBox.SelectionChanged **SelectionChanged** > The SelectionChanged event is called when the row selection is changed by the user or by code. > > The SelectionChanged event handler is called when the row selection changes, not when cell contents change. > > The SelectionChanged 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 SelectionChanged event but a second click to get an insertion point does not. Clicking on a header or a checkbox does not call the SelectionChanged event. > > Also, changing `SelectedRowIndex` via code also triggers the SelectionChanged event. ## Notes Items in a single-column DesktopListBox can be accessed using the CellTextAt method as the column parameter defaults to 0. The following example gets the value in the first row of a \`DesktopListBox\`: ``` xojo Var lastName As String lastName = ListBox1.CellTextAt(0) ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Windows HiDPI When drawing to graphics on Windows HiDPI with a fractional scale factor you may run into a situation that is referred to as a "pixel crack". The symptom is that your drawing does not fill the entire graphics area causing small gaps between the cells. In order to avoid this you need to disable anti-aliasing when drawing on Windows in this situation. You can do this easily as follows, by turning off anti-aliasing in the `PaintCellBackground` event: ``` xojo ' Draw black cell background If row >= Me.RowCount Then Return False g.AntiAlias = False g.DrawingColor = Color.Red g.FillRectangle(0,0, g.Width, g.Height) Return True ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Iterating through rows The `Rows` method returns a `DesktopListBoxRow` 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 DesktopListboxRow In Listbox1.Rows If row.Tag = "Taxable" Then ComputeTaxes(row.Value) Next ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Creating and accessing multiple columns You can create multi-column DesktopListBoxes by changing the ColumnCount property. Because the first column in a multi-column DesktopListBox is column 0 (zero), 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 initial 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 DesktopListBoxes 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 DesktopListBox. 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 DesktopListBox, then the remaining columns will be truncated. Specific cells in a multi-column DesktopListBox can be accessed using the CellTextAt method. To populate a multi-column DesktopListBox, first use the AddRow method to create the new row and populate the first column. Then use the CellTextAt 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 DesktopListBox 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(i.ToString) ' first column ListBox1.CellTextAt(Listbox1.LastAddedRowIndex, 1) = DesktopUIControl(i).Name ' second column Next ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Determining which cell was double-clicked The DoublePressed event fires when the user double-clicks anywhere inside a DesktopListBox, 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 DoublePressed 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 " + row.ToString + ", " + column.ToString) ``` The parameters of RowFromXY are relative to the top, left corner of the DesktopListBox on a window. If you use the DesktopListBox in a DesktopContainer 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.Window.Left, System.MouseY - Me.Top - Self.Top - Me.Window.Top) column = Me.ColumnFromXY(System.MouseX - Me.Left - Me.Parent.Left - Me.Window.Left, System.MouseY - Me.Top - Me.Parent.Top - Me.Window.Top) MessageBox("You double-clicked in cell " + row.ToString + ", " + column.ToString) ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### 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 DesktopListBox. 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 CellPressed event makes the cell the user pressed on editable. The parameters row, and column are passed to the function. ``` xojo Me.CellTypeAt(row, column) = DesktopListBox.CellTypes.TextField Me.EditCellAt(row, column) ``` When a cell is editable, the ActiveTextControl property is the `DesktopTextField` that contains the contents of that cell. You can use this property to set or get the text of the DesktopListBox cell, set the selection, or change other properties of the DesktopListBox's `DesktopTextField`. --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Aligning decimal values in a column 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 point 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 point 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 DesktopListBox 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 DesktopListBox, and now both column widths will enlarge so that their widths remain in a 3/4 to 1/4 ratio. Changing the point 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 DesktopListBox is often used to display the results of database queries. A DesktopListBox 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 Opening event: ``` xojo Me.CellTypeAt(1, 0) = DesktopListBox.CellTypes.CheckBox ``` To change the state of the cell, use the `VisualStates` enumeration of the `CheckBox` control: ``` xojo ListBox1.CellCheckBoxStateAt(1, 0) = DesktopCheckbox.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 `DesktopScrollbar` control has been added to the bottom area of the ListBox and a `DesktopBevelButton` 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 `DesktopScrollbar` control has the following code in its Opening event handler: ``` xojo Me.MaximumValue = 50 Me.MinimumValue = 0 Me.LineStep = 5 ``` The values for Maximum and LineStep were chosen to match the total width of the DesktopListBox's columns. Adjust these values to suit your DesktopListBox. 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 `DesktopBevelButton` enables the user to switch the DesktopListBox between single-line selection and multiple-line selection. The `DesktopBevelButton` is set to have a normal menu and its Opening event handler populates the menu with two items: ``` xojo Me.AddRow("Single-line") Me.AddRow("Multiple-line") ``` The `BevelButton's` Pressed event sets the value of the DesktopListBox's SelectionType property: ``` xojo Select Case Me.MenuValue Case 0 Listbox1.RowSelectionType = DesktopListBox.RowSelectionTypes.Single Case 1 ListBox1.RowSelectionType = DesktopListBox.RowSelectionTypes.Multiple End Select ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Adding horizontal and vertical grid lines You can show horizontal and vertical rules for the entire ListBox using the `GridLineStyle` property. The Default value is equivalent to "None". --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Displaying hierarchical rows A tree view can be created using Expandable Rows. Xojo uses the generic terms Expandable Rows to describe this style. 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 Opening event handler, creates 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 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.CountFields(",") If Not sub1.NthField(";", i).IsEmpty Then Me.AddExpandableRow("") Me.CellTextAt(i - 1, 1) = sub1.NthField(";", i) End If Me.CellTextAt(i - 1, 0) = sub1.NthField(",", 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 DoublePressed 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 RowExpanded event handler runs when the user double-clicks a collapsed element: ``` xojo Var s1 As String Var u As Integer s1 = Me.CellTextAt(row, 1) u = s1.CountFields(",") For i As Integer = 1 To u Me.AddRow("") Me.CellTextAt(Me.LastAddedRowIndex, 0) = s1.NthField(",", i) Next ``` It creates the sublist rows each time the user double-clicks a collapsed state name. If `AllowExpandableRows` is `True`, then collapsing is handled automatically when the user collapses an item. If `AllowExpandableRows` is false, then you need code such as this in the `RowCollapsed` event handler: ``` xojo Var u, numSubRows As Integer numSubRows = Me.CellTextAt(row, 1).CountFields(",") u = row + 1 For i As Integer = row + numSubRows DownTo u Me.RemoveRowAt(i) Next ``` It removes the rows that were created by the `RowExpanded` 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`. Its DragRow event handler is as follows: ``` xojo Function DragRow (drag As DragItem, row As Integer) As Boolean drag.Text = Me.List(row) Return True ' allow the drag End Function ``` ListBox2's Opening event handler has the line: ``` xojo Me.AcceptTextDrop ``` Its DropObject event handler is this: ``` xojo Sub DropObject(obj As DragItem) Me.AddRow(obj.Text) ' adds the dropped text as a new row End Sub ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Drag and drop multiple rows The following code allows the user to drag more than one row from ListBox1 to ListBox2. The dragged rows are added to the end of the list. ListBox1 has its `AllowRowDragging` property set to `True`, enabling items in its list to be dragged, and its `RowSelectionType` property set to `Multiple`. Its DragRow event handler is as follows: ``` xojo Function DragRow (Drag As DragItem, Row As Integer) As Boolean Var nRows As Integer = Me.LastRowIndex For i As Integer = 0 To nRows If Me.RowSelectedAt(i) = True Then Drag.AddItem(0, 0, 20, 4) Drag.Text = Me.CellTextAt(i, 0) ' get text End If Next Return True ' allow the drag End Function ``` It uses the AddItem method of the `DragItem` to add an additional item to the DragItem each selected row. The DropObject event handler then cycles through all items to retrieve all dragged rows. ListBox2 has the following line of code in its Opening event handler. It permits it to receive dragged text. ``` xojo Me.AcceptTextDrop ``` Its DropObject event handler checks to see if the dragged object is text; if it is, it adds a row to the end of the list and assigns the text property of the dragged object to the new row: It loops through all items in the DragItem until NextItem returns `False`. ``` xojo Sub DropObject(obj As DragItem) Do If obj.TextAvailable Then Me.AddRow(obj.Text) End If Loop Until Not obj.NextItem End Sub ``` You can also drag from ListBox1 to the desktop to get a text clipping or to another application that supports text drag and drop. --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Changing the background color of cells This code, which is placed in the `PaintCellBackground` event, assigns alternating colors to the rows in a ListBox: ``` xojo If row Mod 2 = 0 Then g.DrawingColor = &cD2FFF3 Else g.DrawingColor = &cD2EDF5 End If g.FillRectangle(0, 0, g.Width, g.Height) ``` Notes: The `PaintCellBackground` event passes the parameters g (`Graphics`), and the row and column numbers (as `Integer`). You can assign a color to the DrawingColor property by creating it as a constant in the App class or a module and assign the color constant to the DrawingColor property. The following line in the `PaintCellText` event draws the text in the preceding example in red: ``` xojo g.DrawingColor = Color.RGB(255, 0, 0) ``` The PaintCellText event is passed the coordinates of the suggested starting position to draw text in the parameters x and y. You can use them in a call to the DrawText method to specify the string to draw in a particular cell: ``` xojo If row = 4 And column = 1 Then g.DrawingColor = Color.RGB(255, 0, 0) g.DrawText("Payment Overdue!", x, y) End If Return True ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Sorting rows To sort a ListBox, set the column on which the ListBox will be sorted with the `SortingColumn` property. Specify the sort direction on that column with the `ColumnSortDirectionAt` property, and then do the sort by calling the Sort method. The following code sorts a Listbox in descending order on the first column. ``` xojo ' first column, descending order ListBox1.ColumnSortDirectionAt(0) = DesktopListBox.SortDirections.Descending ListBox1.SortingColumn = 0 ' first column is the sort column ListBox1.Sort ``` You can also sort a column based on the current value of `ColumnSortDirectionAt` by calling the `PressHeader` method. This method programmatically clicks the header for the column passed to it.

Tip

If you wish to have specific columns not included in the sort, use the `ColumnSortTypeAt` method.

Note that sorting is based on string comparisons. If you want to sort numbers or CheckBoxes then you have to use a custom sort. --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Sorting rows with your own algorithm Use the `RowComparison` event handler to perform custom sorting on the displayed data. You will want to use custom sorting to property sort numerical data, which by default sorts as a string. This causes "2" to be greater than "100" because the values are treated as strings. You can also provide a custom sort for CheckBox columns, dates and any other information that you may want to sort differently than how it displays as a string. The following example uses the `RowComparison` event to sort columns of numbers numerically: ``` xojo Function RowComparison(row1 As Integer, row2 As Integer, column As Integer, ByRef result As Integer) As Boolean If Me.CellTextAt(row1, column).ToDouble > Me.CellTextAt(row2, column).ToDouble Then result = 1 Else result = -1 End If Return True ' Use the custom sort End Function ``` With this code in place, the correct (numerical) sorting is done whenever the user clicks the header area. Test to be sure that the custom sort affects only the numerical columns. To sort dates, store the `SecondsFrom1970` (or SQLiteDate) property of the `DateTime` in the `CellTagAt` for the column and use it to sort instead of the displayed value. ## Sample code Adding a row to ListBox1: ``` xojo ListBox1.AddRow("October") ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Adding a row at row 1 in ListBox1: ``` xojo ListBox1.AddRowAt(1, "October") ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Creating a three-column ListBox and adding the headings and the first row of information: ``` xojo ListBox1.ColumnCount = 3 ListBox1.HasHeader = True ListBox1.HeaderAt(0) = "Name" ListBox1.HeaderAt(1) = "Phone" ListBox1.HeaderAt(2) = "Email" ListBox1.AddRow("Milton") ListBox1.CellTextAt(ListBox1.LastAddedRowIndex, 1) = "555-2212" ListBox1.CellTextAt(ListBox1.LastAddedRowIndex, 2) = "milt@fredonia.com" ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Changing all items in the ListBox to bold, underline: ``` xojo ListBox1.Bold = True ListBox1.Underline = True ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Copying the fifth element of ListBox1 to another variable: ``` xojo Var e As String e = ListBox1.CellTextAt(4, 0) ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Adding a column to ListBox1 and setting the widths of the columns to 50 and 65 points, respectively: ``` xojo ListBox1.ColumnCount = 2 ListBox1.ColumnWidths = "50,65" ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Setting the number of columns of ListBox1 to three and setting the widths of the columns to 60%, 20% and 20% respectively: ``` xojo ListBox1.ColumnCount = 3 ListBox1.ColumnWidths = "60%,20%,20%" ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If ListBox1 is 100 points wide and has three columns, the following code will set the columns widths as indicated but the last column will only be 10 points wide instead of 20: ``` xojo ListBox1.ColumnWidths = "60,30,20" ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If ListBox1 is 100 points wide and has three columns, the following code will set the columns widths but the last column will not be displayed: ``` xojo ListBox1.ColumnWidths = "60,40,20" ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Copying the fifth row of the third column of ListBox1 to another variable: ``` xojo Var e As String e = ListBox1.CellTextAt(4, 2) ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Assigning a value to the fifth row of the third column of ListBox1: ``` xojo ListBox1.CellTextAt(4, 2) = "Bill" ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Setting the fifth row of the third column of ListBox1 to bold, italic: ``` xojo ListBox1.CellBoldAt(4, 2) = True ListBox1.CellItalicAt(4, 2) = True ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Adding a row with the text "Users" in the first cell and placing an image of a folder to the left of the text. The picture "usersFolder" has been added to the project. ``` xojo ListBox1.AddRow("Users") ListBox1.RowImageAt(0) = UsersFolder ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 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.CellTextAt(Row, 0) Return True End Function ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Summing the numeric values of the selected rows: ``` xojo Var total As Integer For i As Integer = 0 To ListBox1.LastRowIndex If ListBox1.RowSelectedAt(i) Then total = total + ListBox1.CellTextAt(i, 0).ToInteger End If Next ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This code 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) ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This code populates a three-column ListBox with headings: ``` xojo ListBox1.HasHeader = True ListBox1.HeaderAt(0) = "ID" ListBox1.HeaderAt(1) = "JobTitle" ListBox1.HeaderAt(2) = "Name" ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This code sets up a ListBox with four visible columns plus one hidden column. Column zero is hidden: ``` xojo Me.ColumnCount = 5 Me.ColumnWidths = "0,25%,25%,25%,25%" Me.HasHeader = True Me.HeaderAt(0) = "ID" Me.HeaderAt(1) = "FirstName" Me.HeaderAt(2) = "LastName" Me.HeaderAt(3) = "Phone" Me.HeaderAt(4) = "Zip" ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The following line of code displays the value of the hidden column in the selected row: ``` xojo MessageBox(ListBox1.CellTextAt(ListBox1.SelectedRowIndex, 0)) ``` ## Interfaces This class implements the `ListSelectionNotifier` class interface. ## Compatibility | | | |-----------------------|---------| | **Project Types** | Desktop | | **Operating Systems** | All |

`DesktopUIControl` parent class; `DesktopTextField` control; `DesktopListBoxRow`, `DesktopListBoxColumn`, `RowSet` classes