PySide6 Qt for Python 키보드 이벤트와 단축키 가이드 keyPress keyRelease QShortcut QAction 포커스 정책 완전정복

PySide6 Qt for Python 키보드 이벤트와 단축키 가이드 keyPress keyRelease QShortcut QAction 포커스 정책 완전정복

⌨️ 키 입력 처리부터 QShortcut와 QAction 설계, FocusPolicy까지 한 번에 정리해 생산성을 높이세요

데스크톱 앱에서 키보드 입력은 속도와 정확도를 좌우하는 핵심 인터랙션입니다.
특히 PySide6를 사용할 때는 이벤트 전파 흐름과 위젯의 포커스 정책, 그리고 단축키를 어떤 계층에 매달아야 하는지가 결과를 크게 바꿉니다.
프로토타입 단계에서는 우연히 동작해도, 실제 배포 환경에서는 포커스가 다른 위젯에 잡혀 있거나 액션이 비활성화되어 입력이 씹히는 일이 잦습니다.
이 글은 Qt for Python의 표준 방식에 맞춰 keyPressEvent와 keyReleaseEvent를 다루고, QShortcut와 QAction으로 일관된 단축키 체계를 설계하는 법을 친근한 예시와 함께 설명합니다.
또한 FocusPolicy를 이해하고 위젯별로 포커스를 통제해 충돌을 줄이는 실무 팁을 담았습니다.

핵심은 세 가지입니다.
첫째, 이벤트가 어디서 생성되고 누구에게 우선 전달되는지 흐름을 이해하는 것.
둘째, 즉석 처리가 필요한 입력은 이벤트 핸들러에서, 재사용 가능한 명령은 QAction과 QShortcut에 위임해 구조를 분리하는 것.
셋째, 포커스 정책과 포커스 체인을 명확히 정의해 예측 가능한 단축키 경험을 제공하는 것입니다.
글 전반에 걸쳐 흔히 겪는 문제 패턴과 해결책을 짚어 주며, 실제 코드에서 바로 가져다 쓸 수 있는 패턴을 제시합니다.
불필요한 시행착오를 줄이고, 유지보수하기 쉬운 입력 설계를 만드는 데 도움이 될 것입니다.

🧭 키보드 이벤트 개요와 이벤트 흐름

PySide(Qt for Python)에서 키보드 입력은 QKeyEvent로 표현되며, 대표 콜백은 keyPressEvent와 keyReleaseEvent입니다.
키 이벤트는 운영체제 → Qt 이벤트 루프 → 포커스 위젯(focusWidget) 순서로 전달됩니다.
포커스를 가진 위젯이 먼저 처리 기회를 갖고, 처리되었다면 event.accept() 상태로 전파가 멈춥니다.
수신자가 이벤트를 거부하거나 처리하지 않으면 부모 위젯로 버블링되고, 최종적으로 애플리케이션 레벨 필터가 받습니다.
이 흐름을 이해하면 “단축키가 가끔 안 먹는다” 같은 문제를 체계적으로 재현하고 해결할 수 있습니다.

QKeyEvent는 key()(Qt.Key_*)와 modifiers()(Ctrl, Shift, Alt, Meta), text()(문자 입력), isAutoRepeat()(키 반복) 같은 속성을 제공합니다.
문자 편집 위젯에서는 텍스트 삽입이 기본 동작으로 예약돼 있으므로, 커스텀 단축키를 직접 처리하려면 accept() 또는 ignore() 호출로 명시적으로 우선순위를 조절해야 합니다.
또한 입력 방식(IM) 활성화 환경에서는 text()가 조합 중간 단계에서 비어 있을 수 있어, 키코드와 수정자를 함께 판단해야 오작동을 줄일 수 있습니다.

from PySide6 import QtCore, QtGui, QtWidgets

