ScrollBar QML Type

Barra de desplazamiento interactiva vertical u horizontal. Más...

• Lista de todos los miembros, incluidos los heredados

Propiedades

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

Propiedades anexas

• horizontal : ScrollBar
• vertical : ScrollBar

Métodos

• void decrease()
• void increase()

Descripción detallada

ScrollBar es una barra interactiva que se puede utilizar para desplazarse a una posición específica. Una barra de desplazamiento puede ser vertical o horizontal, y puede adjuntarse a cualquier Flickable, como ListView y GridView. También puede utilizarse con ScrollView.

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

Adjuntar ScrollBar a un Flickable

Cuando se adjunta una ScrollBar vertically o horizontally a un Flickable, su geometría y las siguientes propiedades se establecen y actualizan automáticamente según corresponda:

• orientation
• position
• size
• active

Una ScrollBar acoplada se vuelve a acoplar al Flickable de destino. Una ScrollBar adjunta verticalmente se redimensiona a la altura del Flickable, y se posiciona a ambos lados de él basándose en layout direction. Una ScrollBar adjunta horizontalmente se redimensiona a la anchura del Flickable, y se posiciona en la parte inferior. La gestión automática de la geometría puede desactivarse especificando otro padre para la ScrollBar adjunta. Esto puede ser útil, por ejemplo, si la ScrollBar debe colocarse fuera de un Flickable de recorte. Esto se demuestra en el siguiente ejemplo:

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

Observe que la ScrollBar no filtra los eventos clave del Flickable al que está adjunta. El siguiente ejemplo ilustra cómo implementar el desplazamiento con las teclas arriba y abajo:

Flickable {
    focus: true

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

    ScrollBar.vertical: ScrollBar { id: scrollBar }
}

Vinculación del estado activo de las barras de desplazamiento horizontal y vertical

Las barras de desplazamiento horizontal y vertical no comparten el estado active entre sí por defecto. Para mantener ambas barras visibles mientras se desplaza en cualquier dirección, establezca una vinculación bidireccional entre los estados activos como se presenta en el siguiente ejemplo:

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

Barras de desplazamiento no vinculadas

Es posible crear una instancia de ScrollBar sin utilizar la API de propiedades adjuntas. Esto resulta útil cuando el comportamiento de la barra de desplazamiento adjunta no es suficiente o no se utiliza Flickable. En el siguiente ejemplo, se utilizan barras de desplazamiento horizontal y vertical para desplazarse por el texto sin utilizar 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
    }
}

Cuando se utiliza una ScrollBar no adjunta, debe hacerse lo siguiente manualmente:

• Configurar la barra de desplazamiento (con las propiedades x y y o anchors, por ejemplo).
• Establezca las propiedades size y position para determinar el tamaño y la posición de la barra de desplazamiento en relación con el elemento desplazado.
• Establezca la propiedad active para determinar cuándo estará visible la barra de desplazamiento.

Variación del tamaño de los delegados

Los tamaños variables de los delegados pueden hacer que ScrollBar "salte" a medida que se cargan nuevos delegados en la vista. Por este motivo, se recomienda utilizar delegados de igual tamaño. Para más información, consulte Variable Delegate Size and Section Labels.

Véase también ScrollIndicator, ScrollView, Personalización de ScrollBar, y Controles Indicadores.

Documentación de Propiedades

active : bool

Esta propiedad mantiene si la barra de desplazamiento está activa, es decir, cuando es pressed o el Flickable adjunto es moving.

Es posible mantener both horizontal and vertical bars visible mientras se desplaza en cualquier dirección.

Esta propiedad se establece automáticamente cuando la barra de desplazamiento es attached to a flickable.

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

Esta propiedad indica si la barra de desplazamiento es horizontal.

Esta propiedad se introdujo en QtQuick.Controls 2.3 (Qt 5.10).

Véase también orientation.

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

Esta propiedad indica si la barra de desplazamiento es interactiva. El valor por defecto es true.

Una barra de desplazamiento no interactiva es visual y comportamentalmente similar a ScrollIndicator. Esta propiedad es útil para cambiar entre las típicas UIs orientadas al ratón y al tacto con barras de desplazamiento interactivas y no interactivas, respectivamente.

