Flickable QML Type

Proporciona una superficie que se puede "mover". Más...

• Lista de todos los miembros, incluidos los heredados

Propiedades

• acceptedButtons : flags (since 6.9)
• atXBeginning : bool
• atXEnd : bool
• atYBeginning : bool
• atYEnd : bool
• bottomMargin : real
• boundsBehavior : enumeration
• boundsMovement : enumeration
• contentHeight : real
• contentItem : Item
• contentWidth : real
• contentX : real
• contentY : real
• dragging : bool
• draggingHorizontally : bool
• draggingVertically : bool
• flickDeceleration : real
• flickableDirection : enumeration
• flicking : bool
• flickingHorizontally : bool
• flickingVertically : bool
• horizontalOvershoot : real
• horizontalVelocity : real
• interactive : bool
• leftMargin : real
• maximumFlickVelocity : real
• moving : bool
• movingHorizontally : bool
• movingVertically : bool
• originX : real
• originY : real
• pixelAligned : bool
• pressDelay : int
• rebound : Transition
• rightMargin : real
• synchronousDrag : bool
• topMargin : real
• verticalOvershoot : real
• verticalVelocity : real
• visibleArea
  • visibleArea.heightRatio : real
  • visibleArea.widthRatio : real
  • visibleArea.xPosition : real
  • visibleArea.yPosition : real

Señales

• dragEnded()
• dragStarted()
• flickEnded()
• flickStarted()
• movementEnded()
• movementStarted()

Métodos

• void cancelFlick()
• void flick(qreal xVelocity, qreal yVelocity)
• void flickTo(point position) (since 6.11)
• void flickToChild(QQuickItem *child, PositionMode mode, point offset) (since 6.11)
• void positionViewAtChild(QQuickItem *child, PositionMode mode, point offset) (since 6.11)
• void resizeContent(real width, real height, point center)
• void returnToBounds()

Descripción detallada

El elemento Flickable coloca a sus elementos hijos en una superficie que puede arrastrarse y deslizarse, haciendo que la vista sobre los elementos hijos se desplace. Este comportamiento constituye la base de los elementos diseñados para mostrar un gran número de elementos secundarios, como ListView y GridView.

En las interfaces de usuario tradicionales, las vistas pueden desplazarse utilizando controles estándar, como barras de desplazamiento y botones de flecha. En algunas situaciones, también es posible arrastrar la vista directamente manteniendo pulsado el botón del ratón mientras se mueve el cursor. En las interfaces de usuario táctiles, esta acción de arrastrar se complementa a menudo con una acción de deslizar, en la que el desplazamiento continúa después de que el usuario haya dejado de tocar la vista.

Flickable no recorta automáticamente su contenido. Si no se utiliza como un elemento a pantalla completa, debería considerar establecer la propiedad clip a true.

Ejemplo de uso

El siguiente ejemplo muestra una pequeña vista sobre una imagen grande en la que el usuario puede arrastrar o mover la imagen para ver diferentes partes de la misma.

import QtQuick

Flickable {
    width: 200; height: 200
    contentWidth: image.width; contentHeight: image.height

    Image { id: image; source: "bigImage.png" }
}

Los elementos declarados como hijos de un Flickable son automáticamente emparentados con el Flickable contentItem. Esto debe tenerse en cuenta al operar sobre los hijos del Flickable; normalmente son los hijos de contentItem los que son relevantes. Por ejemplo, el destino de los elementos añadidos al Flickable estará disponible en contentItem.childrenRect

Ejemplos de contentX y contentY

Las siguientes imágenes muestran cómo se mueve un flickable en varias direcciones y los valores resultantes contentX y contentY. El cuadrado azul representa el contenido del flickable, y el borde negro representa los límites del flickable.

Limitaciones

Documentación de propiedades

acceptedButtons : flags [since 6.9]

Los botones del ratón que se pueden utilizar para desplazar este Flickable arrastrando.

Por defecto, esta propiedad se establece en Qt.LeftButton, que proporciona el mismo comportamiento que en versiones anteriores de Qt; pero en la mayoría de las interfaces de usuario, este comportamiento es inesperado. Los usuarios esperan desplazarse sólo en una pantalla táctil, y utilizar la rueda del ratón, los gestos del touchpad o una barra de desplazamiento con ratón o touchpad. Establézcalo en Qt.NoButton para desactivar el arrastre.

