0.5.4

Features

• It is now possible to draw bitmap images on a Canvas. (#995)
• The DetailedList widget on Windows has been massively improved, and now matches the visual appearance on other platforms. (#2110, #4319)
• Widget implementations are now contributed by entry points, allowing lazy loading on a per-widget basis. (#2687)
• Toga's WinForms backend can now be used on ARM64 machines with a native ARM64 Python interpreter. (#2782)
• The GTK4 backend now integrates with libadwaita for ActivityIndicator, Window, and App. (#3069)
• Toga Positron now has a bootstrap for FastAPI-based websites. (#3327)
• The WebView widget now supports an on_navigation_starting handler to prevent user-defined URLs from being loaded (#3442)
• The Qt backend now has implementations for all widgets, plus support for dialogs, fonts and status icons. (#3914)
• The currently active backend can now be retrieved at runtime using toga.backend. (#3923)
• Android apps now support the use of webbrowser.open(). (#3932)
• The on_webview_load handler is now supported on Android (#4036)
• Apps built with Toga no longer requires the "Requires Full Screen" key in the app template, allowing support for multitasking on iPadOS. (#4043)
• The columns of Table and Tree widgets can now be specified using Column objects that provide a richer interface for configuring data access. (#4091)
• The header row of a Table and Tree widget can now be hidden. (#4091)
• The rgb and hsl color representation classes now declare slots, reducing memory usage. (#4136)
• The Canvas widget can now draw rounded rectangles. (#4161)
• The Table widget on WinForms can now display icons in all columns. Previously, icons were only supported in the first column. (#4164)
• ListSource and TreeSource now allow mapping-based data to be used without explicitly providing accessors. (#4221)
• The web backend now uses WebAwesome instead of Shoelace to provide web components. (#4227)
• The Switch widget is now supported in the Textual backend. (#4230)
• The Tree widget is now supported in the Windows backend. (#4235, #4360)
• macOS and iOS apps can now use any font that has been registered with the operating system. (#4307)
• The Canvas widget now has save and restore methods, and supports setting the drawing context attributes fill_style, stroke_style, line_width, and line_dash. (#4332)
• The Toga repository now has an AGENTS.md file and Spec Kit constitution to provide assistance for Generative AI tools. (#4344)

Bugfixes

• The Canvas widget on Android, Qt and WinForms now matches the behavior of the HTML Canvas when a transform is applied while preparing a path. (#2206)
• Calling stroke() or fill() in a Canvas context no longer clears the current path. (#2207)
• SplitContainers in a non-primary tab of OptionContainer will now correctly apply its split on Cocoa. (#2288)
• The key event handling code now supports non-US keyboards better on macOS. More keys are supported on Qt. (#2428)
• Memory leaks for all remaining widgets have been resolved on all leaking platforms. (#2849)
• Apps no longer crash if an icon file exists but is cannot be loaded. Toga now logs a warning and falls back to a default icon. (#3565)
• When creating an Image from a file path, it's now guaranteed that the file won't remain open after construction. (#3730)
• On Android, DetailedList now uses theme-resolved text colors (Primary/Secondary) instead of hard-coded black, fixing unreadable text in dark mode. (#3751)
• Calling scroll_to_bottom() on a MultilineTextInput that is already at the bottom of the scroll area no longer causes a "bounce" in the scroll position on Windows. (#3872)
• Double-clicking on the header or an empty row a macOS Table no longer triggers the activation of the last item, raising an error if there is no data. (#3905)
• The text color of TextInput on macOS in dark mode has been fixed. (#3919)
• When adding or removing tabs from an OptionContainer, or when setting the content of a SplitContainer, the window and app properties of the content, and the App and Window's widget registry, are now correctly updated. (#3929)
• Nested OptionContainers will now show label text correctly on iOS 26+. (#3949)
• On iOS, the height of the top status bar will now be accounted for properly when the device is rotated. (#3957)
• Apps now log an error instead of crashing if the system locale value is set to an unknown or invalid value. (#3984)
• Label, Box, and ImageView widgets will now display with a transparent background on the Qt backend. (#3997)
• NumberInput values on macOS no longer visually disappear when the widget loses focus. (#3998)
• Cocoa and GTK OptionContainer widgets now rehints properly to accommodate for all of its content sizes at all times, in addition to the decorations around them. (#4010)
• OptionContainer and ScrollContainer widgets inside an OptionContainer will no longer error on layout on Cocoa. (#4010)
• Setting an item in a ListSource now gives a "change" instead of an "insert" notification. (#4029)
• Data source listeners are now fully disconnected when data changes in DetailedList, Selection, Table and Tree widgets. (#4030)
• On Cocoa, ineffective scrolls in an inner ScrollContainer will now be automatically passed on to the outer ScrollContainer. (#4034)
• Cocoa ScrollContainer widgets will now handle elastic effects in small contents properly in a fashion similar to native apps. (#4034)
• There are now different Listener protocols for ValueSource, ListSource, and TreeSource. (#4035)
• Any AttributeError generated by data source Row and Node objects now reference the correct attribute name. (#4037)
• GTK4's DateInput now consistently emits signals on programmatic change, even when only the year component is altered. (#4040)
• MainWindow objects on iOS will no longer have their content overlap slightly with the navigation bar. (#4043)
• The ListListener and TreeListener protocols no longer incompatibly override the insert, remove and clear methods of ListSource and TreeSource, permitting mutable sources which are also listeners. (#4046)
• WinForms buttons with icons will now reliably scale to 32x32px icon size, regardless of the size of the original icon image. (#4051)
• Screen.as_image now properly accounts for HiDPI scaling on Winforms. (#4051)
• Large static content can now be loaded into WebView widgets on Windows, Android and Qt. (#4062)
• The initial layout of a MainWindow before resize will now be based on the correct size of the container on Qt. (#4069)
• Window state transitions to MAXIMIZED from PRESENTATION or FULLSCREEN will now work reliably with the Qt backend. (#4069)
• The list of accessors for creating rows in Table and Tree widgets is now set at widget creation time, preventing inconsistent data conversion if columns are changed. (#4071)
• Qt windows will now properly close when a close is requested on the application. (#4078)
• File reference handling in the Android event loop has been corrected. (#4083)
• On Cocoa, when not setting a background color, DateInput, TimeInput, and MultilineTextInput now paints the proper background. (#4099)
• On Cocoa, setting the background color from non-transparent colors to transparent now works correctly on the Selection and MultilineTextInput widgets. (#4099)
• Previously, it was documented that setting the colors for Selection would not work on Cocoa; however, the background color worked partially, coloring an entire rectangular widget instead of the widget itself. The color handling is now entirely removed for Selection. (#4099)
• There are no longer any zero division errors when drawing an ellipse in a Canvas on macOS, iOS or GTK backends. (#4161)
• The Android implementation of Canvas now has the same default corner-mitering threshold as the HTML canvas specification. (#4162)
• The mouse wheel scrolling behavior of MultilineTextInput has been improved. (#4222)
• Entering presentation mode with multiple windows now correctly puts all windows into presentation mode, not just the last one. (#4233)
• In Light Mode on macOS, when a DetailedList is not focused but has a selection, the text now draws dark instead of light to preserve contrast. (#4264)
• To better match native styling, the focus border on macOS DetailedList has been removed. (#4270)
• Right-aligned, multi-line strings that contain an empty line are now correctly sized on macOS. (#4315)
• Canvas now consistently handles line-dash patterns of an odd or zero length. (#4334)
• App-level dialogs on macOS 26 are now reliably responsive to clicks for dismissal. (#4346)
• Some runtime errors caused by Window event handlers firing as part of the window initialization process have now been silenced. (#4347)
• Toga's lazy-loading mechanism now uses an explicit file encoding. (#4365)

Backward Incompatible Changes

• The get_platform_factory() function and backend factory modules are deprecated. Widget authors should use toga.get_factory() instead, and writers of new backends should use entry points to declare the implemented objects. The new factory objects are not modules but instead are lazy namespace objects. (#2687)
• The parsing function travertino.colors.color() (also accessible as toga.colors.color()) is deprecated. The Travertino method has been renamed travertino.colors.Color.parse(). There should be no need to use this method in Toga, as all APIs that accept colors will automatically parse raw color representations from strings. (#3946)
• Source objects now look for methods with names of the form source_{notification}, rather than just {notification} when the notify method is called. If you have a custom listener class w...

0.5.3

Features

• Toga now provides a Qt backend for KDE-based desktops. (#1142, #3914)
• GTK now provides a DateInput widget. (#1939)
• Apps can now register a handler that is notified when a window is resized. (#2304)
• During application startup, the locale will now be set to match the system's language setting. (#2773)
• GTK apps can now detect if the user has expressed a preference to be displayed in dark mode. (#2841)
• Table and Tree widgets on desktop platforms can now accept focus programmatically. (#2972)
• The ActivityIndicator, Box, Button, Canvas, DateInput, Label and TextInput widgets are now supported with GTK4, along with improved container handling and the added handling of icons. (#3069)
• ListSource.find now has a default parameter which is returned when no match is found. (#3609)
• Pack now has a font shorthand property for specifying all font properties at once. (#3631)
• Toga's web backend now provides deployment configuration information as part of the packaged wheel. This information can be used by tools like Briefcase to control how web content will be rendered. (#3666)
• On macOS, if the text for a column doesn't fit in the available space, a tooltip will be shown with the full text. (#3673)
• The Android backend now provides an ActivityIndicator widget. (#3729)
• Support for Python 3.14 was added. (#3867)
• macOS and iOS WebView widgets now support displaying JavaScript alert() and confirm() dialogs. (#3927)
• GTK WebView widgets now support the use of SharedArrayBuffer in JavaScript. (#3927)

Bugfixes

• Buttons and other interactive widgets in scroll containers now respond properly to touch events on iOS when scrolled into view. (#2411)
• The performance of the asyncio event loop on Winforms has been slightly improved. (#2613)
• The NumberInput widget now uses the correct localization for decimal separators. (#2773)
• Deprecation warnings on style handling will no longer be produced when using GTK4 >= 4.10. (#3069)
• Toga's Winforms wheel is now correctly tagged to indicate that it is x86_64-specific (as it contains an x86-64 DLL for WebView support). (#3179)
• Registering a font with a name that shadows a built-in font family name now raises an error instead of falling back to the system font silently. (#3567)
• The minimum width hint of the iOS DateInput and TimeInput widgets will now fit to the actual displayed size of the picker. (#3580)
• The rgb and hsl classes now have a __str__ that uses modern CSS syntax. For rgb this is simply a nice update, but for hsl it corrects color rendering issues when using the web backend. (#3611)
• On GTK, the scroll position will now be correctly reflected if a MultilineTextInput is programmatically scrolled immediately after changing text content. (#3658)
• On GTK, mouse drag events are now triggered when modifier keys (e.g. NumLock, Shift) are active. (#3661)
• On macOS, the origin of non-primary screens is now correctly calculated when screens are not vertically aligned and the same size. (#3667)
• App path attributes were unintentionally made writable in 0.5.2 (e.g., app.paths.config = <something> was permitted). This has been fixed. (#3669)
• The text of OptionContainer tab labels is now guaranteed to be str on macOS, instead of an Objective C String. (#3672)
• On macOS, pressing Enter or Tab when a row is selected on a table no longer starts row editing mode. (#3673)
• Backwards compatibility code in Travertino that allows it to function with pre-0.5 versions of Toga has been made more specific, to prevent it from masking other, unrelated errors. (#3683)
• Running a single-file app without an explicit app name under PDB no longer crashes. (#3686)
• The interaction between visibility and starting an ActivityIndicator on iOS has been resolved. (#3729)
• On macOS, the Close and Minimize menu options use the system-provided handlers, ensuring better adherence to system style guides. (#3775)
• The show/hide cursor test was made more reliable on Winforms. (#3783)
• OptionContainer and ScrollContainer widgets will now resize continuously during the drag of a parent SplitContainer on macOS. (#3787)
• The toga-demo app now correctly identifies its icon when run as a Python module. (#3926)

Backward Incompatible Changes

• In order to better match CSS, the rgb and hsl constructors now silently clip (or in the case of hue, wrap) out-of-range values rather than throwing errors. They also convert them to consistent types: integers for red, blue, green, and hue; and floats for saturation, lightness, and alpha. (#3611)
• rgb and hsl color objects are now read-only; their r/g/b/a or h/s/l/a attributes can't be altered after creation. Because of this, format conversions (rgb(...).hsl or hsl(...).rgb) can now cache their results, only performing calculations once. "Converting" a color object to its own type (rgb(...).rgb or hsl(...).hsl) now returns the original object, rather than a new instance with the same values. (#3611)
• Travertino's color-parsing color() function interprets hex strings, e.g. #123, #112233, as well as predefined named colors. Previously, while this was never documented, it also parsed CSS-like declarations like "rgb(...)"; this feature has been removed. (#3611)
• Previously, Travertino provided an rgba and an hsla class, as well as rgb and hsl subclasses that enforce opaque alpha. In order to better match CSS, there is now no difference between these names; the shorter rgb and hsl are the preferred forms, but rgba and hsla are direct aliases for them. This can have backwards-incompatible implications; for instance, rgba(255, 255, 255, .5).rgb would previously have returned a fully opaque rgb instance, while now it will preserve its alpha channel information. (#3611)
• Toga (and Travertino) no longer support Python 3.9. (#3682)
• If an app provides distribution metadata, the app name will be set based on that metadata, rather than using the app ID or module name as an assumed name. If an app explicitly provides an app ID, the app name will be derived from the last part of an explicitly-provided App ID, rather than being implicitly derived from the module name. (#3926)
• Static Positron apps now apply a Cross Origin Opener policy of same-origin, and a Cross Origin Embedder Policy of require-corp. (#3927)

Documentation

• Toga's documentation was migrated to Markdown format. (#3719)

Misc

• #3138, #3582, #3613, #3625, #3632, #3636, #3638, #3649, #3650, #3651, #3653, #3654, #3655, #3659, #3662, #3663, #3664, #3668, #3670, #3676, #3687, #3688, #3689, [#3690](#36...

0.5.2

Features

• iOS and macOS backends now provide DateInput and TimeInput widgets. (#1939)
• The Android backend can now identify if dark mode is enabled. (#2841)
• Toga now has a layout debugging mode. If you set TOGA_DEBUG_LAYOUT=1 in your app's runtime environment or toga.Widget.DEBUG_LAYOUT_ENABLED == True directly in the app's code, widgets will be rendered with different background colors, making it easier to identify how space is being allocated by Toga's layout algorithm. (#2953)
• toga.App.paths properties now create the path on demand, if it does not already exist. (#3236)
• The Web backend now provides Selection and Slider widgets. (#3334)
• Lazily loaded objects in the toga namespace now support type checking. (#3358)
• Winforms now provides an ActivityIndicator widget. (#3473)
• WebViews on macOS now support file uploads. (#3484)
• Pack.font_family now accepts a list of possible values; text will be rendered with the first font family that is available. (#3526)
• App paths are now cached upon first retrieval. (#3544)
• On Windows and GTK, Toga now supports loading arbitrary fronts from the user's system, in addition to Toga's predefined set of system fonts and any that you have registered. (This was already possible on Windows, but undocumented.) (#3569)
• On GTK, a document-based app with multiple file extensions registered will now provide a file type filter that will match all available document types. (#3570)

Bugfixes

• Attempting to refresh a window with no content no longer raises an error on Textual. (#2818)
• MultilineTextInput widget will no longer fire on_change events during creation on Windows. (#3290)
• The Textual backend no longer raises superfluous console messages when the app shuts down. (#3399)
• Apps that use a function-based app startup method now validate that the startup method returns content that can be added to the main window. (#3444)
• Buttons in Toga Web now correctly respond to clicks and trigger their associated actions. (#3451)
• Table Widget on Windows now only fires one event on item selection. (#3472)
• Older Linux distributions (such as Ubuntu 22.04) that ship with GLib < 2.74 can now use GTK4 with Toga. (#3525)
• (#3531)
• On macOS, MultilineTextInput will no longer automatically convert straight quotes to smart quotes. (#3546)
• A crash on Android 9 (and earlier) caused by a symbol that wasn't available on those versions has been resolved. (#3554)
• On macOS, document-based apps no longer raise an error on startup about the event loop already running. (#3570)
• When an app has no windows, GTK no longer returns an error when requesting toga.App.current_window. (#3570)
• The conversion of HSL values with a hue between 240 and 330 has been corrected. The previous calculation reversed the red and green components of the converted colors. (#3584)

Backward Incompatible Changes

• toga.Font objects now raise an UnknownFontError instead of silently falling back to system font if the font family can't be successfully loaded. (#3526)

Documentation

• Documentation for installing platform-specific dependencies has been improved. (#1688)
• Toga's documentation now uses a header and style consistent with the BeeWare website. (#3538)
• A topic guide on managing file paths has been added. (#3552)

Misc

• #2453, #2975, #3138, #3420, #3426, #3427, #3428, #3429, #3430, #3431, #3432, #3433, #3434, #3435, #3436, #3437, #3438, #3439, #3441, #3444, #3447, #3452, #3453, #3454, #3455, #3456, #3457, #3458, #3459, #3460, #3461, #3462, #3463, #3464, #3465, #3486, #3488, #3489, #3490, #3491, #3492, #3493, #3494, #3495, #3496, #3497, #3498, #3499, #3500, #3501, #3509, #3511, #3512, #3513, #3514, #3515, #3516, #3517, #3518, #3519, #3520, #3521, #3522, #3523, #3528, #3533, #3539, #3540, #3541, #3542, #3550, #3556, #3557, #3558, #3559, #3560, #3561, #3562, #3563, #3569, #3572, #3575, #3576, #3577, #3578, #3579, #3583, #3586, #3587, #3587, #3588, #3589, #3591, #3592, #3593, #3594, #3595, #3601, #3603, #3604, #3605, #3607, #3608, #3617, #3618, #3619, #3620, #3621, #3622, #3623, #3629

0.5.1

Features

• The WebView widget now supports specifying static content on instantiation. (#2851)
• The content of a WebView can now be assigned using the content property, without providing a root URL for the content. (#2854)
• Application of style properties has been streamlined to reduce redundant font creation and widget-refreshing. (#3273)
• The Canvas example app's UI controls have been reorganized and more clearly labeled. (#3321)
• The Web backend now supports the DateInput, ScrollContainer and TimeInput widgets. (#3334)

Bugfixes

• The asyncio event loop used on Winforms now shuts down correctly, ensuring there are no dangling resources on application exit. (#3266)
• Changing a widget's text_direction now triggers a layout refresh, since it can affect child positioning. (#3268)
• Table rows are now highlighted on Winforms when the widget doesn't have focus. (#3269)
• Support for GTK3 installs that use a GIO release older than 2.72 has been restored. Ubuntu 22.04, and other Debian 12-derived systems are affected by this issue. (#3296)
• Some errors observed on the Web backend during app startup have been resolved. (#3301)
• An incompatibility with Textual 3.0 that caused log messages to be generated on the console on app exit has been resolved. (#3342)
• Window visibility and focus events in the web backend no longer raise errors when the browser window loses focus (#3345)
• A crash caused by the name argument added to asynchronous tasks in Python 3.13.3 has been corrected. (#3394)
• The type annotation for directional style properties (margin, and the deprecated padding alias) has been corrected. (#3396)

Backward Incompatible Changes

• Supplying multiple arguments to BaseStyle.apply() (and therefore Pack.apply()) has been deprecated. If you want to apply multiple arguments at once, apply them within the with style_object.batch_apply() context manager. (#3273)
• The anticlockwise parameter to the Canvas drawing context's arc and ellipse methods (and the Arc and Ellipse drawing objects) has been deprecated; use counterclockwise instead. (#3300)

Misc

• #3261, #3262, #3263, #3267, #3272, #3275, #3277, #3278, #3279, #3280, #3281, #3283, #3284, #3288, #3289, #3291, #3292, #3294, #3302, #3303, #3304, #3305, #3306, #3307, #3308, #3309, #3310, #3311, #3312, #3313, #3314, #3315, #3316, #3317, #3318, #3319, #3320, #3331, #3332, #3336, #3341, #3342, #3346, #3347, #3348, #3349, #3350, #3351, #3352, #3353, #3354, #3355, #3356, #3357, #3363, #3364, #3365, #3366, #3367, #3368, #3369, #3370, #3371, #3372, #3373, #3374, #3375, #3376, #3377, #3378, #3379, #3380, #3381, #3382, #3383, #3384, #3385, #3386, #3404, #3406, #3407, #3408, #3409, #3410, #3411, #3412, #3413, #3414, #3415, #3416, #3417, #3418, #3419

0.5.0

Features

• A justify_content style attribute has been added, which aligns children along a box's main axis. (#1194)
• Toga apps can now detect and set their window states including maximized, minimized, normal, full screen and presentation states. (#1857)
• A gap style attribute has been added, which adds space between adjacent children of a box. (#1943)
• Windows can now respond to changes in focus and visibility. (#2009)
• The line height of multi-line text on a Canvas can now be configured. (#2144)
• Apps can now interrogate whether they are in dark mode on some platforms. (#2841)
• Toga GTK now supports location services via integration with GeoClue and the XDG Location Portal. (#2990)
• Android cameras now describe themselves in terms of the direction they are facing (if known). (#2996)
• toga.Row and toga.Column can now be used as a shorthand for toga.Box(style=Pack(direction=...)). (#3010)
• Style properties can now be passed directly to a widget's constructor, or accessed as attributes, without explicitly using a style object. (#3011)
• The Pack.margin property (and its deprecated alias, padding) can now be accessed via bracket notation, as in style["margin"]. (Previously this worked for the "sub-properties" of margin_top etc., but not for margin/padding itself.) (#3044)
• The WebView widget now supports the retrieval of cookies. (#3068)
• The Travertino library, providing the base classes for Toga's style and box model, is now managed as part of the Toga release process. (#3086)
• Initial experimental support for GTK4 has been added to Toga's GTK backend. This support can be enabled by setting TOGA_GTK=4 in your environment. (#3087)
• The align_items and justify_content properties now have the aliases horizontal_align_items, vertical_align_items, horizontal_align_content and vertical_align_content that explicitly describe layout behavior in the named direction. (#3111)
• A Briefcase bootstrap for generating Positron apps (i.e., apps that are a web view in a native wrapper - Electron, but more positive, because it's Python) was added. (#3114)
• The Travertino library now has 100% test coverage. (#3129)
• The Travertino library now includes APIs to perform alpha blending operations and conversion of RGBA to HSLA color representations. (#3140)
• Travertino now has an aliased_property descriptor to support declaration of property name aliases in styles. (#3213)
• The Pack style representation is now a dataclass. This should allow most IDEs to infer the names and types of properties and suggest them in creating a Pack instance. (#3215)

Bugfixes

• On WinForms, Box, Canvas, Label and ImageView widgets now have transparent backgrounds by default. (#767)
• On iOS, Box, Canvas, ImageView, Label, ProgressBar, ScrollContainer and Slider widgets now have transparent backgrounds by default. (#767)
• DPI scaling on Windows has been improved, fixing a number of resolution and scaling issues. (#2155)
• On WinForms, the background color of a widget now correctly honors the alpha channel of the selected color. (#2425)
• If a WebView widget completes navigation to a new URL while it is being destroyed, an error is no longer raised on macOS or iOS. (#2512)
• Widgets on the iOS backend no longer leak memory when destroyed. (#2849)
• On macOS, when a dialog is in focus, App.current_window now returns the host window, instead of raising an AttributeError. (#2926)
• An issue with creating dialogs on the Textual backend was resolved. (#2949)
• A newly added, visible widget will be hidden when added to a widget hierarchy where an ancestor is hidden. (#2950)
• Multi-letter keyboard navigation in Tables and DetailedLists with the WinForms backend is now functional. (#2956)
• The web backend now uses the Shoelace default font in all browsers. (#3035)
• The hardware example app now correctly demonstrates usage of the location services method current_location. (#3045)
• On GTK, when a window is hidden, the window.state getter now correctly reports the state when the window was last visible. (#3105)
• On Android, setting a custom background color on widgets now preserves the native look and feel. (#3118)
• On Android, setting widget background color to TRANSPARENT now correctly sets it to transparent. (#3118)
• The binary dependencies for the GTK backend have been updated to reflect changes in requirements of PyGObject. (#3143)
• On Android, DetailedList and Table widgets now correctly unset the highlight color when a row is deselected. (#3156)
• (#3163)

Backward Incompatible Changes

• "Full screen mode" on an app has been renamed "Presentation mode" to avoid the ambiguity with "full screen mode" on a window. The toga.App.enter_full_screen and toga.App.exit_full_screen APIs have been renamed toga.App.enter_presentation_mode and toga.App.exit_presentation_mode, respectively. (#1857)
• The use of generators as event handlers has been deprecated. Any generator-based event handler can be converted into an asynchronous co-routine by converting the handler to async def, and using await asyncio.sleep(t) in place of yield t (for some sleep interval t). (#2721)
• Widgets now create and return their implementations via a _create() method. A user-created custom widget that inherits from an existing Toga widget and uses the same implementation will require no changes. Any user-created widgets that need to specify their own implementation should do so in _create() and return that implementation. Existing user code inheriting from Widget that assigns its implementation before calling super().__init__() will continue to function, but give a RuntimeWarning; unfortunately, this change breaks any existing code that doesn't create its implementation until afterward. Such usage will now raise an exception. (#2942)
• Pack's padding and alignment properties have been renamed to margin and align_items, to match their CSS analogues. align_items also now takes CSS-compatible values of START, CENTER, and END, instead of alignment's TOP/RIGHT/BOTTOM/LEFT/CENTER. The old names are still present — and alignment still takes its existing values — but these constants are deprecated. (#3033)
• APIs marked as deprecated in Toga 0.4.0 and earlier have been removed. (#3059)
• The show() and hide() APIs can no longer be used on a window while it is in a MINIMIZED, FULLSCREEN or PRESENTATION state. (#3109)
• If window size is unchanged as a result of a resize request, a layout of window content is no longer triggered. (#3131)
• If you're running on Ubuntu 22.04, Debian 11 or Debian 12, you'll need to manually add a pin for PyGObject==3.50.0 to your project. This is because recent PyGObject releases specify a requirement on girepository-2.0, which is not available on older Debian-based distributions. A manual pin is required because there's no way to express a dependency on a system package as part of Python's requirements specifications. (#3143)
• The signature of the apply method of BaseStyle (and thus Pack) has changed. Rather than taking a property name and value, it now takes only the name, and the style object checks its own current value for that property to know what to apply. This method is normally used internally, but any user code calling it manually will get a DeprecationWarning if it supplies two arguments. (#3159)
• Travertino's BaseStyle.reapply() (and thus Toga's Pack.reapply()) has been deprecated; the correct usage is now to call .apply() with no arguments. User code is unlikely to ever call this method, but Toga releases before (and including) 0.4.8 calls it extensively, so users who update Travertino but not Toga will receive a DeprecationWarning. (#3160)
• Travertino's declaration module has been split into two smaller modules, properties and style. Toga's imports have been updated to the new locations, but users with Toga <= 0.4.8 that update Travertino to 0.5.0 (and anyone who may be accessing these classes in user code) will get a DeprecationWarning explaining the situation. (#3195)

Documentation

• Tutorial 3 was extended to explain limitations of the browser example, and suggest some extension activities. (#2998)
• A summary of Toga's API design principles has been added. (#3170)
• Widget screenshots have been added for the Web backend. (#3259)

Misc

• #2547, #2893, #2920, #2921, #2922, #2923, #2925, #2931, #2932, #2933, #2934, #2935, #2936, #2939, #2941, #2942, #2951, #2954, #2965, #2967, #2968, #2970, #2975, #2976, #2978, #2980, #2981, #2982, #2983, #2984, #2985, #2986, #2987, #2988, #2989, #2991, #2997, #3006, #3007, #3008, #3016, #3020, #3029, #3030, #3031, #3039, #3040, #3041, #3042, #3044, #3047, #3048, #3051, #3053, #3055, #3057, #3058, #3060, #3061, #3061, #3062, #3064, #3065, #3071, #3072, #3073, #3074, #3075, #3076, #3077, #3078, #3079, #3080, #3081, #3082, #3089, #3091, #3092, #3093, #3094, #3095, #3096, #3097, #3098, #3099, #3100, #3101, #3102, #3103, #3104, #3115, #3117, #3120, #3121, #3122, #3123, #3124, #3125, #3132, #3133, #3141, #3144, #3145, #3146, #3147, #3148, #3149, #3150, #3151, #3154, #3165, #3166, #3169, #3173, #3174, #3175, #3176, #3178, #3183, #3184, #3186, #3189, #3190, #3191, #3196, #3197, #3198, #3199, #3200, #3201, #3202, #3203, #3204, #3205, #3206, #3207, #3208, #3209, #3210, #3212, #3213, #3216, #3219, #3220, #3221, #3222, #3223, #3224, #3225, #3226, #3227, #3228, #3229, #3230, #3231, #3232, #3233, #3243, #3244, #3245, #3246, #3247, #3248, #3249, #3250, #3251, #3252, #3253, #3254, #3255, #3257, #3258

0.4.9

This release contains no new features. The primary purpose of this release is to add an upper version pin to Toga's Travertino requirement, protecting against the upcoming Toga 0.5.0 release that will include backwards incompatible changes in Travertino. (#3167)

Bugfixes

• The testbed app can now be run on any supported Python version. (#2883)
• App.app is now set to an initial value of None, before an app instance is created. This avoids a potential AttributeError when the test suite finishes. (#2918)

Misc

• #2476, #2913

0.4.8

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

0.4.7

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

0.4.6

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

0.4.5

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