Skip to content
Permalink
Browse files

[FEATURE][API] Add flexible framework for custom "validity checks"

Adds a new interface QgsAbstractValidityCheck which defines
a single "check" which can be performed on a given QgsValidityCheckContext.
A new application-wide QgsValidityCheckRegistry registers
and manages instances of all known checks, and allows running
of all registered checks of a specific type at once.

Initially the framework is focused toward print layout validity
checks, but the interface has been designed to be generic enough
to allow alternative types of validity checks (e.g. project save
validity checks, processing model validity checks, etc.).

The API is designed to be used both by internal validity checks
and also to be extended by custom, organisation-specific
validity checks. E.g., for print layout validity checks we could have:
  • Loading branch information
nyalldawson committed Jan 2, 2019
1 parent ac6e674 commit 7ccaa3df3261a73a0c29f69727841acf60902511
@@ -78,6 +78,7 @@ IF(WITH_APIDOC)
${CMAKE_SOURCE_DIR}/src/core/raster
${CMAKE_SOURCE_DIR}/src/core/scalebar
${CMAKE_SOURCE_DIR}/src/core/symbology
${CMAKE_SOURCE_DIR}/src/core/validity
${CMAKE_SOURCE_DIR}/src/gui
${CMAKE_SOURCE_DIR}/src/gui/auth
${CMAKE_SOURCE_DIR}/src/gui/attributetable
@@ -116,6 +116,7 @@ INCLUDE_DIRECTORIES(
${CMAKE_SOURCE_DIR}/src/core/raster
${CMAKE_SOURCE_DIR}/src/core/scalebar
${CMAKE_SOURCE_DIR}/src/core/symbology
${CMAKE_SOURCE_DIR}/src/core/validity
${CMAKE_SOURCE_DIR}/src/plugins

${CMAKE_BINARY_DIR} # qgsconfig.h, qgsversion.h
@@ -668,6 +668,13 @@ Returns the application's image cache, used for caching resampled versions of ra
Returns the application's network content registry used for fetching temporary files during QGIS session

.. versionadded:: 3.2
%End

static QgsValidityCheckRegistry *validityCheckRegistry();
%Docstring
Returns the application's validity check registry, used for managing validity checks.

.. versionadded:: 3.6
%End

static QgsSymbolLayerRegistry *symbolLayerRegistry();
@@ -0,0 +1,114 @@
/************************************************************************
* This file has been generated automatically from *
* *
* src/core/validity/qgsabstractvaliditycheck.h *
* *
* Do not edit manually ! Edit header and run scripts/sipify.pl again *
************************************************************************/



class QgsValidityCheckResult
{
%Docstring
Represents an individual result from a validity check run by a QgsAbstractValidityCheck subclass.

Results can either be warnings or critical errors, as dictated by the type member. Critical error
are errors which are serious enough to prevent an operation from proceeding, while a warning
result will be communicated to users, but not prevent them from proceeding.

.. versionadded:: 3.6
%End

%TypeHeaderCode
#include "qgsabstractvaliditycheck.h"
%End
public:

enum Type
{
Warning,
Critical,
};

Type type;

QString title;

QString detailedDescription;

QString checkId;

};


class QgsAbstractValidityCheck : QObject
{
%Docstring
Abstract base class for individual validity checks.

Validity checks represent objects which can run a test using a :py:class:`QgsValidityCheckContext`, and return
the results of the check via QgsValidityCheckResult objects.

Checks can be used for many different use cases, e.g. validating a layout's contents before allowing
an export to occur, or validating the contents of a Processing model (and warning if required plugin based
providers are not available or if compulsory algorithm parameters have not been populated).

Subclasses must indicate the type of check the represent via the checkType() method. When checks are performed,
all the registered checks with a matching check type are performed sequentially. The check type also
dictates the subclass of the QgsValidityCheckContext which is given to the subclass' runCheck method.

Checks must be registered in the application's :py:class:`QgsValidityCheckRegistry`, which is accessible via
:py:func:`QgsApplication.validityCheckRegistry()`

.. seealso:: :py:class:`QgsValidityCheckRegistry`

.. versionadded:: 3.6
%End

%TypeHeaderCode
#include "qgsabstractvaliditycheck.h"
%End
public:

enum Type
{
TypeLayoutCheck,
TypeUserCheck,
};

virtual QString id() const = 0;
%Docstring
Returns the unique ID of the check.
%End

virtual int checkType() const = 0;
%Docstring
Returns the type of the check.
%End

virtual QString name() const = 0;
%Docstring
Returns the name of the check.
%End

virtual QList< QgsValidityCheckResult > runCheck( const QgsValidityCheckContext *context, QgsFeedback *feedback ) const = 0;
%Docstring
Runs the check and returns a list of results. If the check is "passed" and no warnings or errors are generated,
then an empty list should be returned.

The ``context`` argument gives the wider in which the check is being run.
%End

};




/************************************************************************
* This file has been generated automatically from *
* *
* src/core/validity/qgsabstractvaliditycheck.h *
* *
* Do not edit manually ! Edit header and run scripts/sipify.pl again *
************************************************************************/
@@ -0,0 +1,61 @@
/************************************************************************
* This file has been generated automatically from *
* *
* src/core/validity/qgsvaliditycheckcontext.h *
* *
* Do not edit manually ! Edit header and run scripts/sipify.pl again *
************************************************************************/



class QgsValidityCheckContext
{
%Docstring
Base class for validity check contexts.

QgsAbstractValidityCheck subclasses are passed a QgsValidityCheckContext subclass which
encapsulates the context around that particular check type. For instance, a QgsAbstractValidityCheck
of the QgsAbstractValidityCheck.TypeLayoutCheck type will be passed a QgsLayoutValidityCheckContext
context, containing a reference to the QgsLayout to be checked.

.. versionadded:: 3.6
%End

%TypeHeaderCode
#include "qgsvaliditycheckcontext.h"
%End
public:

};

class QgsLayoutValidityCheckContext : QgsValidityCheckContext
{
%Docstring
Validity check context for print layout validation.

QgsLayoutValidityCheckContext are passed to QgsAbstractValidityCheck subclasses which
indicate they are of the QgsAbstractValidityCheck.TypeLayoutCheck type.

.. versionadded:: 3.6
%End

%TypeHeaderCode
#include "qgsvaliditycheckcontext.h"
%End
public:

QgsLayoutValidityCheckContext( QgsLayout *layout );
%Docstring
Constructor for QgsLayoutValidityCheckContext for the specified ``layout``.
%End

QgsLayout *layout;

};
/************************************************************************
* This file has been generated automatically from *
* *
* src/core/validity/qgsvaliditycheckcontext.h *
* *
* Do not edit manually ! Edit header and run scripts/sipify.pl again *
************************************************************************/
@@ -0,0 +1,77 @@
/************************************************************************
* This file has been generated automatically from *
* *
* src/core/validity/qgsvaliditycheckregistry.h *
* *
* Do not edit manually ! Edit header and run scripts/sipify.pl again *
************************************************************************/


class QgsValidityCheckRegistry
{
%Docstring
This class keeps a list of QgsAbstractValidityCheck checks which can be used when
performing validity checks.

QgsValidityCheckRegistry is not usually directly created, but rather accessed through
:py:func:`QgsApplication.validityCheckRegistry()`

.. versionadded:: 3.6
%End

%TypeHeaderCode
#include "qgsvaliditycheckregistry.h"
%End
public:

QgsValidityCheckRegistry();

~QgsValidityCheckRegistry();


QList<QgsAbstractValidityCheck *> checks() const;
%Docstring
Returns the list of available checks.
%End

QList<QgsAbstractValidityCheck *> checks( int type ) const;
%Docstring
Returns the list of all available checks of the matching ``type``.
%End

void addCheck( QgsAbstractValidityCheck *check /Transfer/ );
%Docstring
Adds a ``check`` to the registry. Ownership of the check
is transferred to the registry.
%End

void removeCheck( QgsAbstractValidityCheck *check );
%Docstring
Removes a ``check`` from the registry.
The check object is automatically deleted.
%End

QList< QgsValidityCheckResult > runChecks( int type, const QgsValidityCheckContext *context, QgsFeedback *feedback ) const;
%Docstring
Runs all checks of the specified ``type`` and returns a list of results.

If all checks are "passed" and no warnings or errors are generated, then
an empty list will be returned.

The ``context`` argument gives the wider in which the check is being run.

The ``feedback`` argument is used to give progress reports and to support
cancelation of long-running checks.
%End

private:
QgsValidityCheckRegistry( const QgsValidityCheckRegistry &rh );
};

/************************************************************************
* This file has been generated automatically from *
* *
* src/core/validity/qgsvaliditycheckregistry.h *
* *
* Do not edit manually ! Edit header and run scripts/sipify.pl again *
************************************************************************/
@@ -305,6 +305,8 @@
%Include auto_generated/fieldformatter/qgsvaluemapfieldformatter.sip
%Include auto_generated/fieldformatter/qgsvaluerelationfieldformatter.sip
%Include auto_generated/geocms/geonode/qgsgeonodeconnection.sip
%Include auto_generated/validity/qgsvaliditycheckcontext.sip
%Include auto_generated/validity/qgsvaliditycheckregistry.sip
%Include auto_generated/gps/qgsqtlocationconnection.sip
%Include auto_generated/gps/qgsgpsconnectionregistry.sip
%Include auto_generated/qgsabstractcontentcache.sip
@@ -452,6 +454,7 @@
%Include auto_generated/layertree/qgslayertreemodellegendnode.sip
%Include auto_generated/layertree/qgslayertreenode.sip
%Include auto_generated/layertree/qgslayertreeregistrybridge.sip
%Include auto_generated/validity/qgsabstractvaliditycheck.sip
%Include auto_generated/qgsuserprofilemanager.sip
%Include auto_generated/symbology/qgsarrowsymbollayer.sip
%Include auto_generated/qgsuserprofile.sip

0 comments on commit 7ccaa3d

Please sign in to comment.
You can’t perform that action at this time.