QScreen Class
La clase QScreen se utiliza para consultar las propiedades de la pantalla. Más información...
| Encabezado: | #include <QScreen> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
| Heredan: | QObject |
Propiedades
|
|
Funciones públicas
| int | angleBetween(Qt::ScreenOrientation a, Qt::ScreenOrientation b) const |
| QRect | availableGeometry() const |
| QSize | availableSize() const |
| QRect | availableVirtualGeometry() const |
| QSize | availableVirtualSize() const |
| int | depth() const |
| qreal | devicePixelRatio() const |
| QRect | geometry() const |
| QPixmap | grabWindow(WId window = 0, int x = 0, int y = 0, int width = -1, int height = -1) |
| QPlatformScreen * | handle() const |
| bool | isLandscape(Qt::ScreenOrientation o) const |
| bool | isPortrait(Qt::ScreenOrientation o) const |
| qreal | logicalDotsPerInch() const |
| qreal | logicalDotsPerInchX() const |
| qreal | logicalDotsPerInchY() const |
| QString | manufacturer() const |
| QRect | mapBetween(Qt::ScreenOrientation a, Qt::ScreenOrientation b, const QRect &rect) const |
| QString | model() const |
| QString | name() const |
| QNativeInterface * | nativeInterface() const |
| Qt::ScreenOrientation | nativeOrientation() const |
| Qt::ScreenOrientation | orientation() const |
| qreal | physicalDotsPerInch() const |
| qreal | physicalDotsPerInchX() const |
| qreal | physicalDotsPerInchY() const |
| QSizeF | physicalSize() const |
| Qt::ScreenOrientation | primaryOrientation() const |
| qreal | refreshRate() const |
| QString | serialNumber() const |
| QSize | size() const |
| QTransform | transformBetween(Qt::ScreenOrientation a, Qt::ScreenOrientation b, const QRect &target) const |
| QRect | virtualGeometry() const |
| QScreen * | virtualSiblingAt(QPoint point) |
| QList<QScreen *> | virtualSiblings() const |
| QSize | virtualSize() const |
Señales
| void | availableGeometryChanged(const QRect &geometry) |
| void | geometryChanged(const QRect &geometry) |
| void | logicalDotsPerInchChanged(qreal dpi) |
| void | orientationChanged(Qt::ScreenOrientation orientation) |
| void | physicalDotsPerInchChanged(qreal dpi) |
| void | physicalSizeChanged(const QSizeF &size) |
| void | primaryOrientationChanged(Qt::ScreenOrientation orientation) |
| void | refreshRateChanged(qreal refreshRate) |
| void | virtualGeometryChanged(const QRect &rect) |
Descripción detallada
Una nota sobre los puntos por pulgada (DPI) lógicos frente a los físicos: los DPI físicos se basan en los tamaños reales de los píxeles, cuando están disponibles, y resultan útiles para la vista previa de impresión y otros casos en los que es conveniente conocer las dimensiones físicas exactas del contenido que se muestra en pantalla.
Los puntos por pulgada lógicos se utilizan para convertir los tamaños de fuente y los elementos de la interfaz de usuario de puntos a píxeles, y pueden diferir de los puntos por pulgada físicos. En ocasiones, el usuario puede configurar los puntos por pulgada lógicos en el panel de configuración del entorno de escritorio, lo que le permite controlar de forma global los tamaños de la interfaz de usuario y de las fuentes en diferentes aplicaciones.
Nota: Tanto los DPI físicos como los lógicos se expresan en puntos independientes del dispositivo. Multiplica por QScreen::devicePixelRatio() para obtener la densidad dependiente del dispositivo.
Para obtener un objeto QScreen, utiliza QGuiApplication::primaryScreen() para la pantalla principal, o QGuiApplication::screens() para obtener una lista de todas las pantallas.
Véase también QGuiApplication::primaryScreen() y QGuiApplication::screens().
Documentación de propiedades
[read-only] availableGeometry : QRect
Esta propiedad contiene la geometría disponible de la pantalla en píxeles
La geometría disponible es aquella que excluye las áreas reservadas por el gestor de ventanas, como las barras de tareas y los menús del sistema.
Nota: en X11, esto devolverá la geometría realmente disponible solo en sistemas con un único monitor y si el gestor de ventanas ha establecido el átomo _NET_WORKAREA. En todos los demás casos, el resultado es igual a geometry(). Se trata de una limitación de la especificación del gestor de ventanas de X11.
Funciones de acceso:
| QRect | availableGeometry() const |
Señal de notificador:
| void | availableGeometryChanged(const QRect &geometry) |
[read-only] availableSize : QSize
Esta propiedad contiene el tamaño disponible de la pantalla en píxeles
El tamaño disponible es el tamaño sin contar las áreas reservadas por el gestor de ventanas, como las barras de tareas y los menús del sistema.
Funciones de acceso:
| QSize | availableSize() const |
Señal de notificador:
| void | availableGeometryChanged(const QRect &geometry) |
[read-only] availableVirtualGeometry : QRect
Esta propiedad contiene la geometría disponible del escritorio virtual al que pertenece esta pantalla
Devuelve la geometría disponible del escritorio virtual correspondiente a esta pantalla.
Se trata de la unión de las geometrías disponibles individuales de los hermanos virtuales.
Funciones de acceso:
| QRect | availableVirtualGeometry() const |
Señal de notificación:
| void | virtualGeometryChanged(const QRect &rect) |
Véase también availableGeometry() y virtualSiblings().
[read-only] availableVirtualSize : QSize
Esta propiedad indica el tamaño disponible del escritorio virtual al que pertenece esta pantalla
Devuelve el tamaño disponible en píxeles del escritorio virtual correspondiente a esta pantalla.
Se trata del tamaño combinado de las geometrías disponibles individuales de los hermanos virtuales.
Funciones de acceso:
| QSize | availableVirtualSize() const |
Señal de notificación:
| void | virtualGeometryChanged(const QRect &rect) |
Véase también availableSize() y virtualSiblings().
[read-only] depth : const int
Esta propiedad indica la profundidad de color de la pantalla
Funciones de acceso:
| int | depth() const |
[read-only] devicePixelRatio : qreal
Esta propiedad contiene la relación de la pantalla entre píxeles físicos y píxeles independientes del dispositivo
Devuelve la relación entre los píxeles físicos y los píxeles independientes del dispositivo para la pantalla.
Esta función puede devolver un valor diferente al de ` QWindow::devicePixelRatio()`; por ejemplo, en Wayland al utilizar escalado fraccionario, o si se han configurado propiedades de la ventana que afectan a la resolución de la superficie. Se recomienda utilizar ` QWindow::devicePixelRatio()`.
Nota: En algunas plataformas, el `devicePixelRatio` de una ventana y el de la pantalla en la que se encuentra pueden ser diferentes. Utiliza esta función solo cuando no sepas a qué ventana te diriges. Si sí conoces la ventana de destino, utiliza en su lugar ` QWindow::devicePixelRatio()`.
Funciones de acceso:
| qreal | devicePixelRatio() const |
Señal de notificación:
| void | physicalDotsPerInchChanged(qreal dpi) |
Véase también QWindow::devicePixelRatio() y QGuiApplication::devicePixelRatio().
[read-only] geometry : QRect
Esta propiedad contiene la geometría de la pantalla en píxeles
A modo de ejemplo, podría devolver QRect(0, 0, 1280, 1024) o, en un entorno de escritorio virtual, QRect(1280, 0, 1280, 1024).
Funciones de acceso:
| QRect | geometry() const |
Señal de notificación:
| void | geometryChanged(const QRect &geometry) |
[read-only] logicalDotsPerInch : qreal
Esta propiedad indica el número de puntos lógicos o píxeles por pulgada
Este valor se puede utilizar para convertir los tamaños de punto de las fuentes a tamaños en píxeles.
Se trata de una propiedad de conveniencia que no es más que la media de las propiedades « logicalDotsPerInchX » y « logicalDotsPerInchY ».
Funciones de acceso:
| qreal | logicalDotsPerInch() const |
Señal de notificación:
| void | logicalDotsPerInchChanged(qreal dpi) |
Véanse también logicalDotsPerInchX() y logicalDotsPerInchY().
[read-only] logicalDotsPerInchX : qreal
Esta propiedad indica el número de puntos lógicos o píxeles por pulgada en la dirección horizontal
Este valor se utiliza para convertir los tamaños de punto de las fuentes a tamaños en píxeles.
Funciones de acceso:
| qreal | logicalDotsPerInchX() const |
Señal de notificación:
| void | logicalDotsPerInchChanged(qreal dpi) |
Véase también logicalDotsPerInchY().
[read-only] logicalDotsPerInchY : qreal
Esta propiedad indica el número de puntos lógicos o píxeles por pulgada en la dirección vertical
Este valor se utiliza para convertir los tamaños de punto de las fuentes a tamaños en píxeles.
Funciones de acceso:
| qreal | logicalDotsPerInchY() const |
Señal de notificación:
| void | logicalDotsPerInchChanged(qreal dpi) |
Véase también logicalDotsPerInchX().
[read-only] manufacturer : const QString
Esta propiedad indica el fabricante de la pantalla
Funciones de acceso:
| QString | manufacturer() const |
[read-only] model : const QString
Esta propiedad contiene el modelo de la pantalla
Funciones de Access:
| QString | model() const |
[read-only] name : const QString
Esta propiedad contiene una cadena legible para el usuario que representa la pantalla
Por ejemplo, en X11, estas se corresponden con los nombres de pantalla de XRandr, normalmente «VGA1», «HDMI1», etc.
Nota: No se garantiza quela cadena visible para el usuario coincida con el resultado de ninguna API nativa, y no debe utilizarse para identificar de forma unívoca una pantalla.
Funciones de acceso:
| QString | name() const |
[read-only] nativeOrientation : Qt::ScreenOrientation
Esta propiedad contiene la orientación nativa de la pantalla
La orientación nativa de la pantalla es aquella en la que el logotipo del dispositivo aparece en posición correcta, o Qt::PrimaryOrientation si la plataforma no admite esta funcionalidad.
La orientación nativa es una propiedad del hardware y no cambia.
Funciones de acceso:
| Qt::ScreenOrientation | nativeOrientation() const |
[read-only] orientation : Qt::ScreenOrientation
Esta propiedad indica la orientación de la pantalla
La propiedad orientation indica la orientación de la pantalla desde la perspectiva del sistema de ventanas.
La mayoría de los dispositivos móviles y tabletas cuentan con sensores acelerómetros. El módulo « Qt Sensors » permite leer directamente este sensor. Sin embargo, el sistema de ventanas puede girar toda la pantalla automáticamente en función de cómo se sostenga el dispositivo; en ese caso, la propiedad « orientation » cambiará.
Funciones de acceso:
| Qt::ScreenOrientation | orientation() const |
Señal de notificador:
| void | orientationChanged(Qt::ScreenOrientation orientation) |
Véase también primaryOrientation() y QWindow::contentOrientation().
[read-only] physicalDotsPerInch : qreal
Esta propiedad indica el número de puntos físicos o píxeles por pulgada
Este valor representa la densidad de píxeles en la pantalla. Dependiendo de la información que proporcione el sistema subyacente, es posible que el valor no sea del todo exacto.
Se trata de una propiedad de conveniencia que no es más que la media de las propiedades « physicalDotsPerInchX » y « physicalDotsPerInchY ».
Nota: El DPIfísico se expresa en puntos independientes del dispositivo. Multiplícalo por QScreen::devicePixelRatio() para obtener la densidad dependiente del dispositivo.
Funciones de acceso:
| qreal | physicalDotsPerInch() const |
Señal de notificación:
| void | physicalDotsPerInchChanged(qreal dpi) |
Véase también physicalDotsPerInchX() y physicalDotsPerInchY().
[read-only] physicalDotsPerInchX : qreal
Esta propiedad indica el número de puntos físicos o píxeles por pulgada en la dirección horizontal
Este valor representa la densidad horizontal real de píxeles en la pantalla. Dependiendo de la información que proporcione el sistema subyacente, es posible que el valor no sea del todo preciso.
Nota: El DPIfísico se expresa en puntos independientes del dispositivo. Multiplícelo por QScreen::devicePixelRatio() para obtener la densidad dependiente del dispositivo.
Funciones de acceso:
| qreal | physicalDotsPerInchX() const |
Señal de notificación:
| void | physicalDotsPerInchChanged(qreal dpi) |
Véase también physicalDotsPerInchY().
[read-only] physicalDotsPerInchY : qreal
Esta propiedad indica el número de puntos físicos o píxeles por pulgada en la dirección vertical
Este valor representa la densidad vertical real de píxeles en la pantalla. Dependiendo de la información que proporcione el sistema subyacente, es posible que el valor no sea del todo preciso.
Nota: El DPIfísico se expresa en puntos independientes del dispositivo. Multiplícelo por QScreen::devicePixelRatio() para obtener la densidad dependiente del dispositivo.
Funciones de acceso:
| qreal | physicalDotsPerInchY() const |
Señal de notificación:
| void | physicalDotsPerInchChanged(qreal dpi) |
Véase también physicalDotsPerInchX().
[read-only] physicalSize : QSizeF
Esta propiedad contiene el tamaño físico de la pantalla (en milímetros)
El tamaño físico representa las dimensiones físicas reales de la pantalla.
Dependiendo de la información que proporcione el sistema subyacente, es posible que el valor no sea del todo exacto.
Funciones de acceso:
| QSizeF | physicalSize() const |
Señal de notificador:
| void | physicalSizeChanged(const QSizeF &size) |
[read-only] primaryOrientation : Qt::ScreenOrientation
Esta propiedad indica la orientación principal de la pantalla
La orientación principal de la pantalla es Qt::LandscapeOrientation si la anchura de la geometría de la pantalla es mayor o igual que su altura, o Qt::PortraitOrientation en caso contrario. Esta propiedad puede cambiar cuando se modifica la orientación de la pantalla (es decir, cuando se gira la pantalla). No obstante, el comportamiento depende de la plataforma y, a menudo, se puede especificar en el archivo de manifiesto de la aplicación.
Funciones de acceso:
| Qt::ScreenOrientation | primaryOrientation() const |
Señal de notificación:
| void | primaryOrientationChanged(Qt::ScreenOrientation orientation) |
[read-only] refreshRate : qreal
Esta propiedad contiene la frecuencia de actualización vertical aproximada de la pantalla en Hz
Advertencia: Evita utilizar la frecuencia de actualización de la pantalla para controlar animaciones mediante un temporizador como QChronoTimer. En su lugar, utiliza QWindow::requestUpdate().
Funciones de acceso:
| qreal | refreshRate() const |
Señal de notificación:
| void | refreshRateChanged(qreal refreshRate) |
Véase también QWindow::requestUpdate().
[read-only] serialNumber : const QString
Esta propiedad contiene el número de serie de la pantalla
Funciones de Access:
| QString | serialNumber() const |
[read-only] size : QSize
Esta propiedad contiene la resolución en píxeles de la pantalla
Funciones de acceso:
| QSize | size() const |
Señal de notificación:
| void | geometryChanged(const QRect &geometry) |
[read-only] virtualGeometry : QRect
Esta propiedad contiene la geometría en píxeles del escritorio virtual al que pertenece esta pantalla
Devuelve la geometría en píxeles del escritorio virtual correspondiente a esta pantalla.
Se trata de la unión de las geometrías individuales de los hermanos virtuales.
Funciones de acceso:
| QRect | virtualGeometry() const |
Señal de notificación:
| void | virtualGeometryChanged(const QRect &rect) |
Véase también ` virtualSiblings()`.
[read-only] virtualSize : QSize
Esta propiedad contiene el tamaño en píxeles del escritorio virtual al que pertenece esta pantalla
Devuelve el tamaño en píxeles del escritorio virtual correspondiente a esta pantalla.
Se trata del tamaño combinado de las geometrías individuales de los hermanos virtuales.
Funciones de acceso:
| QSize | virtualSize() const |
Señal de notificación:
| void | virtualGeometryChanged(const QRect &rect) |
Véase también virtualSiblings().
Documentación de funciones de miembro
int QScreen::angleBetween(Qt::ScreenOrientation a, Qt::ScreenOrientation b) const
Función práctica para calcular el ángulo de rotación necesario para pasar de la rotación a a la rotación b.
El resultado será 0, 90, 180 o 270.
Qt::PrimaryOrientation Se interpreta como la función « primaryOrientation()» de la pantalla.
QPixmap QScreen::grabWindow(WId window = 0, int x = 0, int y = 0, int width = -1, int height = -1)
Crea y devuelve un mapa de píxeles generado a partir del contenido de la ventana especificada ( window ), limitado por el área especificada ( QRect) (x, y, width, height). Si window es 0, se capturará toda la pantalla.
Los argumentos (x, y) especifican el desplazamiento dentro de la ventana, mientras que (width, height) especifican el área que se va a copiar. Si width es negativo, la función copia todo hasta el borde derecho de la ventana. Si height es negativo, la función copia todo hasta la parte inferior de la ventana.
Los argumentos offset y size se especifican en píxeles independientes del dispositivo. El mapa de píxeles devuelto puede ser mayor que el tamaño solicitado al capturar desde una pantalla de alta resolución (DPI). Llama a QPixmap::devicePixelRatio() para determinar si este es el caso.
El identificador del sistema de ventanas (WId) puede recuperarse mediante la función QWidget::winId(). La razón para utilizar un identificador de ventana y no un QWidget es permitir la captura de ventanas que no forman parte de la aplicación, marcos del sistema de ventanas, etc.
Cuando window es 0, el comportamiento depende de la plataforma.
- En plataformas en las que las coordenadas son locales a la pantalla (Windows, X11), (x, y) son relativas al origen de dicha pantalla.
- En plataformas donde las coordenadas son globales (macOS), (x, y) son relativas al escritorio virtual. Esto requiere que los usuarios resten
screen->geometry().topLeft()para obtener el mismo resultado que en Windows.
Para capturar toda la pantalla de forma compatible con todas las plataformas, utiliza grabWindow(0) sin especificar coordenadas. El código que capture un área parcial debe tener en cuenta esta diferencia de forma explícita.
Advertencia: La captura de ventanas que no forman parte de la aplicación no está permitida en sistemas como iOS, donde el entorno de aislamiento (sandboxing) y las medidas de seguridad impiden leer píxeles de ventanas que no pertenecen a la aplicación.
La función `grabWindow()` captura píxeles de la pantalla, no de la ventana; es decir, si hay otra ventana que se superpone parcial o totalmente a la que estás capturando, también obtendrás píxeles de la ventana superpuesta. Por lo general, no se captura el cursor del ratón.
Nota sobre X11: si la ventana « window » especificada no tiene la misma profundidad que la ventana raíz, y otra ventana oculta parcial o totalmente la que se captura, no se obtendrán píxeles de la ventana superpuesta. El contenido de las áreas ocultas en el mapa de píxeles será indefinido y no estará inicializado.
En Windows Vista y versiones posteriores, la captura de una ventana en capas —creada al establecer el atributo « Qt::WA_TranslucentBackground »— no funcionará. En su lugar, debería funcionar la captura del widget del escritorio.
Advertencia: En general, capturar un área fuera de la pantalla no es seguro. Esto depende del sistema de ventanas subyacente.
QPlatformScreen *QScreen::handle() const
Obtener el identificador de la pantalla de la plataforma.
Véase también Abstracción de la plataforma Qt (QPA).
bool QScreen::isLandscape(Qt::ScreenOrientation o) const
Función de conveniencia que devuelve ` true ` si ` o ` es «paisaje» o «paisaje invertido»; en caso contrario, devuelve ` false`.
Qt::PrimaryOrientation Se interpreta como la función ` primaryOrientation()` de la pantalla.
bool QScreen::isPortrait(Qt::ScreenOrientation o) const
Función de conveniencia que devuelve ` true ` si ` o ` es «portrait» o «inverted portrait»; en caso contrario, devuelve ` false`.
Qt::PrimaryOrientation Se interpreta como el valor de ` primaryOrientation()` de la pantalla.
QRect QScreen::mapBetween(Qt::ScreenOrientation a, Qt::ScreenOrientation b, const QRect &rect) const
Asigna el rectángulo entre dos orientaciones de pantalla.
Esto invertirá las dimensiones x e y del rectángulo rect si la orientación a es Qt::PortraitOrientation o Qt::InvertedPortraitOrientation y la orientación b es Qt::LandscapeOrientation o Qt::InvertedLandscapeOrientation, o viceversa.
Qt::PrimaryOrientation se interpreta como el método ` primaryOrientation()` de la pantalla.
template <typename QNativeInterface> QNativeInterface *QScreen::nativeInterface() const
Devuelve una interfaz nativa del tipo indicado para la pantalla.
Esta función proporciona acceso a la funcionalidad específica de la plataforma de QScreen, tal y como se define en el espacio de nombres QNativeInterface:
Interfaz nativa de una pantalla | |
Interfaz nativa para una pantalla en macOS | |
Interfaz nativa para una pantalla en Wayland | |
Interfaz nativa para una pantalla |
Si la interfaz solicitada no está disponible, se devuelve un objeto ` nullptr `.
[signal] void QScreen::orientationChanged(Qt::ScreenOrientation orientation)
Esta señal se emite cuando cambia la orientación de la pantalla con « orientation » como argumento.
Nota: Señalde notificación para la propiedad ` orientation`.
Véase también ` orientation()`.
[signal] void QScreen::primaryOrientationChanged(Qt::ScreenOrientation orientation)
Esta señal se emite cuando cambia la orientación principal de la pantalla con « orientation » como argumento.
Nota: Señalde notificación para la propiedad primaryOrientation.
Véase también primaryOrientation().
QTransform QScreen::transformBetween(Qt::ScreenOrientation a, Qt::ScreenOrientation b, const QRect &target) const
Función de conveniencia para calcular una transformación que mapea desde el sistema de coordenadas definido por la orientación a al sistema de coordenadas definido por la orientación b y las dimensiones de destino target.
Por ejemplo, si a es Qt::Landscape, b es Qt::Portrait y target es QRect(0, 0, w, h), la transformación resultante será tal que el punto QPoint(0, 0) se mapeará a QPoint(0, w), y QPoint(h, w) se mapeará a QPoint(0, h). De este modo, el sistema de coordenadas horizontal QRect(0, 0, h, w) se mapea (con una rotación de 90 grados) al sistema de coordenadas vertical QRect(0, 0, w, h).
Qt::PrimaryOrientation se interpreta como la posición « primaryOrientation » () de la pantalla.
QScreen *QScreen::virtualSiblingAt(QPoint point)
Devuelve la pantalla en point dentro del conjunto de QScreen::virtualSiblings(), o nullptr si se encuentra fuera de cualquier pantalla.
El point está relacionado con el virtualGeometry() de cada conjunto de hermanos virtuales.
QList<QScreen *> QScreen::virtualSiblings() const
Obtener los «hermanos virtuales» de la pantalla.
Los «hermanos virtuales» son las instancias de pantalla que comparten el mismo escritorio virtual. Comparten un sistema de coordenadas común, y las ventanas pueden moverse o colocarse libremente entre ellas sin necesidad de volver a crearlas.
© 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.