Window QML Type

Crée une nouvelle fenêtre de niveau supérieur. En savoir plus…

• 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 associé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 niveau supérieur pour une scène Qt Quick. Il configure automatiquement la fenêtre pour qu'elle puisse être utilisée avec les types graphiques QtQuick.

Une fenêtre peut être déclarée à l’intérieur d’un élément (Item) ou d’une autre fenêtre ; dans ce cas, la fenêtre interne devient automatiquement « transitoire » par rapport à la fenêtre externe, cette dernière faisant office d’ transientParent. Dans ce cas, la plupart des plateformes afficheront la fenêtre centrée par rapport à la fenêtre externe, et il peut exister d’autres comportements dépendants de la plateforme, qui dépendent également de l’ flags. Si la fenêtre imbriquée est destinée à servir de boîte de dialogue dans votre application, vous devriez également définir flags sur Qt.Dialog, car certains gestionnaires de fenêtres n’assureront pas le centrage sans ce drapeau.

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

Vous pouvez également définir ou lier les signaux ` x ` et ` y ` pour positionner explicitement la fenêtre à 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 de ` onClosing ` qui définit ` close.accepted = false `, sauf s’il est possible de fermer la fenêtre en toute sécurité (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.

Mise en forme

Comme tous les types visuels dans Qt Quick, Window prend en charge palettes. Cependant, à l’instar de types tels que Text, Window n’utilise pas de palettes par défaut. Par exemple, pour modifier la couleur d’arrière-plan de la fenêtre lorsque le thème du système d’exploitation change, il faut définir la propriété 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 ») à la place de Qt Quick Controls au lieu de « Window » pour bénéficier d’une mise en forme automatique.

Documentation des propriétés

active : bool [read-only]

Statut d'activité 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 aussi requestActivate().

activeFocusItem : Item [read-only]

L'élément sur lequel se trouve actuellement le focus, ou ` null ` s'il n'y a aucun élément sur lequel le focus est activé.

color : color

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

La définition de cette propriété est plus efficace que l'utilisation d'un rectangle distinct.

contentItem : Item [read-only]

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

contentOrientation : Qt::ScreenOrientation

Il s'agit d'une indication destinée au gestionnaire de fenêtres au cas où celui-ci aurait besoin d'afficher du contenu supplémentaire, tel que des fenêtres contextuelles, des boîtes de dialogue, des barres d'état ou tout autre élément similaire, en rapport avec la fenêtre.

L'orientation recommandée est Screen.orientation, mais une application n'est pas tenue 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’angle de 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 combiner librement des éléments visuels enfants, des ressources et d’autres fenêtres au sein d’une même fenêtre.

Si vous attribuez une autre fenêtre à la liste « data », la fenêtre imbriquée deviendra « transitoire » pour la fenêtre externe.

Si vous attribuez une « Item » à la liste de données, celle-ci devient un enfant de l’« contentItem » de la fenêtre, de sorte qu’elle apparaît à l’intérieur de celle-ci. Le parent de l’élément sera l’« contentItem » de la fenêtre, qui constitue la racine de l’arborescence de propriété des éléments au sein de cette fenêtre.

Si vous attribuez un autre type d’objet, celui-ci est ajouté en tant que ressource.

Il ne devrait généralement pas être nécessaire de faire référence à la propriété data, car il s'agit de la propriété par défaut de la fenêtre et que tous les éléments enfants y sont donc automatiquement affectés.

Voir également QWindow::transientParent().

flags : Qt::WindowFlags

Les indicateurs de la fenêtre.

Les indicateurs de fenêtre déterminent l'apparence de la fenêtre dans le système de fenêtrage : s'il s'agit d'une boîte de dialogue, d'une fenêtre contextuelle ou d'une fenêtre classique, si elle doit comporter une barre de titre, etc.

Les indicateurs que vous lisez à partir de cette propriété peuvent différer de ceux que vous avez définis si les indicateurs demandés n'ont pas pu être pris en compte.

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 également 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'Screen, s'il n'y en a qu'un, 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 destinée au gestionnaire de fenêtres afin d'empêcher tout 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 donnée au gestionnaire de fenêtres afin d'empêcher tout redimensionnement en dessous de la largeur et de la hauteur spécifiées.

modality : Qt::WindowModality

Le mode de la fenêtre.

Une fenêtre modale empêche les autres fenêtres de recevoir des événements d'entrée. 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 gestion des fenêtres prend en charge l’opacité des fenêtres, cette propriété peut être utilisée pour faire apparaître ou disparaître progressivement la fenêtre, ou pour la rendre semi-transparente.

