Тип QML Control

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

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

Свойства

• availableHeight : real
• availableWidth : real
• фон : Item
• bottomInset : real
• bottomPadding : real
• contentItem : Item
• focusPolicy : перечисление
• focusReason : перечисление
• шрифт : шрифт
• horizontalPadding : real
• hoverEnabled : bool
• hovered : bool
• implicitBackgroundHeight : real
• implicitBackgroundWidth : real
• implicitContentHeight : real
• implicitContentWidth : real
• leftInset : real
• leftPadding : real
• locale : Locale
• mirrored : bool
• padding : real
• палитра : palette
• rightInset : real
• rightPadding : real
• интервал : real
• topInset : real
• topPadding : real
• verticalPadding : real
• visualFocus : bool
• wheelEnabled : bool

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

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

Макет 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() в примере ниже никогда не будет выполнен при нажатии на элемент управления Pane, потому что MouseArea находится ниже его в сцене:

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

    Pane {
        anchors.fill: parent
    }
}

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

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

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

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

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

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

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

См. также Макет элемента управления, padding, 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.

См. также Макет элемента управления, padding, 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, у которого есть свой неявный размер).

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

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).

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

hoverEnabled : логическое значение

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

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

Вы также можете включить или выключить эффекты наведения для всех приложений Qt Quick Controls 2, установив 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: 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.