Window QML Type

Erstellt ein neues Fenster auf oberster Ebene. Mehr...

• Liste aller Elemente, einschließlich geerbter Elemente

Eigenschaften

• 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

Zugehörige Eigenschaften

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

Signale

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

Methoden

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

Ausführliche Beschreibung

Das „Window“-Objekt erstellt ein neues Fenster der obersten Ebene für eine „ Qt Quick “-Szene. Es richtet das Fenster automatisch für die Verwendung mit grafischen Elementen vom Typ „ QtQuick “ ein.

Ein „Window“ kann innerhalb eines „Item“ oder innerhalb eines anderen „Window“ deklariert werden; in diesem Fall wird das innere „Window“ automatisch „transient for“ des äußeren „Window“, wobei das äußere „Window“ als sein „ transientParent “ fungiert. Die meisten Plattformen zeigen das Fenster in diesem Fall zentriert innerhalb des äußeren Fensters an; je nach „ flags “ können weitere plattformabhängige Verhaltensweisen auftreten. Wenn das verschachtelte Fenster in Ihrer Anwendung als Dialogfeld dienen soll, sollten Sie außerdem „ flags “ auf „ Qt.Dialog “ setzen, da einige Fenstermanager ohne dieses Flag die Zentrierung nicht gewährleisten.

Sie können auch mehrere Fenster innerhalb eines „ QtObject “ der obersten Ebene deklarieren; in diesem Fall besteht zwischen den Fenstern keine vorübergehende Beziehung.

Alternativ können Sie „ x “ und „ y “ setzen oder binden, um das Fenster explizit auf dem Bildschirm zu positionieren.

Wenn der Benutzer versucht, ein Fenster zu schließen, wird das Signal „ closing “ ausgelöst. Sie können das Fenster zwangsweise offen halten (beispielsweise, um den Benutzer aufzufordern, Änderungen zu speichern), indem Sie einen „ onClosing “-Handler schreiben, der „ close.accepted = false “ setzt, sofern das Schließen des Fensters nicht sicher ist (beispielsweise, weil keine ungespeicherten Änderungen mehr vorhanden sind).

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.

Gestaltung

Wie alle visuellen Typen in „ Qt Quick “ unterstützt „Window“ die Eigenschaft „ palettes “. Allerdings verwendet „Window“ – ebenso wie Typen wie „ Text “ – standardmäßig keine Paletten. Um beispielsweise die Hintergrundfarbe des Fensters zu ändern, wenn sich das Design des Betriebssystems ändert, muss die Eigenschaft „ color “ gesetzt werden:

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

Verwenden Sie „ ApplicationWindow “ (und „ Label “) anstelle von Qt Quick Controls anstelle von „Window“, um eine automatische Stilzuweisung zu erhalten.

Dokumentation zu den Eigenschaften

active : bool [read-only]

Der Status des Fensters (aktiv).

