ScrollBar QML Type

Vertikale oder horizontale interaktive Bildlaufleiste. Mehr...

• Liste aller Elemente, einschließlich geerbter Elemente

Eigenschaften

• active : bool
• horizontal : bool (since QtQuick.Controls 2.3 (Qt 5.10))
• interactive : bool (since QtQuick.Controls 2.2 (Qt 5.9))
• minimumSize : real (since QtQuick.Controls 2.4 (Qt 5.11))
• orientation : enumeration
• policy : enumeration (since QtQuick.Controls 2.2 (Qt 5.9))
• position : real
• pressed : bool
• size : real
• snapMode : enumeration (since QtQuick.Controls 2.2 (Qt 5.9))
• stepSize : real
• vertical : bool (since QtQuick.Controls 2.3 (Qt 5.10))
• visualPosition : real (since QtQuick.Controls 2.4 (Qt 5.11))
• visualSize : real (since QtQuick.Controls 2.4 (Qt 5.11))

Zugehörige Eigenschaften

• horizontal : ScrollBar
• vertical : ScrollBar

Methoden

• void decrease()
• void increase()

Ausführliche Beschreibung

„ScrollBar“ ist eine interaktive Leiste, mit der man zu einer bestimmten Position scrollen kann. Eine Scrollleiste kann entweder „ vertical “ oder „ horizontal “ sein und an jedes „ Flickable “ angehängt werden, wie beispielsweise „ ListView “ und „ GridView “. Sie kann auch mit „ ScrollView “ verwendet werden.

Flickable {
    // ...
    ScrollBar.vertical: ScrollBar { }
}

Anbringen einer ScrollBar an einem Flickable

Wenn eine ScrollBar über vertically oder horizontally an ein „Flickable“ angehängt wird, werden ihre Geometrie und die folgenden Eigenschaften automatisch entsprechend festgelegt und aktualisiert:

• orientation
• position
• size
• active

Ein angehängtes ScrollBar ordnet sich dem Ziel-Flickable als untergeordnetes Element zu. Ein vertikal angehängtes ScrollBar passt seine Größe an die Höhe des Flickable an und positioniert sich basierend auf dem „ layout direction “ auf einer der beiden Seiten davon. Ein horizontal angehängtes ScrollBar passt seine Größe an die Breite des Flickable an und positioniert sich am unteren Rand. Die automatische Geometrieverwaltung kann deaktiviert werden, indem ein anderes übergeordnetes Element für die angehängte ScrollBar angegeben wird. Dies kann beispielsweise nützlich sein, wenn die ScrollBar außerhalb eines beschneidenden Flickable platziert werden soll. Dies wird im folgenden Beispiel veranschaulicht:

Flickable {
    id: flickable
    clip: true
    // ...
    ScrollBar.vertical: ScrollBar {
        parent: flickable.parent
        anchors.top: flickable.top
        anchors.left: flickable.right
        anchors.bottom: flickable.bottom
    }
}

Beachten Sie, dass die ScrollBar keine Tastenereignisse des Flickable filtert, an das sie angehängt ist. Das folgende Beispiel veranschaulicht, wie das Scrollen mit den Auf- und Ab-Tasten implementiert wird:

Flickable {
    focus: true

    Keys.onUpPressed: scrollBar.decrease()
    Keys.onDownPressed: scrollBar.increase()

    ScrollBar.vertical: ScrollBar { id: scrollBar }
}

Verknüpfung des aktiven Zustands von horizontalen und vertikalen Bildlaufleisten

Horizontale und vertikale Bildlaufleisten teilen sich standardmäßig nicht den „ active “-Zustand untereinander. Um beide Leisten beim Scrollen in beide Richtungen sichtbar zu halten, richten Sie eine bidirektionale Bindung zwischen den aktiven Zuständen ein, wie im folgenden Beispiel dargestellt:

Flickable {
    anchors.fill: parent

    contentWidth: parent.width * 2
    contentHeight: parent.height * 2

    ScrollBar.horizontal: ScrollBar { id: hbar; active: vbar.active }
    ScrollBar.vertical: ScrollBar { id: vbar; active: hbar.active }
}

Nicht angehängte Bildlaufleisten

Es ist möglich, eine Instanz von `ScrollBar` zu erstellen, ohne die „attached“-Eigenschafts-API zu verwenden. Dies ist nützlich, wenn das Verhalten der angehängten Bildlaufleiste nicht ausreicht oder „ Flickable “ nicht verwendet wird. Im folgenden Beispiel werden horizontale und vertikale Bildlaufleisten verwendet, um über den Text zu scrollen, ohne „ Flickable “ zu verwenden:

