Тип 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 — это базовый тип элементов управления пользовательским интерфейсом. Он получает события ввода от системного окна и отображает своё представление на экране.

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

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

Значения 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, после вычитания вертикальных отступов из высоты элемента управления.

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

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

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

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

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.

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

locale : Локаль

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

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

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

См. также зеркалирование и 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

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

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.

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

spacing : real

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

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

topInset : real

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

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

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

topPadding : real

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

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

verticalPadding : real

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

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

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

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

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

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

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

wheelEnabled : bool

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

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