Loading document parsing libraries...
# Picker
Class
## About
`Picker` is the base class for popovers that let the user choose a value, such as the table size picker opened from the Table toolbar button. Subclass it, or `GridPicker` for a grid of cells, and override `PreferredWidth`, `PreferredHeight`, `Paint`, and the pointer and key methods. The editor positions, draws, and routes input to the picker, keeps one open at a time, and closes it on Escape or a press outside it.
## Methods
| Name | Parameters | Return Type | Description |
| --- | :---: | :---: | --- |
| Cancel | (None) | (None) | Closes the picker without choosing a value. |
| Closing | committed As Boolean | (None) | Called after the picker closes. committed is True when it closed because Commit chose a value. Override to release state. |
| Commit | value As Variant | (None) | Chooses the supplied value and closes the picker. The value reaches the toolbar item as the Tag of the DesktopMenuItem passed to PerformToolbarAction, PerformAction, or ToolbarItemPressed. |
| ControlsChanged | (None) | (None) | Tells the editor that SearchFieldFrame, ScrollbarFrame, or ScrollMaximum changed, so it repositions its search field and scrollbar. |
| InitialSearchText | (None) | String | Returns the text the editor's search field shows when the picker opens. The default is empty. The editor does not call SearchChanged for it. |
| InitialSecondaryText | (None) | String | Returns the text the editor's secondary field shows when the picker opens. The default is empty. The editor does not call SecondaryChanged for it. |
| Invalidate | (None) | (None) | Redraws the picker. Call it after changing what Paint draws. |
| KeyDown | key As String | Boolean | Called with each key pressed while the picker is open. Return True when the key was handled. An unhandled Escape closes the picker, and other unhandled keys go to the editor. |
| MinimumHeight | (None) | Double | Returns the smallest height the picker can be shown at when the editor has less room than PreferredHeight. The default is PreferredHeight, so a picker is not shrunk unless it can lay itself out in less space. |
| MouseCursorAt | x As Double <br> y As Double | MouseCursor | Returns the cursor for the supplied point in picker coordinates, or Nil for the standard pointer. |
| Opening | (None) | (None) | Called each time the picker opens, after Owner, ToolbarItem, and Bounds are set. Override to reset state, such as the hovered or selected entry. |
| Paint | g As Graphics | (None) | Draws the picker's content. g uses picker coordinates, with 0, 0 at the top-left of Bounds, and is clipped to the picker. The editor draws the popup background and border first. |
| PointerDown | x As Double <br> y As Double | Boolean | Called when the pointer is pressed inside the picker, in picker coordinates. Return True to receive PointerDragged and PointerUp until the pointer is released. A press inside the picker never reaches the document, whatever this returns. |
| PointerDragged | x As Double <br> y As Double | (None) | Called as the pointer moves with the button held, in picker coordinates, after PointerDown returned True, or after the press that opened the picker from its toolbar button. The point can lie outside the picker. |
| PointerMoved | x As Double <br> y As Double | (None) | Called when the pointer moves while the picker is open, in picker coordinates. The point can lie outside the picker. |
| PointerUp | x As Double <br> y As Double | (None) | Called when the pointer is released, in picker coordinates, after PointerDown returned True; the point can lie outside the picker. Also called when the press that opened the picker from its toolbar button is released over the picker, so dragging from the button into the picker and releasing can choose, as in a native menu. |
| PreferredHeight | (None) | Double | Returns the height the picker needs. The editor reduces it to fit the window. |
| PreferredWidth | (None) | Double | Returns the width the picker needs. The editor reduces it to fit the window. |
| Preview | value As Variant | (None) | Shows the supplied value applied to the document, as if it had been chosen, without recording undo or reporting a change. Each call replaces the previous preview, and Nil takes it back. The editor takes the preview back when the picker closes, and before delivering a chosen value. Previews apply to pickers opened from a toolbar item. |
| ScrollbarFrame | (None) | Rect | Returns where the editor shows its vertical scrollbar, in picker coordinates, or Nil for none. It is hidden while ScrollMaximum is 0. |
| ScrollMaximum | (None) | Double | Returns the largest ScrollPosition: the height of the scrollable content beyond what fits. |
| ScrollWheel | deltaY As Double | Boolean | Called for wheel or trackpad scrolling over the picker. The default moves ScrollPosition when there is content to scroll. |
| SearchChanged | query As String | (None) | Called when the text in the editor's search field changes. |
| SearchFieldFrame | (None) | Rect | Returns where the editor shows its search field, in picker coordinates, or Nil for none. While the field has focus, the picker's KeyDown receives its keys first. |
| SearchHint | (None) | String | Returns the hint shown in the empty search field. |
| SearchTooltip | (None) | String | Returns the search field's tooltip. |
| SecondaryChanged | text As String | (None) | Called when the text in the editor's secondary field changes. |
| SecondaryFieldFrame | (None) | Rect | Returns where the editor shows a second text field, in picker coordinates, or Nil for none. It works like SearchFieldFrame, for pickers that need two fields. |
| SecondaryFieldHint | (None) | String | Returns the hint shown in the empty secondary field. |
| SecondaryFieldKeyDown | key As String | Boolean | Called with each key pressed while the secondary field has focus. Return True when the key was handled. The default passes the key to KeyDown. |
| SecondaryFieldTooltip | (None) | String | Returns the secondary field's tooltip. |
| ThemeColor | kind As GraffitiProEditor.ThemeColors | Color | Returns the supplied theme color from the editor showing the picker, so pickers match the editor's chrome. |
| TooltipAt | x As Double <br> y As Double | String | Returns the tooltip for the supplied point in picker coordinates, or an empty string for none. |
## Properties
| Name | Type | Default Value | Description |
| --- | :---: | :---: | --- |
| Bounds | Rect | (None) | Returns the picker's frame in editor coordinates while it is open. |
| Height | Double | (None) | Returns the picker's height. |
| Owner | GraffitiProEditor.Editor | (None) | Returns the editor showing the picker, or Nil when it is closed. |
| ScrollPosition | Double | (None) | Gets or sets how far the content is scrolled, from 0 to ScrollMaximum. Setting it moves the editor's scrollbar and redraws the picker. |
| ToolbarItem | GraffitiProEditor.ToolbarItem | (None) | Returns the toolbar item that opened the picker, or Nil when it was opened from code. |
| Visible | Boolean | (None) | Returns whether an editor is showing this picker. |
| Width | Double | (None) | Returns the picker's width. |
## Notes
Coordinates passed to `Paint`, `PointerDown`, `PointerDragged`, `PointerUp`, `PointerMoved`, `MouseCursorAt`, and `TooltipAt` are relative to the picker, with 0, 0 at the top-left of `Bounds`. Mirror the layout yourself when `Owner.IsRightToLeftInterface` is True; `GridPicker` does.
`Commit` closes the picker and then delivers the value: to the toolbar item that opened it, as a `DesktopMenuItem` whose caption is the item's caption and whose `Tag` is the value, recording undo first when the item's `RecordsUndo` is True; and always to the editor's `PickerClosed` event. A picker opened by `ShowPicker` with no toolbar item delivers only to `PickerClosed`. `Cancel`, Escape, a press outside the picker, and `Editor.ClosePicker` close it without a value.
Pickers draw with the editor's chrome theme colors through `ThemeColor`, and use the editor's localized strings through `Owner`. A picker instance can be reopened; `Opening` runs each time.
A picker never creates controls. It asks the editor for a search field, a secondary field, and a scrollbar instead; see Search Field and Scrollbar. `ListPicker` does this for you.
### Lifecycle
A picker goes through these steps each time it opens:
1. `Editor.ShowPicker`, or a press on a toolbar item whose `Picker` is set, closes any open picker and calls `Attach`, so `Owner` and `ToolbarItem` are set.
2. The editor measures `PreferredWidth` and `PreferredHeight`, places the picker below its anchor, or above it when it fits only there, sets `Bounds`, empties its search field, and calls `Opening`. Reset state there. Once the picker is showing and its search field has focus, the editor raises `PickerOpened`.
3. While open, the editor calls `Paint` after drawing the popup's background and border, and passes pointer movement, presses, wheel scrolling, and keys. While the pointer is over the picker, the editor shows the tooltip `TooltipAt` returns for that point. A press inside the picker never reaches the document. When `PointerDown` returns True, the editor follows the press with `PointerDragged` and `PointerUp`, as Xojo's `MouseDrag` and `MouseUp` follow `MouseDown`. The press on a toolbar button that opens a picker is followed the same way: `PointerDragged` as the pointer moves, and `PointerUp` if it is released over the picker, so pressing the button, dragging into the picker, and releasing chooses like a native menu. A quick click on the button leaves the picker open. Keys reach `KeyDown` whether the editor or its search field has focus. `Bounds` can change as the window resizes, so measure from `Width` and `Height` in `Paint` rather than caching them.
4. `Commit(value)` or a close (`Cancel`, Escape, a press outside the picker or on what opened it, `Editor.ClosePicker`, the editor becoming read-only, or another picker or chooser opening) ends it. The editor hides its search field and scrollbar, calls `Closing`, and sets `Owner` to Nil.
5. After a `Commit`, the value is delivered, and then `PickerClosed` is raised; after a close, only `PickerClosed`.
The editor keeps the picker inside its visible area as the window resizes: it stays where it opened until the editor's edge reaches it, then moves, and then shrinks, but never below `MinimumHeight`. When even that does not fit below the main toolbar, the picker covers the toolbar, as a native menu would. A picker that can lay itself out in less height overrides `MinimumHeight`; `ListPicker` does, keeping its search field and two rows.
Values are delivered where the picker was opened from:
- A main toolbar item of a registered node type: that type's `PerformToolbarAction`.
- Another main toolbar item: the editor's built-in action for its identifier, or the `ToolbarItemPressed` event.
- An item in a node's popover toolbar: that node's `PerformAction`, with the item's action index, after recording undo when the item's `RecordsUndo` is True.
- `ShowPicker(picker, anchor)` from code: only `PickerClosed`.
In the first three cases the value is the `Tag` of a `DesktopMenuItem` whose text is the item's caption, exactly as if it were chosen from a native menu, so a handler written for a menu works unchanged. Any `Variant` can be a value: an `Integer`, a `Pair`, a `Color`, an object, and so on.
The toolbar button that opened a picker stays highlighted until it closes. A read-only editor does not open pickers for items that record undo.
### Previews
A picker opened from a toolbar item can show a choice applied to the document before it is made: call `Preview(value)` with the value it would commit, and `Preview(Nil)` to take it back. `ListPicker` and `GridPicker` do this for you when `PreviewsChoices` is True, previewing the selected item or hovered cell as it moves; override `PreviewValue` to return Nil for a choice that must not be previewed, such as one that opens a dialog.
The editor applies a preview exactly as it would apply the choice, through the item's action or the node's `PerformAction`, so a picker needs no separate preview code. Before the first preview it saves the selected nodes, the selection, the typing style, and the document's font, size, and alignment, and it puts them back before each later preview, when the preview is taken back, and when the picker closes. A committed value is then applied for real, once, with its undo step. While a preview is applied, undo entries are discarded, `IsChanged` is restored, and neither `ContentChanged`, the inspector, nor collaborators hear about it.
Preview only choices that are safe to apply and take back, such as a font, size, color, alignment, or spacing. Choices that insert or delete nodes, open dialogs, or act outside the document must not be previewed. Pickers opened from code with `ShowPicker(picker, anchor)` have no item to apply a value through, so their previews do nothing.
### Search Field and Scrollbar
The editor owns one search field and one scrollbar and lends them to whichever picker is open. A picker never creates, adds, parents, or closes a control itself, so it does not need a window, does not have to clip anything, and cannot leave a control behind.
To show a search field:
1. Return its frame from `SearchFieldFrame`, in picker coordinates, for example `New Rect(12, 12, Width - 24, 28)`. Return Nil, the default, for no field.
2. Optionally return the empty field's hint from `SearchHint` and its tooltip from `SearchTooltip`.
3. Filter in `SearchChanged(query)`, which the editor calls with the field's text each time it changes, then call `Invalidate` to redraw.
The editor does the rest. It creates the field the first time any picker asks, as a child of the editor so it is clipped with the editor, places it over the picker at the supplied frame and keeps it there as the window resizes, empties it before `Opening`, gives it focus when the picker opens, and hides it and returns focus to the editor when the picker closes. The field is emptied without calling `SearchChanged`, so reset the picker's own search state in `Opening`.
While the field has focus, each key goes to the picker's `KeyDown` first. Return True to keep it, as `ListPicker` does with Up, Down, Return, and Enter; an unhandled Escape closes the picker, and other unhandled keys edit the text. The picker never reads the field: `SearchChanged` supplies the text, so keep it if it is needed later, as `ListPicker.Query` does.
A picker that needs two fields, such as find and replace, also returns a frame from `SecondaryFieldFrame`, with `SecondaryFieldHint` and `SecondaryFieldTooltip`, and receives that field's text in `SecondaryChanged`. Keys typed in it go to `SecondaryFieldKeyDown`, which passes them to `KeyDown` unless overridden. Tab and Shift-Tab move between the two fields.
Both fields start empty unless `InitialSearchText` or `InitialSecondaryText` return text; the editor fills them before `Opening` without calling `SearchChanged` or `SecondaryChanged`, and selects the search field's text when it gives the field focus.
To show a scrollbar, return its frame from `ScrollbarFrame` and the height of the content beyond the visible area from `ScrollMaximum`. The editor shows the scrollbar there while `ScrollMaximum` is greater than 0, moves `ScrollPosition` when the user drags it or scrolls over the picker, and moves the scrollbar when the picker sets `ScrollPosition`. Draw the content offset by `ScrollPosition`.
The editor asks for these frames again whenever the picker moves or resizes. Call `ControlsChanged` when they change for another reason, such as filtering that changes `ScrollMaximum`; setting `ScrollPosition` does this already.
## Examples
Open a picker from a toolbar item by setting the item's `Picker`. Its chosen value reaches the node or application as the `Tag` of the `DesktopMenuItem` passed to `PerformToolbarAction`, `PerformAction`, or the editor's `ToolbarItemPressed` event.
### Custom Picker
A complete picker drawn without `GridPicker` or `ListPicker`: five circles, where pointing fills them up to the pointer and releasing the pointer over one chooses that rating, after a click in the picker or a drag from its toolbar button.
```xojo
Class RatingPicker
Inherits GraffitiProEditor.Picker
Private mHovered As Integer = -1
Function PreferredWidth() As Double
Return 5 * 28 + 24
End Function
Function PreferredHeight() As Double
Return 52
End Function
Sub Opening()
mHovered = -1
End Sub
Sub Paint(g As Graphics)
For star As Integer = 0 To 4
g.DrawingColor = If(star <= mHovered, ThemeColor(GraffitiProEditor.ThemeColors.ChromeAccent), ThemeColor(GraffitiProEditor.ThemeColors.ChromeControl))
g.FillOval(12 + star * 28, 14, 24, 24)
Next
End Sub
Sub PointerMoved(x As Double, y As Double)
Var star As Integer = Floor(( x - 12 ) / 28)
If y < 0 Or y > Height Or star < 0 Or star > 4 Then star = -1
If star = mHovered Then Return
mHovered = star
Invalidate
End Sub
Function PointerDown(x As Double, y As Double) As Boolean
'// Follow the press, so the rating is chosen where it is released.
PointerMoved(x, y)
Return True
End Function
Sub PointerDragged(x As Double, y As Double)
PointerMoved(x, y)
End Sub
Sub PointerUp(x As Double, y As Double)
PointerMoved(x, y)
If mHovered >= 0 Then Commit(mHovered + 1)
End Sub
Function KeyDown(key As String) As Boolean
'// Return chooses the hovered rating; Escape is left to the editor.
If key = Chr(13) And mHovered >= 0 Then
Commit(mHovered + 1)
Return True
End If
Return False
End Function
End Class
```
This picker does not mirror itself in a right-to-left interface; check `Owner.IsRightToLeftInterface` to do so.
### Node Popover Picker
```xojo
'// In a node subclass's ActionItem(index)
item = New GraffitiProEditor.ToolbarItem("stamp", "Stamp", GraffitiProEditor.ToolbarItem.Kinds.Menu)
item.Picker = New StampPicker '// A GridPicker subclass
'// In the same node's PerformAction(index, selectedItem)
If selectedItem <> Nil Then StampName = selectedItem.Tag.StringValue
```
### Open From Code
```xojo
'// The value arrives in the editor's PickerClosed event.
Editor.ShowPicker(New StampPicker, anchorRect)
```
### Search Field
A picker that filters a short list of names as the user types. It only describes where the field goes and what it says; the editor creates, positions, focuses, and removes the field. For a longer or scrolling list, subclass `ListPicker`, which does all of this for you.
```xojo
Class StatusPicker
Inherits GraffitiProEditor.Picker
Statuses() As String
Private mMatches() As String
Sub Constructor()
Statuses = Array("Draft", "In Review", "Approved", "Published")
End Sub
Function PreferredWidth() As Double
Return 220
End Function
Function PreferredHeight() As Double
Return 12 + 28 + 8 + Statuses.Count * 24 + 12
End Function
'// Ask for the editor's search field across the top, in picker coordinates.
Function SearchFieldFrame() As Rect
Return New Rect(12, 12, Width - 24, 28)
End Function
Function SearchHint() As String
Return "Search statuses"
End Function
'// The field starts empty each time, so start with every status.
Sub Opening()
SearchChanged("")
End Sub
'// Called as the user types.
Sub SearchChanged(query As String)
mMatches.ResizeTo(-1)
For Each status As String In Statuses
If query.Trim = "" Or status.IndexOf(query.Trim) >= 0 Then mMatches.Add(status)
Next
Invalidate
End Sub
Sub Paint(g As Graphics)
g.DrawingColor = ThemeColor(GraffitiProEditor.ThemeColors.ChromeText)
g.FontSize = 13
For index As Integer = 0 To mMatches.LastIndex
g.DrawText(mMatches(index), 16, 48 + index * 24 + 17)
Next
End Sub
Function PointerDown(x As Double, y As Double) As Boolean
Return True
End Function
Sub PointerUp(x As Double, y As Double)
Var index As Integer = Floor(( y - 48 ) / 24)
If y >= 48 And index <= mMatches.LastIndex Then Commit(mMatches(index))
End Sub
'// Keys typed in the field reach KeyDown first: Return chooses the first
' match. Unhandled keys edit the search text, and Escape closes.
Function KeyDown(key As String) As Boolean
If key = Chr(13) And mMatches.Count > 0 Then
Commit(mMatches(0))
Return True
End If
Return False
End Function
End Class
```