Une valeur égale ou supérieure à 1,0 correspond à une opacité totale, tandis qu'une valeur égale ou inférieure à 0,0 correspond à une transparence totale. Les valeurs intermédiaires correspondent à différents niveaux de translucidité entre ces 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 système. La classe ` QGuiApplication ` gère une palette système/thème qui sert de valeur par défaut pour toutes les fenêtres d’application. Vous pouvez également définir la palette par défaut des fenêtres en transmettant une palette personnalisée à la méthode ` QGuiApplication::setPalette()`, avant de charger tout code QML.

La fenêtre propage les propriétés de palette explicites 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 : Screen

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

Si elle est spécifiée avant l'affichage d'une fenêtre, celle-ci s'affichera sur cet écran, à moins qu'une position de fenêtre n'ait été explicitement définie. La valeur doit être un élément du tableau Application.screens.

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

title : string

Le titre de la fenêtre dans le système de gestion des fenêtres.

Le titre de la fenêtre peut apparaître dans la zone de titre des décorations de fenêtre, selon le système de gestion des fenêtres et les indicateurs de la fenêtre. Il peut également être utilisé par le système de gestion des fenêtres pour identifier la fenêtre dans d'autres contextes, comme dans le sélecteur de tâches.

transientParent : QWindow

La fenêtre dont cette fenêtre est une fenêtre contextuelle temporaire.

Il s'agit d'une indication destinée au gestionnaire de fenêtres, lui signalant que cette fenêtre est une boîte de dialogue ou une fenêtre contextuelle au nom de la fenêtre parente éphémère. Cela signifie généralement que la fenêtre éphémère sera centrée sur sa fenêtre parente éphémère lors de son affichage initial, que la réduction de la fenêtre parente entraînera également la réduction de la fenêtre éphémère, etc. ; toutefois, les résultats varient quelque peu d'une plateforme à l'autre.

La déclaration d’une fenêtre à l’intérieur d’un élément (Item) ou d’une autre fenêtre, que ce soit via la méthode ` default property ` ou une propriété dédiée, établit automatiquement une relation de parent éphémère avec la fenêtre contenante, à moins que la propriété `transientParent` ne soit explicitement définie. Cela s’applique également lors de la création d’éléments de type `Window` via ` Qt.createComponent ` ou ` Qt.createQmlObject `, à condition qu’un élément (Item) ou une fenêtre (Window) soit transmis en tant qu’argument ` parent `.

Une fenêtre ayant un parent temporaire ne s’affichera pas tant que son parent temporaire ne sera pas affiché, même si la propriété ` visible ` est définie sur ` true`. Cela s’applique également à la relation de parenté temporaire automatique décrite ci-dessus. En particulier, si l’élément contenant la fenêtre est un « Item », la fenêtre ne s’affichera pas tant que l’« Item » contenant n’aura pas été ajouté à une scène, via sa hiérarchie parentale visuelle. Définir la propriété « transientParent » sur « null » permettra de contourner ce comportement :

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

Afin que la fenêtre soit centrée par défaut au-dessus de son parent transitoire, selon le gestionnaire de fenêtres utilisé, il peut également être nécessaire de définir la propriété ` Window::flags ` avec une ` Qt::WindowType ` appropriée (telle que ` Qt::Dialog`).

Voir également parent().

visibility : QWindow::Visibility

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

La visibilité indique si la fenêtre doit apparaître dans le système de gestion des fenêtres en mode normal, minimisée, maximisée, en plein écran ou masquée.

Définir la visibilité sur « AutomaticVisibility » revient à attribuer à la fenêtre un état visible par défaut, qui peut être « FullScreen » ou « Windowed » selon la plateforme. Toutefois, lorsque vous lisez la propriété de visibilité, vous obtiendrez toujours l'état réel, jamais « AutomaticVisibility ».

Lorsqu’une fenêtre n’est pas « visible », sa visibilité est « Hidden ». Définir la visibilité sur « Hidden » revient à définir « visible » sur « 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 « visible » sur « false » revient à définir « visibility » sur « 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 associées

Window.active : bool [read-only attached]

Cette propriété associée indique si la fenêtre est active. La propriété associée « Window » peut être associée à n'importe quel élément.

Voici un exemple qui modifie une étiquette afin d’afficher l’état actif de la fenêtre dans laquelle elle s’affiche :

import QtQuick

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

Window.activeFocusItem : Item [read-only attached]

Cette propriété associée contient l'élément qui a actuellement le focus, ou ` null ` s'il n'y a aucun élément ayant le focus. La propriété associée `Window` peut être associée à n'importe quel élément.

Window.contentItem : Item [read-only attached]

Cette propriété associée contient l'élément racine invisible de la scène ou l'null, si l'élément ne se trouve pas dans une fenêtre. La propriété associée « Window » peut être associée à n'importe quel élément.

