Атрибуты QML-объектов

Каждый тип QML-объекта имеет определенный набор атрибутов. Каждый экземпляр типа объекта создается с набором атрибутов, определенных для этого типа объекта. Существует несколько различных типов атрибутов, которые можно указать, описание которых приведено ниже.

Атрибуты в объявлениях объектов

Объявление объекта в QML-документе определяет новый тип. Оно также объявляет иерархию объектов, которая будет инстанцирована, если будет создан экземпляр этого вновь определенного типа.

Следующие типы атрибутов QML-объектов:

• атрибут id
• атрибуты свойств
• атрибуты сигналов
• атрибуты обработчиков сигналов
• атрибуты методов
• присоединенные свойства и атрибуты присоединенных обработчиков сигналов
• атрибуты перечислений

Эти атрибуты подробно описаны ниже.

Атрибут id

Каждый тип QML-объекта имеет ровно один атрибут id. Этот атрибут предоставляется самим языком и не может быть переопределен или изменен любым типом QML-объекта.

Значение может быть присвоено атрибуту id экземпляра объекта, чтобы этот объект можно было идентифицировать и ссылаться на него другими объектами. Это id должно начинаться с буквы в нижнем регистре или символа подчеркивания и не может содержать символы, отличные от букв, цифр и символов подчеркивания.

Ниже приведен объект TextInput и объект Text. Значение атрибута id объекта TextInput установлено в «myTextInput». Объект Text устанавливает свойство text, чтобы иметь такое же значение, как свойство text объекта TextInput, ссылаясь на myTextInput.text. Теперь оба элемента будут отображать один и тот же текст:

import QtQuick 2.0

Column {
    width: 200; height: 200

    TextInput { id: myTextInput; text: "Hello World" }

    Text { text: myTextInput.text }
}

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

После создания экземпляра объекта значение его атрибута id изменить нельзя. Хотя он может выглядеть как обычное свойство, атрибут id не является обычным атрибутом property, и к нему применяются специальные семантики; например, в приведенном выше примере нельзя получить доступ к myTextInput.id.

Атрибуты свойств

Свойство — это атрибут объекта, которому можно присвоить статическое значение или привязать динамическое выражение. Значение свойства можно прочитать другими объектами. Как правило, его также можно изменить другим объектом, если только определенный тип QML явно не запретил это для конкретного свойства.

Определение атрибутов свойств

Свойство можно определить для типа в C++ путем регистрации Q_PROPERTY класса, который затем регистрируется в системе типов QML. В качестве альтернативы, пользовательское свойство типа объекта можно определить в объявлении объекта в QML-документе с помощью следующего синтаксиса:

[default] property <propertyType> <propertyName>

Таким образом, объявление объекта может раскрыть определенное значение для внешних объектов или более легко поддерживать некоторое внутреннее состояние.

Имена свойств должны начинаться с буквы в нижнем регистре и могут содержать только буквы, цифры и символы подчеркивания. Зарезервированные слова JavaScript не являются допустимыми именами свойств. Ключевое слово default необязательно и изменяет семантику объявляемого свойства. Более подробную информацию об атрибуте свойства default см. в следующем разделе по умолчанию.

Объявление пользовательского свойства подразумевает создание сигнала изменения значения для этого свойства, а также связанного обработчика сигнала, называемого on<ИмяСвойства>Changed, где <ИмяСвойства> — имя свойства, с заглавной первой буквы.

Например, следующее объявление объекта определяет новый тип, который наследуется от базового типа Rectangle. Он имеет два новых свойства с реализованным обработчиком сигнала для одного из этих новых свойств:

Rectangle {
    property color previousColor
    property color nextColor
    onNextColorChanged: console.log("The next color will be: " + nextColor.toString())
}

Допустимые типы в определениях пользовательских свойств

В качестве типов пользовательских свойств можно использовать любые базовые типы QML, кроме типа перечисления. Например, все приведенные ниже являются допустимыми объявлениями свойств:

Item {
    property int someNumber
    property string someString
    property url someUrl
}