Window {
    visible: true

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

Siehe auch requestActivate().

activeFocusItem : Item [read-only]

Das Element, das derzeit den Fokus hat, oder null, falls kein Element den Fokus hat.

color : color

Die Hintergrundfarbe des Fensters.

Das Festlegen dieser Eigenschaft ist effizienter als die Verwendung eines separaten Rechtecks.

contentItem : Item [read-only]

Das unsichtbare Stammelement der Szene.

contentOrientation : Qt::ScreenOrientation

Dies ist ein Hinweis für den Fenstermanager, falls er zusätzliche Inhalte wie Popups, Dialogfelder, Statusleisten oder Ähnliches in Bezug auf das Fenster anzeigen muss.

Die empfohlene Ausrichtung ist „ Screen.orientation “, aber eine Anwendung muss nicht alle möglichen Ausrichtungen unterstützen und kann daher die aktuelle Bildschirmausrichtung ignorieren.

Der Unterschied zwischen der Ausrichtung des Fensters und der des Inhalts bestimmt, um wie viel der Inhalt gedreht werden soll.

Der Standardwert ist „ Qt::PrimaryOrientation “.

Siehe auch „ Screen “.

data : list<QtObject> [default]

Mit der Eigenschaft „data“ können Sie visuelle untergeordnete Elemente, Ressourcen und andere Fenster in einem Fenster beliebig miteinander kombinieren.

Wenn Sie der Datenliste ein anderes Fenster zuweisen, wird das verschachtelte Fenster für das äußere Fenster „vorübergehend“ angezeigt.

Wenn Sie der Datenliste ein „ Item “ zuweisen, wird dieses zu einem untergeordneten Element des „ contentItem “ des Fensters, sodass es innerhalb des Fensters angezeigt wird. Das übergeordnete Element des Objekts ist der „ contentItem “ des Fensters, der die Wurzel des Item-Eigentumsbaums innerhalb dieses Fensters darstellt.

Wenn Sie einen anderen Objekttyp zuweisen, wird dieser als Ressource hinzugefügt.

Es sollte im Allgemeinen nicht notwendig sein, auf die Eigenschaft „ data “ zu verweisen, da es sich um die Standardeigenschaft für „Window“ handelt und somit alle untergeordneten Elemente automatisch dieser Eigenschaft zugewiesen werden.

Siehe auch „ QWindow::transientParent()“.

flags : Qt::WindowFlags

Die Fensterflags des Fensters.

Die Fensterflags steuern das Erscheinungsbild des Fensters im Fenstersystem, z. B. ob es sich um ein Dialogfeld, ein Popup-Fenster oder ein normales Fenster handelt und ob es eine Titelleiste haben soll usw.

Die Flags, die Sie aus dieser Eigenschaft auslesen, können von den von Ihnen festgelegten abweichen, wenn die angeforderten Flags nicht erfüllt werden konnten.

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

Siehe auch „ Qt::WindowFlags “ und „Qt Quick -Beispiele – Fenster und Bildschirm“.

Legt die Position und Größe des Fensters fest.

Die (x,y)-Position bezieht sich auf den „ Screen “, sofern nur einer vorhanden ist, oder auf den virtuellen Desktop (Anordnung mehrerer Bildschirme).

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

Legt die maximale Größe des Fensters fest.

Dies ist ein Hinweis an den Fenstermanager, eine Größenänderung über die angegebene Breite und Höhe hinaus zu verhindern.

Legt die Mindestgröße des Fensters fest.

Dies ist ein Hinweis an den Fenstermanager, eine Größenänderung unterhalb der angegebenen Breite und Höhe zu verhindern.

modality : Qt::WindowModality

Die Modalität des Fensters.

Ein modales Fenster verhindert, dass andere Fenster Eingabeereignisse empfangen. Mögliche Werte sind Qt.NonModal (Standard), Qt.WindowModal und Qt.ApplicationModal.

opacity : real

Die Deckkraft des Fensters.

Wenn das Fenstersystem die Opazität von Fenstern unterstützt, kann diese genutzt werden, um das Fenster ein- und auszublenden oder es halbtransparent zu machen.

Ein Wert von 1,0 oder höher wird als vollständig undurchsichtig behandelt, während ein Wert von 0,0 oder niedriger als vollständig transparent behandelt wird. Werte dazwischen stellen unterschiedliche Transparenzgrade zwischen diesen beiden Extremen dar.

Der Standardwert ist 1,0.

palette : Palette [since 6.0]

Diese Eigenschaft enthält die derzeit für das Fenster festgelegte Palette.

Die Standardpalette hängt von der Systemumgebung ab. „ QGuiApplication “ verwaltet eine System-/Designpalette, die als Standard für alle Anwendungsfenster dient. Sie können die Standardpalette für Fenster auch festlegen, indem Sie vor dem Laden von QML eine benutzerdefinierte Palette an „ QGuiApplication::setPalette()“ übergeben.

Das Fenster gibt explizite Paletteneigenschaften an untergeordnete Elemente und Steuerelemente weiter und überschreibt dabei alle Systemstandardwerte für diese Eigenschaft.

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

Diese Eigenschaft wurde in Qt 6.0 eingeführt.

Siehe auch Item::palette, Popup::palette, ColorGroup und SystemPalette.

screen : Screen

Der Bildschirm, dem das Fenster zugeordnet ist.

Wird dieser Wert vor dem Anzeigen eines Fensters angegeben, wird das Fenster auf diesem Bildschirm angezeigt, sofern keine explizite Fensterposition festgelegt wurde. Der Wert muss ein Element aus dem Array „ Application.screens “ sein.

Siehe auch QWindow::setScreen(), QWindow::screen(), QScreen und Application.

title : string

Der Titel des Fensters im Fenstersystem.

Der Fenstertitel wird je nach Fenstersystem und Fensterflags möglicherweise im Titelbereich der Fensterdekoration angezeigt. Er kann vom Fenstersystem auch verwendet werden, um das Fenster in anderen Kontexten zu identifizieren, beispielsweise im Aufgabenumschalter.

transientParent : QWindow

Das Fenster, für das dieses Fenster ein vorübergehendes Popup-Fenster ist.

Dies ist ein Hinweis für den Fenstermanager, dass dieses Fenster ein Dialogfeld oder Popup im Auftrag des vorübergehenden übergeordneten Fensters ist. In der Regel bedeutet dies, dass das vorübergehende Fenster beim ersten Anzeigen über seinem vorübergehenden übergeordneten Fenster zentriert wird, dass das Minimieren des übergeordneten Fensters auch das Minimieren des vorübergehenden Fensters zur Folge hat und so weiter; die Ergebnisse variieren jedoch etwas von Plattform zu Plattform.

Wird ein Fenster innerhalb eines Elements oder eines anderen Fensters deklariert – entweder über die Methode „ default property “ oder eine spezielle Eigenschaft –, wird automatisch eine vorübergehende Eltern-Kind-Beziehung zum umschließenden Fenster hergestellt, sofern die Eigenschaft „transientParent“ nicht explizit festgelegt ist. Dies gilt auch beim Erstellen von Fenster-Elementen über „ Qt.createComponent “ oder „ Qt.createQmlObject “, sofern ein Element oder ein Fenster als Argument „ parent “ übergeben wird.

Ein „Window“ mit einem vorübergehenden übergeordneten Element wird erst angezeigt, wenn dessen vorübergehendes übergeordnetes Element angezeigt wird, selbst wenn die Eigenschaft „ visible “ auf „ true “ gesetzt ist. Dies gilt auch für die oben beschriebene automatische vorübergehende übergeordnete Beziehung. Insbesondere wenn das umschließende Element des Fensters ein „Item“ ist, wird das Fenster erst angezeigt, wenn das umschließende „Item“ über seine visuelle übergeordnete Hierarchie zu einer Szene hinzugefügt wurde. Durch Setzen von `transientParent` auf ` null ` wird dieses Verhalten außer Kraft gesetzt:

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

Damit das Fenster standardmäßig über seinem vorübergehenden übergeordneten Element zentriert wird, kann es je nach Fenstermanager außerdem erforderlich sein, die Eigenschaft „ Window::flags “ auf einen geeigneten „ Qt::WindowType “ (z. B. „ Qt::Dialog “) zu setzen.

Siehe auch parent().

visibility : QWindow::Visibility

Der Bildschirmbelegungsstatus des Fensters.

Die Sichtbarkeit gibt an, ob das Fenster im Fenstersystem als normal, minimiert, maximiert, im Vollbildmodus oder ausgeblendet angezeigt werden soll.

Die Sichtbarkeit auf „ AutomaticVisibility “ zu setzen, bedeutet, dem Fenster einen standardmäßigen sichtbaren Zustand zuzuweisen, der je nach Plattform „ FullScreen “ oder „ Windowed “ lauten kann. Beim Auslesen der Sichtbarkeitseigenschaft erhalten Sie jedoch immer den tatsächlichen Zustand, niemals „ AutomaticVisibility “.

Wenn ein Fenster nicht „ visible “ ist, lautet seine Sichtbarkeit „ Hidden “. Das Setzen der Sichtbarkeit auf „ Hidden “ entspricht dem Setzen von „ visible “ auf „ false “.

Der Standardwert lautet 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")
    }
}

