diff --git a/app/widget/toolbar/toolbar.cpp b/app/widget/toolbar/toolbar.cpp index 79de3dd63..b8c5c2a0d 100644 --- a/app/widget/toolbar/toolbar.cpp +++ b/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 diff --git a/app/widget/toolbar/toolbar.h b/app/widget/toolbar/toolbar.h index 3b561a277..bbbb03bb4 100644 --- a/app/widget/toolbar/toolbar.h +++ b/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 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); }; diff --git a/app/widget/toolbar/toolbarbutton.h b/app/widget/toolbar/toolbarbutton.h index d9da14046..aa4724fc6 100644 --- a/app/widget/toolbar/toolbarbutton.h +++ 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_; };