Window QML Type
Crée une nouvelle fenêtre de premier niveau. Plus d'informations...
| Import Statement: | import QtQuick |
| In C++: | QQuickWindow |
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 : variant
- 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)
- frameSwapped()
- sceneGraphError(SceneGraphError error, QString message)
Méthodes
- alert(int msec)
- close()
- hide()
- lower()
- raise()
- requestActivate()
- show()
- showFullScreen()
- showMaximized()
- showMinimized()
- showNormal()
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) de Qt Quick Controls au lieu de Window pour obtenir un style automatique.
Documentation sur les propriétés
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).
Remarque : tous les systèmes de fenêtrage ne permettent pas de définir ou d'interroger la position des fenêtres au niveau supérieur. Sur un tel système, le déplacement programmatique des fenêtres peut n'avoir aucun effet, et des valeurs artificielles peuvent être renvoyées pour les positions actuelles, telles que QPoint(0, 0).
Window { x: 100; y: 100; width: 100; height: 100 }

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.
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.
active : bool |
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 |
L'élément qui a actuellement le focus actif ou null s'il n'y a pas d'élément ayant 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é.
Remarque : si vous définissez la couleur sur "transparent" ou sur une couleur avec translucidité alpha, vous devez également définir une valeur appropriée pour flags, par exemple flags: Qt.FramelessWindowHint. Dans le cas contraire, la translucidité de la fenêtre peut ne pas être activée de manière cohérente sur toutes les plates-formes.
contentItem : Item |
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 des éléments similaires 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.
La propriété data vous permet de mélanger librement des enfants visuels, des ressources et d'autres fenêtres dans 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 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.
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 appliquer un fondu à la fenêtre 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 |
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 conserve 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 également Item::palette, Popup::palette, ColorGroup, et SystemPalette.
screen : variant |
L'écran auquel la fenêtre est associée.
Si elle est spécifiée 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 Qt.application.screens.
Remarque : pour s'assurer que la fenêtre est associée à l'écran souhaité lorsque la fenêtre native sous-jacente est créée, il convient de s'assurer que cette propriété est définie le plus tôt possible et que la définition de sa valeur n'est pas différée. Cela peut s'avérer particulièrement important sur les plates-formes embarquées dépourvues de système de fenêtrage, où une seule fenêtre par écran est autorisée à la fois. La définition de l'écran après la création d'une fenêtre ne déplace pas cette dernière si le nouvel écran fait partie du même bureau virtuel que l'ancien.
Voir également QWindow::setScreen(), QWindow::screen(), QScreen et Qt.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, que ce soit 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 :
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, réduite, 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 également visible et Qt Quick Exemples - Fenêtre et écran.
visible : bool |
Indique si la fenêtre est visible à l'écran.
Définir la valeur de visible à false revient à définir visibility à Hidden.
La valeur par défaut est false, sauf si elle est remplacée par visibility.
Voir également visibility.
Documentation sur les propriétés jointes
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.active : bool |
Cette propriété jointe indique si la fenêtre est active. La propriété attachée Window 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 |
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 |
Cette propriété jointe 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é Window attached peut être attachée à n'importe quel élément.
Window.visibility : QWindow::Visibility |
Cette propriété jointe indique si la fenêtre est actuellement affichée dans le système de fenêtrage en tant que fenêtre 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 Window peut être attachée à n'importe quel élément.
Documentation du signal
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.
Remarque : le gestionnaire correspondant est onAfterAnimating.
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 pour que la fenêtre soit 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.
Remarque : le gestionnaire correspondant est onClosing.
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.
Remarque : le gestionnaire correspondant est onFrameSwapped.
sceneGraphError(SceneGraphError error, QString message) |
Ce signal est émis lorsqu'un error s'est produit pendant 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.
Note : Le gestionnaire correspondant est onSceneGraphError.
Documentation de la méthode
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.
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.
hide() |
Masque la fenêtre.
Cela équivaut à définir visible sur false ou visibility sur Hidden.
Voir également show().
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.
raise() |
Remonte la fenêtre dans le système de fenêtrage.
Demande que la fenêtre soit levée pour apparaître au-dessus d'autres fenêtres.
requestActivate() |
Demande que la fenêtre soit activée, c'est-à-dire qu'elle reçoive le focus du clavier.
show() |
Affiche la fenêtre.
Cela équivaut à appeler showFullScreen(), showMaximized() ou showNormal(), en fonction du comportement par défaut de la plate-forme pour le type de fenêtre et les drapeaux.
Voir également showFullScreen(), showMaximized(), showNormal(), hide() et QQuickItem::flags().
showFullScreen() |
Affiche la fenêtre en plein écran.
Cela équivaut à configurer visibility en FullScreen.
showMaximized() |
Affiche la fenêtre en mode maximisé.
Équivalent au réglage de visibility à Maximized.
showMinimized() |
Affiche la fenêtre en tant que fenêtre réduite.
Équivalent au réglage de visibility à Minimized.
showNormal() |
Affiche la fenêtre comme normale, c'est-à-dire ni maximisée, ni minimisée, ni en plein écran.
Équivalent au réglage de visibility à Windowed.
© 2025 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.