Merge remote-tracking branch 'upstream/develop' into fix-android-qt-libmain

Author: lanmao

doc/source/apis.rst

@@ -5,6 +5,40 @@ Working on Android
 This page gives details on accessing Android APIs and managing other
 interactions on Android.
 
+Handling system bars and Edge-to-Edge enforcement
+-------------------------------------------------
+
+**Egde-to-Edge is enforced on all android apis >=35 by default i.e. Android 15 and above.**
+
+You can control the overall layout and system bars appearance in following ways::
+
+      from android.display_cutout import update_system_ui
+      
+      update_system_ui(
+            "#0f62fe", # status_bar_color: hex color code or rgba (tuple or list) values
+            [0.059, 0.384, 0.996, 1.000], # navigation_bar_color: hex color code or rgba (tuple or list) values
+            "Light", # icon_style: "Dark" means dark icons will be drawn, "Light" means light icons will be drawn, Literal["Dark", or "Light"]
+            True, # pad_status: Adds a padding to top of content_view, Will take effect on Android 15+
+            True, # pad_nav: Adds a padding to bottom of content_view, Will take effect on Android 15+
+      )
+
+
+Handling Immersive Mode
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Immersive mode allows your application to hide the system bars (status bar and navigation bar) for a true full-screen experience, commonly used in games or media players.
+
+You can control the immersive mode behavior and how system bars reappear using the following way::
+
+    from android.display_cutout import set_immersive_mode
+
+    set_immersive_mode(
+        False, # hide_status: True explicitly targets hiding the top status bar, False leaves it visible
+        False, # hide_nav: True explicitly targets hiding the bottom navigation bar/gestural pill, False leaves it visible
+        True, # remove_contrast: True disables the default system-enforced background scrim/contrast behind the bars, ensuring complete transparency when they peek
+    )
+
+
 Storage paths
 -------------
 
@@ -80,6 +114,17 @@ https://developer.android.com/reference/android/Manifest.permission
 Other common tasks
 ------------------
 
+Using NumPY
+~~~~~~~~~~~
+
+It should work out of the box; just ensure `numpy` is included in your requirements.
+If you want better performance, you can also add `libopenblas` to the requirements.
+This allows NumPy to use BLAS/LAPACK acceleration, which can significantly improve linear algebra operations.
+
+Keep in mind that `libopenblas` is a fairly large library (~12 MB per architecture),
+so it will increase your app size. For example, if you build for 4 architectures,
+the APK size may increase by roughly `12 × 4 = 48 MB` (before compression).
+
 Running executables
 ~~~~~~~~~~~~~~~~~~~
 
@@ -388,6 +433,36 @@ This can be used to prevent errors like:
     Because the python function is called from the PythonActivity thread, you
     need to be careful about your own calls.
 
+Handling DarkMode
+~~~~~~~~~~~~~~~~~
+
+The ``android.darkmode`` module provides functionality to detect and respond to
+system dark mode changes on Android devices.
+
+You can set up a listener to monitor dark mode state changes using the
+``set_dark_mode_listener`` function::
+
+    from android.darkmode import set_dark_mode_listener
+
+    def on_dark_mode_changed(is_dark_mode):
+        if is_dark_mode:
+            print('Dark mode is now enabled')
+            # Update your app's theme to dark mode
+        else:
+            print('Dark mode is now disabled')
+            # Update your app's theme to light mode
+
+    # Register the listener
+    set_dark_mode_listener(on_dark_mode_changed)
+
+To remove the listener, simply pass ``None``::
+
+    set_dark_mode_listener(None)
+
+The callback function receives a single boolean parameter ``is_dark_mode`` that
+indicates whether dark mode is currently enabled (``True``) or disabled (``False``).
+
+
 
 Advanced Android API use
 ------------------------

pythonforandroid/bootstraps/_sdl_common/build/templates/strings.tmpl.xml

@@ -3,7 +3,7 @@
     <style name="KivySupportCutout">
         <item name="android:windowNoTitle">true</item>
         <!-- Display cutout is an area on some devices that extends into the display surface -->
