Owen/control docs p8

sdk/python/examples/controls/menu_bar/nested_submenus.py

@@ -119,4 +119,5 @@ def handle_submenu_hover(e: ft.Event[ft.SubmenuButton]):
     )
 
 
-ft.run(main)
+if __name__ == "__main__":
+    ft.run(main)

sdk/python/examples/controls/menu_item_button/basic.py

@@ -67,4 +67,5 @@ def handle_on_hover(e: ft.Event[ft.MenuItemButton]):
     )
 
 
-ft.run(main)
+if __name__ == "__main__":
+    ft.run(main)

sdk/python/examples/controls/navigation_bar/basic.py

@@ -19,4 +19,5 @@ def main(page: ft.Page):
     page.add(ft.Text("Body!"))
 
 
-ft.run(main)
+if __name__ == "__main__":
+    ft.run(main)

sdk/python/packages/flet/docs/controls/listview.md

@@ -1,10 +1,11 @@
 ---
 class_name: flet.ListView
 examples: ../../examples/controls/list_view
-example_images: ../examples/controls/list_view/media
+example_media: ../examples/controls/list_view/media
+example_images: ../test-images/examples/core/golden/macos/list_view
 ---
 
-{{ class_summary(class_name) }}
+{{ class_summary(class_name, example_images + "/image_for_docs.png", image_caption="Basic list view") }}
 
 ## Examples
 
@@ -16,7 +17,7 @@ example_images: ../examples/controls/list_view/media
 --8<-- "{{ examples }}/autoscroll_and_dynamic_items.py"
 ```
 
-{{ image(example_images + "/autoscroll_and_dynamic_items.gif", alt="autoscroll-and-dynamic-items", width="80%") }}
+{{ image(example_media + "/autoscroll_and_dynamic_items.gif", alt="autoscroll-and-dynamic-items", width="80%") }}
 
 
 {{ class_members(class_name) }}

sdk/python/packages/flet/docs/controls/menubar.md

@@ -1,10 +1,10 @@
 ---
 class_name: flet.MenuBar
 examples: ../../examples/controls/menu_bar
-example_images: ../examples/controls/menu_bar/media
+example_images: ../test-images/examples/material/golden/macos/menu_bar
 ---
 
-{{ class_summary(class_name) }}
+{{ class_summary(class_name, example_images + "/image_for_docs.png", image_caption="Basic menu bar") }}
 
 ## Examples
 

sdk/python/packages/flet/docs/controls/menuitembutton.md

@@ -1,10 +1,10 @@
 ---
 class_name: flet.MenuItemButton
 examples: ../../examples/controls/menu_item_button
-example_images: ../examples/controls/menu_item_button/media
+example_images: ../test-images/examples/material/golden/macos/menu_item_button
 ---
 
-{{ class_summary(class_name) }}
+{{ class_summary(class_name, example_images + "/image_for_docs.png", image_caption="Menu item buttons outside of menubar") }}
 
 ## Examples
 

sdk/python/packages/flet/docs/controls/navigationbar/index.md

@@ -1,12 +1,12 @@
 ---
 class_name: flet.NavigationBar
 examples: ../../examples/controls/navigation_bar
-example_images: ../../examples/controls/navigation_bar/media
+example_images: ../../test-images/examples/material/golden/macos/navigation_bar
 ---
 
 # NavigationBar
 
-{{ class_summary(class_name) }}
+{{ class_summary(class_name, example_images + "/image_for_docs.png", image_caption="Simple navigation bar") }}
 
 ## Examples
 
@@ -18,7 +18,7 @@ example_images: ../../examples/controls/navigation_bar/media
 --8<-- "{{ examples }}/basic.py"
 ```
 
-{{ image(example_images + "/basic.gif", alt="basic", width="80%") }}
+{{ image(example_images + "/basic.png", alt="basic", width="80%") }}
 
 
 {{ class_members(class_name) }}

sdk/python/packages/flet/integration_tests/examples/core/test_list_view.py

@@ -0,0 +1,18 @@
+import pytest
+
+import flet as ft
+import flet.testing as ftt
+
+
+@pytest.mark.asyncio(loop_scope="function")
+async def test_image_for_docs(flet_app_function: ftt.FletTestApp, request):
+    flet_app_function.page.theme_mode = ft.ThemeMode.LIGHT
+    flet_app_function.resize_page(100, 300)
+    flet_app_function.page.update()
+    await flet_app_function.assert_control_screenshot(
+        request.node.name,
+        ft.ListView(
+            controls=[ft.Text(f"Item {i}") for i in range(1, 6)],
+            divider_thickness=1,
+        ),
+    )

sdk/python/packages/flet/integration_tests/examples/material/test_menu_bar.py

