QAccessible 类

QAccessible 类提供了与无障碍性相关的枚举和静态函数。 更多信息...

头文件 #include <QAccessible>
CMakefind_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmakeQT += gui

公共类型

结构体State
枚举Event { AcceleratorChanged, ActionChanged, ActiveDescendantChanged, Alert, AttributeChanged, …, VisibleDataChanged }
Id
InterfaceFactory
枚举InterfaceType { TextInterface, ValueInterface, ActionInterface, TableInterface, TableCellInterface, …, SelectionInterface }
标志Relation
枚举RelationFlag { Label, Labelled, Controller, Controlled, DescriptionFor, …, AllRelations }
枚举Role { AlertMessage, Animation, Application, Assistant, Border, …, Window }
枚举Text { Name, Description, Value, Help, Accelerator, UserText }
枚举TextBoundaryType { CharBoundary, WordBoundary, SentenceBoundary, ParagraphBoundary, LineBoundary, NoBoundary }

静态公共成员

QAccessibleInterface *accessibleInterface(QAccessible::Id id)
voiddeleteAccessibleInterface(QAccessible::Id id)
voidinstallFactory(QAccessible::InterfaceFactory factory)
boolisActive()
QAccessibleInterface *queryAccessibleInterface(QObject *object)
QAccessible::IdregisterAccessibleInterface(QAccessibleInterface *iface)
voidremoveFactory(QAccessible::InterfaceFactory factory)
voidsetRootObject(QObject *object)
QAccessible::IduniqueId(QAccessibleInterface *iface)
voidupdateAccessibility(QAccessibleEvent *event)

详细说明

此类是 QWidget 应用无障碍性 的一部分。

无障碍应用程序可供无法使用传统方式使用应用程序的人使用。

此类中的函数用于无障碍应用程序(也称为 AT 服务器)和辅助技术(AT 客户端,例如屏幕阅读器和盲文显示器)之间的通信。客户端和服务器以以下方式进行通信

服务器和客户端之间的通信由 setRootObject() 函数初始化。可以向 QAccessible 中的静态函数安装函数指针,以替换或扩展其默认行为。

Qt 支持微软的 Active Accessibility (MSAA)、macOS Accessibility 和 Unix/X11 AT-SPI 标准。其他后端可以通过 QAccessibleBridge 支持。

在 Unix/X11 AT-SPI 实现中,当满足以下两个条件时,应用程序变为可访问的

  • org.a11y.Status.IsEnabled DBus 属性为真
  • org.a11y.Status.ScreenReaderEnabled DBus 属性为真

设置 DBus AT-SPI 属性的另一种方法是设置 QT_LINUX_ACCESSIBILITY_ALWAYS_ON 环境变量。

除了 QAccessible 的静态函数外,Qt 还提供了一种通用接口 QAccessibleInterface,可用于封装所有小部件和对象(例如,QPushButton)。此单个接口提供了辅助技术所需的全部元数据。Qt 以插件的形式为其内置小部件提供该接口的实现。

当您开发自定义小部件时,您可以为 QAccessibleInterface 创建自定义的子类,并作为插件(使用 QAccessiblePlugin)分发表达,或者将其编译到应用程序中。同样,Qt 的预定义无障碍支持也可以作为插件(默认)或直接编译到 Qt 库中。使用插件的主要优势是,如果实际使用,才将无障碍类加载到内存中;它们不会减慢没有使用辅助技术的常见情况。

Qt 还包括两个方便的类,QAccessibleObjectQAccessibleWidget,这些类继承自 QAccessibleInterface 并提供最低限度的元数据(例如,小部件几何,窗口标题,基本帮助文本)。您可以用作封装自定义 QObjectQWidget 子类的基类。

另请参阅 QAccessibleInterface

成员类型文档

enum QAccessible::Event

此枚举类型定义了可访问的事件类型。

