LVRS Storyboard Frame

components/app/ApplicationWindow.svx

Path: components/app/ApplicationWindow.svx

Last modified:

ApplicationWindow

위치: qml/ApplicationWindow.qml

ApplicationWindow는 적응형 레이아웃, 전역 인터랙션 라우팅 및 런타임 /render 정책 배선을 위한 LVRS 루트 셸입니다.

1. 범위 및 역할

ApplicationWindow 소유:

  • 플랫폼/크기 클래스 신호 및 적응형 레이아웃 상태,
  • 스캐폴드 내비게이션 구성 (레일/드래어/바텀 모드)
  • 렌더링 품질 레이어 브리지 ( RenderQuality ),
  • 루트 리스너를 통한 전역 압착/컨텍스트 이벤트,
  • 옵션 런타임 및 백엔드 후크 부트스트래핑,
  • 선택 가능한 네이티브 윈도우 스타일링 후크.

ApplicationWindow는 ****를 소유하지 않습니다.

  • 백엔드 정책 상수 (RenderQuality / RuntimeEvents 소유)
  • 라우트 파서 내부 (PageRouter는 라우트 매칭을 보유합니다),
  • 데이터 지속성.

2. 시작 시퀀스 (운영 계약)

Component.onCompleted에서 쉘은 다음을 수행합니다:

  1. FontPolicy.enforceApplicationFallback(),
  2. 선택적 장치 계층 프리셋 적용 ( RenderQuality.applyDeviceTierPreset(...) ),
  3. RenderQuality.applyWindow(windowRoot),
  4. SvgManager.ensureMinimumScale(effectiveSupersampleScale),
  5. 런타임 데몬을 기본적으로 시작/연결합니다 ( autoAttachRuntimeEvents, 기본값: globalEventListenersEnabled ),
  6. 옵션 백엔드 미러 훅 ( autoHookBackendUserEvents , 기본 false ),
  7. 네이티브 윈도우 스타일 애플리케이션 및 지연 새로 고침.

주문은 다음과 같은 이유로 중요합니다:

  • 렌더 레이어 크기 조정은 활성 렌더 품질 정책에 따라 달라집니다.
  • 런타임 훅 경로는 데몬 가용성 및 연결된 윈도우 컨텍스트를 기대합니다.

3. 코어 속성 그룹

3.1 플랫폼 및 사이즈 클래스

속성 의미
platform OS 토큰은 Qt.platform.os에서 가져옵니다.
isMobilePlatform, isDesktopPlatform 플랫폼 그룹 플래그.
widthClass, heightClass 콤팩트/미디엄/확폭 분류.
isCompact, isExpanded 결합된 클래스 도우미

3.2 레이아웃 및 스캐폴드

속성 의미
navItems 스캐폴드 대리자를 위한 소스 내비게이션 모델.
navIndex, navigationEnabled 현재 탐색 선택 및 활성화 상태.
scaffoldLayoutMode auto/mobile/desktop 선호도 힌트.
adaptiveLayoutProfile 프로필이 해결되었습니다 (mobile-compact, desktop-wide 등).
adaptiveNavigationMode 탐색 모드가 해결되었습니다 ( rail , drawer , bottom , none ).

3.3 렌더 품질 브리지

속성 의미
effectiveSupersampleScale 백엔드의 효과적인 정책 가치를 반영합니다.
sceneSupersamplingActive 씬 레이어 슈퍼샘플링을 위한 백엔드 계산 활성화 플래그
inactiveRenderDowngradeEnabled 숨김/최소화된 창에 대한 렌더 비용 다운그레이드 정책을 전환합니다.
inactiveRenderMsaaSamples 다운그레이드 모드에서 사용되는 대상 MSAA 샘플 값.
autoApplyDeviceTierPreset 시작 시 장치 계층 프리셋을 자동으로 적용할지 여부.
forcedDeviceTierPreset 강제 사전 설정 값 (-1는 자동 감지를 의미합니다).
pageRouterRetainInactivePages 비활성 페이지 깊이는 내부 PageRouter에 의해 유지됩니다.
pageRouterCacheCapacity 내부 PageRouter의 라우트-리졸브 캐시 용량.
슈퍼샘플 호스트 layer.textureSize RenderQuality.resolveLayerTextureSize(...)를 통해 해결되었습니다.
슈퍼샘플 호스트 layer.mipmap RenderQuality.mipmapEnabled 정책을 직접 반영합니다.

3.4 런타임 /글로벌 이벤트 브리지

속성 /신호 의미
globalEventListenersEnabled 전역 리스너 구성 요소용 마스터 스위치.
autoAttachRuntimeEvents 런타임 데몬 자동 시작/연결 (기본값: globalEventListenersEnabled).
autoHookBackendUserEvents 자동 후크 백엔드 미러 캐시(기본값 false, 옵트인).
globalPressedEvent(eventData) 루트 글로벌 프레스 릴레이
globalContextEvent(eventData) 전역 컨텍스트 요청 릴레이를 루트합니다.
lastGlobalPressedEventData, lastGlobalContextEventData 마지막으로 전달된 페이로드 스냅샷.

4. 적응형 레이아웃 상태 동작

내부 적응형 호스트는 다음에 대해 보호된 전환을 강제합니다:

  • 레이아웃 프로필 전환 ( mobile-compact , mobile-wide , desktop-compact , desktop-wide ),
  • 네비게이션 모드 전환 ( rail , drawer , bottom , none ).

가드 로직:

  • 한 단계에서 갑작스럽게 호환되지 않는 전환을 허용하지 않습니다.
  • 전환 거부 메타데이터를 방출합니다,
  • 중간 상태가 필요할 때 후속 수렴(Qt.callLater)을 예약합니다.