@@ -0,0 +1,82 @@
+import pytest
+
+import flet as ft
+import flet.testing as ftt
+
+from examples.controls.menu_bar import nested_submenus
+
+
+@pytest.mark.asyncio(loop_scope="function")
+async def test_image_for_docs(flet_app_function: ftt.FletTestApp, request):
+    flet_app_function.page.theme_mode = ft.ThemeMode.LIGHT
+    flet_app_function.page.enable_screenshots = True
+    flet_app_function.resize_page(100, 200)
+    flet_app_function.page.update()
+    mb = ft.MenuBar(
+        controls=[
+            ft.SubmenuButton(
+                content=ft.Text("Submenu"),
+                controls=[
+                    ft.MenuItemButton(content=ft.Text("Item 1")),
+                    ft.MenuItemButton(content=ft.Text("Item 2")),
+                    ft.MenuItemButton(content=ft.Text("Item 3")),
+                ],
+            ),
+        ],
+    )
+    flet_app_function.page.add(mb)
+    flet_app_function.page.update()
+    await flet_app_function.tester.pump_and_settle()
+    btn = await flet_app_function.tester.find_by_text("Submenu")
+    await flet_app_function.tester.tap(btn)
+    await flet_app_function.tester.pump_and_settle()
+
+    flet_app_function.assert_screenshot(
+        "image_for_docs",
+        await flet_app_function.page.take_screenshot(),
+    )
+
+
+@pytest.mark.parametrize(
+    "flet_app_function",
+    [{"flet_app_main": nested_submenus.main}],
+    indirect=True,
+)
+@pytest.mark.asyncio(loop_scope="function")
+async def test_nested_submenus(flet_app_function: ftt.FletTestApp):
+    flet_app_function.page.enable_screenshots = True
+    flet_app_function.resize_page(400, 400)
+    flet_app_function.page.update()
+    await flet_app_function.tester.pump_and_settle(
+        duration=ft.Duration(milliseconds=500)
+    )
+    flet_app_function.assert_screenshot(
+        "nested_submenus1",
+        await flet_app_function.page.take_screenshot(
+            pixel_ratio=flet_app_function.screenshots_pixel_ratio
+        ),
+    )
+    smb = await flet_app_function.tester.find_by_text("File")
+    await flet_app_function.tester.tap(smb)
+    await flet_app_function.tester.pump_and_settle()
+    flet_app_function.assert_screenshot(
+        "nested_submenus2",
+        await flet_app_function.page.take_screenshot(
+            pixel_ratio=flet_app_function.screenshots_pixel_ratio
+        ),
+    )
+    mib = await flet_app_function.tester.find_by_text("Save")
+    await flet_app_function.tester.tap(mib)
+    await flet_app_function.tester.pump_and_settle()
+    flet_app_function.assert_screenshot(
+        "nested_submenus3",
+        await flet_app_function.page.take_screenshot(
+            pixel_ratio=flet_app_function.screenshots_pixel_ratio
+        ),
+    )
+
+    flet_app_function.create_gif(
+        ["nested_submenus1", "nested_submenus2", "nested_submenus3"],
+        "nested_submenus",
+        duration=1600,
+    )

sdk/python/packages/flet/integration_tests/examples/material/test_menu_item_button.py

@@ -0,0 +1,80 @@
+import pytest
+
+import flet as ft
+import flet.testing as ftt
+
+from examples.controls.menu_item_button import basic
+
+
+@pytest.mark.asyncio(loop_scope="function")
+async def test_image_for_docs(flet_app_function: ftt.FletTestApp, request):
+    flet_app_function.page.theme_mode = ft.ThemeMode.LIGHT
+    await flet_app_function.assert_control_screenshot(
+        request.node.name,
+        ft.Row(
+            controls=[
+                ft.MenuItemButton(
+                    content=ft.Text("Yes"),
+                    on_click=lambda e: print("yes"),
+                    autofocus=True,
+                ),
+                ft.MenuItemButton(
+                    content=ft.Text("No"),
+                    on_click=lambda e: print("no"),
+                ),
+                ft.MenuItemButton(
+                    content=ft.Text("Maybe"),
+                    on_click=lambda e: print("maybe"),
+                ),
+            ],
+            alignment=ft.MainAxisAlignment.CENTER,
+            height=50,
+            width=200,
+            expand=True,
+        ),
+    )
+
+
+@pytest.mark.parametrize(
+    "flet_app_function",
+    [{"flet_app_main": basic.main}],
+    indirect=True,
+)
+@pytest.mark.asyncio(loop_scope="function")
+async def test_basic(flet_app_function: ftt.FletTestApp):
+    flet_app_function.page.enable_screenshots = True
+    flet_app_function.resize_page(400, 400)
+    flet_app_function.page.update()
+    await flet_app_function.tester.pump_and_settle(
+        duration=ft.Duration(milliseconds=500)
+    )
+    flet_app_function.assert_screenshot(
+        "basic1",
+        await flet_app_function.page.take_screenshot(
+            pixel_ratio=flet_app_function.screenshots_pixel_ratio
+        ),
+    )
+    btn = await flet_app_function.tester.find_by_text("BgColors")
+    await flet_app_function.tester.tap(btn)
+    await flet_app_function.tester.pump_and_settle()
+    flet_app_function.assert_screenshot(
+        "basic2",
+        await flet_app_function.page.take_screenshot(
+            pixel_ratio=flet_app_function.screenshots_pixel_ratio
+        ),
+    )
+    mib = await flet_app_function.tester.find_by_text("Green")
+    await flet_app_function.tester.tap(mib)
+    await flet_app_function.tester.pump_and_settle()
+    flet_app_function.assert_screenshot(
+        "basic3",
+        await flet_app_function.page.take_screenshot(
+            pixel_ratio=flet_app_function.screenshots_pixel_ratio
+        ),
+    )
+
+    flet_app_function.create_gif(
+        ["basic1", "basic2", "basic3"],
+        "basic",
+        duration=1600,
+    )

