Skip to content
This repository was archived by the owner on Jul 6, 2026. It is now read-only.

ANDROID_15_ADAPTATION.md

Latest commit

 

History

History
333 lines (267 loc) · 11.6 KB

ANDROID_15_ADAPTATION.md

File metadata and controls

333 lines (267 loc) · 11.6 KB
Raw

Android 15/16 Adaptation Summary

Overview

This document summarizes the Android 15 and Android 16 adaptation work completed for the ImmersionBar library. The library now supports Android 15's enforced Edge-to-Edge mode and WindowInsetsController API while maintaining backward compatibility with Android 4.4+.

Completed High-Priority Tasks

1. Version Adapter Utility Class

File: immersionbar/src/main/java/com/gyf/immersionbar/VersionAdapter.java

Created a centralized version detection utility:

  • isAndroid15OrAbove() - Detect Android 15+ (API 35)
  • isAndroid16OrAbove() - Detect Android 16+ (API 36)
  • isAndroid11OrAbove() - Detect Android 11+ (WindowInsetsController support)
  • shouldUseWindowInsetsController() - Check if WindowInsetsController should be used
  • supportsPredictiveBack() - Check predictive back gesture support (Android 13+)
  • supportsNativeStatusBarDarkFont() - Check native dark font support (Android 6+)
  • supportsNavigationBarDarkIcon() - Check dark navigation icon support (Android 8+)
  • supportsDisplayCutout() - Check display cutout API support (Android 9+)
  • getRecommendedApproach() - Get recommended system bar control method
  • getVersionInfo() - Get detailed version info for debugging

2. WindowInsets Change Listener Interface

File: immersionbar/src/main/java/com/gyf/immersionbar/OnInsetsChangeListener.java

New listener interface for Android 15+ Edge-to-Edge mode:

public interface OnInsetsChangeListener {
    void onInsetsChanged(int top, int bottom, int left, int right);
}

This allows developers to react to system bar insets changes in real-time.

3. BarParams Android 15 Fields

File: immersionbar/src/main/java/com/gyf/immersionbar/BarParams.java

Added new configuration fields:

  • edgeToEdgeEnabled - Enable/disable Edge-to-Edge mode (default: true)
  • onInsetsChangeListener - WindowInsets change listener
  • useWindowInsetsController - Use WindowInsetsController API (auto-detected)
  • debugPrintVersionInfo - Print version adaptation info for debugging
  • debugForceEdgeToEdge - Force Edge-to-Edge on lower Android versions (testing only)

4. BarConfig WindowInsets API Support

File: immersionbar/src/main/java/com/gyf/immersionbar/BarConfig.java

Enhanced BarConfig with Android 15+ WindowInsets support:

  • New Fields:

    • mSystemBarsInsets - System bars insets (status + navigation)
    • mDisplayCutoutInsets - Display cutout insets
    • mNavigationBarsInsets - Navigation bar insets

  • New Methods:

    • initForAndroid15(Activity) - Initialize using WindowMetrics and WindowInsets.Type
    • toAndroidXInsets(Insets) - Convert platform Insets to AndroidX
    • initLegacy(Activity) - Traditional initialization for Android 14 and below
    • getSystemBarsInsets() - Get system bars insets
    • getDisplayCutoutInsets() - Get display cutout insets
    • getNavigationBarsInsets() - Get navigation bars insets

Changed final fields to non-final to support dual initialization paths.

5. ImmersionBar Android 15 Adaptation

File: immersionbar/src/main/java/com/gyf/immersionbar/ImmersionBar.java

Core Implementation Changes:

Modified setBar() method (line 407):

void setBar() {
    // Android 15+ 优先使用 Edge-to-Edge 模式
    if (VersionAdapter.isAndroid15OrAbove() && mBarParams.edgeToEdgeEnabled) {
        initEdgeToEdgeForAndroid15();
        hideBarAboveR();
        // ... listener registration
        return;
    }
    // ... legacy code for Android 14 and below
}

New Methods:

  1. initEdgeToEdgeForAndroid15() (line 932):

    • Handles Android 15+ Edge-to-Edge mode
    • Uses WindowInsetsController for status/navigation bar appearance
    • Supports auto dark mode
    • Registers WindowInsets listener

  2. setupInsetsListener() (line 979):

    • Sets up OnApplyWindowInsetsListener
    • Extracts system bars insets
    • Notifies OnInsetsChangeListener

