Тип QML Item

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

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

Свойства

• activeFocus : bool
• activeFocusOnTab : bool
• anchors
  • anchors.alignWhenCentered : bool
  • anchors.baseline : AnchorLine
  • anchors.baselineOffset : real
  • anchors.bottom : AnchorLine
  • anchors.bottomMargin : real
  • anchors.centerIn : Item
  • anchors.fill : Item
  • anchors.horizontalCenter : AnchorLine
  • anchors.horizontalCenterOffset : real
  • anchors.left : AnchorLine
  • anchors.leftMargin : real
  • anchors.margins : real
  • anchors.right : AnchorLine
  • anchors.rightMargin : real
  • anchors.top : AnchorLine
  • anchors.topMargin : real
  • anchors.verticalCenter : AnchorLine
  • anchors.verticalCenterOffset : real
• antialiasing : bool
• baselineOffset : int
• children : список<Item>
• childrenRect
  • childrenRect.height : real
  • childrenRect.width : real
  • childrenRect.x : real
  • childrenRect.y : real
• clip : bool
• containmentMask : QObject*
• data : список<Объект>
• enabled : bool
• focus : bool
• height : real
• implicitHeight : real
• implicitWidth : real
• layer.effect : Компонент
• layer.enabled : bool
• layer.format : перечисление
• layer.mipmap : bool
• layer.samplerName : строка
• layer.samples : перечисление
• layer.smooth : bool
• layer.sourceRect : прямоугольник
• layer.textureMirroring : перечисление
• layer.textureSize : размер
• layer.wrapMode : перечисление
• opacity : real
• palette : Палитра
• parent : Item
• resources : список<Объект>
• rotation : real
• scale : real
• smooth : bool
• state : строка
• states : список<Состояние>
• transform : список<Преобразование>
• transformOrigin : перечисление
• transitions : список<Переход>
• visible : bool
• visibleChildren : список<Item>
• width : real
• x : real
• y : real
• z : real

Методы

• childAt(real x, real y)
• bool contains(точка point)
• forceActiveFocus(Qt::FocusReason reason)
• forceActiveFocus()
• bool grabToImage(callback, targetSize)
• объект mapFromGlobal(real x, real y)
• объект mapFromItem(Item item, прямоугольник r)
• объект mapFromItem(Item item, real x, real y, real width, real height)
• объект mapFromItem(Item item, real x, real y)
• объект mapFromItem(Item item, точка p)
• объект mapToGlobal(real x, real y)
• объект mapToItem(Item item, прямоугольник r)
• объект mapToItem(Item item, real x, real y, real width, real height)
• объект mapToItem(Item item, real x, real y)
• объект mapToItem(Item item, точка 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, через присоединённое свойство Keys. Присоединённое свойство Keys предоставляет основные сигналы, такие как pressed и released, а также сигналы для конкретных клавиш, такие как 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.

Отражение макета

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

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

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

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

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

Элемент будет использовать линейную интерполяцию при масштабировании, если layer.smooth установлено в true и будет использовать mip-мапирование для уменьшения масштаба, если 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: "effect.frag.qsb"
    }
}

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

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

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

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

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

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

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

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

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

По умолчанию неявный размер для большинства элементов — 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) относительно родителя.

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

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

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

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

anchors.alignWhenCentered : bool

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

Отступы применяются к якорям сверху, снизу, слева, справа и заполнения. Свойство 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

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

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

baselineOffset : int

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

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

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

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

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

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

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 и Слои элементов.

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

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

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

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

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

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

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

layer.smooth : bool

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

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

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

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

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

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

[с 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.

[с 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.

parent : Item

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

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

rotation : real

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

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

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

См. также Transform и Rotation.

scale : real

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

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

См. также Transform и Scale.

smooth : bool

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

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

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

state : string

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

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

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

states : list<State>

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

Это свойство содержит список преобразований, которые необходимо применить.

Для получения дополнительной информации см. Transform.

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

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

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

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

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

Для установки произвольной точки начала преобразования используйте типы преобразований Масштаб или Вращение с типом преобразования.

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

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

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

import QtQuick 2.0

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

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

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

видимый : логическое

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

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

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

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

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

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

видимыеДочерниеЭлементы : список<Элемент>

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

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

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

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

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

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

В отображении используются следующие свойства элемента: x, y, масштаб, вращение, 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));

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

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

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

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

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

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

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

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

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

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

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

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