(Значения перечисления — это просто целые значения, и к ним можно обратиться с типом int.)

Некоторые базовые типы предоставляются модулем QtQuick и поэтому не могут использоваться в качестве типов свойств, если модуль не импортирован. Дополнительные сведения см. в документации по базовым типам QML.

Обратите внимание, что базовый тип var — это универсальный тип-заполнитель, который может содержать любые типы значений, включая списки и объекты:

property var someNumber: 1.5
property var someString: "abc"
property var someBool: true
property var someList: [1, 2, "three", "four"]
property var someObject: Rectangle { width: 100; height: 100; color: "red" }

Кроме того, любой тип QML-объекта может использоваться в качестве типа свойства. Например:

property Item someItem
property Rectangle someRectangle

Это относится и к пользовательским типам QML. Если тип QML был определен в файле с именем ColorfulButton.qml (в каталоге, который затем был импортирован клиентом), то свойство типа ColorfulButton также будет допустимым.

Присвоение значений атрибутам свойств

Значение свойства экземпляра объекта можно указать двумя способами:

• присвоение значения при инициализации
• императивное присвоение значения

В обоих случаях значение может быть либо статическим, либо выражением привязки.

Присвоение значения при инициализации

Синтаксис присвоения значения свойству при инициализации:

<propertyName> : <value>

При необходимости присвоение значения при инициализации можно объединить с определением свойства в объявлении объекта. В этом случае синтаксис определения свойства становится:

[default] property <propertyType> <propertyName> : <value>

Следующий пример демонстрирует инициализацию значения свойства:

import QtQuick 2.0

Rectangle {
    color: "red"
    property color nextColor: "blue" // combined property declaration and initialization
}

Императивное присвоение значения

Императивное присвоение значения — это присвоение значения свойства (статическое значение или выражение привязки) свойству из императивного кода JavaScript. Синтаксис императивного присвоения значения — это просто оператор присваивания JavaScript, как показано ниже:

[<objectId>.]<propertyName> = value

Следующий пример демонстрирует императивное присвоение значения:

import QtQuick 2.0

Rectangle {
    id: rect
    Component.onCompleted: {
        rect.color = "red"
    }
}

Статические значения и значения выражений привязки

Как уже отмечалось, существуют два вида значений, которые можно присвоить свойству: статические значения и значения выражений привязки. Последние также известны как привязки свойств.

Вот пример, в котором обоим видам значений присваиваются свойства:

import QtQuick 2.0

Rectangle {
    // both of these are static value assignments on initialization
    width: 400
    height: 200

    Rectangle {
        // both of these are binding expression value assignments on initialization
        width: parent.width / 2
        height: parent.height
    }
}

Примечание: Чтобы императивно присвоить выражение привязки, выражение привязки должно быть заключено в функцию, которая передается в Qt.binding(), а затем возвращаемое Qt.binding() значение должно быть присвоено свойству. В отличие от этого, Qt.binding() не следует использовать при присвоении выражения привязки при инициализации. Дополнительную информацию см. в разделе Привязка свойств.

Безопасность типов

Свойства безопасны с точки зрения типов. Свойству можно присвоить только значение, соответствующее типу свойства.

Например, если свойство является вещественным, и вы попытаетесь присвоить ему строку, будет выдано сообщение об ошибке:

property int volume: "four"  // generates an error; the property's object will not be loaded

Аналогично, если свойству присваивается значение неправильного типа во время выполнения, новое значение не будет присвоено, и будет сгенерировано сообщение об ошибке.

Некоторые типы свойств не имеют естественного представления значения, и в этих случаях QML-движок автоматически выполняет преобразование строки в тип значения. Таким образом, например, хотя свойства типа color хранят цвета, а не строки, вы можете присвоить строку "red" свойству цвета без сообщений об ошибках.

Список типов свойств, поддерживаемых по умолчанию, см. в разделе базовые типы QML. Кроме того, любой доступный тип QML-объекта также может использоваться в качестве типа свойства.

Специальные типы свойств

Атрибуты свойств списка объектов

