diff --git a/python/gui/auto_generated/qgsdataitemguiprovider.sip.in b/python/gui/auto_generated/qgsdataitemguiprovider.sip.in index 192295ec32e..fa1ab086ca3 100644 --- a/python/gui/auto_generated/qgsdataitemguiprovider.sip.in +++ b/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 &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 }; diff --git a/src/gui/qgsdataitemguiprovider.cpp b/src/gui/qgsdataitemguiprovider.cpp index c4afbe9a2fa..bccf21f8e54 100644 --- a/src/gui/qgsdataitemguiprovider.cpp +++ b/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 &, QMenu *, QgsDataItemGuiContext ) +{ + +} diff --git a/src/gui/qgsdataitemguiprovider.h b/src/gui/qgsdataitemguiprovider.h index 18ab8b4e927..dd9e9af42a8 100644 --- a/src/gui/qgsdataitemguiprovider.h +++ b/src/gui/qgsdataitemguiprovider.h @@ -17,8 +17,52 @@ #define QGSDATAITEMGUIPROVIDER_H #include "qgis_gui.h" +#include 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 &items, QMenu *menu, QgsDataItemGuiContext context ); + }; #endif // QGSDATAITEMGUIPROVIDER_H diff --git a/tests/src/python/test_qgsdataitemguiproviderregistry.py b/tests/src/python/test_qgsdataitemguiproviderregistry.py index eff0158984b..baa846f6ad3 100644 --- a/tests/src/python/test_qgsdataitemguiproviderregistry.py +++ b/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):