Доступ к атрибутам типов C++ из QML

QML легко расширяется функциональностью, определенной в коде C++. Благодаря тесной интеграции движка QML с системой метаобъектов Qt, любая функциональность, надлежащим образом экспонированная классом, производным от QObject, доступна из кода QML. Это позволяет напрямую обращаться к данным и функциям C++ из QML, часто с минимальными или без изменений.

Движок QML может интроспектировать экземпляры QObject через систему метаобъектов. Это означает, что любой код QML может получить доступ к следующим членам экземпляра класса, производного от QObject:

• Свойства
• Методы (при условии, что они являются публичными слотами или помечены Q_INVOKABLE)
• Сигналы

(Кроме того, перечисления доступны, если они были объявлены с помощью Q_ENUMS. Подробнее см. Преобразование типов данных между QML и C++.)

В целом, к ним можно получить доступ из QML независимо от того, был ли производный класс QObject зарегистрирован в системе типов QML или нет. Однако, если класс должен использоваться таким образом, что требует доступа к дополнительной информации о типе от движка — например, если сам класс используется в качестве параметра метода или свойства, или если один из его типов перечислений используется таким же образом — тогда класс может потребовать регистрации.

Также обратите внимание, что ряд важных концепций, охватываемых в этом документе, продемонстрированы в учебнике по написанию расширений QML на C++.

Обработка и владение типами данных

Любые данные, передаваемые из C++ в QML, будь то в качестве значения свойства, параметра метода или возвращаемого значения, или значения параметра сигнала, должны иметь тип, поддерживаемый движком QML.

По умолчанию движок поддерживает ряд типов Qt C++ и может автоматически преобразовывать их при использовании из QML. Кроме того, классы C++, зарегистрированные в системе типов QML, могут использоваться в качестве типов данных, как и их перечисления, если они должным образом зарегистрированы. Дополнительная информация приведена в Преобразование типов данных между QML и C++.

Кроме того, при передаче данных из C++ в QML учитываются правила владения данными. Подробности см. в Владение данными.

Экспонирование свойств

Свойство может быть задано для любого производного от QObject класса с помощью макроса Q_PROPERTY(). Свойство — это член данных класса с связанной функцией чтения и необязательной функцией записи.

Все свойства производного от QObject класса доступны из QML.

Например, ниже приведен класс Message со свойством author. Как указано в вызове макроса Q_PROPERTY, к этому свойству можно обратиться для чтения через метод author(), а для записи через метод setAuthor():

class Message : public QObject
{
    Q_OBJECT
    Q_PROPERTY(QString author READ author WRITE setAuthor NOTIFY authorChanged)
public:
    void setAuthor(const QString &a) {
        if (a != m_author) {
            m_author = a;
            emit authorChanged();
        }
    }
    QString author() const {
        return m_author;
    }
signals:
    void authorChanged();
private:
    QString m_author;
};

Если экземпляр этого класса был установлен в качестве свойства контекста при загрузке файла под названием MyItem.qml из C++:

int main(int argc, char *argv[]) {
    QGuiApplication app(argc, argv);

    QQuickView view;
    Message msg;
    view.engine()->rootContext()->setContextProperty("msg", &msg);
    view.setSource(QUrl::fromLocalFile("MyItem.qml"));
    view.show();

    return app.exec();
}

Тогда к свойству author можно обратиться для чтения из MyItem.qml:

// MyItem.qml
import QtQuick 2.0

Text {
    width: 100; height: 100
    text: msg.author    // invokes Message::author() to get this value

    Component.onCompleted: {
        msg.author = "Jonah"  // invokes Message::setAuthor()
    }
}

Для максимальной совместимости с QML, любое записываемое свойство должно иметь связанный сигнал NOTIFY, который излучается всякий раз, когда значение свойства изменяется. Это позволяет использовать свойство со связыванием свойств, что является важной функцией QML, которая обеспечивает связи между свойствами путем автоматического обновления свойства всякий раз, когда значение любого из его зависимостей изменяется.

В приведенном выше примере связанный сигнал NOTIFY для свойства author — это authorChanged, как указано в вызове макроса Q_PROPERTY(). Это означает, что всякий раз, когда сигнал излучается (как это происходит при изменении автора в Message::setAuthor()), это сообщает движку QML, что любые связи, связанные со свойством author, должны быть обновлены, и в свою очередь движок обновит свойство text, вызвав Message::author() еще раз.

Если свойство author было записываемым, но не имело связанного сигнала NOTIFY, значение text было бы инициализировано начальным значением, возвращенным Message::author(), но не обновлялось бы при последующих изменениях этого свойства. Кроме того, любые попытки привязаться к свойству из QML приведут к предупреждению во время выполнения от движка.

