1 /***************************************************************************
2                          qgsprocessingfeedback.h
3                          -----------------------
4     begin                : December 2016
5     copyright            : (C) 2016 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 QGSPROCESSINGFEEDBACK_H
19 #define QGSPROCESSINGFEEDBACK_H
20 
21 #include "qgis_core.h"
22 #include "qgsfeedback.h"
23 #include "qgsmessagelog.h"
24 
25 class QgsProcessingProvider;
26 
27 /**
28  * \class QgsProcessingFeedback
29  * \ingroup core
30  * \brief Base class for providing feedback from a processing algorithm.
31  *
32  * This base class implementation silently ignores all feedback reported by algorithms.
33  * Subclasses of QgsProcessingFeedback can be used to log this feedback or report
34  * it to users via the GUI.
35  * \since QGIS 3.0
36  */
37 class CORE_EXPORT QgsProcessingFeedback : public QgsFeedback
38 {
39     Q_OBJECT
40 
41   public:
42 
43     /**
44      * Constructor for QgsProcessingFeedback.
45      *
46      * If \a logFeedback is TRUE, then all feedback received will be directed
47      * to QgsMessageLog.
48      */
49     QgsProcessingFeedback( bool logFeedback = true );
50 
51     /**
52      * Sets a progress report text string. This can be used in conjunction with
53      * setProgress() to provide detailed progress reports, such as "Transformed
54      * 4 of 5 layers".
55      * \see setProgress()
56      */
57     virtual void setProgressText( const QString &text );
58 
59     /**
60      * Reports that the algorithm encountered an \a error while executing.
61      *
62      * If \a fatalError is TRUE then the error prevented the algorithm from executing.
63      */
64     virtual void reportError( const QString &error, bool fatalError = false );
65 
66     /**
67      * Pushes a warning informational message from the algorithm. This
68      * should only be used sparsely as to maintain the importance of visual
69      * queues associated to this type of message.
70      * \see pushInfo()
71      * \see pushCommandInfo()
72      * \see pushDebugInfo()
73      * \see pushConsoleInfo()
74      * \since QGIS 3.16.4
75      */
76     virtual void pushWarning( const QString &warning );
77 
78     /**
79      * Pushes a general informational message from the algorithm. This can
80      * be used to report feedback which is neither a status report or an
81      * error, such as "Found 47 matching features".
82      * \see pushWarning()
83      * \see pushCommandInfo()
84      * \see pushDebugInfo()
85      * \see pushConsoleInfo()
86      */
87     virtual void pushInfo( const QString &info );
88 
89     /**
90      * Pushes an informational message containing a command from the algorithm.
91      * This is usually used to report commands which are executed in an external
92      * application or as subprocesses.
93      * \see pushWarning()
94      * \see pushInfo()
95      * \see pushDebugInfo()
96      * \see pushConsoleInfo()
97      */
98     virtual void pushCommandInfo( const QString &info );
99 
100     /**
101      * Pushes an informational message containing debugging helpers from
102      * the algorithm.
103      * \see pushWarning()
104      * \see pushInfo()
105      * \see pushCommandInfo()
106      * \see pushConsoleInfo()
107      */
108     virtual void pushDebugInfo( const QString &info );
109 
110     /**
111      * Pushes a console feedback message from the algorithm. This is used to
112      * report the output from executing an external command or subprocess.
113      * \see pushWarning()
114      * \see pushInfo()
115      * \see pushDebugInfo()
116      * \see pushCommandInfo()
117      */
118     virtual void pushConsoleInfo( const QString &info );
119 
120     /**
121      * Pushes a summary of the QGIS (and underlying library) version information to the log.
122      * \since QGIS 3.4.7
123      */
124     void pushVersionInfo( const QgsProcessingProvider *provider = nullptr );
125 
126     /**
127      * Returns the HTML formatted contents of the log, which contains all messages pushed to the feedback object.
128      *
129      * \see textLog()
130      * \since QGIS 3.14
131      */
132     virtual QString htmlLog() const;
133 
134     /**
135      * Returns the plain text contents of the log, which contains all messages pushed to the feedback object.
136      *
137      * \see htmlLog()
138      * \since QGIS 3.14
139      */
140     virtual QString textLog() const;
141 
142   private:
143 
144     void log( const QString &htmlMessage, const QString &textMessage );
145 
146     bool mLogFeedback = true;
147     QString mHtmlLog;
148     QString mTextLog;
149     int mMessageLoggedCount = 0;
150 
151 };
152 
153 
154 /**
155  * \class QgsProcessingMultiStepFeedback
156  * \ingroup core
157  *
158  * \brief Processing feedback object for multi-step operations.
159  *
160  * A processing feedback object which proxies its calls to an underlying
161  * feedback object, but scales overall progress reports to account
162  * for a number of child steps which each report their own feedback.
163  *
164  * \since QGIS 3.0
165  */
166 class CORE_EXPORT QgsProcessingMultiStepFeedback : public QgsProcessingFeedback
167 {
168     Q_OBJECT
169 
170   public:
171 
172     /**
173      * Constructor for QgsProcessingMultiStepFeedback, for a process with the specified
174      * number of \a steps. This feedback object will proxy calls
175      * to the specified \a feedback object.
176      */
177     QgsProcessingMultiStepFeedback( int steps, QgsProcessingFeedback *feedback );
178 
179     /**
180      * Sets the \a step which is being executed. This is used
181      * to scale the current progress to account for progress through the overall process.
182      */
183     void setCurrentStep( int step );
184 
185     void setProgressText( const QString &text ) override;
186     void reportError( const QString &error, bool fatalError = false ) override;
187     void pushWarning( const QString &warning ) override;
188     void pushInfo( const QString &info ) override;
189     void pushCommandInfo( const QString &info ) override;
190     void pushDebugInfo( const QString &info ) override;
191     void pushConsoleInfo( const QString &info ) override;
192     QString htmlLog() const override;
193     QString textLog() const override;
194   private slots:
195 
196     void updateOverallProgress( double progress );
197 
198   private:
199 
200     int mChildSteps = 0;
201     int mCurrentStep = 0;
202     QgsProcessingFeedback *mFeedback = nullptr;
203 
204 };
205 
206 #endif // QGSPROCESSINGFEEDBACK_H
207 
208 
209