Elastic Nodes Example 翻译及学习整理

Elastic Nodes Example 翻译及学习整理

题记：

因为最近的一个项目需要实现图像交互，好在Qt有现成的一些示例。示例是全英文的，还是翻译整理一遍，这样印象会更深刻些。

简介：

该示例演示了如何实现在场景中的图形交互。

具体有一下几个方面：
1、在交互（如鼠标拖放键盘敲击等）过程中如何实现节点之间的连线。
2、实现基本的一些交互，鼠标单击、拖放节点。鼠标滚轮缩放视图。空格键让节点位置随机变化。

我们知道，QGraphicsView 帮助GraphicsScene c类更好的实现图形项的交互，如缩放和旋转。

本示例的程序文档结构很简单，主要由 一个Node class, 一个 Edge class,还有 GraphWidget组成。
其中 Node class 实现的是小圆球的节点，Edge class实现的是节点之间的连线，GraphWidge class 实现的是一个窗体。main()函数实现窗体的显示，以及事件的循环。

Node Class Definition

该类实现的三个主要目标：

1、绘制具有极性渐变填充的小圆球。

2、实现与其他小球的交互。

3、计算拖拽的拉力，从而拉动各个节点。

以下是该类的声明部分

 class Node : public QGraphicsItem
 {
 public:
     Node(GraphWidget *graphWidget);

     void addEdge(Edge *edge);
     QList<Edge *> edges() const;

     enum { Type = UserType + 1 };
     int type() const override { return Type; }

     void calculateForces();
     bool advancePosition();

     QRectF boundingRect() const override;
     QPainterPath shape() const override;
     void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget) override;

 protected:
     QVariant itemChange(GraphicsItemChange change, const QVariant &value) override;

     void mousePressEvent(QGraphicsSceneMouseEvent *event) override;
     void mouseReleaseEvent(QGraphicsSceneMouseEvent *event) override;

 private:
     QList<Edge *> edgeList;
     QPointF newPos;
     GraphWidget *graph;
 };

首先，Node class 继承自QGraphicsItem，从而重写两个强制的函数boundingRect() and paint() 来实现图形绘制。 通过重写shape() 来确保碰撞检测。

为了实现节点间连线的管理控制，该类同时提供了API来增加节点间的连线，以及列表的方式来管理各个相互连接的节点。

advancePosition() 来实现节点的步进。
calculateForces() 来计算拖拽的力度，从而使得临近的节点发生相应的移动。

itemChange() 来相应状态的变化（如节点位置发生变化时），mousePressEvent() and mouseReleaseEvent() 来更新图像项的显示。

接着，我们来看下Node 的构造函数：

 Node::Node(GraphWidget *graphWidget)
     : graph(graphWidget)
 {
     setFlag(ItemIsMovable);
     setFlag(ItemSendsGeometryChanges);
     setCacheMode(DeviceCoordinateCache);
     setZValue(-1);
 }

在构造函数中，
旗标ItemIsMovable 设置图形项是可以被移动。
旗标ItemSendsGeometryChanges 确保itemChange() 通知位置发生移动。
DeviceCoordinateCache用来加速图形的渲染。
为了确保节点始终显示在“连线”的上层（碰撞检测时有用），这里我们设置图形项的Z值为-1.