Примечание: Рекомендуется, чтобы сигнал NOTIFY назывался <свойство>Changed, где <property> — имя свойства. Обработчик связанного изменения свойства, сгенерированный движком QML, всегда будет иметь вид on<Property>Changed, независимо от имени связанного сигнала C++, поэтому рекомендуется следовать этой соглашению, чтобы избежать путаницы.

Примечания по использованию сигналов NOTIFY

Чтобы предотвратить циклы или чрезмерную оценку, разработчики должны убедиться, что сигнал изменения свойства излучается только тогда, когда значение свойства фактически изменилось. Кроме того, если свойство или группа свойств редко используются, разрешается использовать один и тот же сигнал NOTIFY для нескольких свойств. Это следует делать с осторожностью, чтобы не пострадала производительность.

Наличие сигнала NOTIFY влечет за собой небольшие накладные расходы. Существуют случаи, когда значение свойства устанавливается во время создания объекта и не изменяется впоследствии. Наиболее распространенный случай — это когда тип использует группированные свойства, а объект группированного свойства выделяется один раз и освобождается только при удалении объекта. В этих случаях атрибут CONSTANT можно добавить в объявление свойства вместо сигнала NOTIFY.

Атрибут CONSTANT следует использовать только для свойств, значение которых устанавливается и завершается только в конструкторе класса. Все остальные свойства, которые нужно использовать в связях, должны иметь сигнал NOTIFY вместо этого.

Свойства с типами объектов

Свойства типа объект доступны из QML при условии, что тип объекта должным образом зарегистрирован в системе типов QML.

Например, тип Message может иметь свойство body типа MessageBody*:

class Message : public QObject
{
    Q_OBJECT
    Q_PROPERTY(MessageBody* body READ body WRITE setBody NOTIFY bodyChanged)
public:
    MessageBody* body() const;
    void setBody(MessageBody* body);
};

class MessageBody : public QObject
{
    Q_OBJECT
    Q_PROPERTY(QString text READ text WRITE text NOTIFY textChanged)
// ...
}

Предположим, что тип Message был зарегистрирован в системе типов QML, что позволяет использовать его в качестве типа объекта из кода QML:

Message {
    // ...
}

Если тип MessageBody также был зарегистрирован в системе типов, то было бы возможно присвоить MessageBody свойству body экземпляра Message, все из кода QML:

Message {
    body: MessageBody {
        text: "Hello, world!"
    }
}

Свойства со списками объектов

Свойства, содержащие списки производных от QObject типов, также могут быть доступны из QML. Однако для этой цели следует использовать QQmlListProperty вместо QList<T> в качестве типа свойства. Это связано с тем, что QList не является производным от QObject типом и поэтому не может предоставить необходимые характеристики свойства QML, такие как уведомления о сигналах при изменении списка, через систему метаобъектов Qt.

QQmlListProperty — это шаблонный класс, который удобно создаётся из значения QList.

Например, класс MessageBoard ниже имеет свойство messages типа QQmlListProperty, которое хранит список экземпляров Message:

class MessageBoard : public QObject
{
    Q_OBJECT
    Q_PROPERTY(QQmlListProperty<Message> messages READ messages)
public:
    QQmlListProperty<Message> messages() const;

private:
    static void append_message(QQmlListProperty<Message> *list, Message *msg);

    QList<Message *> m_messages;
};

Функция MessageBoard::messages() просто создаёт и возвращает QQmlListProperty из своего члена QList<T> m_messages, передавая соответствующие функции изменения списка, как требуется конструктором QQmlListProperty:

QQmlListProperty<Message> MessageBoard::messages()
{
    return QQmlListProperty<Message>(this, 0, &MessageBoard::append_message);
}

void MessageBoard::append_message(QQmlListProperty<Message> *list, Message *msg)
{
    MessageBoard *msgBoard = qobject_cast<MessageBoard *>(list->object);
    if (msg)
        msgBoard->m_messages.append(msg);
}

Обратите внимание, что тип шаблонного класса для QQmlListProperty — в данном случае Message — должен быть зарегистрирован в системе типов QML.

Группированные свойства

Любое свойство типа объекта, доступное только для чтения, доступно из кода QML как группированное свойство. Это можно использовать для экспонирования группы связанных свойств, описывающих набор атрибутов для типа.

Например, предположим, что свойство Message::author было типа MessageAuthor вместо просто строки, с подсвойствами name и email:

class MessageAuthor : public QObject
{
    Q_PROPERTY(QString name READ name WRITE setName)
    Q_PROPERTY(QString email READ email WRITE setEmail)
public:
    ...
};

