En esta página

Superficie de fotos

Una aplicación QML para dispositivos táctiles que utiliza un «Repeater» con un « FolderListModel » para acceder al contenido de una carpeta, y un « PinchHandler » para gestionar los gestos de pellizco sobre el contenido recuperado.

Una colección de fotos

«Photo Surface» muestra cómo utilizar un « Repeater » con un « FolderListModel » y un « FolderDialog » para acceder a las imágenes de una carpeta seleccionada por el usuario. El ejemplo también muestra cómo gestionar el arrastre, la rotación y el zoom por pellizco dentro del mismo elemento utilizando los controladores de entrada de «Qt Quick ».

Todo el código de la aplicación se encuentra en un único archivo QML: photosurface.qml. El código JavaScript integrado coloca, gira y escala las imágenes en la superficie de fotos.

Ejecución del ejemplo

Puedes ejecutar el ejemplo desde:

Creación de la ventana principal

Para crear la ventana principal de la aplicación Photo Surface, utiliza el tipo QML « Window » como elemento raíz. Este configura automáticamente la ventana para su uso con Qt Quick tipos gráficos:

Window {
    id: root
    visible: true
    width: 1024; height: 600
    color: "black"
    title: Application.displayName + " : " + folderModel.folder
    property real defaultSize: 200
    property real surfaceViewportRatio: 1.5
    property var imageNameFilters: ["*.png", "*.jpg", "*.gif"] // overridden in main.cpp

Acceder al contenido de una carpeta

Utiliza el tipo QML « Repeater » junto con el « FolderListModel » para mostrar las imágenes GIF, JPG y PNG ubicadas en una carpeta (aunque «main.cpp» podría ampliar la lista de tipos de imagen compatibles):

        Repeater {
            model: FolderListModel {
                id: folderModel
                objectName: "folderModel"
                showDirs: false
                nameFilters: root.imageNameFilters
            }

Importa el tipo « FolderListModel »:

import Qt.labs.folderlistmodel

Un FolderDialog permite a los usuarios seleccionar la carpeta que contiene las imágenes:

    FolderDialog {
        id: folderDialog
        title: qsTr("Choose a folder with some images")
        onAccepted: folderModel.folder = selectedFolder
    }

Para utilizar el tipo `FolderDialog`, añade la siguiente instrucción de importación:

import QtQuick.Dialogs

La función ` folderDialog.open() ` abre el cuadro de diálogo de archivos cuando finaliza la presentación de diapositivas inicial, a menos que se haya especificado una ruta de carpeta como argumento de la línea de comandos:

        Component.onDestruction: {
            folderIcon.visible = true
            const lastArg = Application.arguments.slice(-1)[0]
            const standardPicturesLocations = StandardPaths.standardLocations(StandardPaths.PicturesLocation)
            const hasValidPicturesLocation = standardPicturesLocations.length > 0
            if (hasValidPicturesLocation)
                folderDialog.currentFolder = standardPicturesLocations[0]
            if (/.*hotosurface.*|--+/.test(lastArg)) {
                if (hasValidPicturesLocation)
                    folderModel.folder = standardPicturesLocations[0]
                else
                    folderDialog.open()
            }

Los usuarios también pueden hacer clic en el icono del cuadro de diálogo de carpetas para abrirlo. Aquí, un tipo QML «Image» muestra el icono. Dentro del tipo «Image», un « TapHandler » con el controlador de señal « onTapped » llama a la función « folderDialog.open() »:

    Image {
        id: folderIcon
        visible: false
        anchors.top: parent.top
        anchors.left: parent.left
        anchors.margins: 10
        source: "resources/folder.png"

        TapHandler { onTapped: folderDialog.open() }

        HoverHandler { id: folderMouse }

        ToolTip.visible: folderMouse.hovered
        ToolTip.text: qsTr(`Open an image directory (${openShortcut.nativeText})`)
        ToolTip.delay: 1000

        Shortcut {
            id: openShortcut
            sequence: StandardKey.Open
            onActivated: folderDialog.open()
        }
    }

Visualización de imágenes en la superficie «Photo»

Se utiliza un ` Rectangle ` como delegado de un ` Repeater ` para proporcionar un marco a cada imagen que el ` FolderListModel ` encuentra en la carpeta seleccionada. Los métodos ` Math() ` de JavaScript colocan los marcos de forma aleatoria en la superficie de fotos, los giran en ángulos aleatorios y escalan las imágenes. El color del borde indica el estado de la interacción:

            delegate: Rectangle {
                id: photoFrame
                required property date fileModified
                required property string fileName
                required property url fileUrl
                objectName: "frame-" + fileName
                width: image.width * (1 + 0.10 * image.height / image.width)
                height: image.height * 1.10
                scale: root.defaultSize / Math.max(image.sourceSize.width, image.sourceSize.height)
                border.color: pinchHandler.active || dragHandler.active ? "darkturquoise"
                                                                        : mouse.hovered ? "darkseagreen"
                                                                                        : "saddlebrown"
                border.width: 3 / scale
                antialiasing: true
                Component.onCompleted: {
                    x = Math.random() * root.width - width / 2
                    y = Math.random() * root.height - height / 2
                    rotation = Math.random() * 13 - 6
                }

                Image {
                    id: image
                    anchors.centerIn: parent
                    fillMode: Image.PreserveAspectFit
                    source: photoFrame.fileUrl
                    antialiasing: true
                }

Gestión de los gestos de arrastre y pellizco, y del ratón

Un ` DragHandler ` y un ` PinchHandler ` en cada marco de foto gestionan el arrastre, el zoom por pellizco y la rotación:

                PinchHandler {
                    id: pinchHandler
                    minimumRotation: -360
                    maximumRotation: 360
                    minimumScale: 0.1
                    maximumScale: 10
                    grabPermissions: PointerHandler.CanTakeOverFromAnything // and never gonna give it up
                    onActiveChanged: if (active) photoFrame.z = ++flick.highestZ
                }

                DragHandler {
                    id: dragHandler
                    onActiveChanged: {
                        if (active)
                            photoFrame.z = ++flick.highestZ
                        else
                            anim.restart(centroid.velocity)
                    }
                }

Dado que el objeto ` PinchHandler ` se declara dentro del `Rectangle`, la propiedad ` PinchHandler.target ` se establece implícitamente de modo que los gestos de pellizco manipulen el `Rectangle`. Las propiedades de rotación especifican que los marcos pueden girarse a cualquier ángulo, y las propiedades de escala especifican que pueden escalarse entre 0.1 y 10. El gesto de pellizco funciona igual de bien en una pantalla táctil que en un panel táctil multitáctil. Al transformar el marco, se transforma también su contenido (la imagen).

La propiedad « DragHandler.target » también se establece de forma implícita, de modo que puedes arrastrar una foto con un dedo en una pantalla táctil o un panel táctil, o con un ratón. En el controlador de la señal « onActiveChanged » de « DragHandler », el marco de foto seleccionado pasa a la parte superior aumentando el valor de su propiedad « z » (mientras que la propiedad compartida « highestZ » mantiene el mayor valor de « z » que se haya utilizado hasta el momento). Cuando finaliza el arrastre, comienza una animación que mantiene el marco moviéndose en la misma dirección durante un breve instante, hasta que va reduciendo la velocidad y se detiene. Si «lanzas» una foto más allá del borde de la superficie, esta se expande para adaptarse a su nueva posición. Puedes desplazarte para ver diferentes partes de la superficie mediante el ScrollView que contiene el Repeater y todos los marcos de fotos que este rellena.

Dado que puedes arrastrar dos fotos con dos dedos mediante sus «DragHandlers», y que también puedes pellizcar un « PinchHandler » con dos dedos, y que las colecciones de fotos tienden a apilarse unas encima de otras, debes ajustar « grabPermissions » para que el « PinchHandler » tenga prioridad: cuando comienza el gesto de pellizco, no permite que los «DragHandlers» vuelvan a hacerse cargo de las capturas de puntos táctiles.

Para que el ejemplo resulte más interactivo en ordenadores sin dispositivos táctiles, añade el HoverHandler del que depende el border.color anterior, y dos WheelHandlers. Uno te permite mantener pulsada la tecla Ctrl y utilizar la rueda del ratón para girar la foto alrededor del cursor; con el otro, puedes mantener pulsada la tecla Mayús y utilizar la rueda del ratón para acercar o alejar la imagen de la posición situada bajo el cursor. Ambos también elevan la foto de la misma forma que lo hace el DragHandler anterior:

                HoverHandler { id: mouse }

                WheelHandler {
                    acceptedModifiers: Qt.ControlModifier
                    property: "rotation"
                    onActiveChanged: if (active) photoFrame.z = ++flick.highestZ
                }

                WheelHandler {
                    acceptedModifiers: Qt.ShiftModifier
                    property: "scale"
                    onActiveChanged: if (active) photoFrame.z = ++flick.highestZ
                }

Archivos fuente

Proyecto de ejemplo en code.qt.io

Véase también Aplicaciones QML y Ejemplos y tutoriales de «Qt Quick ».

© 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.