Branch data     Line data    Source code

       1                 :            : /***************************************************************************
       2                 :            :                           qgsactionmanager.h
       3                 :            : 
       4                 :            :  These classes store and control the management and execution of actions
       5                 :            :  associated with a particular QGIS layer. Actions are defined to be
       6                 :            :  external programs that are run with user-specified inputs that can
       7                 :            :  depend on the contents of layer attributes.
       8                 :            : 
       9                 :            :                              -------------------
      10                 :            :     begin                : Oct 24 2004
      11                 :            :     copyright            : (C) 2004 by Gavin Macaulay
      12                 :            :     email                : gavin at macaulay dot co dot nz
      13                 :            :  ***************************************************************************/
      14                 :            : 
      15                 :            : /***************************************************************************
      16                 :            :  *                                                                         *
      17                 :            :  *   This program is free software; you can redistribute it and/or modify  *
      18                 :            :  *   it under the terms of the GNU General Public License as published by  *
      19                 :            :  *   the Free Software Foundation; either version 2 of the License, or     *
      20                 :            :  *   (at your option) any later version.                                   *
      21                 :            :  *                                                                         *
      22                 :            :  ***************************************************************************/
      23                 :            : 
      24                 :            : #ifndef QGSACTIONMANAGER_H
      25                 :            : #define QGSACTIONMANAGER_H
      26                 :            : 
      27                 :            : #include "qgis_core.h"
      28                 :            : #include <QString>
      29                 :            : #include <QIcon>
      30                 :            : #include <QObject>
      31                 :            : #include <QUuid>
      32                 :            : 
      33                 :            : #include "qgsaction.h"
      34                 :            : #include "qgsfeature.h"
      35                 :            : 
      36                 :            : class QDomNode;
      37                 :            : class QDomDocument;
      38                 :            : class QgsPythonUtils;
      39                 :            : class QgsVectorLayer;
      40                 :            : class QgsExpressionContextScope;
      41                 :            : class QgsExpressionContext;
      42                 :            : 
      43                 :            : /**
      44                 :            :  * \ingroup core
      45                 :            :  * \class QgsActionManager
      46                 :            :  * \brief Storage and management of actions associated with a layer.
      47                 :            :  *
      48                 :            :  * Actions can trigger custom code or applications to be executed
      49                 :            :  * based on attributes of a given feature.
      50                 :            :  */
      51                 :            : 
      52                 :            : class CORE_EXPORT QgsActionManager: public QObject
      53                 :            : {
      54                 :            :     Q_OBJECT
      55                 :            : 
      56                 :            :   public:
      57                 :            :     //! Constructor
      58                 :         78 :     QgsActionManager( QgsVectorLayer *layer )
      59                 :         78 :       : mLayer( layer )
      60                 :        234 :     {}
      61                 :            : 
      62                 :            :     /**
      63                 :            :      * Add an action with the given name and action details.
      64                 :            :      * Will happily have duplicate names and actions. If
      65                 :            :      * capture is TRUE, when running the action using doAction(),
      66                 :            :      * any stdout from the process will be captured and displayed in a
      67                 :            :      * dialog box.
      68                 :            :      */
      69                 :            :     QUuid addAction( QgsAction::ActionType type, const QString &name, const QString &command, bool capture = false );
      70                 :            : 
      71                 :            :     /**
      72                 :            :      * Add an action with the given name and action details.
      73                 :            :      * Will happily have duplicate names and actions. If
      74                 :            :      * capture is TRUE, when running the action using doAction(),
      75                 :            :      * any stdout from the process will be captured and displayed in a
      76                 :            :      * dialog box.
      77                 :            :      */
      78                 :            :     QUuid addAction( QgsAction::ActionType type, const QString &name, const QString &command, const QString &icon, bool capture = false );
      79                 :            : 
      80                 :            :     /**
      81                 :            :      * Add a new action to this list.
      82                 :            :      */
      83                 :            :     void addAction( const QgsAction &action );
      84                 :            : 
      85                 :            :     /**
      86                 :            :      * Remove an action by its id.
      87                 :            :      *
      88                 :            :      * \since QGIS 3.0
      89                 :            :      */
      90                 :            :     void removeAction( QUuid actionId );
      91                 :            : 
      92                 :            :     /**
      93                 :            :      * Does the given action.
      94                 :            :      *
      95                 :            :      * \param actionId action id
      96                 :            :      * \param feature feature to run action for
      97                 :            :      * \param defaultValueIndex index of the field to be used if the action has a $currfield placeholder.
      98                 :            :      * \param scope expression context scope to add during expression evaluation
      99                 :            :      *
     100                 :            :      * \note available in Python bindings as doActionFeature
     101                 :            :      */
     102                 :            :     void doAction( QUuid actionId, const QgsFeature &feature, int defaultValueIndex = 0, const QgsExpressionContextScope &scope = QgsExpressionContextScope() ) SIP_PYNAME( doActionFeature );
     103                 :            : 
     104                 :            :     /**
     105                 :            :      * Does the action using the expression engine to replace any embedded expressions
     106                 :            :      * in the action definition.
     107                 :            :      * \param actionId action id
     108                 :            :      * \param feature feature to run action for
     109                 :            :      * \param context expression context to evaluate expressions under
     110                 :            :      */
     111                 :            :     void doAction( QUuid actionId, const QgsFeature &feature, const QgsExpressionContext &context );
     112                 :            : 
     113                 :            :     //! Removes all actions
     114                 :            :     void clearActions();
     115                 :            : 
     116                 :            :     /**
     117                 :            :      * Returns a list of actions that are available in the given action scope.
     118                 :            :      * If no action scope is provided, all actions will be returned.
     119                 :            :      *
     120                 :            :      * \since QGIS 3.0
     121                 :            :      */
     122                 :            :     QList<QgsAction> actions( const QString &actionScope = QString() ) const;
     123                 :            : 
     124                 :            :     //! Returns the layer
     125                 :            :     QgsVectorLayer *layer() const { return mLayer; }
     126                 :            : 
     127                 :            :     //! Writes the actions out in XML format
     128                 :            :     bool writeXml( QDomNode &layer_node ) const;
     129                 :            : 
     130                 :            :     //! Reads the actions in in XML format
     131                 :            :     bool readXml( const QDomNode &layer_node );
     132                 :            : 
     133                 :            :     /**
     134                 :            :      * Gets an action by its id.
     135                 :            :      *
     136                 :            :      * \since QGIS 3.0
     137                 :            :      */
     138                 :            :     QgsAction action( QUuid id );
     139                 :            : 
     140                 :            :     /**
     141                 :            :      * Each scope can have a default action. This will be saved in the project
     142                 :            :      * file.
     143                 :            :      *
     144                 :            :      * \since QGIS 3.0
     145                 :            :      */
     146                 :            :     void setDefaultAction( const QString &actionScope, QUuid actionId );
     147                 :            : 
     148                 :            :     /**
     149                 :            :      * Each scope can have a default action. This will be saved in the project
     150                 :            :      * file.
     151                 :            :      *
     152                 :            :      * \since QGIS 3.0
     153                 :            :      */
     154                 :            :     QgsAction defaultAction( const QString &actionScope );
     155                 :            : 
     156                 :            :   private:
     157                 :            :     QList<QgsAction> mActions;
     158                 :            :     QgsVectorLayer *mLayer = nullptr;
     159                 :            :     static void ( *smPythonExecute )( const QString & );
     160                 :            : 
     161                 :            :     void runAction( const QgsAction &action );
     162                 :            : 
     163                 :            :     QMap<QString, QUuid> mDefaultActions;
     164                 :            : 
     165                 :         78 :     bool mOnNotifyConnected = false;
     166                 :            : 
     167                 :            :     QgsExpressionContext createExpressionContext() const;
     168                 :            : 
     169                 :            :   private slots:
     170                 :            :     void onNotifyRunActions( const QString &message );
     171                 :            : };
     172                 :            : 
     173                 :            : #endif