Se puede establecer a una combinación OR de botones del ratón, e ignorará los eventos de otros botones.

Esta propiedad se introdujo en Qt 6.9.

Estas propiedades son verdaderas si la vista flickable está posicionada al principio, o al final respectivamente.

Estas propiedades mantienen los márgenes alrededor del contenido. Este espacio se reserva además de los de contentWidth y contentHeight.

boundsBehavior : enumeration

Esta propiedad determina si la superficie puede ser arrastrada más allá de los límites del Flickable, o sobrepasar los límites del Flickable cuando se hace clic sobre ella.

Cuando boundsMovement es Flickable.FollowBoundsBehavior, un valor distinto de Flickable.StopAtBounds dará la sensación de que los bordes de la vista son suaves, en lugar de un límite físico duro.

boundsBehavior puede ser uno de los siguientes:

• Flickable.StopAtBounds - el contenido no puede ser arrastrado más allá del límite del flickable, y los flicks no se sobrepasarán.
• Flickable.DragOverBounds - el contenido puede ser arrastrado más allá de los límites del Flickable, pero los flicks no se sobrepasarán.
• Flickable.OvershootBounds - el contenido puede sobrepasar los límites cuando se arrastra, pero el contenido no puede ser arrastrado más allá de los límites del flickable. (desde QtQuick 2.5)
• Flickable.DragAndOvershootBounds (por defecto) - el contenido puede ser arrastrado más allá de los límites del Flickable, y puede sobrepasar los límites cuando se pulsa.

Véase también horizontalOvershoot, verticalOvershoot, y boundsMovement.

boundsMovement : enumeration

Esta propiedad mantiene si el flickable dará la sensación de que los bordes de la vista son suaves, en lugar de un límite físico duro.

El boundsMovement puede ser uno de los siguientes:

• Flickable.StopAtBounds - esto permite implementar efectos de borde personalizados donde los contenidos no siguen los arrastres o flicks más allá de los límites del flickable. Los valores de horizontalOvershoot y verticalOvershoot pueden ser utilizados para implementar efectos de borde personalizados.
• Flickable.FollowBoundsBehavior (por defecto) - si el contenido sigue los arrastres o movimientos más allá de los límites del flickable está determinado por boundsBehavior.

El siguiente ejemplo mantiene el contenido dentro de los límites y en su lugar aplica un efecto de volteo cuando se desplaza sobre los límites horizontales:

Flickable {
    id: flickable
    boundsMovement: Flickable.StopAtBounds
    boundsBehavior: Flickable.DragAndOvershootBounds
    transform: Rotation {
        axis { x: 0; y: 1; z: 0 }
        origin.x: flickable.width / 2
        origin.y: flickable.height / 2
        angle: Math.min(30, Math.max(-30, flickable.horizontalOvershoot))
    }
}

El siguiente ejemplo mantiene el contenido dentro de los límites y en su lugar aplica un efecto de opacidad cuando se arrastra sobre los límites verticales:

Flickable {
    boundsMovement: Flickable.StopAtBounds
    boundsBehavior: Flickable.DragOverBounds
    opacity: Math.max(0.5, 1.0 - Math.abs(verticalOvershoot) / height)
}

Véase también boundsBehavior, verticalOvershoot, y horizontalOvershoot.

Las dimensiones del contenido (la superficie controlada por el Flickable). Por lo general, debe ajustarse al tamaño combinado de los elementos colocados en el Flickable.

El siguiente fragmento muestra cómo se utilizan estas propiedades para mostrar una imagen más grande que el propio elemento Flickable:

import QtQuick

Flickable {
    width: 200; height: 200
    contentWidth: image.width; contentHeight: image.height

    Image { id: image; source: "bigImage.png" }
}

En algunos casos, las dimensiones del contenido pueden establecerse automáticamente basándose en las propiedades childrenRect.width y childrenRect.height del contentItem. Por ejemplo, el fragmento anterior podría reescribirse con:

contentWidth: contentItem.childrenRect.width; contentHeight: contentItem.childrenRect.height

Aunque esto supone que el origen del childrenRect es 0,0.

contentItem : Item [read-only]

El elemento interno que contiene los elementos que se van a mover en el Flickable.

Los elementos declarados como hijos de un Flickable se vinculan automáticamente al contentItem del Flickable.

Los elementos creados dinámicamente deben estar explícitamente vinculados al contentItem:

