A store for object properties. More...

#include <qgsproperty.h>

Public Types
enum	Type { InvalidProperty , StaticProperty , FieldBasedProperty , ExpressionBasedProperty }
	Property types. More...

Public Member Functions
	QgsProperty ()
	Constructor for a QgsProperty. More...

	QgsProperty (const QgsProperty &other)
	Copy constructor. More...

	~QgsProperty ()

QString	asExpression () const
	Returns an expression string representing the state of the property, or an empty string if the property could not be converted to an expression. More...

bool	convertToTransformer ()
	Attempts to convert an existing expression based property to a base expression with corresponding transformer. More...

QString	expressionString () const
	Returns the expression used for the property value. More...

QString	field () const
	Returns the current field name the property references. More...

bool	isActive () const
	Returns whether the property is currently active. More...

bool	isProjectColor () const
	Returns `true` if the property is set to a linked project color. More...

bool	isStaticValueInContext (const QgsExpressionContext &context, QVariant &staticValue) const
	Returns `true` if the property is effectively a static value in the specified context. More...

bool	loadVariant (const QVariant &property)
	Loads this property from a QVariantMap, wrapped in a QVariant. More...

	operator bool () const
	Returns `true` if the property is not an invalid type. More...

	operator QVariant () const
	Allows direct construction of QVariants from properties. More...

bool	operator!= (const QgsProperty &other) const

QgsProperty &	operator= (const QgsProperty &other)

bool	operator== (const QgsProperty &other) const

bool	prepare (const QgsExpressionContext &context=QgsExpressionContext()) const
	Prepares the property against a specified expression context. More...

Type	propertyType () const
	Returns the property type. More...

QSet< QString >	referencedFields (const QgsExpressionContext &context=QgsExpressionContext(), bool ignoreContext=false) const
	Returns the set of any fields referenced by the property for a specified expression context. More...

void	setActive (bool active)
	Sets whether the property is currently active. More...

void	setExpressionString (const QString &expression)
	Sets the expression to use for the property value. More...

void	setField (const QString &field)
	Sets the field name the property references. More...

void	setStaticValue (const QVariant &value)
	Sets the static value for the property. More...

void	setTransformer (QgsPropertyTransformer *transformer)
	Sets an optional transformer to use for manipulating the calculated values for the property. More...

QVariant	staticValue () const
	Returns the current static value for the property. More...

QVariant	toVariant () const
	Saves this property to a QVariantMap, wrapped in a QVariant. More...

const QgsPropertyTransformer *	transformer () const
	Returns the existing transformer used for manipulating the calculated values for the property, if set. More...

QVariant	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. More...

bool	valueAsBool (const QgsExpressionContext &context, bool defaultValue=false, bool *ok=nullptr) const
	Calculates the current value of the property and interprets it as an boolean. More...

QColor	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. More...

QDateTime	valueAsDateTime (const QgsExpressionContext &context, const QDateTime &defaultDateTime=QDateTime(), bool *ok=nullptr) const
	Calculates the current value of the property and interprets it as a datetime. More...

double	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. More...

int	valueAsInt (const QgsExpressionContext &context, int defaultValue=0, bool *ok=nullptr) const
	Calculates the current value of the property and interprets it as an integer. More...

QString	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. More...

Static Public Member Functions
static QgsProperty	fromExpression (const QString &expression, bool isActive=true)
	Returns a new ExpressionBasedProperty created from the specified expression. More...

static QgsProperty	fromField (const QString &fieldName, bool isActive=true)
	Returns a new FieldBasedProperty created from the specified field name. More...

static QgsProperty	fromValue (const QVariant &value, bool isActive=true)
	Returns a new StaticProperty created from the specified value. More...

static QVariantMap	propertyMapToVariantMap (const QMap< QString, QgsProperty > &propertyMap)
	Convert a map of QgsProperty to a map of QVariant This is useful to save a map of properties. More...

static QMap< QString, QgsProperty >	variantMapToPropertyMap (const QVariantMap &variantMap)
	Convert a map of QVariant to a map of QgsProperty This is useful to restore a map of properties. More...

Detailed Description

A store for object properties.

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.

Since: QGIS 3.0

Definition at line 230 of file qgsproperty.h.

Member Enumeration Documentation

◆ Type

enum QgsProperty::Type

Property types.

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

Definition at line 235 of file qgsproperty.h.

Constructor & Destructor Documentation

◆ QgsProperty() [1/2]

QgsProperty::QgsProperty ( )

Constructor for a QgsProperty.

The property will be set to an InvalidProperty type.

Definition at line 230 of file qgsproperty.cpp.

◆ ~QgsProperty()

QgsProperty::~QgsProperty ( )

