System
Controller for managing system bars (StatusBar and NavigationBar) independently.
Provides comprehensive control over system bar appearance, visibility, and size measurement.
시스템 바(StatusBar와 NavigationBar)를 독립적으로 관리하는 컨트롤러입니다.
시스템 바의 외관, 가시성 및 크기 측정에 대한 종합적인 제어를 제공합니다.
Why this class exists / 이 클래스가 필요한 이유:
Works independently with only Window object (usable in Activity, Dialog, FloatingWindow, etc.)
Handles API 35+ edge-to-edge breaking changes with custom View overlay approach
Provides both stable (system-defined) and visible (current) size measurements
Simplifies system bar control without requiring Activity inheritance
Window 객체만으로 독립적으로 작동 (Activity, Dialog, FloatingWindow 등에서 사용 가능)
커스텀 View 오버레이 방식으로 API 35+ edge-to-edge breaking change 처리
Stable(시스템 정의)과 Visible(현재) 크기 측정을 모두 제공
Activity 상속 없이 시스템 바 제어 간소화
Design decisions / 설계 결정 이유:
Window-only dependency: No Activity requirement enables broader use cases
Rect return type: Returns window coordinates relative to decorView (left, top, right, bottom)
Stable vs Visible: Stable returns system-defined size, Visible returns actual current size
View caching: Reuses background views for API 35+ to prevent memory churn
No permissions required: System bar control doesn't require runtime permissions
Window만 의존: Activity 요구사항이 없어 더 광범위한 사용 사례 가능
Rect 반환 타입: decorView 기준 윈도우 좌표 반환 (left, top, right, bottom)
Stable vs Visible: Stable은 시스템 정의 크기, Visible은 실제 현재 크기 반환
View 캐싱: API 35+에서 배경 뷰를 재사용하여 메모리 낭비 방지
권한 불필요: 시스템 바 제어는 런타임 권한이 필요 없음
null vs Rect() return policy: null means WindowInsets not ready (early initialization before view measurement),
Rect() means system bar is hidden or doesn't exist on deviceStable vs Visible difference: Stable is system-defined size, constant even when hidden (use for layout calculations),
Visible is current actual size, becomes 0 when hidden (use for padding/margin)Reset visibility policy: resetStatusBarColor()/resetNavigationBarColor() restore visibility by default (restoreVisibility=true),
set restoreVisibility=false to keep current hidden state (e.g., fullscreen video player)Edge-to-edge mode policy: Disabled by default (decorFitsSystemWindows=true), content starts below system bars.
Call setEdgeToEdgeMode(true) to enable edge-to-edge layout (content extends behind system bars).
User must manually handle WindowInsets when edge-to-edge is enablednull vs Rect() 반환 정책: null은 WindowInsets 미준비 상태(뷰 측정 전 초기화 단계),
Rect()는 시스템 바가 숨겨졌거나 기기에 존재하지 않는 경우Stable vs Visible 차이: Stable은 시스템 정의 크기로 숨겨져도 일정(레이아웃 계산용),
Visible은 현재 실제 크기로 숨기면 0이 됨(패딩/마진용)Reset 가시성 정책: resetStatusBarColor()/resetNavigationBarColor()는 기본적으로 가시성 복원(restoreVisibility=true),
현재 숨김 상태 유지 필요 시 restoreVisibility=false 사용(예: 전체화면 비디오 플레이어)Edge-to-edge 모드 정책: 기본적으로 비활성화(decorFitsSystemWindows=true), 컨텐츠는 시스템 바 아래부터 시작.
setEdgeToEdgeMode(true) 호출 시 edge-to-edge 레이아웃 활성화(컨텐츠가 시스템 바 뒤까지 확장).
edge-to-edge 활성화 시 사용자가 WindowInsets를 수동으로 처리해야 함
Usage / 사용법:
val controller = SystemBarController(window)
// Get system bar sizes
val statusBarStable = controller.getStatusBarStableRect()
val statusBarVisible = controller.getStatusBarVisibleRect()
// Set colors
controller.setStatusBarColor(Color.RED, isDarkIcon = false)
controller.setNavigationBarColor(Color.BLUE, isDarkIcon = true)
// Control visibility
controller.setStatusBarVisible() // show
controller.setNavigationBarGone() // hide
// Reset to initial state
controller.resetStatusBarColor()
controller.resetNavigationBarColor()
// Clean up
controller.onDestroy()
```<br><br>
@param window The Window object to control system bars.<br><br>
시스템 바를 제어할 Window 객체.<br>Functions
Returns the window coordinates of the system-defined (stable) NavigationBar area.
This value remains constant even if the NavigationBar is hidden.
Supports bottom, left, and right NavigationBar positions.
시스템 정의(stable) NavigationBar 영역의 윈도우 좌표를 반환합니다.
이 값은 NavigationBar가 숨겨진 경우에도 일정하게 유지됩니다.
하단, 왼쪽, 오른쪽 NavigationBar 위치를 지원합니다.
Returns navigation bar stable state using unified semantic states.
통합된 의미 상태를 사용하여 네비게이션 바 stable 상태를 반환합니다.
Returns the window coordinates of the currently visible NavigationBar area.
Uses WindowInsetsCompat with visibility detection. Returns empty Rect if NavigationBar is hidden.
Supports bottom, left, and right NavigationBar positions.
현재 보이는 NavigationBar 영역의 윈도우 좌표를 반환합니다.
WindowInsetsCompat과 가시성 감지를 사용합니다. NavigationBar가 숨겨진 경우 빈 Rect를 반환합니다.
하단, 왼쪽, 오른쪽 NavigationBar 위치를 지원합니다.
Returns navigation bar visible state using unified semantic states.
통합된 의미 상태를 사용하여 네비게이션 바 visible 상태를 반환합니다.
Gets information about required permissions and their status.
필요한 권한과 그 상태에 대한 정보를 가져옵니다.
Returns the window coordinates of the system-defined (stable) StatusBar area.
This value remains constant even if the StatusBar is hidden.
시스템 정의(stable) StatusBar 영역의 윈도우 좌표를 반환합니다.
이 값은 StatusBar가 숨겨진 경우에도 일정하게 유지됩니다.
Returns status bar stable state using unified semantic states.
통합된 의미 상태를 사용하여 상태바 stable 상태를 반환합니다.
Returns the window coordinates of the currently visible StatusBar area.
Uses WindowInsetsCompat with visibility detection. Returns empty Rect if StatusBar is hidden.
현재 보이는 StatusBar 영역의 윈도우 좌표를 반환합니다.
WindowInsetsCompat과 가시성 감지를 사용합니다. StatusBar가 숨겨진 경우 빈 Rect를 반환합니다.
Returns status bar visible state using unified semantic states.
통합된 의미 상태를 사용하여 상태바 visible 상태를 반환합니다.
Checks whether edge-to-edge mode is currently enabled.
edge-to-edge 모드가 현재 활성화되어 있는지 확인합니다.
Checks if a specific permission is granted.
특정 권한이 부여되었는지 확인합니다.
Refreshes the permission status. Call this after requesting permissions.
권한 상태를 새로고침합니다. 권한 요청 후 이를 호출하세요.
Resets the NavigationBar to its initial state.
Removes custom background views on API 35+ and restores theme default color on older versions.
네비게이션 바를 초기 상태로 복원합니다.
API 35+에서는 커스텀 배경 뷰를 제거하고 이전 버전에서는 테마 기본 색상을 복원합니다.
Resets the StatusBar to its initial state.
Removes custom background views on API 35+ and restores theme default color on older versions.
StatusBar를 초기 상태로 초기화합니다.
API 35+에서는 커스텀 배경 뷰를 제거하고 이전 버전에서는 테마 기본 색상을 복원합니다.
Enables or disables edge-to-edge mode.
When enabled, the layout extends behind system bars (StatusBar and NavigationBar).
When disabled, the layout starts below system bars (default behavior).
edge-to-edge 모드를 활성화하거나 비활성화합니다.
활성화 시 레이아웃이 시스템 바(StatusBar와 NavigationBar) 뒤까지 확장됩니다.
비활성화 시 레이아웃은 시스템 바 아래부터 시작합니다 (기본 동작).
Sets the NavigationBar color.
네비게이션 바 색상을 설정합니다.
Sets the NavigationBar icon appearance mode (Dark or Light).
It may not work on certain devices.
NavigationBar 아이콘 모드를 설정합니다 (Dark 또는 Light).
특정 장치에서는 작동하지 않을 수 있습니다.
Hides the NavigationBar.
Uses WindowInsetsController on API 30+ and SYSTEM_UI_FLAG on older versions.
NavigationBar를 숨깁니다.
API 30+에서는 WindowInsetsController를 사용하고 이전 버전에서는 SYSTEM_UI_FLAG를 사용합니다.
Shows the NavigationBar.
Uses WindowInsetsController on API 30+ and SYSTEM_UI_FLAG on older versions.
NavigationBar를 표시합니다.
API 30+에서는 WindowInsetsController를 사용하고 이전 버전에서는 SYSTEM_UI_FLAG를 사용합니다.
Sets the StatusBar color.
상태 표시줄 색상을 설정합니다.
Sets the StatusBar icon appearance mode (Dark or Light).
It may not work on certain devices.
StatusBar 아이콘 모드를 설정합니다 (Dark 또는 Light).
특정 장치에서는 작동하지 않을 수 있습니다.
Hides the StatusBar.
Uses WindowInsetsController on API 30+ and FLAG_FULLSCREEN on older versions.
StatusBar를 숨깁니다.
API 30+에서는 WindowInsetsController를 사용하고 이전 버전에서는 FLAG_FULLSCREEN을 사용합니다.
Shows the StatusBar.
Uses WindowInsetsController on API 30+ and FLAG_FULLSCREEN on older versions.
StatusBar를 표시합니다.
API 30+에서는 WindowInsetsController를 사용하고 이전 버전에서는 FLAG_FULLSCREEN을 사용합니다.