常量描述
QAccessible::AcceleratorChanged0x80C0操作键盘快捷键已被更改。
QAccessible::ActionChanged0x0101操作已被更改。
QAccessible::ActiveDescendantChanged0x0102 
QAccessible::Alert0x0002系统警报(例如,来自 QMessageBox 的消息)
QAccessible::AttributeChanged0x0103 
QAccessible::ContextHelpEnd0x000D对象的上下文帮助(QWhatsThis)已完成。
QAccessible::ContextHelpStart0x000C对象的上下文帮助(Q WhatsThis)已经开始。
QAccessible::DefaultActionChanged0x80B0可访问对象的默认 QAccessible::Action 已更改。
QAccessible::DescriptionChanged0x800D对象的 QAccessible::Description 已更改。
QAccessible::DialogEnd0x0011对话框(QDialog)已被隐藏
QAccessible::DialogStart0x0010对话框(QDialog)已被设置为可见。
QAccessible::DocumentContentChanged0x0104文本文档的内容已更改。
QAccessible::DocumentLoadComplete0x0105文档已加载。
QAccessible::DocumentLoadStopped0x0106已停止加载文档。
QAccessible::DocumentReload0x0107已启动文档重新加载。
QAccessible::DragDropEnd0x000F拖放操作即将完成。
QAccessible::DragDropStart0x000E即将开始拖放操作。
QAccessible::Focus0x8005一个对象已获得键盘焦点。
QAccessible::ForegroundChanged0x0003一个窗口已被激活(即在桌面上获得焦点的新窗口)。
QAccessible::HelpChanged0x80A0对象的QAccessible::Help文本属性已更改。
QAccessible::HyperlinkEndIndexChanged0x0108超链接显示文本的结束位置已更改。
QAccessible::HyperlinkNumberOfAnchorsChanged0x0109超链接中的锚点数量已更改,可能是因为显示文本被分割以提供多个链接。
QAccessible::HyperlinkSelectedLinkChanged0x010A已选择的超链接的链接已更改。
QAccessible::HyperlinkStartIndexChanged0x010D超链接显示文本的开始位置已更改。
QAccessible::HypertextChanged0x010E超链接的显示文本已更改。
QAccessible::HypertextLinkActivated0x010B一个超链接已被激活,可能通过点击或通过按键来实现。
QAccessible::HypertextLinkSelected0x010C一个超链接已被选中。
QAccessible::HypertextNLinksChanged0x010F 
QAccessible::LocationChanged0x800B屏幕上对象的定位已更改。
QAccessible::MenuCommand0x0018触发了菜单项。
QAccessible::MenuEnd0x0005菜单已关闭(Qt对所有菜单使用PopupMenuEnd)。
QAccessible::MenuStart0x0004在菜单栏上打开了菜单(Qt对所有菜单使用PopupMenuStart)。
QAccessible::NameChanged0x800C对象的QAccessible::Name属性已更改。
QAccessible::ObjectAttributeChanged0x0110 
QAccessible::ObjectCreated0x8000创建了一个新的对象。
QAccessible::ObjectDestroyed0x8001删除了一个对象。
QAccessible::ObjectHide0x8003一个对象被隐藏;例如,使用QWidget::hide()。被隐藏的对象的任何子对象都不会发送此事件。当对象被其他对象遮挡而隐藏时,不会发送此事件。
QAccessible::ObjectReorder0x8004布局或项目视图已添加、移除或移动了一个对象(Qt不使用此事件)。
QAccessible::ObjectShow0x8002一个对象被显示;例如,使用QWidget::show()。
QAccessible::PageChanged0x0111 
QAccessible::ParentChanged0x800F对象的父对象已更改。
QAccessible::PopupMenuEnd0x0007弹出菜单已关闭。
QAccessible::PopupMenuStart0x0006弹出菜单已打开。
QAccessible::ScrollingEnd0x0013滚动条滚动操作已结束(鼠标已释放滑块手柄)。
QAccessible::ScrollingStart0x0012滚动条滚动操作即将开始;这可能是由在滑块手柄上的鼠标按下引起的。
QAccessible::SectionChanged0x0112 
QAccessible::SelectionAdd0x8007在项目视图中已将项目添加到选择中。
QAccessible::SelectionRemove0x8008在项目视图中已从选择中删除项目。
QAccessible::Selection0x8006在菜单或项目视图中已更改选择。
QAccessible::SelectionWithin0x8009项目视图中发生了对选择的多次更改。
QAccessible::SoundPlayed0x0001一个对象播放了声音
QAccessible::TableCaptionChanged0x0113已更改表格标题。
QAccessible::TableColumnDescriptionChanged0x0114表格列的描述已更改,通常位于列标题中。
QAccessible::TableColumnHeaderChanged0x0115表格列标题已更改。
QAccessible::TableRowDescriptionChanged0x0117表格行的描述已更改,通常位于行标题中。
QAccessible::TableRowHeaderChanged0x0118表格行标题已更改。
QAccessible::TableSummaryChanged0x0119已更改表格摘要。
QAccessible::TextColumnChanged0x011D文本列已更改。
QAccessible::VisibleDataChanged0x0122 

