En esta página

Arrastrar y soltar

La función de arrastrar y soltar ofrece un mecanismo visual sencillo que los usuarios pueden utilizar para transferir información entre aplicaciones y dentro de ellas. Su funcionamiento es similar al del mecanismo de cortar y pegar del portapapeles.

Este documento describe el mecanismo básico de arrastrar y soltar y resume el enfoque utilizado para habilitarlo en controles personalizados. Muchas de las funciones de Qt admiten operaciones de arrastrar y soltar, como las vistas de elementos y el marco de trabajo de vistas gráficas, así como los controles de edición de Qt Widgets y Qt Quick. Para obtener más información sobre las vistas de elementos y el marco de trabajo de vistas gráficas, consulta «Uso de arrastrar y soltar con vistas de elementos y el marco de trabajo de vistas gráficas».

Clases de arrastrar y soltar

Estas clases se ocupan de la función de arrastrar y soltar, así como de la codificación y descodificación de tipos MIME necesarias.

QDrag

Compatibilidad con la transferencia de datos mediante «arrastrar y soltar» basada en MIME

QDragEnterEvent

Evento que se envía a un widget cuando una acción de arrastrar y soltar entra en él

QDragLeaveEvent

Evento que se envía a un widget cuando una acción de arrastrar y soltar sale de él

QDragMoveEvent

Evento que se envía mientras se está llevando a cabo una acción de arrastrar y soltar

QDropEvent

Evento que se envía cuando finaliza una acción de arrastrar y soltar

QUtiMimeConverter

Convierte entre un tipo MIME y un formato de Identificador Uniforme de Tipo (UTI)

Configuración

El objeto ` QStyleHints ` proporciona algunas propiedades relacionadas con las operaciones de arrastrar y soltar:

  • QStyleHints::startDragTime() describe el tiempo, en milisegundos, que el usuario debe mantener pulsado un botón del ratón sobre un objeto antes de que comience el arrastre.
  • QStyleHints::startDragDistance() indica la distancia que el usuario debe desplazar el ratón mientras mantiene pulsado un botón para que el movimiento se interprete como un arrastre.
  • QStyleHints::startDragVelocity() indica la velocidad (en píxeles por segundo) a la que el usuario debe mover el ratón para iniciar el arrastre. Un valor de 0 significa que no existe tal límite.

Estas cantidades proporcionan valores predeterminados razonables que se ajustan al sistema de ventanas subyacente y que puedes utilizar si ofreces soporte para arrastrar y soltar en tus controles.

Arrastrar y soltar en Qt Quick

El resto del documento se centra principalmente en cómo implementar la función de arrastrar y soltar en C++. Para utilizar la función de arrastrar y soltar dentro de una escena Qt Quick, consulta la documentación de los elementos Qt Quick, Drag, DragEvent y DropArea, así como los ejemplos de arrastrar y soltar deQt Quick .

Arrastrar

Para iniciar un arrastre, crea un objeto ` QDrag ` y llama a su función `exec()`. En la mayoría de las aplicaciones, es recomendable iniciar una operación de arrastrar y soltar solo después de que se haya pulsado un botón del ratón y el cursor se haya desplazado una cierta distancia. Sin embargo, la forma más sencilla de habilitar el arrastre desde un widget es reimplementar el método mousePressEvent() del widget e iniciar una operación de arrastrar y soltar:

void MainWindow::mousePressEvent(QMouseEvent *event)
{
    if (event->button() == Qt::LeftButton
        && iconLabel->geometry().contains(event->pos())) {

        QDrag *drag = new QDrag(this);
        QMimeData *mimeData = new QMimeData;

        mimeData->setText(commentEdit->toPlainText());
        drag->setMimeData(mimeData);
        drag->setPixmap(iconPixmap);

        Qt::DropAction dropAction = drag->exec();
        ...
    }
}