Rectangle {
    id: frame
    clip: true
    width: 160
    height: 160
    border.color: "black"
    anchors.centerIn: parent

    Text {
        id: content
        text: "ABC"
        font.pixelSize: 160
        x: -hbar.position * width
        y: -vbar.position * height
    }

    ScrollBar {
        id: vbar
        hoverEnabled: true
        active: hovered || pressed
        orientation: Qt.Vertical
        size: frame.height / content.height
        anchors.top: parent.top
        anchors.right: parent.right
        anchors.bottom: parent.bottom
    }

    ScrollBar {
        id: hbar
        hoverEnabled: true
        active: hovered || pressed
        orientation: Qt.Horizontal
        size: frame.width / content.width
        anchors.left: parent.left
        anchors.right: parent.right
        anchors.bottom: parent.bottom
    }
}

Bei Verwendung einer nicht angehängten ScrollBar müssen die folgenden Schritte manuell durchgeführt werden:

• Die Scrollleiste anordnen (beispielsweise mit den Eigenschaften „ x “, „ y “ oder „ anchors “).
• Legen Sie die Eigenschaften „ size “ und „ position “ fest, um Größe und Position der Bildlaufleiste in Bezug auf das gescrollte Element zu bestimmen.
• Legen Sie die Eigenschaft „ active “ fest, um zu bestimmen, wann die Bildlaufleiste sichtbar ist.

Unterschiedliche Delegate-Größen

Variierende Delegate-Größen können dazu führen, dass die ScrollBar „herumspringt“, wenn neue Delegates in die Ansicht geladen werden. Aus diesem Grund wird empfohlen, Delegates gleicher Größe zu verwenden. Weitere Informationen finden Sie unter „ Variable Delegate Size and Section Labels “.

Siehe auch „ ScrollIndicator“ , „ ScrollView “, „Anpassen der ScrollBar“ und „Anzeigesteuerelemente“.

Dokumentation zu den Eigenschaften

active : bool

Diese Eigenschaft gilt unabhängig davon, ob die Bildlaufleiste aktiv ist, d. h. ob sie „ pressed “ ist oder das angehängte „Flickable“ den Status „ moving “ hat.

Es ist möglich, „ both horizontal and vertical bars visible “ beizubehalten, während in beide Richtungen gescrollt wird.

Diese Eigenschaft wird automatisch gesetzt, wenn die Bildlaufleiste auf „ attached to a flickable “ steht.

horizontal : bool [read-only, since QtQuick.Controls 2.3 (Qt 5.10)]

Diese Eigenschaft gibt an, ob die Bildlaufleiste horizontal ist.

Diese Eigenschaft wurde in QtQuick.Controls 2.3 (Qt 5.10) eingeführt.

Siehe auch orientation.

interactive : bool [since QtQuick.Controls 2.2 (Qt 5.9)]

Diese Eigenschaft gibt an, ob die Bildlaufleiste interaktiv ist. Der Standardwert ist „ true “.

Eine nicht-interaktive Bildlaufleiste ähnelt optisch und vom Verhalten her „ ScrollIndicator “. Diese Eigenschaft ist nützlich, um zwischen typischen maus- und touch-orientierten Benutzeroberflächen mit interaktiven bzw. nicht-interaktiven Bildlaufleisten zu wechseln.

Diese Eigenschaft wurde in QtQuick.Controls 2.2 (Qt 5.9) eingeführt.

minimumSize : real [since QtQuick.Controls 2.4 (Qt 5.11)]

Diese Eigenschaft gibt die Mindestgröße der Bildlaufleiste an, skaliert auf 0.0 - 1.0.

Diese Eigenschaft wurde in QtQuick.Controls 2.4 (Qt 5.11) eingeführt.

Siehe auch „ size “, „ visualSize “ und „ visualPosition “.

orientation : enumeration

Diese Eigenschaft legt die Ausrichtung der Bildlaufleiste fest.

Mögliche Werte:

Diese Eigenschaft wird automatisch festgelegt, wenn die Bildlaufleiste auf „ attached to a flickable “ gesetzt ist.

Siehe auch „ horizontal “ und „ vertical “.

policy : enumeration [since QtQuick.Controls 2.2 (Qt 5.9)]

Diese Eigenschaft legt die Richtlinie für die Bildlaufleiste fest. Die Standardrichtlinie lautet „ ScrollBar.AsNeeded “.

Mögliche Werte:

Im folgenden Beispiel bleibt die vertikale Bildlaufleiste immer sichtbar:

Flickable {
    contentHeight: 2000
    ScrollBar.vertical: ScrollBar {
        policy: ScrollBar.AlwaysOn
    }
}

