Class: QgsProcessingAlgorithmWidgetBase¶

Base class for widgets which contain settings for running Processing algorithms.

Note

This is not considered stable API and may change in future QGIS versions.

Note

This is an abstract class, with methods which must be implemented by a subclass.

The following methods must be implemented: QgsProcessingParametersGenerator.createProcessingParameters(), QgsProcessingContextGenerator.processingContext()

List of all members, including inherited members

Class Hierarchy¶

Base classes¶

QDialog
QWidget
QObject
QPaintDevice
`QgsProcessingParametersGenerator`	An interface for objects which can create sets of parameter values for processing algorithms.
`QgsProcessingContextGenerator`	An interface for objects which can create Processing contexts.

Subclasses¶

QgsProcessingBatchAlgorithmDialogBase

Base class for processing batch algorithm dialogs.

Constructor

__init__

Enums

`LogFormat`	Log format options.
`WidgetMode`	Widget modes.

Methods

`algorithm`	Returns the algorithm running in the widget.
`applyContextOverrides`	Applies any defined overrides for Processing context settings to the specified context.
`blockControlsWhileRunning`	Blocks run and changeParameters buttons and parameters tab while the algorithm is running.
`buttonBox`	Returns the widget's button box.
`cancel`	Cancels any algorithm currently running through the widget.
`cancelButton`	Returns the widget's cancel button.
`changeParametersButton`	Returns the widget's change parameters button.
`clearLog`	Clears the current log contents.
`clearProgress`	Clears any current progress from the widget.
`copyLogToClipboard`	Copies the current log contents to the clipboard.
`createFeedback`	Creates a new processing feedback object, automatically connected to the appropriate slots in this widget.
`createProgressDialog`	Creates a modal progress dialog showing progress and log messages from this widget.
`forceClose`	Forces the widget to close by detaching any running task from the widget THEN closing the widget.
`hideShortHelp`	Hides the short help panel.
`logLevel`	Returns the logging level to use when running algorithms from the widget.
`mainWidget`	Returns the main widget for the widget, usually a panel for configuring algorithm parameters.
`messageBar`	Returns the widget's message bar.
`pushCommandInfo`	Pushes command info to the widget's log.
`pushConsoleInfo`	Pushes a console info string to the widget's log.
`pushDebugInfo`	Pushes a debug info string to the widget's log.
`pushFormattedMessage`	Pushes a pre-formatted message to the widget's log
`pushInfo`	Pushes an information string to the widget's log.
`pushWarning`	Pushes a warning information string to the widget's log.
`registerProcessingFeedbackGenerator`	Registers a generator for creating `QgsProcessingFeedback` objects for use in the widget.
`reportError`	Reports an error string to the widget's log.
`resetGui`	Resets the widget's GUI, ready for another algorithm execution.
`results`	Returns the results returned by the algorithm executed.
`runButton`	Returns the widget's run button.
`saveLog`	Opens a dialog allowing users to save the current log contents.
`saveLogToFile`	Saves the log contents to a text file (specified by the file path), in the given format.
`setAlgorithm`	Sets the algorithm to run in the widget.
`setCurrentTask`	Sets the current task running in the widget.
`setExecuted`	Sets whether the algorithm was executed through the widget.
`setExecutedAnyResult`	Sets whether the algorithm was executed through the widget (no matter the result).
`setInfo`	Displays an info message in the widget's log.
`setLogLevel`	Sets the logging level to use when running algorithms from the widget.
`setMainWidget`	Sets the main widget for the widget, usually a panel for configuring algorithm parameters.
`setPercentage`	Sets the percentage progress for the widget, between 0 and 100.
`setProgressText`	Sets a progress text message.
`setResults`	Sets the algorithm results.
`showLog`	Switches the widget to the log page.
`showParameters`	Switches the widget to the parameters page.
`showWidget`	Shows and raises the widget
`tabWidget`	Returns the widget's tab widget.
`updateRunButtonVisibility`	Sets visibility for mutually exclusive buttons Run and Change Parameters.
`wasExecuted`	Returns `True` if an algorithm was executed in the widget.

Virtual Methods

