Window QML Type

Crée une nouvelle fenêtre de premier niveau. Plus d'informations...

• Liste de tous les membres, y compris les membres hérités

Propriétés

• 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

Propriétés rattachées

• active : bool
• activeFocusItem : Item
• contentItem : Item
• height : int
• visibility : QWindow::Visibility
• width : int
• window : Window

Signaux

• afterAnimating()
• closing(CloseEvent close)
• devicePixelRatioChanged()
• frameSwapped()
• sceneGraphError(SceneGraphError error, QString message)

Méthodes

• 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)

Description détaillée

L'objet Window crée une nouvelle fenêtre de premier niveau pour une scène Qt Quick. Il configure automatiquement la fenêtre pour une utilisation avec les types graphiques QtQuick.

Une fenêtre peut être déclarée à l'intérieur d'un élément ou d'une autre fenêtre, auquel cas la fenêtre intérieure deviendra automatiquement "transitoire pour" la fenêtre extérieure, avec cette dernière comme transientParent. La plupart des plateformes afficheront la fenêtre centrée sur la fenêtre extérieure dans ce cas, et il peut y avoir d'autres comportements dépendant de la plateforme, en fonction également de flags. Si la fenêtre imbriquée est destinée à être une boîte de dialogue dans votre application, vous devez également définir flags sur Qt.Dialog, car certains gestionnaires de fenêtres ne fourniront pas le comportement de centrage sans cet indicateur.

Vous pouvez également déclarer plusieurs fenêtres à l'intérieur d'une fenêtre de niveau supérieur QtObject, auquel cas les fenêtres n'auront aucune relation transitoire.

Vous pouvez également définir ou lier x et y pour positionner explicitement la fenêtre sur l'écran.

Lorsque l'utilisateur tente de fermer une fenêtre, le signal closing est émis. Vous pouvez forcer la fenêtre à rester ouverte (par exemple pour inviter l'utilisateur à enregistrer ses modifications) en écrivant un gestionnaire onClosing qui active close.accepted = false jusqu'à ce qu'il soit possible de fermer la fenêtre (par exemple, parce qu'il n'y a plus de modifications non enregistrées).

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.

Style

Comme tous les types visuels de Qt Quick, Window prend en charge palettes. Cependant, comme pour les types tels que Text, Window n'utilise pas de palettes par défaut. Par exemple, pour changer la couleur d'arrière-plan de la fenêtre lorsque le thème du système d'exploitation change, il faut définir 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"
    }
}

Utilisez ApplicationWindow (et Label) à partir de Qt Quick Controls au lieu de Window pour obtenir un style automatique.

Documentation sur les propriétés

active : bool [read-only]

L'état actif de la fenêtre.

Window {
    visible: true

    // here we use the Window.active and Window.palette ordinary properties
    color: active ? palette.active.window : palette.inactive.window
}

Voir également requestActivate().

activeFocusItem : Item [read-only]

L'élément qui a actuellement le focus actif ou null s'il n'y a pas d'élément avec le focus actif.

color : color

La couleur d'arrière-plan de la fenêtre.

Il est plus efficace de définir cette propriété que d'utiliser un rectangle séparé.

contentItem : Item [read-only]

L'élément racine invisible de la scène.

contentOrientation : Qt::ScreenOrientation

Il s'agit d'un indice pour le gestionnaire de fenêtres au cas où il devrait afficher du contenu supplémentaire, comme des fenêtres contextuelles, des boîtes de dialogue, des barres d'état ou autres, par rapport à la fenêtre.

L'orientation recommandée est Screen.orientation, mais une application n'est pas obligée de prendre en charge toutes les orientations possibles et peut donc choisir d'ignorer l'orientation actuelle de l'écran.

La différence entre l'orientation de la fenêtre et celle du contenu détermine l'ampleur de la rotation du contenu.

La valeur par défaut est Qt::PrimaryOrientation.

Voir également Screen.

data : list<QtObject> [default]

La propriété data vous permet de mélanger librement les enfants visuels, les ressources et les autres fenêtres d'une fenêtre.

Si vous assignez une autre fenêtre à la liste de données, la fenêtre imbriquée deviendra "transitoire pour" la fenêtre extérieure.

Si vous assignez un Item à la liste de données, il devient un enfant de la fenêtre contentItem, de sorte qu'il apparaît à l'intérieur de la fenêtre. Le parent de l'élément sera le contentItem de la fenêtre, qui est la racine de l'arbre de propriété de l'élément dans cette fenêtre.

