Releases: beeware/toga
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
andtoga.Column
can now be used as a shorthand fortoga.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 instyle["margin"]
. (Previously this worked for the "sub-properties" ofmargin_top
etc., but not formargin
/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
andjustify_content
properties now have the aliaseshorizontal_align_items
,vertical_align_items
,horizontal_align_content
andvertical_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 anAttributeError
. (#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 methodcurrent_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
andTable
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
andtoga.App.exit_full_screen
APIs have been renamedtoga.App.enter_presentation_mode
andtoga.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 usingawait asyncio.sleep(t)
in place ofyield t
(for some sleep intervalt
). (#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 fromWidget
that assigns its implementation before callingsuper().__init__()
will continue to function, but give aRuntimeWarning
; 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
andalignment
properties have been renamed tomargin
andalign_items
, to match their CSS analogues.align_items
also now takes CSS-compatible values ofSTART
,CENTER
, andEND
, instead ofalignment
'sTOP
/RIGHT
/BOTTOM
/LEFT
/CENTER
. The old names are still present — andalignment
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()
andhide()
APIs can no longer be used on a window while it is in aMINIMIZED
,FULLSCREEN
orPRESENTATION
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 ongirepository-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 ofBaseStyle
(and thusPack
) 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 aDeprecationWarning
if it supplies two arguments. (#3159) - Travertino's
BaseStyle.reapply()
(and thus Toga'sPack.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 aDeprecationWarning
. (#3160) - Travertino's
declaration
module has been split into two smaller modules,properties
andstyle
. 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 aDeprecationWarning
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 potentialAttributeError
when the test suite finishes. (#2918)
Misc
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 amain_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
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
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 anon_close
handler. If a request is made to close the main window, theon_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 totoga.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 thetoga.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-likeremove()
ordiscard()
calls with a Command instance, or using dictionary-likepop()
ordel
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 triggeron_exit
handling. Previouslyon_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 anon_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 ontoga.App
has been deprecated. Background tasks can be implemented using the newon_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 subclassApp
directly, passing the document types as alist
ofDocument
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 calleddescription
; 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 defaulton_close
handler that uses the modification status of a document to control whether a document can close. Invokingtouch()
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 toMainWindow
(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 aDialog
class (e.g.,InfoDialog
), and passing that instance towindow.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
andPosition
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
0.4.4
0.4.3
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()
andCanvas.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
0.4.2
Features
- Buttons can now be created with an icon, instead of a text label. (#774)
- Widgets and Windows can now be sorted. The ID of the widget is used for the sorting order. (#2190)
- The main window generated by the default
startup()
method of an app now has an ID ofmain
. (#2190) - A cross-platform API for camera access was added. (#2266, #2353)
- An OptionContainer widget was added for Android. (#2346)
Bugfixes
- New widgets with an ID matching an ID that was previously used no longer cause an error. (#2190)
App.current_window
on GTK now returnsNone
when all windows are hidden. (#2211)- Selection widgets on macOS can now include duplicated titles. (#2319)
- The padding around DetailedList on Android has been reduced. (#2338)
- The error returned when an Image is created with no source has been clarified. (#2347)
- On macOS,
toga.Image
objects can now be created from raw data that didn't originate from a file. (#2355) - Winforms no longer generates a system beep when pressing Enter in a TextInput. (#2374)
Backward Incompatible Changes
- Widgets must now be added to a window to be available in the widget registry for lookup by ID. (#2190)
- If the label for a Selection contains newlines, only the text up to the first newline will be displayed. (#2319)
- The internal Android method
intent_result
has been deprecated. This was an internal API, and not formally documented, but it was the easiest mechanism for invoking Intents on the Android backend. It has been replaced by the synchronousstart_activity
method that allows you to register a callback when the intent completes. (#2353)
Documentation
- Initial documentation of backend-specific features has been added. (#1798)
- The difference between Icon and Image was clarified, and a note about the lack of an
on_press
handler on ImageView was added. (#2348)
Misc
0.4.1
Features
- Toga images can now be created from (and converted to) PIL images. (#2142)
- A wider range of command shortcut keys are now supported on WinForms. (#2198)
- Most widgets with flexible sizes now default to a minimum size of 100 CSS pixels. An explicit size will still override this value. (#2200)
- OptionContainer content can now be constructed using
toga.OptionItem
objects. (#2259) - An OptionContainer widget was added for iOS. (#2259)
- Apps can now specify platform-specific icon resources by appending the platform name (e.g.,
-macOS
or-windows
) to the icon filename. (#2260) - Images can now be created from the native platform representation of an image, without needing to be transformed to bytes. (#2263)
Bugfixes
- TableViews on macOS will no longer crash if a drag operation is initiated from inside the table. (#1156)
- Separators before and after command sub-groups are now included in menus. (#2193)
- The web backend no longer generates a duplicate title bar. (#2194)
- The web backend is now able to display the About dialog on first page load. (#2195)
- The testbed is now able to run on macOS when the user running the tests has the macOS display setting "Prefer tabs when opening documents" set to "Always". (#2208)
- Compliance with Apple's HIG regarding the naming and shortcuts for the Close and Close All menu items was improved. (#2214)
- Font handling on older versions of iOS has been corrected. (#2265)
- ImageViews with
flex=1
will now shrink to fit if the image is larger than the available space. (#2275)
Backward Incompatible Changes
- The
toga.Image
constructor now takes a single argument (src
); thepath
anddata
arguments are deprecated. (#2142) - The use of Caps Lock as a keyboard modifier for commands was removed. (#2198)
- Support for macOS release prior to Big Sur (11) has been dropped. (#2228)
- When inserting or appending a tab to an OptionContainer, the
enabled
argument must now be provided as a keyword argument. The name of the first argument has been also been renamed (fromtext
totext_or_item
); it should generally be passed as a positional, rather than keyword argument. (#2259) - The use of synchronous
on_result
callbacks on dialogs andWebview.evaluate_javascript()
calls has been deprecated. These methods should be used in their asynchronous form. (#2264)
Documentation
- Documentation for
toga.Key
was added. (#2199) - Some limitations on App presentation imposed by Wayland have been documented. (#2255)