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

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

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

Именование пользовательских типов QML-объектов

Для создания типа объекта QML-документ следует разместить в текстовом файле с именем <TypeName>.qml, где <TypeName> — желаемое имя типа. Имя типа должно соответствовать следующим требованиям:

• Оно должно состоять из буквенно-цифровых символов или подчеркиваний.
• Оно должно начинаться с заглавной буквы.

Этот документ автоматически распознаётся движком как определение QML-типа. Кроме того, тип, определённый таким образом, автоматически становится доступным для других 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. Когда движок 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 id со значением root вместо squareButton, это не вступало бы в конфликт с id с тем же значением для корневого объекта, определённого в SquareButton.qml, так как оба были бы объявлены в разных областях видимости.