Ejemplo de robot de arrastrar y soltar
Muestra cómo arrastrar y soltar elementos en una vista gráfica.
El ejemplo «Robot de arrastrar y soltar» muestra cómo implementar la función de arrastrar y soltar en una subclase de ` QGraphicsItem `, así como cómo animar elementos utilizando el marco de animación de Qt.

La vista gráfica proporciona la clase ` QGraphicsScene ` para gestionar e interactuar con un gran número de elementos gráficos 2D personalizados derivados de la clase ` QGraphicsItem `, y un widget ` QGraphicsView ` para visualizar los elementos, con soporte para el zoom y la rotación.
Este ejemplo consta de una clase ` Robot `, una clase ` ColorItem ` y una función principal: la clase ` Robot ` describe un robot sencillo compuesto por varias extremidades derivadas de ` RobotPart `, entre las que se incluyen ` RobotHead ` y ` RobotLimb`; la clase ` ColorItem ` proporciona una elipse de color arrastrable; y la función ` main() ` proporciona la ventana principal de la aplicación.
En primer lugar, repasaremos la clase ` Robot ` para ver cómo ensamblar las diferentes partes de modo que puedan girarse y animarse individualmente mediante ` QPropertyAnimation`, y a continuación repasaremos la clase ` ColorItem ` para mostrar cómo implementar la función de arrastrar y soltar entre elementos. Por último, repasaremos la función `main()` para ver cómo podemos unir todas las piezas y formar la aplicación final.
Definición de la clase Robot
El robot consta de tres clases principales: la clase « RobotHead », la clase « RobotTorso » y la clase « RobotLimb », que se utiliza para los brazos y las piernas, tanto superiores como inferiores. Todas las partes derivan de la clase « RobotPart », que a su vez hereda de « QGraphicsObject ». La clase « Robot » en sí misma no tiene apariencia visual y sirve únicamente como nodo raíz del robot.
Comencemos con la declaración de la clase ` RobotPart `.
class RobotPart : public QGraphicsObject
{
public:
RobotPart(QGraphicsItem *parent = nullptr);
protected:
void dragEnterEvent(QGraphicsSceneDragDropEvent *event) override;
void dragLeaveEvent(QGraphicsSceneDragDropEvent *event) override;
void dropEvent(QGraphicsSceneDragDropEvent *event) override;
QColor color = Qt::lightGray;
bool dragOver = false;
};Esta clase base hereda de QGraphicsObject. QGraphicsObject proporciona señales y ranuras al heredar de QObject, y también declara las propiedades de QGraphicsItem utilizando Q_PROPERTY, lo que hace que las propiedades sean accesibles para QPropertyAnimation.
RobotPart también implementa los tres controladores de eventos más importantes para aceptar eventos de soltar: dragEnterEvent(), dragLeaveEvent() y dropEvent().
El color se almacena como una variable de miembro, junto con la variable dragOver, que utilizaremos más adelante para indicar visualmente que la extremidad puede aceptar los colores que se arrastren sobre ella.
RobotPart::RobotPart(QGraphicsItem *parent)
: QGraphicsObject(parent), color(Qt::lightGray)
{
setAcceptDrops(true);
}RobotPartEl constructor de esta clase inicializa el miembro `dragOver` y establece el color en ` Qt::lightGray`. En el cuerpo del constructor habilitamos la compatibilidad para aceptar eventos de suelta llamando a ` setAcceptDrops(true)`.
El resto de la implementación de esta clase está dedicada a la gestión de arrastrar y soltar.
void RobotPart::dragEnterEvent(QGraphicsSceneDragDropEvent *event)
{
if (event->mimeData()->hasColor()) {
event->setAccepted(true);
dragOver = true;
update();
} else {
event->setAccepted(false);
}
}El controlador dragEnterEvent() se invoca cuando se arrastra un elemento de arrastrar y soltar al área de la pieza del robot.
La implementación del controlador determina si este elemento en su conjunto puede aceptar o no los datos MIME asociados al objeto arrastrado entrante. RobotPart proporciona un comportamiento básico para todas las piezas que aceptan sueltes de color. Así pues, si el objeto arrastrado entrante contiene un color, se acepta el evento, establecemos ` dragOver ` en ` true ` y llamamos a `update()` para proporcionar una respuesta visual positiva al usuario; de lo contrario, se ignora el evento, lo que a su vez permite que este se propague a los elementos padres.
void RobotPart::dragLeaveEvent(QGraphicsSceneDragDropEvent *event)
{
Q_UNUSED(event);
dragOver = false;
update();
}El controlador ` dragLeaveEvent()` se invoca cuando un elemento de arrastrar y soltar se aleja del área de la pieza del robot. Nuestra implementación simplemente restablece `dragOver` a `false` y llama a ` update()` para ayudar a proporcionar una respuesta visual que indique que el arrastre ha abandonado este elemento.
void RobotPart::dropEvent(QGraphicsSceneDragDropEvent *event)
{
dragOver = false;
if (event->mimeData()->hasColor())
color = qvariant_cast<QColor>(event->mimeData()->colorData());
update();
}El controlador ` dropEvent()` se invoca cuando un elemento de «Arrastrar y soltar» se suelta sobre un elemento (es decir, cuando se suelta el botón del ratón sobre el elemento mientras se arrastra).
Restablecemos dragOver a «false», asignamos el nuevo color al elemento y llamamos a update().
La declaración y la implementación de ` RobotHead`, ` RobotTorso` y ` RobotLimb ` son prácticamente idénticas. Analizaremos ` RobotHead ` en detalle, ya que esta clase presenta una diferencia menor, y dejaremos las demás clases como ejercicio para el lector.
class RobotHead : public RobotPart
{
public:
RobotHead(QGraphicsItem *parent = nullptr);
QRectF boundingRect() const override;
void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget = nullptr) override;
protected:
void dragEnterEvent(QGraphicsSceneDragDropEvent *event) override;
void dropEvent(QGraphicsSceneDragDropEvent *event) override;
private:
QPixmap pixmap;
};La clase RobotHead hereda de RobotPart y proporciona las implementaciones necesarias de boundingRect() y paint(). También reimplementa dragEnterEvent() y dropEvent() para ofrecer un tratamiento especial de las sueltas de imágenes.
La clase contiene un miembro privado de tipo pixmap que podemos utilizar para implementar la compatibilidad con la aceptación de arrastres de imágenes.
RobotHead::RobotHead(QGraphicsItem *parent)
: RobotPart(parent)
{
}RobotHead Tiene un constructor bastante sencillo que simplemente reenvía al constructor de ` RobotPart`.
La reimplementación de boundingRect() devuelve los límites del elemento «head». Como queremos que el centro de rotación sea la parte inferior central del elemento, hemos elegido un rectángulo delimitador que comienza en (-15, -50) y se extiende hasta 30 unidades de ancho y 50 unidades de alto. Al girar la cabeza, el «cuello» permanecerá inmóvil mientras que la parte superior de la cabeza se inclina de un lado a otro.
void RobotHead::paint(QPainter *painter,
const QStyleOptionGraphicsItem *option, QWidget *widget)
{
Q_UNUSED(option);
Q_UNUSED(widget);
if (pixmap.isNull()) {
painter->setBrush(dragOver ? color.lighter(130) : color);
painter->drawRoundedRect(-10, -30, 20, 30, 25, 25, Qt::RelativeSize);
painter->setBrush(Qt::white);
painter->drawEllipse(-7, -3 - 20, 7, 7);
painter->drawEllipse(0, -3 - 20, 7, 7);
painter->setBrush(Qt::black);
painter->drawEllipse(-5, -1 - 20, 2, 2);
painter->drawEllipse(2, -1 - 20, 2, 2);
painter->setPen(QPen(Qt::black, 2));
painter->setBrush(Qt::NoBrush);
painter->drawArc(-6, -2 - 20, 12, 15, 190 * 16, 160 * 16);
} else {
painter->scale(.2272, .2824);
painter->drawPixmap(QPointF(-15 * 4.4, -50 * 3.54), pixmap);
}
}En paint() dibujamos la cabeza propiamente dicha. La implementación se divide en dos secciones: si se ha arrastrado una imagen sobre la cabeza, dibujamos la imagen; de lo contrario, dibujamos una cabeza de robot rectangular redondeada con gráficos vectoriales sencillos.
Por motivos de rendimiento, dependiendo de la complejidad de lo que se dibuje, a menudo puede resultar más rápido dibujar la cabeza como una imagen en lugar de utilizar una secuencia de operaciones vectoriales.
void RobotHead::dragEnterEvent(QGraphicsSceneDragDropEvent *event)
{
if (event->mimeData()->hasImage()) {
event->setAccepted(true);
dragOver = true;
update();
} else {
RobotPart::dragEnterEvent(event);
}
}La cabeza del robot admite la colocación de imágenes. Para ello, su reimplementación de ` dragEnterEvent()` comprueba si el objeto arrastrado contiene datos de imagen y, en caso afirmativo, se acepta el evento. De lo contrario, recurrimos a la implementación básica de ` RobotPart `.
void RobotHead::dropEvent(QGraphicsSceneDragDropEvent *event)
{
if (event->mimeData()->hasImage()) {
dragOver = false;
pixmap = qvariant_cast<QPixmap>(event->mimeData()->imageData());
update();
} else {
RobotPart::dropEvent(event);
}
}Para completar la compatibilidad con imágenes, también debemos implementar dropEvent(). Comprobamos si el objeto arrastrado contiene datos de imagen y, en caso afirmativo, almacenamos estos datos como un miembro pixmap y llamamos a update(). Este pixmap se utiliza dentro de la implementación de paint() que hemos revisado anteriormente.
RobotTorso y RobotLimb son similares a RobotHead, así que pasemos directamente a la clase Robot.
class Robot : public RobotPart
{
public:
Robot(QGraphicsItem *parent = nullptr);
QRectF boundingRect() const override;
void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget = nullptr) override;
};La clase Robot también hereda de RobotPart y, al igual que las demás partes, implementa boundingRect() y paint(). Sin embargo, ofrece una implementación bastante especial:
QRectF Robot::boundingRect() const
{
return QRectF();
}
void Robot::paint(QPainter *painter,
const QStyleOptionGraphicsItem *option, QWidget *widget)
{
Q_UNUSED(painter);
Q_UNUSED(option);
Q_UNUSED(widget);
}Dado que la clase ` Robot ` solo se utiliza como nodo base para el resto del robot, no tiene representación visual. Por lo tanto, su implementación de ` boundingRect()` puede devolver un ` QRectF` nulo, y su función `paint()` no hace nada.
Robot::Robot(QGraphicsItem *parent)
: RobotPart(parent)
{
setFlag(ItemHasNoContents);
QGraphicsObject *torsoItem = new RobotTorso(this);
QGraphicsObject *headItem = new RobotHead(torsoItem);
QGraphicsObject *upperLeftArmItem = new RobotLimb(torsoItem);
QGraphicsObject *lowerLeftArmItem = new RobotLimb(upperLeftArmItem);
QGraphicsObject *upperRightArmItem = new RobotLimb(torsoItem);
QGraphicsObject *lowerRightArmItem = new RobotLimb(upperRightArmItem);
QGraphicsObject *upperRightLegItem = new RobotLimb(torsoItem);
QGraphicsObject *lowerRightLegItem = new RobotLimb(upperRightLegItem);
QGraphicsObject *upperLeftLegItem = new RobotLimb(torsoItem);
QGraphicsObject *lowerLeftLegItem = new RobotLimb(upperLeftLegItem);El constructor comienza estableciendo el indicador ` ItemHasNoContents`, lo cual supone una pequeña optimización para los elementos que carecen de apariencia visual.
A continuación, construimos todas las partes del robot (cabeza, torso y brazos y piernas superiores e inferiores). El orden de apilamiento es muy importante, y utilizamos la jerarquía padre-hijo para garantizar que los elementos giren y se muevan correctamente. Primero construimos el torso, ya que es el elemento raíz. A continuación, construimos la cabeza y pasamos el torso al constructor de ` HeadItem`. De este modo, la cabeza se convierte en un elemento hijo del torso; si se gira el torso, la cabeza lo seguirá. Se aplica el mismo patrón al resto de las extremidades.
headItem->setPos(0, -18);
upperLeftArmItem->setPos(-15, -10);
lowerLeftArmItem->setPos(30, 0);
upperRightArmItem->setPos(15, -10);
lowerRightArmItem->setPos(30, 0);
upperRightLegItem->setPos(10, 32);
lowerRightLegItem->setPos(30, 0);
upperLeftLegItem->setPos(-10, 32);
lowerLeftLegItem->setPos(30, 0);Cada parte del robot se coloca con cuidado. Por ejemplo, el brazo superior izquierdo se desplaza con precisión a la zona superior izquierda del torso, y el brazo superior derecho se desplaza a la zona superior derecha.
QParallelAnimationGroup *animation = new QParallelAnimationGroup(this);
QPropertyAnimation *headAnimation = new QPropertyAnimation(headItem, "rotation");
headAnimation->setStartValue(20);
headAnimation->setEndValue(-20);
QPropertyAnimation *headScaleAnimation = new QPropertyAnimation(headItem, "scale");
headScaleAnimation->setEndValue(1.1);
animation->addAnimation(headAnimation);
animation->addAnimation(headScaleAnimation);En la siguiente sección se crean todos los objetos de animación. Este fragmento de código muestra las dos animaciones que actúan sobre la escala y la rotación de la cabeza. Las dos instancias de ` QPropertyAnimation ` se limitan a establecer el objeto, la propiedad y los valores iniciales y finales correspondientes.
Todas las animaciones están controladas por un grupo de animación paralelo de nivel superior. Las animaciones de escala y rotación se añaden a este grupo.
El resto de animaciones se definen de forma similar.
for (int i = 0; i < animation->animationCount(); ++i) {
QPropertyAnimation *anim = qobject_cast<QPropertyAnimation *>(animation->animationAt(i));
anim->setEasingCurve(QEasingCurve::SineCurve);
anim->setDuration(2000);
}
animation->setLoopCount(-1);
animation->start();Por último, establecemos una curva de aceleración y una duración para cada animación, nos aseguramos de que el grupo de animación de nivel superior se repita indefinidamente e iniciamos la animación de nivel superior.
Definición de la clase ColorItem
La clase ` ColorItem ` representa un elemento circular sobre el que se puede pulsar para arrastrar colores a las partes del robot.
class ColorItem : public QGraphicsItem
{
public:
ColorItem();
QRectF boundingRect() const override;
void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget) override;
protected:
void mousePressEvent(QGraphicsSceneMouseEvent *event) override;
void mouseMoveEvent(QGraphicsSceneMouseEvent *event) override;
void mouseReleaseEvent(QGraphicsSceneMouseEvent *event) override;
private:
QColor color;
};Esta clase es muy sencilla. No utiliza animaciones y no necesita propiedades ni señales ni ranuras, por lo que, para ahorrar recursos, lo más natural es que herede de ` QGraphicsItem ` (en lugar de de ` QGraphicsObject`).
Declara las funciones obligatorias ` boundingRect()` y ` paint()`, y añade reimplementaciones de ` mousePressEvent()`, ` mouseMoveEvent()` y ` mouseReleaseEvent()`. Contiene un único miembro privado de tipo color.
Echemos un vistazo a su implementación.
ColorItem::ColorItem()
: color(QRandomGenerator::global()->bounded(256), QRandomGenerator::global()->bounded(256), QRandomGenerator::global()->bounded(256))
{
setToolTip(QString("QColor(%1, %2, %3)\n%4")
.arg(color.red()).arg(color.green()).arg(color.blue())
.arg("Click and drag this color onto the robot!"));
setCursor(Qt::OpenHandCursor);
setAcceptedMouseButtons(Qt::LeftButton);
}ColorItemEl constructor de este elemento asigna un color aleatorio opaco a su miembro «color» utilizando QRandomGenerator. Para mejorar la usabilidad, le asigna una información sobre herramientas que ofrece una sugerencia útil al usuario y, además, establece un cursor adecuado. Esto garantiza que el cursor cambie a Qt::OpenHandCursor cuando el puntero del ratón se sitúe sobre el elemento.
Por último, llamamos a ` setAcceptedMouseButtons()` para garantizar que este elemento solo pueda procesar ` Qt::LeftButton`. Esto simplifica enormemente los controladores de eventos del ratón, ya que siempre podemos dar por hecho que solo se pulsa y se suelta el botón izquierdo del ratón.
El rectángulo delimitador del elemento es un rectángulo fijo de 30 × 30 unidades centrado en el origen del elemento (0, 0), y ajustado en 0,5 unidades en todas las direcciones para permitir que un lápiz escalable dibuje su contorno. Como toque visual final, los límites también se desplazan unas pocas unidades hacia abajo y a la derecha para dejar espacio a una sencilla sombra proyectada.
void ColorItem::paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget)
{
Q_UNUSED(option);
Q_UNUSED(widget);
painter->setPen(Qt::NoPen);
painter->setBrush(Qt::darkGray);
painter->drawEllipse(-12, -12, 30, 30);
painter->setPen(QPen(Qt::black, 1));
painter->setBrush(QBrush(color));
painter->drawEllipse(-15, -15, 30, 30);
}La implementación de paint() dibuja una elipse con un contorno negro de 1 unidad, un relleno de color liso y una sombra proyectada de color gris oscuro.
void ColorItem::mousePressEvent(QGraphicsSceneMouseEvent *)
{
setCursor(Qt::ClosedHandCursor);
}El controlador ` mousePressEvent()` se invoca al pulsar el botón del ratón dentro del área del elemento. Nuestra implementación simplemente establece el cursor en ` Qt::ClosedHandCursor`.
void ColorItem::mouseReleaseEvent(QGraphicsSceneMouseEvent *)
{
setCursor(Qt::OpenHandCursor);
}El controlador mouseReleaseEvent() se invoca al soltar el botón del ratón tras haberlo pulsado dentro del área de un elemento. Nuestra implementación vuelve a establecer el cursor en Qt::OpenHandCursor. Los controladores de eventos de pulsación y liberación del ratón, en conjunto, proporcionan una útil retroalimentación visual al usuario: al mover el puntero del ratón sobre un CircleItem, el cursor cambia a una mano abierta. Al pulsar el elemento, aparecerá un cursor de mano cerrada. Al soltar el botón, volverá a aparecer el cursor de mano abierta.
void ColorItem::mouseMoveEvent(QGraphicsSceneMouseEvent *event)
{
if (QLineF(event->screenPos(), event->buttonDownScreenPos(Qt::LeftButton))
.length() < QApplication::startDragDistance()) {
return;
}
QDrag *drag = new QDrag(event->widget());
QMimeData *mime = new QMimeData;
drag->setMimeData(mime);El controlador mouseMoveEvent() se invoca cuando se mueve el ratón después de pulsar el botón dentro del área del ColorItem. Esta implementación proporciona la parte más importante de la lógica de CircleItem: el código que inicia y gestiona los arrastres.
La implementación comienza comprobando si el ratón se ha arrastrado lo suficiente como para eliminar el ruido de las oscilaciones del ratón. Solo queremos iniciar un arrastre si el ratón se ha desplazado más allá de la distancia de inicio de arrastre de la aplicación.
A continuación, creamos un objeto ` QDrag `, pasando el evento ` widget ` (es decir, el área de visualización de ` QGraphicsView `) a su constructor. Qt se encargará de que este objeto se elimine en el momento adecuado. También creamos una instancia de ` QMimeData ` que puede contener nuestros datos de color o imagen, y la asignamos al objeto de arrastre.
static int n = 0;
if (n++ > 2 && QRandomGenerator::global()->bounded(3) == 0) {
QImage image(":/images/head.png");
mime->setImageData(image);
drag->setPixmap(QPixmap::fromImage(image).scaled(30, 40));
drag->setHotSpot(QPoint(15, 30));Este fragmento de código tiene un resultado algo aleatorio: de vez en cuando, se asigna una imagen especial a los datos MIME del objeto de arrastre. El mapa de píxeles también se asigna como mapa de píxeles del objeto de arrastre. Esto garantizará que puedas ver la imagen que se está arrastrando como un mapa de píxeles bajo el cursor del ratón.
} else {
mime->setColorData(color);
mime->setText(QString("#%1%2%3")
.arg(color.red(), 2, 16, QLatin1Char('0'))
.arg(color.green(), 2, 16, QLatin1Char('0'))
.arg(color.blue(), 2, 16, QLatin1Char('0')));
QPixmap pixmap(34, 34);
pixmap.fill(Qt::white);
QPainter painter(&pixmap);
painter.translate(15, 15);
painter.setRenderHint(QPainter::Antialiasing);
paint(&painter, nullptr, nullptr);
painter.end();
pixmap.setMask(pixmap.createHeuristicMask());
drag->setPixmap(pixmap);
drag->setHotSpot(QPoint(15, 20));
}De lo contrario, y este es el resultado más habitual, se asigna un color sencillo a los datos MIME del objeto de arrastre. Representamos este ` ColorItem ` en un nuevo mapa de píxeles para proporcionar al usuario una indicación visual de que el color se está «arrastrando».
drag->exec();
setCursor(Qt::OpenHandCursor);
}Por último, ejecutamos el arrastre. ` QDrag::exec()` volverá a entrar en el bucle de eventos y solo saldrá si el arrastre se ha soltado o se ha cancelado. En cualquier caso, restablecemos el cursor a ` Qt::OpenHandCursor`.
La función main()
Ahora que las clases ` Robot ` y ` ColorItem ` están completas, podemos reunir todas las piezas dentro de la función `main()`.
int main(int argc, char **argv)
{
QApplication app(argc, argv);Empezamos creando un objeto ` QApplication` e inicializando el generador de números aleatorios. Esto garantiza que los elementos de color tengan colores diferentes cada vez que se inicie la aplicación.
QGraphicsScene scene(-200, -200, 400, 400);
for (int i = 0; i < 10; ++i) {
ColorItem *item = new ColorItem;
item->setPos(::sin((i * 6.28) / 10.0) * 150,
::cos((i * 6.28) / 10.0) * 150);
scene.addItem(item);
}
Robot *robot = new Robot;
robot->setTransform(QTransform::fromScale(1.2, 1.2), true);
robot->setPos(0, -20);
scene.addItem(robot);Creamos una escena de tamaño fijo y generamos 10 instancias de ` ColorItem ` dispuestas en círculo. Cada elemento se añade a la escena.
En el centro de este círculo creamos una instancia de ` Robot `. El robot se escala y se desplaza unas cuantas unidades hacia arriba. A continuación, se añade a la escena.
GraphicsView view(&scene);
view.setRenderHint(QPainter::Antialiasing);
view.setViewportUpdateMode(QGraphicsView::BoundingRectViewportUpdate);
view.setBackgroundBrush(QColor(230, 200, 167));
view.setWindowTitle("Drag and Drop Robot");
view.show();
return app.exec();
}Por último, creamos una ventana de « QGraphicsView » y le asignamos la escena.
Para mejorar la calidad visual, activamos el suavizado. También optamos por utilizar actualizaciones del rectángulo delimitador para simplificar la gestión de las actualizaciones visuales. A la vista se le asigna un fondo fijo de color arena y un título de ventana.
A continuación, mostramos la vista. Las animaciones comienzan inmediatamente después de que el control entre en el bucle de eventos.
© 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.