Aunque el usuario pueda tardar algún tiempo en completar la operación de arrastre, desde el punto de vista de la aplicación, la función `exec()` es una función bloqueante que devuelve un one of several values. Estos valores indican cómo ha finalizado la operación y se describen con más detalle a continuación.

Tenga en cuenta que la función `exec()` no bloquea el bucle de eventos principal.

Para los widgets que necesitan distinguir entre clics y arrastres del ratón, resulta útil reimplementar la función mousePressEvent() del widget para registrar la posición inicial del arrastre:

void DragWidget::mousePressEvent(QMouseEvent *event)
{
    if (event->button() == Qt::LeftButton)
        dragStartPosition = event->pos();
}

Más adelante, en ` mouseMoveEvent()`, podemos determinar si debe iniciarse un arrastre y crear un objeto de arrastre para gestionar la operación:

void DragWidget::mouseMoveEvent(QMouseEvent *event)
{
    if (!(event->buttons() & Qt::LeftButton))
        return;
    if ((event->pos() - dragStartPosition).manhattanLength()
         < QApplication::startDragDistance())
        return;

    QDrag *drag = new QDrag(this);
    QMimeData *mimeData = new QMimeData;

    mimeData->setData(mimeType, data);
    drag->setMimeData(mimeData);

    Qt::DropAction dropAction = drag->exec(Qt::CopyAction | Qt::MoveAction);
    ...
}

Este enfoque concreto utiliza la función QPoint::manhattanLength() para obtener una estimación aproximada de la distancia entre el punto en el que se produjo el clic del ratón y la posición actual del cursor. Esta función sacrifica precisión a cambio de velocidad y suele ser adecuada para este propósito.

Soltar

Para poder recibir elementos soltados sobre un widget, llama a ` setAcceptDrops(true)` para el widget y reimplementa las funciones de gestión de eventos ` dragEnterEvent()` y ` dropEvent()`.

Por ejemplo, el siguiente código habilita los eventos de suelta en el constructor de una subclase de ` QWidget `, lo que permite implementar de forma útil los controladores de eventos de suelta:

Window::Window(QWidget *parent)
    : QWidget(parent)
{
    ...
    setAcceptDrops(true);
}

La función `dragEnterEvent()` se utiliza normalmente para informar a Qt sobre los tipos de datos que acepta el widget. Debes reimplementar esta función si deseas recibir ` QDragMoveEvent ` o ` QDropEvent ` en tus reimplementaciones de ` dragMoveEvent()` y ` dropEvent()`.

El siguiente código muestra cómo se puede reimplementar dragEnterEvent() para indicar al sistema de arrastrar y soltar que solo podemos gestionar texto sin formato:

void Window::dragEnterEvent(QDragEnterEvent *event)
{
    if (event->mimeData()->hasFormat("text/plain"))
        event->acceptProposedAction();
}

La función ` dropEvent()` se utiliza para desempaquetar los datos soltados y gestionarlos de la forma más adecuada para su aplicación.

En el siguiente código, el texto proporcionado en el evento se pasa a un ` QTextBrowser ` y se rellena un ` QComboBox ` con la lista de tipos MIME que se utilizan para describir los datos:

void Window::dropEvent(QDropEvent *event)
{
    textBrowser->setPlainText(event->mimeData()->text());
    mimeTypeCombo->clear();
    mimeTypeCombo->addItems(event->mimeData()->formats());

    event->acceptProposedAction();
}

En este caso, aceptamos la acción propuesta sin comprobar cuál es. En una aplicación real, puede ser necesario salir de la función dropEvent() sin aceptar la acción propuesta ni gestionar los datos si la acción no es relevante. Por ejemplo, podemos optar por ignorar las acciones de Qt::LinkAction si nuestra aplicación no admite enlaces a fuentes externas.

Anulación de las acciones propuestas

También podemos ignorar la acción propuesta y realizar alguna otra acción con los datos. Para ello, llamaríamos a la función setDropAction() del objeto de evento con la acción preferida de Qt::DropAction antes de llamar a accept(). Esto garantiza que se utilice la acción de soltar de sustitución en lugar de la acción propuesta.

