Toga

This is a minor bugfix release, correcting an issue with Toga's support for Python 3.13 on Android.

Bugfixes

* On macOS, apps that specify both `document_types` and a `main_window` no longer display the document selection dialog on startup. (2860)
* The integration with Android's event loop has been updated to support Python 3.13. (2907)


Backward Incompatible Changes

* Toga no longer supports Python 3.8. (2888)
* Android applications should update their Gradle requirements to use version 1.12.0 of the Material library (``com.google.android.material:material:1.12.0``). (2890)
* Android applications should update their Gradle requirements to use version 6.1.20 of the OSMDroid library (``org.osmdroid:osmdroid-android:6.1.20``). (2890)


Misc

* 2868, 2869, 2870, 2876, 2877, 2884, 2885, 2886, 2887, 2893, 2897, 2898, 2899, 2900, 2901, 2902, 2903, 2904, 2905, 2906, 2912

Features

* The GTK backend was modified to use PyGObject's native asyncio handling, instead of GBulb. (2550)
* The ActivityIndicator widget is now supported on iOS. (2829)

Bugfixes

* Windows retain their original size after being unminimized on Windows. (2729)
* DOM storage is now enabled for WebView on Android. (2767)
* A macOS app in full-screen mode now correctly displays the contents of windows that use a `toga.Box()` as the top-level content. (2796)
* Asynchronous tasks are now protected from garbage collection while they are running. This could lead to asynchronous tasks terminating unexpectedly with an error under some conditions. (2809)
* When a handler is a generator, control will now always be released to the event loop between iterations, even if no sleep interval or a sleep interval of 0 is yielded. (2811)
* When the X button is clicked for the About dialog on GTK, it is now properly destroyed. (2812)
* The Textual backend is now compatible with versions of Textual after v0.63.3. (2822)
* The event loop is now guaranteed to be running when your app's `startup()` method is invoked. This wasn't previously the case on macOS and Windows. (2834)
* iOS apps now correctly account for the size of the navigation bar when laying out app content. (2836)
* A memory leak when using Divider or Switch widgets on iOS was resolved. (2849)
* Apps bundled as standalone frozen binaries (e.g., POSIX builds made with PyInstaller) no longer crash on startup when trying to resolve the app icon. (2852)

Misc

* 2088, 2708, 2715, 2792, 2799, 2802, 2803, 2804, 2807, 2823, 2824, 2825, 2826, 2846, 2847, 2848

Features
--------

* Toga can now define apps that persist in the background without having any open windows. (97)
* Apps can now add items to the system tray. (97)
* It is now possible to use an instance of Window as the main window of an app. This allows the creation of windows that don't have a menu bar or toolbar decoration. (1870)
* The initial position of each newly created window is now different, cascading down the screen as windows are created. (2023)
* The API for Documents and document types has been finalized. Document handling behavior is now controlled by declaring document types as part of your `toga.App` definition. (2209)
* Toga can now define an app whose life cycle isn't tied to a single main window. (2209)
* The Divider widget was implemented on iOS. (2478)
* Commands can now be retrieved by ID. System-installed commands (such as "About" and "Visit Homepage") are installed using a known ID that can be used at runtime to manipulate those commands. (2636)
* A `MainWindow` can now have an `on_close` handler. If a request is made to close the main window, the `on_close` handler will be evaluated; app exit handling will only be processed if the close handler allows the close to continue. (2643)
* Dialogs can now be displayed relative to an app, in addition to be being modal to a window. (2669)
* An `on_running` event handler was added to `toga.App`. This event will be triggered when the app's main loop starts. (2678)
* The `on_exit` handler for an app can now be defined by overriding the method on the `toga.App` subclass. (2678)
* CommandSet now exposes a full set and dictionary interface. Commands can be added to a CommandSet using `[]` notation and a command ID; they can be removed using set-like `remove()` or `discard()` calls with a Command instance, or using dictionary-like `pop()` or `del` calls with the command ID. (2701)
* WebView2 on Winforms now uses the v1.0.2592.51 WebView2 runtime DLLs. (2764)

Bugfixes
--------

