Merge branch 'main' of https://github.com/flet-dev/flet

Author: FeodorFitsner

sdk/python/flet/alert_dialog.py

@@ -10,6 +10,57 @@
 
 
 class AlertDialog(Control):
+    """
+    An alert dialog informs the user about situations that require acknowledgement. An alert dialog has an optional title and an optional list of actions. The title is displayed above the content and the actions are displayed below the content.
+    
+    Example:
+    ```
+    import flet as ft
+
+    def main(page: ft.Page):
+        page.title = "AlertDialog examples"
+
+        dlg = ft.AlertDialog(
+            title=ft.Text("Hello, you!"), on_dismiss=lambda e: print("Dialog dismissed!")
+        )
+
+        def close_dlg(e):
+            dlg_modal.open = False
+            page.update()
+
+        dlg_modal = ft.AlertDialog(
+            modal=True,
+            title=ft.Text("Please confirm"),
+            content=ft.Text("Do you really want to delete all those files?"),
+            actions=[
+                ft.TextButton("Yes", on_click=close_dlg),
+                ft.TextButton("No", on_click=close_dlg),
+            ],
+            actions_alignment=ft.MainAxisAlignment.END,
+            on_dismiss=lambda e: print("Modal dialog dismissed!"),
+        )
+
+        def open_dlg(e):
+            page.dialog = dlg
+            dlg.open = True
+            page.update()
+
+        def open_dlg_modal(e):
+            page.dialog = dlg_modal
+            dlg_modal.open = True
+            page.update()
+
+        page.add(
+            ft.ElevatedButton("Open dialog", on_click=open_dlg),
+            ft.ElevatedButton("Open modal dialog", on_click=open_dlg_modal),
+        )
+
+    ft.app(target=main)
+    ```
+    -----
+
+    Online docs: https://flet.dev/docs/controls/alertdialog
+    """
     def __init__(
         self,
         ref: Optional[Ref] = None,

sdk/python/flet/animated_switcher.py

@@ -31,6 +31,54 @@ class AnimatedSwitcherTransition(Enum):
 
 
 class AnimatedSwitcher(ConstrainedControl):
+    """
+    A control that by default does a cross-fade between a new control and the control previously set on the AnimatedSwitcher as a `content`.
+
+    Example:
+    ```
+    import flet as ft
+
+    def main(page: ft.Page):
+
+        c1 = ft.Container(
+            ft.Text("Hello!", style=ft.TextThemeStyle.HEADLINE_MEDIUM),
+            alignment=ft.alignment.center,
+            width=200,
+            height=200,
+            bgcolor=ft.colors.GREEN,
+        )
+        c2 = ft.Container(
+            ft.Text("Bye!", size=50),
+            alignment=ft.alignment.center,
+            width=200,
+            height=200,
+            bgcolor=ft.colors.YELLOW,
+        )
+        c = ft.AnimatedSwitcher(
+            content=c1,
+            transition=ft.AnimatedSwitcherTransition.SCALE,
+            duration=500,
+            reverse_duration=100,
+            switch_in_curve=ft.AnimationCurve.BOUNCE_OUT,
+            switch_out_curve=ft.AnimationCurve.BOUNCE_IN,
+        )
+
+        def animate(e):
+            c.content = c2 if c.content == c1 else c1
+            c.update()
+
+        page.add(
+            c,
+            ft.ElevatedButton("Animate!", on_click=animate),
+        )
+
+    ft.app(target=main)
+    ```
+
+    -----
+
+    Online docs: https://flet.dev/docs/controls/animatedswitcher
+    """
     def __init__(
         self,
         content: Optional[Control] = None,

sdk/python/flet/app_bar.py

@@ -8,6 +8,48 @@
 
 
 class AppBar(Control):
+    """
+    A material design app bar.
+
+    Example:
+    ```
+    import flet as ft
+
+    def main(page: ft.Page):
+        def check_item_clicked(e):
+            e.control.checked = not e.control.checked
+            page.update()
+
+        page.appbar = ft.AppBar(
+            leading=ft.Icon(ft.icons.PALETTE),
+            leading_width=40,
+            title=ft.Text("AppBar Example"),
+            center_title=False,
+            bgcolor=ft.colors.SURFACE_VARIANT,
+            actions=[
+                ft.IconButton(ft.icons.WB_SUNNY_OUTLINED),
+                ft.IconButton(ft.icons.FILTER_3),
+                ft.PopupMenuButton(
+                    items=[
+                        ft.PopupMenuItem(text="Item 1"),
+                        ft.PopupMenuItem(),  # divider
+                        ft.PopupMenuItem(
+                            text="Checked item", checked=False, on_click=check_item_clicked
+                        ),
+                    ]
+                ),
+            ],
+        )
+        page.add(ft.Text("Body!"))
+
+    ft.app(target=main)
+
+    ```
+
+    -----
+
+    Online docs: https://flet.dev/docs/controls/appbar
+    """
     def __init__(
         self,
         ref: Optional[Ref] = None,
@@ -63,6 +105,11 @@ def leading(self) -> Optional[Control]:
     @leading.setter
     @beartype
     def leading(self, value: Optional[Control]):
+        """
+        A Control to display before the toolbar's title.
+
+        Typically the leading control is an Icon or an IconButton.
+        """
         self.__leading = value
 
     # leading_width

sdk/python/flet/audio.py

@@ -31,6 +31,32 @@ class AudioMethodResults:
 
 
 class Audio(Control):
+    """
+    A control to simultaneously play multiple audio files. Works on macOS, Linux, Windows, iOS, Android and web. Based on audioplayers Flutter widget (https://pub.dev/packages/audioplayers).
+
+    Audio control is non-visual and should be added to `page.overlay` list.
+
+    Example:
+    ```
+    import flet as ft
+
+    def main(page: ft.Page):
+        audio1 = ft.Audio(
+            src="https://luan.xyz/files/audio/ambient_c_motion.mp3", autoplay=True
+        )
+        page.overlay.append(audio1)
+        page.add(
+            ft.Text("This is an app with background audio."),
+            ft.ElevatedButton("Stop playing", on_click=lambda _: audio1.pause()),
+        )
+
+    ft.app(target=main)
+    ```
+
+    -----
+
+    Online docs: https://flet.dev/docs/controls/audio
+    """
     def __init__(
         self,
         src: Optional[str] = None,

sdk/python/flet/banner.py

@@ -9,6 +9,46 @@
 
 
 class Banner(Control):
+    """
+    A banner displays an important, succinct message, and provides actions for users to address (or dismiss the banner). A user action is required for it to be dismissed.
+
+    Banners are displayed at the top of the screen, below a top app bar. They are persistent and non-modal, allowing the user to either ignore them or interact with them at any time.
+
+    Example:
+    ```
+    import flet as ft
+
+    def main(page):
+        def close_banner(e):
+            page.banner.open = False
+            page.update()
+
+        page.banner = ft.Banner(
+            bgcolor=ft.colors.AMBER_100,
+            leading=ft.Icon(ft.icons.WARNING_AMBER_ROUNDED, color=ft.colors.AMBER, size=40),
+            content=ft.Text(
+                "Oops, there were some errors while trying to delete the file. What would you like me to do?"
+            ),
+            actions=[
+                ft.TextButton("Retry", on_click=close_banner),
+                ft.TextButton("Ignore", on_click=close_banner),
+                ft.TextButton("Cancel", on_click=close_banner),
+            ],
+        )
+
+        def show_banner_click(e):
+            page.banner.open = True
+            page.update()
+
+        page.add(ft.ElevatedButton("Show Banner", on_click=show_banner_click))
+
+    ft.app(target=main)
+    ```
+
+    -----
+
+    Online docs: https://flet.dev/docs/controls/banner
+    """
     def __init__(
         self,
         ref: Optional[Ref] = None,

sdk/python/flet/bottom_sheet.py

@@ -8,6 +8,49 @@
 
 
 class BottomSheet(Control):
+    """
+    A modal bottom sheet is an alternative to a menu or a dialog and prevents the user from interacting with the rest of the app.
+    
+    Example:
+    ```
+    import flet as ft
+
+    def main(page: ft.Page):
+        def bs_dismissed(e):
+            print("Dismissed!")
+
+        def show_bs(e):
+            bs.open = True
+            bs.update()
+
+        def close_bs(e):
+            bs.open = False
+            bs.update()
+
+        bs = ft.BottomSheet(
+            ft.Container(
+                ft.Column(
+                    [
+                        ft.Text("This is sheet's content!"),
+                        ft.ElevatedButton("Close bottom sheet", on_click=close_bs),
+                    ],
+                    tight=True,
+                ),
+                padding=10,
+            ),
+            open=True,
+            on_dismiss=bs_dismissed,
+        )
+        page.overlay.append(bs)
+        page.add(ft.ElevatedButton("Display bottom sheet", on_click=show_bs))
+
+    ft.app(target=main)
+    ```
+
+    -----
+
+    Online docs: https://flet.dev/docs/controls/bottomsheet
+    """
     def __init__(
         self,
         content: Optional[Control] = None,

sdk/python/flet/card.py

@@ -16,6 +16,48 @@
 
 
 class Card(ConstrainedControl):
+    """
+    A material design card: a panel with slightly rounded corners and an elevation shadow.
+
+    Example:
+    ```
+    import flet as ft
+
+    def main(page):
+        page.title = "Card Example"
+        page.add(
+            ft.Card(
+                content=ft.Container(
+                    content=ft.Column(
+                        [
+                            ft.ListTile(
+                                leading=ft.Icon(ft.icons.ALBUM),
+                                title=ft.Text("The Enchanted Nightingale"),
+                                subtitle=ft.Text(
+                                    "Music by Julie Gable. Lyrics by Sidney Stein."
+                                ),
+                            ),
+                            ft.Row(
+                                [ft.TextButton("Buy tickets"), ft.TextButton("Listen")],
+                                alignment=ft.MainAxisAlignment.END,
+                            ),
+                        ]
+                    ),
+                    width=400,
+                    padding=10,
+                )
+            )
+        )
+
+    ft.app(target=main)
+
+    ```
+
+    -----
+
+    Online docs: https://flet.dev/docs/controls/card
+    """
+
     def __init__(
         self,
         content: Optional[Control] = None,

sdk/python/flet/checkbox.py

@@ -24,6 +24,38 @@
 
 
 class Checkbox(ConstrainedControl):
+    """
+    Checkbox allows to select one or more items from a group, or switch between two mutually exclusive options (checked or unchecked, on or off).
+    
+    Example:
+    ```
+    import flet as ft
+
+    def main(page):
+        def button_clicked(e):
+            t.value = (
+                f"Checkboxes values are:  {c1.value}, {c2.value}, {c3.value}, {c4.value}, {c5.value}."
+            )
+            page.update()
+
+        t = ft.Text()
+        c1 = ft.Checkbox(label="Unchecked by default checkbox", value=False)
+        c2 = ft.Checkbox(label="Undefined by default tristate checkbox", tristate=True)
+        c3 = ft.Checkbox(label="Checked by default checkbox", value=True)
+        c4 = ft.Checkbox(label="Disabled checkbox", disabled=True)
+        c5 = ft.Checkbox(
+            label="Checkbox with rendered label_position='left'", label_position=ft.LabelPosition.LEFT
+        )
+        b = ft.ElevatedButton(text="Submit", on_click=button_clicked)
+        page.add(c1, c2, c3, c4, c5, b, t)
+
+    ft.app(target=main)
+    ```
+
+    -----
+
+    Online docs: https://flet.dev/docs/controls/checkbox
+    """
     def __init__(
         self,
         ref: Optional[Ref] = None,