QWindowCapture Class
Esta clase se utiliza para capturar una ventana. Más información...
| Encabezado: | #include <QWindowCapture> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Multimedia) target_link_libraries(mytarget PRIVATE Qt6::Multimedia) |
| qmake: | QT += multimedia |
| Desde: | Qt 6.6 |
| En QML: | WindowCapture |
| Heredan de: | QObject |
Tipos públicos
| enum | Error { NoError, InternalError, CapturingNotSupported, CaptureFailed, NotFound } |
Propiedades
|
|
Funciones públicas
| QWindowCapture(QObject *parent = nullptr) | |
| virtual | ~QWindowCapture() override |
| QMediaCaptureSession * | captureSession() const |
| QWindowCapture::Error | error() const |
| QString | errorString() const |
| bool | isActive() const |
| std::optional<qreal> | maximumFrameRate() const |
| void | setMaximumFrameRate(std::optional<qreal> frameRate) |
| void | setWindow(QCapturableWindow window) |
| QCapturableWindow | window() const |
Ranuras públicas
Señales
| void | activeChanged(bool) |
| void | errorChanged() |
| void | errorOccurred(QWindowCapture::Error error, const QString &errorString) |
| void | maximumFrameRateChanged() |
| void | windowChanged(QCapturableWindow window) |
Miembros públicos estáticos
| QList<QCapturableWindow> | capturableWindows() |
Descripción detallada
La clase captura una ventana. Está gestionada por la clase QMediaCaptureSession, donde la ventana capturada se puede mostrar en un objeto de vista previa de vídeo o grabarse en un archivo.
El siguiente fragmento de código muestra cómo seleccionar una de las ventanas capturables y mostrar el resultado en un objeto ` QVideoWidget`:
QMediaCaptureSession session;
QWindowCapture windowCapture;
session.setWindowCapture(&windowCapture);
QVideoWidget videoWidget;
session.setVideoOutput(&videoWidget);
videoWidget.show();
// A window must be selected before capturing can start.
const QList<QCapturableWindow> windows = QWindowCapture::capturableWindows();
if (!windows.isEmpty()) {
windowCapture.setWindow(windows.first());
windowCapture.start();
}Limitaciones de la captura de ventanas
Se aplican las siguientes limitaciones al uso de QWindowCapture:
- QWindowCapture solo es compatible con el backend de FFmpeg.
- En algunas plataformas, no se emiten nuevos fotogramas de vídeo mientras el contenido de la ventana capturada permanece sin cambios. Por lo tanto, las aplicaciones no deben basarse en la recepción de un flujo continuo de fotogramas a la frecuencia de fotogramas solicitada.
Se aplican las siguientes limitaciones al utilizar QWindowCapture en sistemas X11:
- En los sistemas Linux X11, cuando una ventana se desplaza parcialmente fuera del área visible de la pantalla, solo se captura la región visible. Como resultado, los fotogramas de vídeo emitidos pueden tener un tamaño inferior al de la geometría de la ventana.
- Las ventanas que se encuentran fuera del área visible de la pantalla no se pueden capturar, y en ese caso se emite una señal de error.
- El comportamiento de las ventanas minimizadas o de aquellas situadas en un espacio de trabajo virtual invisible depende del gestor de ventanas. Por ejemplo, estas ventanas se pueden capturar en GNOME, mientras que en WindowMaker o Xfwm no se permite dicha captura, y la instancia de captura de ventanas emite un error.
Véase también QMediaCaptureSession y QCapturableWindow.
Documentación sobre tipos de miembros
enum QWindowCapture::Error
Enumera los códigos de error que puede indicar la clase ` QWindowCapture `. La función ` errorString()` proporciona información detallada sobre la causa del error.
| Constante | Valor | Descripción |
|---|---|---|
QWindowCapture::NoError | 0 | Sin error |
QWindowCapture::InternalError | 1 | Error interno del controlador de captura de ventanas |
QWindowCapture::CapturingNotSupported | 2 | La captura de ventanas no es compatible |
QWindowCapture::CaptureFailed | 4 | Error al capturar la ventana |
QWindowCapture::NotFound | 5 | No se ha encontrado la ventana seleccionada |
Documentación de propiedades
active : bool
Esta propiedad indica si la captura está activa en este momento.
Funciones de acceso:
| bool | isActive() const |
| void | setActive(bool active) |
Señal de notificador:
| void | activeChanged(bool) |
Véase también start() y stop().
[read-only] error : Error
Esta propiedad contiene el código del último error.
Funciones de acceso:
| QWindowCapture::Error | error() const |
Señal de notificación:
| void | errorChanged() |
[read-only] errorString : QString
Esta propiedad contiene una cadena legible que describe la causa del error.
Funciones de acceso:
| QString | errorString() const |
Señal de notificación:
| void | errorChanged() |
[since 6.12] maximumFrameRate : std::optional<qreal>
Esta propiedad establece el límite máximo de la frecuencia de fotogramas de la captura de ventana.
Se puede configurar para anular la frecuencia de fotogramas de captura utilizada por defecto en función, por ejemplo, de la frecuencia de actualización de la pantalla, pero solo como límite máximo, ya que la captura de ventana genera fotogramas a una frecuencia variable. No se recomienda establecer este valor por encima de la frecuencia de actualización de la pantalla, ya que puede provocar errores.
Cualquier cambio en esta propiedad se aplica la próxima vez que el « QWindowCapture » se active.
Esta enumeración se introdujo en Qt 6.12.
Funciones de acceso:
| std::optional<qreal> | maximumFrameRate() const |
| void | setMaximumFrameRate(std::optional<qreal> frameRate) |
Señal del notificador:
| void | maximumFrameRateChanged() |
window : QCapturableWindow
Esta propiedad contiene la ventana de captura.
Si se establece esta propiedad en una ventana no válida de una aplicación « QWindowCapture » activa, esta pasará a estar inactiva y generará un error.
Funciones de acceso:
| QCapturableWindow | window() const |
| void | setWindow(QCapturableWindow window) |
Señal de notificador:
| void | windowChanged(QCapturableWindow window) |
Véase también QWindowCapture::capturableWindows.
Documentación de funciones de miembro
[explicit] QWindowCapture::QWindowCapture(QObject *parent = nullptr)
Crea un nuevo objeto `QWindowCapture` con ` parent`.
[override virtual noexcept] QWindowCapture::~QWindowCapture()
Destruye el objeto.
[static invokable] QList<QCapturableWindow> QWindowCapture::capturableWindows()
Devuelve una lista de objetos ` QCapturableWindow ` que están disponibles actualmente para la grabación.
Nota: En macOS, al invocar este método se abrirá el cuadro de diálogo de permisos «Grabación de pantalla». Si aún no se han concedido los permisos, este método devolverá una lista vacía. Si se invoca varias veces, este cuadro de diálogo aparecerá en primer plano.
Nota: Esta función se puede invocar a través del sistema de metaobjetos y desde QML. Véase Q_INVOKABLE.
QMediaCaptureSession *QWindowCapture::captureSession() const
Devuelve la sesión de captura a la que está conectada esta ventana « QWindowCapture ».
Utiliza QMediaCaptureSession::setWindowCapture() para conectar la captura de ventana a una sesión.
[signal] void QWindowCapture::errorChanged()
Esta señal se emite cuando se modifican las propiedades ` error ` o ` errorString `.
Esta señal no se emite cuando se producen varios errores idénticos. Para realizar un seguimiento de dichos errores, utiliza la señal errorOccurred.
Nota: Señalde notificación para las propiedades ` error ` y ` errorString`.
[signal] void QWindowCapture::errorOccurred(QWindowCapture::Error error, const QString &errorString)
Avisa cuando se produce un error de « error », junto con el error « errorString ».
[slot] void QWindowCapture::start()
Comienza a capturar la propiedad « window ».
Esto equivale a establecer la propiedad active en «true».
[slot] void QWindowCapture::stop()
Detiene la captura.
Esto equivale a establecer la propiedad active en false.
© 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.