Winforms Tree widget

changes/4235.feature.md

@@ -0,0 +1 @@
+The Tree widget is now supported in the Windows backend.

docs/en/reference/data/apis_by_platform.yaml

@@ -187,7 +187,6 @@ Widgets:
   Tree:
     description: A hierarchical tree of tabular data.
     unsupported:
-      - winforms
       - iOS
       - android
       - web

examples/tree/tree/app.py

@@ -16,7 +16,12 @@
         "rating": "6.1",
         "genre": "Animation, Adventure, Comedy",
     },
-    {"year": 1998, "title": "Bees", "rating": "6.3", "genre": "Horror"},
+    {
+        "year": 1998,
+        "title": "Bees",
+        "rating": "6.3",
+        "genre": "Horror",
+    },
     {
         "year": 2007,
         "title": "The Girl Who Swallowed Bees",
@@ -64,7 +69,9 @@ def on_select_handler(self, widget):
     # Button callback functions
     def insert_handler(self, widget, **kwargs):
         item = choice(bee_movies)
-        if (year := item["year"]) >= 2000:
+        if (year := item["year"]) >= 2010:
+            root = self.decade_2010s
+        elif year >= 2000:
             root = self.decade_2000s
         elif year >= 1990:
             root = self.decade_1990s
@@ -100,26 +107,37 @@ def startup(self):
             missing_value="?",
         )
 
