ScrollBar QML Type

Barre de défilement interactive verticale ou horizontale. Plus d'informations...

• Liste de tous les membres, y compris les membres hérités

Propriétés

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

Propriétés rattachées

• horizontal : ScrollBar
• vertical : ScrollBar

Méthodes

• void decrease()
• void increase()

Description détaillée

ScrollBar est une barre interactive qui peut être utilisée pour défiler jusqu'à une position spécifique. Une barre de défilement peut être vertical ou horizontal, et peut être attachée à n'importe quel Flickable, comme ListView et GridView. Elle peut également être utilisée avec ScrollView.

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

Attacher une barre de défilement à un Flickable

Lorsqu'une barre de défilement est attachée vertically ou horizontally à un Flickable, sa géométrie et les propriétés suivantes sont automatiquement définies et mises à jour en fonction des besoins :

• orientation
• position
• size
• active

Une barre de défilement attachée se réoriente vers le Flickable cible. Une barre de défilement attachée verticalement se redimensionne à la hauteur du Flickable et se positionne d'un côté ou de l'autre de celui-ci en fonction de layout direction. Une barre de défilement attachée horizontalement se redimensionne à la largeur du Flickable et se positionne en bas. La gestion automatique de la géométrie peut être désactivée en spécifiant un autre parent pour la barre de défilement attachée. Cela peut s'avérer utile, par exemple, si la barre de défilement doit être placée en dehors d'un Flickable qui s'écrase. L'exemple suivant le démontre :

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

Remarquez que la barre de défilement ne filtre pas les événements de touche du Flickable auquel elle est attachée. L'exemple suivant illustre comment mettre en œuvre le défilement avec les touches haut et bas :

Flickable {
    focus: true

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

    ScrollBar.vertical: ScrollBar { id: scrollBar }
}

Lier l'état actif des barres de défilement horizontales et verticales

Par défaut, les barres de défilement horizontales et verticales ne partagent pas l'état active. Pour que les deux barres restent visibles lors d'un défilement dans l'une ou l'autre direction, il convient d'établir une liaison bidirectionnelle entre les états actifs, comme le montre l'exemple suivant :

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

Barres de défilement non attachées

Il est possible de créer une instance de ScrollBar sans utiliser l'API des propriétés attachées. Cela est utile lorsque le comportement de la barre de défilement attachée n'est pas suffisant ou qu'une page Flickable n'est pas utilisée. Dans l'exemple suivant, des barres de défilement horizontales et verticales sont utilisées pour faire défiler le texte sans utiliser 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
    }
}

Lors de l'utilisation d'une barre de défilement non attachée, les opérations suivantes doivent être effectuées manuellement :

• Disposer la barre de défilement (avec les propriétés x et y ou anchors, par exemple).
• Définir les propriétés size et position pour déterminer la taille et la position de la barre de défilement par rapport à l'élément à faire défiler.
• La propriété active permet de déterminer quand la barre de défilement sera visible.

Variations de la taille des délégués

Des délégués de taille variable peuvent conduire la barre de défilement à "sauter" lorsque de nouveaux délégués sont chargés dans la vue. Pour cette raison, il est recommandé d'avoir des délégués de taille égale. Voir Variable Delegate Size and Section Labels pour plus d'informations.

Voir également ScrollIndicator, ScrollView, Personnaliser la barre de défilement et les contrôles d'indicateur.

Documentation sur les propriétés

active : bool

Cette propriété indique si la barre de défilement est active, c'est-à-dire si elle est pressed ou si le Flickable attaché est moving.

Il est possible de conserver both horizontal and vertical bars visible tout en faisant défiler dans l'une ou l'autre direction.

Cette propriété est automatiquement définie lorsque la barre de défilement est attached to a flickable.

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

Cette propriété indique si la barre de défilement est horizontale.

Cette propriété a été introduite dans QtQuick.Controls 2.3 (Qt 5.10).

Voir aussi orientation.

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

Cette propriété indique si la barre de défilement est interactive. La valeur par défaut est true.

Une barre de défilement non interactive est visuellement et comportementalement similaire à ScrollIndicator. Cette propriété est utile pour basculer entre les interfaces utilisateur typiques orientées vers la souris et le toucher avec des barres de défilement interactives et non interactives, respectivement.