在构造函数里还设置了一个GraphWidget 指针，用来存储“this”指针，因为我们过会访问到。

 void Node::addEdge(Edge *edge)
 {
     edgeList << edge;
     edge->adjust();
 }

 QList<Edge *> Node::edges() const
 {
     return edgeList;
 }```


addEdge() 添加与图形相关的连线。如果当节点的位置发生改变是，连接也会相应改变。

edges() 返回节点相关联的连线列表。

```cpp
 void Node::calculateForces()
 {
     if (!scene() || scene()->mouseGrabberItem() == this) {
         newPos = pos();
         return;
     }

有两种方式来实现节点的移动。calculateForces()计算拖拽的弹力。另外，用户可以直接拖拽鼠标点中的节点。

 // Sum up all forces pushing this item away
     qreal xvel = 0;
     qreal yvel = 0;
     foreach (QGraphicsItem *item, scene()->items()) {
         Node *node = qgraphicsitem_cast<Node *>(item);
         if (!node)
             continue;

         QPointF vec = mapToItem(node, 0, 0);
         qreal dx = vec.x();
         qreal dy = vec.y();
         double l = 2.0 * (dx * dx + dy * dy);
         if (l > 0) {
             xvel += (dx * 150.0) / l;
             yvel += (dy * 150.0) / l;
         }
     }

弹力的计算是通过一个算法来实现。

该算法有两个步骤：
1、计算使得节点分离的力。
2、减去使得节点聚集的力。

首先，我们需要查找所有的节点。

接着我们用mapToItem（），来记录每个节点的在场景坐标系中的位置。这个位置信息将用来计算拖拽弹力的大小和方向。我们计算每个节点之间力的总和，然后调整分配，最近的节点获得的力最大。力度的总和记录在两个变量 xvel，yvel

接着我们计算节点间聚集的力

     // Now subtract all forces pulling items together
     double weight = (edgeList.size() + 1) * 10;
     foreach (Edge *edge, edgeList) {
         QPointF vec;
         if (edge->sourceNode() == this)
             vec = mapToItem(edge->destNode(), 0, 0);
         else
             vec = mapToItem(edge->sourceNode(), 0, 0);
         xvel -= vec.x() / weight;
         yvel -= vec.y() / weight;
     }

节点间连线的长度决定聚集的力的大小。通过遍历与当前节点相连的每个连线，我们可以使用类似上面的方法来计算得到聚集里的大小和方向。该力从xvel ，yvel减去得到。

 if (qAbs(xvel) < 0.1 && qAbs(yvel) < 0.1)
     xvel = yvel = 0;

从物理理论上来讲，拖拽的分离的力，和节点间聚合的力会趋向平衡的。由于计算的精度引起的误差，我们这里设置当<0.1 时候，就认为是0；

     QRectF sceneRect = scene()->sceneRect();
     newPos = pos() + QPointF(xvel, yvel);
     newPos.setX(qMin(qMax(newPos.x(), sceneRect.left() + 10), sceneRect.right() - 10));
     newPos.setY(qMin(qMax(newPos.y(), sceneRect.top() + 10), sceneRect.bottom() - 10));
 }

最后我们决定节点的新位置。同时我们保证新的坐标位置仍然在我们设定的边界内。我们这里没有移动图形项，移动的功能实现交给了advancePosition()

 bool Node::advancePosition()
 {
     if (newPos == pos())
         return false;

     setPos(newPos);
     return true;
 }

advancePosition()实现了节点位置的更新，通过调用GraphWidget::timerEvent()来实现。

 QRectF Node::boundingRect() const
 {
     qreal adjust = 2;
     return QRectF( -10 - adjust, -10 - adjust, 23 + adjust, 23 + adjust);
 }

节点的边界矩形的大小是20x20，修正值2，是为了补偿边框的粗细大小。3 个单位的值会了在绘制底部的阴影。

QPainterPath Node::shape() const
{
QPainterPath path;
path.addEllipse(-10, -10, 20, 20);
return path;
}

节点的形状是一个简单的椭圆。确保图中拽时，单击的是节点的内部。

 void Node::paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *)
 {
     painter->setPen(Qt::NoPen);
     painter->setBrush(Qt::darkGray);
     painter->drawEllipse(-7, -7, 20, 20);

     QRadialGradient gradient(-3, -3, 10);
     if (option->state & QStyle::State_Sunken) {
         gradient.setCenter(3, 3);
         gradient.setFocalPoint(3, 3);
         gradient.setColorAt(1, QColor(Qt::yellow).light(120));
         gradient.setColorAt(0, QColor(Qt::darkYellow).light(120));
     } else {
         gradient.setColorAt(0, Qt::yellow);
         gradient.setColorAt(1, Qt::darkYellow);
     }
     painter->setBrush(gradient);

     painter->setPen(QPen(Qt::black, 0));
     painter->drawEllipse(-10, -10, 20, 20);
 }

该函数实现的是节点的绘制。一开始我们我们绘制一个灰黑的阴影。

然后我们绘制一个有极性渐变填充的圆。带有渲染填充会比较慢，这就是所以我们一开始就设置DeviceCoordinateCache的原因。该设置可以有效确保不必要的重绘功能。

 QVariant Node::itemChange(GraphicsItemChange change, const QVariant &value)
 {
     switch (change) {
     case ItemPositionHasChanged:
         foreach (Edge *edge, edgeList)
             edge->adjust();
         graph->itemMoved();
         break;
     default:
         break;
     };

     return QGraphicsItem::itemChange(change, value);
 }

itemChange() 会调整所有连接的节点的位置，这同时也将触发计算新的force calculations.