此枚举值的定义与IAccessible2MSAA规范中定义的值相同。

QAccessible::Id

unsigned的同义词,由QAccessibleInterface缓存使用。

QAccessible::InterfaceFactory

这是对具有以下签名的函数指针的typedef

typedef QAccessibleInterface *myFactoryFunction(const QString &key, QObject *);

函数接收一个QString和一个QObject指针,其中QString是标识接口的键。使用QObject将它们传递给QAccessibleInterface,以便它可以持有其引用。

如果键和QObject没有对应的QAccessibleInterface,则将返回nullptr

查询AccessibilityInterface()会调用已安装的工厂,直到提供接口。

枚举QAccessible::InterfaceType

QAccessibleInterface支持几个子接口。为了提供有关一些对象更多信息,它们的可访问表示形式应该实现一个或多个这些接口。

注意:在子类化这些接口之一时,需要实现QAccessibleInterface::interface_cast()。

常量描述
QAccessible::TextInterface0用于支持选择或超过一行文本的文本。简单的标签不需要实现此接口。
QAccessible::ValueInterface2用于处理值的对象,例如滑动条或滚动条。
QAccessible::ActionInterface3用于允许用户触发动作的交互式对象。基本上是所有允许例如鼠标交互的东西。
QAccessible::TableInterface5用于列表、表和树。
QAccessible::TableCellInterface6用于TableInterface对象中的单元格。
QAccessible::HyperlinkInterface7用于超链接节点(通常作为文本节点的子节点嵌入)
QAccessible::SelectionInterface (自Qt 6.5起)8对于支持选择子对象的非文本对象。

另请参阅:QAccessibleInterface::interface_cast()、QAccessibleTextInterfaceQAccessibleValueInterfaceQAccessibleActionInterfaceQAccessibleTableInterfaceQAccessibleTableCellInterfaceQAccessibleSelectionInterface

枚举QAccessible::RelationFlag
flags QAccessible::Relation

本枚举类型定义了可以组合起来表示两个可访问对象之间关系的位标志。它用于relations()函数,该函数返回调用对象的全部相关接口列表以及每个对象的详细关系。

列表中的每一项都是一个QPair,其中第二个成员存储由第一个成员代表的返回对象与原始(调用者)接口/对象之间的关系类型。

下表中的返回对象是指返回列表中的对象,而原始对象是由调用接口表示的。

