En esta página

Accesibilidad para aplicaciones QWidget

Introducción

Nos centraremos en la interfaz de accesibilidad de Qt, QAccessibleInterface, y en cómo hacer que las aplicaciones sean accesibles.

Accesibilidad en aplicaciones basadas en QWidget

Cuando nos comunicamos con las tecnologías de apoyo, necesitamos describir la interfaz de usuario de Qt de una forma que estas puedan entender. Las aplicaciones Qt utilizan QAccessibleInterface para exponer información sobre los elementos individuales de la interfaz de usuario. Actualmente, Qt ofrece soporte para sus widgets y partes de widgets, por ejemplo, los controles deslizantes, pero la interfaz también podría implementarse para cualquier QObject si fuera necesario. QAccessible contiene enumeraciones que describen la interfaz de usuario. Examinaremos estas enumeraciones a lo largo de este documento.

La estructura de la interfaz de usuario se representa como un árbol de subclases de ` QAccessibleInterface `. A menudo, esto refleja la jerarquía de `QWidgets` que conforman la interfaz de usuario de la aplicación.

Los servidores notifican a los clientes, a través de ` updateAccessibility()``, los cambios en los objetos enviando eventos, y los clientes se registran para recibir dichos eventos. Los eventos disponibles se definen mediante la enumeración ` QAccessible::Event `. A continuación, los clientes pueden consultar qué objeto generó el evento mediante ` QAccessible::queryAccessibleInterface()``.

Los miembros y las enumeraciones de QAccessible se utilizan para describir los objetos accesibles:

  • Role: Describe la función que desempeña el objeto en la interfaz de usuario; por ejemplo, si se trata de una ventana, un campo de texto o una celda de una tabla.
  • Relation: Describe la relación entre los objetos en la jerarquía de objetos.
  • State: Los objetos pueden encontrarse en diversos estados. Algunos ejemplos de estados son si el objeto está desactivado, si tiene el foco o si ofrece un menú emergente.

Los clientes también disponen de algunas opciones para obtener el contenido de los objetos, por ejemplo, el texto de un botón; el objeto proporciona cadenas definidas por la enumeración ` QAccessible::Text `, que ofrecen información sobre el contenido.

El árbol de objetos accesibles

Como se ha mencionado, se construye una estructura de árbol a partir de los objetos accesibles de una aplicación. Al navegar por el árbol, los clientes pueden acceder a todos los elementos de la interfaz de usuario. Las relaciones entre objetos proporcionan a los clientes información sobre la interfaz de usuario. Por ejemplo, el control deslizante es un elemento secundario del control deslizante al que pertenece. QAccessible::Relation describe las diversas relaciones que los clientes pueden solicitar a los objetos.

Tenga en cuenta que no existe una correspondencia directa entre el árbol de « QObject » de Qt y el árbol de objetos accesibles. Por ejemplo, los controladores de las barras de desplazamiento son objetos accesibles, pero no son widgets ni objetos en Qt.

Los clientes de tecnología de asistencia (AT) tienen acceso al árbol de objetos de accesibilidad a través del objeto raíz del árbol, que es el ` QApplication`. Pueden navegar por el árbol con las funciones ` QAccessibleInterface::parent()`, ` QAccessibleInterface::childCount()` y ` QAccessibleInterface::child()`.

Qt proporciona interfaces accesibles para sus widgets y para los controles Qt Quick. Las interfaces para cualquier subclase de QObject pueden solicitarse mediante QAccessible::queryInterface(). Se proporciona una implementación por defecto si no se ha definido una interfaz más especializada. Un cliente de tecnología de asistencia (AT-Client) no puede obtener una interfaz para objetos accesibles que no tengan un equivalente QObject, por ejemplo, los controladores de las barras de desplazamiento, pero estos aparecen como objetos normales a través de las interfaces de los objetos accesibles de nivel superior; por ejemplo, se pueden consultar sus relaciones mediante QAccessibleInterface::relations().

A modo de ilustración, presentamos una imagen de un árbol de objetos accesibles. Debajo del árbol hay una tabla con ejemplos de relaciones entre objetos.

