Solid::Predicate Class
class Solid::PredicateThis class implements predicates for devices. More...
| Header: | #include <Solid/Predicate> |
| CMake: | find_package(KF6 REQUIRED COMPONENTS Solid)target_link_libraries(mytarget PRIVATE KF6::Solid) |
Public Types
| enum | ComparisonOperator { Equals, Mask } |
| enum | NotOperator { NOT } |
| enum | Type { PropertyCheck, Conjunction, Disjunction, InterfaceCheck } |
Public Functions
| Predicate() | |
| Predicate(const QString &ifaceName) | |
| Predicate(const Solid::DeviceInterface::Type &ifaceType) | |
(since 6.17) | Predicate(QStringView ifaceName, Solid::Predicate::NotOperator op) |
| Predicate(const QString &ifaceName, const QString &property, const QVariant &value, Solid::Predicate::ComparisonOperator compOperator = Equals) | |
| Predicate(const Solid::DeviceInterface::Type &ifaceType, const QString &property, const QVariant &value, Solid::Predicate::ComparisonOperator compOperator = Equals) | |
| Solid::Predicate::ComparisonOperator | comparisonOperator() const |
| Solid::Predicate | firstOperand() const |
| Solid::DeviceInterface::Type | interfaceType() const |
(since 6.17) bool | isInterfaceTypeNegated() const |
| bool | isValid() const |
| bool | matches(const Solid::Device &device) const |
| QVariant | matchingValue() const |
| QString | propertyName() const |
| Solid::Predicate | secondOperand() const |
| QString | toString() const |
| Solid::Predicate::Type | type() const |
| QSet<Solid::DeviceInterface::Type> | usedTypes() const |
| Solid::Predicate | operator&(const Solid::Predicate &other) |
| Solid::Predicate & | operator&=(const Solid::Predicate &other) |
| Solid::Predicate | operator|(const Solid::Predicate &other) |
| Solid::Predicate & | operator|=(const Solid::Predicate &other) |
Static Public Members
| Solid::Predicate | fromString(const QString &predicate) |
Detailed Description
A predicate is a logical condition that a given device can match or not. It's a constraint about the value a property must have in a given device interface, or any combination (conjunction, disjunction) of such constraints.
Predicates are used both in code and in Solid action files (present in /usr/share/solid/actions or ~/.local/share/solid/actions). When used in Solid action files, they must be present in the X-KDE-Solid-Predicate= key in the Desktop Entry section of the file.
A predicate can be:
- a single comparison
- a conjunction of exactly two predicates ("AND")
- a disjunction of exactly two predicates ("OR")
Since these can be nested, it is possible to express "a StorageVolume that is not ignored AND that StorageVolume contains a FileSystem AND that StorageVolume is removable". Since conjunctions use exactly two predicates (and this expression has three), square brackets are used to group the nested predicates when writing them out in full:
[ [ StorageVolume.ignored == false AND StorageVolume.usage == 'FileSystem' ]
AND StorageVolume.removable == true ]Predicates can be constructed programmatically by creating single comparisons with the Predicate() constructor, and then building conjunctions with operator& and disjunctions with operator|.
Predicates can be constructed from a string by calling fromString() which returns a predicate. If there are any errors in parsing the string, an empty predicate is returned; use isValid() to detect whether that is the case.
The string language is described exactly in predicate_parser.y, but boils down to:
- a single comparison is written as
<interface>.<property> == <value> - a single bitmask check is written as
<interface>.<property> & <value> - a conjunction is written as
[ <predicate> AND <predicate> ] - a disjunction is written as
[ <predicate> OR <predicate> ]
Note the mandatory use of [ and ] around conjunctions and disjunctions.
See also Solid tutorial.
Member Type Documentation
enum Predicate::ComparisonOperator
The comparison operator which can be used for matching within the predicate.
| Constant | Value | Description |
|---|---|---|
Solid::Predicate::Equals | 0 | The property and the value will match for strict equality |
Solid::Predicate::Mask | 1 | The property and the value will match if the bitmasking is not null |
enum Predicate::NotOperator
Argument for the Predicate() constructor.
| Constant | Value |
|---|---|
Solid::Predicate::NOT | 0 |
enum Predicate::Type
The predicate type which controls how the predicate is handled.
| Constant | Value | Description |
|---|---|---|
Solid::Predicate::PropertyCheck | 0 | The predicate contains a comparison that needs to be matched using a ComparisonOperator |
Solid::Predicate::Conjunction | 1 | The two contained predicates need to be true for this predicate to be true |
Solid::Predicate::Disjunction | 2 | Either of the two contained predicates may be true for this predicate to be true |
Solid::Predicate::InterfaceCheck | 3 | The device type is compared |
Member Function Documentation
Predicate::Predicate()
Constructs an invalid predicate.
[explicit] Predicate::Predicate(const QString &ifaceName)
Constructs a predicate matching devices of a particular device interface ifaceName.
[explicit] Predicate::Predicate(const Solid::DeviceInterface::Type &ifaceType)
Constructs a predicate matching devices of a particular device interface ifaceType.
[explicit, since 6.17] Predicate::Predicate(QStringView ifaceName, Solid::Predicate::NotOperator op)
Constructs a predicate that checks that a device does not have the ifaceName.
The operator op is always NOT.
This function was introduced in 6.17.
Predicate::Predicate(const QString &ifaceName, const QString &property, const QVariant &value, Solid::Predicate::ComparisonOperator compOperator = Equals)
Constructs a predicate matching the value of a property in a given device interface ifaceType.
The optional compOperator applies between the property and the value when matching.
Predicate::Predicate(const Solid::DeviceInterface::Type &ifaceType, const QString &property, const QVariant &value, Solid::Predicate::ComparisonOperator compOperator = Equals)
Constructs a predicate matching the value of a property in a given device interface ifaceType.
The optional compOperator applies between the property and the value when matching.
Solid::Predicate::ComparisonOperator Predicate::comparisonOperator() const
Returns the comparison operator used to compare a property's value.
Note: This is only valid for Conjunction and Disjunction types.
Solid::Predicate Predicate::firstOperand() const
A smaller, inner predicate which is the first to appear and is compared with the second one in a comparison operation.
Note: This is only valid for Conjunction and Disjunction types.
[static] Solid::Predicate Predicate::fromString(const QString &predicate)
Returns a new valid predicate if the given predicate string is syntactically correct, Predicate() otherwise.
Solid::Predicate equalPredicate =
Solid::Predicate::fromString("IS OpticalDisc");Solid::DeviceInterface::Type Predicate::interfaceType() const
Returns a device interface type used by the predicate.
Note: This is only valid for InterfaceCheck and PropertyCheck types.
[since 6.17] bool Predicate::isInterfaceTypeNegated() const
Returns if the interface type check is negated.
This function was introduced in 6.17.
bool Predicate::isValid() const
Returns if the predicate is valid.
Predicate() is the only invalid predicate.
bool Predicate::matches(const Solid::Device &device) const
Returns if a device matches the predicate.
QVariant Predicate::matchingValue() const
Returns the value used when comparing a devices property to see if it matches the predicate.
Note: This is only valid for the PropertyCheck type.
QString Predicate::propertyName() const
Returns the property name used when retrieving the value to compare against.
Note: This is only valid for the PropertyCheck type.
Solid::Predicate Predicate::secondOperand() const
A smaller, inner predicate which is the second to appear and is compared with the first one in a comparison operation.
Note: This is only valid for Conjunction and Disjunction types.
QString Predicate::toString() const
Returns a string representation of the predicate.
Solid::Predicate::Type Predicate::type() const
Retrieves the predicate type, used to determine how to handle the predicate.
QSet<Solid::DeviceInterface::Type> Predicate::usedTypes() const
Returns the device interface types used in this predicate.
Solid::Predicate Predicate::operator&(const Solid::Predicate &other)
'And' operator.
Returns a new 'and' predicate having this and other as operands.
Solid::Predicate &Predicate::operator&=(const Solid::Predicate &other)
'AndEquals' operator.
Assigns to this a new 'and' predicate having this and other as operands.
Solid::Predicate Predicate::operator|(const Solid::Predicate &other)
'Or' operator.
Returns a new 'or' predicate having this and other as operands.
Solid::Predicate &Predicate::operator|=(const Solid::Predicate &other)
'OrEquals' operator.
Assigns to this a new 'or' predicate having this and other as operands.