Add framework for handling non-keyboard/mouse map controllers

This is the base API interface classes for creation of custom
2d or 3d map controllers, and registering them in a common
QgsInputControllerManager singleton class.

doc/CMakeLists.txt

@@ -109,6 +109,7 @@ if(WITH_APIDOC)
       ${CMAKE_SOURCE_DIR}/src/gui/effects
       ${CMAKE_SOURCE_DIR}/src/gui/elevation
       ${CMAKE_SOURCE_DIR}/src/gui/history
+      ${CMAKE_SOURCE_DIR}/src/gui/inputcontroller
       ${CMAKE_SOURCE_DIR}/src/gui/labeling
       ${CMAKE_SOURCE_DIR}/src/gui/layertree
       ${CMAKE_SOURCE_DIR}/src/gui/layout

python/core/auto_additions/qgis.py

@@ -3540,6 +3540,12 @@
 # --
 Qgis.LayoutUnitType.baseClass = Qgis
 # monkey patching scoped based enum
+Qgis.InputControllerType.Map2D.__doc__ = "2D map controller"
+Qgis.InputControllerType.Map3D.__doc__ = "3D map controller"
+Qgis.InputControllerType.__doc__ = 'Input controller types.\n\n.. versionadded:: 3.32\n\n' + '* ``Map2D``: ' + Qgis.InputControllerType.Map2D.__doc__ + '\n' + '* ``Map3D``: ' + Qgis.InputControllerType.Map3D.__doc__
+# --
+Qgis.InputControllerType.baseClass = Qgis
+# monkey patching scoped based enum
 Qgis.PostgresRelKind.NotSet.__doc__ = "Not set"
 Qgis.PostgresRelKind.Unknown.__doc__ = "Unknown"
 Qgis.PostgresRelKind.OrdinaryTable.__doc__ = "Ordinary table"

python/core/auto_generated/qgis.sip.in

@@ -2010,6 +2010,12 @@ The development version
       ScreenUnits
     };
 
