Class
DesktopListBox
Desktop Listbox
Description
The scrollable DesktopListBox control is used to display one or more columns of information.
Properties
Name |
Type |
Read-Only |
Shared |
|---|---|---|---|
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
Methods
Events
Name |
Parameters |
Returns |
|---|---|---|
Row As Integer, Column As Integer, X As Integer, Y As Integer |
||
Column As Integer |
||
Base As DesktopMenuItem, x As Integer, y As Integer |
||
selectedItem As DesktopMenuItem |
||
obj As DragItem, Action As DragItem.Types |
||
obj As DragItem, Action As DragItem.Types |
||
x As Integer, y As Integer, obj As DragItem, Action As DragItem.Types |
||
x As Integer, y As Integer, obj As DragItem, action As Integer, ByRef row As Integer, ByRef parentRow As Integer, ByRef location As DesktopListBox |
||
Obj As DragItem Action As DragItem.Types |
||
x As Integer, y As Integer, obj As DragItem, action As Integer, row As Integer, parentRow As Integer, location As DesktopListBox |
||
Column As Integer |
||
Key As String |
||
Key As String |
||
X As Integer, Y As Integer, DeltaX As Integer, DeltaY As Integer |
||
g As Graphics, Row As Integer, Column As Integer, x As Integer, y As Integer |
||
g As Graphics, row As Integer, ByRef x As Integer, ByRef y As Integer, ByRef width As Integer, ByRef height As Integer |
||
Row As Integer |
||
Row1 As Integer, Row2 As Integer, Column As Integer, ByRef Result As Integer |
||
Row As Integer |
||
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
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. |
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. |
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. |
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. |
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. |
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. |
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
DesktopListBox.Active
Active As Boolean
Indicates whether the control is active.
This property is read-only.
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.
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:
DesktopListBox.CellTypes.TextArea
DesktopListBox.CellTypes.TextField
For example,
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.
DesktopListBox.AllowAutoDeactivate
AllowAutoDeactivate As Boolean
Determines whether the control should be deactivated (on macOS) when the parent window is deactivated. The default is True.
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.
Me.AllowAutoHideScrollbars = False
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.
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.
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.
Me.AllowResizableColumns = True
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:
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:
Me.AcceptTextDrop
Its DropObject event handler is this:
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:
Function DragRow (drag As DragItem, row As Integer) As Boolean
Var nRows, i As Integer
nRows = Me.RowCount - 1
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.
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.
Sub DropObject(obj As DragItem)
Do
If obj.TextAvailable Then
Me.AddRow(obj.Text)
End If
Loop Until Not obj.NextItem
End Sub
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.
Me.AllowRowReordering = True
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:
Me.AllowTabStop = False
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.
Me.Bold = True
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:
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:
ListBox1.ColumnCount = 3
ListBox1.ColumnWidths = "60%,20%,20%"
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:
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:
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:
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:
ListBox1.ColumnWidths = "60,40,20"
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.
Me.DefaultRowHeight = 35
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.
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.
Me.Enabled = False
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.
Me.FontName = "Helvetica"
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.
Me.FontSize = 16
DesktopListBox.FontUnit
FontUnit As FontUnits
The units in which FontSize is measured.
DesktopListBox.GridLineStyle
GridLineStyle As GridLineStyles
The orientations of gridlines that can be displayed.
DesktopListBox.Handle
Handle As Ptr
Returns a handle to the control.
This property is read-only.
For interfacing with Mac 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.
Var p As Ptr = Me.Handle
DesktopListBox.HasBorder
HasBorder As Boolean
Indicates whether or not the border is visible.
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.
Me.HasHeader = True
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.
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.
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.
Var h As Integer = Listbox1.HeaderHeight
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:
Me.SortingColumn = 0
Me.ColumnSortDirectionAt(0) = DesktopListBox.SortDirections.Ascending
Me.HeadingIndex = 0
Me.Sort
DesktopListBox.Height
Height As Integer
The height (in points) of the control.
This example sets the height of the control to 100:
Me.Height = 100
DesktopListBox.Index
Index As Integer
If the control is used in a control set, this specifies the control's index in the set.
This property is read-only.
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.
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.
Me.Italic = True
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 DesktopTextField creates a new row in the DesktopListBox and adds the contents of the DesktopTextField</api/user_interface/desktop/desktoptextfield>`s to the `DesktopListBox.
PeopleList.Addrow("")
PeopleList.CellTextAt(PeopleList.LastAddedRowIndex, 0) = FirstNameField.Text
PeopleList.CellTextAt(PeopleList.LastAddedRowIndex, 1) = LastNameField.Text
PeopleList.SelectedIndex = 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:
If ListBox1.LastAddedRowIndex = DesktopListBox.NoSelection then
System.Beep
MessageBox("Please add a row to continue.")
End If
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.
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.
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:
Me.Left = 150
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.
Me.LockBottom = True
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.
Me.LockLeft = True
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.
Me.LockRight = True
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.
Me.LockTop = True
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 Macintosh, 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.
Me.MouseCursor = System.Cursors.FingerPointer
DesktopListBox.Name
Name As String
The name of the control. Set the name of the control in the Inspector.
This property is read-only.
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.
MessageBox(Me.SelectedPanelIndex.ToString)
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.
Me.Parent = Nil
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.
DesktopListBox.RowCount
RowCount As Integer
The number of rows in the DesktopListBox.
This property is read-only.
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.
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.
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.
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.
DesktopListBox.ScrollPositionX
ScrollPositionX As Integer
Index of the horizontal position of the DesktopListBox.
DesktopListBox.SelectedRowCount
SelectedRowCount As Integer
The number of rows selected (highlighted).
This property is read-only.
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:
If Me.SelectedRowIndex >= 0 Then
MessageBox(Me.CellTextAt(Me.SelectedRowIndex, 0))
End If
The following code displays a message if no row is selected:
If ListBox1.SelectedRowIndex = DesktopListBox.NoSelection Then
MessageBox("Please select a row first.")
End If
This example selects the first row in the ListBox:
ListBox1.SelectedRowIndex = 0
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.
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:
If Listbox1.SortingColumn = ListBox.None then
System.Beep
MessageBox("Please sort the rows by one of the columns.")
End If
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.
Me.TabIndex = 2
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:
Me.Tooltip = "Click to bark."
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:
Me.Top = 140
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.
DesktopListBox.Underline
Underline As Boolean
If True, applies the underline style of the text.
This code underlines the text in the control:
Me.Underline = True
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:
Me.Visible = False
DesktopListBox.Width
Width As Integer
The width (in points) of the control.
The following example resizes the control:
Me.Width = 200
DesktopListBox.Window
Window As DesktopWindow
The control's parent window.
This property is read-only.
This code gets the parent window's Title property.
MessageBox(Me.Window.Title)
Method descriptions
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.
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:
If Not obj.FolderItem.IsFolder Then Return True
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:
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:
Me.AcceptPictureDrop
DropObject Event:
If obj.PictureAvailable Then
Me.Backdrop = obj.Picture
End If
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.
Me.AcceptRawDataDrop("????")
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.
Me.AcceptTextDrop
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, Item is always assigned to column zero. In the case where AllowExpandableRows is True, AddExpandableRow adds Item 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.
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.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
Me.ColumnCount = 1
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.
Listbox1.AddExpandableRowAt(1, "New Hampshire")
DesktopListBox.AddListSelectionNotificationReceiver
AddListSelectionNotificationReceiver(receiver As ListSelectionNotificationReceiver)
The receiver passed is notified when the list selection changes.
DesktopListBox.AddRow
DesktopListBox AddRow
AddRow(ParamArray Item As String)
Appends a new blank row to the end of the ListBox.
Adding the string "October" to a new row in a ListBox named Listbox1:
ListBox1.AddRow("October")
The following line adds a row of months to a ListBox that has four columns:
Listbox1.AddRow("Sept", "Oct", "Nov", "Dec")
The following line adds a row of months to a ListBox that has four columns using an array:
Var months() As String = Array("Sept", "Oct", "Nov", "Dec")
ListBox1.AddRow(months)
The following adds a blank row then sets values for column 3:
ListBox1.AddRow
ListBox1.CellTextAt(ListBox1.LastAddedRowIndex, 2) = "Col 3"
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.
Listbox1.AddRowAt(1, "Steven")
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.
The following line adds rows of months to a ListBox:
Listbox1.AddRows("Sept", "Oct", "Nov", "Dec")
The following line adds rows of months to a ListBox using an array:
Var months() As String = Array("Sept", "Oct", "Nov", "Dec")
ListBox1.AddRows(months)
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 DesktopListBox.Alignments)
Assigns the alignment of the specified cell.
This example aligns sets the alignment of a cell to right:
ListBox1.CellAlignmentAt(1,1) = DesktopListBox.Alignments.Right
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 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:
Me.CellAlignmentOffsetAt(1, 3) = -10
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:
ListBox1.CellBoldAt(1, 1) = True
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 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:
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:
Me.CellBorderColorAt(0, 0) = BorderColor
You can also check the color of a cell by comparing it either to Color or a ColorGroup:
If CustomerList.CellBorderColorAt(0, 0) = Color.Green Then
System.Beep
MessageBox("This customer's order is paid in full.")
End If
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:
Me.CellTypeAt(1, 0) = DesktopListBox.CellTypes.CheckBox
To change the state of the cell, use the DesktopCheckBox.VisualStates enumeration of the DesktopCheckBox control:
ListBox1.CellCheckBoxStateAt(1, 0) = DesktopCheckbox.VisualStates.Indeterminate
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.
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.
ListBox1.CellItalicAt(1, 1) = True
DesktopListBox.CellTagAt
CellTagAt(Row As Integer, Column As Integer) As Variant
Gets or sets a "hidden" identifier associated with the cell identified by its parameters.
This example sets a tag for a cell.
Me.CellTagAt(1, 4) = "My Cell Tag"
This example displays the tag for a cell:
MessageBox(Me.CellTagAt(1, 4))
DesktopListBox.CellTextAt
CellTextAt(row As Integer, column As Integer = 0) As String
CellTextAt(row As Integer, column As Integer = 0, Assigns text 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.
In this example, the following code populates a two-column ListBox with the names of the controls in the window and their indexes.
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
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.
Listbox1.CellTooltipAt(0, 0) = "Enter your full name."
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 DesktopListBox.CellTypes)
Assigns the type to the specified cell.
This code shows a checkbox in a single cell:
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:
ListBox1.CellCheckBoxStateAt(0, 4) = DesktopCheckBox.VisualStates.Checked
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:
ListBox1.CellUnderlineAt(1, 1) = True
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.
Me.Close
DesktopListBox.ColumnAlignmentAt
ColumnAlignmentAt(column As Integer) As DesktopListBox.Alignments
Returns the alignment of the specified column.
ColumnAlignmentAt(column As Integer, Assigns DesktopListBox.Alignments)
Assigns the alignment to the specified column.
The example sets the column to right alignment:
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.
DesktopListBox.ColumnAlignmentOffsetAt
ColumnAlignmentOffsetAt(column As Integer) As Integer
Returns the decimal alignment point of the specified column.
ColumnAlignmentOffsetAt(column As Integer, Assigns 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:
Me.ColumnAlignmentOffsetAt(2) = -10
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.
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 or System to get the mouse coordinates to use with this method, you'll need to take into account that those System values are relative to the top-left corner of the entire screen.
This code in the DoublePressed event of a ListBox obtains the indexes of the cell that was double-clicked:
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:
Var xValue As Integer
xValue = System.MouseX - Me.Left - Self.Left - Me.TrueWindow.Left ' Calculate current mouse position relative to top left of ListBox
Var yValue As Integer
yValue = System.MouseY - Me.Top - Self.Top - Me.TrueWindow.Top ' Calculate current mouse position relative to top of ListBox.
Var row, column As Integer
row = Me.RowFromXY(xValue, yValue)
column=Me.ColumnFromXY(xValue, yValue)
MessageBox("You double-clicked in cell " + row.ToString + ", " + column.ToString)
DesktopListBox.ColumnSortDirectionAt
ColumnSortDirectionAt(column As Integer) As DesktopListBox.SortDirections
Returns the sort direction of the specified column.
ColumnSortDirectionAt(column As Integer, Assigns DesktopListBox.SortDirections)
Assigns the sort direction to the specified column.
This example sets the sort direction for a column.
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.
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 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.
Me.ColumnSortTypeAt(0) = DesktopListBox.SortTypes.Sortable
Me.ColumnSortTypeAt(1) = DesktopListBox.SortTypes.Sortable
Me.ColumnSortTypeAt(2) = DesktopListBox.SortTypes.NotSortable
DesktopListBox.ColumnTagAt
ColumnTagAt(column As Integer) As Variant
Gets and sets the column tag of the specified column.
DesktopListBox.ColumnTypeAt
ColumnTypeAt(column As Integer) As DesktopListBox.CellTypes
Returns the type of the specified column.
ColumnTypeAt(column As Integer, Assigns DesktopListBox.CellTypes)
Assigns the type to the specified column.
The following example makes a column editable:
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:
Me.ColumnTypeAt(4) = DesktopListbox.CellTypes.Checkbox
Me.CellCheckBoxStateAt(0, 4) = DesktopCheckBox.VisualStates.Indeterminate
Me.CellCheckBoxStateAt(1, 4) = DesktopCheckbox.VisualStates.Checked
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:
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.
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:
Var p As New Picture(Me.Width, Me.Height)
Me.DrawInto(p.Graphics, 0, 0)
Canvas1.Backdrop = p
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.
Me.CellTypeAt(row, column) = DesktopListbox.CellTypes.TextField
Me.EditCellAt(row, column)
This code marks an entire column as editable:
ListBox1.ColumnTypeAt(3) = DesktopListBox.CellTypes.TextArea
In the CellPressed event handler, you can then check if the column was pressed and then enable editing:
If column = 3 Then
Me.EditCellAt(row, column)
End If
DesktopListBox.HeaderAt
HeaderAt(index As Integer) As String
Returns the heading of the specified column.
HeaderAt(index As Integer, Assigns 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.,
Me.HeaderAt(ListBox.AllColumns) = "FirstName" + Chr(9) + "LastName"
You must use a space if you want an empty header; empty strings will use the default header.
ListBox1.HeaderAt(ListBox.AllColumns) = "" ' sets all headers of ListBox1 to their defaults.
ListBox1.HeaderAt(5) = "" ' sets column 5's header to its default heading
ListBox1.HeaderAt(5) = " " ' sets column 5's header to empty.
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.
Listbox1.PressHeader(0)
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:
Me.Refresh(True)
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:
Me.Refresh(100, 150, 200, 300)
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.
Listbox1.RefreshCell(1, 0)
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.
Listbox1.RemoveAllRows
DesktopListBox.RemoveListSelectionNotificationReceiver
RemoveListSelectionNotificationReceiver(receiver As ListSelectionNotificationReceiver)
Removes the receiver passed so that it is no longer notified when the list selection changes.
DesktopListBox.RemoveRowAt
RemoveRowAt(index As Integer)
Removes the row at the index passed.
This example removes the second row.
Listbox1.RemoveRowAt(1)
DesktopListBox.RowAt
RowAt(row As Integer) As DesktopListBoxRow
Returns the DesktopListBoxRow for the row indicated by the index passed.
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:
Var row As Integer = ListBox1.RowCount
Var depth As Integer = ListBox1.RowDepthAt(row)
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.
Me.AddExpandableRow("Players")
Me.RowExpandableAt(Me.LastAddedRowIndex) = False ' Disable expandable indicator
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:
ListBox1.RowExpandedAt(1) = Not ListBox1.RowExpandedAt(1)
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 or System to get the mouse coordinates to use with this method, you'll need to take into account that those System values are relative to the top-left corner of the entire screen.
This code in the DoublePressed event obtains the indexes of the cell that was double-clicked:
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:
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)
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.
Listbox1.RowImageAt(0) = UserPhotoImage
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.
For Each row As DesktopListBoxRow In ListBox1.Rows
If row.Tag = "Taxable" Then ComputeTaxes(row.CellTextAt(0))
Next
DesktopListBox.RowSelectedAt
RowSelectedAt(index As Integer) As Boolean
Gets or sets the selection status of the passed Row.
DesktopListBox.RowSelectedAt
RowSelectedAt(index As Integer, Assigns value As Boolean)
Gets or sets the selection status of the passed Row.
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,
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:
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:
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
DesktopListBox.RowTagAt
RowTagAt(Row As Integer) As Variant
Gets and sets the RowTag for the row.
To set the tag:
ListBox1.RowTagAt(row) = "MyTag"
To get the tag:
myTag = ListBox1.RowTagAt(row)
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 the Mac you need Full Keyboard Access turned on in System Preferences (Keyboard->Shortcuts) in order to manually set focus to non-text controls.
The following example 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.
Me.SetFocus
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:
Listbox1.HasHeader = True
The following code sorts a Listbox in descending order on the first column.
' 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
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):
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:
If column = 3 Then ' Is this the CheckBox column?
If Me.CellCheckBoxAt(row, column) Then
MessageBox("You checked the checkbox in row " + row.ToString)
Else
MessageBox("You unchecked the checkbox in row " + row.ToString)
End If
End If
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.
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.
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.
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:
If column = 2 Then ' Is this the editable column?
Me.ColumnTypeAt(column) = DesktopListBox.CellTypes.TextField
Me.EditCellAt(row, column)
Return True
End If
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.
DesktopListBox.Closing
Closing
The control is closing.
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.
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.
' 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
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 ContextualMenuAction event. This can be handy if you have the same contextual menu for several controls who share the same Parent (several on the same window for example). By returning False you can handle them all in a single event.
This simple event handler displays the value of the selected menu item.
If SelectedItem <> Nil Then MessageBox(selectedItem.Text)
Return True
DesktopListBox.DoublePressed
DoublePressed
The user has double-pressed (clicked or tapped) on a row in the ListBox.
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:
If Not obj.FolderItem.IsFolder Then Return True
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.
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.
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)
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.
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.
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:
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.
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.RowCount - 1
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
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.
If Obj.PictureAvailable Then
Me.Image = obj.Picture
ElseIf Obj.FolderItemAvailable Then
Me.Image = Picture.Open(obj.FolderItem)
End If
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.
Select Case location
Case listbox.DropLocations.AfterAllRows
MessageBox "add row after all rows"
Case listbox.DropLocations.AfterRow
MessageBox "add row after rowindex = " + row.ToString
Case listbox.DropLocations.OnControl
MessageBox "drop occurred ON control"
Case listbox.DropLocations.OnRow
MessageBox "add row to rowindex = " + row.ToString
End Select
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.
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.
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.
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.
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.
DesktopListBox.MenuBarSelected
MenuBarSelected
The user has selected a menu while the listbox has the focus.
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 or 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 do not get called.
The MouseDown event uses the DragItem constructor when the user drags the contents of the control. It is:
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
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.
DesktopListBox.MouseEnter
MouseEnter
The mouse has entered the area of the control.
DesktopListBox.MouseExit
MouseExit
The mouse has left the area of the control.
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.
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 or the control. Mouse clicks that are released to the left or above a control are negative.
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.
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.
Sub Opening()
Me.AcceptPictureDrop
Me.AcceptFileDrop("JPEG")
End Sub
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:
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":
If Me.CellTagAt(row, column) = "Red" Then
g.DrawingColor = Color.RGB(255, 0, 0)
g.FillRectangle(0, 0, g.Width, g.Height)
End If
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
RowPicture
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
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 draws a small triangle on the right side of the cell (the code is using column 3 as the cell to draw into):
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:
If Me.ColumnFromXY(x, y) = 3 Then
Return True
End If
This code in MouseUp displays a simple menu:
' Display menu if clicked in PopupMenu column
Var row As Integer = Me.RowFromXY(x, y)
Var col As Integer = Me.ColumnFromXY(x, y)
If col = 3 Then
Me.SelectedIndex = row
Me.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
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)
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.
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.
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.
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.
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:
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:
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
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
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:
For childRow As Integer = 0 To 5
Me.AddRow("Child " + childRow.ToString + " of row " + Me.CellTextAt(row, 0))
Next
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:
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:
' Draw black cell background
If row >= Me.RowCount Then Return False
g.AntiAlias = False
g.DrawingColor = Color.Ref
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.
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.
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.
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.
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.
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:
Me.CellTypeAt(1, 0) = DesktopListBox.CellTypes.CheckBox
To change the state of the cell, use the VisualStates enumeration of the CheckBox control:
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:
Me.Maximum = 50
Me.Minimum = 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:
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:
Me.AddRow("Single-line")
Me.AddRow("Multiple-line")
The BevelButton's Pressed event sets the value of the DesktopListBox's SelectionType property:
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.
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:
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:
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:
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:
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:
Me.AcceptTextDrop
Its DropObject event handler is this:
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:
Function DragRow (Drag As DragItem, Row As Integer) As Boolean
Var nRows As Integer
nRows = Me.RowCount - 1
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.
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.
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:
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:
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:
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.
' first column, descending order
ListBox1.ColumnSortDirectionAt(0) = ListBox.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:
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:
ListBox1.AddRow("October")
Adding a row at row 1 in ListBox1:
ListBox1.AddRowAt(1, "October")
Creating a three-column ListBox and adding the headings and the first row of information:
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:
ListBox1.Bold = True
ListBox1.Underline = True
Copying the fifth element of ListBox1 to another variable:
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:
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:
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:
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:
ListBox1.ColumnWidths = "60,40,20"
Copying the fifth row of the third column of ListBox1 to another variable:
Var e As String
e = ListBox1.CellTextAt(4, 2)
Assigning a value to the fifth row of the third column of ListBox1:
ListBox1.CellTextAt(4, 2) = "Bill"
Setting the fifth row of the third column of ListBox1 to bold, italic:
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.
ListBox1.AddRow("Users")
ListBox1.RowImageAt(0) = UsersFolder
Setting up the DragRow event handler to allow the user to drag a value from a ListBox:
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:
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:
ListBox1.RowExpandedAt(1) = Not ListBox1.RowExpandedAt(1)
This code populates a three-column ListBox with headings:
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:
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:
MessageBox(ListBox1.CellTextAt(ListBox1.SelectedRowIndex, 0))
Interfaces
This class implements the ListSelectionNotifier class interface.
Compatibility
Desktop projects on all supported operating systems.
See also
DesktopUIControl parent class; DesktopTextField controls; DatabaseColumn, DesktopListBoxColumn, RowSet classes