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

Оборачивает определение компонента QML. Подробнее...

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

Свойства

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

Подключенные сигналы

• completed()
• destruction()

Методы

• объект createObject(родитель, объект свойства)
• строка errorString()
• объект incubateObject(родитель, объект свойства, перечисление режим)

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

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

Компоненты часто определяются в файлах компонентов — это .qml файлы. Тип Component позволяет по существу определять компоненты 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, и любые объекты, созданные из этого компонента, будут иметь доступ к идентификаторам и свойствам в этом контексте, таким как 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(родитель, объект свойства)

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

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

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

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

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

Аргумент свойства задаётся как карта элементов свойство-значение. Например, код ниже создаёт объект с начальными значениями 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(родитель, объект свойства, перечисление режим)

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

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

Аргумент свойства задаётся как карта элементов свойство-значение, которые будут установлены на созданный объект во время его построения. режим может быть 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().