class Editor(QtWidgets.QPlainTextEdit):
    def keyPressEvent(self, e: QtGui.QKeyEvent) -> None:
        # 1) 자동 반복 입력은 커서 이동/삭제 같은 경우에만 허용
        if e.isAutoRepeat():
            return super().keyPressEvent(e)

        mods = e.modifiers()
        key  = e.key()

        # 2) 커스텀 단축키: Ctrl+L 로 현재 줄 선택
        if (mods & QtCore.Qt.ControlModifier) and key == QtCore.Qt.Key_L:
            self.selectAll()  # 예시: 실제로는 현재 라인 선택 로직
            e.accept()
            return

        # 3) 그 외는 기본 처리로 전달
        super().keyPressEvent(e)

    def keyReleaseEvent(self, e: QtGui.QKeyEvent) -> None:
        # 키 릴리즈는 상태 전환(토글) 추적용으로만 최소 사용
        super().keyReleaseEvent(e)

app = QtWidgets.QApplication([])
w = Editor()
w.setWindowTitle("Key Handling with PySide6")
w.show()
app.exec()

💬 포커스가 없는 위젯은 키보드 이벤트를 직접 받지 않습니다.
필요하면 QApplication.instance().focusWidget()으로 현재 수신자를 확인하고, 이벤트가 누락되는 경로를 추적하세요.

class KeyWatcher(QtCore.QObject):
    def eventFilter(self, obj, e):
        if e.type() == QtCore.QEvent.KeyPress:
            if (e.modifiers() & QtCore.Qt.ControlModifier) and e.key() == QtCore.Qt.Key_S:
                # 전역 저장 단축키 같은 패턴을 감시
                e.accept()
                # 실제 동작은 QAction/QShortcut에 위임하는 것이 권장
                return True  # True면 이벤트 소비
        return super().eventFilter(obj, e)

watcher = KeyWatcher()
app.installEventFilter(watcher)  # 앱 전역 감시

• 🧭현재 focusWidget()이 무엇인지 먼저 확인
• ⌨️isAutoRepeat() 입력은 별도 처리하여 오동작 방지
• 🧰즉시 반응 로직은 이벤트에서, 명령은 QAction/QShortcut로 분리
• 🔎필요 시 eventFilter로 경로를 관찰하고 accept/ignore 흐름을 검증

🧩 keyPressEvent keyReleaseEvent 정확한 사용법

PySide6에서 keyPressEvent()와 keyReleaseEvent()는 각각 키가 눌렸을 때, 그리고 놓였을 때 호출되는 이벤트 핸들러입니다.
이 두 메서드는 키보드 입력의 저수준 처리에 관여하며, 위젯마다 독립적으로 오버라이드할 수 있습니다.
하지만 단순히 오버라이드한다고 해서 모든 키가 들어오는 것은 아닙니다.
포커스 정책(FocusPolicy)에 따라 이벤트 수신 여부가 결정되기 때문에, 이를 무시하면 이벤트가 들어오지 않는 경우가 생깁니다.

일반적으로 키보드 입력을 다루는 패턴은 다음과 같습니다.
사용자가 특정 키를 눌렀을 때 즉시 반응해야 하는 경우(Space로 일시정지 전환 등)는 keyPressEvent에서 처리합니다.
반면, 키가 해제되는 순간이 중요한 경우(예: 게임에서 방향키 해제, 또는 Shift 토글 해제 등)는 keyReleaseEvent에서 처리합니다.
이 두 이벤트를 함께 사용하면 키의 눌림과 해제 상태를 모두 추적할 수 있습니다.

from PySide6.QtWidgets import QWidget, QApplication
from PySide6.QtGui import QKeyEvent
from PySide6.QtCore import Qt