Si vous attribuez un autre type d'objet, il est ajouté en tant que ressource.

Il n'est généralement pas nécessaire de faire référence à la propriété data, car il s'agit de la propriété par défaut de Window et tous les éléments enfants sont donc automatiquement affectés à cette propriété.

Voir également QWindow::transientParent().

flags : Qt::WindowFlags

Les drapeaux de fenêtre de la fenêtre.

Les drapeaux de fenêtre contrôlent l'apparence de la fenêtre dans le système de fenêtrage, qu'il s'agisse d'une fenêtre de dialogue, d'une fenêtre contextuelle ou d'une fenêtre normale, et qu'elle ait ou non une barre de titre, etc.

Les drapeaux que vous lisez dans cette propriété peuvent être différents de ceux que vous avez définis si les drapeaux demandés n'ont pas pu être satisfaits.

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()
            }
        }
    }
}

Voir aussi Qt::WindowFlags et Qt Quick Exemples - Fenêtre et écran.

Définit la position et la taille de la fenêtre.

La position (x,y) est relative à l'adresse Screen s'il n'y en a qu'une, ou au bureau virtuel (disposition de plusieurs écrans).

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

Définit la taille maximale de la fenêtre.

Il s'agit d'une indication au gestionnaire de fenêtres pour empêcher le redimensionnement au-delà de la largeur et de la hauteur spécifiées.

Définit la taille minimale de la fenêtre.

Il s'agit d'une indication au gestionnaire de fenêtres pour empêcher le redimensionnement en dessous de la largeur et de la hauteur spécifiées.

modality : Qt::WindowModality

La modalité de la fenêtre.

Une fenêtre modale empêche les autres fenêtres de recevoir des événements de saisie. Les valeurs possibles sont Qt.NonModal (par défaut), Qt.WindowModal et Qt.ApplicationModal.

opacity : real

L'opacité de la fenêtre.

Si le système de fenêtrage prend en charge l'opacité de la fenêtre, cette valeur peut être utilisée pour faire apparaître ou disparaître la fenêtre en fondu, ou pour la rendre semi-transparente.

Une valeur de 1,0 ou plus est considérée comme totalement opaque, tandis qu'une valeur de 0,0 ou moins est considérée comme totalement transparente. Les valeurs intermédiaires représentent des niveaux de translucidité variables entre les deux extrêmes.

La valeur par défaut est 1.0.

palette : Palette [since 6.0]

Cette propriété contient la palette actuellement définie pour la fenêtre.

La palette par défaut dépend de l'environnement du système. QGuiApplication maintient une palette système/thème qui sert de palette par défaut pour toutes les fenêtres d'application. Vous pouvez également définir la palette par défaut pour les fenêtres en passant une palette personnalisée à QGuiApplication::setPalette(), avant de charger tout QML.

Window propage les propriétés explicites de la palette aux éléments et contrôles enfants, en remplaçant les valeurs par défaut du système pour cette propriété.

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
        }
    }
}

Cette propriété a été introduite dans Qt 6.0.

Voir aussi Item::palette, Popup::palette, ColorGroup, et SystemPalette.

screen : Screen

L'écran auquel la fenêtre est associée.

S'il est spécifié avant l'affichage d'une fenêtre, la fenêtre sera affichée sur cet écran, à moins qu'une position de fenêtre explicite n'ait été définie. La valeur doit être un élément du tableau Application.screens.

Voir aussi QWindow::setScreen(), QWindow::screen(), QScreen, et Application.

title : string

Titre de la fenêtre dans le système de fenêtrage.

Le titre de la fenêtre peut apparaître dans la zone de titre des décorations de la fenêtre, en fonction du système de fenêtrage et des drapeaux de la fenêtre. Il peut également être utilisé par le système de fenêtrage pour identifier la fenêtre dans d'autres contextes, par exemple dans le sélecteur de tâches.

transientParent : QWindow

La fenêtre pour laquelle cette fenêtre est une fenêtre contextuelle transitoire.

Il s'agit d'une indication au gestionnaire de fenêtres que cette fenêtre est une boîte de dialogue ou une fenêtre contextuelle au nom du parent transitoire. Cela signifie généralement que la fenêtre transitoire sera centrée sur son parent transitoire lors de son affichage initial, que la réduction de la fenêtre parentale entraînera également la réduction de la fenêtre transitoire, et ainsi de suite ; cependant, les résultats varient quelque peu d'une plate-forme à l'autre.

