Доступность для приложений QWidget

Введение

Мы сосредоточимся на интерфейсе Qt для доступности QAccessibleInterface и том, как сделать приложения доступными.

Доступность в приложениях на основе QWidget

При взаимодействии с технологиями辅助, нам необходимо описать пользовательский интерфейс Qt так, чтобы они его понимали. Приложения Qt используют QAccessibleInterface для раскрытия информации об отдельных элементах пользовательского интерфейса. В настоящее время Qt предоставляет поддержку для своих виджетов и частей виджетов, например, ползунков, но интерфейс также может быть реализован для любого QObject, если это необходимо. QAccessible содержит перечисления, описывающие пользовательский интерфейс. Мы рассмотрим перечисления в ходе данного документа.

Структура пользовательского интерфейса представлена в виде дерева подклассов QAccessibleInterface. Это часто отражение иерархии QWidgets, составляющих пользовательский интерфейс приложения.

Серверы уведомляют клиентов об изменениях в объектах с помощью updateAccessibility(), отправляя события, а клиенты регистрируются для получения этих событий. Доступные события определяются перечислением QAccessible::Event. Затем клиенты могут запросить объект, который сгенерировал событие, с помощью QAccessible::queryAccessibleInterface().

Члены и перечисления в QAccessible используются для описания доступных объектов:

• Роль: Описывает роль объекта в пользовательском интерфейсе, например, если это окно, поле редактирования текста или ячейка в таблице.
• Связь: Описывает взаимоотношения между объектами в иерархии объектов.
• Состояние: Объекты могут находиться в различных состояниях. Примеры состояний — объект отключен, имеет ли он фокус или предоставляет всплывающее меню.

Клиенты также имеют возможность получить содержимое объектов, например, текст кнопки; объект предоставляет строки, определенные перечислением QAccessible::Text, которые дают информацию о содержании.

Дерево доступных объектов

Как уже упоминалось, дерево строится из доступных объектов приложения. Переходя по дереву, клиенты могут получить доступ ко всем элементам пользовательского интерфейса. Связи между объектами предоставляют клиентам информацию о пользовательском интерфейсе. Например, маркер ползунка является дочерним элементом ползунка, к которому он принадлежит. QAccessible::Relation описывает различные отношения, которые клиенты могут запросить у объектов.

Обратите внимание, что нет прямого соответствия между деревом Qt QObject и деревом доступных объектов. Например, маркеры полос прокрутки являются доступными объектами, но не являются виджетами или объектами в Qt.

Клиенты AT получают доступ к дереву доступных объектов через корневой объект в дереве, который является QApplication. Они могут перемещаться по дереву с помощью функций QAccessibleInterface::parent(), QAccessibleInterface::childCount() и QAccessibleInterface::child().

Qt предоставляет интерфейсы доступности для своих виджетов и для Qt Quick Controls. Интерфейсы для любого подкласса QObject могут быть запрошены через QAccessible::queryInterface(). Если не определен более специализированный интерфейс, предоставляется реализация по умолчанию. Клиент AT не может получить интерфейс для доступных объектов, у которых нет эквивалентного QObject, например, маркеры полос прокрутки, но они отображаются как обычные объекты через интерфейсы родительских доступных объектов, например, вы можете запросить их отношения с помощью QAccessibleInterface::relations().

Для наглядности мы представим изображение дерева доступных объектов. Под деревом приведена таблица с примерами взаимоотношений объектов.

Метки в порядке сверху вниз: имя класса QAccessibleInterface, виджет, для которого предоставляется интерфейс, и роль объекта. Позиции Position, PageLeft и PageRight соответствуют маркеру ползунка, левой и правой части желоба ползунка соответственно. У этих доступных объектов нет эквивалентного QObject.

Статические функции QAccessible

Доступность управляется статическими функциями QAccessible, которые мы рассмотрим чуть позже. Они генерируют интерфейсы QAccessible, строят дерево объектов и устанавливают соединение с MSAA или другими платформами. Если вас интересует только то, как сделать ваше приложение доступным, вы можете пропустить этот раздел и перейти к Реализации доступности.

