Window QML Type

Crea una nueva ventana de nivel superior. Más...

• Lista de todos los miembros, incluidos los heredados

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 anexas

• 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 Qt Quick. Configura automáticamente la ventana para su uso con los tipos gráficos de QtQuick.

Una ventana puede declararse dentro de un elemento o dentro de otra ventana, en cuyo caso la ventana interior se convertirá automáticamente en "transitoria para" la ventana exterior, con la ventana exterior como su transientParent. La mayoría de las plataformas mostrarán la ventana centrada sobre la ventana exterior en este caso, y puede haber otros comportamientos dependientes de la plataforma, dependiendo también de flags. Si la ventana anidada está destinada a ser un diálogo en su aplicación, también debe establecer flags a Qt.Dialog, porque algunos gestores de ventanas no proporcionarán el comportamiento de centrado sin esa bandera.

También puede declarar múltiples ventanas dentro de un nivel superior QtObject, en cuyo caso las ventanas no tendrán ninguna relación transitoria.

Alternativamente, puede establecer o vincular x y y para posicionar la ventana explícitamente en la pantalla.

Cuando el usuario intente cerrar una ventana, se emitirá la señal closing. Puedes forzar que la ventana permanezca abierta (por ejemplo, para pedir al usuario que guarde los cambios) escribiendo un manejador onClosing que establezca close.accepted = false a menos que sea seguro cerrar la ventana (por ejemplo, porque no hay más 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.

Estilización de

Como todos los tipos visuales en Qt Quick, Window soporta palettes. Sin embargo, al igual que con tipos como Text, Window no utiliza paletas por defecto. Por ejemplo, para cambiar el color de fondo de la ventana cuando cambia el tema del sistema operativo, debe configurarse 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"
    }
}

Utilice ApplicationWindow (y Label) de Qt Quick Controls en lugar de Window para obtener un estilo automático.

Documentación de propiedades

active : bool [read-only]

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 foco activo.

color : color

El color de fondo de la ventana.

Establecer esta propiedad es más eficiente que utilizar un Rectángulo separado.

contentItem : Item [read-only]

El elemento raíz invisible de la escena.

contentOrientation : Qt::ScreenOrientation

Se trata de una pista para el gestor de ventanas en caso de que necesite mostrar contenido adicional como ventanas emergentes, cuadros de diálogo, barras de estado o similares en relación con la ventana.

La orientación recomendada es Screen.orientation, pero una aplicación no tiene por qué soportar todas las orientaciones posibles, y por lo tanto 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 grado de rotación del contenido.

El valor por defecto es Qt::PrimaryOrientation.

Véase también Screen.

data : list<QtObject> [default]

La propiedad data le permite mezclar libremente hijos visuales, recursos y otras Ventanas en una Ventana.

Si asigna otra Ventana a la lista de datos, la Ventana anidada se convertirá en "transitoria para" la Ventana exterior.

Si asigna un Item a la lista de datos, se convertirá en hijo de la ventana contentItem, de modo que aparecerá dentro de la ventana. El padre del elemento será el contentItem de la ventana, que es la raíz del árbol de propiedad del elemento dentro de esa ventana.

Si asigna cualquier otro tipo de objeto, se añadirá como recurso.

Por lo general, no debería ser necesario hacer referencia a la propiedad data, ya que es la propiedad por defecto de Window y, por tanto, todos los ítems hijos se asignan automáticamente a esta propiedad.

Véase también QWindow::transientParent().

flags : Qt::WindowFlags

Las banderas de ventana de la ventana.

Las banderas de ventana controlan la apariencia de la ventana en el sistema de ventanas, si es un diálogo, una ventana emergente o una ventana normal, y si debe tener una barra de título, etc.

Las banderas que se leen de esta propiedad pueden diferir de las que se establecen si las banderas solicitadas no pueden cumplirse.

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 a Screen si sólo hay una, o al escritorio virtual (disposición de varias pantallas).

Window { x: 100; y: 100; width: 100; height: 100 }

Define el tamaño máximo de la ventana.