+    enum class InputControllerType
+    {
+      Map2D,
+      Map3D
+    };
+
     enum class PostgresRelKind
     {
       NotSet,

python/gui/auto_generated/inputcontroller/qgs2dmapcontroller.sip.in

@@ -0,0 +1,50 @@
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/gui/inputcontroller/qgs2dmapcontroller.h                         *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/
+
+
+
+class QgsAbstract2DMapController : QgsAbstractInputController
+{
+%Docstring(signature="appended")
+Abstract base class for all 2D map controllers.
+
+.. versionadded:: 3.32
+%End
+
+%TypeHeaderCode
+#include "qgs2dmapcontroller.h"
+%End
+  public:
+
+    QgsAbstract2DMapController( QObject *parent /TransferThis/ = 0 );
+%Docstring
+Constructor for QgsAbstract2DMapController, with the specified ``parent`` object.
+%End
+
+    virtual Qgis::InputControllerType type() const;
+
+
+  signals:
+
+
+    void zoomMap( double factor );
+%Docstring
+Emitted when the controller should change the scale of a map by the given ``factor``.
+%End
+
+
+};
+
+
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/gui/inputcontroller/qgs2dmapcontroller.h                         *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/

python/gui/auto_generated/inputcontroller/qgs3dmapcontroller.sip.in

@@ -0,0 +1,49 @@
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/gui/inputcontroller/qgs3dmapcontroller.h                         *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/
+
+
+
+class QgsAbstract3DMapController : QgsAbstractInputController
+{
+%Docstring(signature="appended")
+Abstract base class for all 3D map controllers.
+
+.. versionadded:: 3.32
+%End
+
+%TypeHeaderCode
+#include "qgs3dmapcontroller.h"
+%End
+  public:
+
+    QgsAbstract3DMapController( QObject *parent /TransferThis/ = 0 );
+%Docstring
+Constructor for QgsAbstract3DMapController, with the specified ``parent`` object.
+%End
+
+    virtual Qgis::InputControllerType type() const;
+
+
+  signals:
+
+
+    void changeCameraAngleByDelta( double delta );
+%Docstring
+Emitted when the controller needs to change the 3d camera angle by the specified ``delta``.
+%End
+
+};
+
+
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/gui/inputcontroller/qgs3dmapcontroller.h                         *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/

python/gui/auto_generated/inputcontroller/qgsabstractinputcontroller.sip.in

@@ -0,0 +1,64 @@
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/gui/inputcontroller/qgsabstractinputcontroller.h                 *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/
+
+
+
+
+class QgsAbstractInputController : QObject
+{
+%Docstring(signature="appended")
+Abstract base class for all input controllers.
+
+.. versionadded:: 3.32
+%End
+
+%TypeHeaderCode
+#include "qgsabstractinputcontroller.h"
+#include "qgs2dmapcontroller.h"
+#include "qgs3dmapcontroller.h"
+%ConvertToSubClassCode
+    if ( qobject_cast< QgsAbstract2DMapController * >( sipCpp ) )
+      sipType = sipType_QgsAbstract2DMapController;
+    else if ( qobject_cast< QgsAbstract3DMapController * >( sipCpp ) )
+      sipType = sipType_QgsAbstract3DMapController;
+    else
+      sipType = nullptr;
+%End
+%End
+  public:
+
+    QgsAbstractInputController( QObject *parent /TransferThis/ = 0 );
+%Docstring
+Constructor for QgsAbstractInputController, with the specified ``parent`` object.
+%End
+
+    virtual QgsAbstractInputController *clone() const = 0 /Factory/;
+%Docstring
+Returns a new copy of the controller.
+%End
+
+    virtual QString deviceId() const = 0;
+%Docstring
+Returns a string uniquely identifying the device.
+%End
+
+    virtual Qgis::InputControllerType type() const = 0;
+%Docstring
+Returns the input controller type.
+%End
+
+};
+
+
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/gui/inputcontroller/qgsabstractinputcontroller.h                 *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/

python/gui/auto_generated/inputcontroller/qgsinputcontrollermanager.sip.in

@@ -0,0 +1,112 @@
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/gui/inputcontroller/qgsinputcontrollermanager.h                  *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/
+
+
+
+
+
+class QgsInputControllerManager : QObject
+{
+%Docstring(signature="appended")
+Manages input control devices.
+
+:py:class:`QgsInputControllerManager` is not usually directly created, but rather accessed through
+:py:func:`QgsGui.inputControllerManager()`.
+
+.. versionadded:: 3.32
+%End
+
+%TypeHeaderCode
+#include "qgsinputcontrollermanager.h"
+%End
+  public:
+
+    QgsInputControllerManager( QObject *parent /TransferThis/ = 0 );
+%Docstring
+Constructor for QgsInputControllerManager, with the specified ``parent`` object.
+
+.. note::
+
+   QgsInputControllerManager is not usually directly created, but rather accessed through
+   :py:func:`QgsGui.inputControllerManager()`.
+%End
+    ~QgsInputControllerManager();
+
+    QStringList available2DMapControllers() const;
+%Docstring
+Returns a list of the device IDs of available 2D map controllers.
+
+.. seealso:: :py:func:`create2DMapController`
+
+.. seealso:: :py:func:`register2DMapController`
+%End
+
+    QgsAbstract2DMapController *create2DMapController( const QString &deviceId ) const /Factory/;
+%Docstring
+Returns a new instance of the 2D map controller with the specified ``deviceId``.
+
+The caller takes ownership of the returned object.
+
+Will return ``None`` if no matching controller is found.
+
+.. seealso:: :py:func:`available2DMapControllers`
+%End
+
+    bool register2DMapController( QgsAbstract2DMapController *controller /Transfer/ );
+%Docstring
+Registers a new 2D map ``controller``.
+
+Ownership of ``controller`` is transferred to the manager.
+
+Returns ``True`` if the controller was successfully registered, or ``False`` if it could
+not be registered (e.g. if a controller with matching deviceId has already been registered).
+
+.. seealso:: :py:func:`available2DMapControllers`
+%End
+
+    QStringList available3DMapControllers() const;
+%Docstring
+Returns a list of the device IDs of available 3D map controllers.
+
+.. seealso:: :py:func:`create3DMapController`
+
+.. seealso:: :py:func:`register3DMapController`
+%End
+
+    QgsAbstract3DMapController *create3DMapController( const QString &deviceId ) const /Factory/;
+%Docstring
+Returns a new instance of the 3D map controller with the specified ``deviceId``.
+
+The caller takes ownership of the returned object.
+
+Will return ``None`` if no matching controller is found.
+
+.. seealso:: :py:func:`available3DMapControllers`
+%End
+
+    bool register3DMapController( QgsAbstract3DMapController *controller /Transfer/ );
+%Docstring
+Registers a new 3D map ``controller``.
+
+Ownership of ``controller`` is transferred to the manager.
+
+Returns ``True`` if the controller was successfully registered, or ``False`` if it could
+not be registered (e.g. if a controller with matching deviceId has already been registered).
+
+.. seealso:: :py:func:`available3DMapControllers`
+%End
+
+};
+
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/gui/inputcontroller/qgsinputcontrollermanager.h                  *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/

python/gui/auto_generated/qgsgui.sip.in

@@ -197,6 +197,13 @@ Sets the global window ``manager``. Ownership is transferred to the QgsGui insta
 .. seealso:: :py:func:`windowManager`
 
 .. versionadded:: 3.4
+%End
+
+    static QgsInputControllerManager *inputControllerManager() /KeepReference/;
+%Docstring
+Returns the global input controller manager.
+
+.. versionadded:: 3.32
 %End
 
     enum HigFlag

python/gui/gui_auto.sip

@@ -352,6 +352,10 @@
 %Include auto_generated/history/qgshistoryproviderregistry.sip
 %Include auto_generated/history/qgshistorywidget.sip
 %Include auto_generated/history/qgshistorywidgetcontext.sip
+%Include auto_generated/inputcontroller/qgs2dmapcontroller.sip
+%Include auto_generated/inputcontroller/qgs3dmapcontroller.sip
+%Include auto_generated/inputcontroller/qgsabstractinputcontroller.sip
+%Include auto_generated/inputcontroller/qgsinputcontrollermanager.sip
 %Include auto_generated/labeling/qgslabellineanchorwidget.sip
 %Include auto_generated/labeling/qgslabelobstaclesettingswidget.sip
 %Include auto_generated/labeling/qgslabelsettingswidgetbase.sip

src/core/qgis.h

@@ -3484,6 +3484,18 @@ class CORE_EXPORT Qgis
     };
     Q_ENUM( LayoutUnitType )
 
