Тип QML Keys

Обеспечивает обработку нажатий клавиш для элементов Подробнее...

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

Свойства

• enabled : bool
• forwardTo : список<Объект>
• priority : перечисление

Сигналы

• asteriskPressed(KeyEvent event)
• backPressed(KeyEvent event)
• backtabPressed(KeyEvent event)
• callPressed(KeyEvent event)
• cancelPressed(KeyEvent event)
• context1Pressed(KeyEvent event)
• context2Pressed(KeyEvent event)
• context3Pressed(KeyEvent event)
• context4Pressed(KeyEvent event)
• deletePressed(KeyEvent event)
• digit0Pressed(KeyEvent event)
• digit1Pressed(KeyEvent event)
• digit2Pressed(KeyEvent event)
• digit3Pressed(KeyEvent event)
• digit4Pressed(KeyEvent event)
• digit5Pressed(KeyEvent event)
• digit6Pressed(KeyEvent event)
• digit7Pressed(KeyEvent event)
• digit8Pressed(KeyEvent event)
• digit9Pressed(KeyEvent event)
• downPressed(KeyEvent event)
• enterPressed(KeyEvent event)
• escapePressed(KeyEvent event)
• flipPressed(KeyEvent event)
• hangupPressed(KeyEvent event)
• leftPressed(KeyEvent event)
• menuPressed(KeyEvent event)
• noPressed(KeyEvent event)
• pressed(KeyEvent event)
• released(KeyEvent event)
• returnPressed(KeyEvent event)
• rightPressed(KeyEvent event)
• selectPressed(KeyEvent event)
• shortcutOverride(KeyEvent event)
• spacePressed(KeyEvent event)
• tabPressed(KeyEvent event)
• upPressed(KeyEvent event)
• volumeDownPressed(KeyEvent event)
• volumeUpPressed(KeyEvent event)
• yesPressed(KeyEvent event)

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

Все визуальные примитивы поддерживают обработку нажатий клавиш через свойство attached Keys. Обработка нажатий клавиш может выполняться через сигналы onPressed и onReleased.

Сигналы содержат параметр KeyEvent, имеющий имя event, которое содержит подробности события. Если нажатие клавиши обрабатывается, event.accepted должно быть установлено в true, чтобы предотвратить распространение события вверх по иерархии элементов.

Пример использования

Следующий пример демонстрирует, как можно использовать общий обработчик onPressed для проверки нажатия определенной клавиши; в данном случае, левой клавиши курсора:

Item {
    anchors.fill: parent
    focus: true
    Keys.onPressed: {
        if (event.key == Qt.Key_Left) {
            console.log("move left");
            event.accepted = true;
        }
    }
}

Некоторые клавиши могут альтернативно обрабатываться через специальные сигналы, например, onSelectPressed. Эти обработчики автоматически устанавливают event.accepted в true.

Item {
    anchors.fill: parent
    focus: true
    Keys.onLeftPressed: console.log("move left")
}

См. Qt.Key для списка кодов клавиатуры.

Приоритеты обработки нажатий клавиш

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

Если priority равен Keys.BeforeItem (по умолчанию), порядок обработки событий нажатия клавиш такой:

1. Элементы, указанные в forwardTo
2. специфические обработчики клавиш, например, onReturnPressed
3. обработчики onPressed, onReleased
4. обработка нажатий клавиш, специфичная для элемента, например, обработка нажатий клавиш TextInput
5. родительский элемент

Если priority равен Keys.AfterItem, порядок обработки событий нажатия клавиш такой:

1. обработка нажатий клавиш, специфичная для элемента, например, обработка нажатий клавиш TextInput
2. Элементы, указанные в forwardTo
3. специфические обработчики клавиш, например, onReturnPressed
4. обработчики onPressed, onReleased
5. родительский элемент

Если событие принимается на любом из вышеперечисленных шагов, распространение нажатия клавиши прекращается.

См. также KeyEvent и свойство attached KeyNavigation.

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

enabled : bool

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

forwardTo : список<Объект>