-        {% if args.display_cutout != 'never'%}
+        {% if args.display_cutout != 'never' %}
         <item name="android:windowLayoutInDisplayCutoutMode">{{ args.display_cutout }}</item>
         <item name="android:windowTranslucentStatus">true</item>
         <item name="android:windowTranslucentNavigation">true</item>

pythonforandroid/bootstraps/qt/build/src/main/java/org/kivy/android/PythonActivity.java

@@ -3,6 +3,7 @@
 import android.content.Context;
 import android.content.Intent;
 import android.content.pm.PackageManager;
+import android.content.res.Configuration;
 import android.os.Bundle;
 import android.os.PowerManager;
 import android.os.SystemClock;
@@ -233,4 +234,26 @@ public static void _do_start_service(
     public static void stop_service() {
         PythonServiceIntent.stop(PythonActivity.mActivity, PythonService.class);
     }
+
+    public interface DarkModeListener {
+        void onDarkModeChanged(boolean isDarkMode);
+    }
+
+    private DarkModeListener darkModeListener = null;
+
+    public void setDarkModeListener(DarkModeListener listener) {
+        darkModeListener = listener;
+    }
+
+    @Override
+    public void onConfigurationChanged(Configuration newConfig) {
+        int currentNightMode = newConfig.uiMode & Configuration.UI_MODE_NIGHT_MASK;
+        boolean isDarkMode = currentNightMode == Configuration.UI_MODE_NIGHT_YES;
+
+        if (darkModeListener != null) {
+            darkModeListener.onDarkModeChanged(isDarkMode);
+        }
+
+        super.onConfigurationChanged(newConfig);
+    }
 }

pythonforandroid/bootstraps/sdl2/build/src/main/java/org/kivy/android/PythonActivity.java

@@ -5,6 +5,7 @@
 import android.content.Intent;
 import android.content.pm.ActivityInfo;
 import android.content.pm.PackageManager;
+import android.content.res.Configuration;
 import android.content.res.Resources.NotFoundException;
 import android.graphics.Bitmap;
 import android.graphics.BitmapFactory;
@@ -615,6 +616,28 @@ public void requestPermissions(String[] permissions) {
         requestPermissionsWithRequestCode(permissions, 1);
     }
 