这里就是我们为什么要留一个GraphWidget的指针。还有一种同样实现的方式，那就是运用信号槽关联，但是这样的话，Node 需要继承QGraphicsObject.

 void Node::mousePressEvent(QGraphicsSceneMouseEvent *event)
 {
     update();
     QGraphicsItem::mousePressEvent(event);
 }

 void Node::mouseReleaseEvent(QGraphicsSceneMouseEvent *event)
 {
     update();
     QGraphicsItem::mouseReleaseEvent(event);
 }

因为我们已经设置的图形是可移动的旗标，所以我们不需要记录实现鼠标交互时候的坐标，因为它已经提供给我们了，我们只需要重写该函数的句柄就可以了。

Edge Class Definition

该类实现了带箭头的连线。
它包含了指向源节点和目标节点的指针。
提供了adjust() 来保证始终从源节点到目标节点的连线。
下面来看该类的声明：

Let's take a look at the class declaration:
 class Edge : public QGraphicsItem
 {
 public:
     Edge(Node *sourceNode, Node *destNode);

     Node *sourceNode() const;
     Node *destNode() const;

     void adjust();

     enum { Type = UserType + 2 };
     int type() const override { return Type; }

 protected:
     QRectF boundingRect() const override;
     void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget) override;

 private:
     Node *source, *dest;

     QPointF sourcePoint;
     QPointF destPoint;
     qreal arrowSize;
 };

Edge 继承了QGraphicsItem,它非常简单，没有信号 与槽，没有属性。它的构造函数里有两个指针。我们还提供了提取该两个指针的函数。

 Edge::Edge(Node *sourceNode, Node *destNode)
     : arrowSize(10)
 {
     setAcceptedMouseButtons(0);
     source = sourceNode;
     dest = destNode;
     source->addEdge(this);
     dest->addEdge(this);
     adjust();
 }

构造函数中初始化了arrowSize 这个变量。
setAcceptedMouseButtons(0). 不接受鼠标的按钮事件。
更新连线的两个指针，并通过adjust()来更新连线的起点和终点位置。

Node *Edge::sourceNode() const
{
return source;
}

Node *Edge::destNode() const
{
return dest;
}

返回当前连线的节点的指针。

 void Edge::adjust()
 {
     if (!source || !dest)
         return;

     QLineF line(mapFromItem(source, 0, 0), mapFromItem(dest, 0, 0));
     qreal length = line.length();

     prepareGeometryChange();

     if (length > qreal(20.)) {
         QPointF edgeOffset((line.dx() * 10) / length, (line.dy() * 10) / length);
         sourcePoint = line.p1() + edgeOffset;
         destPoint = line.p2() - edgeOffset;
     } else {
         sourcePoint = destPoint = line.p1();
     }
 }

这里为了箭头在节点的轮廓上，而不是节点的中心，我们这里做了edgeOffset补偿。

如果vector 小于20，比如节点重合了。这里我们让两个指针够指向同一个源节点。实际上，这是难易发生的。

prepareGeometryChange() 为了使得返回boundingRect()

 QRectF Edge::boundingRect() const
 {
     if (!source || !dest)
         return QRectF();

     qreal penWidth = 1;
     qreal extra = (penWidth + arrowSize) / 2.0;

     return QRectF(sourcePoint, QSizeF(destPoint.x() - sourcePoint.x(),
                                       destPoint.y() - sourcePoint.y()))
         .normalized()
         .adjusted(-extra, -extra, extra, extra);
 }

边界矩形的定义。

 void Edge::paint(QPainter *painter, const QStyleOptionGraphicsItem *, QWidget *)
 {
     if (!source || !dest)
         return;

     QLineF line(sourcePoint, destPoint);
     if (qFuzzyCompare(line.length(), qreal(0.)))
         return;

绘制连线时，我们这里设置了两个异常的返回。

  // Draw the line itself
     painter->setPen(QPen(Qt::black, 1, Qt::SolidLine, Qt::RoundCap, Qt::RoundJoin));
     painter->drawLine(line);

     // Draw the arrows
     double angle = std::atan2(-line.dy(), line.dx());

     QPointF sourceArrowP1 = sourcePoint + QPointF(sin(angle + M_PI / 3) * arrowSize,
                                                   cos(angle + M_PI / 3) * arrowSize);
     QPointF sourceArrowP2 = sourcePoint + QPointF(sin(angle + M_PI - M_PI / 3) * arrowSize,
                                                   cos(angle + M_PI - M_PI / 3) * arrowSize);
     QPointF destArrowP1 = destPoint + QPointF(sin(angle - M_PI / 3) * arrowSize,
                                               cos(angle - M_PI / 3) * arrowSize);
     QPointF destArrowP2 = destPoint + QPointF(sin(angle - M_PI + M_PI / 3) * arrowSize,
                                               cos(angle - M_PI + M_PI / 3) * arrowSize);

     painter->setBrush(Qt::black);
     painter->drawPolygon(QPolygonF() << line.p1() << sourceArrowP1 << sourceArrowP2);
     painter->drawPolygon(QPolygonF() << line.p2() << destArrowP1 << destArrowP2);
 }

