QgsProperty class

A store for object properties.

Reference

QgsProperty objects are used for storing properties for objects, which can then be transformed to a QVariant value by evaluating them against a supplied QgsExpressionContext. Multiple QgsProperty objects can be grouped using a QgsPropertyCollection for easier bulk storage, retrieval and evaluation.

QgsProperty objects are implicitly shared and can be inexpensively copied.

Public types

enum Type { InvalidProperty, StaticProperty, FieldBasedProperty, ExpressionBasedProperty }: Property types.

Public static functions

static auto fromExpression(const QString& expression, bool isActive = true) -> QgsProperty: Returns a new ExpressionBasedProperty created from the specified expression.
static auto fromField(const QString& fieldName, bool isActive = true) -> QgsProperty: Returns a new FieldBasedProperty created from the specified field name.
static auto fromValue(const QVariant& value, bool isActive = true) -> QgsProperty: Returns a new StaticProperty created from the specified value.

Constructors, destructors, conversion operators

QgsProperty(): Constructor for a QgsAbstractProperty.
QgsProperty(const QgsProperty& other): Copy constructor.
operator bool() const: Returns true if the property is not an invalid type.
operator QVariant() const: Allows direct construction of QVariants from properties.

Public functions

auto asExpression() const -> QString: Returns an expression string representing the state of the property, or an empty string if the property could not be converted to an expression.
auto convertToTransformer() -> bool: Attempts to convert an existing expression based property to a base expression with corresponding transformer.
auto expressionString() const -> QString: Returns the expression used for the property value.
auto field() const -> QString: Returns the current field name the property references.
auto isActive() const -> bool: Returns whether the property is currently active.
auto isProjectColor() const -> bool: Returns true if the property is set to a linked project color.
auto loadVariant(const QVariant& property) -> bool: Loads this property from a QVariantMap, wrapped in a QVariant.
auto prepare(const QgsExpressionContext& context = QgsExpressionContext()) const -> bool: Prepares the property against a specified expression context.
auto propertyType() const -> Type: Returns the property type.
auto referencedFields(const QgsExpressionContext& context = QgsExpressionContext()) const -> QSet<QString>: Returns the set of any fields referenced by the property for a specified expression context.
void setActive(bool active): Sets whether the property is currently active.
void setExpressionString(const QString& expression): Sets the expression to use for the property value.
void setField(const QString& field): Sets the field name the property references.
void setStaticValue(const QVariant& value): Sets the static value for the property.
void setTransformer(QgsPropertyTransformer* transformer): Sets an optional transformer to use for manipulating the calculated values for the property.
auto staticValue() const -> QVariant: Returns the current static value for the property.
auto toVariant() const -> QVariant: Saves this property to a QVariantMap, wrapped in a QVariant.
auto transformer() const -> const QgsPropertyTransformer*: Returns the existing transformer used for manipulating the calculated values for the property, if set.
auto value(const QgsExpressionContext& context, const QVariant& defaultValue = QVariant(), bool* ok = nullptr) const -> QVariant: Calculates the current value of the property, including any transforms which are set for the property.
auto valueAsBool(const QgsExpressionContext& context, bool defaultValue = false, bool* ok = nullptr) const -> bool: Calculates the current value of the property and interprets it as an boolean.
auto valueAsColor(const QgsExpressionContext& context, const QColor& defaultColor = QColor(), bool* ok = nullptr) const -> QColor: Calculates the current value of the property and interprets it as a color.
auto valueAsDouble(const QgsExpressionContext& context, double defaultValue = 0.0, bool* ok = nullptr) const -> double: Calculates the current value of the property and interprets it as a double.
auto valueAsInt(const QgsExpressionContext& context, int defaultValue = 0, bool* ok = nullptr) const -> int: Calculates the current value of the property and interprets it as an integer.
auto valueAsString(const QgsExpressionContext& context, const QString& defaultString = QString(), bool* ok = nullptr) const -> QString: Calculates the current value of the property and interprets it as a string.

Enum documentation

enum QgsProperty::Type

Property types.

Enumerators
InvalidProperty
StaticProperty	Invalid (not set) property. Static property (QgsStaticProperty)
FieldBasedProperty	Field based property (QgsFieldBasedProperty)
ExpressionBasedProperty	Expression based property (QgsExpressionBasedProperty)

Function documentation

QgsProperty::QgsProperty()

Constructor for a QgsAbstractProperty.

The property will be set to an InvalidProperty type.

bool QgsProperty::convertToTransformer()

Attempts to convert an existing expression based property to a base expression with corresponding transformer.

Returns true if conversion was successful. Note that calling this method requires multiple parsing of expressions, so it should only be called in non-performance critical code.

