ScrollBar QML Type

Barre de défilement interactive verticale ou horizontale. En savoir plus…

• 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 associées

• horizontal : ScrollBar
• vertical : ScrollBar

Méthodes

• void decrease()
• void increase()

Description détaillée

ScrollBar est une barre interactive permettant de faire défiler le contenu jusqu'à une position spécifique. Une barre de défilement peut être de type « vertical » ou « horizontal », et peut être associée à n'importe quel « Flickable », tel que « ListView » et « GridView ». Elle peut également être utilisée avec « ScrollView ».

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

Associer ScrollBar à un Flickable

Lorsqu’une barre de défilement (ScrollBar) est associée à un Flickable via vertically ou horizontally, sa géométrie et les propriétés suivantes sont automatiquement définies et mises à jour comme il convient :

• orientation
• position
• size
• active

Une barre de défilement attachée se rattache au Flickable cible. Une barre de défilement attachée verticalement s’adapte à la hauteur du Flickable et se positionne de part et d’autre de celui-ci en fonction de l’ layout direction. Une barre de défilement attachée horizontalement s’adapte à la largeur du Flickable et se positionne en bas de celui-ci. 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 à l’extérieur d’un Flickable de découpage. L’exemple suivant illustre cette situation :

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

Notez que la barre de défilement (ScrollBar) ne filtre pas les événements de touche du Flickable auquel elle est attachée. L’exemple suivant illustre comment implémenter le défilement à l’aide des touches haut et bas :

Flickable {
    focus: true

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

    ScrollBar.vertical: ScrollBar { id: scrollBar }
}

Liaison de 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 leur état « active ». Afin de maintenir les deux barres visibles lors du défilement dans l’une ou l’autre direction, établissez une liaison bidirectionnelle entre les états « », 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 associées

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

Lorsqu’on utilise une barre de défilement non attachée, les opérations suivantes doivent être effectuées manuellement :

• Positionner la barre de défilement (à l’aide des propriétés x, 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 défilé.
• Définissez la propriété ` active ` pour déterminer quand la barre de défilement sera visible.

Tailles variables des délégués

Des tailles de délégués variables peuvent entraîner des « sauts » de la barre de défilement lorsque de nouveaux délégués sont chargés dans la vue. Il est donc recommandé d’utiliser des délégués de taille identique. Voir Variable Delegate Size and Section Labels pour plus d’informations.

Voir également ScrollIndicator, ScrollView, Personnalisation de ScrollBar et Contrôles indicateurs.

Documentation sur les propriétés

active : bool

Cette propriété s'applique que la barre de défilement soit active ou non, c'est-à-dire lorsqu'elle est en mode « pressed » ou lorsque le Flickable associé est en mode « moving ».

Il est possible de conserver l'both horizontal and vertical bars visible e 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 en mode « 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 également 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 similaire, tant sur le plan visuel que fonctionnel, à ScrollIndicator. Cette propriété est utile pour basculer entre des interfaces utilisateur classiques, orientées souris, et des interfaces utilisateur tactiles, comportant respectivement des barres de défilement interactives et non interactives.

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, mise à l'échelle selon la valeur « 0.0 - 1.0 ».

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

Voir également 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 définie automatiquement lorsque la barre de défilement est de type « attached to a flickable ».

Voir également « horizontal » et « vertical ».

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

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

Valeurs possibles :

L'exemple suivant maintient la barre de défilement verticale 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 de mettre en place des barres de défilement temporaires. Les barres de défilement temporaires sont masquées peu après le dernier événement d’interaction (survol ou pression). Cela se fait généralement en animant l’opacité de la barre de défilement. 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 une vue verticale 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é définit la position de la barre de défilement, mise à l'échelle par rapport à 0.0 - 1.0.

La position maximale valide de la barre de défilement est (1.0 - size). Cela garantit un comportement correct dans le cas le plus courant, 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 associé.

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

Voir également Flickable::visibleArea et visualPosition.

pressed : bool

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

size : real

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

Cette propriété est définie automatiquement lorsque la barre de défilement est de type « 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'alignement.

Valeurs possibles :

Dans le tableau suivant, les différents modes sont illustrés par des animations. Le mouvement et l'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 également orientation.

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

Cette propriété contient la position visuelle effective de la barre de défilement, qui peut être limitée par la propriété ` 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é contient la taille visuelle effective de la barre de défilement, qui peut être limitée par la propriété ` minimum size`.

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

Voir également « size » et « minimumSize ».

Documentation sur les propriétés associées

ScrollBar.horizontal : ScrollBar [attached]

Cette propriété ajoute une barre de défilement horizontale à un élément ` Flickable`.

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

Voir également Attaching ScrollBar to a Flickable.

ScrollBar.vertical : ScrollBar [attached]

Cette propriété ajoute une barre de défilement verticale à une ` Flickable`.

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

Voir également Attaching ScrollBar to a Flickable.

Documentation des méthodes

void decrease()

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

Voir également stepSize.

void increase()

Augmente la position de stepSize ou 0.1 si stepSize est égal à 0.0.

Voir également stepSize.