From 9633028f998d78d1a3a65054e7a4d1265391f35d Mon Sep 17 00:00:00 2001 From: itsmattkc Date: Wed, 17 Jul 2019 15:31:34 -0400 Subject: [PATCH] documented node view classes --- app/project/item/sequence/sequence.h | 6 +++ app/widget/nodeview/nodeview.cpp | 10 ++++ app/widget/nodeview/nodeview.h | 53 ++++++++++++++++++++ app/widget/nodeview/nodeviewedge.h | 31 ++++++++++++ app/widget/nodeview/nodeviewitem.cpp | 4 ++ app/widget/nodeview/nodeviewitem.h | 74 ++++++++++++++++++++++++++-- app/widget/nodeview/nodeviewundo.h | 10 ++++ 7 files changed, 184 insertions(+), 4 deletions(-) diff --git a/app/project/item/sequence/sequence.h b/app/project/item/sequence/sequence.h index 249c69318..a995a4d25 100644 --- a/app/project/item/sequence/sequence.h +++ b/app/project/item/sequence/sequence.h @@ -25,11 +25,17 @@ #include "node/graph.h" #include "project/item/item.h" +/** + * @brief The main timeline object, an graph of edited clips that forms a complete edit + */ class Sequence : public Item, public NodeGraph { public: Sequence(); + /** + * @brief Item::Type() override + */ virtual Type type() const override; /* VIDEO GETTER/SETTER FUNCTIONS */ diff --git a/app/widget/nodeview/nodeview.cpp b/app/widget/nodeview/nodeview.cpp index f8f9c9ef1..e67e8f6a6 100644 --- a/app/widget/nodeview/nodeview.cpp +++ b/app/widget/nodeview/nodeview.cpp @@ -111,6 +111,16 @@ NodeViewEdge *NodeView::EdgeToUIObject(QGraphicsScene *scene, NodeEdgePtr n) return nullptr; } +NodeViewItem *NodeView::NodeToUIObject(Node *n) +{ + return NodeToUIObject(&scene_, n); +} + +NodeViewEdge *NodeView::EdgeToUIObject(NodeEdgePtr n) +{ + return EdgeToUIObject(&scene_, n); +} + void NodeView::AddEdge(NodeEdgePtr edge) { NodeViewEdge* edge_ui = new NodeViewEdge(); diff --git a/app/widget/nodeview/nodeview.h b/app/widget/nodeview/nodeview.h index 77e4d8204..f5a6b28b8 100644 --- a/app/widget/nodeview/nodeview.h +++ b/app/widget/nodeview/nodeview.h @@ -27,27 +27,80 @@ #include "widget/nodeview/nodeviewedge.h" #include "widget/nodeview/nodeviewitem.h" +/** + * @brief A widget for viewing and editing node graphs + * + * This widget takes a NodeGraph object and constructs a QGraphicsScene representing its data, viewing and allowing + * the user to make modifications to it. + */ class NodeView : public QGraphicsView { Q_OBJECT public: NodeView(QWidget* parent); + /** + * @brief Sets the graph to view + */ void SetGraph(NodeGraph* graph); + /** + * @brief Retrieve the graphical widget corresponding to a specific Node + * + * In situations where you know what Node you're working with but need the UI object (e.g. for positioning), this + * static function will retrieve the NodeViewItem (Node UI representation) connected to this Node in a certain + * QGraphicsScene. This can be called from any other UI object, since it'll have a reference to the QGraphicsScene + * through QGraphicsItem::scene(). + * + * If the scene does not contain a widget for this node (usually meaning the node's graph is not the active graph + * in this view/scene), this function returns nullptr. + */ static NodeViewItem* NodeToUIObject(QGraphicsScene* scene, Node* n); + + /** + * @brief Retrieve the graphical widget corresponding to a specific NodeEdge + * + * Same as NodeToUIObject() but returns a NodeViewEdge corresponding to a NodeEdgePtr instead. + */ static NodeViewEdge* EdgeToUIObject(QGraphicsScene* scene, NodeEdgePtr n); + /** + * @brief Overloaded NodeToUIObject(QGraphicsScene* scene, Node* n) if you have direct access to a NodeView instance + */ + NodeViewItem* NodeToUIObject(Node* n); + + /** + * @brief Overloaded EdgeToUIObject(QGraphicsScene* scene, NodeEdgePtr n) if you have direct access to a NodeView instance + */ + NodeViewEdge* EdgeToUIObject(NodeEdgePtr n); + private: NodeGraph* graph_; QGraphicsScene scene_; private slots: + /** + * @brief Slot when an edge is added to a graph (SetGraph() connects this) + * + * This should NEVER be called directly, only connected to a NodeGraph. To add an edge (i.e. connect two node + * parameters together), use NodeParam::ConnectEdge(). + */ void AddEdge(NodeEdgePtr edge); + /** + * @brief Slot when an edge is removed from a graph (SetGraph() connects this) + * + * This should NEVER be called directly, only connected to a NodeGraph. To remove an edge (i.e. disconnect two node + * parameters), use NodeParam::DisconnectEdge(). + */ void RemoveEdge(NodeEdgePtr edge); + /** + * @brief Internal function triggered when any change is signalled from the QGraphicsScene + * + * Current primary function is to inform all NodeViewEdges to re-adjust in case any Nodes have moved + */ void ItemsChanged(); }; diff --git a/app/widget/nodeview/nodeviewedge.h b/app/widget/nodeview/nodeviewedge.h index be58620a8..a17c6209d 100644 --- a/app/widget/nodeview/nodeviewedge.h +++ b/app/widget/nodeview/nodeviewedge.h @@ -25,16 +25,47 @@ #include "node/edge.h" +/** + * @brief A graphical representation of a NodeEdge to be used in NodeView + * + * A fairly simple line widget use to visualize a connection between two node parameters (a NodeEdge). + */ class NodeViewEdge : public QGraphicsLineItem { public: NodeViewEdge(QGraphicsItem* parent = nullptr); + /** + * @brief Set the edge that this item corresponds to + * + * This can be changed at any time (but under most circumstances won't be). Calling this will automatically call + * Adjust() to move this item into the correct position. + */ void SetEdge(NodeEdgePtr edge); NodeEdgePtr edge(); + /** + * @brief Moves/updates this line to visually connect between the two corresponding NodeViewItems + * + * Using the attached edge (see SetEdge()), this function retrieves the NodeViewItems representing the two nodes + * that this edge connects. It uses their positions to determine where the line should visually connect and sets + * it accordingly. + * + * This should be set any time the NodeEdge changes (see SetEdge()), and any time the nodes move in the NodeGraph + * (see NodeView::ItemsChanged()). This will keep the nodes visually connected at all times. + */ void Adjust(); + /** + * @brief Set the connected state of this line + * + * When the edge is not connected, it visually depicts this by coloring the line grey. When an edge is connected or + * a potential connection is valid, the line is colored white. This function sets whether the line should be grey + * (false) or white (true). + * + * Using SetEdge() automatically sets this to true. Under most circumstances this should be left alone, and only + * be set when an edge is being created/dragged. + */ void SetConnected(bool c); protected: diff --git a/app/widget/nodeview/nodeviewitem.cpp b/app/widget/nodeview/nodeviewitem.cpp index 58842b17a..a488fa860 100644 --- a/app/widget/nodeview/nodeviewitem.cpp +++ b/app/widget/nodeview/nodeviewitem.cpp @@ -93,6 +93,10 @@ bool NodeViewItem::IsExpanded() void NodeViewItem::SetExpanded(bool e) { + if (expanded_ = e) { + return; + } + expanded_ = e; QRectF new_rect; diff --git a/app/widget/nodeview/nodeviewitem.h b/app/widget/nodeview/nodeviewitem.h index 47b10632c..4fa76c716 100644 --- a/app/widget/nodeview/nodeviewitem.h +++ b/app/widget/nodeview/nodeviewitem.h @@ -31,21 +31,50 @@ #include "nodeviewedge.h" #include "nodeviewitemwidgetproxy.h" +/** + * @brief A visual widget representation of a Node object to be used in a NodeView + * + * This widget can be collapsed or expanded to show/hide the node's various parameters. + * + * To retrieve the NodeViewItem for a certain Node, use NodeView::NodeToUIObject(). + */ class NodeViewItem : public QGraphicsRectItem { public: NodeViewItem(QGraphicsItem* parent = nullptr); + /** + * @brief Set the Node to correspond to this widget + */ void SetNode(Node* n); + + /** + * @brief Get currently attached noe + */ Node* node(); + /** + * @brief Get expanded state + */ bool IsExpanded(); + + /** + * @brief Set expanded state + */ void SetExpanded(bool e); + /** + * @brief Get the rectangle of a specific parameter connector + * + * Useful for drawing parameter connectors (white squares where the Node edges attach) or determining whether a click + * or drag occurred within one. + * + * @param index + * + * Index of the parameter of this node (see NodeParam::index()). + */ QRectF GetParameterConnectorRect(int index); - QPointF GetParameterTextPoint(int index); - protected: virtual void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget = nullptr) override; @@ -54,21 +83,43 @@ protected: virtual void mouseReleaseEvent(QGraphicsSceneMouseEvent *event) override; private: + /** + * @brief Get the relative position to draw text for a parameter at a certain index + */ + QPointF GetParameterTextPoint(int index); + + /** + * @brief Variable for the expand/collapse button rect (stored for clicking) + */ QRectF expand_hitbox_; + /** + * @brief Reference to attached Node + */ Node* node_; + /** + * @brief A QWidget that can receive CSS properties that NodeViewItem can use + * + * \see NodeViewItemWidget + */ NodeViewItemWidget css_proxy_; + /** + * @brief Rectangle of the Node's title bar (equal to rect() when collapsed) + */ QRectF title_bar_rect_; + /** + * @brief Rectangle of the Node's content (zero-size when collapsed, (rect() - title_bar_rect_) when expanded) + */ QRectF content_rect_; + /// Used to determine certain padding/margin variables for high DPI support QFont font; - QFontMetrics font_metrics; - // Edge dragging variables + /// Edge dragging variables NodeViewEdge* dragging_edge_; QPointF dragging_edge_start_; NodeParam* drag_src_param_; @@ -76,15 +127,30 @@ private: NodeViewItem* drag_source_; NodeViewItem* drag_expanded_item_; + /// Sizing variables to use when drawing int node_connector_size_; int node_text_padding_; int node_icon_padding_; int node_border_width_; + /** + * @brief Expanded state + */ bool expanded_; + /** + * @brief Current click mode + * + * \see mousePressEvent() + */ bool standard_click_; + /** + * @brief QUndoCommand for creating and deleting edges by dragging + * + * \see mousePressEvent() + * \see mouseReleaseEvent() + */ QUndoCommand* node_edge_change_command_; }; diff --git a/app/widget/nodeview/nodeviewundo.h b/app/widget/nodeview/nodeviewundo.h index 256a24537..6376dd986 100644 --- a/app/widget/nodeview/nodeviewundo.h +++ b/app/widget/nodeview/nodeviewundo.h @@ -5,6 +5,11 @@ #include "node/node.h" +/** + * @brief An undoable commnd for connecting two NodeParams together + * + * Can be considered a QUndoCommand wrapper for NodeParam::ConnectEdge()/ + */ class NodeEdgeAddCommand : public QUndoCommand { public: NodeEdgeAddCommand(NodeOutput* output, NodeInput* input, QUndoCommand* parent = nullptr); @@ -21,6 +26,11 @@ private: bool done_; }; +/** + * @brief An undoable commnd for disconnecting two NodeParams + * + * Can be considered a QUndoCommand wrapper for NodeParam::DisonnectEdge()/ + */ class NodeEdgeRemoveCommand : public QUndoCommand { public: NodeEdgeRemoveCommand(NodeOutput* output, NodeInput* input, QUndoCommand* parent = nullptr);