QGIS API Documentation  3.22.4-Białowieża (ce8e65e95e)
Public Types | Public Member Functions | Static Public Member Functions | List of all members
QgsProperty Class Reference

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 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
 
QgsPropertyoperator= (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 QgsPropertyTransformertransformer () 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, QgsPropertyvariantMapToPropertyMap (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 231 of file qgsproperty.h.

Member Enumeration Documentation

◆ 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 236 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 229 of file qgsproperty.cpp.

◆ ~QgsProperty()

QgsProperty::~QgsProperty ( )
default

◆ QgsProperty() [2/2]

QgsProperty::QgsProperty ( const QgsProperty other)

Copy constructor.

Definition at line 260 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 356 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 834 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 347 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 324 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 236 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 244 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 252 of file qgsproperty.cpp.

◆ isActive()

bool QgsProperty::isActive ( ) const

Returns whether the property is currently active.

See also
setActive()

Definition at line 290 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 467 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 761 of file qgsproperty.cpp.

◆ operator bool()

QgsProperty::operator bool ( ) const

Returns true if the property is not an invalid type.

Definition at line 332 of file qgsproperty.cpp.

◆ operator QVariant()

QgsProperty::operator QVariant ( ) const
inline

Allows direct construction of QVariants from properties.

Definition at line 528 of file qgsproperty.h.

◆ operator!=()

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

Definition at line 280 of file qgsproperty.cpp.

◆ operator=()

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

Definition at line 264 of file qgsproperty.cpp.

◆ operator==()

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

Definition at line 270 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 380 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 207 of file qgsproperty.cpp.

◆ propertyType()

QgsProperty::Type QgsProperty::propertyType ( ) const

Returns the property type.

Definition at line 285 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 424 of file qgsproperty.cpp.

◆ setActive()

void QgsProperty::setActive ( bool  active)

Sets whether the property is currently active.

See also
isActive()

Definition at line 295 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 337 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 316 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 301 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
transformertransformer 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 823 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 308 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 723 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 829 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
contextQgsExpressionContext 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.
defaultValuedefault value to return if the property is not active or cannot be calculated
okif 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 543 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
contextQgsExpressionContext to evaluate the property for.
defaultValuedefault boolean to return if the property cannot be calculated as an boolean
okif 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 707 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
contextQgsExpressionContext to evaluate the property for.
defaultColordefault color to return if the property cannot be calculated as a color
okif 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 617 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
contextQgsExpressionContext to evaluate the property for.
defaultDateTimedefault datetime to return if the property cannot be calculated as a datetime
okif 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 566 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
contextQgsExpressionContext to evaluate the property for.
defaultValuedefault double to return if the property cannot be calculated as a double
okif 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 648 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
contextQgsExpressionContext to evaluate the property for.
defaultValuedefault integer to return if the property cannot be calculated as an integer
okif 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 671 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
contextQgsExpressionContext to evaluate the property for.
defaultStringdefault string to return if the property cannot be calculated as a string
okif 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 598 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 216 of file qgsproperty.cpp.


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