Свойству типа список можно присвоить список значений QML-типа объекта. Синтаксис для определения значения списка объектов — это список значений, разделенных запятыми, заключенный в квадратные скобки:

[ <item 1>, <item 2>, ... ]

Например, тип Item имеет свойство states, которое используется для хранения списка объектов типа State. Приведенный ниже код инициализирует значение этого свойства списком из трех объектов типа State:

import QtQuick 2.0

Item {
    states: [
        State { name: "loading" },
        State { name: "running" },
        State { name: "stopped" }
    ]
}

Если список содержит один элемент, квадратные скобки можно опустить:

import QtQuick 2.0

Item {
    states: State { name: "running" }
}

Свойство типа список можно указать в объявлении объекта следующим образом:

[default] property list<<objectType>> propertyName

и, как и другие объявления свойств, инициализация свойства может быть объединена с объявлением свойства следующим образом:

[default] property list<<objectType>> propertyName: <value>

Следующий пример демонстрирует объявление свойства списка:

import QtQuick 2.0

Rectangle {
    // declaration without initialization
    property list<Rectangle> siblingRects

    // declaration with initialization
    property list<Rectangle> childRects: [
        Rectangle { color: "red" },
        Rectangle { color: "blue"}
    ]
}

Если вы хотите объявить свойство для хранения списка значений, которые не обязательно являются значениями QML-типа объекта, вместо этого следует объявить свойство var.

Сгруппированные свойства

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

Например, тип Text имеет свойство группы font. Ниже первый объект Text инициализирует свои font значения с помощью нотации точек, а второй использует нотацию групп:

Text {
    //dot notation
    font.pixelSize: 12
    font.b: true
}

Text {
    //group notation
    font { pixelSize: 12; b: true }
}

Типы свойств групп — это базовые типы, которые имеют подсвойства. Некоторые из этих базовых типов предоставляются языком QML, а другие могут использоваться только при импорте модуля Qt Quick. Дополнительную информацию см. в документации по базовым типам QML.

Псевдонимы свойств

Псевдонимы свойств — это свойства, которые хранят ссылку на другое свойство. В отличие от обычного определения свойства, которое выделяет новое, уникальное хранилище для свойства, псевдоним свойства связывает недавно объявленное свойство (называемое псевдонимизирующим свойством) как прямую ссылку на существующее свойство (свойство-оригинал).

Объявление псевдонима свойства выглядит как обычное определение свойства, за исключением того, что оно требует ключевого слова alias вместо типа свойства, а правая часть определения свойства должна быть допустимой ссылкой на псевдоним:

[default] property alias <name>: <alias reference>

В отличие от обычного свойства, у псевдонима есть следующие ограничения:

• Он может ссылаться только на объект или свойство объекта, которое находится в области видимости типа, в котором объявлен псевдоним.
• Он не может содержать произвольные выражения JavaScript.
• Он не может ссылаться на объекты, объявленные за пределами области видимости своего типа.
• Ссылка на псевдоним не является необязательной, в отличие от необязательного значения по умолчанию для обычного свойства; ссылка на псевдоним должна быть предоставлена при первом объявлении псевдонима.
• Он не может ссылаться на присоединенные свойства.
• Он не может ссылаться на свойства групп; следующий код не будет работать:

  property alias color: rectangle.border.color
  
  Rectangle {
      id: rectangle
  }

  Однако псевдонимы для свойств типа значение работают:

  property alias rectX: object.rectProperty.x
  
  Item {
      id: object
      property rect rectProperty
  }

Например, ниже представлен тип Button со свойством buttonText псевдонима, которое подключено к объекту text дочернего элемента Text:

// Button.qml
import QtQuick 2.0

Rectangle {
    property alias buttonText: textItem.text

    width: 100; height: 30; color: "yellow"

    Text { id: textItem }
}

Следующий код создаст Button со строкой текста, определённой для дочернего объекта Text:

Button { buttonText: "Click Me" }

