Control QML Type

Abstrakter Basistyp, der Funktionen bereitstellt, die allen Steuerelementen gemeinsam sind. Mehr...

• Liste aller Mitglieder, einschließlich geerbter Mitglieder

Eigenschaften

• availableHeight : real
• availableWidth : real
• background : Item
• bottomInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
• bottomPadding : real
• contentItem : Item
• focusReason : enumeration
• font : font
• horizontalPadding : real (since QtQuick.Controls 2.5 (Qt 5.12))
• hoverEnabled : bool
• hovered : bool
• implicitBackgroundHeight : real (since QtQuick.Controls 2.5 (Qt 5.12))
• implicitBackgroundWidth : real (since QtQuick.Controls 2.5 (Qt 5.12))
• implicitContentHeight : real (since QtQuick.Controls 2.5 (Qt 5.12))
• implicitContentWidth : real (since QtQuick.Controls 2.5 (Qt 5.12))
• leftInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
• leftPadding : real
• locale : Locale
• mirrored : bool
• padding : real
• rightInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
• rightPadding : real
• spacing : real
• topInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
• topPadding : real
• verticalPadding : real (since QtQuick.Controls 2.5 (Qt 5.12))
• visualFocus : bool
• wheelEnabled : bool

Ausführliche Beschreibung

Ein Steuerelement ist der Basistyp der Benutzeroberflächenelemente. Es empfängt Eingabeereignisse vom Fenstersystem und zeichnet eine Darstellung seiner selbst auf dem Bildschirm.

Aufbau eines Steuerelements

Das folgende Diagramm veranschaulicht das Layout eines typischen Steuerelements:

Die Eigenschaften „ implicitWidth “ und „ implicitHeight “ eines Steuerelements basieren in der Regel auf den impliziten Größen des Hintergrunds und des Inhaltselements zuzüglich etwaiger Einrückungen und Abstände. Diese Eigenschaften legen fest, wie groß das Steuerelement sein wird, wenn keine expliziten Werte für „ width “ oder „ height “ angegeben werden.

Die Geometrie des „ contentItem “ wird durch den Abstand („padding“) bestimmt. Das folgende Beispiel reserviert einen Abstand von 10px zwischen den Rändern des Steuerelements und seinem Inhalt:

Control {
    padding: 10

    contentItem: Text {
        text: "Content"
    }
}

Das „ background “-Element füllt die gesamte Breite und Höhe des Steuerelements aus, sofern keine „insets“ oder eine explizite Größe dafür angegeben wurden. Hintergrund-Insets sind nützlich, um den berührbaren/interaktiven Bereich eines Steuerelements zu vergrößern, ohne dessen visuelle Größe zu beeinflussen. Dies wird häufig auf Touch-Geräten verwendet, um sicherzustellen, dass ein Steuerelement nicht zu klein ist, um vom Benutzer bedient zu werden. Insets wirken sich auf die Größe des Steuerelements aus und beeinflussen somit beispielsweise, wie viel Platz es in einem Layout einnimmt.

Negative Einrückungen können verwendet werden, um den Hintergrund größer als das Steuerelement zu gestalten. Das folgende Beispiel nutzt negative Einrückungen, um einen Schatten außerhalb der Begrenzungen des Steuerelements zu platzieren:

Control {
    topInset: -2
    leftInset: -2
    rightInset: -6
    bottomInset: -6

    background: BorderImage {
        source: ":/images/shadowed-background.png"
    }
}

Ereignisbehandlung

Alle Steuerelemente – mit Ausnahme nicht-interaktiver Anzeigen – lassen Klicks und Berührungen nicht an darunterliegende Elemente weiterleiten. So wird beispielsweise der Aufruf von ` console.log() ` im folgenden Beispiel niemals ausgeführt, wenn auf das „Pane“ geklickt wird, da sich „ MouseArea “ in der Szene darunter befindet:

MouseArea {
    anchors.fill: parent
    onClicked: console.log("MouseArea was clicked")

    Pane {
        anchors.fill: parent
    }
}

Räder-Ereignisse werden von Steuerelementen abgefangen, wenn ` wheelEnabled ` auf ` true` gesetzt ist.

Siehe auch „ ApplicationWindow “, „ Container “ und Using Qt Quick Controls types in property declarations.

Dokumentation zu den Eigenschaften

availableHeight : real [read-only]

Diese Eigenschaft gibt die Höhe an, die dem „ contentItem “ zur Verfügung steht, nachdem der vertikale Abstand („ height “) des Steuerelements abgezogen wurde.

Siehe auch „ Control Layout“ , „ padding “, „ topPadding “ und „ bottomPadding “.