* The order of creation of system-level commands is now consistent between platforms. Menu creation is guaranteed to be deferred until the user's startup method has been invoked. (2619)
* The type of SplitContainer's content was modified to be a list, rather than a tuple. (2638)
* Programmatically invoking `close()` on the main window will now trigger `on_exit` handling. Previously `on_exit` handling would only be triggered if the close was initiated by a user action. (2643)
* GTK apps no longer have extra padding between the menu bar and the window content when the app does not have a toolbar. (2646)
* On Winforms, the window of an application that is set as the main window is no longer shown as a result of assigning the window as `App.main_window`. (2653)
* Menu items on macOS are now able to correctly bind to the arrow and home/end/delete keys. (2661)
* On GTK, the currently selected tab index on an `OptionContainer` can now be retrieved inside an `on_select` handler. (2703)
* The WebView can now be loaded when using Python from the Windows Store. (2752)
* The WebView and MapView widgets now log an error if initialization fails. (2779)


Backward Incompatible Changes
-----------------------------

* The `add_background_task()` API on `toga.App` has been deprecated. Background tasks can be implemented using the new `on_running` event handler, or by using :any:`asyncio.create_task`. (2099)
* The API for Documents and Document-based apps has been significantly modified. Unfortunately, these changes are not backwards compatible; any existing Document-based app will require modification.

The `DocumentApp` base class is no longer required. Apps can subclass `App` directly, passing the document types as a `list` of `Document` classes, rather than a mapping of extension to document type.

The API for `Document` subclasses has also changed:

* A path is no longer provided as an argument to the Document constructor;

* The `document_type` is now specified as a class property called `description`; and

* Extensions are now defined as a class property of the `Document`; and

* The `can_close()` handler is no longer honored. Documents now track if they are modified, and have a default `on_close` handler that uses the modification status of a document to control whether a document can close. Invoking `touch()` on document will mark a document as modified. This modification flag is cleared by saving the document. (2209)
* It is no longer possible to create a toolbar on a `Window` instance. Toolbars can only be added to `MainWindow` (or subclass). (2646)
* The default title of a `toga.Window` is now the name of the app, rather than `"Toga"`. (2646)
* The APIs on `Window` for displaying dialogs (`info_dialog()`, `question_dialog()`, etc) have been deprecated. They can be replaced with creating an instance of a `Dialog` class (e.g., `InfoDialog`), and passing that instance to `window.dialog()`. (2669)

Documentation
-------------

* Building Toga's documentation now requires the use of Python 3.12. (2745)

Misc
----

* 2382, 2635, 2640, 2647, 2648, 2654, 2657, 2660, 2665, 2668, 2675, 2676, 2677, 2682, 2683, 2684, 2689, 2693, 2694, 2695, 2696, 2697, 2698, 2699, 2709, 2710, 2711, 2712, 2722, 2723, 2724, 2726, 2727, 2728, 2733, 2734, 2735, 2736, 2739, 2740, 2742, 2743, 2755, 2756, 2757, 2758, 2760, 2771, 2775, 2776, 2777, 2783, 2788, 2789, 2790

Features

* The typing for Toga's API surface was updated to be more precise. (2252)
* APIs were added for replacing a widget in an existing layout, and for obtaining the index of a widget in a list of children. (2301)
* The content of a window can now be set when the window is constructed. (2307)
* Size and position properties now return values as a `Size` and `Position` `namedtuple`, respectively. `namedtuple` objects support addition and subtraction operations. Basic tuples can still be used to *set* these properties. (2388)
* Android deployments no longer require the SwipeRefreshLayout component unless the app uses the Toga DetailedList widget. (2454)

Bugfixes

* Invocation order of TextInput on_change and validation is now correct. (2325)
* Dialog windows are now properly modal when using the GTK backend. (2446)
* The Button testbed tests can accommodate minor rendering differences on Fedora 40. (2583)
* On macOS, apps will now raise a warning if camera permissions have been requested, but those permissions have not been declared as part of the application metadata. (2589)

Documentation

* The instructions for adding a change note to a pull request have been clarified. (2565)
* The minimum supported Linux release requirements were updated to Ubuntu 20.04 or Fedora 32. (2566)
* The first-time contributor README link has been updated. (2588)
* Typos in the usage examples of `toga.MapPin` were corrected. (2617)