Esta propiedad se introdujo en QtQuick.Controls 2.2 (Qt 5.9).

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

Esta propiedad mantiene el tamaño mínimo de la barra de desplazamiento, escalado a 0.0 - 1.0.

Esta propiedad se introdujo en QtQuick.Controls 2.4 (Qt 5.11).

Véase también size, visualSize, y visualPosition.

orientation : enumeration

Esta propiedad contiene la orientación de la barra de desplazamiento.

Valores posibles:

Esta propiedad se establece automáticamente cuando la barra de desplazamiento es attached to a flickable.

Ver también horizontal y vertical.

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

Esta propiedad contiene la política de la barra de desplazamiento. La política por defecto es ScrollBar.AsNeeded.

Valores posibles:

El siguiente ejemplo mantiene la barra de desplazamiento vertical siempre visible:

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

Los estilos pueden utilizar esta propiedad en combinación con la propiedad active para implementar barras de desplazamiento transitorias. Las barras de desplazamiento transitorias se ocultan poco después del último evento de interacción (hover o pulsación). Esto se hace normalmente animando la opacidad de la barra de desplazamiento. Para anular este comportamiento, establezca la política en ScrollBar.AlwaysOn o ScrollBar.AlwaysOff, dependiendo del tamaño del contenido comparado con su vista. Por ejemplo, para una vertical ListView:

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

Esta propiedad se introdujo en QtQuick.Controls 2.2 (Qt 5.9).

position : real

Esta propiedad contiene la posición de la barra de desplazamiento, escalada a 0.0 - 1.0.

La posición válida más grande de la barra de desplazamiento es (1.0 - size). Esto da un comportamiento correcto para el caso más usado donde mover la barra de desplazamiento hasta el final pondrá el final del documento en el extremo inferior del área visible del Flickable conectado.

Esta propiedad se establece automáticamente cuando la barra de desplazamiento es attached to a flickable.

Véase también Flickable::visibleArea y visualPosition.

pressed : bool

Esta propiedad indica si la barra de desplazamiento está pulsada.

size : real

Esta propiedad contiene el tamaño de la barra de desplazamiento, escalado a 0.0 - 1.0.

Esta propiedad se establece automáticamente cuando la barra de desplazamiento es attached to a flickable.

Véase también Flickable::visibleArea, minimumSize, y visualSize.

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

Esta propiedad contiene el modo de ajuste.

Valores posibles:

En la tabla siguiente se ilustran los distintos modos con animaciones. El movimiento y la dirección stepSize (0.25) son idénticos en cada animación.

Valor	Ejemplo
ScrollBar.NoSnap
ScrollBar.SnapAlways
ScrollBar.SnapOnRelease

Esta propiedad se introdujo en QtQuick.Controls 2.2 (Qt 5.9).

Véase también stepSize.

stepSize : real

Esta propiedad contiene el tamaño del paso. El valor por defecto es 0.0.

Véase también snapMode, increase(), y decrease().

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

Esta propiedad indica si la barra de desplazamiento es vertical.

Esta propiedad se introdujo en QtQuick.Controls 2.3 (Qt 5.10).

Véase también orientation.

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

Esta propiedad contiene la posición visual efectiva de la barra de desplazamiento, que puede estar limitada por minimum size.

Esta propiedad se introdujo en QtQuick.Controls 2.4 (Qt 5.11).

Ver también position y minimumSize.

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

Esta propiedad contiene el tamaño visual efectivo de la barra de desplazamiento, que puede estar limitado por minimum size.

Esta propiedad se introdujo en QtQuick.Controls 2.4 (Qt 5.11).

Ver también size y minimumSize.

Documentación de la propiedad Attached

ScrollBar.horizontal : ScrollBar

Esta propiedad adjunta una barra de desplazamiento horizontal a Flickable.

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

Véase también Attaching ScrollBar to a Flickable.

ScrollBar.vertical : ScrollBar

Esta propiedad adjunta una barra de desplazamiento vertical a Flickable.

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

Véase también Attaching ScrollBar to a Flickable.

Documentación del método

void decrease()

Disminuye la posición en stepSize o 0.1 si stepSize es 0.0.

Véase también stepSize.

void increase()

Aumenta la posición en stepSize o 0.1 si stepSize es 0.0.

Véase también stepSize.