Stile können diese Eigenschaft in Kombination mit der Eigenschaft „ active “ verwenden, um vorübergehende Bildlaufleisten zu implementieren. Temporäre Bildlaufleisten werden kurz nach dem letzten Interaktionsereignis (Mauszeiger-Überfahrt oder Klick) ausgeblendet. Dies geschieht in der Regel durch eine Animation der Deckkraft der Bildlaufleiste. Um dieses Verhalten zu überschreiben, setzen Sie die Richtlinie je nach Größe des Inhalts im Verhältnis zur Ansicht auf „ ScrollBar.AlwaysOn “ oder „ ScrollBar.AlwaysOff “. Beispiel für eine vertikale Bildlaufleiste ( ListView):

policy: listView.contentHeight > listView.height ? ScrollBar.AlwaysOn : ScrollBar.AlwaysOff

Diese Eigenschaft wurde in QtQuick.Controls 2.2 (Qt 5.9) eingeführt.

position : real

Diese Eigenschaft enthält die Position der Bildlaufleiste, skaliert auf 0.0 - 1.0.

Die größte zulässige Position der Bildlaufleiste ist (1.0 - size). Dies sorgt für ein korrektes Verhalten im häufigsten Anwendungsfall, bei dem das Verschieben der Bildlaufleiste an das Ende dazu führt, dass sich das Ende des Dokuments am unteren Rand des sichtbaren Bereichs des verbundenen Flickable befindet.

Diese Eigenschaft wird automatisch gesetzt, wenn die Bildlaufleiste auf „ attached to a flickable “ gesetzt ist.

Siehe auch „ Flickable::visibleArea “ und „ visualPosition “.

pressed : bool

Diese Eigenschaft gibt an, ob die Bildlaufleiste gedrückt ist.

size : real

Diese Eigenschaft gibt die Größe der Bildlaufleiste an, skaliert auf 0.0 - 1.0.

Diese Eigenschaft wird automatisch gesetzt, wenn die Bildlaufleiste auf „ attached to a flickable “ gesetzt ist.

Siehe auch „ Flickable::visibleArea “, „ minimumSize “ und „ visualSize “.

snapMode : enumeration [since QtQuick.Controls 2.2 (Qt 5.9)]

Diese Eigenschaft legt den Snap-Modus fest.

Mögliche Werte:

In der folgenden Tabelle werden die verschiedenen Modi anhand von Animationen veranschaulicht. Die Bewegung und die „ stepSize “ (0.25) sind in jeder Animation identisch.

Wert	Beispiel
ScrollBar.NoSnap
ScrollBar.SnapAlways
ScrollBar.SnapOnRelease

Diese Eigenschaft wurde in QtQuick.Controls 2.2 (Qt 5.9) eingeführt.

Siehe auch „ stepSize “.

stepSize : real

Diese Eigenschaft gibt die Schrittweite an. Der Standardwert lautet „ 0.0 “.

Siehe auch „ snapMode“ , „ increase()“ und „ decrease()“.

vertical : bool [read-only, since QtQuick.Controls 2.3 (Qt 5.10)]

Diese Eigenschaft gibt an, ob die Bildlaufleiste vertikal ist.

Diese Eigenschaft wurde in QtQuick.Controls 2.3 (Qt 5.10) eingeführt.

Siehe auch orientation.

visualPosition : real [read-only, since QtQuick.Controls 2.4 (Qt 5.11)]

Diese Eigenschaft enthält die effektive visuelle Position der Bildlaufleiste, die durch die Eigenschaft „ minimum size “ begrenzt sein kann.

Diese Eigenschaft wurde in QtQuick.Controls 2.4 (Qt 5.11) eingeführt.

Siehe auch „ position “ und „ minimumSize “.

visualSize : real [read-only, since QtQuick.Controls 2.4 (Qt 5.11)]

Diese Eigenschaft enthält die effektive visuelle Größe der Bildlaufleiste, die durch die Eigenschaft „ minimum size “ begrenzt sein kann.

Diese Eigenschaft wurde in QtQuick.Controls 2.4 (Qt 5.11) eingeführt.

Siehe auch „ size “ und „ minimumSize “.

Dokumentation zu angehängten Eigenschaften

ScrollBar.horizontal : ScrollBar [attached]

Diese Eigenschaft fügt einem „ Flickable “ eine horizontale Bildlaufleiste hinzu.

Flickable {
    contentWidth: 2000
    ScrollBar.horizontal: ScrollBar { }
}

Siehe auch „ Attaching ScrollBar to a Flickable “.

ScrollBar.vertical : ScrollBar [attached]

Diese Eigenschaft fügt einem „ Flickable “ eine vertikale Bildlaufleiste hinzu.

Flickable {
    contentHeight: 2000
    ScrollBar.vertical: ScrollBar { }
}

Siehe auch „ Attaching ScrollBar to a Flickable “.

Methodendokumentation

void decrease()

Verringert die Position um stepSize oder 0.1, wenn stepSize gleich 0.0 ist.

Siehe auch stepSize.

void increase()

Erhöht die Position um stepSize oder 0.1, wenn stepSize gleich 0.0 ist.

Siehe auch stepSize.