QAccessible 类

QAccessible 类提供与可访问性相关的枚举和静态函数。 更多...

头: #include <QAccessible>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: QT += gui

公共类型

struct State
enum Event { AcceleratorChanged, ActionChanged, ActiveDescendantChanged, Alert, AttributeChanged, …, VisibleDataChanged }
Id
InterfaceFactory
enum InterfaceType { TextInterface, ValueInterface, ActionInterface, TableInterface, TableCellInterface, …, SelectionInterface }
flags Relation
enum RelationFlag { Label, Labelled, Controller, Controlled, DescriptionFor, …, AllRelations }
enum 角色 { AlertMessage, Animation, Application, Assistant, Border, …, Window }
enum 文本 { Name, Description, Value, Help, Accelerator, UserText }
enum TextBoundaryType { CharBoundary, WordBoundary, SentenceBoundary, ParagraphBoundary, LineBoundary, NoBoundary }

静态公共成员

QAccessibleInterface * accessibleInterface (QAccessible::Id id )
void deleteAccessibleInterface (QAccessible::Id id )
void installFactory (QAccessible::InterfaceFactory factory )
bool isActive ()
QAccessibleInterface * queryAccessibleInterface (QObject * object )
QAccessible::Id registerAccessibleInterface (QAccessibleInterface * iface )
void removeFactory (QAccessible::InterfaceFactory factory )
void setRootObject (QObject * object )
QAccessible::Id uniqueId (QAccessibleInterface * iface )
void updateAccessibility (QAccessibleEvent * event )

详细描述

此类属于 QWidget 应用程序的可访问性 .

可访问应用程序可以由无法使用应用程序的人来使用,按约定方式。

此类中的函数被用于可访问应用程序 (也称 AT 服务器) 和可访问工具 (AT 客户机) (如屏幕阅读器和盲文显示) 之间的通信。客户端和服务器采有以下办法通信:

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

Qt 支持 MSAA (微软活动可访问性)、macOS 可访问性和 Unix/X11 AT-SPI 标准。使用 QAccessibleBridge 可以支持其它后端。

在 Unix/X11 AT-SPI 实现中,应用程序变为可访问当满足 2 条件时:

  • org.a11y.Status.IsEnabled DBus 特性为 true
  • org.a11y.Status.ScreenReaderEnabled DBus 特性为 true

设置 DBus AT-SPI 特性的替代是设置 QT_LINUX_ACCESSIBILITY_ALWAYS_ON 环境变量。

除 QAccessible 静态函数外,Qt 还提供一通用接口 QAccessibleInterface ,可用于包裹所有 Widget 和对象 (如 QPushButton )。此单一接口为辅助技术,提供所有必要元数据。Qt 为内置 Widget 作为插件提供此接口的实现。

当开发自定义 Widget 时,可以创建自定义子类为 QAccessibleInterface 并将它们分发作为插件 (使用 QAccessiblePlugin ) 或将它们编译进应用程序。同样,Qt 的预定义可访问性支持可以构建作为插件 (默认),或直接构建进 Qt 库。使用插件的主要优点是可访问性类仅加载进内存,若它们被实际使用;它们不会减慢没有使用辅助技术的常见情况。

Qt 还包括 2 方便类: QAccessibleObject and QAccessibleWidget ,继承自 QAccessibleInterface 并提供最小元数据公分母 (如:Widget 几何图形、窗口标题、基本帮助文本)。可以把它们用作基类,当包裹自定义 QObject or QWidget 子类。

另请参阅 QAccessibleInterface .

成员类型文档编制

enum QAccessible:: Event

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

