Branch data Line data Source code
1 : : /***************************************************************************
2 : : qgsaction.h - QgsAction
3 : :
4 : : ---------------------
5 : : begin : 18.4.2016
6 : : copyright : (C) 2016 by Matthias Kuhn
7 : : email : matthias@opengis.ch
8 : : ***************************************************************************
9 : : * *
10 : : * This program is free software; you can redistribute it and/or modify *
11 : : * it under the terms of the GNU General Public License as published by *
12 : : * the Free Software Foundation; either version 2 of the License, or *
13 : : * (at your option) any later version. *
14 : : * *
15 : : ***************************************************************************/
16 : : #ifndef QGSACTION_H
17 : : #define QGSACTION_H
18 : :
19 : : #include "qgis_core.h"
20 : : #include <QSet>
21 : : #include <QString>
22 : : #include <QIcon>
23 : : #include <QAction>
24 : : #include <QUuid>
25 : :
26 : : #include "qgsexpressioncontext.h"
27 : : #include <memory>
28 : :
29 : : class QgsExpressionContextScope;
30 : :
31 : : /**
32 : : * \ingroup core
33 : : * \brief Utility class that encapsulates an action based on vector attributes.
34 : : */
35 : 0 : class CORE_EXPORT QgsAction
36 : : {
37 : : public:
38 : : enum ActionType
39 : : {
40 : : Generic,
41 : : GenericPython,
42 : : Mac,
43 : : Windows,
44 : : Unix,
45 : : OpenUrl,
46 : : };
47 : :
48 : : /**
49 : : * Default constructor
50 : : */
51 : 0 : QgsAction() = default;
52 : :
53 : : /**
54 : : * Create a new QgsAction
55 : : *
56 : : * \param type The type of this action
57 : : * \param description A human readable description string
58 : : * \param command The action text. Its interpretation depends on the type
59 : : * \param capture If this is set to TRUE, the output will be captured when an action is run
60 : : * \param enabledOnlyWhenEditable if TRUE then action is only enable in editmode. Not available in Python bindings.
61 : : */
62 : : #ifndef SIP_RUN
63 : 0 : QgsAction( ActionType type, const QString &description, const QString &command, bool capture = false, bool enabledOnlyWhenEditable = false )
64 : 0 : : mType( type )
65 : 0 : , mDescription( description )
66 : 0 : , mCommand( command )
67 : 0 : , mCaptureOutput( capture )
68 : 0 : , mId( QUuid::createUuid() )
69 : 0 : , mIsEnabledOnlyWhenEditable( enabledOnlyWhenEditable )
70 : 0 : {}
71 : : #else
72 : : QgsAction( ActionType type, const QString &description, const QString &command, bool capture = false )
73 : : : mType( type )
74 : : , mDescription( description )
75 : : , mCommand( command )
76 : : , mCaptureOutput( capture )
77 : : , mId( QUuid::createUuid() )
78 : : , mIsEnabledOnlyWhenEditable( enabledOnlyWhenEditable )
79 : : {}
80 : : #endif
81 : :
82 : : /**
83 : : * Create a new QgsAction
84 : : *
85 : : * \param type The type of this action
86 : : * \param description A human readable description string
87 : : * \param action The action text. Its interpretation depends on the type
88 : : * \param icon Path to an icon for this action
89 : : * \param capture If this is set to TRUE, the output will be captured when an action is run
90 : : * \param shortTitle A short string used to label user interface elements like buttons
91 : : * \param actionScopes A set of scopes in which this action will be available
92 : : * \param notificationMessage A particular message which reception will trigger the action
93 : : * \param enabledOnlyWhenEditable if TRUE then action is only enable in editmode. Not available in Python bindings.
94 : : */
95 : : #ifndef SIP_RUN
96 : 0 : QgsAction( ActionType type, const QString &description, const QString &action, const QString &icon, bool capture, const QString &shortTitle = QString(), const QSet<QString> &actionScopes = QSet<QString>(), const QString ¬ificationMessage = QString(), bool enabledOnlyWhenEditable = false )
97 : 0 : : mType( type )
98 : 0 : , mDescription( description )
99 : 0 : , mShortTitle( shortTitle )
100 : 0 : , mIcon( icon )
101 : 0 : , mCommand( action )
102 : 0 : , mCaptureOutput( capture )
103 : 0 : , mActionScopes( actionScopes )
104 : 0 : , mNotificationMessage( notificationMessage )
105 : 0 : , mId( QUuid::createUuid() )
106 : 0 : , mIsEnabledOnlyWhenEditable( enabledOnlyWhenEditable )
107 : 0 : {}
108 : : #else
109 : : QgsAction( ActionType type, const QString &description, const QString &action, const QString &icon, bool capture, const QString &shortTitle = QString(), const QSet<QString> &actionScopes = QSet<QString>(), const QString ¬ificationMessage = QString() )
110 : : : mType( type )
111 : : , mDescription( description )
112 : : , mShortTitle( shortTitle )
113 : : , mIcon( icon )
114 : : , mCommand( action )
115 : : , mCaptureOutput( capture )
116 : : , mActionScopes( actionScopes )
117 : : , mNotificationMessage( notificationMessage )
118 : : , mId( QUuid::createUuid() )
119 : : , mIsEnabledOnlyWhenEditable( enabledOnlyWhenEditable )
120 : : {}
121 : : #endif
122 : :
123 : : //! The name of the action. This may be a longer description.
124 : 0 : QString name() const { return mDescription; }
125 : :
126 : : //! The short title is used to label user interface elements like buttons
127 : : QString shortTitle() const { return mShortTitle; }
128 : :
129 : : /**
130 : : * Returns a unique id for this action.
131 : : *
132 : : * \since QGIS 3.0
133 : : */
134 : 0 : QUuid id() const { return mId; }
135 : :
136 : : /**
137 : : * Returns TRUE if this action was a default constructed one.
138 : : *
139 : : * \since QGIS 3.0
140 : : */
141 : 0 : bool isValid() const { return !mId.isNull(); }
142 : :
143 : : //! The path to the icon
144 : : QString iconPath() const { return mIcon; }
145 : :
146 : : //! The icon
147 : : QIcon icon() const { return QIcon( mIcon ); }
148 : :
149 : : /**
150 : : * Returns the command that is executed by this action.
151 : : * How the content is interpreted depends on the type() and
152 : : * the actionScope().
153 : : *
154 : : * \since QGIS 3.0
155 : : */
156 : 0 : QString command() const { return mCommand; }
157 : :
158 : : /**
159 : : * Returns the notification message that triggers the action
160 : : *
161 : : * \since QGIS 3.0
162 : : */
163 : 0 : QString notificationMessage() const { return mNotificationMessage; }
164 : :
165 : : //! The action type
166 : 0 : ActionType type() const { return mType; }
167 : :
168 : : //! Whether to capture output for display when this action is run
169 : 0 : bool capture() const { return mCaptureOutput; }
170 : :
171 : :
172 : : //! Returns whether only enabled in editable mode
173 : : bool isEnabledOnlyWhenEditable() const { return mIsEnabledOnlyWhenEditable; }
174 : :
175 : : /**
176 : : * Set whether the action is only enabled in editable mode
177 : : *
178 : : * \since QGIS 3.16
179 : : */
180 : : void setEnabledOnlyWhenEditable( bool enable ) { mIsEnabledOnlyWhenEditable = enable; };
181 : :
182 : :
183 : : //! Checks if the action is runable on the current platform
184 : : bool runable() const;
185 : :
186 : : /**
187 : : * Run this action.
188 : : *
189 : : * \since QGIS 3.0
190 : : */
191 : : void run( QgsVectorLayer *layer, const QgsFeature &feature, const QgsExpressionContext &expressionContext ) const;
192 : :
193 : : /**
194 : : * Run this action.
195 : : *
196 : : * \since QGIS 3.0
197 : : */
198 : : void run( const QgsExpressionContext &expressionContext ) const;
199 : :
200 : : /**
201 : : * The action scopes define where an action will be available.
202 : : * Action scopes may offer additional variables like the clicked
203 : : * coordinate.
204 : : *
205 : : * \see QgsActionScope
206 : : * \since QGIS 3.0
207 : : */
208 : : QSet<QString> actionScopes() const;
209 : :
210 : : /**
211 : : * The action scopes define where an action will be available.
212 : : * Action scopes may offer additional variables like the clicked
213 : : * coordinate.
214 : : *
215 : : * \since QGIS 3.0
216 : : */
217 : : void setActionScopes( const QSet<QString> &actionScopes );
218 : :
219 : : /**
220 : : * Reads an XML definition from actionNode
221 : : * into this object.
222 : : *
223 : : * \since QGIS 3.0
224 : : */
225 : : void readXml( const QDomNode &actionNode );
226 : :
227 : : /**
228 : : * Appends an XML definition for this action as a new
229 : : * child node to actionsNode.
230 : : *
231 : : * \since QGIS 3.0
232 : : */
233 : : void writeXml( QDomNode &actionsNode ) const;
234 : :
235 : : /**
236 : : * Sets an expression context scope to use for running the action.
237 : : *
238 : : * \since QGIS 3.0
239 : : */
240 : : void setExpressionContextScope( const QgsExpressionContextScope &scope );
241 : :
242 : : /**
243 : : * Returns an expression context scope used for running the action.
244 : : *
245 : : * \since QGIS 3.0
246 : : */
247 : : QgsExpressionContextScope expressionContextScope() const;
248 : :
249 : : private:
250 : 0 : ActionType mType = Generic;
251 : : QString mDescription;
252 : : QString mShortTitle;
253 : : QString mIcon;
254 : : QString mCommand;
255 : 0 : bool mCaptureOutput = false;
256 : : QSet<QString> mActionScopes;
257 : : QString mNotificationMessage;
258 : : mutable std::shared_ptr<QAction> mAction;
259 : : QUuid mId;
260 : : QgsExpressionContextScope mExpressionContextScope;
261 : 0 : bool mIsEnabledOnlyWhenEditable = false;
262 : : };
263 : :
264 : : Q_DECLARE_METATYPE( QgsAction )
265 : :
266 : : #endif // QGSACTION_H
|
