QAccessibleInterface Class
La clase `QAccessibleInterface` define una interfaz que proporciona información sobre los objetos accesibles. Más información...
| Encabezado: | #include <QAccessibleInterface> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
| Heredado por: |
- Lista de todos los miembros, incluidos los heredados
- QAccessibleInterface forma parte de las clases de accesibilidad.
Funciones públicas
| QAccessibleActionInterface * | actionInterface() |
| virtual QColor | backgroundColor() const |
| virtual QAccessibleInterface * | child(int index) const = 0 |
| virtual QAccessibleInterface * | childAt(int x, int y) const = 0 |
| virtual int | childCount() const = 0 |
| virtual QAccessibleInterface * | focusChild() const |
| virtual QColor | foregroundColor() const |
| virtual int | indexOfChild(const QAccessibleInterface *child) const = 0 |
| virtual void * | interface_cast(QAccessible::InterfaceType type) |
| virtual bool | isValid() const = 0 |
| virtual QObject * | object() const = 0 |
| virtual QAccessibleInterface * | parent() const = 0 |
| virtual QRect | rect() const = 0 |
| virtual QList<std::pair<QAccessibleInterface *, QAccessible::Relation>> | relations(QAccessible::Relation match = QAccessible::AllRelations) const |
| virtual QAccessible::Role | role() const = 0 |
(since 6.5) QAccessibleSelectionInterface * | selectionInterface() |
| virtual void | setText(QAccessible::Text t, const QString &text) = 0 |
| virtual QAccessible::State | state() const = 0 |
| QAccessibleTableCellInterface * | tableCellInterface() |
| QAccessibleTableInterface * | tableInterface() |
| virtual QString | text(QAccessible::Text t) const = 0 |
| QAccessibleTextInterface * | textInterface() |
| QAccessibleValueInterface * | valueInterface() |
(since 6.12) QAccessibleViewportInterface * | viewportInterface() |
| virtual QWindow * | window() const |
Funciones protegidas
| QAccessibleInterface() | |
| virtual | ~QAccessibleInterface() |
Descripción detallada
Esta clase forma parte de «Accesibilidad para aplicaciones QWidget».
Las herramientas de accesibilidad (también denominadas «clientes AT»), como los lectores de pantalla o las pantallas braille, requieren información de alto nivel sobre los objetos accesibles de una aplicación. Los objetos accesibles proporcionan métodos especializados de entrada y salida, lo que permite a los usuarios utilizar herramientas de accesibilidad con aplicaciones habilitadas (servidores AT).
Todo elemento con el que el usuario necesite interactuar o al que deba reaccionar es un objeto accesible y debe proporcionar esta información. Se trata principalmente de objetos visuales, como widgets y elementos de widget, pero también puede tratarse de contenido, como sonidos.
El cliente de TA utiliza tres conceptos básicos para obtener información sobre cualquier objeto accesible de una aplicación:
- Propiedades: el cliente puede leer información sobre los objetos accesibles. En algunos casos, el cliente también puede modificar estas propiedades; por ejemplo, el texto de un campo de edición de línea.
- Acciones: El cliente puede invocar acciones como pulsar un botón o .
- Relaciones y navegación: El cliente puede desplazarse de un objeto accesible a otro utilizando las relaciones entre los objetos.
La interfaz `QAccessibleInterface` define la API para estos tres conceptos.
Relaciones y navegación
Las funciones ` childCount()` y ` indexOfChild()` devuelven el número de hijos de un objeto accesible y el índice que tiene un objeto hijo en su padre. La función ` childAt()` devuelve una interfaz `QAccessibleInterface` de un hijo que se encuentra en una posición determinada. No es necesario que el objeto hijo sea un objeto hijo directo. Esto permite saltarse capas intermedias cuando el objeto padre ya conoce al objeto hijo de nivel más alto. La función ` childAt()` se utiliza para la prueba de colisión (localizar el objeto situado bajo el cursor del ratón).
La función relations() proporciona información sobre las relaciones que un objeto tiene con otros objetos, y parent() y child() permiten recorrer de un objeto a otro.
Propiedades
La propiedad fundamental de un objeto accesible es el « role()» que tiene. Diferentes objetos pueden tener el mismo rol; por ejemplo, tanto el elemento «Añadir línea» de una barra de desplazamiento como el botón « OK » de un cuadro de diálogo tienen el mismo rol: «botón». El rol implica qué tipo de interacción puede realizar el usuario con el elemento de la interfaz de usuario.
La propiedad state() de un objeto es una combinación de diferentes indicadores de estado y puede describir tanto en qué se diferencia el estado del objeto de un estado «normal» —por ejemplo, podría no estar disponible— como cómo se comporta —por ejemplo, podría ser seleccionable—.
La propiedad ` text()` proporciona información textual sobre el objeto. Un objeto suele tener un nombre, pero puede proporcionar información adicional, como una descripción, un texto de ayuda o información sobre los atajos de teclado que ofrece. Algunos objetos permiten modificar la propiedad ` text()` mediante la función ` setText()`, pero esta información es, en la mayoría de los casos, de solo lectura.
La propiedad ` rect()` proporciona información sobre la geometría de un objeto accesible. Esta información suele estar disponible únicamente para objetos visuales.
Interfaces
Para que el usuario pueda interactuar con un objeto accesible, este debe implementar QAccessibleActionInterface además de QAccessibleInterface. Los objetos que admiten selecciones pueden definir acciones para modificar la selección.
Existen otras interfaces que deben implementarse según sea necesario. La interfaz ` QAccessibleTextInterface ` debe utilizarse para ediciones de texto de mayor extensión, como las vistas de documentos. Esta interfaz no debe implementarse para etiquetas ni campos de edición de una sola línea.
Para controles deslizantes, barras de desplazamiento y otros selectores de valores numéricos, se debe implementar ` QAccessibleValueInterface `.
Las listas, tablas y árboles deben implementar ` QAccessibleTableInterface`.
Las vistas desplazables deben implementar ` QAccessibleViewportInterface`.
Véase también QAccessible, QAccessibleActionInterface, QAccessibleTextInterface, QAccessibleValueInterface, QAccessibleTableInterface y QAccessibleViewportInterface.
Documentación de funciones de miembro
[constexpr noexcept protected default] QAccessibleInterface::QAccessibleInterface()
Crea por defecto una instancia de ` QAccessibleInterface`.
[virtual noexcept protected] QAccessibleInterface::~QAccessibleInterface()
Destruye el « QAccessibleInterface ».
QAccessibleActionInterface *QAccessibleInterface::actionInterface()
[virtual] QColor QAccessibleInterface::backgroundColor() const
Devuelve el color de fondo del elemento accesible, si procede, o un objeto ` QColor` no válido.
Véase también foregroundColor().
[pure virtual] QAccessibleInterface *QAccessibleInterface::child(int index) const
Devuelve el elemento secundario accesible con el índice index. El índice comienza en 0. El número de elementos secundarios de un objeto se puede comprobar con childCount.
Devuelve ` nullptr ` cuando se solicita un elemento secundario no válido (por ejemplo, cuando el elemento secundario ha dejado de ser válido entretanto).
Véanse también childCount() y parent().
[pure virtual] QAccessibleInterface *QAccessibleInterface::childAt(int x, int y) const
Devuelve el objeto ` QAccessibleInterface ` de un elemento hijo que contenga las coordenadas de pantalla (x, y). Si no hay ningún elemento hijo en esa posición, esta función devuelve ` nullptr`. El objeto ` ` devuelto debe ser un elemento hijo, pero no necesariamente un elemento hijo directo.
Esta función solo es fiable para objetos visibles (es posible que los objetos invisibles no se dispongan correctamente).
Todos los objetos visuales proporcionan esta información.
Se proporciona una implementación por defecto para los objetos que heredan de ` QAccessibleObject`. Esta recorrerá todos los hijos. Si el widget gestiona sus hijos (por ejemplo, una tabla), será más eficiente escribir una implementación especializada.
Véase también ` rect()`.
[pure virtual] int QAccessibleInterface::childCount() const
Devuelve el número de elementos secundarios que pertenecen a este objeto. Un elemento secundario puede proporcionar información de accesibilidad por sí mismo (por ejemplo, un widget secundario) o ser un subelemento de este objeto accesible.
Todos los objetos proporcionan esta información.
Véase también indexOfChild().
[virtual] QAccessibleInterface *QAccessibleInterface::focusChild() const
Devuelve el objeto que tiene el foco del teclado.
El objeto devuelto puede ser cualquier descendiente, incluido él mismo.
[virtual] QColor QAccessibleInterface::foregroundColor() const
Devuelve el color de primer plano del elemento accesible, si procede, o un objeto ` QColor` no válido.
Véase también backgroundColor().
[pure virtual] int QAccessibleInterface::indexOfChild(const QAccessibleInterface *child) const
Devuelve el índice (empezando por 0) del objeto child en la lista de hijos de este objeto, o -1 si child no es un hijo de este objeto.
Todos los objetos proporcionan esta información sobre sus hijos.
Véase también childCount().
[virtual] void *QAccessibleInterface::interface_cast(QAccessible::InterfaceType type)
Devuelve una interfaz de accesibilidad especializada ` type ` a partir de la interfaz genérica ` QAccessibleInterface`.
Esta función debe reimplementarse cuando se proporcione más información sobre un widget u objeto a través de las interfaces especializadas. Por ejemplo, un campo de edición de línea debería implementar la interfaz ` QAccessibleTextInterface`.
Véanse también « QAccessible::InterfaceType », « QAccessibleTextInterface », « QAccessibleValueInterface », « QAccessibleActionInterface », « QAccessibleTableInterface », « QAccessibleTableCellInterface » y « QAccessibleViewportInterface ».
[pure virtual] bool QAccessibleInterface::isValid() const
Devuelve ` true ` si todos los datos necesarios para utilizar esta implementación de la interfaz son válidos (por ejemplo, si todos los punteros son distintos de nulo); en caso contrario, devuelve ` false`.
Véase también object().
[pure virtual] QObject *QAccessibleInterface::object() const
Devuelve un puntero a la interfaz ` QObject `, para la que esta implementación proporciona información.
Véase también ` isValid()`.
[pure virtual] QAccessibleInterface *QAccessibleInterface::parent() const
Devuelve el ` QAccessibleInterface ` del objeto padre en la jerarquía de objetos accesibles.
Devuelve ` nullptr ` si no existe ningún objeto padre (por ejemplo, en el caso del objeto de aplicación de nivel superior).
Véase también child().
[pure virtual] QRect QAccessibleInterface::rect() const
Devuelve la geometría del objeto. La geometría está expresada en coordenadas de pantalla.
Esta función solo es fiable para los objetos visibles (es posible que los objetos invisibles no se muestren correctamente).
Todos los objetos visuales proporcionan esta información.
Véase también childAt().
[virtual] QList<std::pair<QAccessibleInterface *, QAccessible::Relation>> QAccessibleInterface::relations(QAccessible::Relation match = QAccessible::AllRelations) const
Devuelve las relaciones significativas con otros widgets. Por lo general, esto no devolverá relaciones padre/hijo, a menos que se gestionen de una forma específica, como en las vistas de árbol. Normalmente devolverá las relaciones «labelled-by» y «label».
Es posible filtrar las relaciones utilizando el parámetro opcional ` match`. Nunca debe devolverse a sí misma.
Véanse también parent() y child().
[pure virtual] QAccessible::Role QAccessibleInterface::role() const
Devuelve el rol del objeto. El rol de un objeto suele ser estático.
Todos los objetos accesibles tienen un rol.
Véase también text() y state().
[since 6.5] QAccessibleSelectionInterface *QAccessibleInterface::selectionInterface()
Esta función se introdujo en Qt 6.5.
[pure virtual] void QAccessibleInterface::setText(QAccessible::Text t, const QString &text)
Establece la propiedad de texto « t » del objeto en « text ».
Ten en cuenta que las propiedades de texto de la mayoría de los objetos son de solo lectura, por lo que llamar a esta función podría no surtir efecto.
Véase también text().
[pure virtual] QAccessible::State QAccessibleInterface::state() const
Devuelve el estado actual del objeto. El valor devuelto es una combinación de los indicadores de la enumeración QAccessible::StateFlag.
Todos los objetos accesibles tienen un estado.
Véase también text() y role().
QAccessibleTableCellInterface *QAccessibleInterface::tableCellInterface()
QAccessibleTableInterface *QAccessibleInterface::tableInterface()
[pure virtual] QString QAccessibleInterface::text(QAccessible::Text t) const
Devuelve el valor de la propiedad de texto « t » del objeto.
La propiedad « QAccessible::Name » es una cadena de caracteres que utilizan los clientes para identificar, localizar o anunciar un objeto accesible al usuario. Todos los objetos deben tener un nombre único dentro de su contenedor. Los clientes pueden utilizar el nombre de diferentes maneras, por lo que este debe ofrecer una breve descripción del objeto y ser único.
La propiedad « QAccessible::Description » de un objeto accesible proporciona información textual sobre el aspecto visual del objeto. La descripción se utiliza principalmente para ofrecer un mayor contexto a los usuarios con discapacidad visual, pero también se emplea para la búsqueda contextual u otras aplicaciones. No todos los objetos tienen una descripción. Un botón «Aceptar» no necesitaría una descripción, pero sí la necesitaría un botón de herramienta que muestre la imagen de un emoticono sonriente.
El « QAccessible::Value » de un objeto accesible representa la información visual que contiene el objeto, por ejemplo, el texto de un campo de edición de línea. Por lo general, el usuario puede modificar este valor. No todos los objetos tienen un valor; por ejemplo, las etiquetas de texto estáticas no lo tienen, y algunos objetos tienen un estado que ya constituye el valor, como los botones de alternancia.
El texto « QAccessible::Help » proporciona información sobre la función y el uso de un objeto accesible. No todos los objetos proporcionan esta información.
El « QAccessible::Accelerator » es un atajo de teclado que activa la acción predeterminada del objeto. Un atajo de teclado es el carácter subrayado en el texto de un menú, un elemento de menú o un widget, y puede ser el propio carácter o una combinación de este con una tecla modificadora como Alt, Ctrl o Mayús. Los controles de comando, como los botones de herramientas, también tienen teclas de atajo y suelen mostrarlas en su información sobre herramientas.
El « QAccessible::Identifier » se puede establecer explícitamente para proporcionar un identificador a las tecnologías de asistencia. Esto puede resultar especialmente útil para las pruebas de la interfaz de usuario. Si no se ha establecido ningún identificador de forma explícita, la interfaz correspondiente lo establece basándose en QObject::objectName o en el nombre de su clase, y en QObject::objectName o en el nombre de clase de los elementos padres en su cadena de padres.
Todos los objetos proporcionan una cadena para QAccessible::Name.
Véanse también setText(), role() y state().
QAccessibleTextInterface *QAccessibleInterface::textInterface()
QAccessibleValueInterface *QAccessibleInterface::valueInterface()
[since 6.12] QAccessibleViewportInterface *QAccessibleInterface::viewportInterface()
Esta función se introdujo en Qt 6.12.
[virtual] QWindow *QAccessibleInterface::window() const
Devuelve la ventana asociada al objeto subyacente. Por ejemplo, ` QAccessibleWidget ` reimplementa esta función y devuelve el `windowHandle()` de ` QWidget`.
Se utiliza en algunas plataformas para poder notificar al cliente AT los cambios de estado. El backend recorrerá hacia arriba todos los antepasados hasta encontrar una ventana. (Esto significa que al menos una interfaz entre los antepasados debe devolver un puntero QWindow válido).
La implementación por defecto devuelve nullptr.
© 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.