Это свойство предоставляет способ перенаправления нажатий клавиш, отпусканий клавиш и ввода с клавиатуры от методов ввода другим элементам. Это может быть полезно, когда вы хотите, чтобы один элемент обрабатывал некоторые клавиши (например, клавиши со стрелками вверх и вниз), а другой элемент – другие клавиши (например, клавиши со стрелками влево и вправо). Как только элемент, которому были перенаправлены клавиши, примет событие, он больше не перенаправляется элементам, расположенным позднее в списке.

В этом примере события нажатия клавиш перенаправляются двум спискам:

Item {
    ListView {
        id: list1
        // ...
    }
    ListView {
        id: list2
        // ...
    }
    Keys.forwardTo: [list1, list2]
    focus: true
}

Чтобы увидеть порядок, в котором события принимаются при использовании forwardTo, см. Приоритеты обработки нажатий клавиш.

priority : перечисление

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

• Keys.BeforeItem (по умолчанию) – обрабатывает события нажатия клавиш до обычной обработки нажатий клавиш элемента. Если событие принимается, оно не передаётся элементу.
• Keys.AfterItem – обрабатывает события нажатия клавиш после обычной обработки нажатий клавиш элемента. Если элемент принимает событие нажатия клавиши, оно не будет обработано обработчиком attached Keys.

См. также Приоритеты обработки нажатий клавиш.

Документация по сигналам

asteriskPressed(KeyEvent event)

Этот сигнал генерируется при нажатии клавиши «*» (Звездочка). Параметр event содержит информацию о событии.

Соответствующий обработчик – onAsteriskPressed.

backPressed(KeyEvent event)

Этот сигнал генерируется при нажатии клавиши «Назад». Параметр event содержит информацию о событии.

Соответствующий обработчик – onBackPressed.

backtabPressed(KeyEvent event)

Этот сигнал генерируется при нажатии комбинации клавиш Shift+Tab (Backtab). Параметр event содержит информацию о событии.

Соответствующий обработчик – onBacktabPressed.

callPressed(KeyEvent event)

Этот сигнал генерируется при нажатии клавиши «Вызов». Параметр event содержит информацию о событии.

Соответствующий обработчик – onCallPressed.

cancelPressed(KeyEvent event)

Этот сигнал генерируется при нажатии клавиши «Отмена». Параметр event содержит информацию о событии.

Соответствующий обработчик – onCancelPressed.

context1Pressed(KeyEvent event)

Этот сигнал излучается, когда нажата клавиша Context1. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onContext1Pressed.

context2Pressed(KeyEvent event)

Этот сигнал излучается, когда нажата клавиша Context2. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onContext2Pressed.

context3Pressed(KeyEvent event)

Этот сигнал излучается, когда нажата клавиша Context3. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onContext3Pressed.

context4Pressed(KeyEvent event)

Этот сигнал излучается, когда нажата клавиша Context4. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onContext4Pressed.

deletePressed(KeyEvent event)

Этот сигнал излучается, когда нажата клавиша Delete. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onDeletePressed.

digit0Pressed(KeyEvent event)

Этот сигнал излучается, когда нажата цифровая клавиша '0'. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onDigit0Pressed.

digit1Pressed(KeyEvent event)

Этот сигнал излучается, когда нажата цифровая клавиша '1'. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onDigit1Pressed.

digit2Pressed(KeyEvent event)

Этот сигнал излучается, когда нажата цифровая клавиша '2'. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onDigit2Pressed.

digit3Pressed(KeyEvent event)

Этот сигнал излучается, когда нажата цифровая клавиша '3'. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onDigit3Pressed.

digit4Pressed(KeyEvent event)

Этот сигнал излучается, когда нажата цифровая клавиша '4'. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onDigit4Pressed.

digit5Pressed(KeyEvent event)

Этот сигнал излучается, когда нажата цифровая клавиша '5'. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onDigit5Pressed.

digit6Pressed(KeyEvent event)

Этот сигнал излучается, когда нажата цифровая клавиша '6'. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onDigit6Pressed.

digit7Pressed(KeyEvent event)

