Тип QML Item

Базовый визуальный тип QML. Подробнее...

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

Свойства

• активныйФокус : bool
• активныйФокусНаТабе : bool
• якоря
  • якоря.выравниваниеПриЦентрировании : bool
  • якоря.линияОснования : AnchorLine
  • якоря.смещениеЛинииОснования : real
  • якоря.низ : AnchorLine
  • якоря.отступВниз : real
  • якоря.центрироватьВ : Item
  • якоря.заполнить : Item
  • якоря.горизонтальныйЦентр : AnchorLine
  • якоря.смещениеГоризонтальногоЦентра : real
  • якоря.левый : AnchorLine
  • якоря.отступСлева : real
  • якоря.отступы : real
  • якоря.правый : AnchorLine
  • якоря.отступСправа : real
  • якоря.верхний : AnchorLine
  • якоря.отступСверху : real
  • якоря.вертикальныйЦентр : AnchorLine
  • якоря.смещениеВертикальногоЦентра : real
• антиалиасинг : bool
• смещениеЛинииОснования : int
• дети : list<Item>
• прямоугольникПотомков
  • прямоугольникПотомков.высота : real
  • прямоугольникПотомков.ширина : real
  • прямоугольникПотомков.x : real
  • прямоугольникПотомков.y : real
• обрезка : bool
• маскаСодержимого : QObject*
• данные : list<Object>
• включен : bool
• фокус : bool
• высота : real
• неявнаяВысота : real
• неявнаяШирина : real
• слой.эффект : Component
• слой.включен : bool
• слой.формат : перечисление
• слой.mipКарта : bool
• слой.имяОбразца : строка
• слой.сэмплы : перечисление
• слой.плавный : bool
• слой.областьИсточника : прямоугольник
• слой.зеркалированиеТекстуры : перечисление
• слой.размерТекстуры : размер
• слой.режимОбрезки : перечисление
• прозрачность : real
• палитра : Палитра
• родитель : Item
• ресурсы : list<Object>
• вращение : real
• масштаб : real

• smooth : bool
• состояние : string
• состояния : list<State>
• преобразование : list<Transform>
• transformOrigin : enumeration
• переходы : list<Transition>
• видимость : bool
• видимыеДочерниеЭлементы : list<Item>
• ширина : real
• x : real
• y : real
• z : real

Методы

• childAt(real x, real y)
• bool содержит(point point)
• forceActiveFocus(Qt::FocusReason reason)
• forceActiveFocus()
• bool grabToImage(callback, targetSize)
• object mapFromGlobal(real x, real y)
• object mapFromItem(Item item, rect r)
• object mapFromItem(Item item, real x, real y, real width, real height)
• object mapFromItem(Item item, real x, real y)
• object mapFromItem(Item item, point p)
• object mapToGlobal(real x, real y)
• object mapToItem(Item item, rect r)
• object mapToItem(Item item, real x, real y, real width, real height)
• object mapToItem(Item item, real x, real y)
• object mapToItem(Item item, point p)
• nextItemInFocusChain(bool forward)

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

Тип Item — базовый тип для всех визуальных элементов в Qt Quick.

Все визуальные элементы в Qt Quick наследуются от Item. Хотя объект Item не имеет визуального представления, он определяет все атрибуты, общие для визуальных элементов, такие как положение x и y, ширина и высота, привязка и поддержка обработки нажатий клавиш.

Тип Item может быть полезен для группировки нескольких элементов под одним корневым визуальным элементом. Например:

import QtQuick 2.0

Item {
    Image {
        source: "tile.png"
    }
    Image {
        x: 80
        width: 100
        height: 100
        source: "tile.png"
    }
    Image {
        x: 190
        width: 100
        height: 100
        fillMode: Image.Tile
        source: "tile.png"
    }
}

Обработка событий

Все визуальные типы, основанные на Item, могут использовать Обработчики ввода, чтобы обрабатывать входящие события ввода (подклассы QInputEvent), такие как события мыши, касания и клавиш. Это предпочтительный декларативный способ обработки событий.