Para aplicaciones más sofisticadas, la reimplementación de dragMoveEvent() y dragLeaveEvent() te permitirá hacer que determinadas partes de tus widgets respondan a los eventos de soltar, y te dará un mayor control sobre la función de arrastrar y soltar en tu aplicación.

Subclasificación de widgets complejos

Algunos widgets estándar de Qt ofrecen su propio soporte para la función de arrastrar y soltar. Al crear subclases de estos widgets, puede ser necesario reimplementar ` dragMoveEvent()` además de ` dragEnterEvent()` y ` dropEvent()` para evitar que la clase base proporcione un manejo predeterminado de la función de arrastrar y soltar, y para gestionar cualquier caso especial que te interese.

Acciones de arrastrar y soltar

En el caso más sencillo, el destino de una acción de arrastrar y soltar recibe una copia de los datos que se están arrastrando, y el origen decide si eliminar el original. Esto se describe mediante la acción ` CopyAction `. El destino también puede optar por gestionar otras acciones, concretamente las acciones « MoveAction » y « LinkAction ». Si el origen llama a ` QDrag::exec()` y esta devuelve ` MoveAction`, el origen es responsable de eliminar cualquier dato original si así lo decide. Los objetos QMimeData y QDrag creados por el widget de origen no deben eliminarse, ya que Qt se encargará de destruirlos. El destino es responsable de asumir la propiedad de los datos enviados en la operación de arrastrar y soltar; esto suele hacerse conservando referencias a los datos.

Si el destino reconoce la acción ` LinkAction `, debe almacenar su propia referencia a la información original; la fuente no necesita realizar ningún procesamiento adicional sobre los datos. El uso más habitual de las acciones de arrastrar y soltar es al realizar un «Mover» dentro del mismo widget; consulta la sección sobre acciones de soltar para obtener más información sobre esta característica.

El otro uso principal de las acciones de arrastrar es cuando se utiliza un tipo de referencia como «text/uri-list», en el que los datos arrastrados son, en realidad, referencias a archivos u objetos.

Añadir nuevos tipos de arrastrar y soltar

La función de arrastrar y soltar no se limita al texto y las imágenes. Se puede transferir cualquier tipo de información mediante una operación de arrastrar y soltar. Para arrastrar información entre aplicaciones, estas deben poder indicarse mutuamente qué formatos de datos pueden aceptar y cuáles pueden generar. Esto se consigue mediante los tipos MIME. El objeto ` QDrag ` creado por el origen contiene una lista de tipos MIME que utiliza para representar los datos (ordenados de más apropiado a menos apropiado), y el destino de la acción de arrastrar y soltar utiliza uno de ellos para acceder a los datos. En el caso de los tipos de datos comunes, las funciones de conveniencia gestionan los tipos MIME utilizados de forma transparente; sin embargo, para los tipos de datos personalizados, es necesario especificarlos explícitamente.

Para implementar acciones de arrastrar y soltar para un tipo de información que no esté cubierto por las funciones de conveniencia de ` QDrag `, el primer paso y el más importante es buscar formatos existentes que sean adecuados: la Autoridad de Asignación de Números de Internet (IANA) proporciona una lista jerárquica de tipos de medios MIME en el Instituto de Ciencias de la Información (ISI). El uso de tipos MIME estándar maximiza la interoperabilidad de su aplicación con otro software, tanto ahora como en el futuro.

Para admitir un tipo de medio adicional, basta con establecer los datos en el objeto ` QMimeData ` mediante la función ` setData()`, proporcionando el tipo MIME completo y un objeto ` QByteArray ` que contenga los datos en el formato adecuado. El siguiente código toma un mapa de píxeles de una etiqueta y lo almacena como un archivo de gráficos de red portátiles (PNG) en un objeto ` QMimeData `:

    QByteArray output;
    QBuffer outputBuffer(&output);
    outputBuffer.open(QIODevice::WriteOnly);
    imageLabel->pixmap().toImage().save(&outputBuffer, "PNG");
    mimeData->setData("image/png", output);