常量描述
QAccessible::Label0x00000001返回的对象是原始对象的标签。
QAccessible::Labelled0x00000002返回的对象被原始对象标注。
QAccessible::Controller0x00000004返回的对象控制原始对象。
QAccessible::Controlled0x00000008返回的对象由原始对象控制。
QAccessible::DescriptionFor (自Qt 6.6起用于)0x00000010返回的对象为原始对象提供描述。
QAccessible::Described (自Qt 6.6起用于)0x00000020返回的对象由原始对象描述。
QAccessible::FlowsFrom (自Qt 6.6起用于)0x00000040内容从逻辑上从返回的对象流向原始对象。
QAccessible::FlowsTo (自Qt 6.6起用于)0x00000080内容从逻辑上从原始对象流向返回的对象。
QAccessible::AllRelations0xffffffff用作掩码来指定我们感兴趣的是所有关系的信息

relations()的实现返回这些标志的组合。某些值是互斥的。

关系类型是QFlags<RelationFlag>的typedef。它存储了关系标志值的或表示。

enum QAccessible::Role

此枚举定义了可访问对象的角色。它们是

常量描述
QAccessible::AlertMessage0x00000008用于提醒用户的对象。
QAccessible::Animation0x00000036显示动画的对象。
QAccessible::Application0x0000000E应用程序的主窗口。
QAccessible::Assistant0x00000020提供交互式帮助的对象。
QAccessible::Border0x00000013表示边界的对象。
QAccessible::ButtonDropDown0x00000038下拉列表项的按钮。
QAccessible::ButtonDropGrid0x0000003A下拉网格的按钮。
QAccessible::ButtonMenu0x00000039下拉菜单的按钮。
QAccessible::Canvas0x00000035显示用户可以与之交互的图形的对象。
QAccessible::Caret0x00000007表示系统光标(文本光标)的对象。
QAccessible::Cell0x0000001D表格中的单元格。
QAccessible::Chart0x00000011显示数据图形表示的对象。
QAccessible::CheckBox0x0000002C可以勾选或取消勾选的选项。某些选项提供“混合”状态,例如既不勾选也不取消勾选。
QAccessible::Client0x0000000A窗口的客户区域。
QAccessible::Clock0x0000003D显示时间的时钟。
QAccessible::ColorChooser0x404允许用户选择颜色的对话框。
QAccessible::Column0x0000001B单元格列,通常位于表格中。
QAccessible::ColumnHeader0x00000019数据列的标题。
QAccessible::ComboBox0x0000002E用户可以从中选择的项目列表。
QAccessible::ComplementaryContent0x42C文档或网页中的辅助内容部分,通常是一个地标(参见WAI-ARIA)。
QAccessible::Cursor0x00000006表示鼠标光标的对象。
QAccessible::Desktop0x00000082表示桌面或工作区。
QAccessible::Dial0x00000031表示旋钮或刻度盘的对象。
QAccessible::Dialog0x00000012对话框。
QAccessible::Document0x0000000F文档,例如在办公应用程序中。
QAccessible::EditableText0x0000002A可编辑文本,如行或文本编辑。
QAccessible::Equation0x00000037表示数学方程式的对象。
QAccessible::Footer0x40E页面中的页脚(通常在文档中)。
QAccessible::Form0x410包含控件的网络表单。
QAccessible::Graphic0x00000028图形或图片,例如图标。
QAccessible::Grip0x00000004用户可以拖动以更改小部件大小的手柄。
QAccessible::Grouping0x00000014表示其他对象的逻辑组对象的通用容器。
QAccessible::Heading0x414文档中的标题。
QAccessible::HelpBalloon0x0000001F在单独的、短暂存在的窗口中显示帮助的对象。
QAccessible::HotkeyField0x00000032允许用户输入键序列的热键字段。
QAccessible::Indicator0x00000027表示当前值或项的指示器。
QAccessible::LayeredPane0x00000080可以包含分层子对象的通用容器。
QAccessible::Link0x0000001E通往其他内容的链接。
QAccessible::List0x00000021用户可以选择一个或多个项的项目列表。
QAccessible::ListItem0x00000022项目列表中的项。
QAccessible::MenuBar0x00000002用户可以通过它打开菜单的菜单栏。
QAccessible::MenuItem0x0000000C菜单或菜单栏中的项。
QAccessible::NoRole0x00000000该对象没有角色。这通常表示无效对象。
QAccessible::Note0x41B内容为资源主要内容的辅助或括号内容的章节。
QAccessible::Notification0x00000086表示通知的对象(例如在系统托盘中)。此角色仅在Linux上有效。
QAccessible::PageTab0x00000025用户可以选择切换到对话框中不同页面的页签。
QAccessible::PageTabList0x0000003C页签列表。
QAccessible::Paragraph0x00000083文本段(通常在文档中找到)。
QAccessible::Pane0x00000010一个通用容器。
QAccessible::PopupMenu0x0000000B列出用户可以执行操作的选项的菜单。
QAccessible::ProgressBar0x00000030显示正在进行的操作进度的对象。
QAccessible::PropertyPage0x00000026用户可以更改选项和设置属性页。
QAccessible::Button0x0000002B按钮。
QAccessible::RadioButton0x0000002D表示与其他选项互斥的选项的对象。
QAccessible::Row0x0000001C一个单元格行,通常位于表格中。
QAccessible::RowHeader0x0000001A用于数据行的标题。
QAccessible::ScrollBar0x00000003滚动条,允许用户滚动可见区域。
QAccessible::Section0x00000085文档中的一个部分。
QAccessible::Separator0x00000015将空间划分为逻辑区域的中断符。
QAccessible::Slider0x00000033滑块,允许用户在给定范围内选择值。
QAccessible::Sound0x00000005表示声音的对象。
QAccessible::SpinBox0x00000034一个单选框小部件,允许用户在给定范围内输入值。
QAccessible::Splitter0x0000003E在子小部件之间分配可用空间的分隔器。
QAccessible::StaticText0x00000029静态文本,例如其他小部件的标签。
QAccessible::StatusBar0x00000017状态栏。
QAccessible::Table0x00000018表示以行和列网格形式的数据的表格。
QAccessible::Terminal0x00000081终端或命令行界面。
QAccessible::TitleBar0x00000001窗口标题栏的标题。
QAccessible::ToolBar0x00000016工具栏,将用户经常访问的小部件分组在一起。
QAccessible::ToolTip0x0000000D一个工具提示,提供关于其他对象的信息。
QAccessible::Tree0x00000023树结构中的项目列表。
QAccessible::TreeItem0x00000024树结构中的项。
QAccessible::UserRole0x0000ffff用于用户定义角色的第一个值。
QAccessible::WebDocument0x00000084HTML文档,通常在浏览器中。
QAccessible::Whitespace0x0000003B其他对象之间的空白。
QAccessible::Window0x00000009顶级窗口。

