1 /*************************************************************************** 2 qgsprocessingmodelchildparametersource.h 3 ---------------------------------------- 4 begin : June 2017 5 copyright : (C) 2017 by Nyall Dawson 6 email : nyall dot dawson at gmail dot com 7 ***************************************************************************/ 8 9 /*************************************************************************** 10 * * 11 * This program is free software; you can redistribute it and/or modify * 12 * it under the terms of the GNU General Public License as published by * 13 * the Free Software Foundation; either version 2 of the License, or * 14 * (at your option) any later version. * 15 * * 16 ***************************************************************************/ 17 18 #ifndef QGSPROCESSINGMODELCHILDPARAMETERSOURCE_H 19 #define QGSPROCESSINGMODELCHILDPARAMETERSOURCE_H 20 21 #include "qgis_core.h" 22 #include "qgis.h" 23 #include "qgsprocessing.h" 24 class QgsProcessingParameterDefinition; 25 class QgsProcessingModelAlgorithm; 26 27 ///@cond NOT_STABLE 28 29 /** 30 * \brief Source for the value of a parameter for a child algorithm within a model. 31 * \ingroup core 32 * \since QGIS 3.0 33 */ 34 class CORE_EXPORT QgsProcessingModelChildParameterSource 35 { 36 public: 37 38 //! Possible parameter value sources 39 enum Source 40 { 41 ModelParameter, //!< Parameter value is taken from a parent model parameter 42 ChildOutput, //!< Parameter value is taken from an output generated by a child algorithm 43 StaticValue, //!< Parameter value is a static value 44 Expression, //!< Parameter value is taken from an expression, evaluated just before the algorithm runs 45 ExpressionText, //!< Parameter value is taken from a text with expressions, evaluated just before the algorithm runs 46 ModelOutput, //!< Parameter value is linked to an output parameter for the model 47 }; 48 49 /** 50 * Constructor for QgsProcessingModelChildParameterSource. It is recommended that the static methods 51 * fromStaticValue(), fromModelParameter(), fromChildOutput() and fromExpression() are used instead. 52 */ 53 QgsProcessingModelChildParameterSource() = default; 54 55 bool operator==( const QgsProcessingModelChildParameterSource &other ) const; 56 bool operator!=( const QgsProcessingModelChildParameterSource &other ) const 57 { 58 return !operator==( other ); 59 } 60 61 /** 62 * Returns a new QgsProcessingModelChildParameterSource which takes its value from a static \a value. 63 * \see fromModelParameter() 64 * \see fromChildOutput() 65 * \see fromExpression() 66 * \see fromExpressionText() 67 */ 68 static QgsProcessingModelChildParameterSource fromStaticValue( const QVariant &value ); 69 70 /** 71 * Returns a new QgsProcessingModelChildParameterSource which takes its value from a parent model parameter. 72 * \see fromStaticValue() 73 * \see fromChildOutput() 74 * \see fromExpression() 75 * \see fromExpressionText() 76 */ 77 static QgsProcessingModelChildParameterSource fromModelParameter( const QString ¶meterName ); 78 79 /** 80 * Returns a new QgsProcessingModelChildParameterSource which takes its value from an output generated by a child algorithm. 81 * \see fromStaticValue() 82 * \see fromModelParameter() 83 * \see fromExpression() 84 * \see fromExpressionText() 85 */ 86 static QgsProcessingModelChildParameterSource fromChildOutput( const QString &childId, const QString &outputName ); 87 88 /** 89 * Returns a new QgsProcessingModelChildParameterSource which takes its value from an expression. The expression 90 * is evaluated just before the child algorithm executes, and can use functions available 91 * in its expression context to include results calculated from the child algorithms already 92 * executed by the model. 93 * \see fromStaticValue() 94 * \see fromChildOutput() 95 * \see fromModelParameter() 96 * \see fromExpressionText() 97 * \since QGIS 3.2 98 */ 99 static QgsProcessingModelChildParameterSource fromExpression( const QString &expression ); 100 101 /** 102 * Returns a new QgsProcessingModelChildParameterSource which takes its 103 * value from a text with expressions. Expressions are evaluated just before 104 * the child algorithm executes, and can use functions available 105 * in its expression context to include results calculated from the child 106 * algorithms already executed by the model. 107 * \see fromStaticValue() 108 * \see fromChildOutput() 109 * \see fromModelParameter() 110 * \see fromExpression() 111 * \since QGIS 3.2 112 */ 113 static QgsProcessingModelChildParameterSource fromExpressionText( const QString &text ); 114 115 /** 116 * Returns the parameter value's source. 117 */ 118 Source source() const; 119 120 /** 121 * Sets the parameter's source. 122 * 123 * \since QGIS 3.14 124 */ 125 void setSource( Source source ); 126 127 /** 128 * Returns the source's static value. This is only used when the source() is StaticValue. 129 * \see setStaticValue() 130 */ staticValue()131 QVariant staticValue() const { return mStaticValue; } 132 133 /** 134 * Sets the source's static value. Calling this will also change the source() to StaticValue. 135 * \see staticValue() 136 */ setStaticValue(const QVariant & value)137 void setStaticValue( const QVariant &value ) { mStaticValue = value; mSource = StaticValue; } 138 139 /** 140 * Returns the source's model parameter name. This is only used when the source() is ModelParameter. 141 * \see setParameterName() 142 */ parameterName()143 QString parameterName() const { return mParameterName; } 144 145 /** 146 * Sets the source's model parameter \a name. Calling this will also change the source() to ModelParameter. 147 * \see parameterName() 148 */ setParameterName(const QString & name)149 void setParameterName( const QString &name ) { mParameterName = name; mSource = ModelParameter; } 150 151 /** 152 * Returns the source's child algorithm ID from which the output value will be taken. This is only used when the source() is ChildOutput. 153 * \see setOutputChildId() 154 * \see outputName() 155 */ outputChildId()156 QString outputChildId() const { return mChildId; } 157 158 /** 159 * Sets the source's child algorithm \a id from which the output value will be taken. Calling this will also change the source() to ChildOutput. 160 * \see parameterName() 161 * \see setOutputName() 162 */ setOutputChildId(const QString & id)163 void setOutputChildId( const QString &id ) { mChildId = id; mSource = ChildOutput; } 164 165 /** 166 * Returns the source's child algorithm output name from which the output value will be taken. This is only used when the source() is ChildOutput. 167 * \see setOutputName() 168 * \see outputChildId() 169 */ outputName()170 QString outputName() const { return mOutputName; } 171 172 /** 173 * Sets the source's child algorithm output \a name from which the output value will be taken. Calling this will also change the source() to ChildOutput. 174 * \see outputName() 175 * \see setOutputChildId() 176 */ setOutputName(const QString & name)177 void setOutputName( const QString &name ) { mOutputName = name; mSource = ChildOutput; } 178 179 /** 180 * Returns the source's expression. This is only used when the source() is Expression. 181 * \see setExpression() 182 */ expression()183 QString expression() const { return mExpression; } 184 185 /** 186 * Sets the source's expression. Calling this will also change the source() to Expression. 187 * The expression is evaluated just before the child algorithm executes, and can use functions available 188 * in its expression context to include results calculated from the child algorithms already 189 * executed by the model. 190 * \see expression() 191 */ setExpression(const QString & expression)192 void setExpression( const QString &expression ) { mExpression = expression; mSource = Expression; } 193 194 /** 195 * Returns the source's text with expressions. This is only used when the 196 * source() is ExpressionText. 197 * \see setExpressionText() 198 * \since QGIS 3.2 199 */ expressionText()200 QString expressionText() const { return mExpressionText; } 201 202 /** 203 * Sets the source's text containing expressions. Calling this will also 204 * change the source() to ExpressionText. Expressions are evaluated just 205 * before the child algorithm executes, and can use functions available 206 * in its expression context to include results calculated from the child 207 * algorithms already executed by the model. 208 * \see expressionText() 209 * \since QGIS 3.2 210 */ setExpressionText(const QString & text)211 void setExpressionText( const QString &text ) { mExpressionText = text; mSource = ExpressionText; } 212 213 /** 214 * Saves this source to a QVariant. 215 * \see loadVariant() 216 */ 217 QVariant toVariant() const; 218 219 /** 220 * Loads this source from a QVariantMap. 221 * \see toVariant() 222 */ 223 bool loadVariant( const QVariantMap &map ); 224 225 /** 226 * Attempts to convert the source to executable Python code. 227 * 228 * The \a friendlyChildNames argument gives a map of child id to a friendly algorithm name, to be used in the code to identify that algorithm instead of the raw child id. 229 */ 230 QString asPythonCode( QgsProcessing::PythonOutputType outputType, const QgsProcessingParameterDefinition *definition, const QMap< QString, QString > &friendlyChildNames ) const; 231 232 /** 233 * Returns an explanatory Python comment for the source, or an empty string if no comment is available. 234 * 235 * \since QGIS 3.20 236 */ 237 QString asPythonComment( const QgsProcessingParameterDefinition *definition ) const; 238 239 /** 240 * Returns a user-friendly identifier for this source, given the context of the specified \a model. 241 * \since QGIS 3.14 242 */ 243 QString friendlyIdentifier( QgsProcessingModelAlgorithm *model ) const; 244 245 private: 246 247 Source mSource = StaticValue; 248 QVariant mStaticValue; 249 QString mParameterName; 250 QString mChildId; 251 QString mOutputName; 252 QString mExpression; 253 QString mExpressionText; 254 255 }; 256 257 Q_DECLARE_METATYPE( QgsProcessingModelChildParameterSource ); 258 CORE_EXPORT QDataStream &operator<<( QDataStream &out, const QgsProcessingModelChildParameterSource &source ); 259 CORE_EXPORT QDataStream &operator>>( QDataStream &in, QgsProcessingModelChildParameterSource &source ); 260 261 #ifndef SIP_RUN 262 //! List of child parameter sources 263 typedef QList< QgsProcessingModelChildParameterSource > QgsProcessingModelChildParameterSources; 264 #endif 265 266 ///@endcond 267 268 #endif // QGSPROCESSINGMODELCHILDPARAMETERSOURCE_H 269