default

◆ QgsProperty() [2/2]

QgsProperty::QgsProperty ( const QgsProperty & other )

Copy constructor.

Definition at line 261 of file qgsproperty.cpp.

Member Function Documentation

◆ asExpression()

QString QgsProperty::asExpression ( ) const

Returns an expression string representing the state of the property, or an empty string if the property could not be converted to an expression.

Definition at line 398 of file qgsproperty.cpp.

◆ convertToTransformer()

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.

Definition at line 876 of file qgsproperty.cpp.

◆ expressionString()

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.

See also: setExpressionString()

Definition at line 389 of file qgsproperty.cpp.

◆ field()

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.

See also: setField()

Definition at line 357 of file qgsproperty.cpp.

◆ fromExpression()

QgsProperty QgsProperty::fromExpression	(	const QString &	expression,
		bool	isActive = `true`
	)

static

Returns a new ExpressionBasedProperty created from the specified expression.

Definition at line 237 of file qgsproperty.cpp.

◆ fromField()

QgsProperty QgsProperty::fromField	(	const QString &	fieldName,
		bool	isActive = `true`
	)

static

Returns a new FieldBasedProperty created from the specified field name.

Definition at line 245 of file qgsproperty.cpp.

◆ fromValue()

QgsProperty QgsProperty::fromValue	(	const QVariant &	value,
		bool	isActive = `true`
	)

static

Returns a new StaticProperty created from the specified value.

Definition at line 253 of file qgsproperty.cpp.

◆ isActive()

bool QgsProperty::isActive ( ) const

Returns whether the property is currently active.

See also: setActive()

Definition at line 291 of file qgsproperty.cpp.

◆ isProjectColor()

bool QgsProperty::isProjectColor ( ) const

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

Since: QGIS 3.6

Definition at line 509 of file qgsproperty.cpp.

◆ isStaticValueInContext()

bool QgsProperty::isStaticValueInContext	(	const QgsExpressionContext &	context,
		QVariant &	staticValue
	)		const

Returns true if the property is effectively a static value in the specified context.

I.e. if the property type is QgsProperty::ExpressionBasedProperty with a fixed value expression ('some static value'), this method will return true.

Parameters

context	expression context
staticValue	will be set to evaluated static value if property is effectively a static value

Returns: true if property is a static value

Since: QGIS 3.24

Definition at line 296 of file qgsproperty.cpp.

◆ loadVariant()

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.

See also: toVariant()

Definition at line 803 of file qgsproperty.cpp.

◆ operator bool()

QgsProperty::operator bool ( ) const

Returns true if the property is not an invalid type.

Definition at line 365 of file qgsproperty.cpp.

◆ operator QVariant()

QgsProperty::operator QVariant ( ) const

inline

Allows direct construction of QVariants from properties.

Definition at line 543 of file qgsproperty.h.

◆ operator!=()

bool QgsProperty::operator!= ( const QgsProperty & other ) const

Definition at line 281 of file qgsproperty.cpp.

◆ operator=()

QgsProperty & QgsProperty::operator= ( const QgsProperty & other )

Definition at line 265 of file qgsproperty.cpp.

◆ operator==()

bool QgsProperty::operator== ( const QgsProperty & other ) const

Definition at line 271 of file qgsproperty.cpp.

◆ prepare()

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.

Definition at line 422 of file qgsproperty.cpp.

◆ propertyMapToVariantMap()

QVariantMap QgsProperty::propertyMapToVariantMap ( const QMap< QString, QgsProperty > & propertyMap )

static

Convert a map of QgsProperty to a map of QVariant This is useful to save a map of properties.

Since: QGIS 3.20

Definition at line 208 of file qgsproperty.cpp.

◆ propertyType()

QgsProperty::Type QgsProperty::propertyType ( ) const

Returns the property type.

Definition at line 286 of file qgsproperty.cpp.

◆ referencedFields()

QSet< QString > QgsProperty::referencedFields	(	const QgsExpressionContext &	context = `QgsExpressionContext()`,
		bool	ignoreContext = `false`
	)		const

Returns the set of any fields referenced by the property for a specified expression context.

Note: The optional argument ignoreContext has been added in QGIS 3.14. When set to true, even fields not set in context's fields() will be reported - this is useful e.g. with vector tiles where the actual available field names may not be known beforehand.

Definition at line 466 of file qgsproperty.cpp.

◆ setActive()

void QgsProperty::setActive ( bool active )

Sets whether the property is currently active.

See also: isActive()

Definition at line 328 of file qgsproperty.cpp.

◆ setExpressionString()

void QgsProperty::setExpressionString ( const QString & expression )

Sets the expression to use for the property value.

