Accessibility

QAccessibleWidget Example

Instead of creating a custom widget and implementing an interface for it, we will show how accessibility is implemented for one of Qt's standard widgets: QSlider. The accessible interface, QAccessibleSlider, inherits from QAccessibleAbstractSlider, which in turn inherits QAccessibleWidget. You do not need to examine the QAccessibleAbstractSlider class to read this section. If you want to take a look, the code for all of Qt's accessible interfaces are found in src/plugins/accessible/widgets. Here is the QAccessibleSlider's constructor:

 QAccessibleSlider::QAccessibleSlider(QWidget *w)
 : QAccessibleAbstractSlider(w)
 {
     Q_ASSERT(slider());
     addControllingSignal(QLatin1String("valueChanged(int)"));
 }

The slider is a complex control that functions as a Controller for its accessible children. This relationship must be known by the interface (for relationTo() and navigate()). This can be done using a controlling signal, which is a mechanism provided by QAccessibleWidget. We do this in the constructor:

The choice of signal shown is not important; the same principles apply to all signals that are declared in this way. Note that we use QLatin1String to ensure that the signal name is correctly specified.

When an accessible object is changed in a way that users need to know about, it notifies clients of the change by sending them an event via the accessible interface. This is how QSlider calls updateAccessibility() to indicate that its value has changed:

 void QAbstractSlider::setValue(int value)
     ...
     QAccessible::updateAccessibility(this, 0, QAccessible::ValueChanged);
     ...
 }

Note that the call is made after the value of the slider has changed because clients may query the new value immediately after receiving the event.

The interface must be able to calculate bounding rectangles of itself and any children that do not provide an interface of their own. The QAccessibleSlider has three such children identified by the private enum, SliderElements, which has the following values: PageLeft (the rectangle on the left hand side of the slider handle), PageRight (the rectangle on the right hand side of the handle), and Position (the slider handle). Here is the implementation of rect():

 QRect QAccessibleSlider::rect(int child) const
 {
     ...
     switch (child) {
     case PageLeft:
         if (slider()->orientation() == Qt::Vertical)
             rect = QRect(0, 0, slider()->width(), srect.y());
         else
             rect = QRect(0, 0, srect.x(), slider()->height());
         break;
     case Position:
         rect = srect;
         break;
     case PageRight:
         if (slider()->orientation() == Qt::Vertical)
             rect = QRect(0, srect.y() + srect.height(), slider()->width(), slider()->height()- srect.y() - srect.height());
         else
             rect = QRect(srect.x() + srect.width(), 0, slider()->width() - srect.x() - srect.width(), slider()->height());
         break;
     default:
         return QAccessibleAbstractSlider::rect(child);
     }
     ...

The first part of the function, which we have omitted, uses the current style to calculate the slider handle's bounding rectangle; it is stored in srect. Notice that child 0, covered in the default case in the above code, is the slider itself, so we can simply return the QSlider bounding rectangle obtained from the superclass, which is effectively the value obtained from QAccessibleWidget::rect().

     QPoint tp = slider()->mapToGlobal(QPoint(0,0));
     return QRect(tp.x() + rect.x(), tp.y() + rect.y(), rect.width(), rect.height());
 }

Before the rectangle is returned it must be mapped to screen coordinates.

The QAccessibleSlider must reimplement QAccessibleInterface::childCount() since it manages children without interfaces.

The text() function returns the QAccessible::Text strings for the slider:

 QString QAccessibleSlider::text(Text t, int child) const
 {
     if (!slider()->isVisible())
         return QString();
     switch (t) {
     case Value:
         if (!child || child == 2)
             return QString::number(slider()->value());
         return QString();
     case Name:
         switch (child) {
         case PageLeft:
             return slider()->orientation() == Qt::Horizontal ?
                 QSlider::tr("Page left") : QSlider::tr("Page up");
         case Position:
             return QSlider::tr("Position");
         case PageRight:
             return slider()->orientation() == Qt::Horizontal ?
                 QSlider::tr("Page right") : QSlider::tr("Page down");
         }
         break;
     default:
         break;
     }
     return QAccessibleAbstractSlider::text(t, child);
 }

The slider() function returns a pointer to the interface's QSlider. Some values are left for the superclass's implementation. Not all values are appropriate for all accessible objects, as you can see for QAccessible::Value case. You should just return an empty string for those values where no relevant text can be provided.

The implementation of the role() function is straightforward:

 QAccessible::Role QAccessibleSlider::role(int child) const
 {
     switch (child) {
     case PageLeft:
     case PageRight:
         return PushButton;
     case Position:
         return Indicator;
     default:
         return Slider;
     }
 }

The role function should be reimplemented by all objects and describes the role of themselves and the children that do not provide accessible interfaces of their own.

Next, the accessible interface needs to return the states that the slider can be in. We look at parts of the state() implementation to show how just a few of the states are handled:

 QAccessible::State QAccessibleSlider::state(int child) const
 {
     const State parentState = QAccessibleAbstractSlider::state(0);
     ...
     switch (child) {
     case PageLeft:
         if (slider->value() <= slider->minimum())
             state |= Unavailable;
         break;
     case PageRight:
         if (slider->value() >= slider->maximum())
             state |= Unavailable;
         break;
     case Position:
     default:
         break;
     }

     return state;
 }

The superclass implementation of state(), uses the QAccessibleInterface::state() implementation. We simply need to disable the buttons if the slider is at its minimum or maximum.

We have now exposed the information we have about the slider to the clients. For the clients to be able to alter the slider - for example, to change its value - we must provide information about the actions that can be performed and perform them upon request. We discuss this in the next section.

 QStringList SliderPlugin::keys() const
 {
     return QStringList() << QLatin1String("QSlider");
 }

 QAccessibleInterface *SliderPlugin::create(const QString &classname, QObject *object)
 {
     QAccessibleInterface *interface = 0;

     if (classname == QLatin1String("QSlider") && object && object->isWidgetType())
         interface = new QAccessibleSlider(static_cast<QWidget *>(object));

     return interface;
 }

 Q_EXPORT_STATIC_PLUGIN(SliderPlugin)
 Q_EXPORT_PLUGIN2(acc_sliderplugin, SliderPlugin)

 QAccessibleInterface *sliderFactory(const QString &classname, QObject *object)
 {
     QAccessibleInterface *interface = 0;

     if (classname == QLatin1String("QSlider") && object && object->isWidgetType())
         interface = new QAccessibleSlider(static_cast<QWidget *>(object));

     return interface;
 }

 int main(int argv, char **args)
 {
     QApplication app(argv, args);
     QAccessible::installFactory(sliderFactory);
     ...
 }