The grid

Cells

grid.hints lists the letters, 20 by default. The grid has a column and a row for each, 400 cells in all, and every cell is labelled with its column’s letter, then its row’s.

The cells share out the screen evenly, whatever its shape. On a 1920 × 1080 screen they’re 96 by 54 pixels. On Wayland and macOS, a screen scaled to 2x counts half its pixels each way, so a 4K display at 2x gets the same cells as 1080p.

As you type, the pointer follows. The first letter moves it to the middle of that column, and the second to the middle of the cell. Then the rest of the grid goes, and the cell splits into the sub-grid.

The sub-grid

grid.sub_hints labels the spots in a cell, and grid.sub_cols says how many go across. The default is 25 letters in rows of 5, a five-by-five square read left to right and top to bottom:

a s d f j
k l ; g h
q w e r t
y u i o p
z x c v b

A letter outside the sub-grid does nothing. Neither does a second refinement: to pick another spot, press Backspace first.

Fitting the screen

With target_cell_size, the grid has as many columns and rows as fit cells about that many pixels across, instead of one per letter:

[grid]
target_cell_size = 90

On a 1920 × 1080 screen that’s 12 rows of 90 pixels. Columns would be 21, but there are only 20 letters. They stay at 20, 96 pixels wide. The rows take the first 12 letters, from a to w, and a row letter past them does nothing. There are always at least two columns and two rows, and never more than there are letters.

Your own letters

[grid]
hints = ["a", "s", "d", "f", "g", "h", "j", "k", "l", ";"]
sub_hints = ["q", "w", "e", "a", "s", "d", "z", "x", "c"]
sub_cols = 3

This makes a 10 × 10 grid on the home row, refined three by three. Fewer letters mean bigger cells and a closer refinement. More letters do the opposite.

Keep the letters clear of the action keys, since an action’s key does that action first. The mode keys are the exception: by default b, c and v are sub-grid letters too, and they refine while the sub-grid is up.

Stepping back

Backspace undoes one step at a time: a letter, a refinement, or a switch to another mode. Escape closes the grid from anywhere.