Тип 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 : Locale
• зеркалирование : 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() в примере ниже никогда не будет выполнен при щелчке на Pane, потому что MouseArea расположена под ним в сцене:

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

    Pane {
        anchors.fill: parent
    }
}

См. также ApplicationWindow, Container и Использование типов Qt Quick Controls в объявлениях свойств.

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

[только для чтения] 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, у которого есть свой явный размер).

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

[с QtQuick.Controls 2.5 (Qt 5.12)] 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, шириной и высотой свойствами contentItem не учитываются.

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

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

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 Basic Type.

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

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

locale : Locale

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

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

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

См. также зеркалирование и LayoutMirroring.

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

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

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

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

padding : real

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

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

• leftPadding
• rightPadding
• topPadding
• bottomPadding

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

padding: 0

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

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

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

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

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

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

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

rightPadding : real

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

См. также Макет элемента управления, отступ, leftPadding, горизонтальный отступ и доступная ширина.

spacing : real

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

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

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

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

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

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

topPadding : real

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

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

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

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

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

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

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

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

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

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

wheelEnabled : bool

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

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