In PyQGIS, only methods marked as virtual can be safely overridden in a Python subclass of QgsProcessingAlgorithmWidgetBase. See the FAQ for more details.

`algExecuted`	Called when an algorithm task has completed.
`blockAdditionalControlsWhileRunning`	For subclasses to register their own GUI controls to be blocked while the algorithm is running.
`finished`	Called when the algorithm has finished executing.
`isFinalized`	Returns `True` if the widget is all finalized and can be safely deleted.
`isRunning`	Returns `True` if the widget is currently running an algorithm.
`resetAdditionalGui`	For subclasses to register their own GUI controls to be reset, ready for another algorithm execution.
`runAlgorithm`	Called when the widget's algorithm should be run.
`setParameters`	Sets the parameter values to show in the widget.

Static Methods

formatStringForLog

Formats an input string for display in the log tab.

Signals

`algorithmAboutToRun`	Emitted when the algorithm is about to run in the specified context.
`algorithmFinished`	Emitted whenever an algorithm has finished executing in the widget.

class qgis.gui.QgsProcessingAlgorithmWidgetBase[source]¶

Bases: QDialog, QgsProcessingParametersGenerator, QgsProcessingContextGenerator

__init__(parent: QWidget | None = None, mode: QgsProcessingAlgorithmWidgetBase.WidgetMode = QgsProcessingAlgorithmWidgetBase.WidgetMode.Single)¶

Constructor for QgsProcessingAlgorithmWidgetBase.

Parameters:

parent (Optional[QWidget] = None)
mode (QgsProcessingAlgorithmWidgetBase.WidgetMode = QgsProcessingAlgorithmWidgetBase.WidgetMode.Single)

class LogFormat(*values)¶

Bases: IntEnum

Log format options.

Added in version 3.2.

FormatPlainText: Plain text file (.txt)
FormatHtml: HTML file (.html)

FormatHtml = 1¶

FormatPlainText = 0¶

class WidgetMode(*values)¶

Bases: IntEnum

Widget modes.

Added in version 3.24.

Single: Single algorithm execution mode
Batch: Batch processing mode

Batch = 1¶

Single = 0¶

virtual algExecuted(self, successful: bool, results: dict[str | None, Any])[source]¶

Called when an algorithm task has completed.

Added in version 3.26.

Parameters:

successful (bool)
results (dict[Optional[str], Any])

algorithm(self) → QgsProcessingAlgorithm | None[source]¶

Returns the algorithm running in the widget.

See also

setAlgorithm()

Return type:: Optional[QgsProcessingAlgorithm]

signal algorithmAboutToRun(context: QgsProcessingContext)[source]¶

Emitted when the algorithm is about to run in the specified context.

This signal can be used to tweak the context prior to the algorithm execution.

Added in version 3.38.

Parameters:: context (QgsProcessingContext)

signal algorithmFinished(successful: bool, result: Dict[str, object])[source]¶

Emitted whenever an algorithm has finished executing in the widget.

Added in version 3.14.

Parameters:

successful (bool)
result (Dict[str, object])

applyContextOverrides(self, context: QgsProcessingContext | None)[source]¶

Applies any defined overrides for Processing context settings to the specified context.

This allows the widget to override default Processing settings for an individual algorithm execution.

Added in version 3.32.

Parameters:: context (Optional[QgsProcessingContext])

virtual blockAdditionalControlsWhileRunning(self)[source]¶: For subclasses to register their own GUI controls to be blocked while the algorithm is running.

blockControlsWhileRunning(self)[source]¶: Blocks run and changeParameters buttons and parameters tab while the algorithm is running.

buttonBox(self) → QDialogButtonBox | None[source]¶

Returns the widget’s button box.

Return type:: Optional[QDialogButtonBox]

cancel(self)[source]¶: Cancels any algorithm currently running through the widget.

Note

The cancellation is non-blocking, and may take some time to complete. Some algorithms ignore cancellation requests entirely. This method returns immediately after requesting the cancellation, but the algorithm may still be running after return.

Added in version 4.2.

cancelButton(self) → QPushButton | None[source]¶

Returns the widget’s cancel button.

Return type:: Optional[QPushButton]

changeParametersButton(self) → QPushButton | None[source]¶

Returns the widget’s change parameters button.