New Public APIs:

Added builder methods for Android 15 configuration:

public ImmersionBar setOnInsetsChangeListener(OnInsetsChangeListener listener)
public ImmersionBar edgeToEdgeEnabled(boolean enabled)
public ImmersionBar debugPrintVersionInfo(boolean enabled)
public ImmersionBar debugForceEdgeToEdge(boolean enabled)

6. Kotlin Extension Support

File: immersionbar-ktx/src/main/java/com/gyf/immersionbar/ktx/ImmersionBar.kt

Added Kotlin extensions for Android 15+ features:

// Version detection
val isAndroid15OrAbove: Boolean
val isAndroid11OrAbove: Boolean
val recommendedApproach: String
val versionInfo: String

These extensions automatically work with the existing DSL-style API through the builder pattern.

API Changes Summary

Breaking Changes

None - All changes are additive and backward compatible.

New APIs

Java API:

// Builder methods
ImmersionBar.with(this)
    .edgeToEdgeEnabled(true)  // Enable Edge-to-Edge (default on Android 15+)
    .setOnInsetsChangeListener(new OnInsetsChangeListener() {
        @Override
        public void onInsetsChanged(int top, int bottom, int left, int right) {
            // Handle insets changes
        }
    })
    .debugPrintVersionInfo(true)  // Enable debug logging
    .init();

// Version detection
boolean isAndroid15 = VersionAdapter.isAndroid15OrAbove();
String approach = VersionAdapter.getRecommendedApproach();

Kotlin API:

// DSL style
immersionBar {
    edgeToEdgeEnabled(true)
    setOnInsetsChangeListener { top, bottom, left, right ->
        // Handle insets changes
    }
    debugPrintVersionInfo(true)
}

// Extensions
if (isAndroid15OrAbove) {
    Log.d("Version", versionInfo)
    Log.d("Approach", recommendedApproach)
}

Android 15 Key Changes Addressed

1. ✅ Edge-to-Edge Enforcement

  • Status: Fully implemented
  • Details: Android 15 (API 35) apps with targetSdk 35+ are forced into Edge-to-Edge mode
  • Solution: Automatic detection and handling via initEdgeToEdgeForAndroid15()

2. ✅ WindowInsetsController Migration

  • Status: Implemented for Android 11+
  • Details: Replaced deprecated SYSTEM_UI_FLAG_* with WindowInsetsController
  • Solution: Dual path - WindowInsetsController for Android 11+ (line 932), legacy flags for older versions

3. ✅ WindowInsets API Enhancements

  • Status: Fully implemented
  • Details: Enhanced WindowInsets API with Type-based queries
  • Solution: BarConfig.initForAndroid15() uses WindowMetrics and WindowInsets.Type

4. ⚠️ Predictive Back Gesture

  • Status: Detection available
  • Details: Android 13+ predictive back support
  • Solution: VersionAdapter.supportsPredictiveBack() for detection (app-level implementation needed)

5. ✅ Display Cutout Improvements

  • Status: Implemented
  • Details: Better notch/cutout handling
  • Solution: mDisplayCutoutInsets field in BarConfig with getter method

Pending Medium/Low Priority Tasks

Medium Priority:

  1. SYSTEM_UI_FLAG_ Complete Migration*

    • Current status: Dual-path implementation (both old and new APIs work)
    • Remaining: Could deprecate SYSTEM_UI_FLAG_* usage warnings
    • Location: ImmersionBar.java lines 420-440

  2. Gesture Navigation Detection Enhancement

    • Current: Basic gesture detection via GestureUtils
    • Enhancement: Better Android 15 gesture mode detection

  3. Display Cutout Edge Cases

    • Enhancement: More comprehensive cutout handling for foldables

Low Priority:

  1. Android 16 Preparation

    • Status: Version detection ready (isAndroid16OrAbove())
    • Next: Monitor Android 16 preview releases for changes

  2. Documentation Updates

    • Create migration guide for existing users
    • Add Android 15 specific examples
    • Update README with Edge-to-Edge best practices

Build Configuration Updates

