documented node view classes

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 */

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();

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();
 
 };

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:

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;

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_;
 
 };

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);