Тип QML Control

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

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

Свойства

• availableHeight : real
• availableWidth : real
• фон : Item
• нижнийОтступ : real
• нижнийОтступ : real
• элементСодержимого : Item
• политикаФокуса : перечисление
• причинаФокуса : перечисление
• шрифт : шрифт
• горизонтальныйОтступ : real
• включитьНаведение : bool
• наведение : bool
• явнаяВысотаФоновогоЭлемента : real
• явнаяШиринаФоновогоЭлемента : real
• явнаяВысотаЭлементаСодержимого : real
• явнаяШиринаЭлементаСодержимого : real
• левыйОтступ : real
• левыйОтступ : real
• локаль : Locale
• зеркалировать : bool
• отступ : real
• правыйОтступ : real
• правыйОтступ : real
• интервал : real
• верхнийОтступ : real
• верхнийОтступ : real
• вертикальныйОтступ : real
• визуальныйФокус : bool
• включитьКолесоМыши : bool

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

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

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

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

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

Геометрия элемента содержимого определяется отступом. В следующем примере выделяется 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

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

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

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

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

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

фон : 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)] нижнийОтступ : real

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

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

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

нижнийОтступ : real

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

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

элементСодержимого : 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.

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