Por supuesto, en este caso podríamos haber utilizado simplemente ` setImageData()` para proporcionar datos de imagen en diversos formatos:

    mimeData->setImageData(QVariant(*imageLabel->pixmap()));

El enfoque de ` QByteArray ` sigue siendo útil en este caso, ya que proporciona un mayor control sobre la cantidad de datos almacenados en el objeto ` QMimeData `.

Ten en cuenta que los tipos de datos personalizados utilizados en las vistas de elementos deben declararse como ` meta objects ` y que deben implementarse los operadores de flujo correspondientes.

Acciones de soltar

En el modelo de portapapeles, el usuario puede cortar o copiar la información de origen para pegarla más tarde. Del mismo modo, en el modelo de arrastrar y soltar, el usuario puede arrastrar una copia de la información o puede arrastrar la propia información a una nueva ubicación (moviéndola ). El modelo de arrastrar y soltar presenta una complicación adicional para el programador: el programa no sabe si el usuario quiere cortar o copiar la información hasta que la operación haya finalizado. A menudo esto no supone ninguna diferencia al arrastrar información entre aplicaciones, pero dentro de una misma aplicación es importante comprobar qué acción de soltar se ha utilizado.

Podemos reimplementar la función `mouseMoveEvent()` para un widget e iniciar una operación de «arrastrar y soltar» con una combinación de posibles acciones de soltar. Por ejemplo, quizá queramos asegurarnos de que al arrastrar siempre se muevan los objetos dentro del widget:

void DragWidget::mouseMoveEvent(QMouseEvent *event)
{
    if (!(event->buttons() & Qt::LeftButton))
        return;
    if ((event->pos() - dragStartPosition).manhattanLength()
         < QApplication::startDragDistance())
        return;

    QDrag *drag = new QDrag(this);
    QMimeData *mimeData = new QMimeData;

    mimeData->setData(mimeType, data);
    drag->setMimeData(mimeData);

    Qt::DropAction dropAction = drag->exec(Qt::CopyAction | Qt::MoveAction);
    ...
}

La acción devuelta por la función exec() puede establecer por defecto un « CopyAction » si la información se suelta en otra aplicación, pero, si se suelta en otro widget de la misma aplicación, podemos obtener una acción de suelta diferente.

Las acciones de soltar propuestas pueden filtrarse en la función `dragMoveEvent()` de un widget. Sin embargo, es posible aceptar todas las acciones propuestas en `dragEnterEvent()` y dejar que el usuario decida más tarde cuáles desea aceptar:

void DragWidget::dragEnterEvent(QDragEnterEvent *event)
{
    event->acceptProposedAction();
}

Cuando se produce un soltar en el widget, se llama a la función de gestión dropEvent(), y podemos gestionar cada acción posible por turnos. En primer lugar, gestionamos las operaciones de arrastrar y soltar dentro del mismo widget:

void DragWidget::dropEvent(QDropEvent *event)
{
    if (event->source() == this && event->possibleActions() & Qt::MoveAction)
        return;

En este caso, rechazamos las operaciones de desplazamiento. Se comprueba cada tipo de acción de suelta que aceptamos y se gestiona en consecuencia:

    if (event->proposedAction() == Qt::MoveAction) {
        event->acceptProposedAction();
        // Process the data from the event.
    } else if (event->proposedAction() == Qt::CopyAction) {
        event->acceptProposedAction();
        // Process the data from the event.
    } else {
        // Ignore the drop.
        return;
    }
    ...
}

Ten en cuenta que en el código anterior hemos comprobado las acciones de soltar de forma individual. Como se ha mencionado anteriormente en la sección sobre la anulación de acciones propuestas, a veces es necesario anular la acción de soltar propuesta y elegir otra diferente de entre la selección de posibles acciones de soltar. Para ello, hay que comprobar la presencia de cada acción en el valor proporcionado por el método ` possibleActions()` del evento, establecer la acción de soltar con ` setDropAction()` y llamar a ` accept()`.

