Тип 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
• palette : palette
• rightInset : real
• rightPadding : real
• spacing : real
• topInset : real
• topPadding : real
• verticalPadding : real
• visualFocus : bool
• wheelEnabled : bool

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

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

Макет Control

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

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

Геометрия 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.

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

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

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

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

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

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

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

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

Примечание: Большинство элементов управления используют неявный размер элемента фона для расчета неявного размера самого элемента управления. Если вы замените элемент фона пользовательским элементом, вам также следует предусмотреть разумный неявный размер для него (если это не элемент, подобный 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
    }
}

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

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

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

Это свойство было добавлено в 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.