Siehe auch visible und Qt Quick Beispiele – Fenster und Bildschirm.

visible : bool

Gibt an, ob das Fenster auf dem Bildschirm sichtbar ist.

Die Einstellung von „visible“ auf „false“ entspricht der Einstellung von „ visibility “ auf „ Hidden “.

Der Standardwert ist „ false “, sofern er nicht durch die Einstellung „ visibility “ überschrieben wird.

Siehe auch „ visibility “.

Dokumentation zu angehängten Eigenschaften

Window.active : bool [read-only attached]

Diese angehängte Eigenschaft gibt an, ob das Fenster aktiv ist. Die angehängte Eigenschaft „Window“ kann an jedes beliebige Element angehängt werden.

Hier ist ein Beispiel, das eine Beschriftung so ändert, dass sie den aktiven Status des Fensters anzeigt, in dem sie angezeigt wird:

import QtQuick

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

Window.activeFocusItem : Item [read-only attached]

Diese angehängte Eigenschaft enthält das Element, das derzeit den aktiven Fokus hat, oder „ null “, falls kein Element den aktiven Fokus hat. Die angehängte Eigenschaft „Window“ kann an jedes Element angehängt werden.

Window.contentItem : Item [read-only attached]

Diese angehängte Eigenschaft enthält das unsichtbare Stammelement der Szene oder „ null “, falls sich das Element nicht in einem Fenster befindet. Die angehängte Eigenschaft „Window“ kann an jedes beliebige Element angehängt werden.