Альтернативный способ обработки событий касания — создание подкласса QQuickItem, вызов setAcceptTouchEvents() в конструкторе и переопределение touchEvent(). Примите всё событие, чтобы остановить передачу подлежащим элементам, и чтобы исключительно захватить все точки касания события. Используйте QPointerEvent::setExclusiveGrabber(), чтобы захватить только определённые точки касания и позволить передачу события дальше.

Аналогично, подкласс QQuickItem может вызвать setAcceptedMouseButtons(), чтобы зарегистрироваться для получения событий кнопок мыши, setAcceptHoverEvents(), чтобы получить события наведения (движения мыши, когда ни одна кнопка не нажата), и переопределить виртуальные функции mousePressEvent(), mouseMoveEvent() и mouseReleaseEvent(). Эти функции также могут принять событие, чтобы предотвратить дальнейшую передачу и получить неявный захват одновременно; или явно захватить единственную QEventPoint, которую несет QMouseEvent.

Обработка клавиш доступна для всех визуальных типов, основанных на Item, через свойство Keys присоединенное свойство. Присоединённое свойство Keys предоставляет базовые сигналы, такие как pressed и released, а также сигналы для определённых клавиш, таких как spacePressed. В примере ниже задаётся фокус клавиатуры для элемента и обрабатывается левая клавиша через общий onPressed обработчик, а клавиша возврата — через onReturnPressed обработчик:

import QtQuick 2.0

Item {
    focus: true
    Keys.onPressed: (event)=> {
        if (event.key == Qt.Key_Left) {
            console.log("move left");
            event.accepted = true;
        }
    }
    Keys.onReturnPressed: console.log("Pressed return");
}

Подробная документация представлена в присоединённом свойстве Keys.

Зеркальное отображение макета

Макеты элементов можно зеркально отображать с помощью присоединённого свойства LayoutMirroring. Это приводит к горизонтальному отражению якорей, а также к изменению направления макетов элементов, выстраивающих или позиционирующих своих потомков (например, ListView или Row).

Дополнительная информация представлена в разделе LayoutMirroring.

Слои элементов

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

Если требуется размер текстуры, отличный от размера элемента, это можно сделать с помощью layer.textureSize. Для отображения только части элемента в текстуре используйте layer.sourceRect. Также можно задать layer.sourceRect так, чтобы она выходила за пределы элемента. В этом случае внешняя часть будет заполнена прозрачными пикселями.

Элемент будет использовать линейную интерполяцию для масштабирования, если layer.smooth установлено в true и будет использовать mipmap для уменьшения масштаба, если layer.mipmap установлено в true. Использование mipmap может улучшить качество изображения уменьшенных элементов. Для mipmap отдельных элементов Image используйте Image::mipmap.

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

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

Непрозрачность без слоя Item { id: nonLayered opacity: 0.5 width: 100 height: 100 Rectangle { width: 80; height: 80; border.width: 1 } Rectangle { x: 20; y: 20; width: 80; height: 80; border.width: 1 } }

Слой отображается с непрозрачностью корневого элемента, равной 1, а затем непрозрачность корневого элемента применяется к текстуре при её отображении. Это означает, что затухание большой иерархии элементов от прозрачного до непрозрачного состояния или наоборот может быть выполнено без артефактов перекрытия, которые существуют при обычном смешивании альфа-каналов элементов. Вот тот же пример с включённым слоем:

Item {
    id: layered

    opacity: 0.5

    layer.enabled: true

    width: 100
    height: 100

    Rectangle { width: 80; height: 80; border.width: 1 }
    Rectangle { x: 20; y: 20; width: 80; height: 80; border.width: 1 }
}

В сочетании с эффектами Shader

Установка layer.enabled в значение true преобразует элемент в поставщика текстур, что позволяет использовать элемент непосредственно как текстуру, например, в сочетании с типом ShaderEffect.

Можно применить эффект к слою во время выполнения, используя layer.effect:

Item {
    id: layerRoot
    layer.enabled = true
    layer.effect: ShaderEffect {
        fragmentShader: "effect.frag.qsb"
    }
}

Дополнительная информация о применении эффектов представлена в разделе ShaderEffect.

Примечание: layer.enabled — это на самом деле просто более удобный способ использования ShaderEffectSource.

Память и производительность

При включении слоя элемента в графическом процессоре будет выделена память, равная width x height x 4. В конфигурациях с ограниченным объемом памяти следует с осторожностью использовать большие слои.

В мире QPainter / QWidget иногда выгодно кэшировать сложное содержимое в pixmap, изображении или текстуре. В Qt Quick, благодаря методам, уже используемым рендерером графического сцены, в большинстве случаев это не требуется. Избыточные вызовы отрисовки уже сокращены благодаря объединению и кэшированию, и в большинстве случаев кэш в итоге будет смешивать больше пикселей, чем исходное содержимое. Надстройка, связанная с отрисовкой на отдельном экране и смешиванием полученной текстуры, часто является более затратной, чем просто позволение элементу и его потомкам отображаться в обычном режиме.

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

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

Документация свойств

Определяет естественную ширину или высоту элемента, если не указаны свойства width или height.

По умолчанию неявный размер большинства элементов равен 0x0, однако некоторые элементы имеют собственный неявный размер, который нельзя переопределить, например, Image и Text.

Указание неявного размера полезно для определения компонентов, которые имеют предпочтительный размер, основанный на их содержимом, например:

// Label.qml
import QtQuick 2.0

Item {
    property alias icon: image.source
    property alias label: text.text
    implicitWidth: text.implicitWidth + image.implicitWidth
    implicitHeight: Math.max(text.implicitHeight, image.implicitHeight)
    Image { id: image }
    Text {
        id: text
        wrapMode: Text.Wrap
        anchors.left: image.right; anchors.right: parent.right
        anchors.verticalCenter: parent.verticalCenter
    }
}

Примечание: Использование implicitWidth элементов Text или TextEdit и явное задание ширины влечёт за собой снижение производительности, так как текст должен быть выведен дважды.

Определяет положение и размер элемента. Значение по умолчанию равно 0.

Положение (x, y) относительно родительского элемента parent.

Item { x: 100; y: 100; width: 100; height: 100 }

Свойство children содержит список визуальных дочерних элементов этого элемента. Свойство resources содержит невизуальные ресурсы, которые вы хотите ссылаться по имени.

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

activeFocus : bool

Это только для чтения свойство указывает, имеет ли элемент активный фокус.

Если activeFocus равно true, то либо этот элемент в данный момент получает ввод с клавиатуры, либо это FocusScope предок элемента, который в данный момент получает ввод с клавиатуры.

Обычно активный фокус приобретается путём установки свойства focus на элементе и его содержащих объектах FocusScope. В следующем примере объекты input и focusScope будут иметь активный фокус, в то время как корневой прямоугольный объект — нет.

import QtQuick 2.0

Rectangle {
    width: 100; height: 100

    FocusScope {
        id: focusScope
        focus: true

        TextInput {
            id: input
            focus: true
        }
    }
}

См. также focus и Фокус клавиатуры в Qt Quick.

activeFocusOnTab : bool

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

Цепочка фокуса переходов по табуляции проходит через элементы, сначала посещая родительский элемент, а затем его дочерние элементы в порядке их появления в свойстве children. Нажатие клавиши табуляции на элементе в цепочке фокуса переходов по табуляции переместит фокус клавиатуры на следующий элемент в цепочке. Нажатие клавиши BackTab (обычно Shift+Tab) переместит фокус на предыдущий элемент.

Чтобы настроить цепочку фокуса переходов по табуляции вручную, см. KeyNavigation. События клавиши Tab, используемые Keys или KeyNavigation, имеют приоритет над поведением цепочки фокуса; игнорируйте события в других обработчиках клавиш, чтобы позволить им распространяться.

anchors.alignWhenCentered : bool

Якоря предоставляют способ позиционирования элемента, определяя его отношение к другим элементам.

Отступы применяются к якорям top, bottom, left, right и fill. Свойство anchors.margins может быть использовано для установки всех различных отступов сразу, к одному значению. Оно не переопределит конкретный отступ, который был установлен ранее; чтобы очистить явным образом установленный отступ, установите его значение в undefined. Обратите внимание, что отступы специфичны для якоря и не применяются, если элемент не использует якоря.

Смещения применяются к горизонтальным, вертикальным центрам и якорям baseline.

Item {
    Image {
        id: pic
        // ...
    }
    Text {
        id: label
        anchors.horizontalCenter: pic.horizontalCenter
        anchors.top: pic.bottom
        anchors.topMargin: 5
        // ...
    }
}

Item {
    Image {
        id: pic
        // ...
    }
    Text {
        id: label
        anchors.left: pic.right
        anchors.leftMargin: 5
        // ...
    }
}

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

Чтобы очистить значение якоря, установите его в undefined.

anchors.alignWhenCentered (значение по умолчанию true) принудительно выравнивает центрированные якоря к целому пикселю; если элемент, который центрируется, имеет нечётную ширину или высоту, элемент будет позиционирован на целочисленных координатах, а не на полуцелых. Это гарантирует чёткую отрисовку элемента. В некоторых случаях это нежелательно, например, при вращении элемента могут быть заметны рывки, поскольку центр округляется.

Примечание: Вы можете привязать элемент только к своим соседям или родителю.

Дополнительную информацию см. в разделе Макеты с якорями.

antialiasing : bool

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

Значение по умолчанию — false, но может быть переопределено производными элементами.

baselineOffset : int

Определяет положение базовой линии элемента в локальных координатах.

Базовая линия элемента Text — это воображаемая линия, на которой располагается текст. Элементы управления, содержащие текст, обычно устанавливают свою базовую линию на базовую линию своего текста.

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

[только для чтения] childrenRect.height : real

Это свойство только для чтения, содержащее коллективные положение и размеры дочерних элементов элемента.

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

Возвращаемая геометрия локальна для элемента. Например:

Item {
    x: 50
    y: 100

    // prints: QRectF(-10, -20, 30, 40)
    Component.onCompleted: print(childrenRect)

    Item {
        x: -10
        y: -20
        width: 30
        height: 40
    }
}

clip : bool

Это свойство указывает, включено ли обрезка. Значение обрезки по умолчанию — false.

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

[с версии 5.11] containmentMask : QObject*

Это свойство содержит необязательную маску для элемента, используемую в методе QtQuick::Item::contains. Основное назначение QtQuick::Item::contains — определить, попал ли введённый элемент в элемент или нет.

По умолчанию метод contains возвращает true для любой точки внутри ограничивающей области элемента. containmentMask позволяет более точно управлять этим. Например, разработчик может определить и использовать элемент AnotherItem в качестве containmentMask, который имеет специализированный метод contains, например:

Item { id: item; containmentMask: AnotherItem { id: anotherItem } }

Метод contains элемента item вернёт true только если реализация метода contains элемента anotherItem вернёт true.

Это свойство было введено в Qt 5.11.

[значение по умолчанию] data : list<Object>

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

Таким образом, вы можете написать:

Item {
    Text {}
    Rectangle {}
    Timer {}
}

вместо:

Item {
    children: [
        Text {},
        Rectangle {}
    ]
    resources: [
        Timer {}
    ]
}

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

enabled : bool

Это свойство определяет, получает ли элемент события мыши и клавиатуры. По умолчанию это true.

Прямое изменение этого свойства влияет на значение enabled дочерних элементов. При установке в false, значения enabled всех дочерних элементов также становятся false. При установке в true, значения enabled дочерних элементов возвращаются к true, если они явно не были установлены в false.

Установка этого свойства в false автоматически приводит к установке activeFocus в false, и этот элемент больше не будет получать события клавиатуры.

См. также visible.

focus : bool

Это свойство определяет, имеет ли элемент фокус в рамках содержащего FocusScope. Если true, этот элемент получит активный фокус, когда содержащий FocusScope получит активный фокус.

В следующем примере input получит активный фокус, когда scope получит активный фокус:

import QtQuick 2.0

Rectangle {
    width: 100; height: 100

    FocusScope {
        id: scope

        TextInput {
            id: input
            focus: true
        }
    }
}

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

Rectangle {
    width: 100; height: 100

    TextInput {
          id: input
          focus: true
    }
}

См. также activeFocus и Фокус клавиатуры в Qt Quick.

layer.effect : Component

Содержит эффект, применяемый к данному слою.

Эффект, как правило, является компонентом ShaderEffect, хотя может быть назначен любой компонент Item. Эффект должен иметь свойство текстуры-источника с именем, соответствующим layer.samplerName.

См. также layer.samplerName и Слои элементов.

layer.enabled : bool

Указывает, является ли элемент слоистым. Слоирование по умолчанию отключено.

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

Ни одно из других свойств слоя не оказывает никакого влияния, когда слоирование отключено.

См. также Слои элементов.

layer.format : перечисление

Это свойство определяет внутренний формат текстуры. Изменение этого свойства имеет смысл, когда также указан layer.effect. В зависимости от реализации OpenGL, это свойство может позволить вам сэкономить память текстуры.

• ShaderEffectSource.Alpha - GL_ALPHA;
• ShaderEffectSource.RGB - GL_RGB
• ShaderEffectSource.RGBA - GL_RGBA

Примечание: ShaderEffectSource.RGB и ShaderEffectSource.Alpha следует использовать с осторожностью, так как поддержка этих форматов в базовом оборудовании и драйвере часто отсутствует.

См. также Слои элементов.

layer.mipmap : bool

Если это свойство равно true, для текстуры генерируются mip-уровни.

Примечание: Некоторые реализации OpenGL ES 2 не поддерживают mip-уровни для текстур, не являющихся степенями двойки.

См. также Слои элементов.

layer.samplerName : строка

Содержит имя свойства текстуры-источника эффекта.

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

См. также layer.effect, ShaderEffect и Слои элементов.

[since 5.10] layer.samples : перечисление

Это свойство позволяет запросить многообразное рендеринг в слое.

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

Установив значение в 2, 4 и т.д., можно запросить многообразный рендеринг для части сцены без включения многообразного рендеринга для всей сцены. Таким образом, многообразное рендеринг применяется только к данному поддереву, что может привести к существенным приростам производительности, так как многообразное рендеринг не применяется к другим частям сцены.

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

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

Это свойство было введено в Qt 5.10.

layer.smooth : bool

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

По умолчанию это свойство установлено в false.

См. также Слои элементов.

layer.sourceRect : прямоугольник

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

См. также Слои элементов.

[since 5.6] layer.textureMirroring : перечисление

Это свойство определяет, как должна быть зеркально отображена сгенерированная текстура. Значение по умолчанию — ShaderEffectSource.MirrorVertically. Пользовательская зеркализация может быть полезна, если сгенерированная текстура непосредственно используется пользовательскими шейдерами, такими как те, что определены в ShaderEffect. Если для элемента слоя не указан эффект, зеркалирование не повлияет на визуальное представление элемента.

• ShaderEffectSource.NoMirroring - Отсутствие зеркалирования
• ShaderEffectSource.MirrorHorizontally - Сгенерированная текстура перевернута по оси X.
• ShaderEffectSource.MirrorVertically - Сгенерированная текстура перевернута по оси Y.

Это свойство было введено в Qt 5.6.

layer.textureSize : размер

Это свойство содержит запрашиваемый размер текстуры слоя в пикселях. Если оно пустое (значение по умолчанию), используется размер элемента.

Примечание: Некоторые платформы имеют ограничение на минимальный размер буферов фреймов, что означает, что фактический размер текстуры может быть больше, чем запрашиваемый размер.

См. также Слои элементов.

layer.wrapMode : перечисление

Это свойство определяет режимы обрезки, связанные с текстурой. Изменение этого свойства наиболее разумно, когда указан layer.effect.

• ShaderEffectSource.ClampToEdge - GL_CLAMP_TO_EDGE как по горизонтали, так и по вертикали
• ShaderEffectSource.RepeatHorizontally - GL_REPEAT по горизонтали, GL_CLAMP_TO_EDGE по вертикали
• ShaderEffectSource.RepeatVertically - GL_CLAMP_TO_EDGE по горизонтали, GL_REPEAT по вертикали
• ShaderEffectSource.Repeat - GL_REPEAT как по горизонтали, так и по вертикали

Примечание: Некоторые реализации OpenGL ES 2 не поддерживают режим GL_REPEAT для текстур, не являющихся степенью двойки.

См. также Слои элементов.

opacity : вещественное

Это свойство содержит непрозрачность элемента. Непрозрачность задаётся числом от 0,0 (полностью прозрачный) до 1,0 (полностью непрозрачный). Значение по умолчанию — 1,0.

При установке этого свойства указанная непрозрачность также применяется индивидуально к дочерним элементам. В некоторых случаях это может иметь непредвиденные последствия. Например, во втором наборе прямоугольников ниже, красный прямоугольник задаёт непрозрачность 0,5, что влияет на непрозрачность его синего дочернего прямоугольника, даже если у дочернего элемента не задана непрозрачность.

Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
        Rectangle {
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}

Item {
    Rectangle {
        opacity: 0.5
        color: "red"
        width: 100; height: 100
        Rectangle {
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}

Изменение непрозрачности элемента не влияет на получение им событий пользовательского ввода. (В отличие от этого, установка свойства visible в false блокирует события мыши, а установка свойства enabled в false блокирует события мыши и клавиатуры, а также снимает активный фокус с элемента.)

См. также visible.

[since 6.0] palette : Palette

Это свойство содержит палитру, текущую для элемента.

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

Палитра по умолчанию зависит от системной среды. ApplicationWindow поддерживает системную/темовую палитру, которая служит значением по умолчанию для всех элементов управления. Также могут быть специальные палитры по умолчанию для определённых типов элементов управления. Вы можете установить палитру по умолчанию для элементов управления, либо:

• передав пользовательскую палитру в QGuiApplication::setPalette() перед загрузкой любого QML; или
• указав цвета в файле qtquickcontrols2.conf.

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

Item {
    palette {
        buttonText: "maroon"
        button: "lavender"
    }

    Button {
        text: "Click Me"
    }
}

Это свойство было введено в Qt 6.0.

См. также Window::palette, Popup::palette, ColorGroup и Palette.

родитель : Элемент

Это свойство содержит визуального родителя элемента.

Примечание: Понятие визуального родителя отличается от понятия родителя QObject. Визуальный родитель элемента необязательно совпадает с его родительским объектом. Подробнее см. Концепции — Визуальный родитель в Qt Quick.

поворот : вещественное

Это свойство содержит угол поворота элемента в градусах по часовой стрелке вокруг его transformOrigin.

Значение по умолчанию — 0 градусов (без поворота).

Rectangle {
    color: "blue"
    width: 100; height: 100
    Rectangle {
        color: "red"
        x: 25; y: 25; width: 50; height: 50
        rotation: 30
    }
}

См. также Преобразование и Поворот.

масштаб : вещественное

Это свойство содержит коэффициент масштабирования для этого элемента.

Масштаб меньше 1.0 приводит к отображению элемента в меньшем размере, а масштаб больше 1.0 — в большем. Отрицательный масштаб приводит к зеркальному отображению элемента.

Значение по умолчанию — 1.0.

Масштабирование применяется от transformOrigin.

import QtQuick 2.0

Rectangle {
    color: "blue"
    width: 100; height: 100

    Rectangle {
        color: "green"
        width: 25; height: 25
    }

    Rectangle {
        color: "red"
        x: 25; y: 25; width: 50; height: 50
        scale: 1.4
        transformOrigin: Item.TopLeft
    }
}

См. также Преобразование и Масштабирование.

плавное : логическое

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

В Qt Quick 2.0 это свойство оказывает минимальное влияние на производительность.

По умолчанию это свойство установлено в true.

состояние : строка

Это свойство содержит имя текущего состояния элемента.

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

См. также Состояния в Qt Quick.

состояния : список<Состояние>

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

Это свойство задается как список объектов Состояние. Например, ниже представлен элемент со состояниями "red_color" и "blue_color":

import QtQuick 2.0

Rectangle {
    id: root
    width: 100; height: 100

    states: [
        State {
            name: "red_color"
            PropertyChanges { target: root; color: "red" }
        },
        State {
            name: "blue_color"
            PropertyChanges { target: root; color: "blue" }
        }
    ]
}

Подробнее о работе со состояниями и переходами см. Состояния в Qt Quick и Анимация и переходы в Qt Quick.

См. также переходы.

преобразование : список<Преобразование>

Это свойство содержит список преобразований для применения.

Дополнительную информацию см. в Преобразовании.

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

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

Доступны девять начал преобразования, показанные на изображении ниже. По умолчанию начало преобразования — Item.Center.

В этом примере изображение поворачивается вокруг нижнего правого угла.

Image {
    source: "myimage.png"
    transformOrigin: Item.BottomRight
    rotation: 45
}

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

переходы : список<Переход>

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

Это свойство задается как список объектов Переход. Например:

import QtQuick 2.0

Item {
    transitions: [
        Transition {
            //...
        },
        Transition {
            //...
        }
    ]
}

Подробнее о работе со состояниями и переходами см. Состояния в Qt Quick и Анимация и переходы в Qt Quick.

См. также состояния.

visible : bool

Это свойство определяет, является ли элемент видимым. По умолчанию оно равно true.

Установка этого свойства напрямую влияет на значение visible дочерних элементов. При установке в false, значения visible всех дочерних элементов также становятся false. При установке в true, значения visible дочерних элементов возвращаются к true, если они явно не были установлены в false.

(Из-за этого поведения, использование свойства visible может не иметь ожидаемого эффекта, если привязка свойства должна реагировать только на явные изменения свойства. В таких случаях лучше использовать свойство прозрачность.)

Если это свойство установлено в false, элемент больше не будет получать события мыши, но продолжит получать события клавиатуры и сохранит фокус клавиатуры фокус, если он был установлен. (В отличие от этого, установка свойства enabled в false блокирует как события мыши, так и клавиатуры, а также снимает фокус с элемента.)

Примечание: Значение этого свойства изменяется только при изменении этого свойства или свойства родительского элемента visible. Оно не изменяется, например, если этот элемент выходит за пределы экрана или если прозрачность изменяется на 0.

См. также прозрачность и enabled.

visibleChildren : list<Item>

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

z : real

Устанавливает порядок следования элементов-братьев. По умолчанию порядок следования равен 0.

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

Следующий пример демонстрирует различные эффекты порядка следования.

Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
    }
    Rectangle {
        color: "blue"
        x: 50; y: 50; width: 100; height: 100
    }
}

Item {
    Rectangle {
        z: 1
        color: "red"
        width: 100; height: 100
    }
    Rectangle {
        color: "blue"
        x: 50; y: 50; width: 100; height: 100
    }
}

Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
        Rectangle {
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}

Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
        Rectangle {
            z: -1
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}

Документация по методам

Преобразует точку (x, y) или прямоугольник (x, y, width, height), которые заданы в системе координат этого элемента, в систему координат item и возвращает точку или прямоугольник, соответствующие преобразованным координатам.

При преобразовании используются следующие свойства элемента: x, y, scale, rotation, transformOrigin и transform.

Если item имеет значение null, это преобразует точку или прямоугольник в систему координат корневого QML-представления.

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

Преобразует точку (x, y) или прямоугольник (x, y, width, height), заданные в системе координат item, в систему координат этого элемента и возвращает точку или прямоугольник, соответствующие преобразованным координатам.

При преобразовании используются следующие свойства элемента: x, y, scale, rotation, transformOrigin и transform.

Если item имеет значение null, это отображает точку или прямоугольник из системы координат корневого QML-виджета.

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

childAt(вещественное x, вещественное y)

Возвращает первый видимый дочерний элемент, найденный в точке (x, y) в системе координат этого элемента.

Возвращает null, если такого элемента нет.

логическое contains(точка point)

Возвращает true, если этот элемент содержит point, который задан в локальных координатах; в противном случае возвращает false.

[since 5.1] forceActiveFocus(Qt::FocusReason reason)

Это перегруженный метод.

Принудительно устанавливает активный фокус на элементе с заданным reason.

Этот метод устанавливает фокус на элементе и гарантирует, что все предковые объекты FocusScope в иерархии объектов также получат focus.

Этот метод был представлен в Qt 5.1.

См. также activeFocus и Qt::FocusReason.

forceActiveFocus()

Принудительно устанавливает активный фокус на элементе.

Этот метод устанавливает фокус на элементе и гарантирует, что все предковые объекты FocusScope в иерархии объектов также получат focus.

Причина изменения фокуса будет Qt::OtherFocusReason. Используйте перегруженный метод для указания причины изменения фокуса, чтобы обеспечить лучшее обращение с изменением фокуса.

См. также activeFocus.

логическое grabToImage(callback, targetSize)

Захватывает элемент в виде изображения в памяти.

Захват происходит асинхронно, и JavaScript-функция callback вызывается при завершении захвата. Функция обратного вызова принимает один аргумент, который является результатом операции захвата; объект ItemGrabResult.

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

Если захват не может быть инициирован, функция возвращает false.

Следующий фрагмент кода демонстрирует, как захватить элемент и сохранить результаты в файл.

Rectangle {
    id: source
    width: 100
    height: 100
    gradient: Gradient {
        GradientStop { position: 0; color: "steelblue" }
        GradientStop { position: 1; color: "black" }
    }
}
    // ...
    source.grabToImage(function(result) {
                           result.saveToFile("something.png");
                       });

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

Image {
    id: image
}
    // ...
    source.grabToImage(function(result) {
                           image.source = result.url;
                       },
                       Qt.size(50, 50));

Примечание: Эта функция отобразит элемент на отдельном поверхностном объекте и скопирует этот объект из памяти графического процессора в память центрального процессора, что может быть довольно затратно. Для "живого" предварительного просмотра используйте слои или ShaderEffectSource.

[since 5.7] объект mapFromGlobal(вещественное x, вещественное y)

Преобразует точку (x, y), заданную в глобальной системе координат, в систему координат элемента и возвращает точку, соответствующую преобразованным координатам.

Для преобразования используются следующие свойства элемента: x, y, масштаб, вращение, начало преобразования и преобразование.

Этот метод был представлен в Qt 5.7.

[since 5.7] объект mapToGlobal(вещественное x, вещественное y)

Преобразует точку (x, y), заданную в системе координат этого элемента, в глобальную систему координат и возвращает точку, соответствующую преобразованным координатам.

Для преобразования используются следующие свойства элемента: x, y, масштаб, вращение, начало преобразования и преобразование.

Этот метод был представлен в Qt 5.7.

[since 5.1] nextItemInFocusChain(логическое forward)

Возвращает элемент в цепочке фокуса, следующий за этим элементом. Если forward равно true, или не указано, это следующий элемент в прямом направлении. Если forward равно false, это следующий элемент в обратном направлении.

Этот метод был представлен в Qt 5.1.