Ces propriétés associées contiennent la taille de la fenêtre de l'élément. La propriété associée « Window » peut être associée à n'importe quel élément.

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

Cette propriété associée s'applique quel que soit l'état actuel de la fenêtre dans le système de gestion des fenêtres : normale, réduite, agrandie, en plein écran ou masquée. La propriété associée « Window » peut être attribuée à n'importe quel élément (Item). Si l'élément n'apparaît dans aucune fenêtre, la valeur sera « Hidden ».

Voir également visible et visibility.

Window.window : Window [attached]

Cette propriété associée contient la fenêtre de l'élément. La propriété associée « Window » peut être associée à n'importe quel élément.

Documentation sur les signaux

afterAnimating()

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

Vous pouvez implémenter la méthode `onAfterAnimating` pour effectuer un traitement supplémentaire après chaque étape d'animation.

closing(CloseEvent close)

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

Ce signal inclut un paramètre « close ». La propriété « close.accepted » est définie sur « true » par défaut, ce qui autorise la fermeture de la fenêtre ; mais vous pouvez implémenter un gestionnaire « onClosing » et définir « close.accepted = false » si vous devez effectuer une autre action avant que la fenêtre ne puisse être fermée.

devicePixelRatioChanged()

frameSwapped()

Ce signal est émis lorsqu'une trame a été mise en file d'attente en vue de son affichage. Lorsque la synchronisation verticale est activée, le signal est émis au maximum une fois par intervalle de vsync dans une scène en animation continue.

sceneGraphError(SceneGraphError error, QString message)

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

Vous pouvez implémenter la méthode onSceneGraphError(error, message) pour gérer les erreurs, telles que les échecs de création de contexte graphique, de manière personnalisée. Si aucun gestionnaire n’est connecté à ce signal, Quick affichera l’ message, ou fera apparaître une boîte de message, puis mettra fin à l’application.

Documentation des méthodes

void alert(int msec)

Affiche une alerte pendant msec millisecondes. Si la valeur de msec est « 0 » (valeur par défaut), l’alerte reste affichée indéfiniment jusqu’à ce que la fenêtre redevienne active.

En état d'alerte, la fenêtre indique qu'elle requiert une attention particulière, par exemple en faisant clignoter ou rebondir son icône dans 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 celui-ci ne révoque pas l'autorisation de fermeture, la fenêtre se fermera ensuite. Si la propriété « QGuiApplication::quitOnLastWindowClosed » est définie sur « true » et qu'aucune autre fenêtre n'est ouverte, l'application se fermera.

void hide()

Masque la fenêtre.

Cela revient à définir ` visible ` sur ` false ` ou ` visibility ` sur ` Hidden`.

Voir également show().

void lower()

Abaisse la fenêtre dans le système de gestion des fenêtres.

Demande que la fenêtre soit placée en arrière-plan afin d'apparaître sous les autres fenêtres.

void raise()

Place la fenêtre au premier plan dans le système de gestion des fenêtres.

Demande que la fenêtre soit placée au premier plan afin qu'elle apparaisse au-dessus des autres fenêtres.

void requestActivate()

Demande que la fenêtre soit activée, c'est-à-dire qu'elle reçoive le focus du clavier.

void show()

Affiche la fenêtre.

Cela revient à appeler ` showFullScreen()`, ` showMaximized()` ou ` showNormal()`, selon le comportement par défaut de la plate-forme pour le type de fenêtre et les indicateurs.

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

void showFullScreen()

Affiche la fenêtre en plein écran.

Cela revient à définir la propriété ` visibility ` sur ` FullScreen`.

void showMaximized()

Affiche la fenêtre en mode agrandi.

Cela revient à définir ` visibility ` sur ` Maximized`.

void showMinimized()

Affiche la fenêtre en mode minimisé.

Cela revient à définir la propriété ` visibility ` sur ` Minimized`.

void showNormal()

Affiche la fenêtre de manière normale, c'est-à-dire ni agrandie, ni réduite, ni en plein écran.

Cela revient à définir 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 la prise en charge de la plateforme. La fenêtre suit le curseur de la souris jusqu'à ce que le bouton de la souris soit relâché.

Utilisez cette méthode à la place de ` setPosition`, car elle permet au gestionnaire de fenêtres de gérer l'alignement, la disposition en mosaïque et les animations associées. Sous 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.

Lance une opération de redimensionnement interactive de la fenêtre en utilisant la prise en charge de la plateforme. Le bord spécifié suit le curseur de la souris pendant le glissement.

Utilisez cette méthode plutôt que ` setGeometry`, car elle permet au gestionnaire de fenêtres de gérer l'alignement et les animations de redimensionnement lors du redimensionnement vers les bords de l'écran.

edges Doit correspondre à un seul bord 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.