class KeyExample(QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Key Event Example")
        self.resize(300, 200)

    def keyPressEvent(self, event: QKeyEvent):
        if event.key() == Qt.Key_Space:
            print("Space pressed")
            event.accept()
        elif event.key() == Qt.Key_Escape:
            print("Escape key detected, closing window")
            self.close()
        else:
            event.ignore()

    def keyReleaseEvent(self, event: QKeyEvent):
        if event.key() == Qt.Key_Space:
            print("Space released")

app = QApplication([])
window = KeyExample()
window.show()
app.exec()

위 코드에서 event.accept()를 명시적으로 호출하면, 해당 이벤트는 상위 위젯으로 전달되지 않습니다.
반대로 event.ignore()를 호출하거나 아무 조치도 하지 않으면 부모 위젯 또는 애플리케이션 레벨 필터로 전달됩니다.
이것이 event bubbling이며, Qt 입력 시스템의 중요한 특징입니다.

🎹 키코드와 수정자(Modifiers) 처리하기

Qt의 Qt.Key_* 상수는 대부분의 물리 키보드를 커버합니다.
하지만 동일한 키라도 지역 설정이나 IME 조합 상태에 따라 event.text()는 달라질 수 있습니다.
따라서 키보드 단축키를 감지할 때는 modifiers()와 key()를 함께 판별하는 것이 안전합니다.

if (event.modifiers() & Qt.ControlModifier) and event.key() == Qt.Key_S:
    print("Ctrl + S pressed")

이처럼 수정자와 키코드를 결합하면 복합 단축키를 감지할 수 있으며, 이는 나중에 QShortcut이나 QAction 설정 시에도 동일하게 적용됩니다.
또한 여러 키를 동시에 눌러야 하는 경우(예: Shift + Arrow)에는 modifiers()를 활용하면 간단히 처리할 수 있습니다.

• 🧩포커스가 있어야 keyPressEvent가 동작한다.
• 🎹modifiers()와 key()를 함께 비교해야 한다.
• 🔄기본 위젯 동작을 유지하려면 super() 호출을 생략하지 말 것.
• 🧰기본 입력 처리와 단축키 처리를 분리해 유지보수성을 높인다.

⚡ QShortcut와 QAction으로 단축키 설계하기

PySide6에서 QShortcut과 QAction은 키보드 단축키를 관리하는 핵심 클래스입니다.
직접 keyPressEvent()를 사용하는 방법은 빠르지만, 유지보수나 재사용이 어렵습니다.
반면 QShortcut과 QAction을 활용하면 명령 중심의 설계가 가능해져, UI와 로직을 자연스럽게 분리할 수 있습니다.

예를 들어, “Ctrl + S”로 저장하는 기능을 만들고 싶다면, 단순히 키 이벤트에서 조건문으로 처리하기보다 QAction에 단축키를 연결하는 것이 권장됩니다.
이 방식은 메뉴바, 툴바, 버튼 등에서도 동일한 액션을 재사용할 수 있어 일관성이 높고, Qt Designer에서도 그대로 연결할 수 있습니다.

from PySide6.QtWidgets import QApplication, QMainWindow, QAction, QTextEdit
from PySide6.QtGui import QKeySequence

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QAction and QShortcut Example")
        self.editor = QTextEdit()
        self.setCentralWidget(self.editor)

        # QAction 생성 및 단축키 연결
        save_action = QAction("저장", self)
        save_action.setShortcut(QKeySequence("Ctrl+S"))
        save_action.triggered.connect(self.save_file)
        self.addAction(save_action)

    def save_file(self):
        print("파일 저장 실행됨")

app = QApplication([])
window = MainWindow()
window.show()
app.exec()

위 예시처럼 QAction은 triggered 시그널을 발행하며, 단축키로 바로 호출됩니다.
만약 특정 위젯에만 단축키를 한정하고 싶다면, QShortcut을 사용하면 됩니다.
QShortcut은 개별 위젯에 등록되므로, 해당 위젯이 포커스를 잃으면 단축키가 동작하지 않습니다.

from PySide6.QtWidgets import QWidget, QShortcut, QVBoxLayout, QPushButton
from PySide6.QtGui import QKeySequence

class ShortcutDemo(QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QShortcut Demo")
        layout = QVBoxLayout(self)
        btn = QPushButton("Click or press Ctrl+M")
        layout.addWidget(btn)

        shortcut = QShortcut(QKeySequence("Ctrl+M"), self)
        shortcut.activated.connect(lambda: print("Ctrl+M pressed"))

app = QApplication([])
demo = ShortcutDemo()
demo.show()
app.exec()

🧠 QAction vs QShortcut 차이점

• ⚡단축키는 keyPressEvent보다 QAction/QShortcut으로 관리하는 것이 안정적이다.
• 🧩QAction은 앱 전체 단위 명령, QShortcut은 로컬 단위에 적합하다.
• 🎯메뉴, 버튼, 단축키에서 동일한 QAction을 공유하면 UX 일관성이 높아진다.
• 🧠단축키 충돌은 포커스 우선순위에 따라 해결되므로, 구조 설계 시 이를 고려해야 한다.

🎯 포커스 정책 FocusPolicy와 위젯별 포커스

PySide6의 위젯은 모두 FocusPolicy 속성을 가지고 있으며, 이는 해당 위젯이 어떤 상황에서 키보드 포커스를 받을 수 있는지를 결정합니다.
포커스는 단축키와 키보드 입력의 전제 조건이기 때문에, 키 이벤트가 작동하지 않는 대부분의 원인은 이 정책에서 비롯됩니다.
즉, 위젯이 포커스를 받을 수 없는 상태라면 keyPressEvent()나 QShortcut도 실행되지 않습니다.

📚 FocusPolicy 종류와 특징

예를 들어, 사용자 정의 위젯에 키 이벤트를 적용했는데 아무 반응이 없다면 self.setFocusPolicy(Qt.StrongFocus)를 추가하는 것으로 문제를 해결할 수 있습니다.
이는 특히 QFrame, QLabel 등 기본적으로 포커스를 받지 않는 위젯에서 중요합니다.

from PySide6.QtWidgets import QLabel, QApplication
from PySide6.QtCore import Qt

class FocusLabel(QLabel):
    def __init__(self):
        super().__init__("Press any key")
        self.setFocusPolicy(Qt.StrongFocus)  # 반드시 설정
        self.setAlignment(Qt.AlignCenter)
        self.setStyleSheet("font-size: 20px; border: 2px solid #8B6E63; padding: 20px;")

    def keyPressEvent(self, event):
        self.setText(f"Pressed: {event.text()} ({event.key()})")

app = QApplication([])
label = FocusLabel()
label.show()
app.exec()

위 예시에서는 QLabel이 기본적으로 포커스를 받지 않기 때문에, Qt.StrongFocus를 설정해야 키보드 이벤트가 발생합니다.
이처럼 위젯마다 포커스 정책이 다르기 때문에, 입력이 작동하지 않을 때는 먼저 focusPolicy() 값을 점검해야 합니다.

🔄 포커스 전환과 이벤트 흐름

포커스 전환은 Qt 내부에서 focusInEvent()와 focusOutEvent()로 감지할 수 있습니다.
이 이벤트를 활용하면 포커스가 옮겨갈 때 특정 상태를 초기화하거나 강조 표시를 적용할 수 있습니다.
예를 들어, 입력 필드에 포커스가 들어오면 배경색을 바꾸고, 포커스가 빠지면 원래 색으로 복귀하는 UX를 쉽게 구현할 수 있습니다.

def focusInEvent(self, event):
    self.setStyleSheet("background-color: #fff8e1; border: 2px solid #ffb300;")
    super().focusInEvent(event)

def focusOutEvent(self, event):
    self.setStyleSheet("background-color: #ffffff; border: 1px solid #ccc;")
    super().focusOutEvent(event)

• 🎯키보드 이벤트는 포커스를 가진 위젯만 수신한다.
• 🔑포커스를 받지 않는 위젯은 setFocusPolicy(Qt.StrongFocus)로 설정해야 한다.
• 🧠focusInEvent와 focusOutEvent로 상태 전환을 감지할 수 있다.
• ⚙️포커스 정책은 단축키 작동 여부를 결정하는 가장 근본적인 요소다.

🛠️ 실전 예제 코드 단축키 충돌과 디버깅 팁

PySide6로 애플리케이션을 개발하다 보면 “단축키가 안 먹는다”, “이벤트가 중복 실행된다” 같은 문제가 자주 발생합니다.
이 현상은 대부분 포커스 충돌이나 단축키 중복 등록에서 비롯됩니다.
Qt 이벤트 시스템은 우선순위를 위젯 포커스 → QAction 등록 순으로 판단하므로, 같은 조합의 단축키가 여러 곳에 정의되어 있으면 예기치 않게 무시되거나, 한쪽만 작동할 수 있습니다.

따라서 실무에서는 단축키를 체계적으로 관리해야 합니다.
QAction이나 QShortcut을 등록할 때는 각 키 조합이 중복되지 않도록 중앙에서 관리하거나, 디버그 로그를 통해 현재 등록 상태를 점검합니다.
다음 예시는 단축키 충돌을 실시간으로 확인하고, 이벤트 필터로 키 입력을 추적하는 실전 예제입니다.

from PySide6.QtWidgets import QApplication, QMainWindow, QTextEdit, QAction
from PySide6.QtCore import QEvent, Qt
from PySide6.QtGui import QKeySequence

class DebugFilter(QApplication):
    def notify(self, receiver, event):
        if event.type() == QEvent.KeyPress:
            print(f"[DEBUG] Focused widget: {self.focusWidget().__class__.__name__}, Key: {event.key()}")
        return super().notify(receiver, event)

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Shortcut Debug Example")
        editor = QTextEdit()
        self.setCentralWidget(editor)

        save_action = QAction("Save", self)
        save_action.setShortcut(QKeySequence("Ctrl+S"))
        save_action.triggered.connect(lambda: print("Save action triggered"))
        self.addAction(save_action)

        quit_action = QAction("Quit", self)
        quit_action.setShortcut(QKeySequence("Ctrl+Q"))
        quit_action.triggered.connect(self.close)
        self.addAction(quit_action)

app = DebugFilter([])
window = MainWindow()
window.show()
app.exec()

위 예시에서는 QApplication을 상속한 DebugFilter 클래스에서 notify() 메서드를 재정의하여 모든 키 입력을 중앙에서 로그로 출력합니다.
이를 통해 단축키가 어느 위젯에서 가로채졌는지, 이벤트가 전달되지 않은 이유를 빠르게 파악할 수 있습니다.

🧩 단축키 충돌을 방지하는 3가지 전략

• 🧠중복되는 단축키는 피하고, 전역 단축키는 QAction에만 등록한다.
• 🎯특정 위젯 단위 단축키는 QShortcut을 사용해 국소화한다.
• 🧩디버깅 시 eventFilter 또는 notify()를 통해 키 입력 경로를 로그로 출력한다.

실무에서는 키 입력 로직이 복잡해질수록 이벤트 흐름을 시각화하거나 로그로 추적하는 습관이 중요합니다.
특히 Ctrl이나 Alt 계열 단축키는 OS 단에서 이미 사용 중일 수 있으므로, 다른 조합(예: Ctrl+Shift+S)을 사용하는 것이 안전합니다.

❓ 자주 묻는 질문 (FAQ)

🚀 PySide 키보드 이벤트와 단축키 설계 완벽 가이드 정리

PySide(Qt for Python)에서 키보드 입력은 앱의 반응성과 직결되는 중요한 부분입니다.
이 글에서는 keyPressEvent, keyReleaseEvent, QShortcut, QAction, 그리고 FocusPolicy까지 키 입력과 단축키 시스템의 전 과정을 단계별로 살펴봤습니다.
핵심은 이벤트의 흐름을 이해하고, 단축키는 명령 단위로, 이벤트는 위젯 단위로 처리한다는 점입니다.
포커스 정책을 잘못 설정하면 입력이 무시될 수 있고, 단축키 중복은 앱 전체의 UX를 망칠 수 있습니다.

실제 프로젝트에서는 다음 원칙을 기억하세요.
모든 위젯에는 명시적인 FocusPolicy를 부여하고, 복합 단축키는 QAction으로 통합 관리합니다.
또한 입력 경로를 디버깅하려면 eventFilter나 notify()를 활용하면 좋습니다.
이렇게 구성하면 앱의 유지보수성과 안정성이 높아지며, 사용자에게 더 자연스러운 인터페이스를 제공할 수 있습니다.

🏷️ 관련 태그 : PySide6, QtforPython, keyPressEvent, keyReleaseEvent, QShortcut, QAction, FocusPolicy, 이벤트처리, 단축키설계, Qt프로그래밍