Gradle Versions

  • Gradle: 8.5
  • AGP: 8.2.2
  • Kotlin: 1.9.22
  • CompileSdk: 31 (supports APIs up to Android 12, uses hardcoded constants for 13+)

Key Fixes Applied:

  1. Fixed classifier → archiveClassifier deprecation
  2. Added namespace declarations for all modules
  3. Fixed Kotlin/Java JVM target compatibility
  4. Added Java 21 compatibility flags for ButterKnife
  5. Enabled BuildConfig generation in AGP 8.x
  6. Fixed R class final fields for ButterKnife

Testing Status

Compilation: ✅ PASSED

All modules compile successfully:

  • immersionbar (core library)
  • immersionbar-ktx (Kotlin extensions)
  • immersionbar-components (components)
  • immersionbar-sample (sample app)

Build Outputs:

  • ✅ immersionbar-debug.aar
  • ✅ immersionbar-ktx-debug.aar
  • ✅ immersionbar-components-debug.aar
  • ✅ immersionbar-sample-debug.apk

Runtime Testing:

  • ⏳ Pending: Requires physical Android 15 device or emulator
  • ⏳ Pending: Edge-to-Edge behavior verification
  • ⏳ Pending: WindowInsets listener functionality

Migration Guide for Existing Users

No Breaking Changes

Existing code continues to work without modifications:

// This still works as before
ImmersionBar.with(this)
    .statusBarColor(R.color.colorPrimary)
    .navigationBarColor(R.color.colorPrimary)
    .init();

Recommended for Android 15+ Support

ImmersionBar.with(this)
    .statusBarColor(R.color.colorPrimary)
    .navigationBarColor(R.color.colorPrimary)
    .setOnInsetsChangeListener((top, bottom, left, right) -> {
        // Adjust your layout based on insets
        findViewById(R.id.content).setPadding(0, top, 0, bottom);
    })
    .init();

Debug Mode for Testing

ImmersionBar.with(this)
    .debugPrintVersionInfo(true)  // See which approach is used
    .init();
// Check logcat for: "ImmersionBar: Android 15+ Edge-to-Edge mode: ..."

Files Modified/Created

New Files:

  1. immersionbar/src/main/java/com/gyf/immersionbar/VersionAdapter.java
  2. immersionbar/src/main/java/com/gyf/immersionbar/OnInsetsChangeListener.java
  3. ANDROID_15_ADAPTATION.md (this file)

Modified Files:

  1. immersionbar/src/main/java/com/gyf/immersionbar/BarParams.java
  2. immersionbar/src/main/java/com/gyf/immersionbar/BarConfig.java
  3. immersionbar/src/main/java/com/gyf/immersionbar/ImmersionBar.java
  4. immersionbar-ktx/src/main/java/com/gyf/immersionbar/ktx/ImmersionBar.kt
  5. Build configuration files (build.gradle, gradle.properties, etc.)

Next Steps

Immediate:

  1. ✅ Code compilation - COMPLETE
  2. ⏳ Runtime testing on Android 15 emulator/device
  3. ⏳ Edge-to-Edge behavior verification
  4. ⏳ WindowInsets listener functionality testing

Short-term:

  1. Create sample app demonstrations for Android 15 features
  2. Write migration documentation
  3. Update README with Android 15 support details
  4. Add unit tests for VersionAdapter

Long-term:

  1. Monitor Android 16 preview releases
  2. Deprecate SYSTEM_UI_FLAG_* usage (with migration period)
  3. Consider targetSdk bump to 35 for full Android 15 testing
  4. Performance optimization for WindowInsets handling

Conclusion

The ImmersionBar library has been successfully adapted for Android 15 and prepared for Android 16, with full backward compatibility maintained for Android 4.4+. The implementation uses a clean dual-path approach:

  • Android 15+: WindowInsetsController + Edge-to-Edge mode
  • Android 11-14: WindowInsetsController (recommended)
  • Android 5-10: SYSTEM_UI_FLAG_* (legacy)
  • Android 4.4: Translucent flags

All high-priority adaptation tasks have been completed successfully, with no breaking changes to the public API.

Adaptation Date: 2025-01-03 Android Target: Android 15 (API 35) + Android 16 (API 36) Backward Compatibility: Android 4.4+ (API 19+) Status: ✅ High-priority tasks completed, compilation successful