Diagrama de árbol que muestra la jerarquía de objetos accesibles, con QApplication como raíz y QSlider con los elementos secundarios PageLeft, Position y PageRight

Las etiquetas, en orden de arriba abajo, son: el nombre de la clase QAccessibleInterface, el widget para el que se proporciona una interfaz y la Role del objeto. «Position», «PageLeft» y «PageRight» corresponden al control deslizante, a la ranura izquierda del control deslizante y a la ranura derecha del control deslizante, respectivamente. Estos objetos accesibles no tienen un equivalente QObject.

Objeto de origenObjeto de destinoRelación
Control deslizanteIndicadorControlador
IndicadorControl deslizanteControlado
Control deslizanteAplicaciónAntecesor
AplicaciónControl deslizanteHijo
BotónIndicadorCompañero

Las funciones estáticas de QAccessible

La accesibilidad se gestiona mediante las funciones estáticas de ` QAccessible`, que analizaremos en breve. Estas funciones generan interfaces ` QAccessible `, construyen el árbol de objetos e inician la conexión con MSAA o con otras tecnologías específicas de la plataforma. Si solo te interesa aprender a hacer que tu aplicación sea accesible, puedes saltarte esta sección y pasar directamente a «Implementación de la accesibilidad».

La comunicación entre los clientes y el servidor se inicia cuando se llama a ` setRootObject()`. Esto se lleva a cabo al instanciar la instancia de ` QApplication `, por lo que no deberías tener que hacerlo tú mismo.

Cuando un ` QObject ` llama a ` updateAccessibility()`, se notifica el cambio a los clientes que están a la espera de eventos. La función se utiliza para enviar eventos a la tecnología de asistencia, y los ` events ` accesibles se envían mediante ` updateAccessibility()`.

queryAccessibleInterface() devuelve interfaces accesibles para los objetos de tipo ` QObject`. Todos los widgets de Qt proporcionan interfaces; si necesitas interfaces para controlar el comportamiento de otras subclases de ` QObject `, debes implementar las interfaces tú mismo, aunque la clase de conveniencia ` QAccessibleObject ` implementa parte de la funcionalidad por ti.

La fábrica que genera interfaces de accesibilidad para los `QObjects` es una función de tipo ` QAccessible::InterfaceFactory`. Es posible tener varias fábricas instaladas. La última fábrica instalada será la primera a la que se le solicitarán interfaces. ` queryAccessibleInterface()` utiliza las fábricas para crear interfaces para los ` QObjects`. Normalmente, no es necesario preocuparse por las fábricas, ya que se pueden implementar complementos que generen interfaces. Más adelante daremos ejemplos de ambos enfoques.

Implementación de la accesibilidad

Para proporcionar soporte de accesibilidad a un widget u otro elemento de la interfaz de usuario, es necesario implementar la interfaz ` QAccessibleInterface ` y distribuirla en un ` QAccessiblePlugin`. También es posible compilar la interfaz en la aplicación y proporcionar un ` QAccessible::InterfaceFactory ` para ella. La fábrica se puede utilizar si se realiza una vinculación estática o si no se desea la complejidad añadida que suponen los complementos. Esto puede suponer una ventaja si, por ejemplo, se distribuye una biblioteca de terceros.

Todos los widgets y demás elementos de la interfaz de usuario deben tener interfaces y complementos. Si desea que su aplicación sea compatible con la accesibilidad, deberá tener en cuenta lo siguiente:

  • Qt ya implementa la accesibilidad para sus propios widgets. Por lo tanto, te recomendamos que utilices los widgets de Qt siempre que sea posible.
  • Es necesario implementar un « QAccessibleInterface » para cada elemento que quieras poner a disposición de los clientes de accesibilidad.
  • Debes enviar eventos de accesibilidad desde los elementos personalizados de la interfaz de usuario que implementes.

En general, se recomienda que estés más o menos familiarizado con MSAA, para lo cual se diseñó originalmente la compatibilidad con la accesibilidad de Qt. También deberías estudiar los valores de enumeración de ` QAccessible`, que describen las funciones, acciones, relaciones y eventos que debes tener en cuenta.