Flickable {
    id: myFlickable
    function addItem(file) {
        var component = Qt.createComponent(file)
        component.createObject(myFlickable.contentItem);
    }
}

Estas propiedades contienen la coordenada de superficie actual en la esquina superior izquierda del Flickable. Por ejemplo, si desplazas una imagen 100 píxeles hacia arriba, contentY aumentará en 100.

Véase también Examples of contentX and contentY, originX, y originY.

Estas propiedades describen si la vista se está moviendo horizontalmente, verticalmente o en cualquier dirección, debido a que el usuario arrastra la vista.

flickDeceleration : real

Esta propiedad indica la velocidad a la que se ralentizará un gesto: cuanto mayor sea el número, más rápido se ralentizará cuando el usuario deje de hacer gestos táctiles. Por ejemplo 0.0001 es casi "sin fricción", y 10000 se siente bastante "pegajoso".

El valor por defecto depende de la plataforma. No se permiten valores iguales o inferiores a cero.

flickableDirection : enumeration

Esta propiedad determina en qué direcciones se puede desplazar la vista.

• Flickable.AutoFlickDirection (por defecto) - permite el desplazamiento vertical si contentHeight no es igual a la altura del Flickable. Permite el desplazamiento horizontal si el contentWidth no es igual al ancho del Flickable.
• Flickable.AutoFlickIfNeeded - permite el desplazamiento vertical si contentHeight es mayor que la altura del Flickable. Permite el desplazamiento horizontal si el contentWidth es mayor que el ancho del Flickable. (desde QtQuick 2.7)
• Flickable.HorizontalFlick - permite el desplazamiento horizontal.
• Flickable.VerticalFlick - permite el desplazamiento vertical.
• Flickable.HorizontalAndVerticalFlick - permite desplazarse en ambas direcciones.

Estas propiedades describen si la vista se está moviendo horizontalmente, verticalmente o en cualquier dirección, debido a que el usuario desplaza la vista.

horizontalOvershoot : real [read-only]

Esta propiedad contiene el rebasamiento horizontal, es decir, la distancia horizontal en la que el contenido ha sido arrastrado o desplazado más allá de los límites del flickable. El valor es negativo cuando el contenido es arrastrado o movido más allá del principio, y positivo cuando más allá del final; 0.0 en caso contrario.

Si los valores son reportados para arrastrar y/o deslizar se determina por boundsBehavior. La distancia de rebasamiento se notifica incluso cuando boundsMovement es Flickable.StopAtBounds.

Véase también verticalOvershoot, boundsBehavior, y boundsMovement.

La velocidad instantánea del movimiento a lo largo de los ejes x e y, en píxeles/seg.

La velocidad indicada se suaviza para evitar resultados erráticos.

Tenga en cuenta que para las vistas con un contenido de gran tamaño (más de 10 veces el tamaño de la vista), la velocidad del desplazamiento puede superar la velocidad del toque en el caso de múltiples desplazamientos rápidos consecutivos. Esto permite al usuario desplazarse más rápidamente por contenidos de gran tamaño.

interactive : bool

Esta propiedad describe si el usuario puede interactuar con el Flickable. Un usuario no puede arrastrar o mover un Flickable que no sea interactivo.

Por defecto, esta propiedad es true.

Esta propiedad es útil para desactivar temporalmente el flick. Esto permite una interacción especial con los hijos del Flickable; por ejemplo, podrías querer congelar un mapa flickable mientras te desplazas por un diálogo emergente que es hijo del Flickable.

maximumFlickVelocity : real

Esta propiedad contiene la velocidad máxima a la que el usuario puede mover la vista en píxeles/segundo.

El valor por defecto depende de la plataforma.

Estas propiedades describen si la vista se está moviendo horizontalmente, verticalmente o en cualquier dirección, debido a que el usuario arrastra o desplaza la vista.

Estas propiedades contienen el origen del contenido. Este valor siempre se refiere a la posición superior izquierda del contenido, independientemente de la dirección del diseño.

Suele ser (0,0), aunque ListView y GridView pueden tener un origen arbitrario debido a la variación del tamaño de los delegados o a la inserción/eliminación de elementos fuera de la región visible.

Véase también contentX y contentY.

pixelAligned : bool

Esta propiedad establece la alineación de contentX y contentY a píxeles (true) o subpíxeles (false).