常量 描述
QAccessible::AcceleratorChanged 0x80C0 动作的键盘加速键已改变。
QAccessible::ActionChanged 0x0101 动作已改变。
QAccessible::ActiveDescendantChanged 0x0102
QAccessible::Alert 0x0002 系统警报 (如:消息来自 QMessageBox )
QAccessible::AttributeChanged 0x0103
QAccessible::ContextHelpEnd 0x000D 上下文帮助 ( QWhatsThis ) 对于已完成对象而言。
QAccessible::ContextHelpStart 0x000C 上下文帮助 ( QWhatsThis ) 对于已初启对象而言。
QAccessible::DefaultActionChanged 0x80B0 可访问对象的默认 QAccessible::Action 已改变。
QAccessible::DescriptionChanged 0x800D 对象的 QAccessible::Description 改变。
QAccessible::DialogEnd 0x0011 对话框 ( QDialog ) 已被隐藏
QAccessible::DialogStart 0x0010 对话框 ( QDialog ) 已被设为可见。
QAccessible::DocumentContentChanged 0x0104 文本文档的内容已改变。
QAccessible::DocumentLoadComplete 0x0105 文档已加载。
QAccessible::DocumentLoadStopped 0x0106 文档加载已停止。
QAccessible::DocumentReload 0x0107 文档重载已初启。
QAccessible::DragDropEnd 0x000F 拖放操作即将完成。
QAccessible::DragDropStart 0x000E 拖放操作即将被初启。
QAccessible::Focus 0x8005 对象已获得键盘聚焦。
QAccessible::ForegroundChanged 0x0003 A window has been activated (i.e., a new window has gained focus on the desktop).
QAccessible::HelpChanged 0x80A0 The QAccessible::Help 对象的文本特性已改变。
QAccessible::HyperlinkEndIndexChanged 0x0108 超文本链接的显示文本的结束位置已改变。
QAccessible::HyperlinkNumberOfAnchorsChanged 0x0109 超文本链接中的锚点数已变化,或许因为显示文本已被拆分以提供多个链接。
QAccessible::HyperlinkSelectedLinkChanged 0x010A 选中的超文本链接的链接已改变。
QAccessible::HyperlinkStartIndexChanged 0x010D 超文本链接的显示文本的起始位置已改变。
QAccessible::HypertextChanged 0x010E 用于超文本链接的显示文本已改变。
QAccessible::HypertextLinkActivated 0x010B A hypertext link has been activated, perhaps by being clicked or via a key press.
QAccessible::HypertextLinkSelected 0x010C 超文本链接已被选中。
QAccessible::HypertextNLinksChanged 0x010F
QAccessible::LocationChanged 0x800B 对象在屏幕上的位置已改变。
QAccessible::MenuCommand 0x0018 菜单项被触发。
QAccessible::MenuEnd 0x0005 菜单已关闭 (Qt 对所有菜单使用 PopupMenuEnd)。
QAccessible::MenuStart 0x0004 菜单栏上的菜单已打开 (Qt 对所有菜单使用 PopupMenuStart)。
QAccessible::NameChanged 0x800C The QAccessible::Name 对象的特性已改变。
QAccessible::ObjectAttributeChanged 0x0110
QAccessible::ObjectCreated 0x8000 新对象被创建。
QAccessible::ObjectDestroyed 0x8001 对象被删除。
QAccessible::ObjectHide 0x8003 对象被隐藏;例如,采用 QWidget::hide (). Any children the object that is hidden has do not send this event. It is not sent when an object is hidden as it is being obscured by others.
QAccessible::ObjectReorder 0x8004 布局或项视图已添加、移除或移动对象 (Qt 不使用此事件)。
QAccessible::ObjectShow 0x8002 对象被显示;例如,采用 QWidget::show ().
QAccessible::PageChanged 0x0111
QAccessible::ParentChanged 0x800F 对象的父级对象已改变。
QAccessible::PopupMenuEnd 0x0007 弹出菜单已关闭。
QAccessible::PopupMenuStart 0x0006 弹出菜单已打开。
QAccessible::ScrollingEnd 0x0013 滚动条卷动操作已结束 (鼠标已释放滑块手柄)。
QAccessible::ScrollingStart 0x0012 滚动条卷动操作即将开始;例如,这可能是由鼠标在滑块上按下而引起。
QAccessible::SectionChanged 0x0112
QAccessible::SelectionAdd 0x8007 项已被添加到项视图选定中。
QAccessible::SelectionRemove 0x8008 项已从项视图选定中被移除。
QAccessible::Selection 0x8006 在菜单或项视图中的选定已改变。
QAccessible::SelectionWithin 0x8009 项视图中的选定已有几处改变。
QAccessible::SoundPlayed 0x0001 声音已由对象播放
QAccessible::TableCaptionChanged 0x0113 表格标题已改变。
QAccessible::TableColumnDescriptionChanged 0x0114 在列标题中通常找到的表格列的描述已改变。
QAccessible::TableColumnHeaderChanged 0x0115 表格列标题已改变。
QAccessible::TableRowDescriptionChanged 0x0117 在行标题中通常找到的表格行的描述已改变。
QAccessible::TableRowHeaderChanged 0x0118 表格行标题已改变。
QAccessible::TableSummaryChanged 0x0119 表格摘要已改变。
QAccessible::TextColumnChanged 0x011D 文本列已改变。
QAccessible::VisibleDataChanged 0x0122

此枚举的值被定义为相同值,如那些定义于 IAccessible2 and MSAA 规范。

QAccessible:: Id

unsigned (无符号) 的同义词,使用通过 QAccessibleInterface 缓存。

QAccessible:: InterfaceFactory

