Which Qt 6 QAccessibleRole values map to platform accessibility roles for custom widgets?

Direct answer

The following QAccessibleRole values are reliably translated by Qt 6 to native platform roles on Windows UI Automation, macOS NSAccessibility, and Linux AT‑SPI. Using any of these roles for a custom widget will expose a meaningful role name to assistive technologies.

• Button → UIA ButtonControl / AXButton / AT‑SPI role:button
• CheckBox → UIA CheckBox / AXCheckBox / role:checkbox
• RadioButton → UIA RadioButton / AXRadioButton / role:radio
• ComboBox → UIA ComboBox / AXComboBox / role:combo box
• List → UIA List / AXList / role:list
• ListItem → UIA ListItem / AXListItem / role:list item
• Menu → UIA Menu / AXMenu / role:menu
• MenuItem → UIA MenuItem / AXMenuItem / role:menu item
• ProgressBar → UIA ProgressBar / AXProgressIndicator / role:progress bar
• ScrollBar → UIA ScrollBar / AXScrollBar / role:scroll bar
• Slider → UIA Slider / AXSlider / role:slider
• SpinBox → UIA Spinner / AXSpinButton / role:spin button
• Tab → UIA Tab / AXTab / role:tab
• TabWidget → UIA TabControl / AXTabGroup / role:tab panel
• Table → UIA Table / AXTable / role:table
• TableCell → UIA TableItem / AXCell / role:table cell
• Text → UIA Edit / AXTextField / role:text
• TextEdit → UIA Edit / AXTextArea / role:text box

Confirmed facts

These mappings come from the Qt 6 accessibility plugins (QWindowsAccessibility, QMacAccessibility, QUnixAccessibility) where the enum values are hard‑coded to the corresponding native role strings. Roles not listed above fall back to generic roles (UIA GenericControl, AXGroup/AXUnknown, AT‑SPI widget/generic) and often result in assistive technologies announcing "GenericControl" or providing no role name.

Likely explanation

When a custom widget inherits from QWidget (or QAccessibleWidget) and you call setAccessibleRole(QAccessible::Role), the Qt accessibility bridge forwards the enum to the platform plugin. The plugin looks up the enum in a static table; if a match exists it emits the native role, otherwise it uses the fallback. Therefore, to guarantee a specific native role you must choose a QAccessibleRole that appears in that table.

Steps for developers

1. Identify the desired native role (e.g., a button‑like control).
2. Select the matching QAccessibleRole from the list above (e.g., QAccessible::Button).
3. In your widget’s constructor or initialization code, call setAccessibleRole(QAccessible::Button) (or use QAccessibleWidget::setAccessibleRole).
4. Provide a meaningful name via setAccessibleName and, if needed, a description via setAccessibleDescription.
5. Verify the result with platform‑specific inspection tools:
1. Windows: Inspect.exe or UI Automation Verify → check ControlType and Name.
2. macOS: Accessibility Inspector → check AXRole, AXRoleDescription, and AXTitle.
3. Linux: accerciser or at‑spi‑inspector → check role and name attributes.
6. If the inspected role is generic, double‑check that the enum you used is in the reliable list; otherwise consider using a standard Qt widget that already maps correctly.

Missing diagnostic detail

If you are using a Qt 6 patch release earlier than 6.2, the mapping table may differ slightly; confirming your exact Qt version would change the recommendation to either upgrade or verify the mapping manually.