<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qt4-accessibility.qdoc -->
<title>Qt 4.8: Cross-Platform Accessibility Support in Qt 4</title>
<link rel="stylesheet" type="text/css" href="style/style.css" />
<script src="scripts/jquery.js" type="text/javascript"></script>
<script src="scripts/functions.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="style/superfish.css" />
<link rel="stylesheet" type="text/css" href="style/narrow.css" />
<!--[if IE]>
<meta name="MSSmartTagsPreventParsing" content="true">
<meta http-equiv="imagetoolbar" content="no">
<![endif]-->
<!--[if lt IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie6.css">
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie7.css">
<![endif]-->
<!--[if IE 8]>
<link rel="stylesheet" type="text/css" href="style/style_ie8.css">
<![endif]-->
<script src="scripts/superfish.js" type="text/javascript"></script>
<script src="scripts/narrow.js" type="text/javascript"></script>
</head>
<body class="" onload="CheckEmptyAndLoadList();">
<div class="header" id="qtdocheader">
<div class="content">
<div id="nav-logo">
<a href="index.html">Home</a></div>
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
<div id="narrowsearch"></div>
<div id="nav-topright">
<ul>
<li class="nav-topright-home"><a href="http://qt.digia.com/">Qt HOME</a></li>
<li class="nav-topright-dev"><a href="http://qt-project.org/">DEV</a></li>
<li class="nav-topright-doc nav-topright-doc-active"><a href="http://qt-project.org/doc/">
DOC</a></li>
<li class="nav-topright-blog"><a href="http://blog.qt.digia.com/">BLOG</a></li>
</ul>
</div>
<div id="shortCut">
<ul>
<li class="shortCut-topleft-inactive"><span><a href="index.html">Qt 4.8</a></span></li>
<li class="shortCut-topleft-active"><a href="http://qt-project.org/doc/">ALL VERSIONS </a></li>
</ul>
</div>
<ul class="sf-menu" id="narrowmenu">
<li><a href="#">API Lookup</a>
<ul>
<li><a href="classes.html">Class index</a></li>
<li><a href="functions.html">Function index</a></li>
<li><a href="modules.html">Modules</a></li>
<li><a href="namespaces.html">Namespaces</a></li>
<li><a href="qtglobal.html">Global Declarations</a></li>
<li><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</li>
<li><a href="#">Qt Topics</a>
<ul>
<li><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li><a href="supported-platforms.html">Supported Platforms</a></li>
<li><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</li>
<li><a href="#">Examples</a>
<ul>
<li><a href="all-examples.html">Examples</a></li>
<li><a href="tutorials.html">Tutorials</a></li>
<li><a href="demos.html">Demos</a></li>
<li><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="wrapper">
<div class="hd">
<span></span>
</div>
<div class="bd group">
<div class="sidebar">
<div class="searchlabel">
Search index:</div>
<div class="search" id="sidebarsearch">
<form id="qtdocsearch" action="" onsubmit="return false;">
<fieldset>
<input type="text" name="searchstring" id="pageType" value="" />
<div id="resultdialog">
<a href="#" id="resultclose">Close</a>
<p id="resultlinks" class="all"><a href="#" id="showallresults">All</a> | <a href="#" id="showapiresults">API</a> | <a href="#" id="showarticleresults">Articles</a> | <a href="#" id="showexampleresults">Examples</a></p>
<p id="searchcount" class="all"><span id="resultcount"></span><span id="apicount"></span><span id="articlecount"></span><span id="examplecount"></span> results:</p>
<ul id="resultlist" class="all">
</ul>
</div>
</fieldset>
</form>
</div>
<div class="box first bottombar" id="lookup">
<h2 title="API Lookup"><span></span>
API Lookup</h2>
<div id="list001" class="list">
<ul id="ul001" >
<li class="defaultLink"><a href="classes.html">Class index</a></li>
<li class="defaultLink"><a href="functions.html">Function index</a></li>
<li class="defaultLink"><a href="modules.html">Modules</a></li>
<li class="defaultLink"><a href="namespaces.html">Namespaces</a></li>
<li class="defaultLink"><a href="qtglobal.html">Global Declarations</a></li>
<li class="defaultLink"><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</div>
</div>
<div class="box bottombar" id="topics">
<h2 title="Qt Topics"><span></span>
Qt Topics</h2>
<div id="list002" class="list">
<ul id="ul002" >
<li class="defaultLink"><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li class="defaultLink"><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li class="defaultLink"><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li class="defaultLink"><a href="supported-platforms.html">Supported Platforms</a></li>
<li class="defaultLink"><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li class="defaultLink"><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</div>
</div>
<div class="box" id="examples">
<h2 title="Examples"><span></span>
Examples</h2>
<div id="list003" class="list">
<ul id="ul003">
<li class="defaultLink"><a href="all-examples.html">Examples</a></li>
<li class="defaultLink"><a href="tutorials.html">Tutorials</a></li>
<li class="defaultLink"><a href="demos.html">Demos</a></li>
<li class="defaultLink"><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</div>
</div>
</div>
<div class="wrap">
<div class="toolbar">
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li>Cross-Platform Accessibility Support in Qt 4</li>
</ul>
</div>
<div class="toolbuttons toolblock">
<ul>
<li id="smallA" class="t_button">A</li>
<li id="medA" class="t_button active">A</li>
<li id="bigA" class="t_button">A</li>
<li id="print" class="t_button"><a href="javascript:this.print();">
<span>Print</span></a></li>
</ul>
</div>
</div>
<div class="content mainContent">
<link rel="prev" href="qt4-designer.html" />
<link rel="next" href="qt4-sql.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="qt4-designer.html">The New Qt Designer</a>
<a class="nextPage" href="qt4-sql.html">The Qt 4 Database GUI Layer</a>
</p><p/>
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#general-overview">General Overview</a></li>
<li class="level1"><a href="#enabling-accessibility-support">Enabling Accessibility Support</a></li>
<li class="level1"><a href="#creating-new-accessible-interfaces">Creating New Accessible Interfaces</a></li>
<li class="level1"><a href="#example-code">Example Code</a></li>
</ul>
</div>
<h1 class="title">Cross-Platform Accessibility Support in Qt 4</h1>
<span class="subtitle"></span>
<!-- $$$qt4-accessibility.html-description -->
<div class="descr"> <a name="details"></a>
<p>Qt 4 allows developers to write cross-platform applications that are usable by visually impaired users as well as by users with other disabilities. Qt accessibility will make applications accessible to more users and opens the governmental market, where accessibility is often a requirement.</p>
<a name="general-overview"></a>
<h2>General Overview</h2>
<p>The accessibility classes have been extended in various ways since Qt 3. We added new functions and new enum values, and revised the API to make it more consistent with the rest of Qt. We also added two properties to <a href="qwidget.html">QWidget</a>, <a href="qwidget.html#accessibleName-prop">accessibleName</a> and <a href="qwidget.html#accessibleDescription-prop">accessibleDescription</a>, that can be set in <i>Qt Designer</i> to provide basic help texts without having to write any code.</p>
<p>Qt's accessibility architecture is as follows. Qt offers one generic interface, <a href="qaccessibleinterface.html">QAccessibleInterface</a>, that can be used to wrap all widgets and objects (e.g., <a href="qpushbutton.html">QPushButton</a>). This single interface provides all the metadata necessary for the assistive technologies. Qt provides implementations of this interface for its built-in widgets as plugins.</p>
<p>A more detailed overview of the accessibility support in Qt can be found on the <a href="accessible.html">Accessibility</a> page.</p>
<a name="enabling-accessibility-support"></a>
<h2>Enabling Accessibility Support</h2>
<p>By default, Qt applications are run with accessibility support enabled on Windows and Mac OS X. On Unix/X11 platforms, applications must be launched in an environment with the <tt>QT_ACCESSIBILITY</tt> variable set to 1. For example, this is set in the following way with the bash shell:</p>
<pre class="cpp"> <span class="keyword">export</span> QT_ACCESSIBILITY<span class="operator">=</span><span class="number">1</span></pre>
<p>Accessibility features are built into Qt by default when the libraries are configured and built.</p>
<a name="creating-new-accessible-interfaces"></a>
<h2>Creating New Accessible Interfaces</h2>
<p>When you develop custom widgets, you can create custom subclasses of <a href="qaccessibleinterface.html">QAccessibleInterface</a> and distribute them as plugins (using <a href="qaccessibleplugin.html">QAccessiblePlugin</a>) or compile them into the application. Likewise, Qt's predefined accessibility support can be built as plugin (the default) or directly into the Qt library. The main advantage of using plugins is that the accessibility classes are only loaded into memory if they are actually used; they don't slow down the common case where no assistive technology is being used.</p>
<p>In addition to <a href="qaccessibleinterface.html">QAccessibleInterface</a>, Qt includes two convenience classes, <a href="qaccessibleobject.html">QAccessibleObject</a> and <a href="qaccessiblewidget.html">QAccessibleWidget</a>, that provide the lowest common denominator of metadata (e.g., widget geometry, window title, basic help text). You can use them as base classes when wrapping your custom <a href="qobject.html">QObject</a> or <a href="qwidget.html">QWidget</a> subclasses.</p>
<p>Another new feature in Qt 4 is that Qt can now support other backends in addition to the predefined ones. This is done by subclassing <a href="qaccessiblebridge.html">QAccessibleBridge</a>.</p>
<a name="example-code"></a>
<h2>Example Code</h2>
<p>The first example illustrates how to provide accessibility information for a custom widget. We can use <a href="qaccessiblewidget.html">QAccessibleWidget</a> as a base class and reimplement various functions:</p>
<pre class="cpp"> <span class="keyword">class</span> MyWidgetInterface : <span class="keyword">public</span> <span class="type"><a href="qaccessiblewidget.html">QAccessibleWidget</a></span>
{
<span class="keyword">public</span>:
MyWidgetInterface(<span class="type"><a href="qwidget.html">QWidget</a></span> <span class="operator">*</span>widget<span class="operator">,</span> Role role);
<span class="type"><a href="qstring.html">QString</a></span> text(Text text<span class="operator">,</span> <span class="type">int</span> child) <span class="keyword">const</span>;
State state(<span class="type">int</span> child) <span class="keyword">const</span>;
<span class="type"><a href="qstring.html">QString</a></span> actionText(<span class="type">int</span> action<span class="operator">,</span> Text text<span class="operator">,</span> <span class="type">int</span> child) <span class="keyword">const</span>;
<span class="type">bool</span> doAction(<span class="type">int</span> action<span class="operator">,</span> <span class="type">int</span> child<span class="operator">,</span> <span class="keyword">const</span> <span class="type"><a href="qvariant.html#QVariantList-typedef">QVariantList</a></span> <span class="operator">&</span>params);
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
};</pre>
<p>Here's how we would implement the <a href="qaccessibleinterface.html#doAction">doAction()</a> function to call a function named click() on the wrapped MyWidget object when the user invokes the object's default action or "presses" it.</p>
<pre class="cpp"> <span class="type">bool</span> MyWidgetInterface<span class="operator">::</span>doAction(<span class="type">int</span> action<span class="operator">,</span> <span class="type">int</span> child<span class="operator">,</span>
<span class="keyword">const</span> <span class="type"><a href="qvariant.html#QVariantList-typedef">QVariantList</a></span> <span class="operator">&</span>params)
{
<span class="keyword">if</span> (child <span class="operator">|</span><span class="operator">|</span> <span class="operator">!</span>widget()<span class="operator">-</span><span class="operator">></span>isEnabled())
<span class="keyword">return</span> <span class="keyword">false</span>;
<span class="keyword">switch</span> (action) {
<span class="keyword">case</span> DefaultAction:
<span class="keyword">case</span> Press:
{
MyWidget <span class="operator">*</span>widget <span class="operator">=</span> qobject_cast<span class="operator"><</span>MyWidget <span class="operator">*</span><span class="operator">></span>(object());
<span class="keyword">if</span> (widget)
widget<span class="operator">-</span><span class="operator">></span>click();
}
<span class="keyword">return</span> <span class="keyword">true</span>;
}
<span class="keyword">return</span> <span class="type"><a href="qaccessiblewidget.html">QAccessibleWidget</a></span><span class="operator">::</span>doAction(action<span class="operator">,</span> child<span class="operator">,</span> params);
}</pre>
<p>To export the widget interface as a plugin, we must subclass QAccessibleFactory:</p>
<pre class="cpp"> <span class="type"><a href="qstringlist.html">QStringList</a></span> MyFactory<span class="operator">::</span>keys() <span class="keyword">const</span>
{
<span class="keyword">return</span> <span class="type"><a href="qstringlist.html">QStringList</a></span>() <span class="operator"><</span><span class="operator"><</span> <span class="string">"MyWidget"</span> <span class="operator"><</span><span class="operator"><</span> <span class="string">"MyOtherWidget"</span>;
}
<span class="type"><a href="qaccessibleinterface.html">QAccessibleInterface</a></span> <span class="operator">*</span>MyFactory<span class="operator">::</span>create(<span class="keyword">const</span> <span class="type"><a href="qstring.html">QString</a></span> <span class="operator">&</span>className<span class="operator">,</span>
<span class="type"><a href="qobject.html">QObject</a></span> <span class="operator">*</span>object)
{
<span class="keyword">if</span> (classname <span class="operator">=</span><span class="operator">=</span> <span class="string">"MyWidget"</span>)
<span class="keyword">return</span> <span class="keyword">new</span> MyWidgetInterface(object);
<span class="keyword">if</span> (classname <span class="operator">=</span><span class="operator">=</span> <span class="string">"MyOtherWidget"</span>)
<span class="keyword">return</span> <span class="keyword">new</span> MyOtherWidgetInterface(object);
<span class="keyword">return</span> <span class="number">0</span>;
}
<a href="qtplugin.html#Q_EXPORT_PLUGIN2">Q_EXPORT_PLUGIN2</a>(myfactory<span class="operator">,</span> MyFactory)</pre>
</div>
<!-- @@@qt4-accessibility.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="qt4-designer.html">The New Qt Designer</a>
<a class="nextPage" href="qt4-sql.html">The Qt 4 Database GUI Layer</a>
</p>
</div>
</div>
</div>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2013 Digia Plc and/or its
subsidiaries. Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
The documentation provided herein is licensed under the terms of the
<a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation
License version 1.3</a> as published by the Free Software Foundation.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Digia, Qt and their respective logos are trademarks of Digia Plc
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
<script src="scripts/functions.js" type="text/javascript"></script>
</body>
</html>
