# ListPicker
Class Inherits GraffitiProEditor.Picker
## About
`ListPicker` is a `Picker` that shows a searchable, scrolling list of items, such as the font picker and the node insertion chooser. The editor supplies the search field and scrollbar. Override `ItemCount` and `ItemCaption`, and optionally `ItemValue`, `ItemMatches`, `ItemShownWithoutSearch`, and `DrawItem`. Pointing at an item selects it, the arrow keys move the selection, and releasing the pointer over it, Return, or Enter chooses it with `Commit(ItemValue(index))`. Pressing the toolbar button that opens it, dragging to an item, and releasing chooses that item.
## Methods
| Name | Parameters | Return Type | Description |
| --- | :---: | :---: | --- |
| ColumnCount | (None) | Integer | Returns the number of columns items are laid out in. The default is Columns; override it to choose by width. |
| DrawItem | g As Graphics <br> index As Integer <br> frame As Rect <br> highlighted As Boolean | (None) | Draws one item in list coordinates: frame is the item's row within the clipped list area. highlighted is True for the hovered or selected item. The default fills highlighted rows and draws ItemCaption; override it to draw icons or styled captions. |
| FilteredCount | (None) | Integer | Returns the number of items that match the search text. |
| FilteredItem | position As Integer | Integer | Returns the item index shown at the supplied position in the filtered list, or -1. |
| IsRightToLeft | (None) | Boolean | Returns whether the editor's interface reads right to left. |
| ItemAtPoint | x As Double <br> y As Double | Integer | Returns the index of the item at the supplied point in picker coordinates, or -1. |
| ItemBaseline | g As Graphics <br> frame As Rect | Double | Returns the baseline that centers g's current font vertically in the supplied frame. |
| ItemCaption | index As Integer | String | Returns the caption of the supplied item, used by the default DrawItem and ItemMatches. Override it. |
| ItemCount | (None) | Integer | Returns the number of items. Override it. |
| ItemFrame | position As Integer | Rect | Returns the frame of the item shown at the supplied position in the filtered list, in picker coordinates. |
| ItemMatches | index As Integer <br> query As String | Boolean | Returns whether the supplied item matches query, which is trimmed and lowercase and never empty. The default searches ItemCaption. |
| ItemShownWithoutSearch | index As Integer | Boolean | Returns whether the supplied item is listed while the search field is empty. The default is True; return False for items that should appear only as search results. |
| ItemValue | index As Integer | Variant | Returns the value chosen by the supplied item. The default is the item index. |
| KeyDown | key As String | Boolean | Moves the selection with the arrow keys and chooses it with Return or Enter. |
| ListFrame | (None) | Rect | Returns the area the items scroll in, in picker coordinates. |
| MinimumHeight | (None) | Double | Returns the height of the search field and two rows, the least a list can be shown at; the list scrolls in the rest. |
| MouseCursorAt | x As Double <br> y As Double | MouseCursor | Shows the pointing-hand cursor over items. |
| Opening | (None) | (None) | Clears the search, selects the first item, and scrolls to the top. Call Super.Opening first when overriding. |
| Paint | g As Graphics | (None) | Draws the visible items with DrawItem, or EmptyText when no item matches the search. |
| PointerDown | x As Double <br> y As Double | Boolean | Selects the pressed item and follows the press, so the item is chosen on release. |
| PointerDragged | x As Double <br> y As Double | (None) | Selects the item under the pointer while it is dragged. |
| PointerMoved | x As Double <br> y As Double | (None) | Hovers and selects the item under the pointer. |
| PointerUp | x As Double <br> y As Double | (None) | Chooses the item under the pointer when it is released over one. |
| PreferredHeight | (None) | Double | Returns the height of the search field and VisibleRows rows. |
| PreferredWidth | (None) | Double | Returns ListWidth. |
| PreviewValue | index As Integer | Variant | Returns the value previewed while the supplied item is selected, when PreviewsChoices is True: by default its ItemValue. Return Nil for an item that cannot be previewed, such as one that opens a dialog. |
| Refilter | (None) | (None) | Rebuilds the list from ItemCount and the search text. Call it after the items change while the picker is open. |
| ScrollbarFrame | (None) | Rect | Places the scrollbar beside the list, on the trailing side. |
| ScrollMaximum | (None) | Double | Returns how far the rows extend below the list area. |
| ScrollToSelection | (None) | (None) | Scrolls the selected item into view. |
| SearchChanged | query As String | (None) | Filters the items by the search text and selects the first match. |
| SearchFieldFrame | (None) | Rect | Places the search field at the top when ShowSearchField is True. |
| SearchHint | (None) | String | Returns SearchHintText. |
| SearchTooltip | (None) | String | Returns SearchTooltipText. |
## Properties
| Name | Type | Default Value | Description |
| --- | :---: | :---: | --- |
| ColumnGap | Double | 6 | Gets or sets the space between columns. |
| Columns | Integer | 1 | Gets or sets the number of columns used by the default ColumnCount. |
| EmptyText | String | (None) | Gets or sets the text shown when no item matches the search. |
| HoveredItem | Integer | (None) | Returns the index of the item under the pointer, or -1. |
| ListWidth | Double | 300 | Gets or sets the picker's preferred width. |
| Padding | Double | 12 | Gets or sets the space between the content and the edge of the picker. |
| PreviewsChoices | Boolean | (None) | Gets or sets whether the selected item is previewed in the document with Preview as the selection moves. Off by default; choose it only for values that are safe to apply and take back, such as a font or color. |
| Query | String | (None) | Returns the search text. |
| RowGap | Double | 3 | Gets or sets the space between rows. |
| RowHeight | Double | 36 | Gets or sets the height of each row. |
| SearchHintText | String | (None) | Gets or sets the hint shown in the empty search field. |
| SearchTooltipText | String | (None) | Gets or sets the search field's tooltip. |
| SelectedItem | Integer | (None) | Gets or sets the index of the selected item, which Return chooses, or -1. Setting an item hidden by the search does nothing. |
| ShowSearchField | Boolean | True | Gets or sets whether the editor shows its search field above the list. |
| VisibleRows | Integer | 5 | Gets or sets the number of rows the preferred height shows. |
## Notes
Items are identified by their index, from 0 to `ItemCount - 1`. The search text filters them through `ItemMatches`; while it is empty, items whose `ItemShownWithoutSearch` returns False are left out, so they appear only as search results. Positions in the filtered list map back to item indexes through `FilteredItem`. `SelectedItem` and `HoveredItem` are item indexes, or -1. Set `SelectedItem` after `Super.Opening` to start on the current value; it scrolls into view.
Set `Columns`, or override `ColumnCount`, to lay items out in a grid; Up and Down then move a row, and Left and Right a column until the user types a search, when they move the search field's caret again. `RowHeight`, `RowGap`, `ColumnGap`, `VisibleRows`, `ListWidth`, and `Padding` size the list, and `EmptyText` is shown when nothing matches. Set `ShowSearchField` to False for a list without a search field.
Set `PreviewsChoices` to True to show the selected item applied to the document as the selection moves, by pointing or with the arrow keys; closing without choosing takes it back. `PreviewValue` supplies the previewed value, `ItemValue` by default; return Nil from it for items that must not be previewed. See the `Picker` note Previews.
The search field and scrollbar are the editor's own, lent to the list as described in the `Picker` note Search Field and Scrollbar; a `ListPicker` subclass never creates or positions them. Set `SearchHintText` and `SearchTooltipText` for the field's hint and tooltip, and override `ItemMatches` to change what a search matches. The list filters as the user types, selects the first match, scrolls back to the top, and shows the scrollbar only while the items do not fit; `Query` returns the current search text.
## Examples
```xojo
Class SnippetPicker
Inherits GraffitiProEditor.ListPicker
Snippets() As String
Function ItemCount() As Integer
Return Snippets.Count
End Function
Function ItemCaption(index As Integer) As String
Return Snippets(index)
End Function
Function ItemValue(index As Integer) As Variant
Return Snippets(index)
End Function
End Class
'// The node's toolbar item opens it; PerformAction receives the snippet.
item.Picker = mSnippetPicker
```