Window QML Type
Crea una nueva ventana de nivel superior. Más...
| Import Statement: | import QtQuick |
| In C++: | QQuickWindow |
| Inherited By: |
Propiedades
- active : bool
- activeFocusItem : Item
- color : color
- contentItem : Item
- contentOrientation : Qt::ScreenOrientation
- data : list<QtObject>
- flags : Qt::WindowFlags
- height : int
- maximumHeight : int
- maximumWidth : int
- minimumHeight : int
- minimumWidth : int
- modality : Qt::WindowModality
- opacity : real
- palette : Palette
(since 6.0) - screen : Screen
- title : string
- transientParent : QWindow
- visibility : QWindow::Visibility
- visible : bool
- width : int
- x : int
- y : int
Propiedades adjuntas
- active : bool
- activeFocusItem : Item
- contentItem : Item
- height : int
- visibility : QWindow::Visibility
- width : int
- window : Window
Señales
- afterAnimating()
- closing(CloseEvent close)
- devicePixelRatioChanged()
- frameSwapped()
- sceneGraphError(SceneGraphError error, QString message)
Métodos
- void alert(int msec)
- void close()
- void hide()
- void lower()
- void raise()
- void requestActivate()
- void show()
- void showFullScreen()
- void showMaximized()
- void showMinimized()
- void showNormal()
- void startSystemMove()
(since 6.8) - void startSystemResize(Qt::Edges edges)
(since 6.8)
Descripción detallada
El objeto Window crea una nueva ventana de nivel superior para una escena de Qt Quick. Configura automáticamente la ventana para su uso con tipos gráficos de QtQuick.
Una ventana (Window) puede declararse dentro de un elemento (Item) o dentro de otra ventana; en este último caso, la ventana interna se convertirá automáticamente en «transitoria» respecto a la ventana externa, siendo esta última su contenedor ( transientParent). En este caso, la mayoría de las plataformas mostrarán la ventana centrada sobre la ventana exterior, y puede haber otros comportamientos dependientes de la plataforma, que también dependerán de la ventana principal ( flags). Si la ventana anidada está pensada para ser un cuadro de diálogo en tu aplicación, también debes establecer ` flags ` en ` Qt.Dialog`, ya que algunos gestores de ventanas no proporcionarán el comportamiento de centrado sin ese indicador.
También puede declarar varias ventanas dentro de un ` QtObject` de nivel superior; en ese caso, las ventanas no tendrán ninguna relación transitoria entre sí.
Como alternativa, puede establecer o vincular ` x ` y ` y ` para colocar la ventana de forma explícita en la pantalla.
Cuando el usuario intente cerrar una ventana, se emitirá la señal « closing ». Se puede forzar que la ventana permanezca abierta (por ejemplo, para pedir al usuario que guarde los cambios) escribiendo un controlador de « onClosing » que establezca « close.accepted = false » a menos que sea seguro cerrar la ventana (por ejemplo, porque ya no hay cambios sin guardar).
onClosing: (close) => {
if (document.changed) {
close.accepted = false
confirmExitPopup.open()
}
}
// The confirmExitPopup allows user to save or discard the document,
// or to cancel the closing.Estilo
Al igual que todos los tipos visuales de Qt Quick, Window admite palettes. Sin embargo, al igual que tipos como Text, Window no utiliza paletas de forma predeterminada. Por ejemplo, para cambiar el color de fondo de la ventana cuando cambia el tema del sistema operativo, se debe establecer color:
Window {
visible: true
// here we use the Window.active and Window.palette ordinary properties
color: active ? palette.active.window : palette.inactive.window
Text {
anchors.centerIn: parent
// here we use the Window.active attached property and the Item.palette property
color: Window.active ? palette.active.windowText : palette.inactive.windowText
text: Window.active ? "active" : "inactive"
}
}Utiliza ApplicationWindow (y Label) de Qt Quick Controls en lugar de Window para obtener un estilo automático.
Documentación de la propiedad
active : bool [read-only]
El estado activo de la ventana.
Window {
visible: true
// here we use the Window.active and Window.palette ordinary properties
color: active ? palette.active.window : palette.inactive.window
}Véase también requestActivate().
activeFocusItem : Item [read-only]
El elemento que tiene actualmente el foco activo o ` null ` si no hay ningún elemento con el foco activo.
color : color
El color de fondo de la ventana.
Establecer esta propiedad es más eficiente que utilizar un rectángulo independiente.
Nota: Si estableces el color en "transparent" o en un color con translucidez alfa, también debes establecer un valor adecuado para flags, como flags: Qt.FramelessWindowHint. De lo contrario, es posible que la translucidez de la ventana no se active de forma coherente en todas las plataformas.
contentItem : Item [read-only]
El elemento raíz invisible de la escena.
contentOrientation : Qt::ScreenOrientation
Esta es una indicación para el gestor de ventanas por si necesita mostrar contenido adicional, como ventanas emergentes, cuadros de diálogo, barras de estado o elementos similares, en relación con la ventana.
La orientación recomendada es « Screen.orientation », pero una aplicación no tiene por qué admitir todas las orientaciones posibles, por lo que puede optar por ignorar la orientación actual de la pantalla.
La diferencia entre la orientación de la ventana y la del contenido determina el ángulo de rotación del contenido.
El valor predeterminado es Qt::PrimaryOrientation.
Véase también « Screen ».
data : list<QtObject> [default]
La propiedad «data» te permite combinar libremente elementos visuales secundarios, recursos y otras ventanas dentro de una ventana.
Si asignas otra ventana a la lista de datos, la ventana anidada pasará a ser «transitoria» para la ventana exterior.
Si asignas un objeto « Item » a la lista de datos, este se convierte en un elemento secundario del « contentItem » de la ventana, de modo que aparece dentro de ella. El elemento principal del objeto será el « contentItem » de la ventana, que es la raíz del árbol de propiedad del objeto dentro de esa ventana.
Si se asigna cualquier otro tipo de objeto, se añade como recurso.
Por lo general, no debería ser necesario hacer referencia a la propiedad data, ya que es la propiedad predeterminada de la ventana y, por lo tanto, todos los elementos hijos se asignan automáticamente a esta propiedad.
Véase también QWindow::transientParent().
flags : Qt::WindowFlags
Los indicadores de la ventana.
Los indicadores de la ventana controlan su aspecto en el sistema de ventanas, ya sea un cuadro de diálogo, una ventana emergente o una ventana normal, y si debe tener una barra de título, etc.
Los indicadores que se lean en esta propiedad pueden diferir de los que se hayan establecido si no se han podido aplicar los indicadores solicitados.
import QtQuick
Window {
id: mainWindow
title: "Main Window"
color: "#456"
property real defaultSpacing: 10
property Splash splash: Splash {
onTimeout: mainWindow.show()
}
component Splash: Window {
id: splash
// a splash screen has no titlebar
flags: Qt.SplashScreen
// the transparent color lets background behind the image edges show through
color: "transparent"
modality: Qt.ApplicationModal // in case another application window is showing
title: "Splash Window" // for the taskbar/dock, task switcher etc.
visible: true
// here we use the Screen attached property to center the splash window
x: (Screen.width - splashImage.width) / 2
y: (Screen.height - splashImage.height) / 2
width: splashImage.width
height: splashImage.height
property int timeoutInterval: 2000
signal timeout
Image {
id: splashImage
source: "images/qt-logo.png"
}
TapHandler {
onTapped: splash.timeout()
}
Timer {
interval: splash.timeoutInterval; running: true; repeat: false
onTriggered: {
splash.visible = false
splash.timeout()
}
}
}
}Véase también Qt::WindowFlags y Qt Quick Ejemplos: Ventana y pantalla.
Define la posición y el tamaño de la ventana.
La posición (x, y) es relativa al « Screen » si solo hay uno, o al escritorio virtual (disposición de varias pantallas).
Nota: No todos los sistemas de ventanas admiten la configuración o la consulta de las posiciones de las ventanas de nivel superior. En dichos sistemas, el desplazamiento de ventanas mediante programación puede no surtir efecto, y es posible que se devuelvan valores artificiales para las posiciones actuales, como QPoint(0, 0).
Window { x: 100; y: 100; width: 100; height: 100 }
Define el tamaño máximo de la ventana.
Se trata de una indicación para el gestor de ventanas para que evite cambiar el tamaño por encima de la anchura y la altura especificadas.
Define el tamaño mínimo de la ventana.
Se trata de una indicación para el gestor de ventanas para que evite que el tamaño se reduzca por debajo de la anchura y la altura especificadas.
modality : Qt::WindowModality
La modalidad de la ventana.
Una ventana modal impide que otras ventanas reciban eventos de entrada. Los valores posibles son Qt.NonModal (el valor por defecto), Qt.WindowModal y Qt.ApplicationModal.
opacity : real
La opacidad de la ventana.
Si el sistema de ventanas admite la opacidad, esta se puede utilizar para hacer que la ventana aparezca y desaparezca gradualmente, o para hacerla semitransparente.
Un valor de 1,0 o superior se considera totalmente opaco, mientras que un valor de 0,0 o inferior se considera totalmente transparente. Los valores intermedios representan distintos niveles de translucidez entre ambos extremos.
El valor por defecto es 1,0.
palette : Palette [since 6.0]
Esta propiedad contiene la paleta establecida actualmente para la ventana.
La paleta predeterminada depende del entorno del sistema. QGuiApplication mantiene una paleta de sistema/tema que sirve como predeterminada para todas las ventanas de la aplicación. También puedes establecer la paleta predeterminada para las ventanas pasando una paleta personalizada a QGuiApplication::setPalette(), antes de cargar cualquier QML.
La ventana propaga las propiedades explícitas de la paleta a los elementos y controles secundarios, anulando cualquier valor predeterminado del sistema para dicha propiedad.
import QtQuick
import QtQuick.Controls
Window {
visible: true
// here we use the Window.active and Window.palette ordinary properties
color: active ? palette.active.window : palette.inactive.window
// colors that are not customized here come from SystemPalette
palette.active.window: "peachpuff"
palette.windowText: "brown"
Text {
anchors.centerIn: parent
// here we use the Window.active attached property and the Item.palette property
color: Window.active ? palette.active.windowText : palette.inactive.windowText
text: Window.active ? "active" : "inactive"
}
Button {
text: "Button"
anchors {
bottom: parent.bottom
bottomMargin: 6
horizontalCenter: parent.horizontalCenter
}
}
}Esta propiedad se introdujo en Qt 6.0.
Véase también Item::palette, Popup::palette, ColorGroup y SystemPalette.
screen : Screen
La pantalla a la que está asociada la ventana.
Si se especifica antes de mostrar una ventana, esta se mostrará en esa pantalla, a menos que se haya establecido explícitamente una posición de la ventana. El valor debe ser un elemento de la matriz Application.screens.
Nota: Para garantizar que la ventana se asocie a la pantalla deseada cuando se cree la ventana nativa subyacente, asegúrate de que esta propiedad se establezca lo antes posible y de que la configuración de su valor no se aplace. Esto puede resultar especialmente importante en plataformas integradas sin sistema de ventanas, en las que solo se permite una ventana por pantalla a la vez. Establecer la pantalla después de que se haya creado una ventana no desplaza la ventana si la nueva pantalla forma parte del mismo escritorio virtual que la pantalla anterior.
Véase también QWindow::setScreen(), QWindow::screen(), QScreen y Application.
title : string
El título de la ventana en el sistema de ventanas.
El título de la ventana puede aparecer en el área de título de los elementos decorativos de la ventana, dependiendo del sistema de ventanas y de los indicadores de la ventana. El sistema de ventanas también puede utilizarlo para identificar la ventana en otros contextos, como en el selector de tareas.
transientParent : QWindow
La ventana de la que esta ventana es una ventana emergente transitoria.
Esto indica al gestor de ventanas que esta ventana es un cuadro de diálogo o una ventana emergente en nombre de la ventana principal transitoria. Normalmente significa que la ventana transitoria se centrará sobre su ventana principal transitoria cuando se muestre por primera vez, que al minimizar la ventana principal también se minimizará la ventana transitoria, y así sucesivamente; sin embargo, los resultados varían ligeramente de una plataforma a otra.
Declarar una ventana dentro de un elemento (Item) u otra ventana, ya sea mediante ` default property ` o una propiedad específica, establecerá automáticamente una relación de padre transitorio con la ventana que la contiene, a menos que se establezca explícitamente la propiedad `transientParent`. Esto también se aplica al crear elementos de tipo ventana mediante ` Qt.createComponent ` o ` Qt.createQmlObject `, siempre que se pase un elemento (Item) o una ventana como argumento ` parent `.
Una ventana con un padre transitorio no se mostrará hasta que se muestre su padre transitorio, incluso si la propiedad visible tiene el valor true. Esto también se aplica a la relación de padre transitorio automática descrita anteriormente. En concreto, si el elemento contenedor de la ventana es un «Item», la ventana no se mostrará hasta que el «Item» contenedor se añada a una escena, a través de su jerarquía visual de padres. Establecer «transientParent» en « null » anulará este comportamiento:
Para que la ventana se centre por defecto sobre su padre transitorio, dependiendo del gestor de ventanas, también puede ser necesario establecer la propiedad ` Window::flags ` con un ` Qt::WindowType ` adecuado (como ` Qt::Dialog`).
Véase también parent().
visibility : QWindow::Visibility
El estado de ocupación de pantalla de la ventana.
La visibilidad indica si la ventana debe aparecer en el sistema de ventanas como normal, minimizada, maximizada, a pantalla completa u oculta.
Establecer la visibilidad en « AutomaticVisibility » significa asignar a la ventana un estado visible por defecto, que puede ser « FullScreen » o « Windowed », dependiendo de la plataforma. Sin embargo, al leer la propiedad de visibilidad, siempre se obtendrá el estado real, nunca « AutomaticVisibility ».
Cuando una ventana no está en estado « visible », su visibilidad es « Hidden ». Establecer la visibilidad en « Hidden » equivale a establecer « visible » en « false ».
El valor por defecto es Hidden
import QtQuick
import QtQuick.Controls
Window {
id: win
flags: Qt.Window | Qt.WindowFullscreenButtonHint
visibility: fullscreenButton.checked ? Window.FullScreen : Window.Windowed
Button {
id: fullscreenButton
anchors {
right: parent.right
top: parent.top
margins: 6
}
width: height
checkable: true
Binding on checked { value: win.visibility === Window.FullScreen }
text: "⛶"
ToolTip.visible: hovered
ToolTip.delay: Qt.styleHints.mousePressAndHoldInterval
ToolTip.text: win.visibility === Window.FullScreen ? qsTr("restore") : qsTr("fill screen")
}
}Véanse también visible y Qt Quick Ejemplos: «Ventana» y «Pantalla».
visible : bool
Si la ventana está visible en la pantalla.
Establecer «visible» en «false» equivale a establecer « visibility » en « Hidden ».
El valor por defecto es « false », a menos que se sobrescriba estableciendo « visibility ».
Véase también « visibility ».
Documentación de la propiedad adjunta
Window.active : bool [read-only attached]
Esta propiedad asociada indica si la ventana está activa. La propiedad asociada «Window» se puede asociar a cualquier elemento.
A continuación se muestra un ejemplo en el que se modifica una etiqueta para que muestre el estado activo de la ventana en la que se muestra:
import QtQuick
Text {
text: Window.active ? "active" : "inactive"
}Window.activeFocusItem : Item [read-only attached]
Esta propiedad asociada contiene el elemento que tiene actualmente el foco activo o, en caso de que no haya ningún elemento con el foco activo, ` null `. La propiedad asociada `Window` se puede asociar a cualquier elemento.
Window.contentItem : Item [read-only attached]
Esta propiedad adjunta contiene el elemento raíz invisible de la escena o una instanci null, si el elemento no se encuentra en una ventana. La propiedad adjunta «Window» se puede adjuntar a cualquier elemento.
Estas propiedades asociadas contienen el tamaño de la ventana del elemento. La propiedad asociada «Window» se puede asociar a cualquier elemento.
Window.visibility : QWindow::Visibility [read-only attached]
Esta propiedad asociada se mantiene independientemente de si la ventana se muestra actualmente en el sistema de ventanas como normal, minimizada, maximizada, a pantalla completa u oculta. La propiedad asociada ` Window ` puede asignarse a cualquier elemento (`Item`). Si el elemento no se muestra en ninguna ventana, el valor será ` Hidden`.
Véase también « visible » y « visibility ».
Window.window : Window [attached]
Esta propiedad asociada contiene la ventana del elemento. La propiedad asociada «Window» se puede asociar a cualquier elemento.
Documentación de Signal
afterAnimating()
Esta señal se emite en el hilo de la interfaz gráfica de usuario antes de solicitar al hilo de renderizado que realice la sincronización del grafo de escena.
Puedes implementar onAfterAnimating para realizar un procesamiento adicional tras cada paso de la animación.
Nota: El controlador correspondiente es ` onAfterAnimating`.
closing(CloseEvent close)
Esta señal se emite cuando el usuario intenta cerrar la ventana.
Esta señal incluye un parámetro « close ». La propiedad « close.accepted » está establecida en «true» por defecto, de modo que se permite el cierre de la ventana; sin embargo, puedes implementar un controlador « onClosing » y establecer « close.accepted = false » si necesitas realizar alguna otra acción antes de que se pueda cerrar la ventana.
Nota: El controlador correspondiente es onClosing.
devicePixelRatioChanged()
Nota: El gestor correspondiente es onDevicePixelRatioChanged.
frameSwapped()
Esta señal se emite cuando se ha puesto en cola un fotograma para su visualización. Con la sincronización vertical activada, la señal se emite como máximo una vez por intervalo de vsync en una escena con animación continua.
Nota: El controlador correspondiente es onFrameSwapped.
sceneGraphError(SceneGraphError error, QString message)
Esta señal se emite cuando se produce un error de « error » durante la inicialización del grafo de escena.
Puedes implementar onSceneGraphError(error, message) para gestionar errores, como fallos en la creación del contexto gráfico, de forma personalizada. Si no hay ningún controlador conectado a esta señal, Quick mostrará el message o mostrará un cuadro de mensaje y cerrará la aplicación.
Nota: El controlador correspondiente es onSceneGraphError.
Documentación de métodos
void alert(int msec)
Hace que se muestre una alerta durante msec milisegundos. Si msec es 0 (valor predeterminado), la alerta se muestra indefinidamente hasta que la ventana vuelva a estar activa.
En estado de alerta, la ventana indica que requiere atención, por ejemplo, haciendo parpadear o rebotar la entrada de la barra de tareas.
void close()
Cierra la ventana.
Cuando se invoca este método, o cuando el usuario intenta cerrar la ventana mediante el botón de la barra de título, se emite la señal « closing ». Si no hay ningún controlador, o si el controlador no revoca el permiso para cerrar, la ventana se cerrará a continuación. Si la propiedad « QGuiApplication::quitOnLastWindowClosed » tiene el valor « true » y no hay otras ventanas abiertas, la aplicación se cerrará.
void hide()
Oculta la ventana.
Equivale a establecer ` visible ` en ` false ` o ` visibility ` en ` Hidden`.
Véase también show().
void lower()
Baja la ventana en el sistema de ventanas.
Solicita que la ventana se sitúe por debajo de las demás.
void raise()
Elevará la ventana en el sistema de ventanas.
Solicita que la ventana se sitúe por encima de las demás.
void requestActivate()
Solicita que se active la ventana, es decir, que reciba el foco del teclado.
void show()
Muestra la ventana.
Esto equivale a llamar a showFullScreen(), showMaximized() o showNormal(), dependiendo del comportamiento predeterminado de la plataforma para el tipo de ventana y los indicadores.
Véanse también showFullScreen(), showMaximized(), showNormal(), hide() y QQuickItem::flags().
void showFullScreen()
Muestra la ventana a pantalla completa.
Equivale a establecer ` visibility ` en ` FullScreen`.
void showMaximized()
Muestra la ventana maximizada.
Equivale a establecer ` visibility ` en ` Maximized`.
void showMinimized()
Muestra la ventana minimizada.
Equivale a establecer ` visibility ` en ` Minimized`.
void showNormal()
Muestra la ventana de forma normal, es decir, ni maximizada, ni minimizada, ni a pantalla completa.
Equivale a establecer ` visibility ` en ` Windowed`.
[since 6.8] void startSystemMove()
Inicia una operación de desplazamiento específica del sistema.
Inicia una operación de desplazamiento interactiva en la ventana utilizando la compatibilidad de la plataforma. La ventana sigue al cursor del ratón hasta que se suelta el botón del ratón.
Utiliza este método en lugar de ` setPosition`, ya que permite que el gestor de ventanas se encargue del ajuste, la disposición en mosaico y las animaciones relacionadas. En Wayland, ` setPosition ` no es compatible, por lo que esta es la única forma en que la aplicación puede influir en la posición de la ventana.
Este método se introdujo en Qt 6.8.
[since 6.8] void startSystemResize(Qt::Edges edges)
Inicia una operación de cambio de tamaño específica del sistema.
Inicia una operación interactiva de cambio de tamaño en la ventana utilizando la compatibilidad de la plataforma. El borde especificado sigue al cursor del ratón mientras se arrastra.
Utiliza este método en lugar de ` setGeometry`, ya que permite al gestor de ventanas gestionar el ajuste y las animaciones de redimensionamiento al cambiar el tamaño hacia los bordes de la pantalla.
edges Debe ser un único borde o una combinación de dos bordes adyacentes (una esquina). No se permiten otros valores.
Este método se introdujo en Qt 6.8.
© 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.