enum QAccessible::Text

此枚举指定可访问对象返回的字符串信息。

常量描述
QAccessible::Name0对象名称。这可以作为标识符或简短描述供可访问客户端使用。
QAccessible::Description1描述对象的简短文本。
QAccessible::Value2对象的值。
QAccessible::Help3提供有关如何使用对象的更详细文本。
QAccessible::Accelerator4执行对象的默认操作的键盘快捷键。
QAccessible::UserText0x0000ffff用于用户定义文本的第一个值。

enum QAccessible::TextBoundaryType

此枚举描述不同的文本边界类型。它遵循 IAccessible2 API 并用于 QAccessibleTextInterface

常量描述
QAccessible::CharBoundary0使用单个字符作为边界。
QAccessible::WordBoundary1使用单词作为边界。
QAccessible::SentenceBoundary2使用句子作为边界。
QAccessible::ParagraphBoundary3使用段落作为边界。
QAccessible::LineBoundary4使用换行符作为边界。
QAccessible::NoBoundary5没有边界(使用整个文本)。

另请参阅QAccessibleTextInterface

成员函数文档

[静态] QAccessibleInterface *QAccessible::accessibleInterface(QAccessible::Id id)

返回属于 idQAccessibleInterface

如果 id 无效,则返回 nullptr

