XUISourceList
Description
A powerful control that is frequently used as a navigator control. It can replicate the sidebar functionality seen in macOS Finder and the Windows File Explorer or even the Xojo IDE navigator.
Properties
| Name | Type | Read-Only |
|---|---|---|
| AllowMultipleSelection | Boolean |
|
| Hierarchical | Boolean |
|
| mIsDraggingRow | Boolean |
|
| mLastMouseDownRow | Integer |
|
| mLastMouseDownX | Integer |
|
| mLastMouseDownY | Integer |
|
| mLastMouseDragRow | Integer |
|
| mLastMouseDragX | Integer |
|
| mLastMouseDragY | Integer |
|
| mMouseMoveRow | Integer |
|
| mRenderer | XUISourceListRenderer |
|
| mSections() | XUISourceListItem |
|
| mSelectedItems() | XUISourceListItem |
|
| mStyle | XUISourceListStyle |
|
| Renderer | XUISourceListRenderer |
|
| Style | XUISourceListStyle |
Methods
| Name | Parameters | Returns |
|---|---|---|
| AddSection | section As XUISourceListItem |
|
| AddToSourceList | item As XUISourceListItem |
|
| ExpandRow | row As Integer |
|
| HandleContiguousRowClick | item As XUISourceListItem, x As Integer, y As Integer |
|
| HandleDiscontiguousRowClick | item As XUISourceListItem, x As Integer, y As Integer |
|
| IsDraggingOverRow | row As Integer |
Boolean |
| ItemAtRowIndex | index As Integer |
XUISourceListItem |
| ItemAtRowIndex_ | parent As XUISourceListItem, current As Integer, target As Integer, result As XUISourceListItem |
|
| MoveItem | item As XUISourceListItem, newParent As XUISourceListItem, index As Integer |
|
| Rebuild | ||
| RemoveAllSections | ||
| ResetMouseProperties | ||
| RowForItem | item As XUISourceListItem |
Integer |
| SectionAtIndex | index As Integer |
XUISourceListItem |
| SectionWithName | sectionTitle As String, caseSensitive As Boolean |
XUISourceListItem |
| SelectItemAtRow | row As Integer |
XUISourceListItem |
| StoppedDragging |
Events
| Name | Parameters | Returns |
|---|---|---|
| ClickedItemWidget | item As XUISourceListItem |
|
| CollapsedItem | item As XUISourceListItem |
|
| ExpandedItem | item As XUISourceListItem |
|
| ItemSelected | item As XUISourceListItem, x As Integer, y As Integer |
|
| ItemUnselected | item As XUISourceListItem, x As Integer, y As Integer |
|
| MouseDidMove | x As Integer, y As Integer |
|
| MovedItem | item As XUISourceListItem, oldParent As XUISourceListItem, newParent As XUISourceListItem |
|
| Opening |
Constants
| Name | Type |
|---|---|
| DROP_OVER_THRESHOLD | Double |
DROP_OVER_THRESHOLD As Double This percentage of the row dropped on that is considered the actual row. Above and below this are considered the row above and the row below. 0.5 = 50%.
Property Descriptions
AllowMultipleSelection As Boolean
If True then multiple item selection is permitted.
Hierarchical As Boolean
If False then only sections draw their children. Items do not. This allows for subtle visual differences like seen between the macOS Finder and Mail apps.
mIsDraggingRow As Boolean
True if the use is actively dragging a row.
mLastMouseDownRow As Integer
The row under the mouse during the last MouseDown event. May be -1.
mLastMouseDownX As Integer
The X coordinate in the last MouseDown event.
mLastMouseDownY As Integer
The Y coordinate in the last MouseDown event.
mLastMouseDragRow As Integer
The value of mLastMouseDownRow during the last MouseDrag event.
mLastMouseDragX As Integer
The local X value determined in DragTimer.Action.
mLastMouseDragY As Integer
The local X value determined in DragTimer.Action.
mMouseMoveRow As Integer
The row under the mouse cursor. Updated in the MouseMove event. Will be -1 if there is no valid row under the mouse.
mRenderer As XUISourceListRenderer
The renderer to use to draw the rows in the source list.
mSections() As XUISourceListItem
This source list's sections.
mSelectedItems() As XUISourceListItem
The currently selected items. May be empty.
mStyle As XUISourceListStyle
The colour style to use for the source list.
Renderer As XUISourceListRenderer
The renderer to use to draw the rows in the source list.
Style As XUISourceListStyle
The colour style to use for the source list.
Method Descriptions
AddSection(section As XUISourceListItem)
Appends the passed item as a section in the source list. Rebuilds the source list.
AddToSourceList(item As XUISourceListItem)
Internal method for physically adding an item to the source list.
ExpandRow(row As Integer)
Internal methods. Actually expands row in the listbox. Called by Rebuild() and AddToSourceList().
HandleContiguousRowClick(item As XUISourceListItem, x As Integer, y As Integer)
The user has clicked item in the source list whilst holding down the shift key.
HandleDiscontiguousRowClick(item As XUISourceListItem, x As Integer, y As Integer)
The user has clicked item in the source list whilst holding down Cmd (macOS) or CTRL (Windows / Linux).
IsDraggingOverRow(row As Integer) As Boolean
Returns True if the user is currently dragging over the item at row.
ItemAtRowIndex(index As Integer) As XUISourceListItem
Returns the item at the 0-based row index. Only visible rows are counted.
Row 0 is the first visible row. May return Nil.
ItemAtRowIndex_(parent As XUISourceListItem, current As Integer, target As Integer, result As XUISourceListItem)
Internal recursive method.
MoveItem(item As XUISourceListItem, newParent As XUISourceListItem, index As Integer)
Moves item to be a child of newParent. By default appends it as a child but optionally you can stipulate the
index in newParent to move it to. Does not rebuild the tree.
Rebuild()
Rebuilds the source list.
RemoveAllSections()
Removes every section in the source list. Rebuilds the source list.
ResetMouseProperties()
Resets the private properties tracking mouse actions.
RowForItem(item As XUISourceListItem) As Integer
Returns the 0-based row that item appears on. Only visible items are included.
Row 0 is the first visible row. Returns -1 if not found.
SectionAtIndex(index As Integer) As XUISourceListItem
Returns the section at 0-based index. Raises an InvalidArgumentException if index is invalid.
The index is the seciton index, not the row index.
SectionWithName(sectionTitle As String, caseSensitive As Boolean) As XUISourceListItem
Returns the first matching section whose title is sectionTitle. Returns Nil if not found.
SelectItemAtRow(row As Integer) As XUISourceListItem
Selects the item at row (0 based).
Returns the item selected or Nil if none was selected.
Does not raise the ItemSelected() event.
StoppedDragging()
Stops DragTimer and marks that we are no longer dragging.
Event Descriptions
ClickedItemWidget(item As XUISourceListItem) The user has clicked on an item's widget.
CollapsedItem(item As XUISourceListItem) The user has collapsed an item by clicking on the disclosure widget.
ExpandedItem(item As XUISourceListItem) The user has expanded an item by clicking on the disclosure widget.
ItemSelected(item As XUISourceListItem, x As Integer, y As Integer)
An item in the source list was selected. If clicked, X and Y are the mouse coordinates of the click local to the row the item is on. These will be -1 if the selection was programatic.
ItemUnselected(item As XUISourceListItem, x As Integer, y As Integer)
An item in the source list was unselected. If clicked, X and Y are the mouse coordinates of the click local to the row the item is on. These will be -1 if the selection was programatic.
MouseDidMove(x As Integer, y As Integer) The mouse has moved within the source list. X and Y are local to the source list control.
MovedItem(item As XUISourceListItem, oldParent As XUISourceListItem, newParent As XUISourceListItem)
Called when item has been moved from oldParent to newParent. Occurs when there has been a drag reordering.
Opening() The source list control is opening.