EventListener

위치: qml/components/control/util/EventListener.qml

EventListener는 트리거 토큰을 콜백 이벤트에 매핑하는 LVRS 상호 작용 브리지 구성 요소입니다. 현재 정책은 사건 중심적입니다. 즉, 명시적으로 활성화하지 않는 한 지속적인 상태 수집을 방지합니다.

1. 디자인 목표

• 실제 사건(click, press, release, context request 등)에 대한 이벤트 콜백을 전달합니다.
• 기본적으로 고비용 페이로드 강화를 피하세요.
• 불필요한 런타임 스냅샷/적중 테스트 풀로 인한 연쇄 반응을 방지합니다.

2. 지원되는 트리거

• 포인터-로컬: clicked, pressed, released, entered, exited, hoverChanged
• 휠: wheel
• 키보드: keyPressed, keyReleased
• 글로벌 런타임: globalPressed, globalContextRequested

3. 코어 API

4. 사고 중심 페이로드 규칙

4.1 기본 모드(권장)

기본적으로:

• input 스냅샷을 가져오지 않았습니다.
• UI 적중 테스트 순회가 실행되지 않습니다.
• 콜백은 직접적인 사건 필드만 수신합니다.

이는 런타임 결합을 최소화하고 필요하지 않은 경우에 대한 보이지 않는 뷰 트리 추적을 방지합니다.

4.2 강화 모드(명시적 옵트인)

콜백 로직에 실제로 런타임 상태 일관성이 필요한 경우 includeInputState: true를 설정하세요. 결정에 UI 적중 메타데이터가 필요한 경우(예: 상황별 메뉴)에만 includeUiHit: true를 설정하십시오.

4.3 백엔드 요약 모드

includeBackendSummary: true는 진단 지향적이며 고속 흐름에서는 비용이 많이 들 수 있습니다. 핫 경로 상호 작용 콜백이 아닌 도구/디버그 대시보드에만 사용하세요.

5. 페이로드 스키마

로컬 포인터(clicked|pressed|released)

항상:

• x, y, globalX, globalY
• button, buttons, modifiers
• isGlobal=false

선택사항:

• includeUiHit=true일 때 ui
• includeInputState=true일 때 input
• includeBackendSummary=true일 때 backend

글로벌 포인터(globalPressed|globalContextRequested)

항상:

• x, y, globalX, globalY
• buttons, modifiers
• isGlobal=true

상황별 추가:

• reason
• source ("mouse" 또는 "context")

선택적 강화는 로컬 포인터 페이로드와 동일한 토글을 따릅니다.

휠/키 트리거

• 휠/키는 Qt 이벤트 객체를 직접 전달하도록 트리거합니다.

hoverChanged

• 페이로드: { containsMouse: bool }

6. 중복 제거 동작

• 글로벌 언론 중복 제거는 짧은 시간 내에 중복된 언론 사고를 억제합니다.
• 컨텍스트 중복 제거는 자체 창에서 중복된 컨텍스트 사건을 억제합니다.
• 중복 제거는 콜백 방출에만 영향을 미칩니다. 외부 런타임 데몬 카운터를 변경하지 않습니다.

7. 사용 패턴

7.1 최소 사고 수신기(선호)

import LVRS 1.0 as LV

LV.EventListener {
    trigger: "globalPressed"
    action: function(eventData) {
        // 외부 클릭으로 닫는 로직에는 좌표와 버튼만 사용한다.
    }
}

7.2 UI 히트 메타데이터가 포함된 컨텍스트 리스너

import LVRS 1.0 as LV

LV.EventListener {
    trigger: "globalContextRequested"
    includeUiHit: true
    action: function(eventData) {
        console.log(eventData.ui ? eventData.ui.path : "unknown")
    }
}

7.3 명시적 입력 상태 옵트인

import LVRS 1.0 as LV

LV.EventListener {
    trigger: "globalContextRequested"
    includeInputState: true
    preferBackendState: true
    action: function(eventData) {
        const input = eventData.input || ({})
        console.log(input.activeModifierNames)
    }
}

8. 일반적인 함정

• 습관적으로 어디서나 includeInputState를 활성화합니다.
• 고주파 상호 작용 경로에 대해 includeUiHit 및 includeBackendSummary를 모두 활성화합니다.
• 보도 자료 중심이어야 하는 비즈니스 로직에 hoverChanged를 사용합니다.
• 전역 좌표 확인 없이 전역 트리거를 로컬 형상 전용 이벤트로 처리합니다.

9. 문제 해결 매트릭스

10. Codex 중심 플레이북

새로운 청취자를 위한 10.1 Safe Codex 기본값

1. includeUiHit=false를 유지하세요.
2. includeInputState=false를 유지하세요.
3. includeBackendSummary=false를 유지하세요.
4. 콜백 논리에 필요한 경우에만 강화를 활성화합니다.

10.2 Codex 안티 패턴

• 모든 리스너에 입력 상태 강화를 자동 주입하지 마세요.
• 프레임별 추적 의미 체계에 전역 수신기를 사용하지 마세요.
• 공유 루트 리스너에 부작용이 많은 콜백 본문을 추가하지 마세요.

10.3 코덱스 회귀 체크리스트

수정 후:

1. 글로벌 언론/컨텍스트 청취자는 여전히 사건당 정확히 한 번만 실행됩니다.
2. 외부 해제 흐름은 최소한의 페이로드로 계속 작동합니다.
3. 강화된 리스너는 활성화된 경우 요청된 선택적 필드를 계속 수신합니다.

11. 관련 API

• RuntimeEvents: 글로벌 트리거용 런타임 데몬 소스입니다.
• Backend: 선택적 백엔드 우선 입력 상태 소스.
• ApplicationWindow: 앱 전체 동작을 위해 루트 수준 전역 수신기를 설치합니다.