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

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

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

Свойства

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

Присоединенные сигналы

• completed()
• destruction()

Методы

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

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

Компоненты — это многократно используемые, инкапсулированные типы 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(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().