Add method to populate browser context menu to QgsDataItemGuiProvider

python/gui/auto_generated/qgsdataitemguiprovider.sip.in

@@ -9,6 +9,45 @@
 
 
 
+class QgsDataItemGuiContext
+{
+%Docstring
+
+Encapsulates the context in which a QgsDataItem is shown within the application GUI.
+
+.. versionadded:: 3.6
+%End
+
+%TypeHeaderCode
+#include "qgsdataitemguiprovider.h"
+%End
+  public:
+
+    QgsDataItemGuiContext();
+%Docstring
+Constructor for QgsDataItemGuiContext.
+%End
+
+    QgsMessageBar *messageBar();
+%Docstring
+Returns the associated message bar.
+
+This bar can be used to provide non-blocking feedback to users.
+
+.. seealso:: :py:func:`setMessageBar`
+%End
+
+    void setMessageBar( QgsMessageBar *bar );
+%Docstring
+Sets the associated message ``bar``.
+
+This bar can be used to provide non-blocking feedback to users.
+
+.. seealso:: :py:func:`messageBar`
+%End
+
+};
+
 class QgsDataItemGuiProvider
 {
 %Docstring
@@ -16,7 +55,7 @@ class QgsDataItemGuiProvider
 Abstract base class for providers which affect how QgsDataItem items behave
 within the application GUI.
 
-Providers must be registered via QgsDataItemGuiProviderRegistry.
+Providers must be registered via :py:class:`QgsDataItemGuiProviderRegistry`.
 
 .. versionadded:: 3.6
 %End
@@ -31,6 +70,28 @@ Providers must be registered via QgsDataItemGuiProviderRegistry.
     virtual QString name() = 0;
 %Docstring
 Returns the provider's name.
+%End
+
+    virtual void populateContextMenu( const QList<QgsDataItem *> &items, QMenu *menu, QgsDataItemGuiContext context );
+%Docstring
+Called when the given context ``menu`` is being populated for the given selected ``items``, allowing the provider
+to add its own actions and submenus to the context menu. Additionally,
+providers could potentially alter menus and actions added by other providers
+if desired, or use standard QMenu API to insert their items and submenus into
+the desired location within the context menu.
+
+When creating a context menu, this method is called for EVERY QgsDataItemGuiProvider
+within the QgsDataItemGuiProviderRegistry. It is the QgsDataItemGuiProvider subclass'
+responsibility to test the selected ``items`` for their properties and classes and decide what actions
+(if any) are appropriate to add to the context ``menu``.
+
+Care must be taken to correctly parent newly created sub menus and actions to the
+provided ``menu`` to avoid memory leaks.
+
+The ``context`` argument gives the wider context under which the context menu is being shown,
+and contains accessors for useful objects like the application message bar.
+
+The base class method has no effect.
 %End
 
 };

src/gui/qgsdataitemguiprovider.cpp

@@ -15,4 +15,26 @@
 
 #include "qgsdataitemguiprovider.h"
 
-// no implementation currently
+//
+// QgsDataItemGuiContext
+//
+
+QgsMessageBar *QgsDataItemGuiContext::messageBar()
+{
+  return mMessageBar;
+}
+
+void QgsDataItemGuiContext::setMessageBar( QgsMessageBar *messageBar )
+{
+  mMessageBar = messageBar;
+}
+
+
+//
+// QgsDataItemGuiProvider
+//
+
+void QgsDataItemGuiProvider::populateContextMenu( const QList<QgsDataItem *> &, QMenu *, QgsDataItemGuiContext )
+{
+
+}

src/gui/qgsdataitemguiprovider.h

@@ -17,8 +17,52 @@
 #define QGSDATAITEMGUIPROVIDER_H
 
 #include "qgis_gui.h"
+#include <QList>
 
 class QString;
+class QgsDataItem;
+class QMenu;
+class QgsMessageBar;
+
+/**
+ * \class QgsDataItemGuiContext
+ * \ingroup gui
+ *
+ * Encapsulates the context in which a QgsDataItem is shown within the application GUI.
+ *
+ * \since QGIS 3.6
+ */
+class GUI_EXPORT QgsDataItemGuiContext
+{
+  public:
+
+    /**
+     * Constructor for QgsDataItemGuiContext.
+     */
+    QgsDataItemGuiContext() = default;
+
+    /**
+     * Returns the associated message bar.
+     *
+     * This bar can be used to provide non-blocking feedback to users.
+     *
+     * \see setMessageBar()
+     */
+    QgsMessageBar *messageBar();
+
+    /**
+     * Sets the associated message \a bar.
+     *
+     * This bar can be used to provide non-blocking feedback to users.
+     *
+     * \see messageBar()
+     */
+    void setMessageBar( QgsMessageBar *bar );
+
+  private:
+
+    QgsMessageBar *mMessageBar = nullptr;
+};
 
 /**
  * \class QgsDataItemGuiProvider
@@ -42,6 +86,28 @@ class GUI_EXPORT QgsDataItemGuiProvider
      */
     virtual QString name() = 0;
 
+    /**
+     * Called when the given context \a menu is being populated for the given selected \a items, allowing the provider
+     * to add its own actions and submenus to the context menu. Additionally,
+     * providers could potentially alter menus and actions added by other providers
+     * if desired, or use standard QMenu API to insert their items and submenus into
+     * the desired location within the context menu.
+     *
+     * When creating a context menu, this method is called for EVERY QgsDataItemGuiProvider
+     * within the QgsDataItemGuiProviderRegistry. It is the QgsDataItemGuiProvider subclass'
+     * responsibility to test the selected \a items for their properties and classes and decide what actions
+     * (if any) are appropriate to add to the context \a menu.
+     *
+     * Care must be taken to correctly parent newly created sub menus and actions to the
+     * provided \a menu to avoid memory leaks.
+     *
+     * The \a context argument gives the wider context under which the context menu is being shown,
+     * and contains accessors for useful objects like the application message bar.
+     *
+     * The base class method has no effect.
+     */
+    virtual void populateContextMenu( const QList<QgsDataItem *> &items, QMenu *menu, QgsDataItemGuiContext context );
+
 };
 
 #endif // QGSDATAITEMGUIPROVIDER_H

tests/src/python/test_qgsdataitemguiproviderregistry.py

@@ -15,8 +15,10 @@ __revision__ = '$Format:%H$'
 import qgis  # NOQA
 
 from qgis.gui import (QgsGui,
+                      QgsDataItemGuiContext,
                       QgsDataItemGuiProvider,
-                      QgsDataItemGuiProviderRegistry)
+                      QgsDataItemGuiProviderRegistry,
+                      QgsMessageBar)
 from qgis.testing import start_app, unittest
 
 app = start_app()
@@ -32,6 +34,17 @@ class TestProvider(QgsDataItemGuiProvider):
         return self._name
 
 
+class TestQgsDataItemGuiContext(unittest.TestCase):
+
+    def testContext(self):
+        context = QgsDataItemGuiContext()
+        self.assertIsNone(context.messageBar())
+
+        mb = QgsMessageBar()
+        context.setMessageBar(mb)
+        self.assertEqual(context.messageBar(), mb)
+
+
 class TestQgsDataItemGuiProviderRegistry(unittest.TestCase):
 
     def testAppRegistry(self):