Return type:: Optional[QPushButton]

clearLog(self)[source]¶: Clears the current log contents.

Added in version 3.2.

clearProgress(self)[source]¶: Clears any current progress from the widget.

copyLogToClipboard(self)[source]¶: Copies the current log contents to the clipboard.

Added in version 3.2.

createFeedback(self) → QgsProcessingFeedback | None[source]¶

Creates a new processing feedback object, automatically connected to the appropriate slots in this widget.

See also

registerProcessingFeedbackFactory()

Return type:: Optional[QgsProcessingFeedback]

createProgressDialog(self) → QDialog | None[source]¶

Creates a modal progress dialog showing progress and log messages from this widget.

Return type:: Optional[QDialog]

virtual finished(self, successful: bool, result: dict[str | None, Any], context: QgsProcessingContext, feedback: QgsProcessingFeedback | None)[source]¶

Called when the algorithm has finished executing.

Parameters:

successful (bool)
result (dict[Optional[str], Any])
context (QgsProcessingContext)
feedback (Optional[QgsProcessingFeedback])

forceClose(self)[source]¶: Forces the widget to close by detaching any running task from the widget THEN closing the widget.

Added in version 4.2.

static formatStringForLog(string: str | None) → str[source]¶

Formats an input string for display in the log tab.

Parameters:: string (Optional[str])
Return type:: str

hideShortHelp(self)[source]¶: Hides the short help panel.

virtual isFinalized(self) → bool[source]¶

Returns True if the widget is all finalized and can be safely deleted.

Added in version 3.26.

Return type:: bool

virtual isRunning(self) → bool[source]¶

Returns True if the widget is currently running an algorithm.

If the algorithm has not yet started or has finished executing then False will be returned.

Note

Unlike the isFinalized() method, isRunning() only provides information about the state of widget and is not tied to the deletion mechanisms of the widget.

See also

isFinalized()

Added in version 4.2.

Return type:: bool

logLevel(self) → Qgis.ProcessingLogLevel[source]¶

Returns the logging level to use when running algorithms from the widget.

See also

setLogLevel()

Added in version 3.20.

Return type:: Qgis.ProcessingLogLevel

mainWidget(self) → QgsPanelWidget | None[source]¶

Returns the main widget for the widget, usually a panel for configuring algorithm parameters.

See also

setMainWidget()

Return type:: Optional[QgsPanelWidget]

messageBar(self) → QgsMessageBar | None[source]¶

Returns the widget’s message bar.

Return type:: Optional[QgsMessageBar]

pushCommandInfo(self, info: str | None)[source]¶

Pushes command info to the widget’s log.

Parameters:: info (Optional[str])

pushConsoleInfo(self, info: str | None)[source]¶

Pushes a console info string to the widget’s log.

Parameters:: info (Optional[str])

pushDebugInfo(self, message: str | None)[source]¶

Pushes a debug info string to the widget’s log.

Parameters:: message (Optional[str])

pushFormattedMessage(self, html: str | None)[source]¶

Pushes a pre-formatted message to the widget’s log

This can be used to push formatted HTML messages to the widget.

Added in version 3.36.

Parameters:: html (Optional[str])

pushInfo(self, info: str | None)[source]¶

Pushes an information string to the widget’s log.

Parameters:: info (Optional[str])

pushWarning(self, warning: str | None)[source]¶

Pushes a warning information string to the widget’s log.

Parameters:: warning (Optional[str])

registerProcessingFeedbackGenerator(self, generator: QgsProcessingFeedbackGenerator | None)[source]¶

Registers a generator for creating QgsProcessingFeedback objects for use in the widget.

Ownership of generator is not transferred, the caller is responsible for ensuring that it exists for the lifetime of the widget.

If no generator is registered then a default QgsProcessingFeedback object will be created.

See also

createFeedback()

Added in version 4.2.

Parameters:: generator (Optional[QgsProcessingFeedbackGenerator])

reportError(self, error: str | None, fatalError: bool)[source]¶

Reports an error string to the widget’s log.

If fatalError is True, the error prevented the algorithm from executing.

Parameters:

error (Optional[str])
fatalError (bool)