availableWidth : real [read-only]

Diese Eigenschaft gibt die Breite an, die dem „ contentItem “ zur Verfügung steht, nachdem der horizontale Abstand („ width “) des Steuerelements abgezogen wurde.

Siehe auch „ Control Layout“ , „ padding “, „ leftPadding “ und „ rightPadding “.

background : Item

Diese Eigenschaft enthält das Hintergrundelement.

Button {
    id: control
    text: qsTr("Button")
    background: Rectangle {
        implicitWidth: 100
        implicitHeight: 40
        opacity: enabled ? 1 : 0.3
        color: control.down ? "#d0d0d0" : "#e0e0e0"
    }
}

Siehe auch „ Control Layout “.

bottomInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]

Diese Eigenschaft legt den unteren Rand des Hintergrunds fest.

Diese Eigenschaft wurde in QtQuick.Controls 2.5 (Qt 5.12) eingeführt.

Siehe auch Control Layout und topInset.

bottomPadding : real

Diese Eigenschaft legt den unteren Abstand fest. Sofern nicht ausdrücklich festgelegt, entspricht der Wert „ verticalPadding “.

Siehe auch Control Layout, padding, topPadding, verticalPadding und availableHeight.

contentItem : Item

Diese Eigenschaft enthält das visuelle Inhaltselement.

Button {
    id: control
    text: qsTr("Button")
    contentItem: Label {
        text: control.text
        verticalAlignment: Text.AlignVCenter
    }
}

Siehe auch Control Layout und padding.

focusReason : enumeration

Diese Eigenschaft enthält den Grund für den letzten Fokuswechsel.

Der Wert dieser Eigenschaft wird von Qt bei jeder Fokusübertragung geändert, und Sie sollten diese Eigenschaft niemals selbst setzen müssen.

Siehe auch Item::activeFocus und visualFocus.

font : font

Diese Eigenschaft enthält die derzeit für das Steuerelement festgelegte Schriftart.

Diese Eigenschaft beschreibt die vom Steuerelement angeforderte Schriftart. Die Schriftart wird vom Stil des Steuerelements beim Rendern von Standardkomponenten verwendet und dient dazu, sicherzustellen, dass benutzerdefinierte Steuerelemente die Konsistenz mit dem nativen „Look and Feel“ der jeweiligen Plattform wahren können. Es ist üblich, dass verschiedene Plattformen oder verschiedene Stile unterschiedliche Schriftarten für eine Anwendung definieren.

Die Standardschriftart hängt von der Systemumgebung ab. ` ApplicationWindow ` verwaltet eine System-/Design-Schriftart, die als Standard für alle Steuerelemente dient. Für bestimmte Arten von Steuerelementen kann es zudem spezielle Standardschriftarten geben. Sie können die Standardschriftart für Steuerelemente auch wie folgt festlegen:

• eine benutzerdefinierte Schriftart an ` QGuiApplication::setFont()` übergeben, bevor das QML geladen wird; oder
• die Schriftarten in der Datei `qtquickcontrols2.conf` festlegen.

Abschließend wird die Schriftart mit der Qt-Schriftartendatenbank abgeglichen, um die beste Übereinstimmung zu finden.

Das Steuerelement gibt explizite Schriftarteneigenschaften vom übergeordneten Element an untergeordnete Elemente weiter. Wenn Sie eine bestimmte Eigenschaft der Schriftart eines Steuerelements ändern, wird diese Eigenschaft an alle untergeordneten Elemente des Steuerelements weitergegeben und überschreibt dabei alle Systemstandards für diese Eigenschaft.

Page {
    font.family: "Courier"

    Column {
        Label {
            text: qsTr("This will use Courier...")
        }

        Switch {
            text: qsTr("... and so will this")
        }
    }
}

Eine vollständige Liste der verfügbaren Schriftarteneigenschaften finden Sie in der Dokumentation zu „ font QML Value Type “.

horizontalPadding : real [since QtQuick.Controls 2.5 (Qt 5.12)]

Diese Eigenschaft legt den horizontalen Abstand fest. Sofern nicht explizit festgelegt, entspricht der Wert „ padding “.

Diese Eigenschaft wurde in QtQuick.Controls 2.5 (Qt 5.12) eingeführt.

Siehe auch „ Control Layout“ , „ padding “, „ leftPadding “, „ rightPadding “ und „ verticalPadding “.

hoverEnabled : bool

Diese Eigenschaft legt fest, ob das Steuerelement Hover-Ereignisse akzeptiert. Der Standardwert ist „ Application.styleHints.useHoverEffects “.

Durch das Setzen dieser Eigenschaft wird der Wert an alle untergeordneten Steuerelemente weitergegeben, für die „ hoverEnabled “ nicht explizit festgelegt ist.

