Control comments (#681)

* added comments for page, container, tooltip

* comments for view, row

* comments for column

* updated example

* comments

* Update stack.py

* Update list_view.py

* Update list_tile.py

* Update grid_view.py

* Update responsive_row.py

* Update tabs.py

* Update card.py

* Update divider.py

* Update vertical_divider.py

* Update app_bar.py

* Update navigation_rail.py

* navigation_rail and navigation_bar

* Update text.py

* Update icon.py

* Update image.py

* Update markdown.py

* Update circle_avatar.py

* Update progress_bar.py

* Update progress_ring.py

* Update elevated_button.py

* Update filled_button.py

* Update filled_tonal_button.py

* Update floating_action_button.py

* Update icon_button.py

* Update outlined_button.py

* Update popup_menu_button.py

* Update text_button.py

* Update checkbox.py

* Update dropdown.py

* Radio and RadioGroup comments

* Update slider.py

* Update switch.py

* Update textfield.py

* Update alert_dialog.py

* Update banner.py

* Update bottom_sheet.py

* Update snack_bar.py

* Update matplotlib_chart.py

* Update plotly_chart.py

* Update animated_switcher.py

* Update audio.py

* Update draggable.py

* Update drag_target.py

* Update file_picker.py

* Update gesture_detector.py

* Update haptic_feedback.py

* Update semantics.py

* Update shader_mask.py

* Update shake_detector.py

* Update window_drag_area.py

Author: InesaFitsner

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,