Active pixelAligned para optimizar el contenido estático o en movimiento con bordes de alto contraste, como líneas de un píxel de ancho, texto o gráficos vectoriales. Desactiva pixelAligned cuando optimices la calidad de la animación.

El valor predeterminado es false.

pressDelay : int

Esta propiedad mantiene el tiempo de retardo (ms) de la entrega de una pulsación a los hijos del Flickable. Esto puede ser útil cuando reaccionar a una pulsación antes de una acción de deslizamiento tiene efectos no deseados.

Si el flickable es arrastrado o pulsado antes de que se agote el tiempo de retardo, el evento de pulsación no se producirá. Si el botón se suelta dentro del tiempo de espera, tanto la pulsación como la liberación serán entregadas.

Ten en cuenta que para Flickables anidados con pressDelay establecido, el pressDelay de los Flickables externos es anulado por el Flickable más interno. Si el arrastre supera el umbral de arrastre de la plataforma, el evento de pulsación se producirá independientemente de esta propiedad.

Ver también QStyleHints.

rebound : Transition

Contiene la transición que se aplicará a la vista de contenido cuando se ajuste a los límites del flickable. La transición se activa cuando la vista se desplaza o arrastra más allá del borde del área de contenido, o cuando se llama a returnToBounds().

import QtQuick 2.0

Flickable {
    width: 150; height: 150
    contentWidth: 300; contentHeight: 300

    rebound: Transition {
        NumberAnimation {
            properties: "x,y"
            duration: 1000
            easing.type: Easing.OutBounce
        }
    }

    Rectangle {
        width: 300; height: 300
        gradient: Gradient {
            GradientStop { position: 0.0; color: "lightsteelblue" }
            GradientStop { position: 1.0; color: "blue" }
        }
    }
}

Cuando la vista se desplaza más allá de sus límites, volverá a ellos utilizando la transición especificada:

Si esta propiedad no está establecida, se aplica una animación por defecto.

synchronousDrag : bool

Si esta propiedad está establecida a true, entonces cuando el ratón o el punto táctil se mueven lo suficientemente lejos como para empezar a arrastrar el contenido, el contenido saltará, de tal forma que el píxel de contenido que estaba bajo el cursor o el punto táctil cuando se pulsó permanecerá bajo ese punto.

El valor por defecto es false, que proporciona una experiencia más suave (sin salto) a costa de que parte de la distancia de arrastre se "pierde" al principio.

verticalOvershoot : real [read-only]

Esta propiedad contiene el rebasamiento vertical, es decir, la distancia vertical en la que el contenido ha sido arrastrado o desplazado más allá de los límites del flickable. El valor es negativo cuando el contenido es arrastrado o movido más allá del principio, y positivo cuando más allá del final; 0.0 en caso contrario.

Si los valores son reportados para arrastrar y/o deslizar se determina por boundsBehavior. La distancia de rebasamiento se notifica incluso cuando boundsMovement es Flickable.StopAtBounds.

Véase también horizontalOvershoot, boundsBehavior, y boundsMovement.

visibleArea group

Estas propiedades describen la posición y el tamaño del área visualizada actualmente. El tamaño se define como el porcentaje de la vista completa visible actualmente, escalado a 0,0 - 1,0. La posición de la página está normalmente en el rango de 0.0 (principio) a 1.0 menos el ratio de tamaño (final), es decir, yPosition está en el rango de 0.0 a 1.0-heightRatio. Sin embargo, es posible que los contenidos sean arrastrados fuera del rango normal, resultando en que las posiciones de la página también estén fuera del rango normal.

Estas propiedades se utilizan normalmente para dibujar una barra de desplazamiento. Por ejemplo:

Rectangle {
    width: 200; height: 200

    Flickable {
        id: flickable
        ...
    }

    Rectangle {
        id: scrollbar
        anchors.right: flickable.right
        y: flickable.visibleArea.yPosition * flickable.height
        width: 10
        height: flickable.visibleArea.heightRatio * flickable.height
        color: "black"
    }
}

Señal Documentación

dragEnded()

Esta señal se emite cuando el usuario deja de arrastrar la vista.

Si la velocidad del arrastre es suficiente en el momento en que se suelta el botón táctil/del ratón, se iniciará un flick.

dragStarted()

Esta señal se emite cuando la vista comienza a ser arrastrada debido a la interacción del usuario.

flickEnded()