Взаимодействие между клиентами и сервером начинается при вызове setRootObject(). Это происходит при создании экземпляра QApplication, и вам не нужно делать этого самостоятельно.

Когда QObject вызывает updateAccessibility(), клиенты, слушающие события, уведомляются об изменении. Функция используется для публикации событий в технологиях辅助, и доступные события публикуются функцией updateAccessibility().

queryAccessibleInterface() возвращает интерфейсы доступности для QObjects. Все виджеты в Qt предоставляют интерфейсы; если вам нужны интерфейсы для управления поведением других подклассов QObject, вы должны реализовать их сами, хотя класс-удобство QAccessibleObject реализует части функциональности за вас.

Фабрика, генерирующая интерфейсы доступности для QObjects, является функцией типа QAccessible::InterfaceFactory. Можно установить несколько фабрик. Последняя установленная фабрика будет первой, к которой будут обращаться за интерфейсами. queryAccessibleInterface() использует фабрики для создания интерфейсов для QObject. Обычно вам не нужно беспокоиться о фабриках, потому что вы можете реализовать плагины, которые генерируют интерфейсы. Мы приведем примеры обоих подходов позже.

Реализация доступности

Для обеспечения поддержки доступности для виджета или другого элемента пользовательского интерфейса необходимо реализовать QAccessibleInterface и распространить его в QAccessiblePlugin. Также возможно скомпилировать интерфейс в приложение и предоставить QAccessible::InterfaceFactory для него. Фабрика может использоваться, если вы связываете библиотеки статически или не хотите сложности с плагинами. Это может быть преимуществом, например, при разработке сторонней библиотеки.

Все виджеты и другие элементы пользовательского интерфейса должны иметь интерфейсы и плагины. Если вы хотите, чтобы ваше приложение поддерживало доступность, вам нужно учесть следующее:

• Qt уже реализует доступность для своих виджетов. Поэтому мы рекомендуем использовать виджеты Qt, где это возможно.
• Для каждого элемента, который вы хотите предоставить клиентам для обеспечения доступности, требуется реализовать QAccessibleInterface.
• Вам нужно отправлять события доступности от реализуемых вами пользовательских элементов интерфейса.

В общем случае рекомендуется предварительно ознакомиться с MSAA, для которого изначально разрабатывалась поддержка доступности Qt. Также следует изучить значения перечислений QAccessible, которые описывают роли, действия, взаимоотношения и события, которые нужно учитывать.

Обратите внимание, что вы можете изучить, как виджеты Qt реализуют свою доступность. Одна из основных проблем со стандартом MSAA заключается в том, что интерфейсы часто реализуются несогласованно. Это затрудняет работу для клиентов и часто приводит к догадкам о функциональности объектов.

Можно реализовать интерфейсы, унаследовав QAccessibleInterface и реализовав его чистые виртуальные функции. Однако на практике обычно предпочтительнее наследоваться от QAccessibleObject или QAccessibleWidget, которые реализуют часть функциональности за вас. В следующем разделе мы рассмотрим пример реализации доступности для виджета путем наследования класса QAccessibleWidget.

Классы-удобства QAccessibleObject и QAccessibleWidget

При реализации интерфейса доступности для виджетов обычно наследуют QAccessibleWidget, который представляет собой класс-удобство для виджетов. Другой доступный класс-удобство, от которого наследуется QAccessibleWidget, — это QAccessibleObject, который реализует часть интерфейса для QObjects.

Класс QAccessibleWidget предоставляет следующий функционал:

• Он обрабатывает навигацию по дереву и проверку попадания в объекты.
• Он обрабатывает события, роли и действия, общие для всех QWidget.
• Он обрабатывает действия и методы, которые могут выполняться на всех виджетах.
• Он вычисляет прямоугольники границ с помощью rect().
• Он предоставляет строки text(), подходящие для универсального виджета.
• Он устанавливает состояния, которые общие для всех виджетов.

Пример QAccessibleWidget