Calling this will transform the property into an ExpressionBasedProperty.

See also: expressionString()

Definition at line 370 of file qgsproperty.cpp.

◆ setField()

void QgsProperty::setField ( const QString & field )

Sets the field name the property references.

Calling this will transform the property into an FieldBasedProperty.

See also: field()

Definition at line 349 of file qgsproperty.cpp.

◆ setStaticValue()

void QgsProperty::setStaticValue ( const QVariant & value )

Sets the static value for the property.

Calling this will transform the property into an StaticProperty.

See also: staticValue()

Definition at line 334 of file qgsproperty.cpp.

◆ setTransformer()

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 nullptr to remove an existing transformer.

See also: transformer()

Definition at line 865 of file qgsproperty.cpp.

◆ staticValue()

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.

See also: setStaticValue()

Definition at line 341 of file qgsproperty.cpp.

◆ toVariant()

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.

See also: loadVariant()

Definition at line 765 of file qgsproperty.cpp.

◆ transformer()

const QgsPropertyTransformer * QgsProperty::transformer ( ) const

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

See also: setTransformer()

Definition at line 871 of file qgsproperty.cpp.

◆ value()

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

See also: valueAsString(); valueAsColor(); valueAsDouble(); valueAsInt(); valueAsBool()

Definition at line 585 of file qgsproperty.cpp.

◆ valueAsBool()

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

See also: value(); valueAsDateTime(); valueAsString(); valueAsColor(); valueAsDouble(); valueAsInt()

Definition at line 749 of file qgsproperty.cpp.

◆ valueAsColor()

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

See also: value(); valueAsDateTime(); valueAsString(); valueAsDouble(); valueAsInt(); valueAsBool()

Definition at line 659 of file qgsproperty.cpp.

◆ valueAsDateTime()

QDateTime QgsProperty::valueAsDateTime	(	const QgsExpressionContext &	context,
		const QDateTime &	defaultDateTime = `QDateTime()`,
		bool *	ok = `nullptr`
	)		const

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

Parameters

context	QgsExpressionContext to evaluate the property for.
defaultDateTime	default datetime to return if the property cannot be calculated as a datetime
ok	if specified, will be set to `true` if conversion was successful

Returns: value parsed to datetime

See also: value(); valueAsString(); valueAsColor(); valueAsDouble(); valueAsInt(); valueAsBool()

Since: QGIS 3.14

Definition at line 608 of file qgsproperty.cpp.

◆ valueAsDouble()

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

See also: value(); valueAsDateTime(); valueAsString(); valueAsColor(); valueAsInt(); valueAsBool()

Definition at line 690 of file qgsproperty.cpp.

◆ valueAsInt()

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

See also: value(); valueAsDateTime(); valueAsString(); valueAsColor(); valueAsDouble(); valueAsBool()

Definition at line 713 of file qgsproperty.cpp.

◆ valueAsString()

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

See also: value(); valueAsDateTime(); valueAsColor(); valueAsDouble(); valueAsInt(); valueAsBool()

Definition at line 640 of file qgsproperty.cpp.

◆ variantMapToPropertyMap()

QMap< QString, QgsProperty > QgsProperty::variantMapToPropertyMap ( const QVariantMap & variantMap )

static

Convert a map of QVariant to a map of QgsProperty This is useful to restore a map of properties.

The properties are created using QgsProperty::loadVariant

Since: QGIS 3.20

Definition at line 217 of file qgsproperty.cpp.

The documentation for this class was generated from the following files:

/build/qgis-3.24.2+99sid/src/core/qgsproperty.h
/build/qgis-3.24.2+99sid/src/core/qgsproperty.cpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ Type

Constructor & Destructor Documentation

◆ QgsProperty() [1/2]

◆ ~QgsProperty()

◆ QgsProperty() [2/2]

Member Function Documentation

◆ asExpression()

◆ convertToTransformer()

◆ expressionString()

◆ field()

◆ fromExpression()

◆ fromField()

◆ fromValue()

◆ isActive()

◆ isProjectColor()

◆ isStaticValueInContext()

◆ loadVariant()

◆ operator bool()

◆ operator QVariant()

◆ operator!=()

◆ operator=()

◆ operator==()

◆ prepare()

◆ propertyMapToVariantMap()

◆ propertyType()

◆ referencedFields()

◆ setActive()

◆ setExpressionString()

◆ setField()

◆ setStaticValue()

◆ setTransformer()

◆ staticValue()

◆ toVariant()

◆ transformer()

◆ value()

◆ valueAsBool()

◆ valueAsColor()

◆ valueAsDateTime()

◆ valueAsDouble()

◆ valueAsInt()

◆ valueAsString()

◆ variantMapToPropertyMap()