Se trata de una indicación al gestor de ventanas para que no cambie el tamaño por encima de la anchura y la altura especificadas.

Define el tamaño mínimo de la ventana.

Es una indicación al gestor de ventanas para que no cambie el tamaño 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 predeterminado), Qt.WindowModal y Qt.ApplicationModal.

opacity : real

La opacidad de la ventana.

Si el sistema de ventanas admite la opacidad de la ventana, se puede utilizar para difuminarla o 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 actualmente establecida 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 puede establecer la paleta predeterminada para las ventanas pasando una paleta personalizada a QGuiApplication::setPalette(), antes de cargar cualquier QML.

Window propaga las propiedades explícitas de la paleta a los elementos y controles hijos, anulando cualquier valor predeterminado del sistema para esa 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 se asocia la ventana.

Si se especifica antes de mostrar una ventana, hará que la ventana se muestre en esa pantalla, a menos que se haya establecido una posición explícita de la ventana. El valor debe ser un elemento de la matriz Application.screens.

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 del título de las decoraciones de la ventana, dependiendo del sistema de ventanas y de las banderas de la ventana. También puede ser utilizado por el sistema de ventanas para identificar la ventana en otros contextos, como en el conmutador de tareas.

transientParent : QWindow

La ventana para la que esta ventana es una ventana emergente transitoria.

Es una indicación para el gestor de ventanas de que esta ventana es un diálogo o ventana emergente en nombre del padre transitorio. Normalmente significa que la ventana transitoria se centrará sobre su ventana padre transitoria cuando se muestre inicialmente, que al minimizar la ventana padre también se minimizará la ventana transitoria, etc.; sin embargo, los resultados varían un poco de una plataforma a otra.

Al declarar una ventana dentro de un elemento o de otra ventana, ya sea a través de default property o de una propiedad específica, se 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 cuando se crean elementos de ventana a través de Qt.createComponent o Qt.createQmlObject, siempre que se pase un elemento 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 es true. Esto también se aplica a la relación automática de padre transitorio descrita anteriormente. En particular, si el elemento contenedor de la ventana es un elemento, la ventana no se mostrará hasta que el elemento contenedor se añada a la escena, a través de su jerarquía visual. Estableciendo el transientParent a null anulará este comportamiento:

Window {
    // visible is false by default
    Window {
        transientParent: null
        visible: true
    }
}

Para hacer que la ventana se centre por encima de su padre transitorio por defecto, 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 a AutomaticVisibility significa dar 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 obtendrás el estado real, nunca AutomaticVisibility.

Cuando una ventana no es visible, su visibilidad es Hidden. Establecer la visibilidad en Hidden es lo mismo que 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éase también visible y Qt Quick Ejemplos - Ventana y Pantalla.

visible : bool

Si la ventana es visible en la pantalla.

Establecer visible a false es lo mismo que establecer visibility a Hidden.

El valor por defecto es false, a menos que se cambie por visibility.

Véase también visibility.

Documentación de la propiedad Attached

Window.active : bool [read-only]

Esta propiedad adjunta indica si la ventana está activa. La propiedad adjunta Window puede adjuntarse a cualquier Elemento.

A continuación se muestra un ejemplo que cambia una etiqueta para mostrar el estado activo de la ventana en la que se muestra:

import QtQuick

Text {
    text: Window.active ? "active" : "inactive"
}

Window.activeFocusItem : Item [read-only]

Esta propiedad adjunta contiene el ítem que actualmente tiene el foco activo o null si no hay ningún ítem con foco activo. La propiedad adjunta Window puede adjuntarse a cualquier elemento.

Window.contentItem : Item [read-only]

Esta propiedad adjunta contiene el ítem raíz invisible de la escena o null si el ítem no está en una ventana. La propiedad adjunta Window puede ser adjuntada a cualquier Item.

Estas propiedades adjuntas contienen el tamaño de la ventana del elemento. La propiedad adjunta Ventana puede adjuntarse a cualquier Elemento.

