ScrollBar QML Type

Vertical or horizontal interactive scroll bar. More...

• List of all members, including inherited members

Properties

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

Attached Properties

• horizontal : ScrollBar
• vertical : ScrollBar

Methods

• void decrease()
• void increase()

Detailed Description

ScrollBar is an interactive bar that can be used to scroll to a specific position. A scroll bar can be either vertical or horizontal, and can be attached to any Flickable, such as ListView and GridView. It can also be used with ScrollView.

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

Attaching ScrollBar to a Flickable

When ScrollBar is attached vertically or horizontally to a Flickable, its geometry and the following properties are automatically set and updated as appropriate:

• orientation
• position
• size
• active

An attached ScrollBar re-parents itself to the target Flickable. A vertically attached ScrollBar resizes itself to the height of the Flickable, and positions itself to either side of it based on the layout direction. A horizontally attached ScrollBar resizes itself to the width of the Flickable, and positions itself to the bottom. The automatic geometry management can be disabled by specifying another parent for the attached ScrollBar. This can be useful, for example, if the ScrollBar should be placed outside a clipping Flickable. This is demonstrated by the following example:

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

Notice that ScrollBar does not filter key events of the Flickable it is attached to. The following example illustrates how to implement scrolling with up and down keys:

 Flickable {
     focus: true

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

     ScrollBar.vertical: ScrollBar { id: scrollBar }
 }

Binding the Active State of Horizontal and Vertical Scroll Bars

Horizontal and vertical scroll bars do not share the active state with each other by default. In order to keep both bars visible whilst scrolling to either direction, establish a two-way binding between the active states as presented by the following example:

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

Non-attached Scroll Bars

It is possible to create an instance of ScrollBar without using the attached property API. This is useful when the behavior of the attached scroll bar is not sufficient or a Flickable is not in use. In the following example, horizontal and vertical scroll bars are used to scroll over the text without using Flickable:

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

When using a non-attached ScrollBar, the following must be done manually:

• Layout the scroll bar (with the x and y or anchors property, for example).
• Set the size and position properties to determine the size and position of the scroll bar in relation to the scrolled item.
• Set the active property to determine when the scroll bar will be visible.

See also ScrollIndicator, ScrollView, Customizing ScrollBar, and Indicator Controls.

Property Documentation

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

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

Attached Property Documentation

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

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

Method Documentation