Тип компонента QML

Инкапсулирует определение компонента QML Подробнее...

• Список всех членов, включая унаследованные

Свойства

• progress : вещественное
• status : перечисление
• url : url

Прикреплённые сигналы

• completed()
• destruction()

Методы

• объект createObject(QtObject parent, объект properties)
• строка errorString()
• объект incubateObject(Item parent, объект properties, перечисление mode)

Подробное описание

Компоненты — это многократно используемые, инкапсулированные типы QML с хорошо определёнными интерфейсами.

Компоненты часто определяются файлами компонентов — то есть, .qml файлами. Тип QML-документ, а не отдельным QML-файлом. Это может быть полезно для повторного использования небольшого компонента внутри QML-файла или для определения компонента, который логически принадлежит к другим компонентам QML в файле.

Например, вот компонент, который используется несколькими объектами Loader. Он содержит один элемент — Rectangle:

import QtQuick 2.0

Item {
    width: 100; height: 100

    Component {
        id: redSquare

        Rectangle {
            color: "red"
            width: 10
            height: 10
        }
    }

    Loader { sourceComponent: redSquare }
    Loader { sourceComponent: redSquare; x: 20 }
}

Обратите внимание, что, хотя сам Rectangle будет автоматически отрисовываться и отображаться, это не так для прямоугольника выше, потому что он определён внутри Component. Компонент инкапсулирует типы QML внутри, как если бы они были определены в отдельном QML-файле, и загружается только по запросу (в данном случае, двумя объектами Loader). Поскольку Component не наследуется от Item, к нему нельзя привязать ничего.

Определение Component аналогично определению QML-документа. QML-документ имеет один элемент верхнего уровня, который определяет поведение и свойства этого компонента и не может определить свойства или поведение за пределами этого элемента верхнего уровня. Точно так же определение Component содержит один элемент верхнего уровня (который в приведённом примере — Rectangle) и не может определять какие-либо данные за пределами этого элемента, за исключением id (который в приведённом примере — redSquare).

Тип Component обычно используется для предоставления графических компонентов для представлений. Например, свойство ListView::delegate требует Component для указания того, как должен отображаться каждый элемент списка.

Component объекты также могут быть созданы динамически с помощью Qt.createComponent().

Контекст создания

Контекст создания компонента соответствует контексту, где был объявлен компонент. Этот контекст используется в качестве родительского контекста (создавая иерархию контекстов контекста) при создании компонента объектом, например ListView или Loader.

В следующем примере, comp1 создаётся в корневом контексте MyItem.qml, и любые объекты, созданные из этого компонента, будут иметь доступ к id и свойствам в этом контексте, таким как internalSettings.color. Когда comp1 используется как делегат ListView в другом контексте (как в main.qml ниже), он по-прежнему будет иметь доступ к свойствам своего контекста создания (которые в противном случае были бы скрыты для внешних пользователей).

Item {
    property Component mycomponent: comp1

    QtObject {
        id: internalSettings
        property color color: "green"
    }

    Component {
        id: comp1
        Rectangle { color: internalSettings.color; width: 400; height: 50 }
    }
}

ListView {
    width: 400; height: 400
    model: 5
    delegate: myItem.mycomponent    //will create green Rectangles

    MyItem { id: myItem }
}

Документация по свойствам

progress : вещественное

Прогресс загрузки компонента, от 0.0 (ничего не загружено) до 1.0 (загрузка завершена).

status : перечисление

Это свойство содержит состояние загрузки компонента. Состояние может быть одним из следующих:

• Component.Null — данные для компонента недоступны
• Component.Ready — компонент загружен и может использоваться для создания экземпляров.
• Component.Loading — компонент в настоящее время загружается
• Component.Error — во время загрузки компонента произошла ошибка. Вызов errorString() предоставит удобочитаемое описание любых ошибок.

url : url

URL компонента. Это URL, который был использован для построения компонента.

Документация по прикреплённым сигналам

completed()

Вызывается после того, как объект был создан. Это можно использовать для выполнения скриптового кода при запуске, после того, как вся QML-среда будет установлена.

Соответствующий обработчик — onCompleted. Он может быть объявлен в любом объекте. Порядок выполнения onCompleted обработчиков не определён.

Rectangle {
    Component.onCompleted: console.log("Completed Running!")
    Rectangle {
        Component.onCompleted: console.log("Nested Completed Running!")
    }
}

destruction()

Вызывается, когда начинается уничтожение объекта. Это можно использовать для отмены работы, выполненной в ответ на сигнал completed(), или другого императивного кода в вашем приложении.