Rectángulos de soltar

El método `dragMoveEvent()` del widget puede utilizarse para restringir las sueltas a determinadas partes del widget, aceptando únicamente las acciones de suelta propuestas cuando el cursor se encuentre dentro de esas áreas. Por ejemplo, el siguiente código acepta cualquier acción de suelta propuesta cuando el cursor se encuentra sobre un widget secundario (`dropFrame`):

void Window::dragMoveEvent(QDragMoveEvent *event)
{
    if (event->mimeData()->hasFormat("text/plain")
        && event->answerRect().intersects(dropFrame->geometry()))

        event->acceptProposedAction();
}

El método dragMoveEvent() también se puede utilizar si necesitas proporcionar retroalimentación visual durante una operación de arrastrar y soltar, para desplazar la ventana o cualquier otra acción que resulte adecuada.

El portapapeles

Las aplicaciones también pueden comunicarse entre sí colocando datos en el portapapeles. Para acceder a él, es necesario obtener un objeto ` QClipboard ` a partir del objeto ` QApplication `.

La clase ` QMimeData ` se utiliza para representar los datos que se transfieren hacia y desde el portapapeles. Para colocar datos en el portapapeles, puedes utilizar las funciones de conveniencia `setText()`, `setImage()` y `setPixmap()` para los tipos de datos más comunes. Estas funciones son similares a las que se encuentran en la clase ` QMimeData `, salvo que también admiten un argumento adicional que controla dónde se almacenan los datos: si se especifica ` Clipboard `, los datos se colocan en el portapapeles; si se especifica ` Selection `, los datos se colocan en la selección del ratón (solo en X11). Por defecto, los datos se colocan en el portapapeles.

Por ejemplo, podemos copiar el contenido de un objeto ` QLineEdit ` al portapapeles con el siguiente código:

QGuiApplication::clipboard()->setText(lineEdit->text(), QClipboard::Clipboard);

También se pueden copiar a el portapapeles datos con diferentes tipos MIME. Crea un objeto ` QMimeData ` y establece los datos con la función `setData()` tal y como se describe en la sección anterior; a continuación, este objeto se puede copiar a el portapapeles con la función ` setMimeData()`.

La clase ` QClipboard ` puede notificar a la aplicación los cambios en los datos que contiene a través de su señal ` dataChanged()`. Por ejemplo, podemos supervisar el portapapeles conectando esta señal a una ranura de un widget:

    connect(clipboard, &QClipboard::dataChanged,
            this, &ClipWindow::updateClipboard);

La ranura conectada a esta señal puede leer los datos del portapapeles utilizando uno de los tipos MIME que sirven para representarlos:

void ClipWindow::updateClipboard()
{
    mimeTypeCombo->clear();

    QStringList formats = clipboard->mimeData()->formats();
    if (formats.isEmpty())
        return;

    for (const auto &format : formats) {
        QByteArray data = clipboard->mimeData()->data(format);
        // ...
    }

La señal ` selectionChanged()` se puede utilizar en X11 para supervisar la selección del ratón.

Ejemplos

Interoperabilidad con otras aplicaciones

En X11 se utiliza el protocolo público XDND, mientras que en Windows Qt utiliza el estándar OLE y Qt para macOS utiliza el gestor de arrastre de Cocoa. En X11, XDND utiliza MIME, por lo que no es necesaria ninguna conversión. La API de Qt es la misma independientemente de la plataforma. En Windows, las aplicaciones compatibles con MIME pueden comunicarse utilizando nombres de formatos del portapapeles que son tipos MIME. Algunas aplicaciones de Windows ya utilizan convenciones de nomenclatura MIME para sus formatos de portapapeles.

Se pueden registrar clases personalizadas para convertir formatos de portapapeles propietarios reimplementando ` QWindowsMimeConverter ` en Windows o ` QUtiMimeConverter ` en macOS.

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