WinUI 3 foundational implementation by Oliver-Leigh · Pull Request #4600 · beeware/toga

Oliver-Leigh · 2026-07-27T08:32:29Z

This PR adds the foundation of a WinUI 3 backend for the Windows platform. The backend is based on the win32more Microsoft App SDK projection. The currently implemented entry points are:

App
Command
Font
Icon
Paths
resources
MenuStatusIcon
SimpleStatusIcon
StatusIconSet
MainWindow
Window
Box
Button
Label

Note: Documentation is missing

Refs #2574

PR Checklist:

I will abide by the BeeWare Code of Conduct
I have read and have followed the CONTRIBUTING.md file
This PR was generated or assisted using an AI tool

Assisted-by:

Oliver-Leigh · 2026-08-03T14:18:55Z

Thanks for the review @johnzhou721! The DPI suggestions were especially helpful.

No I have not. I think we can put it in this PR to see if the ARM64 coverage increases (since the handling inline is try-catch not direct skip in arm64 ci) and if so remove all the try-catches.

Unfortunately it didn't work.

johnzhou721 · 2026-08-06T19:52:37Z

Thanks for the review @johnzhou721! The DPI suggestions were especially helpful.

No worries! I don't have much time right now, but if you want to test multiple monitors setup, you can use this project: https://github.com/VirtualDrivers/Virtual-Display-Driver -- note that it may require test signing, though. The console app in that repo isn't really reliable, so installing the drivers through Device Manager may be a better approach there.

(Hopefully my line of Norwegian at the start of my review wasn't too awkward...)

freakboy3742

I'm still working my way through this, but I wanted to give you the comments I have so far. On the whole, this works great in my testing; I'm still working out how some of the finer details (like the cascading properties and staged properties) work.

freakboy3742 · 2026-08-20T02:50:51Z

We only need a single feature here - the notable entry in the next release will be that there is a WinUI3 backend at all, rather than multiple specific feature call outs.

Fair enough! Updated.

freakboy3742 · 2026-08-20T02:51:59Z

                )

    def _startup(self) -> None:
+        print("app._startup() - start")


I'm assuming these are here for debugging purposes - they'll need to be removed before this lands.

Yes, occasionally the testbed reports that the window never became visible. I'm trying to find where the issue happens with this code, but it hasn't popped up again yet.

freakboy3742 · 2026-08-20T02:58:40Z

+        ]
+
+        # The size properties for WinUI 3 are not immediately available
+        await asyncio.sleep(0.1)


Flagging because this is a mild concern as I work through the PR in alphabetical order - unclear if this is purely a "testbed testing" concern, or a "real" concern. If it's purely a Testbed thing, that's OK; it's more of a problem if it's going to have a broader "real" impact.

freakboy3742 · 2026-08-20T02:59:24Z

-        screen_window_dict[window_information["paired_screen"]] = window_information[
-            "window"
-        ]
+


Is there any particular significance to the move of this test?

Not really. I was trying to sort out the parts related to the sleep. I've changed this now to use the window_probe.wait_for_window() method instead. I think it's much cleaner.

freakboy3742 · 2026-08-20T03:03:53Z

+        # GitHub Windows ARM64 runners don't seem to be able to accept input focus.
+        # See https://github.com/actions/partner-runner-images/issues/174
+        if platform.machine() != "ARM64" or os.environ["RUNNING_IN_CI"] != "true":
+            raise AssertionError from e


If I'm reading this right... this fix will also fix the "winforms testing on ARM" issue - is that your read as well?

Maybe "fix" is too strong but it would help us get more test coverage on ARM64. I'm honestly not sure what the best structure for this type of skip is. I think the current approach needs some work (for example, here there should probably be an "is Windows" type condition as well).

One possibility is to apply the existing Winforms approach here as well. Then open a separate issue to try and get as much ARM64 coverage on both Windows backends.

freakboy3742 · 2026-08-20T05:10:02Z

+        - Italics goes against the Windows design prinicpals, so it is safe to set the
+            Normal font style by default. See:
+            learn.microsoft.com/windows/apps/design/signature-experiences/typography


So I understand the implications here - it looks like Italic is still being honored; where is it being disabled as a default?

Yes, but I'll reword this comment because it's not clear what I'm trying to say.

The point is that Toga's default style is NORMAL not SYSTEM. Conceivably some parts of the UI would default to a different style. However, the Windows design philosophy means that we have SYSTEM == NORMAL anyway.

Comments have now been updated.

freakboy3742 · 2026-08-20T05:11:26Z

+    def _creator(self, property):
+        def property_creator(property=property):
+            return property
+
+        return property_creator


I'm sure there's a technical reason for this... what is it? As written, it seems like a really complicated way to implement self.FontFamily = family...