绘制连线和箭头

GraphWidget Class Definition

GraphWidget 是QGraphicsView的子类。

 class GraphWidget : public QGraphicsView
 {
     Q_OBJECT

 public:
     GraphWidget(QWidget *parent = 0);

     void itemMoved();

 public slots:
     void shuffle();
     void zoomIn();
     void zoomOut();

 protected:
     void keyPressEvent(QKeyEvent *event) override;
     void timerEvent(QTimerEvent *event) override;
 #if QT_CONFIG(wheelevent)
     void wheelEvent(QWheelEvent *event) override;
 #endif
     void drawBackground(QPainter *painter, const QRectF &rect) override;

     void scaleView(qreal scaleFactor);

 private:
     int timerId;
     Node *centerNode;
 };

该类，初始化了场景。
提供了itemMoved() 来告知场景中的图形发生了变化。一些事件的重载。以及背景的绘制，视图的缩放。

 GraphWidget::GraphWidget(QWidget *parent)
     : QGraphicsView(parent), timerId(0)
 {
     QGraphicsScene *scene = new QGraphicsScene(this);
     scene->setItemIndexMethod(QGraphicsScene::NoIndex);
     scene->setSceneRect(-200, -200, 400, 400);
     setScene(scene);
     setCacheMode(CacheBackground);
     setViewportUpdateMode(BoundingRectViewportUpdate);
     setRenderHint(QPainter::Antialiasing);
     setTransformationAnchor(AnchorUnderMouse);
     scale(qreal(0.8), qreal(0.8));
     setMinimumSize(400, 400);
     setWindowTitle(tr("Elastic Nodes"));

这里初始化了场景，还有设置了场景的大小。
setCacheMode(CacheBackground); 缓存静态背景。
setViewportUpdateMode(BoundingRectViewportUpdate); 设置视图的更新模式。
setRenderHint(QPainter::Antialiasing);抗锯齿。
setTransformationAnchor(AnchorUnderMouse);缩放时以鼠标为中心。

    Node *node1 = new Node(this);
     Node *node2 = new Node(this);
     Node *node3 = new Node(this);
     Node *node4 = new Node(this);
     centerNode = new Node(this);
     Node *node6 = new Node(this);
     Node *node7 = new Node(this);
     Node *node8 = new Node(this);
     Node *node9 = new Node(this);
     scene->addItem(node1);
     scene->addItem(node2);
     scene->addItem(node3);
     scene->addItem(node4);
     scene->addItem(centerNode);
     scene->addItem(node6);
     scene->addItem(node7);
     scene->addItem(node8);
     scene->addItem(node9);
     scene->addItem(new Edge(node1, node2));
     scene->addItem(new Edge(node2, node3));
     scene->addItem(new Edge(node2, centerNode));
     scene->addItem(new Edge(node3, node6));
     scene->addItem(new Edge(node4, node1));
     scene->addItem(new Edge(node4, centerNode));
     scene->addItem(new Edge(centerNode, node6));
     scene->addItem(new Edge(centerNode, node8));
     scene->addItem(new Edge(node6, node9));
     scene->addItem(new Edge(node7, node4));
     scene->addItem(new Edge(node8, node7));
     scene->addItem(new Edge(node9, node8));

     node1->setPos(-50, -50);
     node2->setPos(0, -50);
     node3->setPos(50, -50);
     node4->setPos(-50, 0);
     centerNode->setPos(0, 0);
     node6->setPos(50, 0);
     node7->setPos(-50, 50);
     node8->setPos(0, 50);
     node9->setPos(50, 50);
 }

初始化节点和连线。

 void GraphWidget::itemMoved()
 {
     if (!timerId)
         timerId = startTimer(1000 / 25);
 }