Tenga en cuenta que puede examinar cómo los Qt Widgets implementan su accesibilidad. Uno de los principales problemas del estándar MSAA es que las interfaces suelen implementarse de forma inconsistente. Esto complica las cosas a los clientes y, a menudo, les obliga a hacer conjeturas sobre la funcionalidad de los objetos.

Es posible implementar interfaces heredando de QAccessibleInterface e implementando sus funciones virtuales puras. Sin embargo, en la práctica suele ser preferible heredar de QAccessibleObject o QAccessibleWidget, que ya implementan parte de la funcionalidad por ti. En la siguiente sección, veremos un ejemplo de cómo implementar la accesibilidad para un widget heredando de la clase QAccessibleWidget.

Las clases de conveniencia QAccessibleObject y QAccessibleWidget

A la hora de implementar una interfaz de accesibilidad para widgets, lo habitual es heredar de ` QAccessibleWidget`, que es una clase de conveniencia para widgets. Otra clase de conveniencia disponible, de la que hereda ` QAccessibleWidget`, es ` QAccessibleObject`, que implementa parte de la interfaz para `QObjects`.

QAccessibleWidget proporciona las siguientes funcionalidades:

  • Se encarga de la navegación por el árbol y de la comprobación de colisiones de los objetos.
  • Gestiona los eventos, los roles y las acciones comunes a todos los « QWidget».
  • Gestiona las acciones y los métodos que se pueden realizar en todos los widgets.
  • Calcula los rectángulos delimitadores mediante rect().
  • Proporciona cadenas de « text()» adecuadas para un widget genérico.
  • Establece los states que son comunes a todos los widgets.

Ejemplo de QAccessibleWidget

En lugar de crear un widget personalizado e implementar una interfaz para él, mostraremos cómo se implementa la accesibilidad para uno de los widgets estándar de Qt: QSlider. La interfaz accesible, QAccessibleSlider, hereda de QAccessibleAbstractSlider, que a su vez hereda de QAccessibleWidget. No es necesario examinar la clase `QAccessibleAbstractSlider` para leer esta sección. Si quieres echarle un vistazo, el código de todas las interfaces accesibles de Qt se encuentra en `qtbase/src/widgets/accessible`. Este es el constructor de `QAccessibleSlider`:

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

El control deslizante es un control complejo que actúa como un « Controller » para sus elementos hijos accesibles. La interfaz debe conocer esta relación (para parent(), child() y relations()). Esto se puede lograr mediante una señal de control, que es un mecanismo proporcionado por QAccessibleWidget. Lo hacemos en el constructor:

La elección de la señal mostrada no es importante; los mismos principios se aplican a todas las señales que se declaran de esta manera. Ten en cuenta que utilizamos QLatin1String para garantizar que el nombre de la señal se especifique correctamente.

Cuando un objeto accesible sufre un cambio del que los usuarios deben ser informados, notifica a los clientes dicho cambio enviándoles un evento a través de la interfaz accesible. Así es como QSlider llama a updateAccessibility() para indicar que su valor ha cambiado:

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

Tenga en cuenta que la llamada se realiza después de que el valor del control deslizante haya cambiado, ya que los clientes pueden consultar el nuevo valor inmediatamente después de recibir el evento.

