Начало работы с QML

QML (Qt Modeling Language) — язык разметки для создания QML-документов, представляющих собой дерево элементов. Он описывает расположение элементов относительно друг друга на экране, их свойства и взаимодействия с ними.

В состав Аврора SDK входят следующие QML-модули, используемые для создания приложений для ОС Аврора:

Qt Quick — стандартная библиотека для написания QML-приложений.
Silica — предоставляет дополнительные типы, предназначенные для создания приложений с внешним видом, поведением и уникальными возможностями, соответствующими стилю стандартных приложений ОС Аврора.

В данной статье основы синтаксиса QML рассмотрены на примере создания первого проекта в Аврора SDK, в результате чего в проекте появятся базовые QML-файлы, минимально необходимые для работы приложения.

Содержание:

QML-структура проекта
Материалы для дальнейшего изучения

QML-структура проекта

Все используемые для работы QML-файлы (QML-документы) находятся в директории qml.

Директория qml содержит в себе корневой файл <имя_проекта>.qml. Он используется как точка входа в приложение.

Директория QML

Корневой файл

Ниже представлено содержание данного QML-файла.

import QtQuick 2.0
import Sailfish.Silica 1.0

ApplicationWindow {
    objectName: "applicationWindow"
    initialPage: Qt.resolvedUrl("pages/MainPage.qml")
    cover: Qt.resolvedUrl("cover/DefaultCoverPage.qml")
    allowedOrientations: defaultAllowedOrientations
}

Строки импорта используются для подключения необходимых библиотек QtQuick и Silica.
ApplicationWindow — компонент верхнего уровня, точка входа для загрузки приложения. Компоненты в QML содержат внутри свойства, представляющие собой пару имя: значение В свойствах ApplicationWindow указывается начальная страница и обложка приложения.
objectName — свойство, задающее уникальное имя для компонента.
initialPage — свойство, содержащее в себе путь к странице, которая отображается при открытии приложения.
cover — свойство, содержащее путь к активной обложке приложения.
allowedOrientations — свойство, определяющее доступную ориентацию приложения.

Каждое окно приложения содержит один стек страниц, доступный через свойство pageStack, которое определяет содержимое, отображаемое приложением. Стек состоит из объектов Page.

Начальная страница

Все страницы хранятся в поддиректории pages.

import QtQuick 2.0
import Sailfish.Silica 1.0

Page {
    objectName: "mainPage"
    allowedOrientations: Orientation.All

    PageHeader {
        objectName: "pageHeader"
        title: qsTr("Template")
        extraContent.children: [
            IconButton {
                objectName: "aboutButton"
                icon.source: "image://theme/icon-m-about"
                anchors.verticalCenter: parent.verticalCenter

                onClicked: pageStack.push(Qt.resolvedUrl("AboutPage.qml"))
            }
        ]
    }
}

PageHeader — вложенный компонент, представляющий собой заголовок страницы.
title — свойство, содержащее текст заголовка.
extraContent — элемент управления внутренним пространством заголовка страницы. Используется для добавления дополнительного контента заголовка. Подсвойство chidlren вызывается у данного свойства для создания массива из элементов.
IconButton — компонент, который реализует оформленную в стиле ОС Аврора кнопку с изображением.
icon — свойство, которое вместе с подсвойством source добавляет значок приложения, используемого в ОС Аврора. Полный список наименований значков, имеющихся в Silica, доступен в Figma. Также при создании приложения в окне «Иконка приложения» можно изменить значок по умолчанию, задав другой цвет или загрузив другой значок.
anchors.verticalCenter — свойство, позволяющее позиционировать компонент относительно других компонентов. Подсвойство verticalCenter позволяет выравнять компонент IconButton вертикально по центру относительно PageHeader, который является для него родительским компонентом. Для обращения к родительскому компоненту используется свойство parent.
onClicked — обработчик события клика, клик определяется как нажатие с последующим отпусканием. Нажатие на компонент приведёт к переходу на другую страницу. Свойство pageStack управляет страницами приложения и хранит их.

Результат рендеринга данной страницы можно посмотреть в эмуляторе:

Начальная страница в эмуляторе

Cтраница "О приложении"

import QtQuick 2.0
import Sailfish.Silica 1.0

Page {
    objectName: "aboutPage"
    allowedOrientations: Orientation.All

    SilicaFlickable {
        objectName: "flickable"
        anchors.fill: parent
        contentHeight: layout.height + Theme.paddingLarge

        Column {
            id: layout
            objectName: "layout"
            width: parent.width

            PageHeader {
                objectName: "pageHeader"
                title: qsTr("About Application")
            }

            Label {
                objectName: "descriptionText"
                anchors { left: parent.left; right: parent.right; margins: Theme.horizontalPageMargin }
                color: palette.highlightColor
                font.pixelSize: Theme.fontSizeSmall
                textFormat: Text.RichText
                wrapMode: Text.WordWrap
                text: qsTr("#descriptionText")
            }

            SectionHeader {
                objectName: "licenseHeader"
                text: qsTr("3-Clause BSD License")
            }

            Label {
                objectName: "licenseText"
                anchors { left: parent.left; right: parent.right; margins: Theme.horizontalPageMargin }
                color: palette.highlightColor
                font.pixelSize: Theme.fontSizeSmall
                textFormat: Text.RichText
                wrapMode: Text.WordWrap
                text: qsTr("#licenseText")
            }
        }
    }
}

SilicaFlickable — компонент Flickable с характерными для ОС Аврора поведением и дополнительными свойствами.
contentHeight — свойство, определяющее размер отображаемого контента внутри компонента Flickable. Контент, не умещающийся в заданные рамки, будет доступен для прокрутки.
Theme — компонент, содержащий оформление пользовательского интерфейса приложения в стиле ОС Аврора. Например, внешние и внутренние отступы, размеры шрифтов.
Column — компонент, располагающий дочерние компоненты вертикально.
PageHeader — компонент, представляющий собой оформленный в стиле ОС Аврора заголовок.
Label — компонент, представляющий собой оформленную в стиле ОС Аврора текстовую метку.
Стоит обратить внимание, что подсвойства для одного и того же свойства рекомендуется группировать, как это сделано в компоненте Label.
font.pixelSize — свойство и подсвойство, устанавливающее размер шрифта в пикселях.
textFormat — свойство, отвечающее за расположение текста.
Text — компонент, содержащий свойства для работы с текстом.
wrapMode — свойство, определяющее, как текст будет переноситься на новую строку, если он не помешается в одну строку.
text — свойство, содержащее в себе текст для компонента Label.

Страница "О приложении" в эмуляторе

Обложка

Обложка приложения хранится в директории cover. Обложка — это визуальное представление приложения, которые отображаются на домашнем экране устройства, когда приложение работает в фоне.

import QtQuick 2.0
import Sailfish.Silica 1.0

CoverBackground {
    objectName: "defaultCover"

    CoverTemplate {
        objectName: "applicationCover"
        primaryText: "App"
        secondaryText: qsTr("Template")
        icon {
            source: Qt.resolvedUrl("../icons/HelloWorld.svg")
            sourceSize { width: icon.width; height: icon.height }
        }
    }
}

CoverBackground — компонент, представляющий собой полупрозрачную обложку.
CoverTemplate — компонент, представляющий собой шаблон для обложки приложения.
primaryText, secondaryText — свойства, которые отображают текст в соответствующих полях обложки.
icon — свойство, регулирующее отображение значка приложения.

Обложка на эмуляторе

Материалы для дальнейшего изучения

В этом списке представлены ссылки на статьи, которые пригодятся при дальнейшей работе с QML: