Тип QML Item

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

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

Свойства

• activeFocus : bool
• activeFocusOnTab : bool
• anchors
  • anchors.top : AnchorLine
  • anchors.bottom : AnchorLine
  • anchors.left : AnchorLine
  • anchors.right : AnchorLine
  • anchors.horizontalCenter : AnchorLine
  • anchors.verticalCenter : AnchorLine
  • anchors.baseline : AnchorLine
  • anchors.fill : Item
  • anchors.centerIn : Item
  • anchors.margins : real
  • anchors.topMargin : real
  • anchors.bottomMargin : real
  • anchors.leftMargin : real
  • anchors.rightMargin : real
  • anchors.horizontalCenterOffset : real
  • anchors.verticalCenterOffset : real
  • anchors.baselineOffset : real
  • anchors.alignWhenCentered : bool
• antialiasing : bool
• baselineOffset : int
• children : list<Item>
• childrenRect
  • childrenRect.x : real
  • childrenRect.y : real
  • childrenRect.width : real
  • childrenRect.height : real

Методы

• childAt(real x, real y)
• bool содержит(point point)
• принудительноВыделитьФокус()
• принудительноВыделитьФокус(Qt::FocusReason reason)
• bool захватитьВИзображение(callback, targetSize)
• object преобразоватьОтГлобального(real x, real y)
• object преобразоватьОтЭлемента(Item item, real x, real y)
• object преобразоватьОтЭлемента(Item item, real x, real y, real width, real height)
• object преобразоватьВГлобальный(real x, real y)
• object преобразоватьВЭлемент(Item item, real x, real y)
• object преобразоватьВЭлемент(Item item, real x, real y, real width, real height)
• следующийЭлементЦепиФокуса(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"
    }
}

Обработка клавиш

Обработка клавиш доступна для всех визуальных типов, основанных на элементе, через свойство Клавиши (Keys). Свойство Клавиши (Keys) предоставляет базовые сигналы, такие как нажатие и отпускание, а также сигналы для определенных клавиш, например, spacePressed. В примере ниже задается фокус клавиатуры для элемента и обрабатывается левая клавиша через общий onPressed обработчик, а клавиша ввода — через обработчик onReturnPressed.

import QtQuick 2.0

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

Подробная документация содержится в свойстве Клавиши (Keys).

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

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

Дополнительные сведения см. в LayoutMirroring.

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

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

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

Элемент будет использовать линейную интерполяцию при масштабировании, если layer.smooth установлено в true, и будет использовать mipmap для уменьшения масштаба, если layer.mipmap установлено в true. Мипмаппинг может улучшить качество изображения уменьшенных элементов. Для мипмаппинга отдельных элементов 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: "
            uniform lowp sampler2D source; // this item
            uniform lowp float qt_Opacity; // inherited opacity of this item
            varying highp vec2 qt_TexCoord0;
            void main() {
                lowp vec4 p = texture2D(source, qt_TexCoord0);
                lowp float g = dot(p.xyz, vec3(0.344, 0.5, 0.156));
                gl_FragColor = vec4(g, g, g, p.a) * qt_Opacity;
            }"
    }

В этом примере мы реализуем эффект шейдера вручную. Модуль Qt Graphical Effects содержит набор готовых эффектов для использования с Qt Quick.

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

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

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

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

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

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

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

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

activeFocus : bool

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

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

Обычно фокус activeFocus получает элемент, на котором установлен 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

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

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

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

anchors.top : AnchorLine

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

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

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

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

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

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

baselineOffset : int

Указывает позицию базовой линии элемента в локальных координатах.

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

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

children : list<Item>

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

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

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

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

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

clip : bool

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

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

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 позволяет свободно смешивать визуальные дочерние элементы и ресурсы в элементе. Если вы назначите визуальный элемент в список данных, он станет дочерним элементом, а если вы назначите любой другой тип объекта, он будет добавлен как ресурс.

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

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.

height : real

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

Положение (x, y) относительно родителя parent.

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

implicitHeight : real

Определяет естественную высоту элемента, если не указана ширина 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 и явное задание ширины приводит к снижению производительности, так как текст должен быть отформатирован дважды.

implicitWidth : real

Определяет естественную ширину элемента, если не указана ширина 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 и явное задание ширины приводит к снижению производительности, так как текст должен быть отформатирован дважды.

layer.effect : Component

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

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

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

layer.enabled : bool

Указывает, включен ли слой или нет. По умолчанию слои отключены.

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

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

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

layer.format : enumeration

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

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

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

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

layer.mipmap : bool

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

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

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

layer.samplerName : string

Содержит имя свойства sourceTexture эффекта.

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

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

layer.samples : enumeration

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

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

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

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

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

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

layer.smooth : bool

Указывает, будет ли слой плавно преобразован.

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

layer.sourceRect : rect

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

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

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

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

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

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

layer.textureSize : размер

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

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

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

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

Это свойство определяет режимы обрезки OpenGL, связанные с текстурой. Изменение этого свойства имеет смысл, когда задан 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.

parent : Item

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

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

resources : список<Объект>

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

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

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

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

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

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

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

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

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

Масштаб меньше 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
    }
}

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

smooth : логическое

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

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

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

state : строка

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

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

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

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

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

Это свойство задается как список объектов State. Например, ниже показан элемент с состояниями «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.

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

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

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

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

transformOrigin : перечисление

Это свойство хранит точку начала преобразований масштабирования и поворота.

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

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

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

Чтобы установить произвольную точку начала преобразования, используйте типы преобразования Scale или Rotation со свойством transform.

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

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

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

import QtQuick 2.0

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

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

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

visible : логическое

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

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

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

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

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

См. также opacity и enabled.

visibleChildren : список<Item>

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

width : вещественный

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

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

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

x : вещественный

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

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

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

y : вещественный

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

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

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

z : вещественный

Устанавливает порядок наложения элементов-потомков. По умолчанию порядок наложения равен 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, масштаб, поворот, transformOrigin и transform.

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

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

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

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

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

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

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

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

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

forceActiveFocus()

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

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

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

См. также activeFocus.

forceActiveFocus(Qt::FocusReason reason)

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

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

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

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

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

логическое 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.

объект mapFromGlobal(вещественный x, вещественный y)

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

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

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

объект mapToGlobal(вещественный x, вещественный y)

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

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

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

nextItemInFocusChain(логическое forward)

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

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