En esta página

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:

QNativeInterface::QAndroidScreen

Interfaz nativa de una pantalla

QNativeInterface::QCocoaScreen

Interfaz nativa para una pantalla en macOS

QNativeInterface::QWaylandScreen

Interfaz nativa para una pantalla en Wayland

QNativeInterface::QWindowsScreen

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.