Toolbar Customization — Drag to Reorder, Show/Hide Buttons, Separator Management

[FTA7700]

Background

While working on PR #24090 (Add Open Destination Folder button to toolbar), a recurring theme emerged in the review: disagreement about where buttons should be positioned. @stalkerok suggested one position, @Chocobo1 another, @cocopaw raised menu-order conventions. All valid perspectives — but the underlying issue is that qBittorrent's toolbar is entirely hardcoded with no user control whatsoever.

If users could arrange the toolbar themselves, these debates become irrelevant. This discussion proposes a toolbar customization feature.

---

Proposed Features

1. Drag to reorder buttons (Core)

Left-click and drag any toolbar button to reposition it. A floating preview follows the cursor (constrained to the toolbar), the original button vanish as soon as the drag start, and a drop indicator line shows the insertion point. On release the button is placed at the closest position.

2. Show/Hide buttons (High priority)

Right-clicking on the empty toolbar area extends the existing context menu with a "Show/Hide Buttons" submenu — one checkbox per button. Includes a "Reset to Default" option at the top.

3. Separator management (Medium priority)

Right-clicking on a specific toolbar button shows a context-aware menu:

• "Add separator before" / "Remove separator before" depending on current state
• "Add separator after" / "Remove separator after" depending on current state

4. Persistence

All changes are saved immediately to Preferences under MainWindow/toolbarState and restored on startup.

• The spacer, column filter, and Lock button are excluded from all customization and remain in their fixed positions.
• There also would be a "Reset to Default" option, which will rollback to stock.

void MainWindow::saveToolbarState() const
{
    QStringList toolbarState;
    for (const QAction *action : m_ui->toolBar->actions())
    {
        if (action == m_spacerAction || action == m_columnFilterAction
            || action->objectName() == u"actionLock"_s)
            break;
        if (action->isSeparator())
            toolbarState << u"separator"_s;
        else
            toolbarState << QString(u"%1:%2"_s).arg(action->objectName(), action->isVisible() ? u"1"_s : u"0"_s);
    }
    Preferences::instance()->setToolbarState(toolbarState.join(u","_s).toUtf8());
}

---

Implementation Approach

A new class CustomizableToolBar subclasses QToolBar. This is the cleanest Qt pattern — QToolBar's child buttons are QToolButton widgets that consume mouse events before the toolbar sees them, so the only clean interception point is via event filters installed on each child widget through actionEvent, which is most naturally done in a subclass.

class CustomizableToolBar : public QToolBar
{
    Q_OBJECT
    Q_DISABLE_COPY_MOVE(CustomizableToolBar)

public:
    explicit CustomizableToolBar(QWidget *parent = nullptr);
    explicit CustomizableToolBar(const QString &title, QWidget *parent = nullptr);
    ~CustomizableToolBar() override = default;

    void lockAction(QAction *action);

Q_SIGNALS:
    void actionsReordered();

protected:
    void actionEvent(QActionEvent *event) override;
    bool eventFilter(QObject *watched, QEvent *event) override;
    void paintEvent(QPaintEvent *event) override;

private:
    QList<QAction *> m_lockedActions;
    QPoint m_dragStartPos;
    QPoint m_dropPos;
    QAction *m_draggedAction = nullptr;
    QLabel *m_floatingPreview = nullptr;
    bool m_isDragging = false;
};

Event filters are installed on each button widget as it is added to the toolbar via actionEvent:

void CustomizableToolBar::actionEvent(QActionEvent *event)
{
    QToolBar::actionEvent(event);
    if (event->type() == QEvent::ActionAdded)
    {
        QWidget *w = widgetForAction(event->action());
        if (w)
        {
            w->installEventFilter(this);
            w->setMouseTracking(true);
        }
    }
}

Fixed widgets (spacer, column filter, Lock) are protected via lockAction():

void CustomizableToolBar::lockAction(QAction *action)
{
    if (action && !m_lockedActions.contains(action))
        m_lockedActions.append(action);
}

Considered QDrag but rejected it — it propagates drop events to any widget under the cursor, causing unintended actions (e.g. releasing over the torrent list triggered Torrent Creator). The custom mouse-event approach keeps drag entirely within the toolbar.

Qt's built-in QMainWindow::saveState() was considered for persistence but only handles toolbar docking, not action order or visibility. Custom serialization was necessary.

Files changed:

• NEW: src/gui/customizabletoolbar.h / .cpp
• MODIFIED: src/gui/mainwindow.h / .cpp / .ui
• MODIFIED: src/gui/CMakeLists.txt
• MODIFIED: src/base/preferences.h / .cpp

---

If this is a direction the project would consider I'm ready to submit a PR if there's interest. Also open to feedback on the implementation approach.

[cocopaw]

No comment on the code/classdesign but the overall design concept and GUI mockup screenshots look great to me.

This has been talked about and requested before via the following issues (and possibly elsewhere too):

#20555

#16234

#1145

May I also suggest:

1. A "lock toolbar" function to place the toolbar in a state where its locked and users cant accidently move buttons around by dragging them as they click. Similarly an "unlock toolbar" function when it is in the locked(default) state.

2. Leaving the toolbar buttons in their default locations (attempting otherwise will likely lead to much disagreement and subsequent stalling)

p.s. If it were me id just go ahead and create the PR at this stage (this is a previously requested feature, its seems that you have already put considerable effort into it and you have code)

[FTA7700]

Thank you for the references — good to know this has been requested before.

Regarding the suggestions:

1. Lock toolbar — great idea and a natural fit. Will propose it as a toggle in the Toolbar buttons right-click menu ("Lock Toolbar" checkbox) that enables/disables drag reordering would prevent accidental moves during normal use. Will add this before submitting the PR.

2. Default button positions — already the case. The implementation only saves and restores user-defined state; the default layout remains unchanged for new installs or after "Reset to Default".

Will go ahead and submit the PR.

[FTA7700]

Implementation is now ready as a PR #24309