QString QgsProperty::expressionString() const

Returns the expression used for the property value.

If the property is not a ExpressionBasedProperty this will return an empty string.

QString QgsProperty::field() const

Returns the current field name the property references.

If the property is not a FieldBasedProperty this will return an empty string.

bool QgsProperty::isActive() const

Returns whether the property is currently active.

bool QgsProperty::isProjectColor() const

Returns true if the property is set to a linked project color.

bool QgsProperty::loadVariant(const QVariant& property)

Loads this property from a QVariantMap, wrapped in a QVariant.

You can use QgsXmlUtils::readVariant to load it from an XML document.

bool QgsProperty::prepare(const QgsExpressionContext& context = QgsExpressionContext()) const

Prepares the property against a specified expression context.

Calling prepare before evaluating the property multiple times allows precalculation of expensive setup tasks such as parsing expressions. Returns true if preparation was successful.

void QgsProperty::setActive(bool active)

Sets whether the property is currently active.

void QgsProperty::setExpressionString(const QString& expression)

Sets the expression to use for the property value.

Calling this will transform the property into an ExpressionBasedProperty.

void QgsProperty::setField(const QString& field)

Sets the field name the property references.

Calling this will transform the property into an FieldBasedProperty.

void QgsProperty::setStaticValue(const QVariant& value)

Sets the static value for the property.

Calling this will transform the property into an StaticProperty.

void QgsProperty::setTransformer(QgsPropertyTransformer* transformer)

Sets an optional transformer to use for manipulating the calculated values for the property.

Parameters
transformer	transformer to install. Ownership is transferred to the property, and any existing transformer will be deleted. Set to null to remove an existing transformer.

QVariant QgsProperty::staticValue() const

Returns the current static value for the property.

If the property is not a StaticProperty this will return an invalid variant.

QVariant QgsProperty::toVariant() const

Saves this property to a QVariantMap, wrapped in a QVariant.

You can use QgsXmlUtils::writeVariant to save it to an XML document.

const QgsPropertyTransformer* QgsProperty::transformer() const

Returns the existing transformer used for manipulating the calculated values for the property, if set.

QVariant QgsProperty::value(const QgsExpressionContext& context, const QVariant& defaultValue = QVariant(), bool* ok = nullptr) const

Calculates the current value of the property, including any transforms which are set for the property.

Parameters
context	QgsExpressionContext to evaluate the property for. The variables and functions contained in the expression context can be used to alter the calculated value for the property, so that a property is able to respond to the current environment, layers and features within QGIS.
defaultValue	default value to return if the property is not active or cannot be calculated
ok	if specified, will be set to true if conversion was successful
Returns	calculated value for property

bool QgsProperty::valueAsBool(const QgsExpressionContext& context, bool defaultValue = false, bool* ok = nullptr) const

Calculates the current value of the property and interprets it as an boolean.

Parameters
context	QgsExpressionContext to evaluate the property for.
defaultValue	default boolean to return if the property cannot be calculated as an boolean
ok	if specified, will be set to true if conversion was successful
Returns	value parsed to boolean

QColor QgsProperty::valueAsColor(const QgsExpressionContext& context, const QColor& defaultColor = QColor(), bool* ok = nullptr) const

Calculates the current value of the property and interprets it as a color.

Parameters
context	QgsExpressionContext to evaluate the property for.
defaultColor	default color to return if the property cannot be calculated as a color
ok	if specified, will be set to true if conversion was successful
Returns	value parsed to color

double QgsProperty::valueAsDouble(const QgsExpressionContext& context, double defaultValue = 0.0, bool* ok = nullptr) const

Calculates the current value of the property and interprets it as a double.

Parameters
context	QgsExpressionContext to evaluate the property for.
defaultValue	default double to return if the property cannot be calculated as a double
ok	if specified, will be set to true if conversion was successful
Returns	value parsed to double

int QgsProperty::valueAsInt(const QgsExpressionContext& context, int defaultValue = 0, bool* ok = nullptr) const

Calculates the current value of the property and interprets it as an integer.

Parameters
context	QgsExpressionContext to evaluate the property for.
defaultValue	default integer to return if the property cannot be calculated as an integer
ok	if specified, will be set to true if conversion was successful
Returns	value parsed to integer

QString QgsProperty::valueAsString(const QgsExpressionContext& context, const QString& defaultString = QString(), bool* ok = nullptr) const

Calculates the current value of the property and interprets it as a string.

Parameters
context	QgsExpressionContext to evaluate the property for.
defaultString	default string to return if the property cannot be calculated as a string
ok	if specified, will be set to true if conversion was successful
Returns	value parsed to string