Diese angehängten Eigenschaften enthalten die Größe des Fensters des Elements. Die angehängte Eigenschaft „Window“ kann an jedes Element angehängt werden.

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

Diese angehängte Eigenschaft gilt unabhängig davon, ob das Fenster derzeit im Fenstersystem als normal, minimiert, maximiert, im Vollbildmodus oder ausgeblendet angezeigt wird. Die angehängte Eigenschaft „ Window “ kann an jedes Element angehängt werden. Wenn das Element in keinem Fenster angezeigt wird, lautet der Wert „ Hidden “.

Siehe auch „ visible “ und „ visibility “.

Window.window : Window [attached]

Diese angehängte Eigenschaft enthält das Fenster des Elements. Die angehängte Eigenschaft „Window“ kann an jedes Element angehängt werden.

Signal-Dokumentation

afterAnimating()

Dieses Signal wird im GUI-Thread ausgesendet, bevor der Render-Thread aufgefordert wird, die Synchronisation des Szenengraphen durchzuführen.

Sie können die Methode „onAfterAnimating“ implementieren, um nach jedem Animationsschritt zusätzliche Verarbeitungsschritte durchzuführen.

closing(CloseEvent close)

Dieses Signal wird ausgelöst, wenn der Benutzer versucht, das Fenster zu schließen.

Dieses Signal enthält den Parameter „ close “. Die Eigenschaft „ close.accepted “ ist standardmäßig auf „true“ gesetzt, sodass das Fenster geschlossen werden darf; Sie können jedoch einen „ onClosing “-Handler implementieren und „ close.accepted = false “ setzen, falls Sie vor dem Schließen des Fensters noch etwas anderes tun müssen.

devicePixelRatioChanged()

frameSwapped()

Dieses Signal wird ausgegeben, wenn ein Frame zur Darstellung in die Warteschlange gestellt wurde. Bei aktivierter vertikaler Synchronisation wird das Signal in einer kontinuierlich animierten Szene höchstens einmal pro Vsync-Intervall ausgegeben.

sceneGraphError(SceneGraphError error, QString message)

Dieses Signal wird ausgelöst, wenn während der Initialisierung des Szenengraphen ein Fehler „ error “ aufgetreten ist.

Sie können `onSceneGraphError(error, message)` implementieren, um Fehler, wie z. B. Fehler beim Erstellen des Grafikkontexts, auf benutzerdefinierte Weise zu behandeln. Wenn kein Handler mit diesem Signal verbunden ist, gibt Quick den ` message` aus oder zeigt ein Meldungsfeld an und beendet die Anwendung.

Methodendokumentation

void alert(int msec)