这是采用以下签名的函数指针的 typedef:

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

函数接收 QString QObject 指针,其中 QString 是标识接口的关键。 QObject 被用来传递给 QAccessibleInterface 以便可以保持对它的引用。

若键和 QObject 没有相应 QAccessibleInterface , nullptr 将被返回。

已安装工厂的调用是通过 queryAccessibilityInterface(),直到一个提供接口为止。

enum QAccessible:: InterfaceType

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

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

常量 描述
QAccessible::TextInterface 0 对于支持选定或多于一行的文本而言。简单标签不需要实现此接口。
QAccessible::ValueInterface 2 对于用来操纵值的对象而言 (例如:滑块或滚动条)。
QAccessible::ActionInterface 3 对于允许用户触发动作的交互对象而言。基本上所有东西都允许 (例如:鼠标交互)。
QAccessible::TableInterface 5 对于列表、表格和树而言。
QAccessible::TableCellInterface 6 对于 TableInterface 对象单元格而言。
QAccessible::HyperlinkInterface 7 For hyperlink nodes (usually embedded as children of text nodes)
QAccessible::SelectionInterface (since Qt 6.5) 8 For non-text objects that support selection of child objects.

另请参阅 QAccessibleInterface::interface_cast (), QAccessibleTextInterface , QAccessibleValueInterface , QAccessibleActionInterface , QAccessibleTableInterface , QAccessibleTableCellInterface ,和 QAccessibleSelectionInterface .

enum QAccessible:: RelationFlag
flags QAccessible:: Relation

This enum type defines bit flags that can be combined to indicate the relationship between two accessible objects. It is used by the relations() function, which returns a list of all the related interfaces of the calling object, together with the relations for each object.

Each entry in the list is a QPair 在哪里 second member stores the relation type(s) between the returned object represented by the first member and the origin (the caller) interface/object.

In the table below, the returned object refers to the object in the returned list, and the origin object is the one represented by the calling interface.

常量 描述
QAccessible::Label 0x00000001 The returned object is the label for the origin 对象。
QAccessible::Labelled 0x00000002 The returned object is labelled by the origin 对象。
QAccessible::Controller 0x00000004 The returned object controls the origin 对象。
QAccessible::Controlled 0x00000008 The returned object is controlled by the origin 对象。
QAccessible::DescriptionFor (since Qt 6.6) 0x00000010 The returned object provides a description for the origin 对象。
QAccessible::Described (since Qt 6.6) 0x00000020 The returned object is described by the origin 对象。
QAccessible::FlowsFrom (since Qt 6.6) 0x00000040 Content logically flows from the returned 对象到 origin 对象。
QAccessible::FlowsTo (since Qt 6.6) 0x00000080 Content logically flows to the returned 对象从 origin 对象。
QAccessible::AllRelations 0xffffffff 用作掩码以指定对所有关系的有关信息感兴趣

Relations() 的实现返回这些标志的组合。某些值相互排斥。

Relation 类型是 typedef 对于 QFlags <RelationFlag>。它存储 RelationFlag 值的 OR 组合。

enum QAccessible:: 角色

此枚举定义可访问对象的角色。角色包括:

常量 描述
QAccessible::AlertMessage 0x00000008 用于提醒用户的对象。
QAccessible::Animation 0x00000036 显示动画的对象。
QAccessible::Application 0x0000000E 应用程序的主窗口。
QAccessible::Assistant 0x00000020 An object that provides interactive help.
QAccessible::Border 0x00000013 表示边框的对象。
QAccessible::ButtonDropDown 0x00000038 下拉项列表的按钮。
QAccessible::ButtonDropGrid 0x0000003A 下拉栅格的按钮。
QAccessible::ButtonMenu 0x00000039 下拉菜单的按钮。
QAccessible::Canvas 0x00000035 用户可以与之交互,显示图形的对象。
QAccessible::Caret 0x00000007 表示系统插入符号 (文本光标) 的对象。
QAccessible::Cell 0x0000001D 表格中的单元格。
QAccessible::Chart 0x00000011 显示数据图形表示的对象。
QAccessible::CheckBox 0x0000002C 表示可以被复选 (或取消复选) 的选项的对象。某些选项提供混合状态,如:既不复选也不取消复选。
QAccessible::Client 0x0000000A 在窗口中的客户端区域。
QAccessible::Clock 0x0000003D 显示时间的时钟。
QAccessible::ColorChooser 0x404 让用户选择颜色的对话框。
QAccessible::Column 0x0000001B 单元格的列,通常在表格中。
QAccessible::ColumnHeader 0x00000019 用于数据列的 Header 头。
QAccessible::ComboBox 0x0000002E 用户可以从其中选择的抉择列表。
QAccessible::ComplementaryContent 0x42C 与主要内容互补的文档或网页的一部分,通常是地标 (见 WAI-ARIA)。
QAccessible::Cursor 0x00000006 表示鼠标光标的对象。
QAccessible::Desktop 0x00000082 表示桌面或工作空间的对象。
QAccessible::Dial 0x00000031 表示表盘或旋钮的对象。
QAccessible::Dialog 0x00000012 对话框。
QAccessible::Document 0x0000000F 文档 (例如:在办公应用程序中)。
QAccessible::EditableText 0x0000002A 可编辑的文本 (譬如:行编辑或文本编辑)。
QAccessible::Equation 0x00000037 数学方程式表示对象。
QAccessible::Footer 0x40E 在页面中的页脚 (通常在文档中)。
QAccessible::Form 0x410 包含控件的 Web 表单。
QAccessible::Graphic 0x00000028 图形或图片 (如:图标)。
QAccessible::Grip 0x00000004 用户可以拖曳能改变 Widget 大小的握把。
QAccessible::Grouping 0x00000014 表示其它对象逻辑分组的对象。
QAccessible::Heading 0x414 文档中的标题。
QAccessible::HelpBalloon 0x0000001F 在单独短期窗口中显示帮助的对象。
QAccessible::HotkeyField 0x00000032 允许用户键入键序列的热键字段。
QAccessible::Indicator 0x00000027 表示当前值或项的指示器。
QAccessible::LayeredPane 0x00000080 可以包含分层子级的对象 (如:在堆栈中)。
QAccessible::Link 0x0000001E 指向其它内容的链接。
QAccessible::List 0x00000021 用户可从中选择一项或多项的项列表。
QAccessible::ListItem 0x00000022 在项列表中的项。
QAccessible::MenuBar 0x00000002 用户从中打开菜单的菜单栏。
QAccessible::MenuItem 0x0000000C 在菜单或菜单栏中的项。
QAccessible::NoRole 0x00000000 对象没有角色。这通常指示无效对象。
QAccessible::Note 0x41B 其内容在括号内或辅助资源的主要内容的区间。
QAccessible::Notification 0x00000086 通知表示对象 (如:在系统托盘中)。此角色仅在 Linux 起作用。
QAccessible::PageTab 0x00000025 用户可以在对话框中选择切换到不同页面的页面选项卡。
QAccessible::PageTabList 0x0000003C 页面选项卡列表。
QAccessible::Paragraph 0x00000083 文本段落 (通常在文档中找到)。
QAccessible::Pane 0x00000010 通用容器。
QAccessible::PopupMenu 0x0000000B 列表用户可以选择履行动作的选项的菜单。
QAccessible::ProgressBar 0x00000030 正在进行中操作进度的显示对象。
QAccessible::PropertyPage 0x00000026 用户可以在其中改变选项、设置的特性页面。
QAccessible::Button 0x0000002B 按钮。
QAccessible::RadioButton 0x0000002D 与其它选项相互排斥的选项的表示对象。
QAccessible::Row 0x0000001C 单元格行 (通常在表格中)。
QAccessible::RowHeader 0x0000001A 用于数据行的 Header 头。
QAccessible::ScrollBar 0x00000003 允许用户滚动可见区域的滚动条。
QAccessible::Section 0x00000085 章节 (在文档中)。
QAccessible::Separator 0x00000015 将空间划分成逻辑区域的分隔符。
QAccessible::Slider 0x00000033 允许用户选择给定范围值的滑块。
QAccessible::Sound 0x00000005 表示声音的对象。
QAccessible::SpinBox 0x00000034 允许用户录入给定范围值的自旋框 Widget。
QAccessible::Splitter 0x0000003E 在其子级 Widget 之间分配可用空间的分割器。
QAccessible::StaticText 0x00000029 静态文本 (譬如:其它 Widget 的标签)。
QAccessible::StatusBar 0x00000017 状态栏。
QAccessible::Table 0x00000018 以行、列栅格表示数据的表格。
QAccessible::Terminal 0x00000081 终端或命令行接口。
QAccessible::TitleBar 0x00000001 窗口的标题栏标题。
QAccessible::ToolBar 0x00000016 用于分组用户频繁访问 Widget 的工具栏。
QAccessible::ToolTip 0x0000000D 提供其它对象有关信息的工具提示。
QAccessible::Tree 0x00000023 树结构中的项列表。
QAccessible::TreeItem 0x00000024 树结构中的项。
QAccessible::UserRole 0x0000ffff 要使用的第一值 (对于用户定义角色而言)。
QAccessible::WebDocument 0x00000084 HTML 文档,通常在浏览器中。
QAccessible::Whitespace 0x0000003B 在其它对象之间的空白空间。
QAccessible::Window 0x00000009 顶层窗口。