[静态] void QAccessible::deleteAccessibleInterface(QAccessible::Id id)

从缓存中移除属于此 id 的接口并将其删除。该 id 变为无效,可以被缓存重新使用。

[静态] void QAccessible::installFactory(QAccessible::InterfaceFactory factory)

安装 InterfaceFactory factory。最后添加的工厂是 queryAccessibleInterface() 首先使用的。

[静态] bool QAccessible::isActive()

如果平台请求了辅助信息,则返回 true

在此功能返回 false 之前,直到屏幕阅读器之类的工具访问辅助框架。即使辅助功能未激活,也可以使用 QAccessible::queryAccessibleInterface()。但平台不会接收任何通知。

建议在不需要时,使用此函数来防止通过 updateAccessibility() 发送昂贵的通知。

[静态] QAccessibleInterface *QAccessible::queryAccessibleInterface(QObject *object)

如果为指定的 object 存在 QAccessibleInterface 实现,此函数返回实现的一个指针;否则返回 nullptr

此函数将调用所有已安装的工厂函数(从最近安装的到最不经常安装的顺序),直到找到一个为 object 的类提供接口的函数。如果没有工厂能提供类的辅助实现,函数将加载已安装的辅助插件,并检查任何插件是否可以提供实现。

如果没有可用对象类实现,此函数将尝试使用上述策略查找对象父类的实现。

所有接口都由内部缓存管理,不应进行删除。

[静态] QAccessible::Id QAccessible::registerAccessibleInterface(QAccessibleInterface *iface)

调用此函数以确保手动创建的接口正确地管理内存。

必须仅针对每个接口 iface 调用一次。在调用 queryAccessibleInterface 时会隐式调用它,只有当 QAccessibleInterfaces 使用“new”运算符实例化时才需要调用此函数。这不被推荐,尽可能使用默认函数,并让 queryAccessibleInterface() 负责此操作。

当需要重新实现 QAccessibleInterface::child() 函数并在构建后返回子节点时,需要调用此函数。

[静态] void QAccessible::removeFactory(QAccessible::InterfaceFactory factory)

从安装的 InterfaceFactories 列表中移除 factory

[静态] void QAccessible::setRootObject(QObject *对象)

将此应用程序可访问对象的根对象设置为对象。所有其他可访问对象都可以通过从根对象导航来访问。

通常,不需要调用此函数,因为 Qt 在进入 QApplication::exec() 的事件循环之前立即将 QApplication 对象设置为根对象。

使用 QAccessible::installRootObjectHandler() 将函数调用重定向到自定义处理函数。

另见 查询可访问接口

[静态] QAccessible::Id QAccessible::uniqueId(QAccessibleInterface *接口)

返回 QAccessibleInterface 的唯一 接口

[静态] void QAccessible::updateAccessibility(QAccessibleEvent *事件)

通知关于可能对可访问性客户端相关的重要更改。

事件 提供关于更改的详细信息。这包括变化的来源和性质。该 事件 应包含足够的信息以提供有意义的通知。

例如,类型 ValueChange 指示滑块的定位已更改。

当您的可访问对象或其子元素的状态发生改变时,无论是通过程序方式(例如,通过调用 QLabel::setText())还是通过用户交互时,调用此函数。

如果没有可访问性工具监听此事件,调用此函数的性能损失很小,但如果确定调用参数的成本高昂,可以测试 QAccessible::isActive() 以避免不必要的计算。

© 2024 Qt 公司。此处包含的文档贡献属于其各自所有者的版权。此处提供的文档受 GNU 自由文档许可证版本 1.3 的条款控制,由自由软件基金会发布。Qt 和相关的标志是芬兰及/或世界其他地区的 The Qt Company Ltd. 的商标。所有其他商标均为各自所有者的财产。