-        self.decade_1940s = self.tree.data.append(
-            {"year": "1940s", "title": "", "rating": "", "genre": ""}
+        century_1900s = self.tree.data.append(
+            {"year": "2000s", "title": "20th Century", "rating": "", "genre": ""}
         )
-        self.decade_1950s = self.tree.data.append(
-            {"year": "1950s", "title": "", "rating": "", "genre": ""}
+        century_2000s = self.tree.data.append(
+            {"year": "2000s", "title": "21st Century", "rating": "", "genre": ""}
         )
-        self.decade_1960s = self.tree.data.append(
-            {"year": "1960s", "title": "", "rating": "", "genre": ""}
+
+        self.decade_1940s = century_1900s.append(
+            {"year": "1940s", "title": "Roaring 40s", "rating": "", "genre": ""}
         )
-        self.decade_1970s = self.tree.data.append(
-            {"year": "1970s", "title": "", "rating": "", "genre": ""}
+        self.decade_1950s = century_1900s.append(
+            {"year": "1950s", "title": "Golden 50s", "rating": "", "genre": ""}
         )
-        self.decade_1980s = self.tree.data.append(
-            {"year": "1980s", "title": "", "rating": "", "genre": ""}
+        self.decade_1960s = century_1900s.append(
+            {"year": "1960s", "title": "Swinging 60s", "rating": "", "genre": ""}
         )
-        self.decade_1990s = self.tree.data.append(
-            {"year": "1990s", "title": "", "rating": "", "genre": ""}
+        self.decade_1970s = century_1900s.append(
+            {"year": "1970s", "title": "Groovy 70s", "rating": "", "genre": ""}
+        )
+        self.decade_1980s = century_1900s.append(
+            {"year": "1980s", "title": "Radical 80s", "rating": "", "genre": ""}
+        )
+        self.decade_1990s = century_1900s.append(
+            {"year": "1990s", "title": "Grunge 90s", "rating": "", "genre": ""}
+        )
+
+        self.decade_2000s = century_2000s.append(
+            {"year": "2000s", "title": "Naughty 00s", "rating": "", "genre": ""}
         )
-        self.decade_2000s = self.tree.data.append(
-            {"year": "2000s", "title": "", "rating": "", "genre": ""}
+        self.decade_2010s = century_2000s.append(
+            {"year": "2010s", "title": "Modern 10s", "rating": "", "genre": ""}
         )
 
         # Buttons

testbed/tests/widgets/test_tree.py

@@ -107,7 +107,7 @@ def source():
 
 @pytest.fixture
 async def widget(source, on_select_handler, on_activate_handler):
-    skip_on_platforms("iOS", "android", "windows")
+    skip_on_platforms("iOS", "android")
     return toga.Tree(
         ["A", "B", "C"],
         data=source,
@@ -120,7 +120,7 @@ async def widget(source, on_select_handler, on_activate_handler):
 
 @pytest.fixture
 async def headerless_widget(source, on_select_handler):
-    skip_on_platforms("iOS", "android", "windows")
+    skip_on_platforms("iOS", "android")
     return toga.Tree(
         columns=[
             AccessorColumn(None, "a"),
@@ -152,7 +152,7 @@ async def headerless_probe(main_window, headerless_widget):
 @pytest.fixture
 async def multiselect_widget(source, on_select_handler):
     # Although Android *has* a table implementation, it needs to be rebuilt.
-    skip_on_platforms("iOS", "android", "windows")
+    skip_on_platforms("iOS", "android")
     return toga.Tree(
         ["A", "B", "C"],
         data=source,
@@ -179,11 +179,7 @@ async def multiselect_probe(main_window, multiselect_widget):
 test_cleanup = build_cleanup_test(
     toga.Tree,
     kwargs={"columns": ["A", "B", "C"]},
-    skip_platforms=(
-        "iOS",
-        "android",
-        "windows",
-    ),
+    skip_platforms=("iOS", "android"),
 )
 
 
@@ -228,6 +224,64 @@ async def test_select(widget, probe, source, on_select_handler):
         await probe.redraw("A non-shortcut key was pressed")
         assert widget.selection == source[1][2][0]
 
+    # Test selection remains after node with lower index is expanded
+    widget.collapse()
+    assert not probe.is_expanded(source[3])
+    await probe.select_row((1,))
+    await probe.redraw("A row that is below a row to be expanded is selected")
+    widget.expand(source[3])
+    assert widget.selection == source[1]
+    widget.collapse(source[3])
+    assert not probe.is_expanded(source[3])
+
+    # Test selection remains after the selected node is expanded
+    assert not probe.is_expanded(source[3])
+    await probe.select_row((3,))
+    await probe.redraw("A row that is to be expanded is selected")
+    widget.expand(source[3])
+    assert widget.selection == source[3]
+    widget.collapse(source[3])
+    assert not probe.is_expanded(source[3])
+
+    # Test selection remains after node with higher index is expanded
+    assert not probe.is_expanded(source[3])
+    await probe.select_row((4,))
+    await probe.redraw("A row that is to be expanded is selected")
+    widget.expand(source[3])
+    assert widget.selection == source[4]
+    widget.collapse(source[3])
+    assert not probe.is_expanded(source[3])
+
+    # Test selection remains after node with lower index is collapsed
+    widget.expand(source[3])
+    assert probe.is_expanded(source[3])
+    await probe.select_row((1,))
+    await probe.redraw("A node is expanded and a row with lower index is selected")
+    widget.collapse(source[3])
+    assert widget.selection == source[1]
+    assert not probe.is_expanded(source[3])
+
+    # Test selection remains after root node with higher index is collapsed
+    widget.expand(source[3])
+    assert probe.is_expanded(source[3])
+    await probe.select_row((4,))
+    await probe.redraw(
+        "A node is expanded and a root-row with higher index is selected"
+    )
+    widget.collapse(source[3])
+    assert widget.selection == source[4]
+    assert not probe.is_expanded(source[3])
+
+    if toga.platform.current_platform in {"macOS", "windows"}:
+        # Test that selection is lost after a node containing selection is collapsed.
+        widget.expand(source[3])
+        assert probe.is_expanded(source[3])
+        await probe.select_row((3, 1))
+        await probe.redraw("A node is expanded and a child is selected")
+        widget.collapse(source[3])
+        assert widget.selection is None
+        assert not probe.is_expanded(source[3])
+
 
 async def test_expand_collapse(widget, probe, source):
     """Nodes can be expanded and collapsed"""
@@ -461,6 +515,51 @@ async def test_expand_collapse(widget, probe, source):
     assert not probe.is_expanded(source[2])
     assert not probe.is_expanded(source[2][2])
 
+    # Test WinForms expand/collapse for non-visible nodes.
+    if toga.platform.current_platform == "windows":
+        # Expand non-visible node.
+        widget.expand(source[0][2])
+        await probe.redraw("A non-visible node is expanded.")
+        assert not probe.is_expanded(source[0])
+        assert probe.is_expanded(source[0][2])
+        assert not probe.is_expanded(source[1])
+        assert not probe.is_expanded(source[1][2])
+        assert not probe.is_expanded(source[2])
+        assert not probe.is_expanded(source[2][2])
+
+        # Collapse non-visible node.
+        widget.collapse(source[0][2])
+        await probe.redraw("A non-visible node is collapsed.")
+        assert not probe.is_expanded(source[0])
+        assert not probe.is_expanded(source[0][2])
+        assert not probe.is_expanded(source[1])
+        assert not probe.is_expanded(source[1][2])
+        assert not probe.is_expanded(source[2])
+        assert not probe.is_expanded(source[2][2])
+
+    # Test WinForms node toggle functionality.
+    if toga.platform.current_platform == "windows":
+        # Toggle non-visible node to open.
+        widget.collapse()
+        probe.toggle_node((0, 2))
+        await probe.redraw("A non-visible node is toggled to open.")
+        assert not probe.is_expanded(source[0])
+        assert probe.is_expanded(source[0][2])
+        assert not probe.is_expanded(source[1])
+        assert not probe.is_expanded(source[1][2])
+        assert not probe.is_expanded(source[2])
+        assert not probe.is_expanded(source[2][2])
+
+        # Toggle non-visible node to closed.
+        probe.toggle_node((0, 2))
+        await probe.redraw("A non-visible node is toggled to closed.")
+        assert not probe.is_expanded(source[0])
+        assert not probe.is_expanded(source[0][2])
+        assert not probe.is_expanded(source[1])
+        assert not probe.is_expanded(source[1][2])
+        assert not probe.is_expanded(source[2])
+        assert not probe.is_expanded(source[2][2])
+
 
 async def test_activate(
     widget,
@@ -913,13 +1012,14 @@ async def test_cell_widget(widget, probe):
         warning_check = contextlib.nullcontext()
     else:
         warning_check = pytest.warns(
-            match=".* does not support the use of widgets in cells"
+            match=r".* does not support the use of widgets in cells"
         )
 
     with warning_check:
         widget.data = data
 
-        # Qt backend doesn't know there are widgets until the row is expanded
+        # Qt and Windows backends don't know there are widgets until the row is
+        # expanded.
         await probe.expand_tree()
         await probe.redraw("Tree has data with widgets")
 
@@ -988,3 +1088,55 @@ def test_deprecated_methods(widget, method_name, args, expected_args):
         method(**args)
 
     mock_method.assert_called_once_with(**expected_args)
+
+
+async def test_mouse_events(widget, probe, on_activate_handler):
+    skip_on_platforms("android", "iOS", "linux", "macOS")
+    """Does the widget implement mouse events correctly?"""
+    # These tests are WinForms specific
+    if toga.platform.current_platform != "windows":
+        return
+
+    # Use the small data
+    small_data = [
+        (
+            {"a": "A0", "b": "", "c": ""},
+            [({"a": f"A{i}", "b": i, "c": "C"}, None) for i in range(2)],
+        )
+    ]
+
+    widget.data = small_data
+    widget.collapse()
+    await probe.redraw("Tree is collapsed and awaiting hover of state-change arrow")
+    assert not probe.is_expanded(widget.data[0])
+    await probe.assert_item_mouse_hover((0,))
+
+    widget.expand(widget.data[0])
+    await probe.redraw("A node is expanded and awaiting hover of state-change arrow")
+    assert probe.is_expanded(widget.data[0])
+    await probe.assert_item_mouse_hover((0,))
+
+    # Simulate clicks on the state change arrow.
+    widget.collapse()
+    await probe.redraw("Tree is collapsed and awaiting toggle by mouse click")
+    await probe.single_click((0,), toggle=True, on_item=True)
+    assert widget.selection is None
+    await probe.single_click((0,), toggle=True, on_item=True)
+    assert widget.selection is None
+
+    # Simulate a normal item selection click.
+    await probe.redraw("Tree is collapsed and awaiting an item selection mouse click")
+    await probe.single_click((0,), toggle=False, on_item=True)
+    assert widget.selection == widget.data[0]
+
+    # Simulate a normal selection click in the client area, but away from items.
+    await probe.redraw("Tree is collapsed and awaiting an item selection mouse click")
+    await probe.single_click((0,), toggle=False, on_item=False)
+    assert widget.selection is None
+
+    # Double clicking on a state-change arrow doesn't activate the row.")
+    await probe.double_click_state_change_arrow((0,))
+    on_activate_handler.assert_not_called()
+
+    # Test the mouse cursor leaving the client area
+    await probe.assert_mouse_leave()

winforms/pyproject.toml

@@ -103,7 +103,7 @@ Switch = "toga_winforms.widgets.switch:Switch"
 Table = "toga_winforms.widgets.table:Table"
 TextInput = "toga_winforms.widgets.textinput:TextInput"
 TimeInput = "toga_winforms.widgets.timeinput:TimeInput"
-# Tree = "toga_winforms.widgets.tree:Tree"
+Tree = "toga_winforms.widgets.tree:Tree"
 WebView = "toga_winforms.widgets.webview:WebView"
 
 # Windows

winforms/src/toga_winforms/factory.py

@@ -33,6 +33,7 @@
 from .widgets.table import Table
 from .widgets.textinput import TextInput
 from .widgets.timeinput import TimeInput
+from .widgets.tree import Tree
 from .widgets.webview import WebView
 from .window import MainWindow, Window
 
@@ -85,6 +86,7 @@ def not_implemented(feature):  # pragma: no cover
     "Table",
     "TextInput",
     "TimeInput",
+    "Tree",
     "WebView",
     # Windows
     "Window",

winforms/src/toga_winforms/libs/comctl32classes.py

@@ -2,7 +2,18 @@
     WINFUNCTYPE,
     Structure as c_Structure,
 )
-from ctypes.wintypes import HWND, INT, LPARAM, LPWSTR, UINT, WPARAM
+from ctypes.wintypes import (
+    COLORREF,
+    DWORD,
+    HDC,
+    HWND,
+    INT,
+    LPARAM,
+    LPWSTR,
+    RECT,
+    UINT,
+    WPARAM,
+)
 
 from .win32 import DWORD_PTR, INT_PTR, LRESULT, PUINT, UINT_PTR
 
@@ -37,6 +48,37 @@ class NMHDR(c_Structure):
     ]
 
 
+# https://learn.microsoft.com/en-us/windows/win32/api/commctrl/ns-commctrl-nmcustomdraw
+class NMCUSTOMDRAW(c_Structure):
+    _fields_ = [
+        ("hdr", NMHDR),
+        ("dwDrawStage", DWORD),
+        ("hdc", HDC),
+        ("rc", RECT),
+        ("dwItemSpec", DWORD_PTR),
+        ("uItemState", UINT),
+        ("lItemlParam", LPARAM),
+    ]
+
+
+# https://learn.microsoft.com/en-us/windows/win32/api/commctrl/ns-commctrl-nmlvcustomdraw
+class NMLVCUSTOMDRAW(c_Structure):
+    _fields_ = [
+        ("nmcd", NMCUSTOMDRAW),
+        ("clrText", COLORREF),
+        ("clrTextBk", COLORREF),
+        ("iSubItem", INT),
+        ("dwItemType", DWORD),
+        ("clrFace", COLORREF),
+        ("iIconEffect", INT),
+        ("iIconPhase", INT),
+        ("iPartId", INT),
+        ("iStateId", INT),
+        ("rcText", RECT),
+        ("uAlign", UINT),
+    ]
+
+
 # https://learn.microsoft.com/en-us/windows/win32/api/commctrl/ns-commctrl-nmlvdispinfow
 class NMLVDISPINFOW(c_Structure):
     _fields_ = [