Соответствующий обработчик — onDestruction. Он может быть объявлен в любом объекте. Порядок выполнения onDestruction обработчиков не определён.

Rectangle {
    Component.onDestruction: console.log("Destruction Beginning!")
    Rectangle {
        Component.onDestruction: console.log("Nested Destruction Beginning!")
    }
}

См. также Qt QML.

Документация по методам

объект createObject(QtObject parent, объект properties)

Создаёт и возвращает экземпляр объекта этого компонента, который будет иметь указанного parent и properties. Аргумент properties необязателен. Возвращает null, если создание объекта не удаётся.

Объект будет создан в том же контексте, что и контекст создания компонента. Эта функция всегда вернёт null при вызове для компонентов, которые не были созданы в QML.

Если вы хотите создать объект без задания родителя, укажите null для значения parent. Обратите внимание, что если возвращаемый объект должен быть отображён, вы должны указать действительное значение parent или установить свойство parent возвращаемого объекта; в противном случае объект не будет отображаться.

Если parent не указан для createObject(), ссылка на возвращаемый объект должна быть сохранена, чтобы он не был уничтожен сборщиком мусора. Это верно независимо от того, установлено ли Item::parent позже, так как установка родителя Item не меняет владение объектом. Меняется только графический родитель.

Начиная с QtQuick 1.1, этот метод принимает необязательный аргумент properties, который определяет карту начальных значений свойств для создаваемого объекта. Эти значения применяются до завершения создания объекта. Это более эффективно, чем установка значений свойств после создания объекта, особенно там, где определены большие наборы значений свойств, и также позволяет настраивать привязки свойств (с помощью Qt.binding) до создания объекта.

Аргумент properties задаётся как карта элементов свойство-значение. Например, код ниже создаёт объект с начальными x и y значениями 100 и 100 соответственно:

var component = Qt.createComponent("Button.qml");
if (component.status == Component.Ready)
    component.createObject(parent, {"x": 100, "y": 100});

Динамически созданные экземпляры могут быть удалены с помощью метода destroy(). См. Динамическое создание QML-объектов из JavaScript для получения дополнительной информации.

См. также incubateObject().

строка errorString()

Возвращает удобочитаемое описание любой ошибки.

Строка включает файл, расположение и описание каждой ошибки. Если присутствуют несколько ошибок, они разделяются символом новой строки.

Если ошибок нет, возвращается пустая строка.

объект incubateObject(Item parent, объект properties, перечисление mode)

Создаёт инкубатор для экземпляра этого компонента. Инкубаторы позволяют асинхронно создавать новые экземпляры компонентов и не вызывают зависания пользовательского интерфейса.

Аргумент parent задаёт родителя, который будет у созданного экземпляра. Пропуск параметра или передача null создаст объект без родителя. В этом случае ссылка на созданный объект должна быть сохранена, чтобы он не был уничтожен сборщиком мусора.

Аргумент properties задаётся как карта элементов свойство-значение, которые будут установлены на созданном объекте во время его построения. mode может быть Qt.Synchronous или Qt.Asynchronous и управляет тем, создаётся ли экземпляр синхронно или асинхронно. По умолчанию — асинхронно. В некоторых случаях, даже если указано Qt.Synchronous, инкубатор может создать объект асинхронно. Это происходит, если компонент, вызывающий incubateObject(), сам создаётся асинхронно.

Все три аргумента необязательны.

Если операция выполнена успешно, метод возвращает инкубатор, иначе null. У инкубатора есть следующие свойства:

• status Статус инкубатора. Допустимые значения: Component.Ready, Component.Loading и Component.Error.
• object Созданный экземпляр объекта. Будет доступен только после того, как инкубатор перейдет в состояние Ready.
• onStatusChanged Указывает функцию обратного вызова, которая вызывается при изменении статуса. Статус передается в качестве параметра в функцию обратного вызова.
• forceCompletion() Вызов для синхронного завершения инкубации.

Следующий пример демонстрирует использование инкубатора:

var component = Qt.createComponent("Button.qml");

var incubator = component.incubateObject(parent, { x: 10, y: 10 });
if (incubator.status != Component.Ready) {
    incubator.onStatusChanged = function(status) {
        if (status == Component.Ready) {
            print ("Object", incubator.object, "is now ready!");
        }
    }
} else {
    print ("Object", incubator.object, "is ready immediately!");
}

Динамически созданные экземпляры могут быть удалены с помощью метода destroy(). Подробнее см. Динамическое создание QML-объектов из JavaScript.

См. также createObject().