2017-05-16 08:39:03 +02:00
|
|
|
/************************************************************************
|
|
|
|
* This file has been generated automatically from *
|
|
|
|
* *
|
|
|
|
* src/core/qgsexpressioncontext.h *
|
|
|
|
* *
|
|
|
|
* Do not edit manually ! Edit header and run scripts/sipify.pl again *
|
|
|
|
************************************************************************/
|
|
|
|
|
|
|
|
|
|
|
|
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2017-05-14 11:20:29 +02:00
|
|
|
class QgsScopedExpressionFunction : QgsExpressionFunction
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
{
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Expression function for use within a QgsExpressionContextScope. This differs from a
|
|
|
|
standard QgsExpression.Function in that it requires an implemented
|
|
|
|
clone() method.
|
|
|
|
.. versionadded:: 2.12
|
|
|
|
%End
|
|
|
|
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
%TypeHeaderCode
|
2017-05-16 08:39:03 +02:00
|
|
|
#include "qgsexpressioncontext.h"
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
%End
|
|
|
|
public:
|
2017-05-16 08:39:03 +02:00
|
|
|
|
|
|
|
QgsScopedExpressionFunction( const QString &fnname,
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
int params,
|
2017-05-16 08:39:03 +02:00
|
|
|
const QString &group,
|
|
|
|
const QString &helpText = QString(),
|
2017-01-09 13:51:53 +10:00
|
|
|
bool usesGeometry = false,
|
2017-05-16 08:39:03 +02:00
|
|
|
const QSet<QString> &referencedColumns = QSet<QString>(),
|
2017-01-09 13:51:53 +10:00
|
|
|
bool lazyEval = false,
|
|
|
|
bool handlesNull = false,
|
|
|
|
bool isContextual = true );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Create a new QgsScopedExpressionFunction
|
|
|
|
|
|
|
|
.. versionadded:: 2.12
|
|
|
|
%End
|
2017-01-09 13:51:53 +10:00
|
|
|
|
2017-05-16 08:39:03 +02:00
|
|
|
QgsScopedExpressionFunction( const QString &fnname,
|
2017-05-14 11:20:29 +02:00
|
|
|
const QgsExpressionFunction::ParameterList ¶ms,
|
2017-05-16 08:39:03 +02:00
|
|
|
const QString &group,
|
|
|
|
const QString &helpText = QString(),
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
bool usesGeometry = false,
|
2017-05-16 08:39:03 +02:00
|
|
|
const QSet<QString> &referencedColumns = QSet<QString>(),
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
bool lazyEval = false,
|
2015-08-20 15:06:09 +10:00
|
|
|
bool handlesNull = false,
|
|
|
|
bool isContextual = true );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Create a new QgsScopedExpressionFunction using named parameters.
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2017-05-16 08:39:03 +02:00
|
|
|
.. versionadded:: 3.0
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
virtual QVariant func( const QVariantList &values, const QgsExpressionContext *context, QgsExpression *parent ) = 0;
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
virtual QgsScopedExpressionFunction *clone() const = 0 /Factory/;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Returns a clone of the function.
|
|
|
|
:rtype: QgsScopedExpressionFunction
|
|
|
|
%End
|
|
|
|
|
2017-05-14 11:20:29 +02:00
|
|
|
virtual bool usesGeometry( const QgsExpressionNodeFunction *node ) const;
|
2017-05-16 08:39:03 +02:00
|
|
|
|
2017-05-14 11:20:29 +02:00
|
|
|
virtual QSet<QString> referencedColumns( const QgsExpressionNodeFunction *node ) const;
|
2017-05-16 08:39:03 +02:00
|
|
|
|
2017-05-14 11:20:29 +02:00
|
|
|
virtual bool isStatic( const QgsExpressionNodeFunction *node, QgsExpression *parent, const QgsExpressionContext *context ) const;
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
|
|
|
};
|
|
|
|
|
2016-02-14 03:50:23 +01:00
|
|
|
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
|
|
|
class QgsExpressionContextScope
|
|
|
|
{
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Single scope for storing variables and functions for use within a QgsExpressionContext.
|
|
|
|
Examples include a project's scope, which could contain information about the current project such as
|
|
|
|
the project file's location. QgsExpressionContextScope can encapsulate both variables (static values)
|
|
|
|
and functions(which are calculated only when an expression is evaluated).
|
|
|
|
|
|
|
|
See QgsExpressionContextUtils for helper methods for working with QgsExpressionContextScope objects.
|
|
|
|
|
|
|
|
.. versionadded:: 2.12
|
|
|
|
%End
|
|
|
|
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
%TypeHeaderCode
|
2017-05-16 08:39:03 +02:00
|
|
|
#include "qgsexpressioncontext.h"
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
%End
|
|
|
|
public:
|
|
|
|
|
|
|
|
struct StaticVariable
|
|
|
|
{
|
2017-05-16 08:39:03 +02:00
|
|
|
|
|
|
|
StaticVariable( const QString &name = QString(), const QVariant &value = QVariant(), bool readOnly = false, bool isStatic = false );
|
|
|
|
%Docstring
|
|
|
|
Constructor for StaticVariable.
|
|
|
|
\param name variable name (should be unique within the QgsExpressionContextScope)
|
|
|
|
\param value initial variable value
|
|
|
|
\param readOnly true if variable should not be editable by users
|
|
|
|
\param isStatic true if the variable will not change during the lifteime of an iterator.
|
|
|
|
%End
|
|
|
|
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
QString name;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Variable name
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
|
|
|
QVariant value;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Variable value
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
|
|
|
bool readOnly;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
True if variable should not be editable by users
|
|
|
|
%End
|
2017-05-02 00:40:24 +02:00
|
|
|
|
|
|
|
bool isStatic;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
A static variable can be cached for the lifetime of a context
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
};
|
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
QgsExpressionContextScope( const QString &name = QString() );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Constructor for QgsExpressionContextScope
|
|
|
|
\param name friendly display name for the context scope
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
QgsExpressionContextScope( const QgsExpressionContextScope &other );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Copy constructor
|
|
|
|
%End
|
|
|
|
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
|
|
|
~QgsExpressionContextScope();
|
|
|
|
|
|
|
|
QString name() const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Returns the friendly display name of the context scope.
|
|
|
|
:rtype: str
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2017-05-02 00:40:24 +02:00
|
|
|
void setVariable( const QString &name, const QVariant &value, bool isStatic = false );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Convenience method for setting a variable in the context scope by ``name`` name and ``value``. If a variable
|
|
|
|
with the same name is already set then its value is overwritten, otherwise a new variable is added to the scope.
|
|
|
|
If the ``isStatic`` parameter is set to true, this variable can be cached during the execution
|
|
|
|
of QgsExpression.prepare().
|
|
|
|
.. seealso:: addVariable()
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
void addVariable( const QgsExpressionContextScope::StaticVariable &variable );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Adds a variable into the context scope. If a variable with the same name is already set then its
|
|
|
|
value is overwritten, otherwise a new variable is added to the scope.
|
|
|
|
\param variable definition of variable to insert
|
|
|
|
.. seealso:: setVariable()
|
|
|
|
.. seealso:: addFunction()
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
bool removeVariable( const QString &name );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Removes a variable from the context scope, if found.
|
|
|
|
\param name name of variable to remove
|
|
|
|
:return: true if variable was removed from the scope, false if matching variable was not
|
|
|
|
found within the scope
|
|
|
|
:rtype: bool
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
bool hasVariable( const QString &name ) const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Tests whether a variable with the specified name exists in the scope.
|
|
|
|
\param name variable name
|
|
|
|
:return: true if matching variable was found in the scope
|
|
|
|
.. seealso:: variable()
|
|
|
|
.. seealso:: hasFunction()
|
|
|
|
:rtype: bool
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
QVariant variable( const QString &name ) const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Retrieves a variable's value from the scope.
|
|
|
|
\param name variable name
|
|
|
|
:return: variable value, or invalid QVariant if matching variable could not be found
|
|
|
|
.. seealso:: hasVariable()
|
|
|
|
.. seealso:: function()
|
|
|
|
:rtype: QVariant
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
|
|
|
QStringList variableNames() const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Returns a list of variable names contained within the scope.
|
|
|
|
.. seealso:: functionNames()
|
|
|
|
.. seealso:: filteredVariableNames()
|
|
|
|
:rtype: list of str
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2015-09-11 17:11:48 +10:00
|
|
|
QStringList filteredVariableNames() const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Returns a filtered and sorted list of variable names contained within the scope.
|
|
|
|
Hidden variable names will be excluded, and the list will be sorted so that
|
|
|
|
read only variables are listed first.
|
|
|
|
.. seealso:: variableNames()
|
|
|
|
:rtype: list of str
|
|
|
|
%End
|
2015-09-11 17:11:48 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
bool isReadOnly( const QString &name ) const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Tests whether the specified variable is read only and should not be editable
|
|
|
|
by users.
|
|
|
|
\param name variable name
|
|
|
|
:return: true if variable is read only
|
|
|
|
:rtype: bool
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2017-05-02 00:40:24 +02:00
|
|
|
bool isStatic( const QString &name ) const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Tests whether the variable with the specified ``name`` is static and can
|
|
|
|
be cached.
|
|
|
|
|
|
|
|
.. versionadded:: 3.0
|
|
|
|
:rtype: bool
|
|
|
|
%End
|
2017-05-02 00:40:24 +02:00
|
|
|
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
int variableCount() const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Returns the count of variables contained within the scope.
|
|
|
|
:rtype: int
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
|
|
|
bool hasFunction( const QString &name ) const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Tests whether a function with the specified name exists in the scope.
|
|
|
|
\param name function name
|
|
|
|
:return: true if matching function was found in the scope
|
|
|
|
.. seealso:: function()
|
|
|
|
.. seealso:: hasFunction()
|
|
|
|
:rtype: bool
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2017-05-14 11:20:29 +02:00
|
|
|
QgsExpressionFunction *function( const QString &name ) const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Retrieves a function from the scope.
|
|
|
|
\param name function name
|
|
|
|
:return: function, or null if matching function could not be found
|
|
|
|
.. seealso:: hasFunction()
|
|
|
|
.. seealso:: functionNames()
|
|
|
|
.. seealso:: variable()
|
2017-05-14 11:20:29 +02:00
|
|
|
:rtype: QgsExpressionFunction
|
2017-05-16 08:39:03 +02:00
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2015-08-19 16:14:32 +10:00
|
|
|
QStringList functionNames() const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Retrieves a list of names of functions contained in the scope.
|
|
|
|
.. seealso:: function()
|
|
|
|
.. seealso:: variableNames()
|
|
|
|
:rtype: list of str
|
|
|
|
%End
|
2015-08-19 16:14:32 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
void addFunction( const QString &name, QgsScopedExpressionFunction *function /Transfer/ );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Adds a function to the scope.
|
|
|
|
\param name function name
|
|
|
|
\param function function to insert. Ownership is transferred to the scope.
|
|
|
|
.. seealso:: addVariable()
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2017-02-15 10:24:29 +10:00
|
|
|
bool hasFeature() const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Returns true if the scope has a feature associated with it.
|
|
|
|
.. versionadded:: 3.0
|
|
|
|
.. seealso:: feature()
|
|
|
|
:rtype: bool
|
|
|
|
%End
|
2017-02-15 10:24:29 +10:00
|
|
|
|
|
|
|
QgsFeature feature() const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Sets the feature associated with the scope.
|
|
|
|
.. seealso:: setFeature()
|
|
|
|
.. seealso:: hasFeature()
|
|
|
|
.. versionadded:: 3.0
|
|
|
|
:rtype: QgsFeature
|
|
|
|
%End
|
2017-02-15 10:24:29 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
void setFeature( const QgsFeature &feature );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Convenience function for setting a feature for the scope. Any existing
|
|
|
|
feature set by the scope will be overwritten.
|
|
|
|
\param feature feature for scope
|
|
|
|
.. seealso:: removeFeature()
|
|
|
|
.. seealso:: feature()
|
|
|
|
%End
|
2015-08-19 16:14:32 +10:00
|
|
|
|
2017-02-22 13:58:11 +10:00
|
|
|
void removeFeature();
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Removes any feature associated with the scope.
|
|
|
|
.. versionadded:: 3.0
|
|
|
|
.. seealso:: setFeature()
|
|
|
|
.. seealso:: hasFeature()
|
|
|
|
%End
|
2017-02-22 13:58:11 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
void setFields( const QgsFields &fields );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Convenience function for setting a fields for the scope. Any existing
|
|
|
|
fields set by the scope will be overwritten.
|
|
|
|
\param fields fields for scope
|
|
|
|
%End
|
2016-04-18 15:27:17 +10:00
|
|
|
|
2017-05-16 08:39:03 +02:00
|
|
|
};
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
|
|
|
class QgsExpressionContext
|
|
|
|
{
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Expression contexts are used to encapsulate the parameters around which a QgsExpression should
|
|
|
|
be evaluated. QgsExpressions can then utilize the information stored within a context to contextualise
|
|
|
|
their evaluated result. A QgsExpressionContext consists of a stack of QgsExpressionContextScope objects,
|
|
|
|
where scopes added later to the stack will override conflicting variables and functions from scopes
|
|
|
|
lower in the stack.
|
|
|
|
|
|
|
|
See QgsExpressionContextUtils for helper methods for working with QgsExpressionContext objects.
|
|
|
|
|
|
|
|
.. versionadded:: 2.12
|
|
|
|
%End
|
|
|
|
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
%TypeHeaderCode
|
2017-05-16 08:39:03 +02:00
|
|
|
#include "qgsexpressioncontext.h"
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
%End
|
|
|
|
public:
|
|
|
|
|
2016-02-14 03:50:23 +01:00
|
|
|
QgsExpressionContext();
|
2015-08-21 06:59:57 +10:00
|
|
|
|
2017-05-16 08:39:03 +02:00
|
|
|
explicit QgsExpressionContext( const QList<QgsExpressionContextScope *> &scopes /Transfer/ );
|
|
|
|
%Docstring
|
|
|
|
Initializes the context with given list of scopes.
|
|
|
|
Ownership of the scopes is transferred to the stack.
|
|
|
|
.. versionadded:: 3.0
|
|
|
|
%End
|
2017-01-05 14:37:31 +08:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
QgsExpressionContext( const QgsExpressionContext &other );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Copy constructor
|
|
|
|
%End
|
|
|
|
|
|
|
|
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
|
|
|
~QgsExpressionContext();
|
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
bool hasVariable( const QString &name ) const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Check whether a variable is specified by any scope within the context.
|
|
|
|
\param name variable name
|
|
|
|
:return: true if variable is set
|
|
|
|
.. seealso:: variable()
|
|
|
|
.. seealso:: variableNames()
|
|
|
|
:rtype: bool
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
QVariant variable( const QString &name ) const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Fetches a matching variable from the context. The variable will be fetched
|
|
|
|
from the last scope contained within the context which has a matching
|
|
|
|
variable set.
|
|
|
|
\param name variable name
|
|
|
|
:return: variable value if matching variable exists in the context, otherwise an invalid QVariant
|
|
|
|
.. seealso:: hasVariable()
|
|
|
|
.. seealso:: variableNames()
|
|
|
|
:rtype: QVariant
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2017-01-09 13:38:47 +10:00
|
|
|
QVariantMap variablesToMap() const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Returns a map of variable name to value representing all the expression variables
|
|
|
|
contained by the context.
|
|
|
|
.. versionadded:: 3.0
|
|
|
|
:rtype: QVariantMap
|
|
|
|
%End
|
2017-01-09 13:38:47 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
bool isHighlightedVariable( const QString &name ) const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Returns true if the specified variable name is intended to be highlighted to the
|
|
|
|
user. This is used by the expression builder to more prominently display the
|
|
|
|
variable.
|
|
|
|
\param name variable name
|
|
|
|
.. seealso:: setHighlightedVariables()
|
|
|
|
:rtype: bool
|
|
|
|
%End
|
2015-08-20 16:06:34 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
void setHighlightedVariables( const QStringList &variableNames );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Sets the list of variable names within the context intended to be highlighted to the user. This
|
|
|
|
is used by the expression builder to more prominently display these variables.
|
|
|
|
\param variableNames variable names to highlight
|
|
|
|
.. seealso:: isHighlightedVariable()
|
|
|
|
%End
|
2015-08-20 16:06:34 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
QgsExpressionContextScope *activeScopeForVariable( const QString &name );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Returns the currently active scope from the context for a specified variable name.
|
|
|
|
As scopes later in the stack override earlier contexts, this will be the last matching
|
|
|
|
scope which contains a matching variable.
|
|
|
|
\param name variable name
|
|
|
|
:return: matching scope containing variable, or null if none found
|
|
|
|
:rtype: QgsExpressionContextScope
|
|
|
|
%End
|
|
|
|
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
QgsExpressionContextScope *scope( int index );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Returns the scope at the specified index within the context.
|
|
|
|
\param index index of scope
|
|
|
|
:return: matching scope, or null if none found
|
|
|
|
.. seealso:: lastScope()
|
|
|
|
:rtype: QgsExpressionContextScope
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
QgsExpressionContextScope *lastScope();
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Returns the last scope added to the context.
|
|
|
|
.. seealso:: scope()
|
|
|
|
:rtype: QgsExpressionContextScope
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2017-05-16 08:39:03 +02:00
|
|
|
QList< QgsExpressionContextScope * > scopes();
|
|
|
|
%Docstring
|
|
|
|
Returns a list of scopes contained within the stack.
|
|
|
|
:return: list of pointers to scopes
|
|
|
|
:rtype: list of QgsExpressionContextScope
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
int indexOfScope( QgsExpressionContextScope *scope ) const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Returns the index of the specified scope if it exists within the context.
|
|
|
|
\param scope scope to find
|
|
|
|
:return: index of scope, or -1 if scope was not found within the context.
|
|
|
|
:rtype: int
|
|
|
|
%End
|
2016-07-20 11:01:00 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
int indexOfScope( const QString &scopeName ) const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Returns the index of the first scope with a matching name within the context.
|
|
|
|
\param scopeName name of scope to find
|
|
|
|
:return: index of scope, or -1 if scope was not found within the context.
|
|
|
|
.. versionadded:: 3.0
|
|
|
|
:rtype: int
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
|
|
|
QStringList variableNames() const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Returns a list of variables names set by all scopes in the context.
|
|
|
|
:return: list of unique variable names
|
|
|
|
.. seealso:: filteredVariableNames
|
|
|
|
.. seealso:: functionNames
|
|
|
|
.. seealso:: hasVariable
|
|
|
|
.. seealso:: variable
|
|
|
|
:rtype: list of str
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2015-08-19 16:14:32 +10:00
|
|
|
QStringList filteredVariableNames() const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Returns a filtered list of variables names set by all scopes in the context. The included
|
|
|
|
variables are those which should be seen by users.
|
|
|
|
:return: filtered list of unique variable names
|
|
|
|
.. seealso:: variableNames
|
|
|
|
:rtype: list of str
|
|
|
|
%End
|
2015-08-19 16:14:32 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
bool isReadOnly( const QString &name ) const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Returns whether a variable is read only, and should not be modifiable by users.
|
|
|
|
\param name variable name
|
|
|
|
:return: true if variable is read only. Read only status will be taken from last
|
|
|
|
matching scope which contains a matching variable.
|
|
|
|
:rtype: bool
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
bool hasFunction( const QString &name ) const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Checks whether a specified function is contained in the context.
|
|
|
|
\param name function name
|
|
|
|
:return: true if context provides a matching function
|
|
|
|
.. seealso:: function
|
|
|
|
:rtype: bool
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2015-08-19 16:14:32 +10:00
|
|
|
QStringList functionNames() const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Retrieves a list of function names contained in the context.
|
|
|
|
.. seealso:: function()
|
|
|
|
.. seealso:: variableNames()
|
|
|
|
:rtype: list of str
|
|
|
|
%End
|
2015-08-19 16:14:32 +10:00
|
|
|
|
2017-05-14 11:20:29 +02:00
|
|
|
QgsExpressionFunction *function( const QString &name ) const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Fetches a matching function from the context. The function will be fetched
|
|
|
|
from the last scope contained within the context which has a matching
|
|
|
|
function set.
|
|
|
|
\param name function name
|
|
|
|
:return: function if contained by the context, otherwise null.
|
|
|
|
.. seealso:: hasFunction
|
2017-05-14 11:20:29 +02:00
|
|
|
:rtype: QgsExpressionFunction
|
2017-05-16 08:39:03 +02:00
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
|
|
|
int scopeCount() const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Returns the number of scopes contained in the context.
|
|
|
|
:rtype: int
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
void appendScope( QgsExpressionContextScope *scope /Transfer/ );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Appends a scope to the end of the context. This scope will override
|
|
|
|
any matching variables or functions provided by existing scopes within the
|
|
|
|
context. Ownership of the scope is transferred to the stack.
|
|
|
|
\param scope expression context to append to context
|
|
|
|
%End
|
|
|
|
|
|
|
|
void appendScopes( const QList<QgsExpressionContextScope *> &scopes /Transfer/ );
|
|
|
|
%Docstring
|
|
|
|
Appends a list of scopes to the end of the context. This scopes will override
|
|
|
|
any matching variables or functions provided by existing scopes within the
|
|
|
|
context. Ownership of the scopes is transferred to the stack.
|
|
|
|
\param scopes scopes to append to context
|
|
|
|
.. versionadded:: 3.0
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
QgsExpressionContextScope *popScope();
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Removes the last scope from the expression context and return it.
|
|
|
|
:rtype: QgsExpressionContextScope
|
|
|
|
%End
|
|
|
|
|
2016-01-08 13:42:53 +01:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
void setFeature( const QgsFeature &feature );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Convenience function for setting a feature for the context. The feature
|
|
|
|
will be set within the last scope of the context, so will override any
|
|
|
|
existing features within the context.
|
|
|
|
\param feature feature for context
|
|
|
|
.. seealso:: feature()
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2017-02-15 10:24:29 +10:00
|
|
|
bool hasFeature() const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Returns true if the context has a feature associated with it.
|
|
|
|
.. versionadded:: 3.0
|
|
|
|
.. seealso:: feature()
|
|
|
|
:rtype: bool
|
|
|
|
%End
|
|
|
|
|
2015-09-05 22:03:16 +10:00
|
|
|
QgsFeature feature() const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Convenience function for retrieving the feature for the context, if set.
|
|
|
|
.. seealso:: setFeature
|
|
|
|
:rtype: QgsFeature
|
|
|
|
%End
|
2015-09-05 22:03:16 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
void setFields( const QgsFields &fields );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Convenience function for setting a fields for the context. The fields
|
|
|
|
will be set within the last scope of the context, so will override any
|
|
|
|
existing fields within the context.
|
|
|
|
\param fields fields for context
|
|
|
|
.. seealso:: fields()
|
|
|
|
%End
|
2015-08-19 16:14:32 +10:00
|
|
|
|
2015-09-05 22:03:16 +10:00
|
|
|
QgsFields fields() const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Convenience function for retrieving the fields for the context, if set.
|
|
|
|
.. seealso:: setFields
|
|
|
|
:rtype: QgsFields
|
|
|
|
%End
|
2015-09-05 22:03:16 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
void setOriginalValueVariable( const QVariant &value );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Sets the original value variable value for the context.
|
|
|
|
\param value value for original value variable. This usually represents the an original widget
|
|
|
|
value before any data defined overrides have been applied.
|
|
|
|
.. versionadded:: 2.12
|
|
|
|
%End
|
2015-10-01 15:41:19 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
void setCachedValue( const QString &key, const QVariant &value ) const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Sets a value to cache within the expression context. This can be used to cache the results
|
|
|
|
of expensive expression sub-calculations, to speed up future evaluations using the same
|
|
|
|
expression context.
|
|
|
|
\param key unique key for retrieving cached value
|
|
|
|
\param value value to cache
|
|
|
|
.. seealso:: hasCachedValue()
|
|
|
|
.. seealso:: cachedValue()
|
|
|
|
.. seealso:: clearCachedValues()
|
|
|
|
.. versionadded:: 2.16
|
|
|
|
%End
|
2016-05-16 15:23:42 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
bool hasCachedValue( const QString &key ) const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Returns true if the expression context contains a cached value with a matching key.
|
|
|
|
\param key unique key used to store cached value
|
|
|
|
.. seealso:: setCachedValue()
|
|
|
|
.. seealso:: cachedValue()
|
|
|
|
.. seealso:: clearCachedValues()
|
|
|
|
.. versionadded:: 2.16
|
|
|
|
:rtype: bool
|
|
|
|
%End
|
2016-05-16 15:23:42 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
QVariant cachedValue( const QString &key ) const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Returns the matching cached value, if set. This can be used to retrieve the previously stored results
|
|
|
|
of an expensive expression sub-calculation.
|
|
|
|
\param key unique key used to store cached value
|
|
|
|
:return: matching cached value, or invalid QVariant if not set
|
|
|
|
.. seealso:: setCachedValue()
|
|
|
|
.. seealso:: hasCachedValue()
|
|
|
|
.. seealso:: clearCachedValues()
|
|
|
|
.. versionadded:: 2.16
|
|
|
|
:rtype: QVariant
|
|
|
|
%End
|
2016-05-16 15:23:42 +10:00
|
|
|
|
|
|
|
void clearCachedValues() const;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Clears all cached values from the context.
|
|
|
|
.. seealso:: setCachedValue()
|
|
|
|
.. seealso:: hasCachedValue()
|
|
|
|
.. seealso:: cachedValue()
|
|
|
|
.. versionadded:: 2.16
|
|
|
|
%End
|
2016-05-16 15:23:42 +10:00
|
|
|
|
2016-01-04 22:51:18 +11:00
|
|
|
static const QString EXPR_FIELDS;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Inbuilt variable name for fields storage
|
|
|
|
%End
|
2016-01-04 22:51:18 +11:00
|
|
|
static const QString EXPR_ORIGINAL_VALUE;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Inbuilt variable name for value original value variable
|
|
|
|
%End
|
2016-01-20 08:21:32 +01:00
|
|
|
static const QString EXPR_SYMBOL_COLOR;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Inbuilt variable name for symbol color variable
|
|
|
|
%End
|
2016-01-20 08:21:32 +01:00
|
|
|
static const QString EXPR_SYMBOL_ANGLE;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Inbuilt variable name for symbol angle variable
|
|
|
|
%End
|
2016-01-27 13:58:32 +11:00
|
|
|
static const QString EXPR_GEOMETRY_PART_COUNT;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Inbuilt variable name for geometry part count variable
|
|
|
|
%End
|
2016-01-27 13:58:32 +11:00
|
|
|
static const QString EXPR_GEOMETRY_PART_NUM;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Inbuilt variable name for geometry part number variable
|
|
|
|
%End
|
|
|
|
static const QString EXPR_GEOMETRY_POINT_COUNT;
|
|
|
|
%Docstring
|
|
|
|
Inbuilt variable name for point count variable
|
|
|
|
%End
|
|
|
|
static const QString EXPR_GEOMETRY_POINT_NUM;
|
|
|
|
%Docstring
|
|
|
|
Inbuilt variable name for point number variable
|
|
|
|
%End
|
2016-09-12 13:51:14 +10:00
|
|
|
static const QString EXPR_CLUSTER_SIZE;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Inbuilt variable name for cluster size variable
|
|
|
|
%End
|
2016-09-12 13:51:14 +10:00
|
|
|
static const QString EXPR_CLUSTER_COLOR;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Inbuilt variable name for cluster color variable
|
|
|
|
%End
|
|
|
|
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
};
|
|
|
|
|
|
|
|
|
|
|
|
class QgsExpressionContextUtils
|
|
|
|
{
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Contains utilities for working with QgsExpressionContext objects, including methods
|
|
|
|
for creating scopes for specific uses (e.g., project scopes, layer scopes).
|
|
|
|
.. versionadded:: 2.12
|
|
|
|
%End
|
|
|
|
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
%TypeHeaderCode
|
2017-05-16 08:39:03 +02:00
|
|
|
#include "qgsexpressioncontext.h"
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
%End
|
|
|
|
public:
|
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
static QgsExpressionContextScope *globalScope() /Factory/;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Creates a new scope which contains variables and functions relating to the global QGIS context.
|
|
|
|
For instance, QGIS version numbers and variables specified through QGIS options.
|
|
|
|
.. seealso:: setGlobalVariable()
|
|
|
|
:rtype: QgsExpressionContextScope
|
|
|
|
%End
|
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
static void setGlobalVariable( const QString &name, const QVariant &value );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Sets a global context variable. This variable will be contained within scopes retrieved via
|
|
|
|
globalScope().
|
|
|
|
\param name variable name
|
|
|
|
\param value variable value
|
|
|
|
.. seealso:: setGlobalVariable()
|
|
|
|
.. seealso:: globalScope()
|
|
|
|
%End
|
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
static void setGlobalVariables( const QVariantMap &variables );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Sets all global context variables. Existing global variables will be removed and replaced
|
|
|
|
with the variables specified.
|
|
|
|
\param variables new set of global variables
|
|
|
|
.. seealso:: setGlobalVariable()
|
|
|
|
.. seealso:: globalScope()
|
|
|
|
%End
|
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
static QgsExpressionContextScope *projectScope( const QgsProject *project ) /Factory/;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Creates a new scope which contains variables and functions relating to a QGIS project.
|
|
|
|
For instance, project path and title, and variables specified through the project properties.
|
|
|
|
\param project What project to use
|
|
|
|
.. seealso:: setProjectVariable()
|
|
|
|
:rtype: QgsExpressionContextScope
|
|
|
|
%End
|
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
static void setProjectVariable( QgsProject *project, const QString &name, const QVariant &value );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Sets a project context variable. This variable will be contained within scopes retrieved via
|
|
|
|
projectScope().
|
|
|
|
\param project Project to apply changes to
|
|
|
|
\param name variable name
|
|
|
|
\param value variable value
|
|
|
|
.. seealso:: setProjectVariables()
|
|
|
|
.. seealso:: projectScope()
|
|
|
|
%End
|
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
static void setProjectVariables( QgsProject *project, const QVariantMap &variables );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Sets all project context variables. Existing project variables will be removed and replaced
|
|
|
|
with the variables specified.
|
|
|
|
\param project Project to apply changes to
|
|
|
|
\param variables new set of project variables
|
|
|
|
.. seealso:: setProjectVariable()
|
|
|
|
.. seealso:: projectScope()
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
static QgsExpressionContextScope *layerScope( const QgsMapLayer *layer ) /Factory/;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Creates a new scope which contains variables and functions relating to a QgsMapLayer.
|
|
|
|
For instance, layer name, id and fields.
|
|
|
|
:rtype: QgsExpressionContextScope
|
|
|
|
%End
|
|
|
|
|
|
|
|
static QList<QgsExpressionContextScope *> globalProjectLayerScopes( const QgsMapLayer *layer ) /Factory/;
|
|
|
|
%Docstring
|
|
|
|
Creates a list of three scopes: global, layer's project and layer.
|
|
|
|
.. versionadded:: 3.0
|
|
|
|
:rtype: list of QgsExpressionContextScope
|
|
|
|
%End
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
static void setLayerVariable( QgsMapLayer *layer, const QString &name, const QVariant &value );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Sets a layer context variable. This variable will be contained within scopes retrieved via
|
|
|
|
layerScope().
|
|
|
|
\param layer map layer
|
|
|
|
\param name variable name
|
|
|
|
\param value variable value
|
|
|
|
.. seealso:: setLayerVariables()
|
|
|
|
.. seealso:: layerScope()
|
|
|
|
%End
|
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
static void setLayerVariables( QgsMapLayer *layer, const QVariantMap &variables );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Sets all layer context variables. Existing layer variables will be removed and replaced
|
|
|
|
with the variables specified.
|
|
|
|
\param layer map layer
|
|
|
|
\param variables new set of layer variables
|
|
|
|
.. seealso:: setLayerVariable()
|
|
|
|
.. seealso:: layerScope()
|
|
|
|
%End
|
2015-08-10 07:42:34 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
static QgsExpressionContextScope *mapSettingsScope( const QgsMapSettings &mapSettings ) /Factory/;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Creates a new scope which contains variables and functions relating to a QgsMapSettings object.
|
|
|
|
For instance, map scale and rotation.
|
|
|
|
:rtype: QgsExpressionContextScope
|
|
|
|
%End
|
2015-09-07 19:18:44 +10:00
|
|
|
|
2017-05-02 07:21:20 +02:00
|
|
|
static QgsExpressionContextScope *updateSymbolScope( const QgsSymbol *symbol, QgsExpressionContextScope *symbolScope = 0 );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Updates a symbol scope related to a QgsSymbol to an expression context.
|
|
|
|
\param symbol symbol to extract properties from
|
|
|
|
\param symbolScope pointer to an existing scope to update
|
|
|
|
.. versionadded:: 2.14
|
|
|
|
:rtype: QgsExpressionContextScope
|
|
|
|
%End
|
2016-01-20 08:21:32 +01:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
static QgsExpressionContextScope *compositionScope( const QgsComposition *composition ) /Factory/;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Creates a new scope which contains variables and functions relating to a QgsComposition.
|
|
|
|
For instance, number of pages and page sizes.
|
|
|
|
\param composition source composition
|
|
|
|
:rtype: QgsExpressionContextScope
|
|
|
|
%End
|
2015-08-13 09:42:51 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
static void setCompositionVariable( QgsComposition *composition, const QString &name, const QVariant &value );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Sets a composition context variable. This variable will be contained within scopes retrieved via
|
|
|
|
compositionScope().
|
|
|
|
\param composition target composition
|
|
|
|
\param name variable name
|
|
|
|
\param value variable value
|
|
|
|
.. seealso:: setCompositionVariables()
|
|
|
|
.. seealso:: compositionScope()
|
|
|
|
%End
|
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
static void setCompositionVariables( QgsComposition *composition, const QVariantMap &variables );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Sets all composition context variables. Existing composition variables will be removed and replaced
|
|
|
|
with the variables specified.
|
|
|
|
\param composition target composition
|
|
|
|
\param variables new set of layer variables
|
|
|
|
.. seealso:: setCompositionVariable()
|
|
|
|
.. seealso:: compositionScope()
|
|
|
|
%End
|
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
static QgsExpressionContextScope *atlasScope( const QgsAtlasComposition *atlas ) /Factory/;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Creates a new scope which contains variables and functions relating to a QgsAtlasComposition.
|
|
|
|
For instance, current page name and number.
|
|
|
|
\param atlas source atlas. If null, a set of default atlas variables will be added to the scope.
|
|
|
|
:rtype: QgsExpressionContextScope
|
|
|
|
%End
|
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
static QgsExpressionContextScope *composerItemScope( const QgsComposerItem *composerItem ) /Factory/;
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Creates a new scope which contains variables and functions relating to a QgsComposerItem.
|
|
|
|
For instance, item size and position.
|
|
|
|
\param composerItem source composer item
|
|
|
|
:rtype: QgsExpressionContextScope
|
|
|
|
%End
|
2015-08-13 09:42:51 +10:00
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
static void setComposerItemVariable( QgsComposerItem *composerItem, const QString &name, const QVariant &value );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Sets a composer item context variable. This variable will be contained within scopes retrieved via
|
|
|
|
composerItemScope().
|
|
|
|
\param composerItem target composer item
|
|
|
|
\param name variable name
|
|
|
|
\param value variable value
|
|
|
|
.. seealso:: setComposerItemVariables()
|
|
|
|
.. seealso:: composerItemScope()
|
|
|
|
%End
|
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
static void setComposerItemVariables( QgsComposerItem *composerItem, const QVariantMap &variables );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Sets all composition context variables. Existing compositoin variables will be removed and replaced
|
|
|
|
with the variables specified.
|
|
|
|
\param composerItem target composer item
|
|
|
|
\param variables new set of layer variables
|
|
|
|
.. seealso:: setComposerItemVariable()
|
|
|
|
.. seealso:: composerItemScope()
|
|
|
|
%End
|
|
|
|
|
2017-05-01 16:42:33 +02:00
|
|
|
static QgsExpressionContext createFeatureBasedContext( const QgsFeature &feature, const QgsFields &fields );
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Helper function for creating an expression context which contains just a feature and fields
|
|
|
|
collection. Generally this method should not be used as the created context does not include
|
|
|
|
standard scopes such as the global and project scopes.
|
|
|
|
:rtype: QgsExpressionContext
|
|
|
|
%End
|
2016-02-14 03:50:23 +01:00
|
|
|
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
static void registerContextFunctions();
|
2017-05-16 08:39:03 +02:00
|
|
|
%Docstring
|
|
|
|
Registers all known core functions provided by QgsExpressionContextScope objects.
|
|
|
|
%End
|
2016-02-14 03:50:23 +01:00
|
|
|
|
New framework for context based expressions
This commit adds the ability for expressions to be evaluated against
specific contexts. It replaces the previous behaviour where
expressions were evaluated against a specific feature and could
utilise fragile global "special columns".
Now, expressions are instead evaluated using a context designed for
each individual expression. This is done via QgsExpressionContext
and QgsExpressionContextScope objects.
A QgsExpressionContextScope encapsulates the variables and functions
relating to a specific context. For instance, scopes can be created
for "global" variables (such as QGIS version, platform, and user-set
variables specified within the QGIS options dialog. Think things
like user name, work department, etc), or for "project" variables
(eg project path, title, filename, and user-set variables set
through the project properties dialog. Project version, reference
number, that kind of thing). Many more scopes are planned, including
map layer scopes (variables for layer name, id, user-set variables
through the layer properties dialog), composer scopes, etc...
QgsExpressionContextScopes are 'stacked' into a QgsExpressionContext
object. Scopes added later to a QgsExpressionContext will override
any variables or functions provided by earlier scopes, so for
instance a user could override their global 'author' variable set
within QGIS options with a different 'author' set via the project
properties dialog.
The intended use is that a QgsExpressionContext is created before
a batch set of QgsExpression evaluations. Scopes are then added to
the context based on what makes sense for that particular
expression. Eg, almost all contexts will consist of the global
scope and project scope, and then additional scopes as required.
So a composer label would be evaluated against a context
consisting of the global scope, project scope, composition scope
and finally composer item scope. The batch set of expression
evaluations would then be performed using this context, after which
the context is discarded. In other words, a context is designed
for use for one specific set of expression evaluations only.
2015-08-07 15:29:51 +10:00
|
|
|
};
|
|
|
|
|
2017-05-16 08:39:03 +02:00
|
|
|
/************************************************************************
|
|
|
|
* This file has been generated automatically from *
|
|
|
|
* *
|
|
|
|
* src/core/qgsexpressioncontext.h *
|
|
|
|
* *
|
|
|
|
* Do not edit manually ! Edit header and run scripts/sipify.pl again *
|
|
|
|
************************************************************************/
|