Esta señal se emite cuando la vista deja de moverse después de un flick o una serie de flicks.

flickStarted()

Esta señal se emite cuando se desliza la vista. Un flick comienza en el momento en que se suelta el ratón o el toque, mientras aún está en movimiento.

movementEnded()

Esta señal se emite cuando la vista deja de moverse debido a la interacción del usuario o a un flick() generado. Si estaba activo un flick, esta señal se emitirá cuando el flick se detenga. Si no estaba activo un flick, esta señal se emitirá cuando el usuario deje de arrastrar, es decir, cuando se suelte el ratón o la pantalla táctil.

movementStarted()

Esta señal se emite cuando la vista comienza a moverse debido a la interacción del usuario o a un flick generado ().

Documentación del método

void cancelFlick()

Cancela la animación actual.

void flick(qreal xVelocity, qreal yVelocity)

Mueve el contenido con xVelocity horizontalmente y yVelocity verticalmente en píxeles/seg.

Al llamar a este método se actualizarán las propiedades y señales de movimiento y parpadeo correspondientes, como si se tratara de un parpadeo real en una pantalla táctil.

[since 6.11] void flickTo(point position)

Mueve el flickable a position.

Si al mover el flickable se muestra un espacio vacío al principio o al final del flickable, el flickable dejará de moverse en el límite.

Este método se introdujo en Qt 6.11.

[since 6.11] void flickToChild(QQuickItem *child, PositionMode mode, point offset)

Mueve el flickable de forma que el elemento child (si es hijo) se encuentre en la posición especificada por mode. mode puede ser una combinación or-ed de las siguientes:

Si no se especifica una alineación vertical, se ignorará el desplazamiento vertical. Lo mismo ocurre con la alineación horizontal.

Opcionalmente, puede especificar offset para desplazar un número extra de píxeles más allá de la alineación objetivo.

Si al mover el flickable en el elemento hijo se muestra un espacio vacío al principio o al final del flickable, el flickable dejará de moverse en el límite.

import QtQuick
import QtQuick.Controls
import QtQuick.Window

Flickable {
    id: flickable

    width: 200
    height: 200
    contentWidth: width
    contentHeight: column.height

    // Will flick to the beginning of the activeFocusItem every time it changes
    property Item activeFocusItem: Window.activeFocusItem
    onActiveFocusItemChanged: flickable.flickToChild(activeFocusItem, Flickable.AlignTop)

    Column {
        id: column

        spacing: 10

        Repeater {
            model: 10
            TextArea {}
        }
    }
}

Este método se introdujo en Qt 6.11.

[since 6.11] void positionViewAtChild(QQuickItem *child, PositionMode mode, point offset)

Posiciones contentX y contentY tales que el elemento child (si es hijo) se encuentra en la posición especificada por mode. mode puede ser una combinación or-ed de las siguientes:

Si no se especifica la alineación vertical, se ignorará el posicionamiento vertical. Lo mismo ocurre con la alineación horizontal.

Opcionalmente, puede especificar offset para mover contentX y contentY un número extra de píxeles más allá de la alineación objetivo.

Si posicionar el flickable en el elemento hijo causaría que se mostrara un espacio vacío al principio o al final del flickable, el flickable se posicionará en el límite.

import QtQuick
import QtQuick.Controls
import QtQuick.Window

Flickable {
    id: flickable

    width: 200
    height: 200
    contentWidth: width
    contentHeight: column.height

    // Will center activeFocusItem in the Flickable every time it changes
    property Item activeFocusItem: Window.activeFocusItem
    onActiveFocusItemChanged: flickable.positionViewAtChild(activeFocusItem, Flickable.AlignCenter)

    Column {
        id: column

        spacing: 10

        Repeater {
            model: 10
            TextArea {}
        }
    }
}

Este método se introdujo en Qt 6.11.

void resizeContent(real width, real height, point center)

Cambia el tamaño del contenido a width x height sobre center.

Esto no escala el contenido del Flickable - sólo redimensiona el contentWidth y contentHeight.

Redimensionar el contenido puede hacer que éste se sitúe fuera de los límites del Flickable. Si se llama a returnToBounds(), el contenido volverá a situarse dentro de los límites legales.

void returnToBounds()

Asegura que el contenido está dentro de los límites legales.

Puede invocarse para asegurarse de que el contenido está dentro de los límites legales después de posicionarlo manualmente.