Этот сигнал излучается, когда нажата цифровая клавиша '7'. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onDigit7Pressed.

digit8Pressed(KeyEvent event)

Этот сигнал излучается, когда нажата цифровая клавиша '8'. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onDigit8Pressed.

digit9Pressed(KeyEvent event)

Этот сигнал излучается, когда нажата цифровая клавиша '9'. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onDigit9Pressed.

downPressed(KeyEvent event)

Этот сигнал излучается, когда нажата клавиша со стрелкой вниз. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onDownPressed.

enterPressed(KeyEvent event)

Этот сигнал излучается, когда нажата клавиша Enter. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onEnterPressed.

escapePressed(KeyEvent event)

Этот сигнал излучается, когда нажата клавиша Escape. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onEscapePressed.

flipPressed(KeyEvent event)

Этот сигнал излучается, когда нажата клавиша Flip. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onFlipPressed.

hangupPressed(KeyEvent event)

Этот сигнал излучается, когда нажата клавиша Hangup. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onHangupPressed.

leftPressed(KeyEvent event)

Этот сигнал излучается, когда нажата клавиша со стрелкой влево. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onLeftPressed.

menuPressed(KeyEvent event)

Этот сигнал излучается, когда нажата клавиша Menu. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onMenuPressed.

noPressed(KeyEvent event)

Этот сигнал излучается, когда нажата клавиша No. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onNoPressed.

pressed(KeyEvent event)

Этот сигнал излучается, когда нажата любая клавиша. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onPressed.

released(KeyEvent event)

Этот сигнал излучается, когда клавиша отпущена. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onReleased.

returnPressed(KeyEvent event)

Этот сигнал излучается, когда нажата клавиша Return. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onReturnPressed.

rightPressed(KeyEvent event)

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

Соответствующий обработчик — onRightPressed.

selectPressed(KeyEvent event)

Этот сигнал излучается, когда нажата клавиша Select. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onSelectPressed.

shortcutOverride(KeyEvent event)

Этот сигнал излучается, когда нажата клавиша, которая потенциально может использоваться как сочетание клавиш. Параметр event содержит информацию об этом событии.

Установите event.accepted в значение true, если вы хотите предотвратить использование нажатой клавиши как сочетания клавиш другими типами, такими как Shortcut. Например:

Item {
    id: escapeItem
    focus: true

    // Ensure that we get escape key press events first.
    Keys.onShortcutOverride: event.accepted = (event.key === Qt.Key_Escape)

    Keys.onEscapePressed: {
        console.log("escapeItem is handling escape");
        // event.accepted is set to true by default for the specific key handlers
    }
}

Shortcut {
    sequence: "Escape"
    onActivated: console.log("Shortcut is handling escape")
}

Как и в других сигналах, shortcutOverride будет излучаться только для элемента, если у этого элемента установлен activeFocus.

Соответствующий обработчик — onShortcutOverride.

Этот QML-сигнал был добавлен в Qt 5.9.

См. также Shortcut.

spacePressed(KeyEvent event)

Этот сигнал излучается, когда нажата клавиша пробела. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onSpacePressed.

tabPressed(KeyEvent event)

Этот сигнал излучается, когда нажата клавиша Tab. Параметр event содержит информацию об этом событии.

Соответствующий обработчик — onTabPressed.

upPressed(KeyEvent event)

Этот сигнал испускается при нажатии клавиши Вверх. Параметр event содержит информацию об событии.

Соответствующий обработчик — onUpPressed.

volumeDownPressed(KeyEvent event)

Этот сигнал испускается при нажатии клавиши Уменьшение громкости. Параметр event содержит информацию об событии.

Соответствующий обработчик — onVolumeDownPressed.

volumeUpPressed(KeyEvent event)

Этот сигнал испускается при нажатии клавиши Увеличение громкости. Параметр event содержит информацию об событии.

Соответствующий обработчик — onVolumeUpPressed.

yesPressed(KeyEvent event)

Этот сигнал испускается при нажатии клавиши Да. Параметр event содержит информацию об событии.

Соответствующий обработчик — onYesPressed.