More control images for docs, create_gif helper method (#5717)

* Add BottomAppBar example and integration test

Updated documentation to include a new example image and code snippet for BottomAppBar. Added an integration test and corresponding golden image for visual regression testing of the BottomAppBar control.

* Add Canvas example and test for documentation

Updated Canvas documentation to include a basic example image and code snippet. Added a corresponding integration test and golden image for screenshot validation. Adjusted image references in docs to use new example image and media paths.

* Add example and test for CupertinoActionSheet

Updated documentation to include a new example image and code snippet for CupertinoActionSheet. Added an integration test and corresponding golden image for documentation purposes.

* Update CupertinoActivityIndicator docs and add test

Updated documentation for CupertinoActivityIndicator to include a new example image and improved example references. Added a golden image and an integration test for the control to ensure visual consistency. Also enhanced the docstring with a usage example.

* Add BottomSheet example and integration test

Updated documentation for BottomSheet with a new example image and code snippet. Added an integration test and corresponding screenshot for the BottomSheet control to improve test coverage and documentation clarity.

* Add alert dialog example tests and update docs

Introduced integration tests and golden images for alert dialog examples, covering both modal and non-modal dialogs. Updated documentation to use new screenshots instead of GIFs, and improved the example code to use a main guard. Added an empty __init__.py for the alert_dialog example package.

* Add GIF creation utility to FletTestApp

Introduces a create_gif method to FletTestApp for generating animated GIFs from a sequence of PNG images. Integration test for alert dialog now uses this method to create a GIF of the dialog flow when golden images are enabled.

* Update alert dialog test to set GIF duration

Added the 'duration=500' parameter to the create_gif call in test_alert_dialog.py to control the frame duration. Updated the corresponding golden GIF to reflect this change.

* Update alert dialog test GIF generation timing

Adjusted the sequence and duration of frames in the alert dialog test GIF for improved clarity. Default GIF frame duration in FletTestApp was increased to 1000ms, and the test now uses a longer duration and an updated frame sequence.

* Update alertdialog docs with GIF example

Replaced three static images with a single GIF to better illustrate modal and non-modal dialog flows in the alertdialog documentation.

Author: InesaFitsner

sdk/python/examples/controls/alert_dialog/__init__.py

@@ -36,4 +36,5 @@ def main(page: ft.Page):
     )
 
 
-ft.run(main)
+if __name__ == "__main__":
+    ft.run(main)

sdk/python/examples/controls/alert_dialog/modal_and_non_modal.py

@@ -2,7 +2,6 @@
 class_name: flet.AlertDialog
 examples: ../../examples/controls/alert_dialog
 example_images: ../test-images/examples/material/golden/macos/alert_dialog
-example_media: ../examples/controls/alert_dialog/media
 ---
 
 {{ class_summary(class_name, example_images + "/image_for_docs.png", image_caption="Basic AlertDialog") }}
@@ -17,7 +16,7 @@ example_media: ../examples/controls/alert_dialog/media
 --8<-- "{{ examples }}/modal_and_non_modal.py"
 ```
 
-{{ image(example_media + "/modal_and_non_modal.gif", alt="modal-and-non-modal", width="80%") }}
+{{ image(example_images + "/alert_dialog_flow.gif", alt="Modal and non-modal dialogs", caption="Modal and non-modal dialogs",width="50%") }}
 
 
 {{ class_members(class_name) }}

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

@@ -1,10 +1,11 @@
 ---
 class_name: flet.BottomAppBar
 examples: ../../examples/controls/bottom_app_bar
-example_images: ../examples/controls/bottom_app_bar/media
+example_images: ../test-images/examples/material/golden/macos/bottom_app_bar
+example_media: ../examples/controls/bottom_app_bar/media
 ---
 
-{{ class_summary(class_name) }}
+{{ class_summary(class_name, example_images + "/image_for_docs.png", image_caption="Basic BottomAppBar", image_width="100%") }}
 
 ## Examples
 
@@ -16,7 +17,7 @@ example_images: ../examples/controls/bottom_app_bar/media
 --8<-- "{{ examples }}/notched_fab.py"
 ```
 
-{{ image(example_images + "/notched_fab.png", alt="notched-fab", width="80%") }}
+{{ image(example_media + "/notched_fab.png", alt="notched-fab", width="80%") }}
 
 
 {{ class_members(class_name) }}

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

@@ -1,10 +1,11 @@
 ---
 class_name: flet.BottomSheet
 examples: ../../examples/controls/bottom_sheet
-example_images: ../examples/controls/bottom_sheet/media
+example_images: ../test-images/examples/material/golden/macos/bottom_sheet
+example_media: ../examples/controls/bottom_sheet/media
 ---
 
-{{ class_summary(class_name) }}
+{{ class_summary(class_name, example_images + "/image_for_docs.png", image_caption="Basic BottomSheet") }}
 
 ## Examples
 
