Определение типов объектов через QML-документы

Одна из основных функций QML заключается в том, что она позволяет легко определять типы QML-объектов в лёгкой форме через QML-документы, чтобы удовлетворить потребности отдельных QML-приложений. Стандартный модуль Qt Quick предоставляет различные типы, такие как Прямоугольник, Текст и Изображение для построения QML-приложения; помимо этого, вы можете легко определять свои собственные QML-типы для повторного использования в приложении. Эта возможность создавать собственные типы является основой любого QML-приложения.

Определение типа объекта с помощью QML-файла

Для создания типа объекта QML-документ должен быть помещён в текстовый файл с именем <TypeName>.qml, где <TypeName> — желаемое имя типа, которое должно состоять из буквенно-цифровых символов или символов подчёркивания и начинаться с заглавной буквы. Этот документ автоматически распознаётся движком как определение типа QML. Кроме того, тип, определённый таким образом, автоматически становится доступным для других QML-файлов в том же каталоге, так как движок ищет в непосредственном каталоге при разрешении имён QML-типов.

Например, ниже представлен документ, который объявляет Прямоугольник с дочерним элементом Областью наведения мыши. Документ был сохранён в файл с именем SquareButton.qml.

// SquareButton.qml
import QtQuick 2.0

Rectangle {
    property int side: 100
    width: side; height: side
    color: "red"

    MouseArea {
        anchors.fill: parent
        onClicked: console.log("Button clicked!")
    }
}

Поскольку файл называется SquareButton.qml, теперь его можно использовать в качестве типа SquareButton любым другим QML-файлом в том же каталоге. Например, если в том же каталоге был файл myapplication.qml, он мог бы ссылаться на тип SquareButton.

// myapplication.qml
import QtQuick 2.0

SquareButton {}

Это создаёт красный Прямоугольник размером 100x100 с внутренней Областью наведения мыши, как определено в SquareButton.qml. Когда движок загружает этот myapplication.qml документ, он загружает документ SquareButton.qml в качестве компонента и инициализирует его, чтобы создать объект SquareButton.

Тип SquareButton инкапсулирует дерево QML-объектов, объявленных в SquareButton.qml. Когда QML-движок создаёт объект SquareButton из этого типа, он создаёт объект из дерева Прямоугольника, объявленного в SquareButton.qml.

Примечание: регистр букв имени файла имеет значение на некоторых файловых системах (в частности, UNIX). Рекомендуется, чтобы регистр имени файла точно соответствовал регистру желаемого имени QML-типа — например, Box.qml, а не BoX.qml, независимо от платформы, на которой будет развернут QML-тип.

Импортирование типов, определённых вне текущего каталога

Если SquareButton.qml находился не в том же каталоге, что и myapplication.qml, тип SquareButton нужно было бы сделать доступным через оператор import в myapplication.qml. Он может быть импортирован из относительного пути на файловой системе или как установленный модуль; см. модуль для получения более подробной информации.

Доступные атрибуты пользовательских типов

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

Например, типом корневого объекта в файле SquareButton.qml выше является Прямоугольник. Это означает, что любые свойства, определённые типом Прямоугольник, могут быть изменены для объекта SquareButton. Код ниже определяет три объекта SquareButton с настраиваемыми значениями для некоторых свойств корневого объекта Прямоугольник типа SquareButton:

// application.qml
import QtQuick 2.0

Column {
    SquareButton { side: 50 }
    SquareButton { x: 50; color: "blue" }
    SquareButton { radius: 10 }
}

Атрибуты, доступные для объектов пользовательского QML-типа, включают любые пользовательские свойства, методы и сигналы, которые дополнительно были определены для объекта. Например, предположим, что Прямоугольник в SquareButton.qml был определён следующим образом, с дополнительными свойствами, методами и сигналами:

// SquareButton.qml
import QtQuick 2.0

Rectangle {
    id: root

    property bool pressed: mouseArea.pressed

    signal buttonClicked(real xPos, real yPos)

    function randomizeColor() {
        root.color = Qt.rgba(Math.random(), Math.random(), Math.random(), 1)
    }

    property int side: 100
    width: side; height: side
    color: "red"

    MouseArea {
        id: mouseArea
        anchors.fill: parent
        onClicked: root.buttonClicked(mouse.x, mouse.y)
    }
}

Любой объект SquareButton может использовать свойство pressed, сигнал buttonClicked и метод randomizeColor(), которые были добавлены к корневому объекту Прямоугольник:

// application.qml
import QtQuick 2.0

SquareButton {
    id: squareButton

    onButtonClicked: {
        console.log("Clicked", xPos, yPos)
        randomizeColor()
    }

    Text { text: squareButton.pressed ? "Down" : "Up" }
}

Обратите внимание, что любые значения id , определённые в SquareButton.qml, недоступны для объектов SquareButton, так как значения id доступны только из области видимости компонента, в которой объявлен компонент. Объект SquareButton не может ссылаться на mouseArea для ссылки на дочерний элемент Область наведения мыши, и если у него был бы id со значением root, а не squareButton, это не конфликтовало бы со значением id корневого объекта, определённого в SquareButton.qml, так как оба были бы объявлены в отдельных областях видимости.