# GridPicker
Class Inherits GraffitiProEditor.Picker
## About
`GridPicker` is a `Picker` that shows a grid of cells, hovers the cell under the pointer or moved to with the arrow keys, and chooses it when the pointer is released over it or with Return. Pressing the toolbar button that opens it, dragging to a cell, and releasing chooses that cell. The table size picker is one. Set `Rows` and `Columns`, and override `CellValue` to choose something other than the default row : column `Pair`, `DrawCell` or `CellHighlighted` to change how cells look, and `CaptionText` with `ShowCaption` to describe the hovered cell.
## Methods
| Name | Parameters | Return Type | Description |
| --- | :---: | :---: | --- |
| CaptionText | (None) | String | Returns the caption drawn below the grid when ShowCaption is True, usually describing the hovered cell. Override it; the default is empty. |
| CellAtPoint | x As Double <br> y As Double <br> ByRef row As Integer <br> ByRef column As Integer | Boolean | Finds the cell at the supplied point in picker coordinates and returns whether there is one. |
| CellFrame | row As Integer <br> column As Integer | Rect | Returns the frame of the supplied cell in picker coordinates. |
| CellHighlighted | row As Integer <br> column As Integer | Boolean | Returns whether the default DrawCell highlights the supplied cell. The default highlights the hovered cell; override it to highlight a range. |
| CellValue | row As Integer <br> column As Integer | Variant | Returns the value chosen by the supplied cell. The default is a row : column Pair of zero-based indexes. |
| DrawCell | g As Graphics <br> row As Integer <br> column As Integer <br> frame As Rect | (None) | Draws one cell in picker coordinates. The default draws a rounded cell, filled with the accent color when CellHighlighted is True. Override it to draw content such as a color or symbol. |
| HoverCell | row As Integer <br> column As Integer | (None) | Sets the hovered cell and redraws the picker. Pass -1 to clear it. |
| KeyDown | key As String | Boolean | Moves the hovered cell with the arrow keys and chooses it with Return or Enter. |
| Opening | (None) | (None) | Clears the hovered cell. Call Super.Opening when overriding. |
| Paint | g As Graphics | (None) | Draws every cell with DrawCell, then the caption when ShowCaption is True. |
| PointerDown | x As Double <br> y As Double | Boolean | Hovers the pressed cell and follows the press, so the cell is chosen on release. |
| PointerDragged | x As Double <br> y As Double | (None) | Hovers the cell under the pointer while it is dragged. |
| PointerMoved | x As Double <br> y As Double | (None) | Hovers the cell under the pointer. |
| PointerUp | x As Double <br> y As Double | (None) | Chooses the cell under the pointer when it is released over one. |
| PreferredHeight | (None) | Double | Returns the height of the grid, its padding, and its caption. |
| PreferredWidth | (None) | Double | Returns the width of the grid and its padding. |
| PreviewValue | row As Integer <br> column As Integer | Variant | Returns the value previewed while the supplied cell is hovered, when PreviewsChoices is True: by default its CellValue. Return Nil for a cell that cannot be previewed, such as one that opens a dialog. |
## Properties
| Name | Type | Default Value | Description |
| --- | :---: | :---: | --- |
| CellGap | Double | 3 | Gets or sets the space between cells. |
| CellSize | Double | 18 | Gets or sets the width and height of each cell. |
| Columns | Integer | 3 | Gets or sets the number of columns. |
| HoveredColumn | Integer | (None) | Returns the hovered cell's column, or -1 when no cell is hovered. |
| HoveredRow | Integer | (None) | Returns the hovered cell's row, or -1 when no cell is hovered. |
| Padding | Double | 12 | Gets or sets the space between the grid and the edge of the picker. |
| PreviewsChoices | Boolean | (None) | Gets or sets whether the hovered cell is previewed in the document with Preview as the hover moves. Off by default; choose it only for values that are safe to apply and take back, such as a color or alignment. |
| Rows | Integer | 3 | Gets or sets the number of rows. |
| ShowCaption | Boolean | (None) | Gets or sets whether CaptionText is drawn below the grid. |
## Notes
Cells are numbered from 0, by `row` and `column`, and laid out from `Padding`, `CellSize`, and `CellGap`; `CellFrame` returns a cell's frame in picker coordinates and `CellAtPoint` finds the cell at a point, counting half the gap around each cell so the hover does not flicker. In a right-to-left interface the columns run from the right.
`HoveredRow` and `HoveredColumn` give the hovered cell, or -1 before one is hovered. The pointer hovers a cell, and the arrow keys move the hover, starting from the first cell; call `HoverCell` from `Opening` to start somewhere else, such as on the current value. Return, Enter, or releasing the pointer over a cell chooses it with `Commit(CellValue(row, column))`; releasing elsewhere chooses nothing.
`DrawCell` draws each cell; the default fills it with the control color and fills `CellHighlighted` cells with the accent color. `CellHighlighted` returns the hovered cell by default; the table size picker returns every cell up to it. With `ShowCaption` set, `CaptionText` is drawn below the grid and redrawn as the hover moves.
Set `PreviewsChoices` to True to show the hovered cell applied to the document as the hover moves; closing without choosing takes it back. `PreviewValue` supplies the previewed value, `CellValue` by default; return Nil from it for cells that must not be previewed. See the `Picker` note Previews.
Override `Opening` with a call to `Super.Opening`, which clears the hover. Set `Rows` and `Columns` before the picker opens, since they decide its size.
## Examples
```xojo
Class SwatchPicker
Inherits GraffitiProEditor.GridPicker
Sub Constructor()
Rows = 2
Columns = 4
CellSize = 22
End Sub
Function CellValue(row As Integer, column As Integer) As Variant
Return Swatches(row * Columns + column)
End Function
Sub DrawCell(g As Graphics, row As Integer, column As Integer, frame As Rect)
g.DrawingColor = Swatches(row * Columns + column)
g.FillRoundRectangle(frame, 4, 4)
If CellHighlighted(row, column) Then
g.DrawingColor = ThemeColor(GraffitiProEditor.ThemeColors.ChromeAccent)
g.DrawRoundRectangle(frame, 4, 4)
End If
End Sub
End Class
```