QAccessible 類

QAccessible 類提供與可訪問性相關的枚舉和靜態函數。 更多...

頭: #include <QAccessible>
qmake: QT += gui

公共類型

struct State
enum Event { AcceleratorChanged, ActionChanged, ActiveDescendantChanged, Alert, AttributeChanged, …, VisibleDataChanged }
typedef Id
typedef InterfaceFactory
enum InterfaceType { TextInterface, ValueInterface, ActionInterface, TableInterface, TableCellInterface }
flags Relation
enum RelationFlag { Label, Labelled, Controller, Controlled, AllRelations }
enum Role { AlertMessage, Animation, Application, Assistant, Border, …, Window }
enum Text { 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 客戶機) (如屏幕閱讀器和盲文顯示) 之間的通信。客戶端和服務器采有以下辦法通信:

  • AT Servers notify the clients about events through calls to the updateAccessibility() function.
  • AT Clients 請求有關服務器對象的信息。 QAccessibleInterface 類是核心接口,並把此信息封裝在純虛擬 API 中。接口的實現由 Qt 提供透過 queryAccessibleInterface () API.

服務器和客戶端之間通信的初始化是通過 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 ()。任何被隱藏的子級對象不會發送此事件。它不會被發送,當對象被其它對象遮擋時。
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 規範。

typedef QAccessible:: Id

unsigned (無符號) 的同義詞,使用通過 QAccessibleInterface 緩存。

typedef 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 對象單元格而言。

另請參閱 QAccessibleInterface::interface_cast (), QAccessibleTextInterface , QAccessibleValueInterface , QAccessibleActionInterface , QAccessibleTableInterface ,和 QAccessibleTableCellInterface .

enum QAccessible:: RelationFlag
flags QAccessible:: Relation

此枚舉類型定義可以組閤以指示 2 可訪問對象間關係的位標誌。

常量 描述
QAccessible::Label 0x00000001 第 1 個對象是第 2 個對象的標簽。
QAccessible::Labelled 0x00000002 第 1 個對象被第 2 個對象所標簽化。
QAccessible::Controller 0x00000004 第 1 個對象控製第 2 個對象。
QAccessible::Controlled 0x00000008 第 1 個對象被第 2 個對象所控製。
QAccessible::AllRelations 0xffffffff 用作掩碼以指定對所有關係的有關信息感興趣

Relations() 的實現返迴這些標誌的組閤。某些值相互排斥。

Relation 類型是 typedef 對於 QFlags <RelationFlag>。它存儲 RelationFlag 值的 OR 組閤。

enum QAccessible:: Role

此枚舉定義可訪問對象的角色。角色包括:

常量 描述
QAccessible::AlertMessage 0x00000008 用於提醒用戶的對象。
QAccessible::Animation 0x00000036 顯示動畫的對象。
QAccessible::Application 0x0000000E 應用程序的主窗口。
QAccessible::Assistant 0x00000020 提供交互幫助的對象。
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 。最近添加工廠第 1 個被使用通過 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 () 以避免不必要的計算。