이는 급격한 크기 조정/장치 등급 변경 시 불안정한 진동을 방지합니다.

5. 렌더 경로 사례

케이스 sceneSupersamplingActive 예상 레이어 동작
픽셀 예산 아래의 작은 창 참 슈퍼샘플 레이어가 활성화되었습니다; 백엔드 정책에 따라 텍스처 크기가 조정되었습니다.
예산을 초과하는 큰 창 false 레이어는 스케일되지 않은 기본 크기를 유지합니다.
RenderQuality가 빌드 변형에 의해 비활성화되었습니다 false/1x 우아한 대체 경로를 기본 텍스처 사이징으로
창이 아직 적용되지 않았습니다. 적용될 때까지 거짓 RenderQuality.applyWindow에 전화하십시오.

6. 런타임 /이벤트 케이스

케이스 조건 예상 동작
런타임 자동 부착이 활성화되었습니다 (기본값) globalEventListenersEnabled=true 및 autoAttachRuntimeEvents=true 데몬이 시작되어 이 창에 부착됩니다.
백엔드 자동 훅이 활성화되었습니다 (옵트인) autoHookBackendUserEvents=true Backend.hookUserEvents() 시도 및 로그인 실패
전역 리스너 비활성화 globalEventListenersEnabled=false 전역 압착/컨텍스트 릴레이가 중지됩니다
좌표가 없는 컨텍스트 이벤트 오형화된 페이로드 컨텍스트 메뉴 헬퍼는 안전하게 무작업 처리해야 합니다.

7. 권장 통합 패턴

7.1 생산 쉘 기준선

import LVRS 1.0 as LV

LV.ApplicationWindow {
    visible: true
    width: 1280
    height: 800

    globalEventListenersEnabled: true
}

7.2 내부 페이지 스택이 포함된 내비게이션

import LVRS 1.0 as LV

LV.ApplicationWindow {
    useInternalPageStack: true
    pageRoutes: [
        { path: "/", component: homePage },
        { path: "/reports", component: reportsPage }
    ]
}

8. 일반적인 함정

  • 경로 정의를 활성화하지만 내부 페이지 스택을 의도치 않게 비활성화합니다.
  • 백엔드 리졸버를 사용하는 대신 페이지 내에서 렌더 레이어 크기 계산을 교체합니다.
  • 루트 리스너가 비활성화된 상태에서 전역 컨텍스트 신호를 기대합니다.
  • 런타임 데몬이 수동으로 autoAttachRuntimeEvents=false를 설정한 후에도 항상 연결된다고 가정합니다.
  • 백엔드 미러링 캐시가 autoHookBackendUserEvents를 활성화하지 않고 항상 활성화되어 있다고 가정합니다.

9. 문제 해결 매트릭스

증상 예상 원인 검증 조치
적응 모드가 크기 조정 시 깜박거림 충돌하는 수동 상태 쓰기 레이아웃 프로파일 전환을 검사합니다 적응형 호스트가 자체 프로필 전환을 수행하도록 합니다
컨텍스트 메뉴가 표시되지 않습니다 전역 컨텍스트 페이로드가 없거나 리스너가 비활성화되었습니다 lastGlobalContextEventData 리스너를 활성화하고, 페이로드 좌표를 확인하십시오.
렌더링 품질이 효과가 없습니다 윈도우 정책이 적용되지 않았습니다. 시작 로그/주문 확인 완료 시 RenderQuality.applyWindow가 실행되도록 보장하십시오.
백엔드 훅 실패 런타임 사용 불가 또는 훅 오류 Backend.lastError 런타임 싱글턴가 로드되고 연결되었는지 확인하십시오.

10. Codex 중심 플레이북

10.1 안전 코덱스 패치 경계

ApplicationWindow.qml를 편집할 때는 다음을 선호합니다:

  1. 적응형 상태 기계의 의미를 그대로 유지하십시오.
  2. 백엔드 API 호출에서 렌더링 품질 수학을 유지하십시오.
  3. 런타임 후크 배선을 기존 기능 플래그 뒤에 유지하십시오.
  4. 신호 페이로드 계약을 안정적으로 유지하십시오.

10.2 Codex 안티 패턴

  • 여러 대리자에 새 슈퍼샘플 공식을 내선으로 포함하지 마십시오.
  • 필요하지 않은 경우 내부 적응형 호스트 프라이빗 전환 플래그를 직접 변경하지 마십시오.
  • 기능 플래그가 존재하는 경우 백엔드 후크를 항상 켜도록 하드 와이어하지 마십시오.

10.3 코덱스 회귀 체크리스트

쉘 동작을 패치한 후:

  1. 빠른 크기 조정 후에도 적응형 레이아웃이 여전히 수렴하는지 확인하십시오.
  2. 전역 압착/맥락 신호가 여전히 방출되는지 확인하십시오.
  3. 백엔드에서 해결된 텍스처 크기에 슈퍼샘플 호스트 바인드를 검증합니다,
  4. 런타임 자동 연결 및 백엔드 자동 훅 플래그가 여전히 독립적으로 작동하는지 확인하십시오.

11. 검증 체크리스트

  • 정책에 민감한 작업에 대한 시작 순서는 변함이 없습니다.
  • 적응 전이는 콤팩트/넓은 경계 변화 하에서 결정론적 상태를 유지합니다.
  • 백엔드 플래그로 레이어 토글을 렌더링하고, 로컬 수학이 중복되지 않도록 합니다.
  • 전역 이벤트 릴레이와 런타임 플래그는 문서화된 대로 독립적으로 작동합니다.

12. 관련 API

  • RenderQuality (docs/backend/RenderQuality.md)
  • RuntimeEvents (docs/backend/RuntimeEvents.md)
  • Backend (docs/backend/Backend.md)
  • PageRouter 컴포넌트 문서