documented toolbar

app/widget/toolbar/toolbar.cpp

@@ -47,8 +47,7 @@ Toolbar::Toolbar(QWidget *parent) :
   btn_add_ = CreateToolButton(olive::icon::Add, olive::tool::kAdd);
 
   // Create snapping button, which is not actually a tool, it's a toggle option
-  btn_snapping_toggle_ = new ToolbarButton(this, olive::icon::Snapping, olive::tool::kNone);
-  layout_->addWidget(btn_snapping_toggle_);
+  btn_snapping_toggle_ = CreateNonToolButton(olive::icon::Snapping);
   connect(btn_snapping_toggle_, SIGNAL(clicked(bool)), this, SLOT(SnappingButtonClicked(bool)));
 
   Retranslate();
@@ -111,6 +110,17 @@ ToolbarButton* Toolbar::CreateToolButton(const QIcon &icon, const olive::tool::T
   return b;
 }
 
+ToolbarButton *Toolbar::CreateNonToolButton(const QIcon &icon)
+{
+  // Create a ToolbarButton object
+  ToolbarButton* b = new ToolbarButton(this, icon, olive::tool::kNone);
+
+  // Add it to the layout
+  layout_->addWidget(b);
+
+  return b;
+}
+
 void Toolbar::ToolButtonClicked()
 {
   // Get new tool from ToolbarButton object

app/widget/toolbar/toolbar.h

@@ -27,30 +27,130 @@
 #include "widget/toolbar/toolbarbutton.h"
 #include "tool/tool.h"
 
+/**
+ * @brief The Toolbar class
+ *
+ * A widget containing buttons for all of Olive's application-wide tools. Buttons are displayed in a FlowLayout that
+ * adjusts and wraps (like text) depending on the widget's size.
+ *
+ * By default, this Toolbar is not connected to anything. It's recommended to connect SLOT(SetTool()) and
+ * SIGNAL(ToolChanged()) to Core (corresponding SIGNAL(ToolChanged()) and SLOT(SetTool()) respectively) so that the
+ * Toolbar updates the current tool application-wide, and is also automatically updated when the tool is changed
+ * elsewhere.
+ */
 class Toolbar : public QWidget
 {
   Q_OBJECT
 public:
+  /**
+   * @brief Toolbar Constructor
+   *
+   * Creates and connects all the Toolbar buttons
+   *
+   * @param parent
+   *
+   * QWidget parent.
+   */
   Toolbar(QWidget* parent);
 
 public slots:
+  /**
+   * @brief Set the tool to be displayed as "selected"
+   *
+   * This function does not set the application-wide tool, it only sets which tool show as selected in this widget.
+   * It's recommended to use this function only as a slot connected to Core::ToolChanged() so that it automatically
+   * updates whenever the application-wide tool is changed.
+   *
+   * @param tool
+   *
+   * Tool to show as selected
+   */
   void SetTool(const olive::tool::Tool &tool);
+
+  /**
+   * @brief Set snapping checked value
+   *
+   * Similar to SetTool(), this does not set anything application-wide, it only changes the displayed button appearance.
+   * In this case, whether the snapping button should show as snapping enabled or disabled.
+   *
+   * @param snapping
+   */
   void SetSnapping(const bool &snapping);
 
 protected:
+  /**
+   * @brief Qt changeEvent
+   *
+   * Overridden to catch language change events (see Retranslate())
+   *
+   * @param e
+   */
   virtual void changeEvent(QEvent* e) override;
 
 signals:
-  void ToolChanged(const olive::tool::Tool&);
-  void SnappingChanged(const bool&);
+  /**
+   * @brief Emitted whenever a tool is selected using this widget
+   *
+   * @param t
+   *
+   * Tool that was selected
+   */
+  void ToolChanged(const olive::tool::Tool& t);
+
+  /**
+   * @brief Emitted whenever the snapping setting is changed
+   *
+   * @param b
+   *
+   * New snapping enabled setting
+   */
+  void SnappingChanged(const bool& b);
 
 private:
+  /**
+   * @brief Reset all strings based on the currently selected language
+   */
   void Retranslate();
 
+  /**
+   * @brief Internal convenience function for creating tool buttons quickly
+   *
+   * This function will create a ToolbarButton object, set the icon to `icon`, set its tool value to `tool`, add it to
+   * the widget layout, add it to toolbar_btns_ so the buttons can be iterated (done in various functions), and connect
+   * the button to ToolButtonClicked().
+   *
+   * If you need a non-tool but similarly styled button, use CreateNonToolButton().
+   *
+   * @return
+   *
+   * The created ToolbarButton. The button parent is automatically set to `this`.
+   */
   ToolbarButton* CreateToolButton(const QIcon &icon, const olive::tool::Tool& tool);
 
+  /**
+   * @brief Internal convenience function for creating buttons quickly
+   *
+   * Similar to CreateToolButton() but doesn't add the button to toolbar_btns_ and doesn't connect the button to
+   * ToolButtonClicked(). This is to create a button that is similarly styled but doesn't actually represent a tool
+   * per se.
+   *
+   * @return
+   *
+   * The created ToolbarButton. The button parent is automatically set to `this`.
+   */
+  ToolbarButton* CreateNonToolButton(const QIcon &icon);
+
+  /**
+   * @brief Internal layout used for buttons
+   */
   FlowLayout* layout_;
 
+  /**
+   * @brief Array/list of toolbar buttons
+   *
+   * This list is automatically appended by CreateToolButton(). It's used to iterate through the toolbar buttons
+   * quickly with for loops, etc. See SetTool() for example usage.
+   */
   QList<ToolbarButton*> toolbar_btns_;
 
   ToolbarButton* btn_pointer_tool_;
@@ -68,7 +168,26 @@ private:
   ToolbarButton* btn_snapping_toggle_;
 
 private slots:
+  /**
+   * @brief Slot for a ToolbarButton being clicked
+   *
+   * ToolbarButtons created from CreateToolButton() are automatically connected to this slot.
+   * This slot will receive the ToolbarButton's tool value
+   * and emit a signal indicating that the tool has changed to the newly selected tool. This function static_casts
+   * the sender to ToolbarButton so you should not connect any other class type to this slot.
+   */
   void ToolButtonClicked();
+
+  /**
+   * @brief Receiver for the snapping toggle button
+   *
+   * This function's primary purpose is to emit SnappingChanged() and should be connected to the ToolbarButton's
+   * SIGNAL(clicked(bool)).
+   *
+   * @param b
+   *
+   * The new snapping value received from the sender's clicked signal
+   */
   void SnappingButtonClicked(bool b);
 };
 

app/widget/toolbar/toolbarbutton.h

@@ -25,13 +25,41 @@
 
 #include "tool/tool.h"
 
+/**
+ * @brief The ToolbarButton class
+ *
+ * Simple derived class of QPushButton to contain an Tool ID. Used as the main widget through Toolbar.
+ */
 class ToolbarButton : public QPushButton
 {
 public:
+  /**
+   * @brief ToolbarButton Constructor
+   *
+   * @param parent
+   *
+   * QWidget parent. Almost always an instance of Toolbar.
+   *
+   * @param icon
+   *
+   * Icon to set this QWidget to.
+   *
+   * @param tool
+   *
+   * Tool object. Must be a member of enum olive::tool::Tool, including kNone if this button does not represent a tool.
+   */
   ToolbarButton(QWidget* parent, const QIcon& icon, const olive::tool::Tool& tool);
 
+  /**
+   * @brief Retrieve tool ID that this button represents
+   *
+   * Set in the constructor and shouldn't change throughout its lifetime.
+   */
   const olive::tool::Tool& tool();
 private:
+  /**
+   * @brief Internal tool value
+   */
   olive::tool::Tool tool_;
 };