Drag QML Type (Uncreatable)
Para especificar eventos de arrastrar y soltar para los elementos movidos. Más...
| Import Statement: | import QtQuick |
Nota: Se trata de un tipo no creable. No se puede instanciar en QML.
Propiedades asociadas
- active : bool
- dragType : enumeration
- hotSpot : point
- imageSource : url
- imageSourceSize : size
(since 6.8) - keys : stringlist
- mimeData : var
- proposedAction : enumeration
- source : Object
- supportedActions : flags
- target : Object
Señales adjuntas
- dragFinished(DropAction dropAction)
- dragStarted()
Métodos adjuntos
- void cancel()
- enumeration drop()
- void start(flags supportedActions)
- void startDrag(flags supportedActions)
Descripción detallada
Mediante la propiedad adjunta «Drag», cualquier elemento puede convertirse en origen de eventos de arrastrar y soltar dentro de una escena.
Cuando se realiza un arrastre ( active ) sobre un elemento, cualquier cambio en la posición de dicho elemento generará un evento de arrastre que se enviará a cualquier objeto de área de trabajo ( DropArea ) que se cruce con la nueva posición del elemento. Otros elementos que implementen controladores de eventos de arrastrar y soltar también pueden recibir estos eventos.
El siguiente fragmento de código muestra cómo se puede arrastrar un elemento con ` MouseArea`. Sin embargo, el arrastre no se limita a los movimientos del ratón; cualquier cosa que pueda mover un elemento puede generar eventos de arrastre, incluidos los eventos táctiles, las animaciones y los enlaces.
import QtQuick
Item {
width: 200; height: 200
DropArea {
x: 75; y: 75
width: 50; height: 50
Rectangle {
anchors.fill: parent
color: "green"
visible: parent.containsDrag
}
}
Rectangle {
x: 10; y: 10
width: 20; height: 20
color: "red"
Drag.active: dragArea.drag.active
Drag.hotSpot.x: 10
Drag.hotSpot.y: 10
MouseArea {
id: dragArea
anchors.fill: parent
drag.target: parent
}
}
}Un arrastre puede finalizarse bien cancelándolo con `Drag.cancel()` o estableciendo `Drag.active` en `false`, o bien puede finalizarse con un evento de suelta llamando a `Drag.drop()`. Si se acepta el evento de suelta, `Drag.drop()` devolverá el ` drop action ` elegido por el destinatario del evento; de lo contrario, devolverá `Qt.IgnoreAction`.
Véase también Ejemplos de «Qt Quick »: arrastrar y soltar.
Documentación de propiedades asociadas
Drag.active : bool [read-only attached]
Esta propiedad indica si hay una secuencia de eventos de arrastre activa en ese momento.
Al vincular esta propiedad a la propiedad «active» de « MouseArea::drag », se llamará a « startDrag » cuando el usuario comience a arrastrar.
Si se establece esta propiedad en «true», también se enviará un evento QDragEnter a la escena con la posición actual del elemento. Si se establece en «false», se enviará un evento QDragLeave.
Mientras el arrastre esté activo, cualquier cambio en la posición de un elemento enviará a la escena un evento «QDragMove» con la nueva posición del elemento.
Drag.dragType : enumeration [attached]
Esta propiedad indica si se deben iniciar automáticamente las acciones de arrastre, no hacer nada o utilizar acciones de arrastre internas compatibles con versiones anteriores. El valor predeterminado es utilizar acciones de arrastre internas compatibles con versiones anteriores.
También se puede iniciar un arrastre manualmente mediante ` startDrag`.
| Constante | Descripción |
|---|---|
Drag.None | no iniciar arrastres automáticamente |
Drag.Automatic | iniciar arrastres automáticamente |
Drag.Internal | (por defecto) iniciar arrastres compatibles con versiones anteriores automáticamente |
Al utilizar « Drag.Automatic », también debes definir « mimeData » y vincular la propiedad « active » a la propiedad «active» de « MouseArea »: MouseArea::drag.active
Drag.hotSpot : point [attached]
Esta propiedad almacena la posición de arrastre con respecto a la esquina superior izquierda del elemento.
Por defecto, es (0, 0).
Los cambios en hotSpot activan un nuevo movimiento de arrastre con la posición actualizada.
Drag.imageSource : url [attached]
Esta propiedad contiene la URL de la imagen que se utilizará para representar los datos durante la operación de arrastrar y soltar. Cambiar esta propiedad una vez iniciada la operación de arrastrar no tendrá ningún efecto.
El siguiente ejemplo utiliza el contenido de un elemento como imagen de arrastre:
import QtQuick
Item {
width: 200; height: 200
Rectangle {
anchors.centerIn: parent
width: text.implicitWidth + 20; height: text.implicitHeight + 10
color: "green"
radius: 5
Drag.dragType: Drag.Automatic
Drag.supportedActions: Qt.CopyAction
Drag.mimeData: {
"text/plain": "Copied text"
}
Text {
id: text
anchors.centerIn: parent
text: "Drag me"
}
DragHandler {
id: dragHandler
onActiveChanged:
if (active) {
parent.grabToImage(function(result) {
parent.Drag.imageSource = result.url
parent.Drag.active = true
})
} else {
parent.Drag.active = false
}
}
}
}Véase también Item::grabToImage().
Drag.imageSourceSize : size [attached, since 6.8]
Esta propiedad indica el tamaño de la imagen que se utilizará para representar los datos durante la operación de arrastrar y soltar. Cambiar esta propiedad una vez iniciada la operación de arrastrar no tendrá ningún efecto.
Esta propiedad establece el número máximo de píxeles almacenados para la imagen cargada, de modo que las imágenes grandes no utilicen más memoria de la necesaria. Consulta Image.sourceSize para obtener más detalles.
El ejemplo siguiente muestra una imagen SVG representada en un tamaño y la vuelve a representar en un tamaño diferente para la imagen de arrastre:
import QtQuick
Item {
width: 200; height: 200
Image {
anchors.centerIn: parent
source: "images/qt_logo.svg"
sourceSize.width: 96
Drag.dragType: Drag.Automatic
Drag.supportedActions: Qt.CopyAction
Drag.mimeData: {
"text/plain": "Qt Quick rocks!"
}
Drag.imageSource: "images/qt_logo.svg"
Drag.imageSourceSize: Qt.size(48, 35)
Drag.active: dragHandler.active
DragHandler {
id: dragHandler
}
}
}Esta propiedad se introdujo en Qt 6.8.
Véase también imageSource y Item::grabToImage().
Drag.keys : stringlist [attached]
Esta propiedad contiene una lista de claves que puede utilizar un « DropArea » para filtrar los eventos de arrastre.
Si se modifican las claves mientras hay un arrastre activo, se restablecerá la secuencia de eventos de arrastre enviando un evento de salida de arrastre seguido de un evento de entrada de arrastre con el nuevo origen.
Drag.mimeData : var [attached]
Esta propiedad contiene una tabla que relaciona el tipo MIME con los datos, y que se utiliza durante la operación « startDrag ». Los datos MIME deben ser de un tipo que coincida con el tipo MIME (por ejemplo, una cadena si el tipo MIME es «text/plain», o una imagen si el tipo MIME es «image/png»), o un objeto ` ArrayBuffer ` con los datos codificados según el tipo MIME.
Drag.proposedAction : enumeration [attached]
Esta propiedad contiene una acción recomendada por la fuente de arrastre como valor de retorno de la función `drop()`.
Los cambios en `proposedAction` desencadenarán un evento de desplazamiento con la propuesta actualizada.
Drag.source : Object [attached]
Esta propiedad contiene un objeto que se identifica ante los destinatarios de los eventos de arrastre como el origen de dichos eventos. Por defecto, se trata del elemento al que está asociada la propiedad «Drag».
Si se cambia el origen mientras hay un arrastre activo, se restablecerá la secuencia de eventos de arrastre enviando un evento de salida de arrastre seguido de un evento de entrada de arrastre con el nuevo origen.
Drag.supportedActions : flags [attached]
Esta propiedad contiene los valores de retorno de Drag.drop() compatibles con la fuente de arrastre.
Si se modifica la propiedad supportedActions mientras hay un arrastre activo, se restablecerá la secuencia de eventos de arrastre enviando un evento de salida de arrastre seguido de un evento de entrada de arrastre con la nueva fuente.
Drag.target : Object [attached]
Mientras un arrastre está activo, esta propiedad contiene el último objeto que ha aceptado un evento «enter» del elemento arrastrado; si la posición actual del arrastre no se cruza con ningún destino que lo acepte, el valor es nulo.
Cuando no hay ningún arrastre activo, esta propiedad contiene el objeto que aceptó el evento de soltado que puso fin al arrastre; si ningún objeto aceptó el soltado o si el arrastre se canceló, el destino será nulo.
Documentación de la señal adjunta
[attached] dragFinished(DropAction dropAction)
Esta señal se emite cuando finaliza un arrastre que se haya iniciado mediante el método ` startDrag()` o que se haya iniciado automáticamente mediante la propiedad ` dragType `.
dropAction Contiene la acción aceptada por el elemento de destino.
Nota: El controlador correspondiente es onDragFinished.
Véase también drop().
[attached] dragStarted()
Esta señal se emite cuando se inicia un arrastre con el método startDrag() o cuando se inicia automáticamente mediante la propiedad dragType.
Nota: El controlador correspondiente es onDragStarted.
Documentación del método adjunta
[attached] void cancel()
Finaliza una secuencia de arrastre.
[attached] enumeration drop()
Finaliza una secuencia de arrastre enviando un evento de soltar al elemento de destino.
Devuelve la acción aceptada por el elemento de destino. Si el elemento de destino o un elemento padre no acepta el evento de suelta, se devolverá Qt.IgnoreAction.
La acción de soltar devuelta puede ser una de las siguientes:
| Constante | Descripción |
|---|---|
Qt.CopyAction | Copiar los datos al destino |
Qt.MoveAction | Mover los datos desde el origen al destino |
Qt.LinkAction | Crear un enlace desde el origen al destino. |
Qt.IgnoreAction | Ignora la acción (no realiza ninguna operación con los datos). |
[attached] void start(flags supportedActions)
Inicia el envío de eventos de arrastre. Se utiliza para iniciar arrastres internos al estilo antiguo. ` startDrag ` es el método preferido, al nuevo estilo, para iniciar arrastres.
El argumento opcional ` supportedActions ` se puede utilizar para anular la propiedad ` supportedActions ` de la secuencia iniciada.
[attached] void startDrag(flags supportedActions)
Comienza a enviar eventos de arrastre.
El argumento opcional « supportedActions » se puede utilizar para anular la propiedad « supportedActions » de la secuencia iniciada.
© 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.