+    /**
+     * Input controller types.
+     *
+     * \since QGIS 3.32
+     */
+    enum class InputControllerType : int
+    {
+      Map2D, //!< 2D map controller
+      Map3D //!< 3D map controller
+    };
+    Q_ENUM( InputControllerType );
+
     /**
      * Postgres database relkind options.
      *

src/gui/CMakeLists.txt

@@ -245,6 +245,11 @@ set(QGIS_GUI_SRCS
   history/qgshistorywidget.cpp
   history/qgshistorywidgetcontext.cpp
 
+  inputcontroller/qgs2dmapcontroller.cpp
+  inputcontroller/qgs3dmapcontroller.cpp
+  inputcontroller/qgsabstractinputcontroller.cpp
+  inputcontroller/qgsinputcontrollermanager.cpp
+
   labeling/qgslabelengineconfigdialog.cpp
   labeling/qgslabelinggui.cpp
   labeling/qgslabelingwidget.cpp
@@ -1169,6 +1174,11 @@ set(QGIS_GUI_HDRS
   history/qgshistorywidget.h
   history/qgshistorywidgetcontext.h
 
+  inputcontroller/qgs2dmapcontroller.h
+  inputcontroller/qgs3dmapcontroller.h
+  inputcontroller/qgsabstractinputcontroller.h
+  inputcontroller/qgsinputcontrollermanager.h
+
   labeling/qgslabelengineconfigdialog.h
   labeling/qgslabelinggui.h
   labeling/qgslabelingwidget.h
@@ -1517,7 +1527,6 @@ if (WITH_COPC)
   )
 endif()
 
-
 # disable deprecation warnings for classes re-exporting deprecated methods
 if(MSVC)
   set_source_files_properties(
@@ -1581,6 +1590,7 @@ target_include_directories(qgis_gui PUBLIC
   ${CMAKE_SOURCE_DIR}/src/gui/effects
   ${CMAKE_SOURCE_DIR}/src/gui/elevation
   ${CMAKE_SOURCE_DIR}/src/gui/history
+  ${CMAKE_SOURCE_DIR}/src/gui/inputcontroller
   ${CMAKE_SOURCE_DIR}/src/gui/labeling
   ${CMAKE_SOURCE_DIR}/src/gui/layertree
   ${CMAKE_SOURCE_DIR}/src/gui/layout