Window.visibility : QWindow::Visibility [read-only]

Esta propiedad adjunta mantiene si la ventana se muestra actualmente en el sistema de ventanas como normal, minimizada, maximizada, a pantalla completa u oculta. La propiedad adjunta Window puede adjuntarse a cualquier Elemento. Si el elemento no se muestra en ninguna ventana, el valor será Hidden.

Véase también visible y visibility.

Window.window : Window

Esta propiedad adjunta contiene la ventana del ítem. La propiedad adjunta Ventana puede adjuntarse a cualquier Elemento.

Documentación de Señales

afterAnimating()

Esta señal se emite en el hilo GUI antes de solicitar al hilo de renderizado que realice la sincronización del gráfico de la escena.

Puedes implementar onAfterAnimating para realizar un procesamiento adicional después de cada paso de animación.

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 es verdadera por defecto para que la ventana pueda cerrarse; pero puedes implementar un manejador onClosing y establecer close.accepted = false si necesitas hacer algo más antes de que la ventana pueda cerrarse.

devicePixelRatioChanged()

frameSwapped()

Esta señal se emite cuando un fotograma se ha puesto en cola para su presentación. Con la sincronización vertical activada, la señal se emite como máximo una vez por intervalo vsync en una escena de animación continua.

sceneGraphError(SceneGraphError error, QString message)

Esta señal se emite cuando se produce un error durante la inicialización del gráfico de escena.

Puedes implementar onSceneGraphError(error, mensaje) para manejar errores, como fallos en la creación del contexto gráfico, de forma personalizada. Si no hay ningún manejador conectado a esta señal, Quick imprimirá el mensaje message, o mostrará un cuadro de mensaje, y terminará la aplicación.

Documentación del método

void alert(int msec)

Hace que se muestre una alerta durante msec milisegundos. Si msec es 0 (el valor predeterminado), la alerta se muestra indefinidamente hasta que la ventana vuelve a estar activa.

En estado de alerta, la ventana indica que requiere atención, por ejemplo, parpadeando o haciendo rebotar la entrada de la barra de tareas.

void close()

Cierra la ventana.

Cuando se llame a este método, o cuando el usuario intente cerrar la ventana mediante su botón de la barra de título, se emitirá la señal closing. Si no hay manejador, o el manejador no revoca el permiso para cerrar, la ventana se cerrará posteriormente. Si la propiedad QGuiApplication::quitOnLastWindowClosed es true, y no hay otras ventanas abiertas, la aplicación se cerrará.

void hide()

Oculta la ventana.

Equivale a poner 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 baje para que aparezca debajo de otras ventanas.

void raise()

Eleva la ventana en el sistema de ventanas.

Solicita que la ventana se eleve para aparecer por encima de otras ventanas.

void requestActivate()

Solicita que la ventana se active, 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 por defecto de la plataforma para el tipo de ventana y las banderas.

Véase también showFullScreen(), showMaximized(), showNormal(), hide(), y QQuickItem::flags().

void showFullScreen()

Muestra la ventana como pantalla completa.

Equivale a configurar visibility en FullScreen.

void showMaximized()

Muestra la ventana maximizada.

Equivale a configurar visibility en Maximized.

void showMinimized()

Muestra la ventana como minimizada.

Equivale a configurar 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 movimiento específica del sistema.

Inicia una operación de movimiento interactiva en la ventana utilizando el soporte de la plataforma. La ventana sigue el cursor del ratón hasta que se suelta el botón del ratón.

Utilice este método en lugar de setPosition, ya que permite al gestor de ventanas manejar el ajuste, el mosaico y las animaciones relacionadas. En Wayland, setPosition no está soportado, 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 redimensionamiento específica del sistema.

Inicia una operación interactiva de redimensionamiento de la ventana utilizando el soporte de la plataforma. El borde especificado sigue el cursor del ratón mientras se arrastra.

Utilice este método en lugar de setGeometry, ya que permite al gestor de ventanas manejar las animaciones de ajuste y redimensionamiento cuando se redimensiona a 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.