Add method to toggle user visibility of QgsDockWidgets

python/gui/auto_generated/qgsdockwidget.sip.in

@@ -45,6 +45,8 @@ Returns true if the dock is both opened and raised to the front (ie not hidden b
 any other tabs.
 
 .. seealso:: :py:func:`setUserVisible`
+
+.. seealso:: :py:func:`toggleUserVisible`
 %End
 
   public slots:
@@ -64,6 +66,21 @@ Sets the dock widget as visible to a user, ie both shown and raised to the front
                 - hiding a dock which is closed has no effect and raises no signals
 
 .. seealso:: :py:func:`isUserVisible`
+
+.. seealso:: :py:func:`toggleUserVisible`
+%End
+
+    void toggleUserVisible();
+%Docstring
+Toggles whether the dock is user visible. If the dock is not currently user
+visible (i.e. opened and activated as a tab) then the dock will be opened
+and raised. If it is currently user visible it will be closed.
+
+.. seealso:: :py:func:`setUserVisible`
+
+.. seealso:: :py:func:`isUserVisible`
+
+.. versionadded:: 3.2
 %End
 
   protected:

src/gui/qgsdockwidget.cpp

@@ -47,6 +47,11 @@ void QgsDockWidget::setUserVisible( bool visible )
   }
 }
 
+void QgsDockWidget::toggleUserVisible()
+{
+  setUserVisible( !isUserVisible() );
+}
+
 bool QgsDockWidget::isUserVisible() const
 {
   return mVisibleAndActive;

src/gui/qgsdockwidget.h

@@ -53,6 +53,7 @@ class GUI_EXPORT QgsDockWidget : public QDockWidget
      * Returns true if the dock is both opened and raised to the front (ie not hidden by
      * any other tabs.
      * \see setUserVisible()
+     * \see toggleUserVisible()
      */
     bool isUserVisible() const;
 
@@ -70,9 +71,21 @@ class GUI_EXPORT QgsDockWidget : public QDockWidget
      * be closed
      * - hiding a dock which is closed has no effect and raises no signals
      * \see isUserVisible()
+     * \see toggleUserVisible()
      */
     void setUserVisible( bool visible );
 
+    /**
+     * Toggles whether the dock is user visible. If the dock is not currently user
+     * visible (i.e. opened and activated as a tab) then the dock will be opened
+     * and raised. If it is currently user visible it will be closed.
+     *
+     * \see setUserVisible()
+     * \see isUserVisible()
+     * \since QGIS 3.2
+     */
+    void toggleUserVisible();
+
   protected:
 
     void closeEvent( QCloseEvent * ) override;

tests/src/gui/testqgsdockwidget.cpp

@@ -32,6 +32,7 @@ class TestQgsDockWidget: public QObject
     void testSignals();
     void testUserVisible();
     void testSetUserVisible();
+    void testToggleUserVisible();
 
   private:
 
@@ -176,5 +177,48 @@ void TestQgsDockWidget::testSetUserVisible()
 
 }
 
+void TestQgsDockWidget::testToggleUserVisible()
+{
+  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();
+
+  QVERIFY( d2->isUserVisible() );
+  QVERIFY( !d1->isUserVisible() );
+
+  d1->toggleUserVisible();
+  QVERIFY( !d2->isUserVisible() );
+  QVERIFY( d2->isVisible() );
+  QVERIFY( d1->isUserVisible() );
+  QVERIFY( d1->isVisible() );
+
+  d2->hide();
+  d2->toggleUserVisible();
+  QVERIFY( d2->isUserVisible() );
+  QVERIFY( d2->isVisible() );
+  QVERIFY( !d1->isUserVisible() );
+  QVERIFY( d1->isVisible() );
+
+  d2->hide();
+  d1->raise(); //shouldn't be necessary outside of tests
+  QVERIFY( !d2->isUserVisible() );
+  QVERIFY( !d2->isVisible() );
+  QVERIFY( d1->isUserVisible() );
+  QVERIFY( d1->isVisible() );
+
+  d1->toggleUserVisible();
+  QVERIFY( !d2->isVisible() );
+  QVERIFY( !d1->isUserVisible() );
+  QVERIFY( !d1->isVisible() );
+
+  delete w;
+
+}
+
 QGSTEST_MAIN( TestQgsDockWidget )
 #include "testqgsdockwidget.moc"