Misc

* 2567, 2568, 2569, 2570, 2571, 2576, 2577, 2578, 2579, 2580, 2593, 2600, 2601, 2602, 2604, 2605, 2606, 2614, 2621, 2625, 2626, 2627, 2629, 2631, 2632

Bugfixes

* The mechanism for loading application icons on macOS was corrected to account for how Xcode populates ``Info.plist`` metadata. (2558)

Misc

* 2555, 2557, 2560

Features

* A MapView widget was added. (727)
* Toga apps can now access details about the screens attached to the computer. Window position APIs have been extended to allow for placement on a specific screen, and positioning relative to a specific screen. (1930)
* Key definitions were added for number pad keys on GTK. (2232)
* Toga can now be extended, via plugins, to create Toga Images from external image classes (and vice-versa). (2387)
* Non-implemented features now raise a formal warning, rather than logging to the console. (2398)
* Support for Python 3.13 was added. (2404)
* Toga's release processes now include automated testing on ARM64. (2404)
* An action for a Toga command can now be easily modified after initial construction. (2433)
* A geolocation service was added for Android, iOS and macOS. (2462)
* When a Toga app is packaged as a binary, and no icon is explicitly configured, Toga will now use the binary's icon as the app icon. This means it is no longer necessary to include the app icon as data in a `resources` folder if you are packaging your app for distribution. (2527)


Bugfixes

* Compatibility with macOS 14 (Sonoma) was added. (2188, 2383)
* Key handling for Insert, Delete, NumLock, ScrollLock, and some other esoteric keys was added for GTK and Winforms. Some uses of bare Shift on GTK were also improved. (2220)
* A crash observed on iOS devices when taking photographs has been resolved. (2381)
* Key shortcuts for punctuation and special keys (like Page Up and Escape) were added for GTK and Winforms. (2414)
* The placement of menu items relative to sub-menus was corrected on GTK. (2418)
* Tree data nodes can now be modified prior to tree expansion. (2439)
* Some memory leaks associated with macOS Icon and Image storage were resolved. (2472)
* The stack trace dialog no longer raises an `asyncio.TimeoutError` when displayed. (2474)
* The integration of the `asyncio` event loop was simplified on Android. As a result, `asyncio.loop.run_in_executor()` now works as expected. (2479)
* Some memory leaks associated with the macOS Table, Tree and DetailedList widgets were resolved. (2482)
* Widget IDs can now be reused after the associated widget's window is closed. (2514)
* :class:`~toga.WebView` is now compatible with Linux GTK environments only providing WebKit2 version 4.1 without version 4.0. (2527)


Backward Incompatible Changes

* The macOS implementations of `Window.as_image()` and `Canvas.as_image()` APIs now return images in native device resolution, not CSS pixel resolution. This will result in images that are double the previous size on Retina displays. (1930)


Documentation

* The camera permission requirements on macOS apps have been clarified. (2381)
* Documentation for the class property `toga.App.app` was added. (2413)
* The documentation landing page and some documentation sections were reorganized. (2463)
* The README badges were updated to display correctly on GitHub. (2491)
* The links to ReadTheDocs were updated to better arbitrate between linking to the stable version or the latest version. (2510)
* An explicit system requirements section was added to the documentation for widgets that require the installation of additional system components. (2544)
* The system requirements were updated to be more explicit and now include details for OpenSUSE Tumbleweed. (2549)


Misc

* 2153, 2372, 2389, 2390, 2391, 2392, 2393, 2394, 2396, 2397, 2400, 2403, 2405, 2406, 2407, 2408, 2409, 2422, 2423, 2427, 2440, 2442, 2445, 2448, 2449, 2450, 2457, 2458, 2459, 2460, 2464, 2465, 2466, 2467, 2470, 2471, 2476, 2487, 2488, 2498, 2501, 2502, 2503, 2504, 2509, 2518, 2519, 2520, 2521, 2522, 2523, 2532, 2533, 2534, 2535, 2536, 2537, 2538, 2539, 2540, 2541, 2542, 2546, 2552