Вместо создания пользовательского виджета и реализации интерфейса для него, мы покажем, как реализовать доступность для одного из стандартных виджетов Qt: QSlider. Доступный интерфейс, QAccessibleSlider, наследуется от QAccessibleAbstractSlider, который в свою очередь наследуется от QAccessibleWidget. Вам не нужно изучать класс QAccessibleAbstractSlider для прочтения этого раздела. Если вы хотите взглянуть, код всех доступных интерфейсов Qt находится в qtbase/src/widgets/accessible. Вот конструктор QAccessibleSlider:

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

Ползунок — это сложное управление, которое действует как Контроллер для его доступных дочерних элементов. Эта связь должна быть известна интерфейсу (для parent(), child() и relations()). Это можно сделать с помощью управляющего сигнала, который является механизмом, предоставляемым QAccessibleWidget. Мы делаем это в конструкторе:

Выбор показанного сигнала не важен; те же принципы применяются ко всем сигналам, объявленным таким образом. Обратите внимание, что мы используем QLatin1String, чтобы убедиться, что имя сигнала указано правильно.

Когда доступный объект изменяется таким образом, что пользователи должны об этом знать, он уведомляет клиентов об изменении, отправляя им событие через доступный интерфейс. Вот как QSlider вызывает updateAccessibility(), чтобы указать, что его значение изменилось:

void QAbstractSlider::setValue(int value)
    ...
    QAccessibleValueChangeEvent event(this, d->value);
    QAccessible::updateAccessibility(&event);
    ...
}

Обратите внимание, что вызов выполняется после изменения значения ползунка, так как клиенты могут запросить новое значение сразу после получения события.

Интерфейс должен уметь рассчитывать ограничивающие прямоугольники самого себя и любых дочерних элементов, которые не предоставляют собственного интерфейса. У QAccessibleSlider есть три таких дочерних элемента, идентифицированных закрытым перечислением, SliderElements, которое имеет следующие значения: PageLeft (прямоугольник слева от ручки ползунка), PageRight (прямоугольник справа от ручки), и Position (ручка ползунка). Вот реализация 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);
    }
    ...

Первая часть функции, которую мы опустили, использует текущий стиль, чтобы вычислить ограничивающий прямоугольник ручки ползунка; он хранится в srect. Обратите внимание, что дочерний элемент 0, покрытый в случае по умолчанию в приведенном выше коде, — это сам ползунок, поэтому мы можем просто вернуть прямоугольник QSlider, полученный от суперкласса, который фактически является значением, полученным из QAccessibleWidget::rect().

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

Перед возвращением прямоугольника он должен быть преобразован в координаты экрана.

QAccessibleSlider должен повторно реализовать QAccessibleInterface::childCount(), так как он управляет дочерними элементами без интерфейсов.

Функция text() возвращает строки QAccessible::Text для ползунка:

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);
}

Функция slider() возвращает указатель на QSlider интерфейса. Некоторые значения оставляются для реализации суперкласса. Не все значения подходят для всех доступных объектов, как вы можете видеть для случая QAccessible::Value. Для тех значений, где нельзя предоставить релевантный текст, вы должны просто вернуть пустую строку.

Реализация функции role() проста:

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

Функция role должна быть переопределена всеми объектами и описывает роль самих себя и дочерних элементов, которые не предоставляют собственных доступных интерфейсов.

Далее, доступный интерфейс должен возвращать состояния, в которых может находиться ползунок. Мы рассмотрим части реализации state() , чтобы показать, как обрабатываются всего несколько состояний:

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;
}

Реализация суперкласса state() использует реализацию QAccessibleInterface::state(). Нам просто нужно отключить кнопки, если ползунок находится в минимальном или максимальном положении.

Теперь мы предоставили клиентам информацию о ползунке. Чтобы клиенты могли изменить ползунок — например, изменить его значение — мы должны предоставить информацию о действиях, которые могут быть выполнены, и выполнить их по запросу. Мы обсудим это в следующем разделе.

Обработка запросов на выполнение действий от клиентов