La interfaz debe ser capaz de calcular los rectángulos delimitadores de sí misma y de cualquier elemento secundario que no disponga de una interfaz propia. El ` QAccessibleSlider ` tiene tres elementos hijos de este tipo identificados por la enumeración privada ` SliderElements`, que tiene los siguientes valores: ` PageLeft ` (el rectángulo situado a la izquierda del control deslizante), ` PageRight ` (el rectángulo situado a la derecha del control deslizante) y ` Position ` (el control deslizante). A continuación se muestra la implementación de ` 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);
    }
    ...

La primera parte de la función, que hemos omitido, utiliza el ` style ` actual para calcular el rectángulo delimitador del control deslizante; este se almacena en ` srect`. Obsérvese que el elemento secundario 0, al que se hace referencia en el caso predeterminado del código anterior, es el propio control deslizante, por lo que basta con devolver el rectángulo delimitador de QSlider obtenido de la superclase, que es, en la práctica, el valor obtenido de QAccessibleWidget::rect().

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

Antes de devolver el rectángulo, este debe asignarse a las coordenadas de pantalla.

El QAccessibleSlider debe reimplementar QAccessibleInterface::childCount(), ya que gestiona elementos hijos sin interfaces.

La función text() devuelve las cadenas QAccessible::Text del control deslizante:

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

La función ` slider() ` devuelve un puntero a la ` QSlider` de la interfaz. Algunos valores se dejan a la implementación de la superclase. No todos los valores son apropiados para todos los objetos accesibles, como se puede ver en el caso de ` QAccessible::Value `. Simplemente debes devolver una cadena vacía para aquellos valores en los que no se pueda proporcionar ningún texto relevante.

La implementación de la función role() es sencilla:

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

La función «role» debe ser reimplementada por todos los objetos y describe el rol de sí mismos y de los hijos que no proporcionan interfaces accesibles propias.

A continuación, la interfaz accesible debe devolver los estados ( states ) en los que puede encontrarse el control deslizante. Analizamos partes de la implementación de ` state() ` para mostrar cómo se gestionan algunos de estos estados:

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

La implementación de la superclase de state() utiliza la implementación de QAccessibleInterface::state(). Simplemente tenemos que desactivar los botones si el control deslizante se encuentra en su valor mínimo o máximo.

Ahora hemos puesto a disposición de los clientes la información de la que disponemos sobre el control deslizante. Para que los clientes puedan modificar el control deslizante —por ejemplo, para cambiar su valor—, debemos proporcionar información sobre las acciones que se pueden realizar y ejecutarlas cuando se soliciten. Analizaremos esto en la siguiente sección.

Gestión de solicitudes de acción de los clientes

Las aplicaciones pueden exponer acciones que el cliente puede invocar. Para que un objeto admita acciones, hay que heredar de ` QAccessibleActionInterface`.

Los elementos interactivos deben exponer funcionalidades que se activen, por ejemplo, mediante la interacción con el ratón. Un botón, por ejemplo, debería implementar una acción de clic.

Establecer el foco es otra acción que debe implementarse para los widgets que aceptan recibir el foco.

Es necesario reimplementar ` actionNames()` para devolver una lista de todas las acciones que admite el objeto. Esta lista no debe estar localizada.

Hay dos funciones que proporcionan información sobre las acciones y que deben devolver cadenas localizadas: ` localizedActionName()` y ` localizedActionDescription()`. El cliente puede utilizar estas funciones para presentar las acciones al usuario. En general, el nombre debe ser conciso y constar únicamente de una sola palabra, como «pulsar».

Existe una lista de nombres de acciones estándar y sus correspondientes localizaciones que deben utilizarse cuando la acción sea adecuada. Esto facilita a los clientes la comprensión de la semántica, y Qt intentará mostrarlas correctamente en las diferentes plataformas.

Por supuesto, la acción también necesita una forma de activarse. doAction() debería invocar la acción tal y como se indica en su nombre y descripción.

Para ver ejemplos de cómo implementar acciones y métodos, puedes examinar las implementaciones de los widgets estándar de Qt, como QAccessiblePushButton.

Implementación de complementos accesibles

En esta sección explicaremos el procedimiento para implementar complementos accesibles para tus interfaces. Un complemento es una clase almacenada en una biblioteca compartida que se puede cargar en tiempo de ejecución. Resulta conveniente distribuir las interfaces como complementos, ya que solo se cargarán cuando sea necesario.

Para crear un complemento accesible hay que heredar de ` QAccessiblePlugin`, definir los nombres de las clases compatibles en la descripción JSON del complemento y reimplementar ` create()` a partir de ` QAccessiblePlugin`. El archivo ` .pro ` debe modificarse para utilizar la plantilla del complemento, y la biblioteca que contiene el complemento debe colocarse en una ruta donde Qt busque los complementos accesibles.

Repasaremos la implementación de SliderPlugin, que es un complemento accesible que genera la interfaz `QAccessibleSlider` a partir del ejemplo `QAccessibleWidget`. Comenzamos con la función ` key() `:

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

Simplemente tenemos que devolver el nombre de la clase de la única interfaz para la que nuestro complemento puede crear una interfaz accesible. Un complemento puede admitir cualquier número de clases; basta con añadir más nombres de clases a la lista de cadenas. Pasamos a la función ` 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;
}