class Message : public QObject
{
    Q_OBJECT
    Q_PROPERTY(MessageAuthor* author READ author)
public:
    Message(QObject *parent)
        : QObject(parent), m_author(new MessageAuthor(this))
    {
    }
    MessageAuthor *author() const {
        return m_author;
    }
private:
    MessageAuthor *m_author;
};

К свойству author можно было бы обратиться с использованием синтаксиса группированных свойств в QML, например так:

Message {
    author.name: "Alexandra"
    author.email: "alexandra@mail.com"
}

Тип, экспонируемый в качестве группированного свойства, отличается от свойства типа объекта тем, что группированное свойство является только для чтения и инициализируется допустимым значением родительским объектом при создании. Подсвойства группированного свойства можно изменять из QML, но сам объект группированного свойства никогда не изменится, в то время как свойство типа объекта может быть присвоено новое значение объекта из QML в любое время. Таким образом, жизненный цикл объекта группированного свойства строго контролируется реализацией родительского объекта C++, в то время как свойство типа объекта может быть свободно создано и уничтожено через код QML.

Экспонирование методов (включая слоты Qt)

Любой метод производного от QObject типа доступен из кода QML, если он:

• Является общедоступным методом, помеченным макросом Q_INVOKABLE()
• Методом, который является общедоступным слотом Qt Qt

Например, класс MessageBoard ниже имеет метод postMessage(), помеченный макросом Q_INVOKABLE, а также метод refresh(), являющийся публичным слотом:

class MessageBoard : public QObject
{
    Q_OBJECT
public:
    Q_INVOKABLE bool postMessage(const QString &msg) {
        qDebug() << "Called the C++ method with" << msg;
        return true;
    }

public slots:
    void refresh() {
        qDebug() << "Called the C++ slot";
    }
};

Если экземпляр MessageBoard был установлен как данные контекста для файла MyItem.qml, как показано слева, то из MyItem.qml можно вызвать два метода, как показано справа:

int main(int argc, char *argv[]) {
    QGuiApplication app(argc, argv);

    MessageBoard msgBoard;
    QQuickView view;
    view.engine()->rootContext()->setContextProperty("msgBoard", &msgBoard);
    view.setSource(QUrl::fromLocalFile("MyItem.qml"));
    view.show();

    return app.exec();
}

// MyItem.qml
import QtQuick 2.0

Item {
    width: 100; height: 100

    MouseArea {
        anchors.fill: parent
        onClicked: {
            var result = msgBoard.postMessage("Hello from QML")
            console.log("Result of postMessage():", result)
            msgBoard.refresh();
        }
    }
}

Если у метода C++ есть параметр типа QObject*, значение параметра можно передать из QML, используя объект id или значение JavaScript переменной, ссылающееся на этот объект.

QML поддерживает вызов перегруженных функций C++. Если существует несколько функций C++ с одинаковым именем, но различными аргументами, правильная функция будет вызвана в соответствии с количеством и типами предоставленных аргументов.

Значения, возвращаемые методами C++, преобразуются в значения JavaScript при обращении к ним из выражений JavaScript в QML.

Отображение сигналов

Любой публичный сигнал объекта, производного от QObject, доступен из кода QML.

Двигатель QML автоматически создаёт обработчик сигнала для любого сигнала объекта, производного от QObject, который используется из QML. Обработчики сигналов всегда имеют имя on<Signal>, где <Signal> — имя сигнала с заглавной первой буквой. Все параметры, передаваемые сигналом, доступны в обработчике сигнала через имена параметров.

Например, предположим, что класс MessageBoard имеет сигнал newMessagePosted() с единственным параметром subject.

class MessageBoard : public QObject
{
    Q_OBJECT
public:
   // ...
signals:
   void newMessagePosted(const QString &subject);
};

Если тип MessageBoard был зарегистрирован в системе типов QML, то объект MessageBoard , объявленный в QML, мог бы получать сигнал newMessagePosted() с помощью обработчика сигналов с именем onNewMessagePosted, и исследовать значение параметра subject.

MessageBoard {
    onNewMessagePosted: console.log("New message received:", subject)
}

Как и в случае с значениями свойств и параметрами методов, параметр сигнала должен иметь тип, поддерживаемый движком QML; см. Преобразование типов данных между QML и C++. (Использование незарегистрированного типа не вызовет ошибки, но значение параметра не будет доступно из обработчика.)

Классы могут иметь несколько сигналов с одинаковым именем, но доступен только последний сигнал как QML-сигнал. Обратите внимание, что сигналы с одинаковым именем, но разными параметрами, не могут быть различимы.