QGIS API Documentation  3.16.0-Hannover (43b64b13f3)
Classes | Public Member Functions | List of all members
QgsAbstractMapToolHandler Class Referenceabstract

An abstract base class for map tool handlers which automatically handle all the necessary logic for toggling the map tool and enabling/disabling the associated action when the QGIS application is in a state permissible for the tool. More...

#include <qgsabstractmaptoolhandler.h>

Classes

struct  Context
 Context of a QgsAbstractMapToolHandler call. More...
 

Public Member Functions

 QgsAbstractMapToolHandler (QgsMapTool *tool, QAction *action)
 Constructor for a map tool handler for the specified tool. More...
 
virtual ~QgsAbstractMapToolHandler ()
 
QAction * action ()
 Returns the action associated with toggling the tool. More...
 
virtual bool isCompatibleWithLayer (QgsMapLayer *layer, const QgsAbstractMapToolHandler::Context &context)=0
 Returns true if the associated map tool is compatible with the specified layer. More...
 
QgsMapToolmapTool ()
 Returns the tool associated with this handler. More...
 
virtual void setLayerForTool (QgsMapLayer *layer)
 Sets the layer to use for the tool. More...
 

Detailed Description

An abstract base class for map tool handlers which automatically handle all the necessary logic for toggling the map tool and enabling/disabling the associated action when the QGIS application is in a state permissible for the tool.

Creating these handlers avoids a lot of complex setup code and manual connections which are otherwise necessary to ensure that a map tool is correctly activated and deactivated when the state of the QGIS application changes (e.g. when the active layer is changed, when edit modes are toggled, when other map tools are switched to, etc).

class MyMapTool(QgsMapTool):
...
class MyMapToolHandler(QgsAbstractMapToolHandler):
def __init__(self, tool, action):
super().__init__(tool, action)
def isCompatibleWithLayer(self, layer, context):
# this tool can only be activated when an editable vector layer is selected
return isinstance(layer, QgsVectorLayer) and layer.isEditable()
my_tool = MyMapTool()
my_action = QAction('My Map Tool')
my_handler = MyMapToolHandler(my_tool, my_action)
iface.registerMapToolHandler(my_handler)
Since
QGIS 3.16

Definition at line 61 of file qgsabstractmaptoolhandler.h.

Constructor & Destructor Documentation

◆ QgsAbstractMapToolHandler()

QgsAbstractMapToolHandler::QgsAbstractMapToolHandler ( QgsMapTool tool,
QAction *  action 
)

Constructor for a map tool handler for the specified tool.

The action argument must be set to the action associated with switching to the tool.

The ownership of neither tool nor action is transferred, and the caller is responsible for ensuring that these objects exist for the lifetime of the handler.

Warning
The handler will be responsible for creating the appropriate connections between the action and the tool. These should NOT be manually connected elsewhere!

Definition at line 18 of file qgsabstractmaptoolhandler.cpp.

◆ ~QgsAbstractMapToolHandler()

QgsAbstractMapToolHandler::~QgsAbstractMapToolHandler ( )
virtualdefault

Member Function Documentation

◆ action()

QAction * QgsAbstractMapToolHandler::action ( )

Returns the action associated with toggling the tool.

Definition at line 33 of file qgsabstractmaptoolhandler.cpp.

◆ isCompatibleWithLayer()

virtual bool QgsAbstractMapToolHandler::isCompatibleWithLayer ( QgsMapLayer layer,
const QgsAbstractMapToolHandler::Context context 
)
pure virtual

Returns true if the associated map tool is compatible with the specified layer.

Additional information is available through the context argument.

◆ mapTool()

QgsMapTool * QgsAbstractMapToolHandler::mapTool ( )

Returns the tool associated with this handler.

Definition at line 28 of file qgsabstractmaptoolhandler.cpp.

◆ setLayerForTool()

void QgsAbstractMapToolHandler::setLayerForTool ( QgsMapLayer layer)
virtual

Sets the layer to use for the tool.

Called whenever a new layer should be associated with the tool, e.g. as a result of the user selecting a different active layer.

The default implementation does nothing.

Definition at line 38 of file qgsabstractmaptoolhandler.cpp.


The documentation for this class was generated from the following files:
QgsAbstractMapToolHandler
An abstract base class for map tool handlers which automatically handle all the necessary logic for t...
Definition: qgsabstractmaptoolhandler.h:62
QgsMapTool
Abstract base class for all map tools.
Definition: qgsmaptool.h:64