Здесь изменение buttonText напрямую изменяет значение textItem.text; оно не изменяет какое-либо другое значение, которое затем обновляет textItem.text. Если buttonText не был псевдонимом, изменение его значения фактически не изменит отображаемый текст, так как связи свойств не двунаправленные: значение buttonText изменится, если будет изменено textItem.text, но не наоборот.

Учет псевдонимов свойств

Псевдонимы активируются только после того, как компонент был полностью инициализирован. При попытке обратиться к неинициализированному псевдониму генерируется ошибка. Аналогичным образом, псевдонимизация псевдонима свойства также приведет к ошибке.

property alias widgetLabel: label

//will generate an error
//widgetLabel.text: "Initial text"

//will generate an error
//property alias widgetLabelText: widgetLabel.text

Component.onCompleted: widgetLabel.text = "Alias completed Initialization"

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

Возможно, что псевдонимизирующее свойство будет иметь то же имя, что и существующее свойство, фактически перезаписывая существующее свойство. Например, следующий тип QML имеет свойство-псевдоним color, имеющее то же имя, что и встроенное свойство Rectangle::color:

Rectangle {
    id: coloredrectangle
    property alias color: bluerectangle.color
    color: "red"

    Rectangle {
        id: bluerectangle
        color: "#1234ff"
    }

    Component.onCompleted: {
        console.log (coloredrectangle.color)    //prints "#1234ff"
        setInternalColor()
        console.log (coloredrectangle.color)    //prints "#111111"
        coloredrectangle.color = "#884646"
        console.log (coloredrectangle.color)    //prints #884646
    }

    //internal function that has access to internal properties
    function setInternalColor() {
        color = "#111111"
    }
}

Любой объект, использующий этот тип и ссылающийся на свойство color, будет ссылаться на псевдоним, а не на обычное свойство Rectangle::color. Однако внутренне прямоугольник может правильно установить свойство color и сослаться на фактически определенное свойство, а не на псевдоним.

Свойства по умолчанию

Определение объекта может иметь единственное свойство по умолчанию. Свойство по умолчанию — это свойство, которому присваивается значение, если объект объявлен внутри определения другого объекта без объявления его как значения для конкретного свойства.

Объявление свойства с необязательным ключевым словом default помечает его как свойство по умолчанию. Например, предположим, что есть файл MyLabel.qml со свойством по умолчанию someText:

// MyLabel.qml
import QtQuick 2.0

Text {
    default property var someText

    text: "Hello, " + someText.text
}

Значение someText можно присвоить в определении объекта MyLabel следующим образом:

MyLabel {
    Text { text: "world!" }
}

Это имеет точно такой же эффект, как и следующее:

MyLabel {
    someText: Text { text: "world!" }
}

Однако, так как свойство someText помечено как свойство по умолчанию, нет необходимости явно назначать объект Text этому свойству.

Вы заметите, что дочерние объекты могут быть добавлены к любому типу на основе Item без явного добавления их в свойство children. Это происходит потому, что свойство по умолчанию для Item — это свойство data , и любые элементы, добавленные в этот список для Item, автоматически добавляются в список его children.

Свойства по умолчанию могут быть полезны для повторного назначения дочерних элементов элемента. См. Пример TabWidget, который использует свойство по умолчанию для автоматического повторного назначения дочерних элементов TabWidget в качестве дочерних элементов внутреннего ListView. См. также Расширение QML.

Только для чтения свойства

Объявление объекта может определить свойство только для чтения, используя ключевое слово readonly со следующим синтаксисом:

readonly property <propertyType> <propertyName> : <initialValue>

Свойствам только для чтения необходимо присвоить значение при инициализации. После инициализации свойства только для чтения его больше нельзя присвоить значение, ни из императивного кода, ни каким-либо другим способом.

Например, код в блоке Component.onCompleted ниже недопустим:

Item {
    readonly property int someNumber: 10

    Component.onCompleted: someNumber = 20  // doesn't work, causes an error
}

Примечание: Свойство только для чтения не может также быть свойством по умолчанию.

Объекты-модификаторы свойств

