Тип QML Control

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

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

Свойства

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

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

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

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

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

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

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

Control {
    padding: 10

    contentItem: Text {
        text: "Content"
    }
}

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

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

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 и Использование типов Qt Quick Controls в объявлениях свойств.

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

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

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

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

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

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

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

background : Item

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

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

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

[с момента QtQuick.Controls 2.5 (Qt 5.12)] 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
    }
}

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

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 Базовый тип шрифта.

[с версии QtQuick.Controls 2.5 (Qt 5.12)] 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.

[только для чтения, с версии QtQuick.Controls 2.5 (Qt 5.12)] 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.

[только для чтения, с версии QtQuick.Controls 2.5 (Qt 5.12)] 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.

[только для чтения, с версии QtQuick.Controls 2.5 (Qt 5.12)] 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.

[только для чтения, с версии QtQuick.Controls 2.5 (Qt 5.12)] 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.

[с версии QtQuick.Controls 2.5 (Qt 5.12)] leftInset : вещественное

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

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

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

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

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

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

locale : Locale

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

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

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

См. также mirrored.

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

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

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

Начиная с Qt 6.2, свойство locale больше не влияет на это свойство.

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

padding : real

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

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

• leftPadding
• rightPadding
• topPadding
• bottomPadding

padding: 0

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

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

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

[с QtQuick.Controls 2.5 (Qt 5.12)] rightInset : real

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

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

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

rightPadding : real

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

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

spacing : real

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

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

[с QtQuick.Controls 2.5 (Qt 5.12)] topInset : real

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

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

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

topPadding : real

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

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

[с QtQuick.Controls 2.5 (Qt 5.12)] 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.