Back to Qt.io
Contact Us Blog Download Qt

Keys QML Type

항목에 키 처리를 제공합니다. 더 보기...

Import Statement: import QtQuick

속성

신호

상세 설명

모든 시각적 프리미티브는 키가 첨부된 프로퍼티를 통해 키 처리를 지원합니다. 키는 onPressed 및 onReleased 신호 속성을 통해 처리할 수 있습니다.

신호 속성에는 이벤트의 세부 정보를 포함하는 이벤트라는 이름의 KeyEvent 매개변수가 있습니다. 키가 처리되는 경우 이벤트가 항목 계층 구조로 전파되지 않도록 event.accepted를 true로 설정해야 합니다.

사용 예

다음 예는 일반 onPressed 핸들러를 사용하여 특정 키(이 경우 왼쪽 커서 키)를 테스트하는 방법을 보여줍니다:

Item {
    anchors.fill: parent
    focus: true
    Keys.onPressed: (event)=> {
        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 을 참조하세요.

키 처리 우선순위

키가 연결된 항목 전후에 키 이벤트를 처리하도록 키가 연결된 속성을 구성할 수 있습니다. 이렇게 하면 이벤트를 가로채서 항목의 기본 동작을 재정의하거나 항목에서 처리하지 않는 키에 대한 대체 키로 사용할 수 있습니다.

priority 이 키 이벤트 처리 순서는 Keys.BeforeItem(기본값)인 경우입니다:

  1. 에 지정된 항목 forwardTo
  2. 특정 키 핸들러(예: onReturnPressed
  3. onPressed, onReleased 핸들러
  4. 항목별 키 처리, 예: TextInput 키 처리
  5. 부모 항목

우선순위가 Keys.AfterItem인 경우 키 이벤트 처리 순서는 다음과 같습니다:

  1. 항목별 키 처리, 예: TextInput 키 처리
  2. 에 지정된 항목 forwardTo
  3. 특정 키 핸들러, 예: onReturnPressed
  4. onPressed, onReleased 핸들러
  5. 부모 항목

위의 단계 중 하나라도 이벤트가 수락되면 키 전파가 중지됩니다.

KeyEvent 및 KeyNavigation attached property 을참조하세요 .

속성 문서

enabled : bool

이 플래그가 true(기본값)이면 키 처리를 활성화하고, 그렇지 않으면 키 핸들러가 호출되지 않습니다.


forwardTo : list<Item> [read-only]

이 속성은 입력 메서드에서 오는 키 누르기, 키 놓기 및 키보드 입력을 다른 항목으로 전달하는 방법을 제공합니다. 한 항목은 일부 키(예: 위쪽 및 아래쪽 화살표 키)를 처리하고 다른 항목은 다른 키(예: 왼쪽 및 오른쪽 화살표 키)를 처리하도록 하려는 경우에 유용할 수 있습니다. 키가 전달된 항목이 이벤트를 수락하면 더 이상 목록의 뒷부분에 있는 항목으로 이벤트가 전달되지 않습니다.

이 예에서는 키 이벤트를 두 개의 목록으로 전달합니다:

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

forwardTo를 사용할 때 이벤트가 수신되는 순서를 확인하려면 Key Handling Priorities 을 참조하세요.


priority : enumeration

이 속성은 첨부된 항목의 자체 키 처리 전 또는 후에 키가 처리되는지 여부를 결정합니다.

Constant설명
Keys.BeforeItem(기본값) 일반 항목 키 처리 전에 키 이벤트를 처리합니다. 이벤트가 수락되면 항목에 전달되지 않습니다.
Keys.AfterItem정상적인 항목 키 처리 후에 키 이벤트를 처리합니다. 항목이 키 이벤트를 수락하면 키 첨부 속성 핸들러에서 처리하지 않습니다.

Key Handling Priorities 를참조하세요 .


신호 문서

asteriskPressed(KeyEvent event)

이 신호는 별표 '*'를 눌렀을 때 발생합니다. event 매개변수는 이벤트에 대한 정보를 제공합니다.

참고: 해당 핸들러는 onAsteriskPressed 입니다.


backPressed(KeyEvent event)

이 신호는 뒤로 키를 눌렀을 때 전송됩니다. event 매개변수는 이벤트에 대한 정보를 제공합니다.

참고: 해당 핸들러는 onBackPressed 입니다.


backtabPressed(KeyEvent event)

이 신호는 Shift+Tab 키 조합(백탭)을 눌렀을 때 전송됩니다. 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)

이 신호는 플립 키를 눌렀을 때 전송됩니다. event 매개변수는 이벤트에 대한 정보를 제공합니다.

참고: 해당 핸들러는 onFlipPressed 입니다.


hangupPressed(KeyEvent event)

이 신호는 끊기 키를 눌렀을 때 전송됩니다. event 매개 변수는 이벤트에 대한 정보를 제공합니다.

참고: 해당 핸들러는 onHangupPressed 입니다.


leftPressed(KeyEvent event)

이 신호는 왼쪽 화살표를 눌렀을 때 전송됩니다. event 매개변수는 이벤트에 대한 정보를 제공합니다.

참고: 해당 핸들러는 onLeftPressed 입니다.


이 신호는 메뉴 키를 눌렀을 때 발생합니다. event 매개변수는 이벤트에 대한 정보를 제공합니다.

참고: 해당 핸들러는 onMenuPressed 입니다.


noPressed(KeyEvent event)

이 신호는 아니요 키를 눌렀을 때 전송됩니다. 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 매개변수는 이벤트에 대한 정보를 제공합니다.

참고: 해당 핸들러는 onSelectPressed 입니다.


shortcutOverride(KeyEvent event)

이 신호는 바로 가기로 사용될 수 있는 키를 눌렀을 때 발생합니다. event 매개변수는 이벤트에 대한 정보를 제공합니다.

누른 키가 Shortcut 와 같은 다른 유형에서 바로 가기로 사용되지 않도록 하려면 event.accepted 를 true 로 설정하세요. 예를 들어

Item {
    id: escapeItem
    focus: true

    // Ensure that we get escape key press events first.
    Keys.onShortcutOverride: (event)=> 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 입니다.

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 입니다.


© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.