Sie können Hover-Effekte für alle „ Qt Quick Controls “-Anwendungen auch aktivieren oder deaktivieren, indem Sie die Umgebungsvariable „ QT_QUICK_CONTROLS_HOVER_ENABLED “ setzen.

Siehe auch „ hovered “.

hovered : bool [read-only]

Diese Eigenschaft gibt an, ob der Mauszeiger über dem Steuerelement schwebt.

Siehe auch hoverEnabled.

implicitBackgroundHeight : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

Diese Eigenschaft enthält die implizite Hintergrundhöhe.

Der Wert entspricht „ background ? background.implicitHeight : 0 “.

Sie wird typischerweise zusammen mit ` implicitContentHeight` verwendet, um die ` implicitHeight` zu berechnen:

Control {
    implicitHeight: Math.max(implicitBackgroundHeight + topInset + bottomInset,
                             implicitContentHeight + topPadding + bottomPadding)
}

Diese Eigenschaft wurde in QtQuick.Controls 2.5 (Qt 5.12) eingeführt.

Siehe auch „ implicitBackgroundWidth “ und „ implicitContentHeight “.

implicitBackgroundWidth : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

Diese Eigenschaft enthält die implizite Hintergrundbreite.

Der Wert entspricht „ background ? background.implicitWidth : 0 “.

Sie wird typischerweise zusammen mit ` implicitContentWidth` verwendet, um die ` implicitWidth` zu berechnen:

Control {
    implicitWidth: Math.max(implicitBackgroundWidth + leftInset + rightInset,
                            implicitContentWidth + leftPadding + rightPadding)
}

Diese Eigenschaft wurde in QtQuick.Controls 2.5 (Qt 5.12) eingeführt.

Siehe auch „ implicitBackgroundHeight “ und „ implicitContentWidth “.

implicitContentHeight : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

Diese Eigenschaft enthält die implizite Höhe des Inhalts.

Bei einfachen Steuerelementen entspricht der Wert dem Wert von „ contentItem ? contentItem.implicitHeight : 0 “. Bei Typen, die von „Container“ oder „Pane“ erben, wird der Wert auf der Grundlage der untergeordneten Inhaltselemente berechnet.

Dies wird typischerweise zusammen mit ` implicitBackgroundHeight` verwendet, um die ` implicitHeight` zu berechnen:

Control {
    implicitHeight: Math.max(implicitBackgroundHeight + topInset + bottomInset,
                             implicitContentHeight + topPadding + bottomPadding)
}

Diese Eigenschaft wurde in QtQuick.Controls 2.5 (Qt 5.12) eingeführt.

Siehe auch „ implicitContentWidth “ und „ implicitBackgroundHeight “.

implicitContentWidth : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

Diese Eigenschaft enthält die implizite Breite des Inhalts.

Bei einfachen Steuerelementen entspricht der Wert dem Wert von „ contentItem ? contentItem.implicitWidth : 0 “. Bei Typen, die von „Container“ oder „Pane“ erben, wird der Wert auf der Grundlage der untergeordneten Inhaltselemente berechnet.

Dies wird typischerweise zusammen mit „ implicitBackgroundWidth “ verwendet, um die „ implicitWidth “ zu berechnen:

Control {
    implicitWidth: Math.max(implicitBackgroundWidth + leftInset + rightInset,
                            implicitContentWidth + leftPadding + rightPadding)
}

Diese Eigenschaft wurde in QtQuick.Controls 2.5 (Qt 5.12) eingeführt.

Siehe auch „ implicitContentHeight “ und „ implicitBackgroundWidth “.

leftInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]

Diese Eigenschaft legt den linken Rand des Hintergrunds fest.

Diese Eigenschaft wurde in QtQuick.Controls 2.5 (Qt 5.12) eingeführt.

Siehe auch Control Layout und rightInset.

leftPadding : real

Diese Eigenschaft legt den linken Abstand fest. Sofern nicht ausdrücklich festgelegt, entspricht der Wert „ horizontalPadding “.

Siehe auch Control Layout, padding, rightPadding, horizontalPadding und availableWidth.

locale : Locale

Diese Eigenschaft enthält die Locale des Steuerelements.

Sie enthält lokalisierungsspezifische Eigenschaften zur Formatierung von Daten und Zahlen. Sofern keine spezielle Lokalisierung festgelegt wurde, handelt es sich dabei entweder um die Lokalisierung des übergeordneten Elements oder um die Standardlokalisierung.

