En esta página

Tumbler QML Type

Rueda giratoria con elementos que se pueden seleccionar. Más...

Import Statement: import QtQuick.Controls
Inherits:

Control

Propiedades

Propiedades adjuntas

Métodos

  • void positionViewAtIndex(int index, PositionMode mode) (since QtQuick.Controls 2.5 (Qt 5.12))

Descripción detallada

Tumbler {
    model: 5
    // ...
}

Tumbler permite al usuario seleccionar una opción de una «rueda» giratoria de elementos. Resulta útil cuando hay demasiadas opciones para utilizar, por ejemplo, un « RadioButton », y muy pocas como para requerir el uso de un « SpinBox » editable. Es práctico porque no requiere el uso del teclado y, cuando hay un gran número de elementos, se va alternando entre los extremos.

La API es similar a la de vistas como ListView y PathView; se pueden establecer model y delegate, y las propiedades count y currentItem proporcionan acceso de solo lectura a la información sobre la vista. Para situar la vista en un índice determinado, utilice positionViewAtIndex().

Sin embargo, a diferencia de vistas como PathView y ListView, siempre hay un elemento actual (cuando el modelo no está vacío). Esto significa que, cuando count es igual a 0, currentIndex será -1. En todos los demás casos, será mayor o igual que 0.

Por defecto, Tumbler wraps cuando llega al principio y al final, siempre que haya más elementos en el modelo que elementos visibles; es decir, cuando count es mayor que visibleItemCount:

import QtQuick
import QtQuick.Window
import QtQuick.Controls

Rectangle {
    width: frame.implicitWidth + 10
    height: frame.implicitHeight + 10

    FontMetrics {
        id: fontMetrics
    }

    Component {
        id: delegateComponent

        Label {
            text: formatText(Tumbler.tumbler.count, modelData)
            opacity: 1.0 - Math.abs(Tumbler.displacement) / (Tumbler.tumbler.visibleItemCount / 2)
            horizontalAlignment: Text.AlignHCenter
            verticalAlignment: Text.AlignVCenter
            font.pixelSize: fontMetrics.font.pixelSize * 1.25

            function formatText(count, modelData) {
                var data = count === 12 ? modelData + 1 : modelData;
                return data.toString().length < 2 ? "0" + data : data;
            }
        }
    }

    Frame {
        id: frame
        padding: 0
        anchors.centerIn: parent

        Row {
            id: row

            Tumbler {
                id: hoursTumbler
                model: 12
                delegate: delegateComponent
            }

            Tumbler {
                id: minutesTumbler
                model: 60
                delegate: delegateComponent
            }

            Tumbler {
                id: amPmTumbler
                model: ["AM", "PM"]
                delegate: delegateComponent
            }
        }
    }
}

Véase también Personalización deTumbler y controles de entrada.

Documentación de propiedades

count : int [read-only]

Esta propiedad contiene el número de elementos del modelo.

currentIndex : int

Esta propiedad contiene el índice del elemento actual.

El valor de esta propiedad es -1 cuando count es igual a 0. En todos los demás casos, será mayor o igual que 0.

Véanse también currentItem y positionViewAtIndex().

currentItem : Item [read-only]

Esta propiedad contiene el elemento del índice actual.

Véase también currentIndex y positionViewAtIndex().

delegate : Component

Esta propiedad contiene el delegado que se utiliza para mostrar cada elemento.

Tumbler no asume la propiedad del delegado.

flickDeceleration : int

Esta propiedad determina la velocidad a la que se desacelera un movimiento rápido: cuanto mayor sea el valor, más rápido se ralentizará cuando el usuario deje de realizar el movimiento rápido con el dedo. Por ejemplo, 0.0001 es casi «sin fricción», mientras que 10000 se percibe como bastante «pegajoso».

Cuando wrap es true (el valor por defecto), el valor predeterminado de flickDeceleration es 100. En caso contrario, depende de la plataforma. Para anular este comportamiento, establece explícitamente el valor de esta propiedad. Para volver al comportamiento predeterminado, establece esta propiedad en undefined. No se permiten valores iguales o inferiores a cero.

model : variant

Esta propiedad contiene el modelo que proporciona los datos para este vaso.

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

Esta propiedad indica si el vaso se está moviendo en ese momento, ya sea porque el usuario lo está arrastrando o porque le ha dado un golpecito.

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

visibleItemCount : int

Esta propiedad indica el número de elementos visibles en el tambor. Debe ser un número impar, ya que el elemento actual siempre está centrado verticalmente.

wrap : bool [since QtQuick.Controls 2.1 (Qt 5.8)]

Esta propiedad determina si el tambor da la vuelta al llegar a la parte superior o inferior.

El valor por defecto es « false » cuando « count » es menor que « visibleItemCount », ya que resulta más sencillo interactuar con un Tumbler sin rebote cuando solo hay unos pocos elementos. Para anular este comportamiento, establezca explícitamente el valor de esta propiedad. Para volver al comportamiento por defecto, establezca esta propiedad en « undefined ».

Esta propiedad se introdujo en QtQuick.Controls 2.1 (Qt 5.8).

Documentación de la propiedad adjunta

Tumbler.displacement : real [read-only attached]

Esta propiedad asociada toma valores comprendidos entre -visibleItemCount / 2 y visibleItemCount / 2, lo que representa la distancia a la que se encuentra este elemento respecto a ser el elemento actual, siendo 0 el valor que indica que es completamente el elemento actual.

Por ejemplo, el elemento que aparece a continuación tendrá un 40 % de opacidad cuando no sea el elemento actual, y pasará a tener un 100 % de opacidad cuando se convierta en el elemento actual:

delegate: Text {
    text: modelData
    opacity: 0.4 + Math.max(0, 1 - Math.abs(Tumbler.displacement)) * 0.6
}

Tumbler.tumbler : Tumbler [read-only attached]

Esta propiedad adjunta contiene el «tumbler». La propiedad se puede asociar a un delegado «tumbler». El valor es « null » si el elemento no es un delegado «tumbler».

Documentación del método

[since QtQuick.Controls 2.5 (Qt 5.12)] void positionViewAtIndex(int index, PositionMode mode)

Coloca la vista de tal manera que el punto de vista ( index ) se sitúe en la posición especificada por mode.

Por ejemplo:

positionViewAtIndex(10, Tumbler.Center)

Si wrap es true (valor por defecto), estarán disponibles los modos de la función positionViewAtIndex() de PathView; en caso contrario, estarán disponibles los modos de la función positionViewAtIndex() de ListView.

Nota: Existe una limitación conocida por la que, si se utiliza ` Tumbler.Beginning ` cuando ` wrap ` es ` true `, se colocará un elemento incorrecto en la parte superior de la vista. Como solución alternativa, pasa ` index - 1`.

Este método se introdujo en QtQuick.Controls 2.5 (Qt 5.12).

Véase también currentIndex.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.