Comprobamos si la interfaz solicitada es para ` QSlider`; si lo es, creamos y devolvemos una interfaz para ella. Ten en cuenta que ` object ` siempre será una instancia de ` classname`. Debes devolver 0 si no admites la clase. ` updateAccessibility()` comprueba los complementos de accesibilidad disponibles hasta que encuentra uno que no devuelva 0.

Por último, debes incluir macros en el archivo cpp:

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

La macro Q_PLUGIN_METADATA exporta el complemento de la clase SliderPlugin a la biblioteca acc_sliderplugin. El primer argumento es el IID del complemento y el segundo es un archivo JSON opcional que contiene información de metadatos sobre el complemento. Para obtener más información sobre los complementos, puedes consultar el documento de descripción general de los complementos.

No importa si necesitas que el complemento esté vinculado de forma estática o dinámica con la aplicación.

Implementación de fábricas de interfaces

Si no desea proporcionar complementos para sus interfaces de accesibilidad, puede utilizar una fábrica de interfaces (QAccessible::InterfaceFactory), que es la forma recomendada de proporcionar interfaces accesibles en una aplicación enlazada de forma estática.

QAccessiblePluginUna fábrica es un puntero a una función que toma los mismos parámetros que create's () —un QString y un QObject —. Además, funciona de la misma manera. La fábrica se instala mediante la función installFactory(). A continuación ofrecemos un ejemplo de cómo crear una fábrica para la interfaz 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);
    ...
}

Accessible

Permite la accesibilidad de los elementos QML

QAccessible

Enumeraciones y funciones estáticas relacionadas con la accesibilidad

QAccessibleActionInterface

Implementa el soporte para acciones invocables en la interfaz

QAccessibleAnnouncementEvent

Se utiliza para solicitar que las tecnologías de asistencia anuncien un mensaje determinado

QAccessibleAttributesInterface

Implementa soporte para los atributos de información de un objeto accesible

QAccessibleEditableTextInterface

Implementa soporte para objetos con texto editable

QAccessibleEvent

La clase base para las notificaciones de accesibilidad

QAccessibleInterface

Define una interfaz que expone información sobre los objetos accesibles

QAccessibleObject

Implementa partes de la interfaz QAccessibleInterface para objetos QObject

QAccessiblePlugin

Clase base abstracta para complementos que proporcionan información de accesibilidad sobre elementos de la interfaz de usuario

QAccessibleSelectionInterface

Implementa soporte para la gestión de la selección

QAccessibleStateChangeEvent

Notifica al marco de accesibilidad que el estado de un objeto ha cambiado

QAccessibleTableCellInterface

Implementa el soporte para la interfaz IAccessibleTable2 Cell

QAccessibleTableInterface

Implementa compatibilidad con la interfaz IAccessibleTable2

QAccessibleTableModelChangeEvent

Indica un cambio en una tabla, lista o árbol en el que se añaden o eliminan celdas. Si el cambio ha afectado a varias filas, firstColumn y lastColumn devolverán -1. Del mismo modo, en el caso de las columnas, las funciones de fila pueden devolver -1

QAccessibleTextCursorEvent

Notifica los movimientos del cursor

QAccessibleTextInsertEvent

Notifica la inserción de texto

QAccessibleTextInterface

Implementa la compatibilidad con el manejo de texto

QAccessibleTextRemoveEvent

Notifica la eliminación de texto

QAccessibleTextSelectionEvent

Indica un cambio en la selección de texto de un objeto

QAccessibleTextUpdateEvent

Notifica los cambios en el texto. Esto es para elementos accesibles que admiten texto editable, como los campos de edición de línea. Este evento se produce, por ejemplo, cuando una parte del texto seleccionado se sustituye al pegar un nuevo texto o en el modo de sobrescritura de los editores

QAccessibleValueChangeEvent

Describe un cambio en el valor de un objeto accesible

QAccessibleValueInterface

Implementa soporte para objetos que manipulan un valor

QAccessibleViewportInterface

Implementa soporte para ventanas de visualización

QAccessibleWidget

Implementa la interfaz QAccessibleInterface para QWidgets

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.