virtual resetAdditionalGui(self)[source]¶: For subclasses to register their own GUI controls to be reset, ready for another algorithm execution.

resetGui(self)[source]¶: Resets the widget’s GUI, ready for another algorithm execution.

results(self) → dict[str, Any][source]¶

Returns the results returned by the algorithm executed.

See also

wasExecuted()

See also

setResults()

Return type:: dict[str, Any]

virtual runAlgorithm(self)[source]¶: Called when the widget’s algorithm should be run. Must be overridden by subclasses.

runButton(self) → QPushButton | None[source]¶

Returns the widget’s run button.

Return type:: Optional[QPushButton]

saveLog(self)[source]¶: Opens a dialog allowing users to save the current log contents.

See also

saveLogToFile()

Added in version 3.2.

saveLogToFile(self, path: str | None, format: QgsProcessingAlgorithmWidgetBase.LogFormat = QgsProcessingAlgorithmWidgetBase.LogFormat.FormatPlainText)[source]¶

Saves the log contents to a text file (specified by the file path), in the given format.

See also

saveLog()

Added in version 3.2.

Parameters:

path (Optional[str])
format (QgsProcessingAlgorithmWidgetBase.LogFormat = QgsProcessingAlgorithmWidgetBase.LogFormat.FormatPlainText)

setAlgorithm(self, algorithm: QgsProcessingAlgorithm | None)[source]¶

Sets the algorithm to run in the widget.

Ownership of the algorithm instance is transferred to the widget.

See also

algorithm()

Parameters:: algorithm (Optional[QgsProcessingAlgorithm])

setCurrentTask(self, task: QgsProcessingAlgRunnerTask | None)[source]¶

Sets the current task running in the widget. The task will automatically be started by the widget. Ownership of task is transferred to the widget.

Parameters:: task (Optional[QgsProcessingAlgRunnerTask])

setExecuted(self, executed: bool)[source]¶

Sets whether the algorithm was executed through the widget.

See also

wasExecuted()

See also

setResults()

Parameters:: executed (bool)

setExecutedAnyResult(self, executedAnyResult: bool)[source]¶

Sets whether the algorithm was executed through the widget (no matter the result).

Parameters:: executedAnyResult (bool)

setInfo(self, message: str | None, isError: bool = False, escapeHtml: bool = True, isWarning: bool = False)[source]¶

Displays an info message in the widget’s log.

Parameters:

message (Optional[str])
isError (bool = False)
escapeHtml (bool = True)
isWarning (bool = False)

setLogLevel(self, level: Qgis.ProcessingLogLevel)[source]¶

Sets the logging level to use when running algorithms from the widget.

See also

logLevel()

Added in version 3.20.

Parameters:: level (Qgis.ProcessingLogLevel)

setMainWidget(self, widget: QgsPanelWidget | None)[source]¶

Sets the main widget for the widget, usually a panel for configuring algorithm parameters.

See also

mainWidget()

Parameters:: widget (Optional[QgsPanelWidget])

virtual setParameters(self, values: dict[str | None, Any])[source]¶

Sets the parameter values to show in the widget.

Added in version 3.24.

Parameters:: values (dict[Optional[str], Any])

setPercentage(self, percent: float)[source]¶

Sets the percentage progress for the widget, between 0 and 100.

Parameters:: percent (float)

setProgressText(self, text: str | None)[source]¶

Sets a progress text message.

Parameters:: text (Optional[str])

setResults(self, results: dict[str | None, Any])[source]¶

Sets the algorithm results.

See also

results()

See also

setExecuted()

Parameters:: results (dict[Optional[str], Any])

showLog(self)[source]¶: Switches the widget to the log page.

showParameters(self)[source]¶: Switches the widget to the parameters page.

showWidget(self)[source]¶: Shows and raises the widget

Added in version 4.2.

tabWidget(self) → QTabWidget | None[source]¶

Returns the widget’s tab widget.

Return type:: Optional[QTabWidget]

updateRunButtonVisibility(self)[source]¶: Sets visibility for mutually exclusive buttons Run and Change Parameters.

wasExecuted(self) → bool[source]¶

Returns True if an algorithm was executed in the widget.

See also

results()

See also

setExecuted()

Return type:: bool