Branch data     Line data    Source code

       1                 :            : /***************************************************************************
       2                 :            :                          qgsprocessingmodelchildalgorithm.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 QGSPROCESSINGMODELCHILDALGORITHM_H
      19                 :            : #define QGSPROCESSINGMODELCHILDALGORITHM_H
      20                 :            : 
      21                 :            : #include "qgis_core.h"
      22                 :            : #include "qgis.h"
      23                 :            : #include "qgsprocessingmodelcomponent.h"
      24                 :            : #include "qgsprocessingmodelchildparametersource.h"
      25                 :            : #include "qgsprocessingmodeloutput.h"
      26                 :            : #include "qgsprocessingmodelcomment.h"
      27                 :            : #include "qgsprocessingmodelchilddependency.h"
      28                 :            : #include <memory>
      29                 :            : 
      30                 :            : class QgsProcessingModelAlgorithm;
      31                 :            : class QgsProcessingAlgorithm;
      32                 :            : 
      33                 :            : ///@cond NOT_STABLE
      34                 :            : 
      35                 :            : /**
      36                 :            :  * \brief Child algorithm representing a single component of a QgsProcessingModelAlgorithm.
      37                 :            :  * \ingroup core
      38                 :            :  * \since QGIS 3.0
      39                 :            :  */
      40                 :          0 : class CORE_EXPORT QgsProcessingModelChildAlgorithm : public QgsProcessingModelComponent
      41                 :            : {
      42                 :            :   public:
      43                 :            : 
      44                 :            :     /**
      45                 :            :      * Constructor for QgsProcessingModelChildAlgorithm. The \a algorithmId parameter
      46                 :            :      * should be set to a QgsProcessingAlgorithm algorithm ID.
      47                 :            :      */
      48                 :            :     QgsProcessingModelChildAlgorithm( const QString &algorithmId = QString() );
      49                 :            : 
      50                 :            :     QgsProcessingModelChildAlgorithm( const QgsProcessingModelChildAlgorithm &other );
      51                 :            :     QgsProcessingModelChildAlgorithm &operator=( const QgsProcessingModelChildAlgorithm &other );
      52                 :            : 
      53                 :            :     QgsProcessingModelChildAlgorithm *clone() const override SIP_FACTORY;
      54                 :            : 
      55                 :            :     /**
      56                 :            :      * Copies all non-specific definition properties from the the matching component from a \a model.
      57                 :            :      *
      58                 :            :      * This includes properties like the size and position of the component, but not properties
      59                 :            :      * like the specific algorithm or input details.
      60                 :            :      *
      61                 :            :      * \since QGIS 3.14
      62                 :            :      */
      63                 :            :     void copyNonDefinitionPropertiesFromModel( QgsProcessingModelAlgorithm *model );
      64                 :            : 
      65                 :            :     /**
      66                 :            :      * Returns the child algorithm's unique ID string, used the identify
      67                 :            :      * this child algorithm within its parent model.
      68                 :            :      * \see setChildId()
      69                 :            :      * \see generateChildId()
      70                 :            :      */
      71                 :          0 :     QString childId() const { return mId; }
      72                 :            : 
      73                 :            :     /**
      74                 :            :      * Sets the child algorithm's unique \a id string, used the identify
      75                 :            :      * this child algorithm within its parent model.
      76                 :            :      * \see childId()
      77                 :            :      * \see generateChildId()
      78                 :            :      */
      79                 :            :     void setChildId( const QString &id ) { mId = id; }
      80                 :            : 
      81                 :            :     /**
      82                 :            :      * Automatically generates a unique childId() for the algorithm,
      83                 :            :      * avoiding child IDs which are already present in \a model.
      84                 :            :      * \see childId()
      85                 :            :      * \see setChildId()
      86                 :            :      */
      87                 :            :     void generateChildId( const QgsProcessingModelAlgorithm &model );
      88                 :            : 
      89                 :            :     /**
      90                 :            :      * Returns the underlying child algorithm's ID.
      91                 :            :      * \see algorithm()
      92                 :            :      * \see setAlgorithmId()
      93                 :            :      */
      94                 :          0 :     QString algorithmId() const { return mAlgorithmId; }
      95                 :            : 
      96                 :            :     /**
      97                 :            :      * Sets the underlying child algorithm's ID. This
      98                 :            :      * should be set to an existing QgsProcessingAlgorithm algorithm ID.
      99                 :            :      *
     100                 :            :      * Returns TRUE if the algorithm was successfully set.
     101                 :            :      *
     102                 :            :      * \see reattach()
     103                 :            :      * \see algorithm()
     104                 :            :      * \see algorithmId()
     105                 :            :      */
     106                 :            :     bool setAlgorithmId( const QString &algorithmId );
     107                 :            : 
     108                 :            :     /**
     109                 :            :      * Attempts to re-attach the child to the algorithm specified by \a algorithmId().
     110                 :            :      *
     111                 :            :      * This can be run to relink the child to algorithms from providers which were not
     112                 :            :      * originally available for the model to link to.
     113                 :            :      *
     114                 :            :      * Returns TRUE if the algorithm was successfully reattached.
     115                 :            :      *
     116                 :            :      * \see algorithm()
     117                 :            :      * \see setAlgorithmId()
     118                 :            :      */
     119                 :            :     bool reattach() const;
     120                 :            : 
     121                 :            :     /**
     122                 :            :      * Returns the child algorithm's configuration map.
     123                 :            :      *
     124                 :            :      * This map specifies configuration settings which are passed
     125                 :            :      * to the algorithm, allowing it to dynamically adjust its initialized parameters
     126                 :            :      * and outputs according to this configuration. This allows child algorithms in the model
     127                 :            :      * to adjust their behavior at run time according to some user configuration.
     128                 :            :      *
     129                 :            :      * \see setConfiguration()
     130                 :            :      */
     131                 :            :     QVariantMap configuration() const;
     132                 :            : 
     133                 :            :     /**
     134                 :            :      * Sets the child algorithm's \a configuration map.
     135                 :            :      *
     136                 :            :      * This map specifies configuration settings which are passed
     137                 :            :      * to the algorithm, allowing it to dynamically adjust its initialized parameters
     138                 :            :      * and outputs according to this configuration. This allows child algorithms in the model
     139                 :            :      * to adjust their behavior at run time according to some user configuration.
     140                 :            :      *
     141                 :            :      * \see configuration()
     142                 :            :      */
     143                 :            :     void setConfiguration( const QVariantMap &configuration );
     144                 :            : 
     145                 :            :     /**
     146                 :            :      * Returns the underlying child algorithm, or NULLPTR
     147                 :            :      * if a matching algorithm is not available.
     148                 :            :      * \see reattach()
     149                 :            :      * \see algorithmId()
     150                 :            :      */
     151                 :            :     const QgsProcessingAlgorithm *algorithm() const;
     152                 :            : 
     153                 :            :     /**
     154                 :            :      * Returns a map of parameter sources. The keys are the child algorithm
     155                 :            :      * parameter names, the values are the sources for that parameter.
     156                 :            :      * \see setParameterSources()
     157                 :            :      * \see addParameterSources()
     158                 :            :      */
     159                 :          0 :     QMap< QString, QList< QgsProcessingModelChildParameterSource > > parameterSources() const { return mParams; }
     160                 :            : 
     161                 :            :     /**
     162                 :            :      * Sets the map of parameter \a sources. The keys are the child algorithm
     163                 :            :      * parameter names, the values are the sources for that parameter.
     164                 :            :      * \see parameterSources()
     165                 :            :      * \see addParameterSources()
     166                 :            :      */
     167                 :            :     void setParameterSources( const QMap< QString, QList< QgsProcessingModelChildParameterSource > > &sources ) { mParams = sources; }
     168                 :            : 
     169                 :            :     /**
     170                 :            :      * Adds a parameter source. The \a name argument should match
     171                 :            :      * one of the child algorithm's parameter names, and the \a sources
     172                 :            :      * argument is used to set the sources for that parameter.
     173                 :            :      *
     174                 :            :      * Any existing parameter sources with matching name will be replaced.
     175                 :            :      * \see parameterSources()
     176                 :            :      * \see setParameterSources()
     177                 :            :      */
     178                 :            :     void addParameterSources( const QString &name, const QList< QgsProcessingModelChildParameterSource > &source ) { mParams.insert( name, source ); }
     179                 :            : 
     180                 :            :     /**
     181                 :            :      * Returns TRUE if the child algorithm is active.
     182                 :            :      * \see setActive()
     183                 :            :      */
     184                 :          0 :     bool isActive() const { return mActive; }
     185                 :            : 
     186                 :            :     /**
     187                 :            :      * Sets whether the child algorithm is active.
     188                 :            :      * \see isActive()
     189                 :            :      */
     190                 :          0 :     void setActive( bool active ) { mActive = active; }
     191                 :            : 
     192                 :            :     /**
     193                 :            :      * Returns the list of child algorithms from the parent model on which this
     194                 :            :      * algorithm is dependent.
     195                 :            :      * \see setDependencies()
     196                 :            :      */
     197                 :          0 :     QList< QgsProcessingModelChildDependency > dependencies() const { return mDependencies; }
     198                 :            : 
     199                 :            :     /**
     200                 :            :      * Sets the list of child algorithms from the parent model on which this
     201                 :            :      * algorithm is dependent.
     202                 :            :      * \see dependencies()
     203                 :            :      */
     204                 :            :     void setDependencies( const QList< QgsProcessingModelChildDependency > &dependencies ) { mDependencies = dependencies; }
     205                 :            : 
     206                 :            :     /**
     207                 :            :      * Returns the map of final model outputs which are generated by this child algorithm.
     208                 :            :      * The keys are the output names from this child algorithm. Only outputs which are
     209                 :            :      * part of the final outputs from the model are included in this map.
     210                 :            :      * \see setModelOutputs()
     211                 :            :      * \see modelOutput()
     212                 :            :      */
     213                 :          0 :     QMap<QString, QgsProcessingModelOutput> modelOutputs() const { return mModelOutputs; }
     214                 :            : 
     215                 :            :     /**
     216                 :            :      * Returns the final model output with matching \a name. If no output
     217                 :            :      * exists with the name, a new one will be created and returned.
     218                 :            :      *
     219                 :            :      * If child model outputs are altered by this method, QgsProcessingModelAlgorithm::updateDestinationParameters()
     220                 :            :      * must be called on the parent model.
     221                 :            :      *
     222                 :            :      * \see modelOutputs()
     223                 :            :      * \see setModelOutputs()
     224                 :            :      */
     225                 :            :     QgsProcessingModelOutput &modelOutput( const QString &name ) { return mModelOutputs[ name ]; }
     226                 :            : 
     227                 :            :     /**
     228                 :            :      * Sets the map of final model \a outputs which are generated by this child algorithm.
     229                 :            :      * Only outputs which are part of the final outputs from the model should be included in this map.
     230                 :            :      *
     231                 :            :      * If child model outputs are altered by this method, QgsProcessingModelAlgorithm::updateDestinationParameters()
     232                 :            :      * must be called on the parent model.
     233                 :            :      *
     234                 :            :      * \see modelOutputs()
     235                 :            :      */
     236                 :            :     void setModelOutputs( const QMap<QString, QgsProcessingModelOutput> &outputs );
     237                 :            : 
     238                 :            :     /**
     239                 :            :      * Removes an existing output from the final model outputs.
     240                 :            :      *
     241                 :            :      * QgsProcessingModelAlgorithm::updateDestinationParameters() must be called on the parent model.
     242                 :            :      *
     243                 :            :      * \see modelOutputs()
     244                 :            :      * \since QGIS 3.2
     245                 :            :      */
     246                 :            :     bool removeModelOutput( const QString &name );
     247                 :            : 
     248                 :            :     /**
     249                 :            :      * Saves this child to a QVariant.
     250                 :            :      * \see loadVariant()
     251                 :            :      */
     252                 :            :     QVariant toVariant() const;
     253                 :            : 
     254                 :            :     /**
     255                 :            :      * Loads this child from a QVariant.
     256                 :            :      * \see toVariant()
     257                 :            :      */
     258                 :            :     bool loadVariant( const QVariant &child );
     259                 :            : 
     260                 :            :     /**
     261                 :            :      * Attempts to convert the child to executable Python code, and returns a list of the generated lines of code.
     262                 :            :      *
     263                 :            :      * The \a outputType argument specifies the type of script to generate.
     264                 :            :      *
     265                 :            :      * Additional parameters to be passed to the child algorithm are specified in the \a extraParameters argument.
     266                 :            :      *
     267                 :            :      * The \a currentIndent and \a indentSize are used to set the base line indent and size of further indented lines respectively.
     268                 :            :      *
     269                 :            :      * 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.
     270                 :            :      */
     271                 :            :     QStringList asPythonCode( QgsProcessing::PythonOutputType outputType, const QgsStringMap &extraParameters, int currentIndent, int indentSize,
     272                 :            :                               const QMap<QString, QString> &friendlyChildNames, const QMap<QString, QString> &friendlyOutputNames ) const;
     273                 :            : 
     274                 :          0 :     SIP_SKIP const QgsProcessingModelComment *comment() const override { return &mComment; }
     275                 :          0 :     QgsProcessingModelComment *comment() override { return &mComment; }
     276                 :          0 :     void setComment( const QgsProcessingModelComment &comment ) override { mComment = comment; }
     277                 :            : 
     278                 :            :   private:
     279                 :            : 
     280                 :            :     QString mId;
     281                 :            : 
     282                 :            :     QString mAlgorithmId;
     283                 :            :     std::unique_ptr< QgsProcessingAlgorithm > mAlgorithm;
     284                 :            : 
     285                 :            :     QVariantMap mConfiguration;
     286                 :            : 
     287                 :            :     //! A map of parameter sources. Keys are algorithm parameter names.
     288                 :            :     QMap< QString, QgsProcessingModelChildParameterSources > mParams;
     289                 :            : 
     290                 :            :     //! A map of ModelOutput for final model outputs generated by this child algorithm. Keys are output names from the child algorithm.
     291                 :            :     QMap< QString, QgsProcessingModelOutput > mModelOutputs;
     292                 :            : 
     293                 :            :     bool mActive = true;
     294                 :            : 
     295                 :            :     //! List of child algorithms from the parent model on which this algorithm is dependent
     296                 :            :     QList< QgsProcessingModelChildDependency > mDependencies;
     297                 :            : 
     298                 :            :     QgsProcessingModelComment mComment;
     299                 :            : 
     300                 :            :     friend class TestQgsProcessing;
     301                 :            : 
     302                 :            : };
     303                 :            : 
     304                 :            : ///@endcond
     305                 :            : 
     306                 :            : #endif // QGSPROCESSINGMODELCHILDALGORITHM_H