@@ -16,7 +17,7 @@ example_images: ../examples/controls/bottom_sheet/media
 --8<-- "{{ examples }}/basic.py"
 ```
 
-{{ image(example_images + "/basic.gif", alt="basic", width="80%") }}
+{{ image(example_media + "/basic.gif", alt="basic", width="80%") }}
 
 
 {{ class_members(class_name) }}

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

@@ -1,12 +1,13 @@
 ---
 class_name: flet.canvas.Canvas
 examples: ../../examples/controls/canvas
-example_images: ../../examples/controls/canvas/media
+example_images: ../../test-images/examples/core/golden/macos/canvas
+example_media: ../../examples/controls/canvas/media
 ---
 
 # Canvas
 
-{{ class_summary(class_name) }}
+{{ class_summary(class_name, example_images + "/image_for_docs.png", image_caption="Basic Canvas") }}
 
 ## Examples
 
@@ -18,7 +19,7 @@ example_images: ../../examples/controls/canvas/media
 --8<-- "{{ examples }}/smiling_face.py"
 ```
 
-{{ image(example_images + "/smiling_face.png", alt="smiling-face", width="80%") }}
+{{ image(example_media + "/smiling_face.png", alt="smiling-face", width="80%") }}
 
 
 ### Flet logo
@@ -27,7 +28,7 @@ example_images: ../../examples/controls/canvas/media
 --8<-- "{{ examples }}/flet_logo.py"
 ```
 
-{{ image(example_images + "/flet_logo.png", alt="flet-logo", width="80%") }}
+{{ image(example_media + "/flet_logo.png", alt="flet-logo", width="80%") }}
 
 
 ### Triangles
@@ -36,7 +37,7 @@ example_images: ../../examples/controls/canvas/media
 --8<-- "{{ examples }}/triangles.py"
 ```
 
-{{ image(example_images + "/triangles.png", alt="triangles", width="80%") }}
+{{ image(example_media + "/triangles.png", alt="triangles", width="80%") }}
 
 
 ### Bezier curves
@@ -45,7 +46,7 @@ example_images: ../../examples/controls/canvas/media
 --8<-- "{{ examples }}/bezier_curves.py"
 ```
 
-{{ image(example_images + "/bezier_curves.png", alt="bezier-curves", width="80%") }}
+{{ image(example_media + "/bezier_curves.png", alt="bezier-curves", width="80%") }}
 
 
 ### Text
@@ -54,7 +55,7 @@ example_images: ../../examples/controls/canvas/media
 --8<-- "{{ examples }}/text.py"
 ```
 
-{{ image(example_images + "/text.png", alt="text", width="80%") }}
+{{ image(example_media + "/text.png", alt="text", width="80%") }}
 
 
 ### Free-hand drawing with image capture

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

@@ -1,12 +1,13 @@
 ---
 class_name: flet.CupertinoActionSheet
 examples: ../../examples/controls/cupertino_action_sheet
-example_images: ../../examples/controls/cupertino_action_sheet/media
+example_images: ../../test-images/examples/cupertino/golden/macos/cupertino_action_sheet
+example_media: ../../examples/controls/cupertino_action_sheet/media
 ---
 
 # CupertinoActionSheet
 
-{{ class_summary(class_name) }}
+{{ class_summary(class_name, example_images + "/image_for_docs.png", image_caption="Basic CupertinoActionSheet") }}
 
 ## Examples
 
@@ -18,7 +19,7 @@ example_images: ../../examples/controls/cupertino_action_sheet/media
 --8<-- "{{ examples }}/basic.py"
 ```
 
-{{ image(example_images + "/basic.png", alt="basic", width="80%") }}
+{{ image(example_media + "/basic.png", alt="basic", width="80%") }}
 
 
 {{ class_members(class_name) }}

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

@@ -1,10 +1,11 @@
 ---
 class_name: flet.CupertinoActivityIndicator
 examples: ../../examples/controls/cupertino_activity_indicator
-example_images: ../examples/controls/cupertino_activity_indicator/media
+example_images: ../test-images/examples/cupertino/golden/macos/cupertino_activity_indicator
+example_media: ../examples/controls/cupertino_activity_indicator/media
 ---
 
-{{ class_summary(class_name) }}
+{{ class_summary(class_name, example_images + "/image_for_docs.png", image_caption="Basic CupertinoActivityIndicator") }}
 
 ## Examples
 
@@ -16,7 +17,7 @@ example_images: ../examples/controls/cupertino_activity_indicator/media
 --8<-- "{{ examples }}/basic.py"
 ```
 
-{{ image(example_images + "/basic.png", alt="basic", width="80%") }}
+{{ image(example_media + "/basic.png", alt="basic", width="80%") }}
 
 
 {{ class_members(class_name) }}

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

@@ -0,0 +1,38 @@
+import pytest
+
+import flet as ft
+import flet.canvas as cv
+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
+    await flet_app_function.assert_control_screenshot(
+        request.node.name,
+        cv.Canvas(
+            width=160,
+            height=160,
+            shapes=[
+                cv.Rect(
+                    0,
+                    0,
+                    160,
+                    160,
+                    paint=ft.Paint(
+                        color=ft.Colors.BLUE_100,
+                        style=ft.PaintingStyle.FILL,
+                    ),
+                ),
+                cv.Circle(
+                    80,
+                    80,
+                    50,
+                    paint=ft.Paint(
+                        color=ft.Colors.BLUE_400,
+                        style=ft.PaintingStyle.FILL,
+                    ),
+                ),
+            ],
+        ),
+    )