Löst die Anzeige einer Warnmeldung für msec Millisekunden aus. Wenn msec auf „ 0 “ gesetzt ist (Standardeinstellung), wird die Warnmeldung so lange angezeigt, bis das Fenster wieder aktiv wird.

Im Warnzustand signalisiert das Fenster, dass es Aufmerksamkeit erfordert, beispielsweise durch Blinken oder Springen des Eintrags in der Taskleiste.

void close()

Schließt das Fenster.

Wenn diese Methode aufgerufen wird oder wenn der Benutzer versucht, das Fenster über die Schaltfläche in der Titelleiste zu schließen, wird das Signal „ closing “ ausgelöst. Wenn kein Handler vorhanden ist oder der Handler die Berechtigung zum Schließen nicht widerruft, wird das Fenster anschließend geschlossen. Wenn die Eigenschaft „ QGuiApplication::quitOnLastWindowClosed “ auf „ true “ gesetzt ist und keine anderen Fenster geöffnet sind, wird die Anwendung beendet.

void hide()

Blendet das Fenster aus.

Entspricht der Einstellung „ visible “ auf „ false “ oder „ visibility “ auf „ Hidden “.

Siehe auch show().

void lower()

Verschiebt das Fenster im Fenstersystem nach unten.

Fordert an, dass das Fenster so verschoben wird, dass es unterhalb anderer Fenster angezeigt wird.

void raise()

Hebt das Fenster im Fenstersystem an.

Fordert an, dass das Fenster so angehoben wird, dass es über anderen Fenstern angezeigt wird.

void requestActivate()

Fordert an, dass das Fenster aktiviert wird, d. h. den Tastaturfokus erhält.

void show()

Zeigt das Fenster an.

Dies entspricht dem Aufruf von ` showFullScreen()`, ` showMaximized()` oder ` showNormal()`, je nach dem Standardverhalten der Plattform für den Fenstertyp und die Flags.

Siehe auch showFullScreen(), showMaximized(), showNormal(), hide() und QQuickItem::flags().

void showFullScreen()

Zeigt das Fenster im Vollbildmodus an.

Entspricht der Einstellung von ` visibility ` auf ` FullScreen`.

void showMaximized()

Zeigt das Fenster in maximierter Darstellung an.

Entspricht der Einstellung von „ visibility “ auf „ Maximized “.

void showMinimized()

Zeigt das Fenster minimiert an.

Entspricht der Einstellung von „ visibility “ auf „ Minimized “.

void showNormal()

Zeigt das Fenster im normalen Modus an, d. h. weder maximiert, minimiert noch im Vollbildmodus.

Entspricht der Einstellung „ visibility “ auf „ Windowed “.

[since 6.8] void startSystemMove()

Startet einen systemabhängigen Verschiebevorgang.

Startet einen interaktiven Verschiebungsvorgang für das Fenster unter Nutzung der Plattformunterstützung. Das Fenster folgt dem Mauszeiger, bis die Maustaste losgelassen wird.

Verwenden Sie diese Methode anstelle von ` setPosition`, da sie es dem Fenstermanager ermöglicht, das Einrasten, das Kacheln und zugehörige Animationen zu verarbeiten. Unter Wayland wird ` setPosition ` nicht unterstützt, daher ist dies die einzige Möglichkeit für die Anwendung, die Position des Fensters zu beeinflussen.

Diese Methode wurde in Qt 6.8 eingeführt.

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

Startet einen systemspezifischen Vorgang zur Größenanpassung.

Startet einen interaktiven Größenänderungsvorgang für das Fenster unter Nutzung der Plattformunterstützung. Die angegebene Kante folgt beim Ziehen dem Mauszeiger.

Verwenden Sie diese Methode anstelle von ` setGeometry`, da sie es dem Fenstermanager ermöglicht, das Einrasten und Animationen bei der Größenänderung an den Bildschirmrändern zu handhaben.

edges Muss eine einzelne Kante oder eine Kombination aus zwei benachbarten Kanten (eine Ecke) sein. Andere Werte sind nicht zulässig.

Diese Methode wurde in Qt 6.8 eingeführt.