Тип QML Control

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

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

Свойства

• availableHeight : real
• availableWidth : real
• фон : Item
• bottomInset : real
• bottomPadding : real
• contentItem : Item
• focusPolicy : перечисление
• focusReason : перечисление
• шрифт : шрифт
• горизонтальная отступ : real
• hoverEnabled : bool
• hovered : bool
• явный размер фона высота : real
• явный размер фона ширина : real
• явный размер содержимого высота : real
• явный размер содержимого ширина : real
• leftInset : real
• leftPadding : real
• locale : Локаль
• mirrored : bool
• отступ : real
• палитра : палитра
• rightInset : real
• rightPadding : real
• пробел : real
• topInset : real
• topPadding : real
• вертикальный отступ : real
• visualFocus : bool
• wheelEnabled : bool

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

Control — это базовый тип пользовательских элементов управления. Он получает события ввода от системы окон и отрисовывает свое представление на экране.

Макет элемента управления

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

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

Геометрия contentItem определяется отступами. В следующем примере резервируется 10 пикселей отступа между границами элемента управления и его содержимым:

Control {
    padding: 10

    contentItem: Text {
        text: "Content"
    }
}

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

Отрицательные отступы могут использоваться для увеличения размера фона по сравнению с элементом управления. В следующем примере используются отрицательные отступы для размещения тени за пределами границ элемента управления:

Control {
    topInset: -2
    leftInset: -2
    rightInset: -6
    bottomInset: -6

    background: BorderImage {
        source: ":/images/shadowed-background.png"
    }
}

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

Все элементы управления, за исключением неинтерактивных индикаторов, не пропускают щелчки и касания к элементам под ними. Например, вызов console.log() в примере ниже никогда не будет выполнен при нажатии на область, потому что MouseArea находится под ним в сцене:

MouseArea {
    anchors.fill: parent
    onClicked: console.log("MouseArea was clicked")

    Pane {
        anchors.fill: parent
    }
}

См. также ApplicationWindow и Container.

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

[только для чтения] availableHeight : real

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

См. также Макет элемента управления, отступ, topPadding и bottomPadding.

[только для чтения] availableWidth : real

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

См. также Макет элемента управления, отступ, leftPadding и rightPadding.

фон : Item

Это свойство содержит элемент фона.

Button {
    id: control
    text: qsTr("Button")
    background: Rectangle {
        implicitWidth: 100
        implicitHeight: 40
        opacity: enabled ? 1 : 0.3
        color: control.down ? "#d0d0d0" : "#e0e0e0"
    }
}

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

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

См. также Макет элемента управления.

bottomInset : real

Это свойство содержит нижний отступ для фона.

Это свойство было добавлено в QtQuick.Controls 2.5 (Qt 5.12).

См. также Макет элемента управления и topInset.

bottomPadding : real

Это свойство содержит нижний отступ. Если явно не указано, значение равно verticalPadding.

См. также Макет элемента управления, отступ, topPadding, verticalPadding и availableHeight.

contentItem : Item

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

Button {
    id: control
    text: qsTr("Button")
    contentItem: Label {
        text: control.text
        font: control.font
        verticalAlignment: Text.AlignVCenter
    }
}

Примечание: Элемент содержимого автоматически позиционируется и изменяет размер для соответствия отступу управления. Связывания со свойствами x, y, width и height элемента contentItem не учитываются.

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

См. также Макет элемента управления и отступ.

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

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

[только для чтения] focusReason : перечисление

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

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

См. также Item::activeFocus и visualFocus.

font : шрифт

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

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

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

• передача пользовательского шрифта в QGuiApplication::setFont() до загрузки QML; или
• указание шрифтов в файле qtquickcontrols2.conf.

Наконец, шрифт сравнивается с базой данных шрифтов Qt, чтобы найти лучшее соответствие.

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

Page {
    font.family: "Courier"

    Column {
        Label {
            text: qsTr("This will use Courier...")
        }

        Switch {
            text: qsTr("... and so will this")
        }
    }
}

Полный список доступных свойств шрифта см. в документации QML-типа шрифта.

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

Это свойство содержит горизонтальный отступ. Если явно не задано, значение равно padding.

Это свойство было добавлено в QtQuick.Controls 2.5 (Qt 5.12).

См. также Макет элемента управления, отступ, leftPadding, rightPadding и verticalPadding.

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

Это свойство определяет, принимает ли элемент управления события наведения. Значение по умолчанию равно Qt.styleHints.useHoverEffects.

Установка этого свойства распространяет значение на все дочерние элементы управления, у которых hoverEnabled явно не задано.

Вы также можете включить или отключить эффекты наведения для всех приложений Qt Quick Controls, установив QT_QUICK_CONTROLS_HOVER_ENABLED переменную среды.

См. также hovered.

[только для чтения] hovered : логическое

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

См. также hoverEnabled.

[только для чтения] implicitBackgroundHeight : вещественное

Это свойство содержит неявную высоту фона.

Значение равно background ? background.implicitHeight : 0.

Обычно используется вместе с implicitContentHeight для вычисления implicitHeight:

Control {
    implicitHeight: Math.max(implicitBackgroundHeight + topInset + bottomInset,
                             implicitContentHeight + topPadding + bottomPadding)
}

Это свойство было добавлено в QtQuick.Controls 2.5 (Qt 5.12).