Приложения могут предоставлять действия, которые могут быть вызваны клиентом. Для поддержки действий в объекте наследуйте от QAccessibleActionInterface.

Интерактивные элементы должны предоставлять функциональность, запускаемую взаимодействием с мышкой, например. Кнопка, например, должна реализовать действие щелчка.

Установка фокуса — это еще одно действие, которое должно быть реализовано для виджетов, которые могут получать фокус.

Вы должны переопределить actionNames(), чтобы вернуть список всех действий, поддерживаемых объектом. Этот список не должен быть локализован.

Существуют две функции, которые предоставляют информацию о действиях, которые должны возвращать локализованные строки: localizedActionName() и localizedActionDescription(). Эти функции могут использоваться клиентом для отображения действий пользователю. Как правило, имя должно быть кратким и состоять только из одного слова, например, «нажать».

Доступен список стандартных имен действий и локализаций, которые следует использовать, когда действие подходит. Это упрощает клиентам понимание семантики, и Qt будет пытаться правильно их представить на разных платформах.

Конечно, действие также должно иметь способ запуска. doAction() должно вызывать действие, как указано в названии и описании.

Чтобы увидеть примеры реализации действий и методов, вы можете изучить реализации для стандартных виджетов Qt, таких как QAccessiblePushButton.

Реализация доступных плагинов

В этом разделе мы объясним процедуру реализации доступных плагинов для ваших интерфейсов. Плагин — это класс, хранящийся в библиотеке общего использования, который может загружаться во время выполнения. Распространение интерфейсов в виде плагинов удобно, поскольку они будут загружаться только по мере необходимости.

Создание доступного плагина достигается путем наследования от QAccessiblePlugin, определения поддерживаемых имен классов в описании плагина в формате JSON и переопределения create() из QAccessiblePlugin. Файл .pro необходимо изменить, чтобы использовать шаблон плагина, а библиотека, содержащая плагин, должна быть размещена на пути, где Qt ищет доступные плагины.

Мы пройдём по реализации SliderPlugin, что является доступным плагином, который генерирует интерфейс QAccessibleSlider из примера QAccessibleWidget. Мы начинаем с функции key():

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

Нам просто нужно вернуть имя класса единственного интерфейса, для которого наш плагин может создать доступный интерфейс. Плагин может поддерживать любое количество классов; просто добавьте больше имён классов в список строк. Мы переходим к функции create():

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;
}

Мы проверяем, является ли запрашиваемый интерфейс для QSlider; если это так, мы создаём и возвращаем интерфейс для него. Обратите внимание, что object всегда будет экземпляром classname. Вы должны вернуть 0, если вы не поддерживаете класс. updateAccessibility() проверяет доступные плагины доступности, пока не найдёт тот, который не вернёт 0.

Наконец, вам нужно включить макросы в файл cpp:

    Q_OBJECT
    Q_PLUGIN_METADATA(IID "org.qt-project.Qt.Examples.Accessibility.SliderPlugin" FILE "slider.json")

Макрос Q_PLUGIN_METADATA экспортирует плагин в классе SliderPlugin в библиотеку acc_sliderplugin. Первый аргумент — это IID плагина, а второй — необязательный файл json, содержащий метаданные плагина. Более подробную информацию о плагинах можно найти в обзоре документов по плагинам.

Не имеет значения, нужен ли вам плагин для статической или динамической компоновки с приложением.

Реализация фабрик интерфейсов

Если вы не хотите предоставлять плагины для своих интерфейсов доступности, вы можете использовать фабрику интерфейсов (QAccessible::InterfaceFactory), что является рекомендуемым способом предоставления доступных интерфейсов в статически скомпонованном приложении.

Фабрика — это указатель на функцию, которая принимает те же параметры, что и QAccessiblePlugin’s create() — QString и QObject. Она также работает так же. Вы устанавливаете фабрику с помощью функции installFactory(). Мы приводим пример создания фабрики для интерфейса QAccessibleSlider:

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 argc, char *argv[])
{
    QApplication app(argc, argv);
    QAccessible::installFactory(sliderFactory);
    ...
}