Simpler API to link actions to QgsDockWidget

python/gui/auto_generated/qgsdockwidget.sip.in

@@ -47,6 +47,25 @@ any other tabs.
 .. seealso:: :py:func:`setUserVisible`
 
 .. seealso:: :py:func:`toggleUserVisible`
+%End
+
+    void setLinkedAction( QAction *action );
+%Docstring
+Links an ``action`` to the dock, so that toggling the action will automatically set the dock's visibility
+to suit (and changing the dock visibility will update the action's state).
+
+.. seealso:: :py:func:`linkedAction`
+
+.. versionadded:: 3.4
+%End
+
+    QAction *linkedAction();
+%Docstring
+Returns the action linked to the dock.
+
+.. seealso:: :py:func:`setLinkedAction`
+
+.. versionadded:: 3.4
 %End
 
   public slots:

src/gui/qgsdockwidget.cpp

@@ -17,6 +17,7 @@
 
 
 #include "qgsdockwidget.h"
+#include <QAction>
 
 
 QgsDockWidget::QgsDockWidget( QWidget *parent, Qt::WindowFlags flags )
@@ -57,6 +58,27 @@ bool QgsDockWidget::isUserVisible() const
   return mVisibleAndActive;
 }
 
+void QgsDockWidget::setLinkedAction( QAction *action )
+{
+  mAction = action;
+  if ( !mAction->isCheckable() )
+    mAction->setCheckable( true );
+  mAction->setChecked( isUserVisible() );
+  connect( mAction, &QAction::toggled, this, [ = ]( bool visible )
+  {
+    setUserVisible( visible );
+  } );
+  connect( this, &QgsDockWidget::visibilityChanged, mAction, [ = ]( bool visible )
+  {
+    mAction->setChecked( visible );
+  } );
+}
+
+QAction *QgsDockWidget::linkedAction()
+{
+  return mAction;
+}
+
 void QgsDockWidget::closeEvent( QCloseEvent *e )
 {
   emit closed();

src/gui/qgsdockwidget.h

@@ -57,6 +57,23 @@ class GUI_EXPORT QgsDockWidget : public QDockWidget
      */
     bool isUserVisible() const;
 
+    /**
+     * Links an \a action to the dock, so that toggling the action will automatically set the dock's visibility
+     * to suit (and changing the dock visibility will update the action's state).
+     *
+     * \see linkedAction()
+     * \since QGIS 3.4
+     */
+    void setLinkedAction( QAction *action );
+
+    /**
+     * Returns the action linked to the dock.
+     *
+     * \see setLinkedAction()
+     * \since QGIS 3.4
+     */
+    QAction *linkedAction();
+
   public slots:
 
     /**
@@ -131,5 +148,7 @@ class GUI_EXPORT QgsDockWidget : public QDockWidget
 
     bool mVisibleAndActive = false;
 
+    QAction *mAction = nullptr;
+
 };
 #endif //QGSDOCKWIDGET_H

tests/src/gui/testqgsdockwidget.cpp

@@ -19,6 +19,7 @@
 #include "qgsdockwidget.h"
 #include <QApplication>
 #include <QMainWindow>
+#include <QAction>
 
 class TestQgsDockWidget: public QObject
 {
@@ -33,6 +34,7 @@ class TestQgsDockWidget: public QObject
     void testUserVisible();
     void testSetUserVisible();
     void testToggleUserVisible();
+    void testAction();
 
   private:
 
@@ -220,5 +222,61 @@ void TestQgsDockWidget::testToggleUserVisible()
 
 }
 
+void TestQgsDockWidget::testAction()
+{
+  QMainWindow *w = new QMainWindow();
+  QApplication::setActiveWindow( w ); //required for focus events
+  QgsDockWidget *d1 = new QgsDockWidget( w );
+  QgsDockWidget *d2 = new QgsDockWidget( w );
+  w->addDockWidget( Qt::RightDockWidgetArea, d1 );
+  w->addDockWidget( Qt::RightDockWidgetArea, d2 );
+  w->tabifyDockWidget( d1, d2 );
+  w->show();
+
+  QAction *a1 = new QAction( w );
+  QAction *a2 = new QAction( w );
+
+  QVERIFY( ! d1->linkedAction() );
+  d1->setLinkedAction( a1 );
+  d2->setLinkedAction( a2 );
+  QVERIFY( a1->isCheckable() );
+  QVERIFY( a2->isCheckable() );
+  QCOMPARE( d1->linkedAction(), a1 );
+  QCOMPARE( d2->linkedAction(), a2 );
+
+  QVERIFY( d2->isUserVisible() );
+  QVERIFY( a2->isChecked() );
+  QVERIFY( !d1->isUserVisible() );
+  QVERIFY( !a1->isChecked() );
+
+  a1->setChecked( true );
+  QVERIFY( !d2->isUserVisible() );
+  QVERIFY( !a2->isChecked() );
+  QVERIFY( d1->isUserVisible() );
+  QVERIFY( a1->isChecked() );
+
+  a1->setChecked( true );
+  QVERIFY( !d2->isUserVisible() );
+  QVERIFY( !a2->isChecked() );
+  QVERIFY( d1->isUserVisible() );
+  QVERIFY( a1->isChecked() );
+
+  a2->setChecked( true );
+  QVERIFY( d2->isUserVisible() );
+  QVERIFY( a2->isChecked() );
+  QVERIFY( !d1->isUserVisible() );
+  QVERIFY( !a1->isChecked() );
+
+  d2->hide();
+  d1->raise(); //shouldn't be necessary outside of tests
+  QVERIFY( !a2->isChecked() );
+  QVERIFY( d1->isUserVisible() );
+  QVERIFY( a1->isChecked() );
+
+  a1->setChecked( false );
+  QVERIFY( !d1->isUserVisible() );
+  QVERIFY( !a1->isChecked() );
+}
+
 QGSTEST_MAIN( TestQgsDockWidget )
 #include "testqgsdockwidget.moc"