Das Steuerelement gibt die Ländereinstellung vom übergeordneten Element an die untergeordneten Elemente weiter. Wenn Sie die Ländereinstellung des Steuerelements ändern, wird diese an alle untergeordneten Elemente des Steuerelements weitergegeben und überschreibt dabei die Standard-Ländereinstellung des Systems.

Siehe auch „ mirrored “.

mirrored : bool [read-only]

Diese Eigenschaft gibt an, ob das Steuerelement gespiegelt ist.

Diese Eigenschaft dient der Benutzerfreundlichkeit. Ein Steuerelement gilt als gespiegelt, wenn seine visuelle Ausrichtungsrichtung von rechts nach links verläuft, d. h., wenn „ LayoutMirroring.enabled “ auf „ true “ gesetzt ist.

Ab Qt 6.2 hat die Eigenschaft ` locale ` keinen Einfluss mehr auf diese Eigenschaft.

Siehe auch „ LayoutMirroring “ und „Benutzeroberflächen von rechts nach links“.

padding : real

Diese Eigenschaft legt den Standard-Abstand fest.

Der Abstand schafft einen Freiraum zwischen jeder Kante des Inhaltselements und dem Hintergrundelement und bestimmt so effektiv die Größe des Inhaltselements. Um einen Abstandwert für eine bestimmte Kante des Steuerelements festzulegen, setzen Sie die entsprechende Eigenschaft:

• leftPadding
• rightPadding
• topPadding
• bottomPadding

padding: 0

sollten Sie stattdessen die jeweiligen spezifischen Eigenschaften festlegen:

leftPadding: 0
rightPadding: 0
topPadding: 0
bottomPadding: 0

Siehe auch Control Layout, availableWidth, availableHeight, topPadding, leftPadding, rightPadding und bottomPadding.

rightInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]

Diese Eigenschaft legt den rechten Abstand zum Hintergrund fest.

Diese Eigenschaft wurde in QtQuick.Controls 2.5 (Qt 5.12) eingeführt.

Siehe auch Control Layout und leftInset.

rightPadding : real

Diese Eigenschaft legt den richtigen Abstand fest. Sofern nicht ausdrücklich festgelegt, entspricht der Wert „ horizontalPadding “.

Siehe auch Control Layout, padding, leftPadding, horizontalPadding und availableWidth.

spacing : real

Diese Eigenschaft legt den Abstand fest.

Der Abstand ist nützlich für Steuerelemente, die mehrere oder sich wiederholende Bausteine enthalten. Beispielsweise verwenden einige Stile den Abstand, um den Abstand zwischen dem Text und der Anzeige von „ CheckBox “ festzulegen. Der Abstand wird von „Control“ nicht erzwungen, sodass jeder Stil ihn unterschiedlich interpretieren kann und manche ihn möglicherweise gänzlich ignorieren.

topInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]

Diese Eigenschaft legt den oberen Rand des Hintergrunds fest.

Diese Eigenschaft wurde in QtQuick.Controls 2.5 (Qt 5.12) eingeführt.

Siehe auch Control Layout und bottomInset.

topPadding : real

Diese Eigenschaft legt den oberen Abstand fest. Sofern nicht explizit festgelegt, entspricht der Wert „ verticalPadding “.

Siehe auch Control Layout, padding, bottomPadding, verticalPadding und availableHeight.

verticalPadding : real [since QtQuick.Controls 2.5 (Qt 5.12)]

Diese Eigenschaft legt den vertikalen Abstand fest. Sofern nicht explizit festgelegt, entspricht der Wert dem Wert „ padding “.

Diese Eigenschaft wurde in QtQuick.Controls 2.5 (Qt 5.12) eingeführt.

Siehe auch „ Control Layout“ , „ padding “, „ topPadding “, „ bottomPadding “ und „ horizontalPadding “.

visualFocus : bool [read-only]

Diese Eigenschaft gibt an, ob das Steuerelement den visuellen Fokus hat. Diese Eigenschaft ist „ true “, wenn das Steuerelement den aktiven Fokus hat und der Fokusgrund entweder „ Qt.TabFocusReason “, „ Qt.BacktabFocusReason “ oder „ Qt.ShortcutFocusReason “ ist.

Im Allgemeinen wird diese Eigenschaft zur Visualisierung des Tastenfokus gegenüber „ Item::activeFocus “ bevorzugt. Dadurch wird sichergestellt, dass der Tastenfokus nur bei der Interaktion mit Tasten visualisiert wird – nicht jedoch bei der Interaktion per Touch oder Maus.

Siehe auch „ focusReason “ und „ Item::activeFocus “.

wheelEnabled : bool

Diese Eigenschaft legt fest, ob das Steuerelement Mausrad-Ereignisse verarbeitet. Der Standardwert lautet „ false “.