En esta página

Foco del teclado en los widgets

Los widgets de Qt gestionan el foco del teclado de formas que se han convertido en habituales en las interfaces gráficas de usuario.

La cuestión fundamental es que las pulsaciones del usuario pueden dirigirse a cualquiera de las distintas ventanas de la pantalla y a cualquiera de los distintos widgets dentro de la ventana en cuestión. Cuando el usuario pulsa una tecla, espera que se dirija al lugar correcto, y el software debe intentar satisfacer esta expectativa. El sistema debe determinar a qué aplicación va dirigida la pulsación de tecla, a qué ventana dentro de esa aplicación y a qué widget dentro de esa ventana.

Movimiento del foco

Las prácticas que se han ido desarrollando para dirigir el foco del teclado hacia un control concreto son las siguientes:

  1. El usuario pulsa « Tab » (o « Shift+Tab »).
  2. El usuario hace clic en un control.
  3. El usuario pulsa un atajo de teclado.
  4. El usuario utiliza la rueda del ratón.
  5. El usuario desplaza el foco a una ventana, y la aplicación debe determinar qué control de la ventana debe recibir el foco.

Cada uno de estos mecanismos de interacción es diferente, y los distintos tipos de widgets reciben el foco solo en algunos de ellos. Los veremos uno por uno.

Tecla Tab o Mayús+Tab

Pulsar Tab es, con diferencia, la forma más habitual de desplazar el foco mediante el teclado. (A veces, en aplicaciones de introducción de datos, la tecla Intro realiza la misma función que Tab; esto se puede conseguir fácilmente en Qt implementando un filtro de eventos.)

Pulsar Tab, en todos los sistemas de ventanas de uso habitual hoy en día, desplaza el foco del teclado al siguiente widget de una lista circular por ventana. Tab desplaza el foco a lo largo de la lista circular en una dirección, Shift+Tab en la otra. El orden en el que las pulsaciones de Tab se desplazan de un widget a otro se denomina orden de tabulación.

Puedes personalizar el orden de tabulación mediante QWidget::setTabOrder(). (Si no lo haces, Tab suele desplazar el foco siguiendo el orden de construcción de los widgets.) Qt Widgets Designer permite cambiar visualmente el orden de tabulación.

Dado que pulsar Tab es tan habitual, la mayoría de los widgets que pueden recibir el foco deberían admitir el foco de tabulación. La principal excepción son los widgets que se utilizan en raras ocasiones y en los que existe algún atajo de teclado o controlador de errores que desplaza el foco.

Por ejemplo, en un cuadro de diálogo de introducción de datos, podría haber un campo que solo sea necesario en el uno por ciento de los casos. En un cuadro de diálogo de este tipo, al pulsar Tab se podría omitir este campo, y el cuadro de diálogo podría utilizar uno de estos mecanismos:

  1. Si el programa puede determinar si el campo es necesario, puede desplazar el foco hacia él cuando el usuario termine la introducción de datos y pulse la tecla « OK », o cuando el usuario pulse Intro tras completar los demás campos. Como alternativa, se puede incluir el campo en el orden de tabulación, pero desactivarlo. Se activará si resulta apropiado en función de lo que el usuario haya establecido en los demás campos.
  2. La etiqueta del campo puede incluir un atajo de teclado que desplace el foco a dicho campo.

Otra excepción a la compatibilidad con « Tab » son los widgets de introducción de texto que deben admitir la inserción de tabulaciones; casi todos los editores de texto entran en esta categoría. Qt trata Ctrl+Tab como Tab y Ctrl+Shift+Tab como Shift+Tab, y dichos widgets pueden reimplementar QWidget::event() y gestionar la tecla Tab antes de llamar a QWidget::event() para obtener el procesamiento normal de todas las demás teclas. Sin embargo, dado que algunos sistemas utilizan Ctrl+Tab para otros fines, y muchos usuarios desconocen Ctrl+Tab de todos modos, esta no es una solución completa.

El usuario hace clic en un widget

Esto es quizás incluso más habitual que pulsar Tab en ordenadores con ratón u otro dispositivo señalador.

Hacer clic para mover el foco es ligeramente más potente que Tab. Aunque desplaza el foco a un widget, en el caso de los widgets de editor también mueve el cursor de texto (el foco interno del widget) al punto donde se hace clic con el ratón.

Dado que es tan habitual y la gente está acostumbrada a ello, es recomendable que la mayoría de los widgets lo admitan. Sin embargo, también hay una razón importante para evitarlo: es posible que no quieras quitar el foco del widget en el que se encontraba.

Por ejemplo, en un procesador de textos, cuando el usuario hace clic en el botón de herramienta «B» (negrita), ¿qué debería ocurrir con el foco del teclado? ¿Debería permanecer donde estaba, casi con toda seguridad en el widget de edición, o debería desplazarse al botón «B»?

Recomendamos admitir el «clic para enfocar» en los widgets que admiten la introducción de texto, y evitarlo en la mayoría de los widgets en los que un clic del ratón tiene un efecto diferente. (En el caso de los botones, también recomendamos añadir un atajo de teclado: QAbstractButton y sus subclases lo facilitan mucho).

En Qt, solo la función QWidget::setFocusPolicy() afecta a la función «clic para enfocar».

El usuario pulsa un atajo de teclado

No es raro que los atajos de teclado desplacen el foco. Esto puede ocurrir de forma implícita al abrir cuadros de diálogo modales, pero también de forma explícita utilizando aceleradores de foco como los que proporcionan QLabel::setBuddy(), QGroupBox y QTabBar.

Tu aplicación puede admitir atajos de teclado para todos los widgets a los que el usuario quiera saltar. Por ejemplo, un cuadro de diálogo con pestañas puede tener atajos de teclado para cada una de sus páginas, de modo que el usuario pueda pulsar, por ejemplo, Alt+P para pasar a la página de impresión. Ten en cuenta que es fácil excederse con esto, ya que solo hay unas pocas teclas, y también es importante proporcionar atajos de teclado para los comandos. Consulta las directrices de diseño de la plataforma a la que te dirijas; por ejemplo, las directrices de Microsoft para el diseño de interfaces de usuario con teclado o las directrices de Apple sobre el foco y la selección.

El usuario gira la rueda del ratón

En Microsoft Windows, el uso de la rueda del ratón siempre lo gestiona el widget que tiene el foco del teclado. En macOS y X11, lo gestiona el widget que recibe otros eventos del ratón.

Qt gestiona esta diferencia entre plataformas permitiendo que los widgets cambien el foco del teclado cuando se utiliza la rueda. Con la política de foco adecuada en cada widget, las aplicaciones pueden funcionar de forma idiomáticamente correcta en Windows, macOS y X11.

El usuario desplaza el foco a esta ventana

En esta situación, la aplicación debe determinar qué widget dentro de la ventana debe recibir el foco.

Esto puede ser sencillo: si el foco ya ha estado en esta ventana anteriormente, el último widget que lo tuvo debería recuperarlo. Qt lo hace automáticamente.

Si el foco nunca ha estado en esta ventana anteriormente y sabes dónde debe comenzar, llama a ` QWidget::setFocus()` en el widget que deba recibir el foco antes de llamar a ` QWidget::show()` en él. Si no lo haces, Qt elegirá un widget adecuado.

© 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.