Release History¶
0.4.3 (2024-05-06)¶
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
resourcesfolder 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.TimeoutErrorwhen displayed. (#2474)The integration of the
asyncioevent 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)
WebViewis 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.appwas 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 (2024-02-06)¶
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_windowon GTK now returnsNonewhen 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.Imageobjects 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_resulthas 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_activitymethod that allows you to register a callback when the intent completes. (#2353)
Documentation¶
Misc¶
0.4.1 (2023-12-21)¶
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.OptionItemobjects. (#2259)An OptionContainer widget was added for iOS. (#2259)
Apps can now specify platform-specific icon resources by appending the platform name (e.g.,
-macOSor-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=1will now shrink to fit if the image is larger than the available space. (#2275)
Backward Incompatible Changes¶
The
toga.Imageconstructor now takes a single argument (src); thepathanddataarguments 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
enabledargument must now be provided as a keyword argument. The name of the first argument has been also been renamed (fromtexttotext_or_item); it should generally be passed as a positional, rather than keyword argument. (#2259)The use of synchronous
on_resultcallbacks on dialogs andWebview.evaluate_javascript()calls has been deprecated. These methods should be used in their asynchronous form. (#2264)
Documentation¶
Misc¶
0.4.0 (2023-11-03)¶
Features¶
The Toga API has been fully audited. All APIs now have 100% test coverage, complete API documentation (including type annotations), and are internally consistent. ( #1903, #1938, #1944, #1946, #1949, #1951, #1955, #1956, #1964, #1969, #1984, #1996, #2011, #2017, #2025, #2029, #2044, #2058, #2075)
Headings are no longer mandatory for Tree widgets. If headings are not provided, the widget will not display its header bar. (#1767)
Support for custom font loading was added to the GTK, Cocoa and iOS backends. (#1837)
The testbed app has better diagnostic output when running in test mode. (#1847)
A Textual backend was added to support terminal applications. (#1867)
Support for determining the currently active window was added to Winforms. (#1872)
Programmatically scrolling to top and bottom in MultilineTextInput is now possible on iOS. (#1876)
A handler has been added for users confirming the contents of a TextInput by pressing Enter/Return. (#1880)
An API for giving a window focus was added. (#1887)
Widgets now have a
.clear()method to remove all child widgets. (#1893)Winforms now supports hiding and re-showing the app cursor. (#1894)
ProgressBar and Switch widgets were added to the Web backend. (#1901)
Missing value handling was added to the Tree widget. (#1913)
App paths now include a
configpath for storing configuration files. (#1964)A more informative error message is returned when a platform backend doesn’t support a widget. (#1992)
The example apps were updated to support being run with
briefcase runon all platforms. (#1995)Headings are no longer mandatory Table widgets. (#2011)
Columns can now be added and removed from a Tree. (#2017)
The default system notification sound can be played via
App.beep(). (#2018)DetailedList can now respond to “primary” and “secondary” user actions. These may be implemented as left and right swipe respectively, or using any other platform-appropriate mechanism. (#2025)
A DetailedList can now provide a value to use when a row doesn’t provide the required data. (#2025)
The accessors used to populate a DetailedList can now be customized. (#2025)
Transformations can now be applied to any canvas context, not just the root context. (#2029)
Canvas now provides more
list-like methods for manipulating drawing objects in a context. (#2029)On Windows, the default font now follows the system theme. On most devices, this means it has changed from Microsoft Sans Serif 8pt to Segoe UI 9pt. (#2029)
Font sizes are now consistently interpreted as CSS points. On Android, iOS and macOS, this means any numeric font sizes will appear 33% larger than before. The default font size on these platforms is unchanged. (#2029)
MultilineTextInputs no longer show spelling suggestions when in read-only mode. (#2136)
Applications now verify that a main window has been created as part of the
startup()method. (#2047)An implementation of ActivityIndicator was added to the Web backend. (#2050)
An implementation of Divider was added to the Web backend. (#2051)
The ability to capture the contents of a window as an image has been added. (#2063)
A PasswordInput widget was added to the Web backend. (#2089)
The WebKit inspector is automatically enabled on all macOS WebViews, provided you’re using macOS 13.3 (Ventura) or iOS 16.4, or later. (#2109)
Text input widgets on macOS now support undo and redo. (#2151)
The Divider widget was implemented on Android. (#2181)
Bugfixes¶
The WinForms event loop was decoupled from the main form, allowing background tasks to run without a main window being present. (#750)
Widgets are now removed from windows when the window is closed, preventing a memory leak on window closure. (#1215)
Android and iOS apps no longer crash if you invoke
App.hide_cursor()orApp.show_cursor(). (#1235)A Selection widget with no items now consistently returns a selected value of
Noneon all platforms. (#1723)macOS widget methods that return strings are now guaranteed to return strings, rather than native Objective C string objects. (#1779)
WebViews on Windows no longer have a black background when they are resized. (#1855)
The interpretation of
MultilineTextInput.readonlywas corrected iOS (#1866)A window without an
on_closehandler can now be closed using the window frame close button. (#1872)Android apps running on devices older than API level 29 (Android 10) no longer crash. (#1878)
Missing value handling on Tables was fixed on Android and Linux. (#1879)
The GTK backend is now able to correctly identify the currently active window. (#1892)
Error handling associated with the creation of Intents on Android has been improved. (#1909)
The DetailedList widget on GTK now provides an accurate size hint during layout. (#1920)
Apps on Linux no longer segfault if an X Windows display cannot be identified. (#1921)
The
on_resulthandler is now used by Cocoa file dialogs. (#1947)Pack layout now honors an explicit width/height setting of 0. (#1958)
The minimum window size is now correctly recomputed and enforced if window content changes. (#2020)
The title of windows can now be modified on Winforms. (#2094)
An error on Winforms when a window has no content has been resolved. (#2095)
iOS container views are now set to automatically resize with their parent view (#2161)
Backward Incompatible Changes¶
The
weight,styleandvariantarguments forFontandFont.registerare now keyword-only. (#1903)The
clear()method for resetting the value of a MultilineTextInput, TextInput and PasswordInput has been removed. This method was an ambiguous override of theclear()method on Widget that removed all child nodes. To remove all content from a text input widget, usewidget.value = "". (#1938)The ability to perform multiple substring matches in a
Containsvalidator has been removed. (#1944)The
TextInput.validatemethod has been removed. Validation now happens automatically whenever thevalueorvalidatorsproperties are changed. (#1944)The argument names used to construct validators have changed. Error message arguments now all end with
_message;compare_counthas been renamedcount; andmin_valueandmax_valuehave been renamedmin_lengthandmax_length, respectively. (#1944)The
get_dom()method on WebView has been removed. This method wasn’t implemented on most platforms, and wasn’t working on any of the platforms where it was implemented, as modern web view implementations don’t provide a synchronous API for accessing web content in this way. (#1949)The
evaluate_javascript()method on WebView has been modified to work in both synchronous and asynchronous contexts. In a synchronous context you can invoke the method and use a functionalon_resultcallback to be notified when evaluation is complete. In an asynchronous context, you can await the result. (#1949)The
on_key_downhandler has been removed from WebView. If you need to catch user input, either use a handler in the embedded JavaScript, or create aCommandwith a key shortcut. (#1949)The
invoke_javascript()method has been removed. All usage ofinvoke_javascript()can be replaced withevaluate_javascript(). (#1949)The usage of local
file://URLs has been explicitly prohibited.file://URLs have not been reliable for some time; their usage is now explicitly prohibited. (#1949)DatePickerhas been renamedDateInput. (#1951)TimePickerhas been renamedTimeInput. (#1951)The
on_selecthandler on the Selection widget has been renamedon_changefor consistency with other widgets. (#1955)The
_notify()method on data sources has been renamednotify(), reflecting its status as a public API. (#1955)The
prepend()method was removed from theListSourceandTreeSourceAPIs. Calls toprepend(...)can be replaced withinsert(0, ...). (#1955)The
insert()andappend()APIs onListSourceandTreeSourcehave been modified to provide an interface that is closer to thatlistAPI. These methods previously accepted a variable list of positional and keyword arguments; these arguments should be combined into a single tuple or dictionary. This matches the API provided by__setitem__(). (#1955)Images and ImageViews no longer support loading images from URLs. If you need to display an image from a URL, use a background task to obtain the image data asynchronously, then create the Image and/or set the ImageView
imageproperty on the completion of the asynchronous load. (#1956)A row box contained inside a row box will now expand to the full height of its parent, rather than collapsing to the maximum height of the inner box’s child content. (#1958)
A column box contained inside a column box will now expand to the full width of its parent, rather than collapsing to the maximum width of the inner box’s child content. (#1958)
On Android, the user data folder is now a
datasub-directory of the location returned bycontext.getFilesDir(), rather than the barecontext.getFilesDir()location. (#1964)GTK now returns
~/.local/state/appname/logas the log file location, rather than~/.cache/appname/log. (#1964)The location returned by
toga.App.paths.appis now the folder that contains the Python source file that defines the app class used by the app. If you are using atoga.Appinstance directly, this may alter the path that is returned. (#1964)On Winforms, if an application doesn’t define an author, an author of
Unknownis now used in application data paths, rather thanToga. (#1964)Winforms now returns
%USERPROFILE%/AppData/Local/<Author Name>/<App Name>/Dataas the user data file location, rather than%USERPROFILE%/AppData/Local/<Author Name>/<App Name>. (#1964)Support for SplitContainers with more than 2 panels of content has been removed. (#1984)
Support for 3-tuple form of specifying SplitContainer items, used to prevent panels from resizing, has been removed. (#1984)
The ability to increment and decrement the current OptionContainer tab was removed. Instead of container.current_tab += 1, use container.current_tab = container.current_tab.index + 1 (#1996)
OptionContainer.add(),OptionContainer.remove()andOptionContainer.insert()have been removed, due to being ambiguous with base widget methods of the same name. Use theOptionContainer.content.append(),OptionContainer.content.remove()andOptionContainer.content.insert()APIs instead. (#1996)The
on_selecthandler for OptionContainer no longer receives theoptionargument providing the selected tab. Usecurrent_tabto obtain the currently selected tab. (#1996)TimePicker.min_timeandTimePicker.max_timehas been renamedTimeInput.minandTimeInput.max, respectively. (#1999)DatePicker.min_dateandDatePicker.max_datehas been renamedDateInput.minandDateInput.max, respectively. (#1999)NumberInput.min_valueandNumberInput.max_valuehave been renamedNumberInput.minandNumberInput.max, respectively. (#1999)Slider.rangehas been replaced bySlider.minandSlider.max. (#1999)Tables now use an empty string for the default missing value, rather than warning about missing values. (#2011)
Table.add_column()has been deprecated in favor ofTable.append_column()andTable.insert_column()(#2011)Table.on_double_clickhas been renamedTable.on_activate. (#2011, #2017)Trees now use an empty string for the default missing value, rather than warning about missing values. (#2017)
The
parentargument has been removed from theinsertandappendcalls onTreeSource. This improves consistency between the API forTreeSourceand the API forlist. To insert or append a row in to a descendant of a TreeSource root, useinsertandappendon the parent node itself - i.e.,source.insert(parent, index, ...)becomesparent.insert(index, ...), andsource.insert(None, index, ...)becomessource.insert(index, ...). (#2017)When constructing a DetailedList from a list of tuples, or a list of lists, the required order of values has changed from (icon, title, subtitle) to (title, subtitle, icon). (#2025)
The
on_selecthandler for DetailedList no longer receives the selected row as an argument. (#2025)The handling of row deletion in DetailedList widgets has been significantly altered. The
on_deleteevent handler has been renamedon_primary_action, and is now only a notification that a “swipe left” event (or platform equivalent) has been confirmed. This was previously inconsistent across platforms. Some platforms would update the data source to remove the row; some treatedon_deleteas a notification event and expected the application to handle the deletion. It is now the application’s responsibility to perform the data deletion. (#2025)Support for Python 3.7 was removed. (#2027)
fill()andstroke()now return simple drawing operations, rather than context managers. If you attempt to usefill()orstroke()on a context as a context manager, an exception will be raised; using these methods on Canvas will raise a warning, but return the appropriate context manager. (#2029)The
clicksargument toCanvas.on_presshas been removed. Instead, to detect “double clicks”, you should useCanvas.on_activate. Theclicksargument has also been removed fromCanvas.on_release,Canvas.on_drag,Canvas.on_alt_press,Canvas.on_alt_release, andCanvas.on_alt_drag. (#2029)The
new_pathoperation has been renamedbegin_pathfor consistency with the HTML5 Canvas API. (#2029)Methods that generate new contexts have been renamed:
context(),closed_path(),fill()andstroke()have becomeContext(),ClosedPath(),Fill()andStroke()respectively. This has been done to make it easier to differentiate between primitive drawing operations and context-generating operations. (#2029)A Canvas is no longer implicitly a context object. The
Canvas.contextproperty now returns the root context of the canvas. If you were previously usingCanvas.context()to generate an empty context, it should be replaced withCanvas.Context(). Any operations toremove()drawing objects from the canvas orclear()the canvas of drawing objects should be made onCanvas.context. Invoking these methods onCanvaswill now call the baseWidgetimplementations, which will throw an exception becauseCanvaswidgets cannot have children. (#2029)The
preserveoption onFill()operations has been deprecated. It was required for an internal optimization and can be safely removed without impact. (#2029)Drawing operations (e.g.,
arc,line_to, etc) can no longer be invoked directly on a Canvas. Instead, they should be invoked on the root context of the canvas, retrieved with via the canvas property. Context creating operations (Fill,StrokeandClosedPath) are not affected. (#2029)The
tightargument toCanvas.measure_text()has been deprecated. It was a GTK implementation detail, and can be safely removed without impact. (#2029)The
multiselectargument to Open File and Select Folder dialogs has been renamedmultiple_select, for consistency with other widgets that have multiple selection capability. (#2058)Window.resizeableandWindow.closeablehave been renamedWindow.resizableandWindow.closable, to adhere to US spelling conventions. (#2058)Windows no longer need to be explicitly added to the app’s window list. When a window is created, it will be automatically added to the windows for the currently running app. (#2058)
The optional arguments of
CommandandGroupare now keyword-only. (#2075)In
App, the propertiesidandnamehave been deprecated in favor ofapp_idandformal_namerespectively, and the propertymodule_namehas been removed. (#2075)GROUP_BREAK,SECTION_BREAKandCommandSetwere removed from thetoganamespace. End users generally shouldn’t need to use these classes. If your code does need them for some reason, you can access them from thetoga.commandnamespace. (#2075)The
windowsconstructor argument oftoga.Apphas been removed. Windows are now automatically added to the current app. (#2075)The
filenameargument and property oftoga.Documenthas been renamedpath, and is now guaranteed to be apathlib.Pathobject. (#2075)Documents must now provide a
create()method to instantiate amain_windowinstance. (#2075)App.exit()now unconditionally exits the app, rather than confirming that theon_exithandler will permit the exit. (#2075)
Documentation¶
Documentation for application paths was added. (#1849)
The contribution guide was expanded to include more suggestions for potential projects, and to explain how the backend tests work. (#1868)
All code blocks were updated to add a button to copy the relevant contents on to the user’s clipboard. (#1897)
Class references were updated to reflect their preferred import location, rather than location where they are defined in code. (#2001)
The Linux system dependencies were updated to reflect current requirements for developing and using Toga. (#2021)
Misc¶
#1865, #1875, #1881, #1882, #1886, #1889, #1895, #1900, #1902, #1906, #1916, #1917, #1918, #1926, #1933, #1948, #1950, #1952, #1954, #1963, #1972, #1977, #1980, #1988, #1989, #1998, #2008, #2014, #2019, #2022, #2028, #2034, #2035, #2039, #2052, #2053, #2055, #2056, #2057, #2059, #2067, #2068, #2069, #2085, #2090, #2092, #2093, #2101, #2102, #2113, #2114, #2115, #2116, #2118, #2119, #2123, #2124, #2127, #2128, #2131, #2132, #2146, #2147, #2148, #2149, #2150, #2163, #2165, #2166, #2171, #2177, #2180, #2184, #2186
0.3.1 (2023-04-12)¶
Features¶
The Button widget now has 100% test coverage, and complete API documentation. (#1761)
The mapping between Pack layout and HTML/CSS has been formalized. (#1778)
The Label widget now has 100% test coverage, and complete API documentation. (#1799)
TextInput now supports focus handlers and changing alignment on GTK. (#1817)
The ActivityIndicator widget now has 100% test coverage, and complete API documentation. (#1819)
The Box widget now has 100% test coverage, and complete API documentation. (#1820)
NumberInput now supports changing alignment on GTK. (#1821)
The Divider widget now has 100% test coverage, and complete API documentation. (#1823)
The ProgressBar widget now has 100% test coverage, and complete API documentation. (#1825)
The Switch widget now has 100% test coverage, and complete API documentation. (#1832)
Event handlers have been internally modified to simplify their definition and use on backends. (#1833)
The base Toga Widget now has 100% test coverage, and complete API documentation. (#1834)
Support for FreeBSD was added. (#1836)
The Web backend now uses Shoelace to provide web components. (#1838)
Winforms apps can now go full screen. (#1863)
Bugfixes¶
Issues with reducing the size of windows on GTK have been resolved. (#1205)
iOS now supports newlines in Labels. (#1501)
The Slider widget now has 100% test coverage, and complete API documentation. (#1708)
The GTK backend no longer raises a warning about the use of a deprecated
set_wmclassAPI. (#1718)MultilineTextInput now correctly adapts to Dark Mode on macOS. (#1783)
The handling of GTK layouts has been modified to reduce the frequency and increase the accuracy of layout results. (#1794)
The text alignment of MultilineTextInput on Android has been fixed to be TOP aligned. (#1808)
GTK widgets that involve animation (such as Switch or ProgressBar) are now redrawn correctly. (#1826)
Improved Documentation¶
Misc¶
0.3.0 (2023-01-30)¶
Features¶
Widgets now use a three-layered (Interface/Implementation/Native) structure.
A GUI testing framework was added.
A simplified “Pack” layout algorithm was added.
Added a web backend.
Bugfixes¶
Too many to count!
0.2.15¶
Added more widgets and cross-platform support, especially for GTK+ and Winforms
0.2.14¶
Removed use of
namedtuple
0.2.13¶
Various fixes in preparation for PyCon AU demo
0.2.12¶
Migrated to CSS-based layout, rather than Cassowary/constraint layout.
Added Windows backend
Added Django backend
Added Android backend
0.2.0 - 0.2.11¶
Internal development releases.
0.1.2¶
Further improvements to multiple-repository packaging strategy.
Ensure Ctrl-C is honored by apps.
Cocoa: Added runtime warnings when minimum OS X version is not met.
0.1.1¶
Refactored code into multiple repositories, so that users of one backend don’t have to carry the overhead of other installed platforms
Corrected a range of bugs, mostly related to problems under Python 3.
0.1.0¶
Initial public release. Includes:
A Cocoa (OS X) backend
A GTK+ backend
A proof-of-concept Win32 backend
A proof-of-concept iOS backend