La déclaration d'une fenêtre à l'intérieur d'un élément ou d'une autre fenêtre, via default property ou une propriété dédiée, établira automatiquement une relation de parent transitoire avec la fenêtre qui la contient, à moins que la propriété transientParent ne soit explicitement définie. Cela s'applique également à la création d'éléments de fenêtre via Qt.createComponent ou Qt.createQmlObject, à condition qu'un élément ou une fenêtre soit transmis en tant qu'argument parent.

Une fenêtre avec un parent transitoire ne sera pas affichée tant que son parent transitoire n'est pas affiché, même si la propriété visible est true. Cela s'applique également à la relation parentale transitoire automatique décrite ci-dessus. En particulier, si l'élément contenant la fenêtre est un élément, la fenêtre ne sera pas affichée tant que l'élément contenant n'aura pas été ajouté à une scène, par l'intermédiaire de sa hiérarchie parentale visuelle. La définition de la valeur transientParent à null permet d'ignorer ce comportement :

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

Pour que la fenêtre soit centrée par défaut au-dessus de son parent transitoire, en fonction du gestionnaire de fenêtres, il peut également être nécessaire de définir la propriété Window::flags avec un Qt::WindowType approprié (tel que Qt::Dialog).

Voir également parent().

visibility : QWindow::Visibility

L'état d'occupation de l'écran de la fenêtre.

La visibilité indique si la fenêtre doit apparaître dans le système de fenêtrage comme normale, minimisée, maximisée, en plein écran ou cachée.

Définir la visibilité à AutomaticVisibility signifie donner à la fenêtre un état visible par défaut, qui peut être FullScreen ou Windowed en fonction de la plateforme. Toutefois, lorsque vous lisez la propriété de visibilité, vous obtenez toujours l'état réel, jamais AutomaticVisibility.

Lorsqu'une fenêtre n'est pas visible, sa visibilité est Hidden. Définir la visibilité à Hidden revient à définir visible à false.

La valeur par défaut est 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")
    }
}

Voir aussi visible et Qt Quick Exemples - Fenêtre et écran.

visible : bool

Indique si la fenêtre est visible à l'écran.

Attribuer la valeur false à visible revient à attribuer la valeur visibility à Hidden.

La valeur par défaut est false, sauf si elle est remplacée par le paramètre visibility.

Voir également visibility.

Documentation sur la propriété attachée

Window.active : bool [read-only]

Cette propriété jointe indique si la fenêtre est active. La propriété attachée à la fenêtre peut être attachée à n'importe quel élément.

Voici un exemple qui modifie une étiquette pour indiquer l'état actif de la fenêtre dans laquelle elle est affichée :

import QtQuick

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

Window.activeFocusItem : Item [read-only]

Cette propriété attachée contient l'élément qui a actuellement le focus actif ou null s'il n'y a pas d'élément avec le focus actif. La propriété attachée à la fenêtre peut être attachée à n'importe quel élément.

Window.contentItem : Item [read-only]

Cette propriété attachée contient l'élément racine invisible de la scène ou null si l'élément n'est pas dans une fenêtre. La propriété attachée à la fenêtre peut être attachée à n'importe quel élément.

Ces propriétés jointes définissent la taille de la fenêtre de l'élément. La propriété attachée Fenêtre peut être attachée à n'importe quel élément.

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

La propriété attached indique si la fenêtre est actuellement affichée dans le système de fenêtrage comme normale, minimisée, maximisée, plein écran ou cachée. La propriété attachée Window peut être attachée à n'importe quel élément. Si l'élément n'est affiché dans aucune fenêtre, la valeur sera Hidden.

Voir également visible et visibility.

Window.window : Window

Cette propriété jointe contient la fenêtre de l'élément. La propriété attachée Fenêtre peut être attachée à n'importe quel élément.

Documentation sur les signaux

afterAnimating()

Ce signal est émis par le thread de l'interface graphique avant de demander au thread de rendu d'effectuer la synchronisation du graphe de scène.

Vous pouvez implémenter onAfterAnimating pour effectuer un traitement supplémentaire après chaque étape de l'animation.

closing(CloseEvent close)

Ce signal est émis lorsque l'utilisateur tente de fermer la fenêtre.

Ce signal comprend un paramètre close. La propriété close.accepted est vraie par défaut, de sorte que la fenêtre est autorisée à se fermer ; mais vous pouvez implémenter un gestionnaire onClosing et définir close.accepted = false si vous devez faire quelque chose d'autre avant que la fenêtre ne puisse être fermée.