It's to do with the staging. I've added a note at the top of the class.

freakboy3742 · 2026-08-20T05:12:10Z

+
+    The WinUI 3 backend needs two type of icon:
+        - Native WinUI 3 - to be used with most native WinUI 3 classes such as button.
+        - Win32 - to be used with StatusIcons the title bar.


Is there a missing "on" here?

Yes. I've rewritten this for clarity.

freakboy3742 · 2026-08-20T06:48:30Z

It's annoying that this is (AFAICT) near identical to the Winforms version; not sure if I have any ideas for how to refactor this, though.

I think we can factor out ReadyDeque and TwoThreadIocpProactor. I'm not sure where to put them though. In fact there are a few Win32 things which are duplicated as well.

The WinUI 3 loop is a bit simpler than the Winforms loop because of the way scheduling works.

freakboy3742 · 2026-08-20T06:50:42Z

This module may not be necessary any more; the recent changes in core mean we can fall back on platformdirs as a default here.

I've rewritten the Paths module to use platformdirs via the PlatformDirsPaths class. This way we can leverage the advantages of platformdirs and still have distinct Config and Data folders.

freakboy3742 · 2026-08-24T08:03:36Z

Thanks for those updates; to set expectations - I'm about to head to PyCon AU, so my bandwidth to review code will be reduced for about a week. I'll take a look if I get a chance, but it might take a little longer than normal.

Oliver-Leigh added 30 commits May 25, 2026 20:20

WinUI 3 proof of concept

326b37c

Added Status Icons

164fc78

Change to procator start for version compatibility

6838901

Minor fixes and changes

e67e6e2

Add fonts and refactor gdiplus

0fff5f5

Refactor native properties and staged properties

65231a5

Add minimum window and container sizes

754ee47

Minor fix to container

fdcf9f4

Refactor GDI+ functions and add get_pixels

a0a47a1

Improve Window closing, states and visibility

0b6f6ec

Fix cursor and window show/hide

8926d50

Fix Icon for use with Button

adfcd66

Fixes to property staging

4dc6825

More fixes to property staging

9b12c53

Fixes to font exception types

0b348c8

Fix Icon error handling and add new file formats

d84665c

Improvements to status icons

8524c16

Add reactive proactor

77ebc23

Update interop to win32more

41ec3e0

Fix Button icon size and background color

352c5f3

Improve native event handling

d8aeddf

Add background to Label widget

204f84b

Align Window states with Toga API requirements

a372601

Add WinUI 3 testbed

0b6016c

Add test skips for unimplemented modules

2b10166

Add skips to test_app.py and make menu tests async

d1db8c0

Add await within app_probe.assert_system_menus()

ea4af2e

Add base, app and window probes - test_app passing

fbe9c52

Improve app probe - test_statusicons passing

fe2a5e5

Make StatusIcon activation tests async

e4a2911

Oliver-Leigh added 3 commits August 3, 2026 13:22

Improve DPI handling

fdd4097

Minor changes to tests

002a18e

Minor fixes and changes from review

912819c

Oliver-Leigh added 9 commits August 5, 2026 13:38

Consolidate test skips into module level skips

6c298c5

Property staging revamp and other minor changes

2c2367e

Improve the testing of property staging

98cb359

Improve backend for test_menu_visit_homepage

816112b

Improve backend for test_menu_visit_homepage, II

d36dff8

Improve menu item selection on testbed backend

9889c93

Debug testbed instability, I

8c25963

Debug testbed instability, II

961684d

Debug testbed instability, III

92eb3fb

Oliver-Leigh added 8 commits August 7, 2026 07:50

Use while loops over for loops when test waiting

4133186

Fixes to window state changes

bc09a33

Minor updates to loop and fixes to loop shutdown

fa0adc1

Fix to window min_size for DPI changes

06241ab

Add DPI change test

2748010

Fix DPI test

fec9e1c

Reduce DPI test window size to fit CI runner

fb13e2c

Improve flaky Icon tests

a936808

freakboy3742 requested changes Aug 20, 2026

View reviewed changes

Changes based on review

5b3ea7b

Oliver-Leigh added 5 commits August 24, 2026 16:05

Add TextInput implementation

6aca287

Test backend for TextInput

7c27121

Merge branch 'main' into winui-3

af084a5

Use platformdirs for Paths module

8b9f8d7

Minor changes to Label

838be37

Uh oh!

Uh oh!

Conversation

Oliver-Leigh commented Jul 27, 2026

PR Checklist:

Uh oh!

Oliver-Leigh commented Aug 3, 2026

Uh oh!

johnzhou721 commented Aug 6, 2026

Uh oh!

freakboy3742 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

freakboy3742 commented Aug 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants