Metadata-Version: 2.4
Name: wx-accessible-grid
Version: 0.6.1
Summary: An accessible data grid for wxPython built on a native virtual wx.ListCtrl, read directly by NVDA, JAWS, and VoiceOver with no WebView: instant population at any size, native row navigation, and native multi-select.
Project-URL: Homepage, https://github.com/Community-Access/wx-accessible-grid
Author: Community Access
Author-email: Taylor Arndt <taylor@techopolisonline.com>
Maintainer-email: Taylor Arndt <taylor@techopolisonline.com>
License: MIT
License-File: LICENSE
Keywords: a11y,accessibility,datagrid,grid,jaws,keyboard,listctrl,native,nvda,screen-reader,table,voiceover,wxpython,wxwidgets
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Adaptive Technologies
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.10
Requires-Dist: wxpython>=4.2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# wx-accessible-grid

An accessible, editable data grid for wxPython that a blind person can actually
use. It is a **real native wx control**: a virtual `wx.ListCtrl` in report mode.
NVDA, JAWS, and VoiceOver read it directly, the way they read any native list,
with no WebView and no HTML in the path.

Earlier versions rendered a semantic ARIA grid into a WebView. That worked, but
it put a browser document between your data and the screen reader, depended on a
WebView2/WKWebView runtime, and paged the DOM to stay fast. The native virtual
`wx.ListCtrl`, proven in Versatile Radio Programmer's channel grid, reads each
row correctly as you arrow through it, populates instantly at any size, and needs
no browser runtime. That is the library's approach now.

It is built for data entry, not a spreadsheet engine. There are no formulas. What
there is, is a native grid that is fully keyboard-operable and announced
correctly, with editing that round-trips through your model.

## What you get

- A native virtual list (`LC_REPORT | LC_VIRTUAL`). Virtual means rows are pulled
  on demand through a single `OnGetItemText` callback, so a grid with thousands
  of rows populates instantly and there is no paging. The screen reader still
  gets a correct sense of "row N of many" from the native list itself.
- Up and down move by row; left and right move by cell. Arrow up and down and
  the screen reader reads the focused row, because it is a genuine native list
  item, not a styled `<div>` or an ARIA emulation. Arrow left and right and a
  cell cursor walks the columns of that row, speaking each cell as "value, column
  name" so you can read across a row one field at a time. (A native list will not
  announce per cell on its own, so the grid voices the cell through an `announce`
  callback you pass in; see below.)
- Multi-select by default. Selecting rows for a bulk operation (move, reorder,
  delete a region) is a native selection the user already knows how to drive. The
  host reads the selected rows, acts through the model, and refreshes.
- Selection and focus helpers that keep the screen reader honest. A native list
  item is only spoken when its control has system focus, so moving to a row takes
  focus to the grid, makes the row visible, and ensures it is read. Restoring a
  moved block re-selects the whole block and focuses the first row.
- Editing round-trips through your model, so the value the screen reader confirms
  is the validated, normalized one, never the raw keystrokes. If an edit is
  rejected the user hears why.
- A pure-Python model with no wx in it. Columns, row data, selection math, and
  cell formatting are all plain Python, so they are unit-testable headless,
  without a display.

## Install

```bash
pip install wx-accessible-grid
```

That pulls in wxPython.

## Use it

Describe your columns and provide the row data through a model, then drop the
grid into a sizer. The grid is a virtual `wx.ListCtrl`, so it asks your model for
each cell's text as it paints, rather than holding every row in the control.

```python
import wx
from wx_accessible_grid import AccessibleGrid, GridModel, Column

class ChannelModel(GridModel):
    def __init__(self, rows):
        self._rows = rows
        self._cols = [
            Column("num", "#", is_row_header=True),
            Column("name", "Name"),
            Column("mode", "Mode"),
            Column("active", "Active"),
            Column("volume", "Volume"),
        ]

    def columns(self):
        return self._cols

    def row_count(self):
        return len(self._rows)

    def cell_text(self, row, column):
        # the text the list paints and the screen reader reads for this cell
        if column == "num":
            return str(row + 1)
        val = self._rows[row][column]
        if column == "active":
            return "Yes" if val else "No"
        return str(val)

grid = AccessibleGrid(panel, ChannelModel(rows), label="Memory channels",
                      announce=speak)
sizer.Add(grid.control, 1, wx.EXPAND)
```

`announce` is how left/right speaks. A native list does not announce per cell, so
when the cell cursor moves the grid calls `announce("146.520, Frequency")` and
your app says it however it speaks elsewhere (VRP routes this to prism, plus the
status bar). Leave `announce` off and left/right still move the cursor, just
silently. Up/down need nothing here: the native list reads the row itself.

The grid exposes the native selection and the cell cursor so the host can act on
them:

```python
nums = grid.selected_rows()      # selected rows, or the focused row if none
grid.select_rows([3, 4, 5])      # replace the selection
grid.focus_row(3)                # move focus there and make sure it is read
grid.refresh_rows([3])           # repaint just those rows after an edit
row, col = grid.current_cell()   # where the left/right cursor is, for host editing
```

The `dev` extra (`pip install "wx-accessible-grid[dev]"`) adds pytest for the
model tests, which run without wx.

## Keyboard

- Arrow up and down: move the focused row. The screen reader reads the row as a
  native list item.
- Arrow left and right: move the cell cursor across the columns of the focused
  row. Each move speaks "value, column name". The cursor stops at the first and
  last columns; it does not wrap.
- `Home` / `End`: first / last row. `Page Up` / `Page Down`: a screenful at a
  time. All standard native `wx.ListCtrl` navigation works, because it is a
  native list.
- Space and `Ctrl+Space`: extend or toggle the native selection.
- Editing and row actions are wired by the host through the selection and focus
  helpers (for example, a native edit dialog or a context menu on `Shift+F10`),
  so they use real native controls that read correctly.

## How it works

`AccessibleGrid` wraps a `wx.ListCtrl` created with `LC_REPORT | LC_VIRTUAL`.
Report mode gives it real column headers; virtual mode means it never stores the
rows itself: it calls your model's `cell_text(row, column)` for each visible cell
as it paints. Because it is a native control, the platform accessibility layer
(UIA on Windows, NSAccessibility on macOS, AT-SPI on Linux) exposes the rows
directly to the screen reader. No HTML, no WebView bridge, no injected JavaScript.

The model carries all the data and the index/number and selection arithmetic, in
plain Python with no wx, so it can be tested headless. The grid widget is a thin
shell over the native list plus the selection and focus helpers that make sure a
moved or edited row is both selected and actually spoken.

Left and right are the one thing the native list cannot do for itself: it has no
per-cell cursor. So the grid keeps its own current-column index, handles the
left/right keys, and on each move reads the cell from the model and hands the
text to your `announce` callback. Up and down stay entirely native, so the row
read you get is the real one from the platform, not something reconstructed.

## Status

This is the native build. The library moved off the WebView-hosted ARIA grid to
a native virtual `wx.ListCtrl` after the native approach proved out in Versatile
Radio Programmer's channel grid (instant population at full radio size, correct
per-row reading, native multi-select). 0.6.0 adds the left/right cell cursor so
you can read across a row a field at a time, not just row by row. Tested on macOS
and in headless unit tests for the model and navigation. NVDA and JAWS
verification on Windows, with a host that wires `announce` to speech, is the next
milestone; reports welcome.

## License

MIT. A Community Access open-source project, created by Taylor Arndt.