GraphWidget 会监测节点的移动。通过定时器事件来更新节点的位置。

 void GraphWidget::keyPressEvent(QKeyEvent *event)
 {
     switch (event->key()) {
     case Qt::Key_Up:
         centerNode->moveBy(0, -20);
         break;
     case Qt::Key_Down:
         centerNode->moveBy(0, 20);
         break;
     case Qt::Key_Left:
         centerNode->moveBy(-20, 0);
         break;
     case Qt::Key_Right:
         centerNode->moveBy(20, 0);
         break;
     case Qt::Key_Plus:
         zoomIn();
         break;
     case Qt::Key_Minus:
         zoomOut();
         break;
     case Qt::Key_Space:
     case Qt::Key_Enter:
         shuffle();
         break;
     default:
         QGraphicsView::keyPressEvent(event);
     }
 }

键盘事件的实现。

 void GraphWidget::timerEvent(QTimerEvent *event)
 {
     Q_UNUSED(event);

     QList<Node *> nodes;
     foreach (QGraphicsItem *item, scene()->items()) {
         if (Node *node = qgraphicsitem_cast<Node *>(item))
             nodes << node;
     }

     foreach (Node *node, nodes)
         node->calculateForces();

     bool itemsMoved = false;
     foreach (Node *node, nodes) {
         if (node->advancePosition())
             itemsMoved = true;
     }

     if (!itemsMoved) {
         killTimer(timerId);
         timerId = 0;
     }
 }

每次只要计时器开启，该句柄会查找所有的节点，通过计算拖拽的力，然后更新节点的位置。通过advance()的返回值，若果是false，则停止定时器。

 void GraphWidget::wheelEvent(QWheelEvent *event)
 {
     scaleView(pow((double)2, -event->delta() / 240.0));
 }

鼠标的滚轮缩放。

 void GraphWidget::drawBackground(QPainter *painter, const QRectF &rect)
 {
     Q_UNUSED(rect);

     // Shadow
     QRectF sceneRect = this->sceneRect();
     QRectF rightShadow(sceneRect.right(), sceneRect.top() + 5, 5, sceneRect.height());
     QRectF bottomShadow(sceneRect.left() + 5, sceneRect.bottom(), sceneRect.width(), 5);
     if (rightShadow.intersects(rect) || rightShadow.contains(rect))
         painter->fillRect(rightShadow, Qt::darkGray);
     if (bottomShadow.intersects(rect) || bottomShadow.contains(rect))
         painter->fillRect(bottomShadow, Qt::darkGray);

     // Fill
     QLinearGradient gradient(sceneRect.topLeft(), sceneRect.bottomRight());
     gradient.setColorAt(0, Qt::white);
     gradient.setColorAt(1, Qt::lightGray);
     painter->fillRect(rect.intersected(sceneRect), gradient);
     painter->setBrush(Qt::NoBrush);
     painter->drawRect(sceneRect);

     // Text
     QRectF textRect(sceneRect.left() + 4, sceneRect.top() + 4,
                     sceneRect.width() - 4, sceneRect.height() - 4);
     QString message(tr("Click and drag the nodes around, and zoom with the mouse "
                        "wheel or the '+' and '-' keys"));

     QFont font = painter->font();
     font.setBold(true);
     font.setPointSize(14);
     painter->setFont(font);
     painter->setPen(Qt::lightGray);
     painter->drawText(textRect.translated(2, 2), message);
     painter->setPen(Qt::black);
     painter->drawText(textRect, message);
 }

背景的绘制，

 void GraphWidget::scaleView(qreal scaleFactor)
 {
     qreal factor = transform().scale(scaleFactor, scaleFactor).mapRect(QRectF(0, 0, 1, 1)).width();
     if (factor < 0.07 || factor > 100)
         return;

     scale(scaleFactor, scaleFactor);
 }

滚轮幅度的计算。

The main() Function

int main(int argc, char **argv)
{
    QApplication app(argc, argv);

    GraphWidget *widget = new GraphWidget;

    QMainWindow mainWindow;
    mainWindow.setCentralWidget(widget);

    mainWindow.show();
    return app.exec();
}

main（)函数很简单，创建了QApplication、mainWindows、GraphWidget，开启了事件循环。

ps:花了一天的时间阅读完了，真的是一段段翻译下来。这个过程还是很耗精力的。移动算法部分是本应用程序的精妙之处，和物理学上的力的合成和分解有关，这里用到定时器来模拟橡筋的力的传递过程，非常有意思。算法部分还是有一定难度，等过后慢慢调试理解吧。