enum QAccessible:: 文本

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

常量 描述
QAccessible::Name 0 对象的名称。这可以用作标识符或短描述通过可访问客户端。
QAccessible::Description 1 描述对象的短文字。
QAccessible::Value 2 对象的值。
QAccessible::Help 3 给出如何使用对象的有关信息的更长文本。
QAccessible::Accelerator 4 执行对象默认动作的键盘快捷键。
QAccessible::UserText 0x0000ffff 用于用户定义文本的第一值。

enum QAccessible:: TextBoundaryType

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

常量 描述
QAccessible::CharBoundary 0 使用单个字符作为边界。
QAccessible::WordBoundary 1 使用单词作为边界。
QAccessible::SentenceBoundary 2 使用句子作为边界。
QAccessible::ParagraphBoundary 3 使用段落作为边界。
QAccessible::LineBoundary 4 使用换行符作为边界。
QAccessible::NoBoundary 5 无边界 (使用整个文本)。

另请参阅 QAccessibleTextInterface .

成员函数文档编制

[static] QAccessibleInterface *QAccessible:: accessibleInterface ( QAccessible::Id id )

返回 QAccessibleInterface 属于 id .

返回 nullptr 若 ID 无效。

[static] void QAccessible:: deleteAccessibleInterface ( QAccessible::Id id )

移除接口属于此 id 来自缓存且删除它。ID 变为无效,通过缓存可重用。

[static] void QAccessible:: installFactory ( QAccessible::InterfaceFactory factory )

安装 InterfaceFactory factory 。最近添加工厂第一个被使用通过 queryAccessibleInterface ().

[static] bool QAccessible:: isActive ()

返回 true 若平台请求可访问性信息。

此函数将返回 false,直到工具 (譬如:屏幕阅读器) 访问可访问性框架。仍可能使用 QAccessible::queryAccessibleInterface () 即使可访问性不活动。但是,不会有通知被发送给平台。

推荐使用此函数来阻止昂贵通知凭借 updateAccessibility () 当不需要它们时。

[static] QAccessibleInterface *QAccessible:: queryAccessibleInterface ( QObject * object )

QAccessibleInterface 实现存在为给定 object ,此函数返回指向实现的指针;否则返回 nullptr .

函数调用所有已安装工厂函数 (从最近安装到至少最近安装),直到找到某一提供接口,对于类 object 。若没有工厂可以为类提供可访问性实现,函数将加载已安装的可访问性插件,并测试是否有任何插件可以提供实现。

若对象的类的实现不可用,函数将试着使用以上战略寻找对象的父类的实现。

所有接口由内部缓存管理,且不应被删除。

[static] QAccessible::Id QAccessible:: registerAccessibleInterface ( QAccessibleInterface * iface )

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

必须只准确调用一次,对于每接口 iface 。这是隐式调用当调用 queryAccessibleInterface ,才要求调用此函数,当采用 new 运算符实例化 QAccessibleInterfaces 时。这不推荐,尽可能使用默认函数和让 queryAccessibleInterface () 关心这。

当有必要重实现 QAccessibleInterface::child () 函数且在构造后返回子级,需要调用此函数。

[static] void QAccessible:: removeFactory ( QAccessible::InterfaceFactory factory )

移除 factory 从已安装的 InterfaceFactories 列表。

[static] void QAccessible:: setRootObject ( QObject * object )

将此应用程序可访问对象的根对象设为 object 。可以到达所有其它可访问对象,使用来自根对象的对象导航。

通常,没有必要调用此函数,因为 Qt 设置 QApplication 对象立即作为根对象,之后才进入事件循环在 QApplication::exec ().

使用 QAccessible::installRootObjectHandler() 能将函数调用重定向到定制处理程序函数。

另请参阅 queryAccessibleInterface ().

[static] QAccessible::Id QAccessible:: uniqueId ( QAccessibleInterface * iface )

返回唯一 ID 为 QAccessibleInterface iface .

[static] void QAccessible:: updateAccessibility ( QAccessibleEvent * event )

通知可能与可访问性客户端相关的即将改变。

event 提供改变的有关细节。这些包括改变的来源和改变的性质。 event 应包含足够信息以给出有意义通知。

例如,类型 ValueChange 指示滑块位置已改变。

调用此函数,每当可访问对象或其某一子元素的状态以编程方式改变时 (如:通过调用 QLabel::setText ()) 或通过用户交互。

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