Which approach should an SDL application use to make a custom-drawn UI accessible to screen readers?

Question

Our application renders its entire user interface through SDL (Simple DirectMedia Layer), drawing menus and dialogs onto a single window surface. We now need this workflow to be usable with screen readers such as NVDA and VoiceOver, not just with keyboard-only input.

From what I understand, SDL is a low-level windowing and input layer: it delivers keyboard events and offers SDL_StartTextInput for IME-aware text entry, but it does not populate the platform accessibility tree (UIA, AT-SPI, NSAccessibility) for custom-rendered content. That leaves the window effectively opaque to assistive technology unless the application adds something itself. I also could not find a documented cross-platform SDL API for announcing dynamic content changes, such as live-region-style updates when a dialog opens.

We are targeting SDL2 today, with SDL3 migration under consideration, so version differences in text input handling matter to us.

Is building per-platform accessibility bridges the accepted approach, or is embedding an accessible UI toolkit alongside SDL more practical in real projects? Does the answer change between SDL2 and SDL3? And is there any documented pattern for announcing dynamic content changes to screen readers from an SDL-rendered UI?

Muntasir · Answer

Direct answer
Build an accessibility bridge that exposes each custom‑drawn control to the operating system’s accessibility API (UI Automation/IAccessible2 on Windows, NSAccessibility on macOS, AT‑SPI on Linux) and forward SDL input events to that bridge. Use the platform’s live‑region mechanism to announce dynamic changes such as dialog openings or status updates.
Confirmed facts

SDL itself does not populate the platform accessibility tree for custom‑rendered content.
To be usable with NVDA, VoiceOver, Orca, etc., the application must provide accessible objects with correct role, name, description, state, and value.
Input focus and activation must be reported from SDL to the bridge so that screen readers can track navigation and activation.
Live‑region‑style announcements are done via the platform’s accessibility API (e.g., UI Automation LiveSettingChanged event, NSAccessibility AXLiveSettingChanged, or AT‑SPI object:live-region-changed).
SDL2 and SDL3 do not differ in accessibility support; the change in text‑input handling between the versions does not affect the bridge approach.

Steps needed for this case

Identify each UI element drawn by SDL (buttons, sliders, list items, dialogs, etc.).
For each element, create an accessible object in the platform API with the appropriate role (button, slider, listitem, dialog, …) and set its name (label) and any needed description or value.
Whenever the visual state changes (toggle, slider move, list selection, dialog show/hide), update the corresponding properties on the accessible object.
Register a callback for SDL mouse/keyboard/touch events; when an event hits a custom control, forward the event to the bridge so that focus moves and activation (press, click) are reported to the screen reader.
Implement a logical tab order if keyboard navigation is required; the bridge should accept focus‑change requests and move SDL’s internal focus accordingly.
For dynamic content such as a dialog appearing, fire a live‑region announcement through the platform API (e.g., raise a UI Automation LiveRegionChanged event with the dialog’s title or message).
Test with the native screen reader on each target platform (Narrator/ NVDA on Windows, VoiceOver on macOS, Orca on Linux) to verify that all controls are announced, states are spoken, and live updates are heard.

When the recommendation changes
If you need to support multiple platforms, let me know which operating systems you target so I can suggest whether a cross‑platform accessibility library (e.g., AccessKit) would reduce duplicated bridge code.

Which approach should an SDL application use to make a custom-drawn UI accessible to screen readers?

1 answer

Direct answer

Confirmed facts

Steps needed for this case

When the recommendation changes

Your perspective belongs here.

1 question comment