devicePixelRatioChanged()

frameSwapped()

Ce signal est émis lorsqu'une image a été mise en file d'attente pour être présentée. Lorsque la synchronisation verticale est activée, le signal est émis au maximum une fois par intervalle vsync dans une scène animée en continu.

sceneGraphError(SceneGraphError error, QString message)

Ce signal est émis lorsqu'une erreur error s'est produite lors de l'initialisation du graphe de scène.

Vous pouvez implémenter onSceneGraphError(error, message) pour gérer les erreurs, telles que les échecs de création de contexte graphique, d'une manière personnalisée. Si aucun gestionnaire n'est connecté à ce signal, Quick imprimera le message message, ou affichera une boîte de message, et terminera l'application.

Documentation de la méthode

void alert(int msec)

Provoque l'affichage d'une alerte pendant msec millisecondes. Si msec est 0 (valeur par défaut), l'alerte est affichée indéfiniment jusqu'à ce que la fenêtre redevienne active.

En état d'alerte, la fenêtre indique qu'elle demande de l'attention, par exemple en faisant clignoter ou rebondir l'entrée de la barre des tâches.

void close()

Ferme la fenêtre.

Lorsque cette méthode est appelée, ou lorsque l'utilisateur tente de fermer la fenêtre à l'aide du bouton de la barre de titre, le signal closing est émis. S'il n'y a pas de gestionnaire, ou si le gestionnaire ne révoque pas l'autorisation de fermer, la fenêtre se fermera par la suite. Si la propriété QGuiApplication::quitOnLastWindowClosed est true et qu'aucune autre fenêtre n'est ouverte, l'application se ferme.

void hide()

Masque la fenêtre.

Cela équivaut à régler visible sur false ou visibility sur Hidden.

Voir également show().

void lower()

Abaisse la fenêtre dans le système de fenêtrage.

Demande que la fenêtre soit abaissée pour apparaître sous d'autres fenêtres.

void raise()

Relève la fenêtre dans le système de fenêtrage.

Demande que la fenêtre soit élevée pour apparaître au-dessus des autres fenêtres.

void requestActivate()

Demande à la fenêtre d'être activée, c'est-à-dire de recevoir le focus clavier.

void show()

Affiche la fenêtre.

Cela équivaut à appeler showFullScreen(), showMaximized() ou showNormal(), en fonction du comportement par défaut de la plateforme pour le type de fenêtre et les drapeaux.

Voir aussi showFullScreen(), showMaximized(), showNormal(), hide() et QQuickItem::flags().

void showFullScreen()

Affiche la fenêtre en plein écran.

Cela équivaut à régler visibility sur FullScreen.

void showMaximized()

Affiche la fenêtre comme étant maximisée.

Cela équivaut à régler visibility sur Maximized.

void showMinimized()

Affiche la fenêtre comme étant réduite.

Cela équivaut à régler visibility sur Minimized.

void showNormal()

Affiche la fenêtre normalement, c'est-à-dire ni maximisée, ni minimisée, ni en plein écran.

Cela équivaut à régler visibility sur Windowed.

[since 6.8] void startSystemMove()

Lance une opération de déplacement spécifique au système.

Lance une opération de déplacement interactive sur la fenêtre en utilisant le support de la plate-forme. La fenêtre suit le curseur de la souris jusqu'à ce que le bouton de la souris soit relâché.

Utilisez cette méthode au lieu de setPosition, car elle permet au gestionnaire de fenêtres de gérer l'accrochage, le tuilage et les animations associées. Sur Wayland, setPosition n'est pas pris en charge, c'est donc le seul moyen pour l'application d'influencer la position de la fenêtre.

Cette méthode a été introduite dans Qt 6.8.

[since 6.8] void startSystemResize(Qt::Edges edges)

Lance une opération de redimensionnement spécifique au système.

Démarre une opération interactive de redimensionnement de la fenêtre en utilisant le support de la plateforme. Le bord spécifié suit le curseur de la souris lors du déplacement.

Utilisez cette méthode au lieu de setGeometry, car elle permet au gestionnaire de fenêtres de gérer les animations d'accrochage et de redimensionnement lors du redimensionnement sur les bords de l'écran.

edges doit être un bord unique ou une combinaison de deux bords adjacents (un coin). Les autres valeurs ne sont pas autorisées.

Cette méthode a été introduite dans Qt 6.8.