사용 사례 - QML에서 사용자 입력에 응답하기

지원되는 사용자 입력 유형

모듈은 Qt Quick 모듈은 마우스 및 터치 이벤트, 텍스트 입력, 키 누르기 이벤트 등 가장 일반적인 유형의 사용자 입력을 지원합니다. 다른 모듈은 다른 유형의 사용자 입력에 대한 지원을 제공합니다.

이 문서에서는 기본적인 사용자 입력을 처리하는 방법을 다룹니다. 시청각 입력에 대한 자세한 내용은 Qt Multimedia 문서를 참조하세요.

마우스 및 터치 이벤트

입력 핸들러를 사용하면 QML 애플리케이션에서 마우스 및 터치 이벤트를 처리할 수 있습니다. 예를 들어 이미지에 TapHandler 를 추가하여 버튼을 만들거나 Rectangle 에 Text 객체를 추가하여 버튼을 만들 수 있습니다. TapHandler 은 모든 유형의 포인팅 장치에 대한 탭 또는 클릭에 반응합니다.

import QtQuick

Item {
    id: root

    width: 320
    height: 480

    Rectangle {
        color: "#272822"
        width: 320
        height: 480
    }

    Rectangle {
        id: rectangle
        x: 40
        y: 20
        width: 120
        height: 120
        color: "red"

        TapHandler {
            onTapped: rectangle.width += 10
        }
    }
}

참고: 일부 항목 유형에는 자체 입력 처리가 내장되어 있습니다. 예를 들어 Flickable 은 마우스 드래그, 터치 플리킹, 마우스 휠 스크롤에 반응합니다.

키보드 및 버튼 이벤트

디바이스의 버튼, 키패드 또는 키보드의 버튼 및 키 누름은 모두 Keys 첨부 프로퍼티를 사용하여 처리할 수 있습니다. 이 첨부 속성은 모든 Item 파생 유형에서 사용할 수 있으며 Item::focus 속성과 함께 작동하여 어떤 유형이 키 이벤트를 수신할지 결정합니다. 간단한 키 처리를 위해 하나의 Item 에 포커스를 true로 설정하고 거기서 모든 키 처리를 수행할 수 있습니다.

import QtQuick

Item {
    id: root

    width: 320
    height: 480

    Rectangle {
        color: "#272822"
        width: 320
        height: 480
    }

    Rectangle {
        id: rectangle
        x: 40
        y: 20
        width: 120
        height: 120
        color: "red"

        focus: true
        Keys.onUpPressed: rectangle.y -= 10
        Keys.onDownPressed: rectangle.y += 10
        Keys.onLeftPressed: rectangle.x += 10
        Keys.onRightPressed: rectangle.x -= 10
    }
}

텍스트 입력의 경우 선택할 수 있는 QML 유형이 여러 가지 있습니다. TextInput 는 스타일이 지정되지 않은 한 줄 편집 가능한 텍스트를 제공하는 반면 TextField 은 애플리케이션의 양식 필드에 더 적합합니다. TextEdit 은 여러 줄 편집 가능한 텍스트를 처리할 수 있지만 TextArea 은 스타일이 추가되므로 더 나은 대안이 될 수 있습니다.

다음 스니펫은 애플리케이션에서 이러한 유형을 사용하는 방법을 보여줍니다:

import QtQuick
import QtQuick.Controls
import QtQuick.Layouts

ApplicationWindow {
    width: 300
    height: 200
    visible: true

    ColumnLayout {
        anchors.fill: parent
        TextField {
            id: singleline
            text: "Initial Text"
            Layout.alignment: Qt.AlignHCenter | Qt.AlignTop
            Layout.margins: 5
            background: Rectangle {
               implicitWidth: 200
               implicitHeight: 40
               border.color: singleline.focus ? "#21be2b" : "lightgray"
               color: singleline.focus ? "lightgray" : "transparent"
            }
        }

        TextArea {
            id: multiline
            placeholderText: "Initial text\n...\n...\n"
            Layout.alignment: Qt.AlignLeft
            Layout.fillWidth: true
            Layout.fillHeight: true
            Layout.margins: 5
            background: Rectangle {
               implicitWidth: 200
               implicitHeight: 100
               border.color: multiline.focus ? "#21be2b" : "lightgray"
               color: multiline.focus ? "lightgray" : "transparent"
            }
        }
    }
}

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