Back to Qt.io
Contact Us Blog Download Qt

QIfAbstractZonedFeature Class

The QIfAbstractZonedFeature is the base class for all zoned features. More...

Header: #include <QIfAbstractZonedFeature>
qmake: QT += interfaceframework
In QML: AbstractZonedFeature
Inherits: QIfAbstractFeature

Properties

Public Functions

QIfAbstractZonedFeature(const QString &interface, const QString &zone = QString(), QObject *parent = nullptr)
QStringList availableZones() const
QString zone() const
QIfAbstractZonedFeature *zoneAt(const QString &zone) const
QList<QIfAbstractZonedFeature *> zones() const

Signals

void availableZonesChanged(const QStringList &zones)
void zoneChanged()
void zonesChanged()

Protected Functions

QIfZonedFeatureInterface *backend(const QString &interface = QString()) const
virtual QIfAbstractZonedFeature *createZoneFeature(const QString &zone) = 0

Reimplemented Protected Functions

virtual bool acceptServiceObject(QIfServiceObject *serviceObject) override
virtual void clearServiceObject() override
virtual void connectToServiceObject(QIfServiceObject *serviceObject) override

Detailed Description

Subclass QIfAbstractZonedFeature to create an API with several zones. See Zoned Features for usecases were this concept can be useful.

Implementation

A derived class needs to implement the createZoneFeature function which is responsible for instantiating the class used for the given zone. In the simplest form, the same class is allocated, passing on the zone argument to its constructor:

class QIfClimateControl : public QIfAbstractZonedFeature {

    ...

    explicit QIfClimateControl(const QString &zone = QString(), QObject *parent = nullptr)
        : QIfAbstractZonedFeature(QIfClimateControl_iid, zone, parent)
    {
    }

protected:
    QIfAbstractZonedFeature *createZoneFeature(const QString &zone) override
    {
        new QIfClimateControl(zone, this);
    }
}

For the derived class, the same backend connection calls are made in the same order as specified in QIfAbstractFeature and Detailed Connection Order. This applies also for the zone instances, which use the passed zone argument to identify the signals in the backendinterface belonging to this zone.

See QIfZonedFeatureInterface for how a backend needs to be implemented and how it can handle zone specific properties.

Zone specific instance

Using the simple form described above, together with handling zone specific properties in the backend has some down-sides. As the API is the same for the front-facing API and all its zones, the developer using such an API cannot identify which properties/functions are zone specific.

There are two solutions for the problem, which are best used together to provide the most versatile API.

Implement an isXAvailable function for each zone functionality

Add an extra property for each zone functionality to specify whether the functionality is available. A developer can use such a property in the UI the hide the relevant UI elements on the fly, instead of hardcoding it based on a zone name or relying on the error mechanism described in the Setter implementation.

Instantiate a custom class in createZoneFeature

By instantiating a custom class in createZoneFeature, the API for zoned and unzoned features can be split over two classes. The unzoned functionality is implemented in the front-facing API, while all zone specific functions are implemented in the Zone class which is returned by createZoneFeature().

Usage

Once the backend is connected, the availableZones property can be used to retrieve all currently available zones. A specific zone can be accessed using the zoneAt() function or by using the zones function, which returns all zones in a list.

Property Documentation

[read-only] availableZones : const QStringList

Holds a list of the available zones.

Access functions:

QStringList availableZones() const

Notifier signal:

void availableZonesChanged(const QStringList &zones)

zone : const QString

Name of the zone of this zoned feature.

The zone can be given in the feature initialization. With this property it's possible to control only a single specific feature zone.

This property is writable only before the backend is connected. Once the backend is discovered and the component is verified to be valid, zone is not writable anymore.

It's recommended to initialize the zone in the feature constructor:

QIfClimateControl *climateControl = new QIfClimateControl("FrontLeft", this);
climateControl->startAutoDiscovery();
QString zone = climateControl->zone();

After initialization, it's not recommended to change the zone.

Access functions:

QString zone() const

Notifier signal:

void zoneChanged()

[read-only] zoneAt : const QVariantMap

Provides direct feature access to the given zone.

Notifier signal:

void zonesChanged()

[read-only] zones : const QVariantList

Provides access to the feature zones model.

Notifier signal:

void zonesChanged()

Member Function Documentation

[explicit] QIfAbstractZonedFeature::QIfAbstractZonedFeature(const QString &interface, const QString &zone = QString(), QObject *parent = nullptr)

Constructs a zoned feature with a specific interface and zone.

If parent is of type QIfAbstractZonedFeature, then the created instance uses parent for the backend connection. Parent is connected to the backend and will forward updates between child features and the backend.

See also QIfAbstractFeature.

[override virtual protected] bool QIfAbstractZonedFeature::acceptServiceObject(QIfServiceObject *serviceObject)

Reimplements: QIfAbstractFeature::acceptServiceObject(QIfServiceObject *serviceObject).

[protected] QIfZonedFeatureInterface *QIfAbstractZonedFeature::backend(const QString &interface = QString()) const

Returns a pointer to the backend interface.

Returns the parent backend, if the parent is a QIfAbstractZonedFeature type. Returns zero if no backend is connected.

[override virtual protected] void QIfAbstractZonedFeature::clearServiceObject()

Reimplements: QIfAbstractFeature::clearServiceObject().

[override virtual protected] void QIfAbstractZonedFeature::connectToServiceObject(QIfServiceObject *serviceObject)

Reimplements: QIfAbstractFeature::connectToServiceObject(QIfServiceObject *serviceObject).

[pure virtual protected] QIfAbstractZonedFeature *QIfAbstractZonedFeature::createZoneFeature(const QString &zone)

Create a new child feature for the given zone.

Returns zero if the feature can't be created using the parameters specified.

QIfAbstractZonedFeature *QIfAbstractZonedFeature::zoneAt(const QString &zone) const

Returns the given zone instance for the feature.

QList<QIfAbstractZonedFeature *> QIfAbstractZonedFeature::zones() const

Returns all zone instances for the feature.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.