К свойствам могут быть привязаны объекты-модификаторы значений свойств. Синтаксис объявления экземпляра типа модификатора свойства, связанного с определенным свойством, следующий:

<PropertyModifierTypeName> on <propertyName> {
    // attributes of the object instance
}

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

Некоторые типы модификаторов свойств могут применяться только к определенным типам свойств, однако это не проверяется языком. Например, тип NumberAnimation, предоставляемый QtQuick , будет анимировать только свойства числового типа (например, int или real). Попытка использовать NumberAnimation со свойством нечислового типа не приведет к ошибке, однако свойство нечислового типа не будет анимироваться. Поведение типа модификатора свойства при привязке к определенному типу свойства определяется его реализацией.

Атрибуты сигналов

Сигнал — это уведомление от объекта о том, что произошло какое-либо событие: например, свойство изменилось, анимация началась или остановилась, или изображение было загружено. Тип MouseArea, например, имеет сигнал clicked, который излучается при нажатии пользователем внутри области мыши.

Объект может получать уведомления через обработчик сигнала всякий раз, когда излучается определенный сигнал. Обработчик сигнала объявляется с синтаксисом on<Signal>, где <Signal> — это имя сигнала, первая буква которого заглавная. Обработчик сигнала должен быть объявлен внутри определения объекта, который излучает сигнал, и обработчик должен содержать блок кода JavaScript, который должен быть выполнен при вызове обработчика сигнала.

Например, обработчик сигнала onClicked ниже объявлен внутри объекта MouseArea и вызывается при нажатии на MouseArea, вызывая вывод сообщения в консоль:

import QtQuick 2.0