См. также implicitBackgroundWidth и implicitContentHeight.

[только для чтения] implicitBackgroundWidth : вещественное

Это свойство содержит неявную ширину фона.

Значение равно background ? background.implicitWidth : 0.

Обычно используется вместе с implicitContentWidth для вычисления implicitWidth:

Control {
    implicitWidth: Math.max(implicitBackgroundWidth + leftInset + rightInset,
                            implicitContentWidth + leftPadding + rightPadding)
}

Это свойство было добавлено в QtQuick.Controls 2.5 (Qt 5.12).

См. также implicitBackgroundHeight и implicitContentWidth.

[только для чтения] implicitContentHeight : вещественное

Это свойство содержит неявную высоту содержимого.

Для основных элементов управления значение равно contentItem ? contentItem.implicitHeight : 0. Для типов, наследующих Container или Pane, значение рассчитывается на основе дочерних элементов содержимого.

Обычно используется вместе с implicitBackgroundHeight для вычисления implicitHeight:

Control {
    implicitHeight: Math.max(implicitBackgroundHeight + topInset + bottomInset,
                             implicitContentHeight + topPadding + bottomPadding)
}

Это свойство было добавлено в QtQuick.Controls 2.5 (Qt 5.12).

См. также implicitContentWidth и implicitBackgroundHeight.

[только для чтения] implicitContentWidth : вещественное

Это свойство содержит неявную ширину содержимого.

Для основных элементов управления значение равно contentItem ? contentItem.implicitWidth : 0. Для типов, наследующих Container или Pane, значение рассчитывается на основе дочерних элементов содержимого.

Обычно используется вместе с implicitBackgroundWidth для вычисления implicitWidth:

Control {
    implicitWidth: Math.max(implicitBackgroundWidth + leftInset + rightInset,
                            implicitContentWidth + leftPadding + rightPadding)
}

Это свойство было добавлено в QtQuick.Controls 2.5 (Qt 5.12).

См. также implicitContentHeight и implicitBackgroundWidth.

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

Это свойство содержит левый отступ для фона.

Это свойство было добавлено в QtQuick.Controls 2.5 (Qt 5.12).

См. также Макет элемента управления и rightInset.

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

Это свойство содержит левый отступ. Если явно не задано, значение равно horizontalPadding.

См. также Макет элемента управления, padding, rightPadding, horizontalPadding и availableWidth.

locale : Locale

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

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

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

См. также mirrored и LayoutMirroring.

[только для чтения] mirrored : bool

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

Это свойство предоставлено для удобства. Элемент управления считается зеркальным, если его направление визуального макета справа налево; то есть при использовании локали справа налево или когда LayoutMirroring.enabled равно true.

См. также locale, LayoutMirroring и Интерфейсы пользователя справа налево.

padding : real

Это свойство содержит значение отступа по умолчанию.

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

• leftPadding
• rightPadding
• topPadding
• bottomPadding

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

padding: 0

установите каждое конкретное свойство вместо этого:

leftPadding: 0
rightPadding: 0
topPadding: 0
bottomPadding: 0

См. также Макет элемента управления, availableWidth, availableHeight, topPadding, leftPadding, rightPadding и bottomPadding.

palette : palette

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

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

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

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

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

Page {
    palette.text: "red"

    Column {
        Label {
            text: qsTr("This will use red color...")
        }

        Switch {
            text: qsTr("... and so will this")
        }
    }
}

Полный список доступных цветов палитры см. в документации палитры QML.

Это свойство было добавлено в QtQuick.Controls 2.3 (Qt 5.10).

См. также ApplicationWindow::palette и Popup::palette.

rightInset : real

Это свойство содержит правый отступ для фона.

Это свойство было добавлено в QtQuick.Controls 2.5 (Qt 5.12).

См. также Макет элемента управления и leftInset.

rightPadding : real

Это свойство содержит правый отступ. Если явно не задано, значение равно horizontalPadding.

См. также Макет элемента управления, padding, leftPadding, horizontalPadding и availableWidth.

spacing : real

Это свойство содержит значение интервала.

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

topInset : real

Это свойство содержит верхний отступ для фона.

Это свойство было добавлено в QtQuick.Controls 2.5 (Qt 5.12).

См. также Макет элемента управления и bottomInset.

topPadding : real

Это свойство содержит верхний отступ. Если явно не задано, значение равно verticalPadding.

См. также Макет элемента управления, padding, bottomPadding, verticalPadding и availableHeight.

verticalPadding : real

Это свойство содержит вертикальный отступ. Если явно не задано, значение равно padding.

Это свойство было добавлено в QtQuick.Controls 2.5 (Qt 5.12).

См. также Макет элемента управления, padding, topPadding, bottomPadding и horizontalPadding.

[только для чтения] visualFocus : bool

Это свойство указывает, имеет ли элемент управления визуальный фокус. Это свойство true когда элемент управления имеет активный фокус, и причина фокуса является Qt.TabFocusReason, Qt.BacktabFocusReason, или Qt.ShortcutFocusReason.

В общем случае для визуализации фокуса по клавишам рекомендуется использовать это свойство вместо Item::activeFocus. Это гарантирует, что фокус по клавишам визуализируется только при взаимодействии с клавишами, а не при взаимодействии с помощью сенсорного ввода или мыши.

См. также focusReason и Item::activeFocus.

wheelEnabled : bool

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

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