Cette propriété a été introduite dans QtQuick.Controls 2.2 (Qt 5.9).

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

Cette propriété définit la taille minimale de la barre de défilement, à l'échelle de 0.0 - 1.0.

Cette propriété a été introduite dans QtQuick.Controls 2.4 (Qt 5.11).

Voir aussi size, visualSize, et visualPosition.

orientation : enumeration

Cette propriété définit l'orientation de la barre de défilement.

Valeurs possibles :

Cette propriété est automatiquement définie lorsque la barre de défilement est attached to a flickable.

Voir également horizontal et vertical.

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

Cette propriété contient la politique de la barre de défilement. La politique par défaut est ScrollBar.AsNeeded.

Valeurs possibles :

Dans l'exemple suivant, la barre de défilement verticale est toujours visible :

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

Les styles peuvent utiliser cette propriété en combinaison avec la propriété active afin d'implémenter des barres de défilement transitoires. Les barres de défilement transitoires sont masquées peu après le dernier événement d'interaction (survol ou pression). Pour ce faire, l'opacité de la barre de défilement est généralement animée. Pour remplacer ce comportement, définissez la politique sur ScrollBar.AlwaysOn ou ScrollBar.AlwaysOff, en fonction de la taille du contenu par rapport à sa vue. Par exemple, pour un contenu vertical ListView:

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

Cette propriété a été introduite dans QtQuick.Controls 2.2 (Qt 5.9).

position : real

Cette propriété contient la position de la barre de défilement, mise à l'échelle sur 0.0 - 1.0.

La plus grande position valide de la barre de défilement est (1.0 - size). Cela permet d'obtenir un comportement correct dans le cas le plus fréquent où le déplacement de la barre de défilement jusqu'à la fin place la fin du document à l'extrémité inférieure de la zone visible du Flickable connecté.

Cette propriété est automatiquement définie lorsque la barre de défilement est attached to a flickable.

Voir également Flickable::visibleArea et visualPosition.

pressed : bool

Cette propriété indique si la barre de défilement est enfoncée.

size : real

Cette propriété contient la taille de la barre de défilement, mise à l'échelle sur 0.0 - 1.0.

Cette propriété est automatiquement définie lorsque la barre de défilement est attached to a flickable.

Voir également Flickable::visibleArea, minimumSize, et visualSize.

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

Cette propriété définit le mode d'accrochage.

Valeurs possibles :

Dans le tableau suivant, les différents modes sont illustrés par des animations. Le mouvement et le site stepSize (0.25) sont identiques dans chaque animation.

Valeur	Exemple
ScrollBar.NoSnap
ScrollBar.SnapAlways
ScrollBar.SnapOnRelease

Cette propriété a été introduite dans QtQuick.Controls 2.2 (Qt 5.9).

Voir également stepSize.

stepSize : real

Cette propriété définit la taille du pas. La valeur par défaut est 0.0.

Voir également snapMode, increase() et decrease().

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

Cette propriété indique si la barre de défilement est verticale.

Cette propriété a été introduite dans QtQuick.Controls 2.3 (Qt 5.10).

Voir aussi orientation.

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

Cette propriété définit la position visuelle effective de la barre de défilement, qui peut être limitée par l'adresse minimum size.

Cette propriété a été introduite dans QtQuick.Controls 2.4 (Qt 5.11).

Voir également position et minimumSize.

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

Cette propriété définit la taille visuelle effective de la barre de défilement, qui peut être limitée par la page minimum size.

Cette propriété a été introduite dans QtQuick.Controls 2.4 (Qt 5.11).

Voir également size et minimumSize.

Documentation sur la propriété Attached

ScrollBar.horizontal : ScrollBar

Cette propriété permet d'attacher une barre de défilement horizontale à un site Flickable.

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

Voir aussi Attaching ScrollBar to a Flickable.

ScrollBar.vertical : ScrollBar

Cette propriété permet d'attacher une barre de défilement verticale à un site Flickable.

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

Voir aussi Attaching ScrollBar to a Flickable.

Documentation de la méthode

void decrease()

Diminue la position de stepSize ou 0.1 si stepSize est 0.0.

Voir aussi stepSize.

void increase()

Augmente la position de stepSize ou 0.1 si stepSize est 0.0.

Voir aussi stepSize.