Item {
    width: 100; height: 100

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

Определение атрибутов сигналов

Сигнал может быть определен для типа в C++ путем регистрации Q_SIGNAL класса, который затем регистрируется в системе QML. Кроме того, пользовательский сигнал для типа объекта может быть определен в объявлении объекта в документе QML с использованием следующего синтаксиса:

signal <signalName>[([<type> <parameter name>[, ...]])]

Попытка объявить два сигнала или метода с одинаковым именем в одном блоке типа является ошибкой. Однако новый сигнал может повторно использовать имя существующего сигнала в типе. (Это следует делать с осторожностью, так как существующий сигнал может быть скрыт и стать недоступным.)

Вот три примера объявлений сигналов:

import QtQuick 2.0

Item {
    signal clicked
    signal hovered()
    signal actionPerformed(string action, var actionResult)
}

Если сигнал не имеет параметров, скобки «()» являются необязательными. Если используются параметры, типы параметров должны быть объявлены, как и для аргументов string и var для сигнала actionPerformed выше. Допустимые типы параметров совпадают с теми, которые перечислены в разделе Определение атрибутов свойств на этой странице.

Для излучения сигнала вызовите его как метод. Все соответствующие обработчики сигналов будут вызваны при излучении сигнала, и обработчики могут использовать определенные имена аргументов сигнала для доступа к соответствующим аргументам.

Сигналы изменения свойств

Типы QML также предоставляют встроенные сигналы изменения свойств, которые излучаются всякий раз, когда изменяется значение свойства, как описано ранее в разделе атрибуты свойств. См. предстоящий раздел обработчики сигналов изменения свойств для получения дополнительной информации о том, почему эти сигналы полезны, и о том, как их использовать.

Атрибуты обработчиков сигналов

Обработчики сигналов — это особый вид атрибута метода, где реализация метода вызывается движком QML всякий раз, когда излучается связанный сигнал. Добавление сигнала в определение объекта в QML автоматически добавляет связанный обработчик сигнала в определение объекта, который по умолчанию имеет пустую реализацию. Клиенты могут предоставить реализацию для реализации логики программы.

Рассмотрим следующий тип SquareButton , определение которого представлено в файле SquareButton.qml следующим образом, с сигналами activated и deactivated:

// SquareButton.qml
Rectangle {
    id: root

    signal activated(real xPosition, real yPosition)
    signal deactivated

    property int side: 100
    width: side; height: side

    MouseArea {
        anchors.fill: parent
        onPressed: root.activated(mouse.x, mouse.y)
        onReleased: root.deactivated()
    }
}

Эти сигналы могут быть получены любыми SquareButton объектами в другом файле QML в той же директории, где обработчики сигналов реализуются клиентом:

// myapplication.qml
SquareButton {
    onActivated: console.log("Activated at " + xPosition + "," + yPosition)
    onDeactivated: console.log("Deactivated!")
}

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

Обработчики сигналов изменения свойств

Обработчики сигналов изменения свойств имеют синтаксическую форму on<Свойство>Изменено, где <Свойство> — это имя свойства, первая буква которого заглавная. Например, хотя в документации типа TextInput не документируется textChanged сигнал, этот сигнал неявно доступен из-за наличия у TextInput свойства text, поэтому можно написать обработчик onTextChanged сигнала, который вызывается всякий раз, когда это свойство изменяется:

import QtQuick 2.0

TextInput {
    text: "Change this!"

    onTextChanged: console.log("Text has changed to:", text)
}

Атрибуты методов

Метод типа объекта — это функция, которую можно вызвать для выполнения некоторой обработки или для запуска дополнительных событий. Метод может быть подключен к сигналу, чтобы он автоматически вызывался всякий раз, когда испускается сигнал. См. Системы событий сигналов и обработчиков для получения дополнительной информации.

Определение атрибутов методов

Метод можно определить для типа в C++ путём добавления тега к функции класса, которая затем регистрируется в системе типов QML с помощью Q_INVOKABLE, или зарегистрировать её как Q_SLOT класса. Кроме того, пользовательский метод можно добавить к объявлению объекта в документе QML следующим образом:

function <functionName>([<parameterName>[, ...]]) { <body> }

Методы могут быть добавлены к типу QML для определения автономных, многократно используемых блоков кода JavaScript. Эти методы могут вызываться как внутренними, так и внешними объектами.

В отличие от сигналов, типы параметров методов не нужно объявлять, так как они по умолчанию имеют тип var.

Попытка объявить два метода или сигнала с одинаковым именем в одном блоке типа является ошибкой. Тем не менее, новый метод может повторно использовать имя существующего метода в типе. (Это следует делать с осторожностью, так как существующий метод может быть скрыт и стать недоступным.)

Ниже приведён Прямоугольник с методом calculateHeight(), который вызывается при присвоении значения height:

import QtQuick 2.0
Rectangle {
    id: rect

    function calculateHeight() {
        return rect.width / 2;
    }

    width: 100
    height: calculateHeight()
}

Если метод имеет параметры, они доступны по имени внутри метода. Ниже, когда Область мыши щелкается, вызывается метод moveTo(), который затем может использовать полученные параметры newX и newY для перемещения текста:

import QtQuick 2.0

Item {
    width: 200; height: 200

    MouseArea {
        anchors.fill: parent
        onClicked: label.moveTo(mouse.x, mouse.y)
    }

    Text {
        id: label

        function moveTo(newX, newY) {
            label.x = newX;
            label.y = newY;
        }

        text: "Move me!"
    }
}

Присоединенные свойства и обработчики присоединенных сигналов

Присоединенные свойства и обработчики присоединенных сигналов — это механизмы, которые позволяют добавлять к объектам дополнительные свойства или обработчики сигналов, которые в противном случае недоступны для объекта. В частности, они позволяют объектам получать доступ к свойствам или сигналам, которые конкретно относятся к данному объекту.

Реализация типа QML может выбрать создание типа присоединения в C++ с определенными свойствами и сигналами. Экземпляры этого типа могут затем создаваться и присоединяться к определённым объектам во время выполнения, что позволяет этим объектам получать доступ к свойствам и сигналам типа присоединения. К ним обращаются путём добавления имени типа присоединения перед свойствами и соответствующими обработчиками сигналов.

Ссылки на присоединённые свойства и обработчики имеют следующую синтаксическую форму:

<AttachingType>.<propertyName>
<AttachingType>.on<SignalName>

Например, тип Список имеет присоединённое свойство ListView.isCurrentItem, которое доступно каждому объекту делегата в Списке. Это можно использовать каждому отдельному объекту делегата, чтобы определить, является ли он в данный момент выделенным элементом в представлении:

import QtQuick 2.0

ListView {
    width: 240; height: 320
    model: 3
    delegate: Rectangle {
        width: 100; height: 30
        color: ListView.isCurrentItem ? "red" : "yellow"
    }
}

В этом случае имя типа присоединения — ListView, а интересующее нас свойство — isCurrentItem, поэтому присоединённое свойство обозначается как ListView.isCurrentItem.

Присоединённый обработчик сигнала обозначается аналогичным образом. Например, присоединённый обработчик сигнала Component.onCompleted обычно используется для выполнения некоторого JavaScript-кода, когда процесс создания компонента завершён. В примере ниже, как только Модель списка будет полностью создана, её обработчик сигнала Component.onCompleted будет автоматически вызван для заполнения модели:

import QtQuick 2.0

ListView {
    width: 240; height: 320
    model: ListModel {
        id: listModel
        Component.onCompleted: {
            for (var i = 0; i < 10; i++)
                listModel.append({"Name": "Item " + i})
        }
    }
    delegate: Text { text: index }
}

Поскольку имя типа присоединения — Component, и этот тип имеет сигнал completed, присоединённый обработчик сигнала обозначается как Component.onCompleted.

Примечание об обращении к присоединённым свойствам и обработчикам сигналов

Частая ошибка заключается в предположении, что к присоединённым свойствам и обработчикам сигналов можно напрямую получить доступ из дочерних элементов объекта, к которому эти атрибуты присоединены. Это не так. Экземпляр типа присоединения прикреплён только к определённым объектам, а не к объекту и всем его дочерним элементам.

Например, ниже приведён изменённый вариант предыдущего примера, связанного с присоединёнными свойствами. На этот раз делегат — Элемент, а цветной Прямоугольник — его дочерний элемент:

import QtQuick 2.0

ListView {
    width: 240; height: 320
    model: 3
    delegate: Item {
        width: 100; height: 30

        Rectangle {
            width: 100; height: 30
            color: ListView.isCurrentItem ? "red" : "yellow"    // WRONG! This won't work.
        }
    }
}

Это не работает как ожидается, потому что ListView.isCurrentItem присоединён только к корневому объекту делегата, а не к его дочерним элементам. Поскольку Прямоугольник является дочерним элементом делегата, а не самим делегатом, он не может получить доступ к присоединённому свойству isCurrentItem как ListView.isCurrentItem. Поэтому вместо этого прямоугольник должен получить доступ к isCurrentItem через корневой делегат:

ListView {
    //....
    delegate: Item {
        id: delegateItem
        width: 100; height: 30

        Rectangle {
            width: 100; height: 30
            color: delegateItem.ListView.isCurrentItem ? "red" : "yellow"   // correct
        }
    }
}

Теперь delegateItem.ListView.isCurrentItem правильно ссылается на присоединённое свойство isCurrentItem делегата.

Атрибуты перечислений

Перечисления предоставляют фиксированный набор именованных выборов. Их можно объявлять в QML, используя ключевое слово enum:

// MyText.qml
Text {
    enum TextType {
        Normal,
        Heading
    }
}

Как показано выше, типы перечислений (например, TextType) и значения (например, Normal) должны начинаться с заглавной буквы.

К значениям обращаются с помощью <Type>.<EnumerationType>.<Value> или <Type>.<Value>.

// MyText.qml
Text {
    enum TextType {
        Normal,
        Heading
    }

    property int textType: MyText.TextType.Normal

    font.bold: textType == MyText.TextType.Heading
    font.pixelSize: textType == MyText.TextType.Heading ? 24 : 12
}

Дополнительную информацию об использовании перечислений в QML можно найти в документации по QML базовым типам перечислению.

Возможность объявлять перечисления в QML была добавлена в Qt 5.10.