+    public interface DarkModeListener {
+        void onDarkModeChanged(boolean isDarkMode);
+    }
+
+    private DarkModeListener darkModeListener = null;
+
+    public void setDarkModeListener(DarkModeListener listener) {
+        darkModeListener = listener;
+    }
+
+    @Override
+    public void onConfigurationChanged(Configuration newConfig) {
+        int currentNightMode = newConfig.uiMode & Configuration.UI_MODE_NIGHT_MASK;
+        boolean isDarkMode = currentNightMode == Configuration.UI_MODE_NIGHT_YES;
+
+        if (darkModeListener != null) {
+            darkModeListener.onDarkModeChanged(isDarkMode);
+        }
+
+        super.onConfigurationChanged(newConfig);
+    }
+
     public static void changeKeyboard(int inputType) {
         if (SDLActivity.keyboardInputType != inputType) {
             SDLActivity.keyboardInputType = inputType;

pythonforandroid/bootstraps/sdl3/build/src/main/java/org/kivy/android/PythonActivity.java

@@ -5,6 +5,7 @@
 import android.content.Intent;
 import android.content.pm.ActivityInfo;
 import android.content.pm.PackageManager;
+import android.content.res.Configuration;
 import android.content.res.Resources.NotFoundException;
 import android.graphics.Bitmap;
 import android.graphics.BitmapFactory;
@@ -614,6 +615,28 @@ public void requestPermissions(String[] permissions) {
         requestPermissionsWithRequestCode(permissions, 1);
     }
 
+    public interface DarkModeListener {
+        void onDarkModeChanged(boolean isDarkMode);
+    }
+
+    private DarkModeListener darkModeListener = null;
+
+    public void setDarkModeListener(DarkModeListener listener) {
+        darkModeListener = listener;
+    }
+
+    @Override
+    public void onConfigurationChanged(Configuration newConfig) {
+        int currentNightMode = newConfig.uiMode & Configuration.UI_MODE_NIGHT_MASK;
+        boolean isDarkMode = currentNightMode == Configuration.UI_MODE_NIGHT_YES;
+
+        if (darkModeListener != null) {
+            darkModeListener.onDarkModeChanged(isDarkMode);
+        }
+
+        super.onConfigurationChanged(newConfig);
+    }
+
     public static void changeKeyboard(int inputType) {
         /*
          if (SDLActivity.keyboardInputType != inputType){

pythonforandroid/bootstraps/webview/build/src/main/java/org/kivy/android/PythonActivity.java

@@ -6,6 +6,7 @@
 import android.content.DialogInterface;
 import android.content.Intent;
 import android.content.pm.PackageManager;
+import android.content.res.Configuration;
 import android.graphics.Bitmap;
 import android.graphics.BitmapFactory;
 import android.graphics.Color;
@@ -542,6 +543,28 @@ public void requestPermissionsWithRequestCode(String[] permissions, int requestC
     public void requestPermissions(String[] permissions) {
         requestPermissionsWithRequestCode(permissions, 1);
     }
+
+    public interface DarkModeListener {
+        void onDarkModeChanged(boolean isDarkMode);
+    }
+
+    private DarkModeListener darkModeListener = null;
+
+    public void setDarkModeListener(DarkModeListener listener) {
+        darkModeListener = listener;
+    }
+
+    @Override
+    public void onConfigurationChanged(Configuration newConfig) {
+        int currentNightMode = newConfig.uiMode & Configuration.UI_MODE_NIGHT_MASK;
+        boolean isDarkMode = currentNightMode == Configuration.UI_MODE_NIGHT_YES;
+
+        if (darkModeListener != null) {
+            darkModeListener.onDarkModeChanged(isDarkMode);
+        }
+
+        super.onConfigurationChanged(newConfig);
+    }
 }
 
 class PythonMain implements Runnable {

pythonforandroid/recipes/android/src/android/darkmode.py

@@ -0,0 +1,57 @@
+from typing import Callable
+
+from jnius import PythonJavaClass, java_method, autoclass
+from android.config import ACTIVITY_CLASS_NAME, ACTIVITY_CLASS_NAMESPACE
+
+_listener = None
+
+
+class DarkModeListener(PythonJavaClass):
+    """
+    A listener class for detecting and handling dark mode changes.
+
+    This class implements the `DarkModeListener` interface in a Python-Java
+    hybrid context through Kivy Android functionality. It listens for changes
+    in the system's dark mode settings and executes a callback upon detecting
+    a change.
+
+    Attributes:
+        on_dark_mode_changed (Callable[[bool], None]): A callback function to
+            handle the event when dark mode status changes. The callback
+            receives a single parameter `is_dark_mode`, which is a boolean
+            indicating whether dark mode is currently enabled.
+    """
+    __javacontext__ = "app"
+    __javainterfaces__ = [ACTIVITY_CLASS_NAMESPACE + '$DarkModeListener']
+
+    def __init__(self, on_dark_mode_changed: Callable[[bool], None]):
+        self.on_dark_mode_changed = on_dark_mode_changed
+
+    @java_method('(Z)V')
+    def onDarkModeChanged(self, is_dark_mode):
+        self.on_dark_mode_changed(is_dark_mode)
+
+
+def set_dark_mode_listener(on_dark_mode_changed: Callable[[bool], None] | None) -> None:
+    """
+    Sets a listener to monitor changes in the dark mode state.
+
+    This function assigns a provided callback to handle changes in the
+    dark mode settings. The callback will be invoked with a boolean
+    argument indicating the current dark mode state.
+
+    Args:
+        on_dark_mode_changed: A callable that accepts a single boolean
+            parameter indicating whether dark mode is active.
+
+    Returns:
+        None
+    """
+    global _listener
+    activity = autoclass(ACTIVITY_CLASS_NAME).mActivity
+    if on_dark_mode_changed:
+        _listener = DarkModeListener(on_dark_mode_changed)
+        activity.setDarkModeListener(_listener)
+    else:
+        activity.setDarkModeListener(on_dark_mode_changed)
+        _listener = None