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.

«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:
- Qt Creator
Abre el modo « Welcome » y selecciona el ejemplo en Examples. Para obtener más información, consulta Qt Creator: Tutorial: Compilar y ejecutar.
- Qt Extension for Visual Studio Code
Ejecute el comando « Qt: Open Qt examples » desde Command Palette y seleccione el ejemplo de la lista. Para obtener más información, consulte Qt Extension for Visual Studio Code: Tutorial: Compilar y ejecutar.
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.cppAcceder 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.folderlistmodelUn 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.DialogsLa 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
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.