sdk/python/packages/flet/integration_tests/examples/material/test_navigation_bar.py

@@ -0,0 +1,47 @@
+import pytest
+
+import flet as ft
+import flet.testing as ftt
+
+from examples.controls.navigation_bar import basic
+
+
+@pytest.mark.asyncio(loop_scope="function")
+async def test_image_for_docs(flet_app_function: ftt.FletTestApp, request):
+    flet_app_function.page.theme_mode = ft.ThemeMode.LIGHT
+    flet_app_function.page.enable_screenshots = True
+    nvb = ft.NavigationBar(
+        destinations=[
+            ft.NavigationBarDestination(icon=ft.Icons.CIRCLE, label="Item 1"),
+            ft.NavigationBarDestination(icon=ft.Icons.SQUARE, label="Item 2"),
+            ft.NavigationBarDestination(icon=ft.Icons.HEXAGON, label="Item 3"),
+        ],
+    )
+    flet_app_function.resize_page(300, 100)
+    flet_app_function.page.navigation_bar = nvb
+    flet_app_function.page.update()
+    await flet_app_function.tester.pump_and_settle(
+        duration=ft.Duration(milliseconds=800)
+    )
+    flet_app_function.assert_screenshot(
+        "image_for_docs",
+        await flet_app_function.page.take_screenshot(),
+    )
+
+
+@pytest.mark.parametrize(
+    "flet_app_function",
+    [{"flet_app_main": basic.main}],
+    indirect=True,
+)
+@pytest.mark.asyncio(loop_scope="function")
+async def test_basic(flet_app_function: ftt.FletTestApp):
+    flet_app_function.page.theme_mode = ft.ThemeMode.LIGHT
+    flet_app_function.page.enable_screenshots = True
+    flet_app_function.resize_page(300, 300)
+    flet_app_function.page.update()
+    await flet_app_function.tester.pump_and_settle()
+    flet_app_function.assert_screenshot(
+        "basic",
+        await flet_app_function.page.take_screenshot(),
+    )

sdk/python/packages/flet/src/flet/controls/core/list_view.py

@@ -20,6 +20,13 @@ class ListView(LayoutControl, ScrollableControl, AdaptiveControl):
     ListView is the most commonly used scrolling control. It displays its children one
     after another in the scroll direction. In the cross axis, the children are required
     to fill the ListView.
+
+    ```python
+    ft.ListView(
+        controls=[ft.Text(f"Item {i}") for i in range(1, 6)],
+    )
+    ```
+
     """
 
     controls: list[Control] = field(default_factory=list)

sdk/python/packages/flet/src/flet/controls/material/menu_bar.py

@@ -44,6 +44,22 @@ class MenuBar(Control):
     It could be placed anywhere but typically resides above the main body of the
     application and defines a menu system for invoking callbacks in response to user
     selection of a menu item.
+
+    ```python
+    ft.MenuBar(
+        controls=[
+            ft.SubmenuButton(
+                content=ft.Text("Submenu"),
+                controls=[
+                    ft.MenuItemButton(content=ft.Text("Item 1")),
+                    ft.MenuItemButton(content=ft.Text("Item 2")),
+                    ft.MenuItemButton(content=ft.Text("Item 3")),
+                ],
+            ),
+        ],
+    )
+    ```
+
     """
 
     controls: list[Control] = field(default_factory=list)

sdk/python/packages/flet/src/flet/controls/material/menu_item_button.py

@@ -16,6 +16,26 @@ class MenuItemButton(LayoutControl):
     """
     A button for use in a MenuBar or on its own, that can be activated by click or
     keyboard navigation.
+
+    ```python
+    ft.Row(
+        controls=[
+            ft.MenuItemButton(
+                content=ft.Text("Yes"),
+                on_click=lambda e: print("yes"),
+            ),
+            ft.MenuItemButton(
+                content=ft.Text("No"),
+                on_click=lambda e: print("no"),
+            ),
+            ft.MenuItemButton(
+                content=ft.Text("Maybe"),
+                on_click=lambda e: print("maybe"),
+            ),
+        ],
+    )
+    ```
+
     """
 
     content: Optional[StrOrControl] = None