Inesa/v1 docstrings cupertino

packages/flet/lib/src/controls/cupertino_action_sheet.dart

@@ -14,8 +14,8 @@ class CupertinoActionSheetControl extends StatelessWidget {
     debugPrint("CupertinoActionSheetControl build: ${control.id}");
 
     var sheet = CupertinoActionSheet(
-      title: control.buildWidget("title"),
-      message: control.buildWidget("message"),
+      title: control.buildTextOrWidget("title"),
+      message: control.buildTextOrWidget("message"),
       cancelButton: control.buildWidget("cancel"),
       actions: control.buildWidgets("actions"),
     );

packages/flet/lib/src/controls/cupertino_list_tile.dart

@@ -20,15 +20,15 @@ class CupertinoListTileControl extends StatelessWidget {
   Widget build(BuildContext context) {
     debugPrint("CupertinoListTile build: ${control.id}");
 
-    var title = control.buildWidget("title");
+    var title = control.buildTextOrWidget("title");
     if (title == null) {
       return const ErrorControl(
           "CupertinoListTile.title must be provided and visible");
     }
-    var leading = control.buildWidget("leading");
-    var additionalInfo = control.buildWidget("additional_info");
-    var subtitle = control.buildWidget("subtitle");
-    var trailing = control.buildWidget("trailing");
+    var leading = control.buildIconOrWidget("leading");
+    var additionalInfo = control.buildTextOrWidget("additional_info");
+    var subtitle = control.buildTextOrWidget("subtitle");
+    var trailing = control.buildIconOrWidget("trailing");
     var backgroundColor = control.getColor("bgcolor", context);
     var bgcolorActivated = control.getColor("bgcolor_activated", context);
     var padding = control.getPadding("content_padding");

sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_action_sheet.py

@@ -1,8 +1,9 @@
-from typing import List, Optional
+from typing import Optional
 
 from flet.controls.base_control import control
 from flet.controls.constrained_control import ConstrainedControl
 from flet.controls.control import Control
+from flet.controls.types import StrOrControl
 
 __all__ = ["CupertinoActionSheet"]
 
@@ -12,12 +13,37 @@ class CupertinoActionSheet(ConstrainedControl):
     """
     An iOS-style action sheet.
 
-    -----
-
     Online docs: https://flet.dev/docs/controls/cupertinoactionsheet
     """
 
-    title: Optional[Control] = None
-    message: Optional[Control] = None
-    actions: Optional[List[Control]] = None
+    title: Optional[StrOrControl] = None
+    """
+    A control containing the title of the action sheet.
+
+    Typically a [`Text`](https://flet.dev/docs/controls/text) control.
+    """
+
+    message: Optional[StrOrControl] = None
+    """
+    A control containing a descriptive message that provides more details about the
+    reason for the alert.
+
+    Typically a [`Text`](https://flet.dev/docs/controls/text) control.
+    """
+
+    actions: Optional[list[Control]] = None
+    """
+    A list of action buttons to be shown in the sheet.
+
+    These actions are typically [`CupertinoActionSheetAction`](https://flet.dev/docs/controls/cupertinoactionsheetaction)s.
+
+    This list must have at least one action.
+    """
+
     cancel: Optional[Control] = None
+    """
+    An optional control to be shown below the actions but grouped separately from them.
+
+    Typically a [`CupertinoActionSheetAction`](https://flet.dev/docs/controls/cupertinoactionsheetaction) 
+    button.
+    """

sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_action_sheet_action.py

@@ -12,16 +12,39 @@ class CupertinoActionSheetAction(ConstrainedControl):
     """
     An action button typically used in a CupertinoActionSheet.
 
-    -----
-
     Online docs: https://flet.dev/docs/controls/cupertinoactionsheetaction
     """
 
     content: StrOrControl
+    """
+    The child control to be shown in this action button.
+
+    In case both `text` and `content` are provided, then `content` will be used.
+    """
+
     default: bool = False
+    """
+    Whether this action should receive the style of an emphasized, default action.
+
+    Defaults to `False`.
+    """
+
     destructive: bool = False
+    """
+    Whether this action should receive the style of a destructive action.
+
+    Defaults to `False`.
+    """
+
     mouse_cursor: Optional[MouseCursor] = None
+    """
+    TBD
+    """
+
     on_click: OptionalControlEventCallable = None
+    """
+    Fires when this action button is clicked.
+    """
 
     def before_update(self):
         super().before_update()

sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_activity_indicator.py

@@ -10,11 +10,21 @@ class CupertinoActivityIndicator(ConstrainedControl):
     """
     An iOS-style activity indicator that spins clockwise.
 
-    -----
-
     Online docs: https://flet.dev/docs/controls/cupertinoactivityindicator
     """
 
     radius: Number = 10
+    """
+    The radius of the activity indicator.
+    """
+
     color: OptionalColorValue = None
+    """
+    Defines the [color](https://flet.dev/docs/reference/colors) of the activity 
+    indicator.
+    """
+
     animating: bool = True
+    """
+    Whether the activity indicator is running its animation.
+    """

sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_alert_dialog.py

@@ -1,13 +1,11 @@
 from dataclasses import field
-from typing import List, Optional
+from typing import Optional
 
 from flet.controls.animation import Animation, AnimationCurve
 from flet.controls.base_control import control
 from flet.controls.control import Control
 from flet.controls.dialog_control import DialogControl
-
 from flet.controls.duration import Duration
-
 from flet.controls.types import StrOrControl
 
 __all__ = ["CupertinoAlertDialog"]
@@ -17,97 +15,64 @@
 class CupertinoAlertDialog(DialogControl):
     """
     An iOS-style alert dialog.
-    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.horizontal_alignment = ft.CrossAxisAlignment.CENTER
-        page.scroll = True
-
-        def handle_action_click(e):
-            page.add(ft.Text(f"Action clicked: {e.control.text}"))
-            # e.control is the clicked action button, e.control.parent is the corresponding parent dialog of the button
-            page.close(e.control.parent)
-
-        cupertino_actions = [
-            ft.CupertinoDialogAction(
-                "Yes",
-                is_destructive_action=True,
-                on_click=handle_action_click,
-            ),
-            ft.CupertinoDialogAction(
-                text="No",
-                is_default_action=False,
-                on_click=handle_action_click,
-            ),
-        ]
-
-        material_actions = [
-            ft.TextButton(text="Yes", on_click=handle_action_click),
-            ft.TextButton(text="No", on_click=handle_action_click),
-        ]
-
-        page.add(
-            ft.FilledButton(
-                text="Open Material Dialog",
-                on_click=lambda e: page.open(
-                    ft.AlertDialog(
-                        title=ft.Text("Material Alert Dialog"),
-                        content=ft.Text("Do you want to delete this file?"),
-                        actions=material_actions,
-                    )
-                ),
-            ),
-            ft.CupertinoFilledButton(
-                text="Open Cupertino Dialog",
-                on_click=lambda e: page.open(
-                    ft.CupertinoAlertDialog(
-                        title=ft.Text("Cupertino Alert Dialog"),
-                        content=ft.Text("Do you want to delete this file?"),
-                        actions=cupertino_actions,
-                    )
-                ),
-            ),
-            ft.FilledButton(
-                text="Open Adaptive Dialog",
-                adaptive=True,
-                on_click=lambda e: page.open(
-                    ft.AlertDialog(
-                        adaptive=True,
-                        title=ft.Text("Adaptive Alert Dialog"),
-                        content=ft.Text("Do you want to delete this file?"),
-                        actions=cupertino_actions if page.platform in [ft.PagePlatform.IOS, ft.PagePlatform.MACOS] else material_actions,
-                    )
-                ),
-            ),
-        )
 
-
-    ft.app(target=main)
-    ```
-    -----
+    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.
 
     Online docs: https://flet.dev/docs/controls/cupertinoalertdialog
     """
 
     modal: bool = False
+    """
+    If set to True, dialog cannot be dismissed by clicking the area outside of it.
+    The default value is False.
+    """
+
     title: Optional[StrOrControl] = None
+    """
+    The (optional) title of the dialog is displayed in a large font at the top of the 
+    dialog.
+
+    Typically a [`Text`](https://flet.dev/docs/controls/text) control.
+    """
+
     content: Optional[Control] = None
-    actions: List[Control] = field(default_factory=list)
+    """
+    The (optional) content of the dialog is displayed in the center of the dialog in a 
+    lighter font.
+
+    Typically this is a [`Column`](https://flet.dev/docs/controls/column) that contains 
+    the dialog's [`Text`](https://flet.dev/docs/controls/text) message.
+    """
+
+    actions: list[Control] = field(default_factory=list)
+    """
+    The (optional) set of actions that are displayed at the bottom of the dialog.
+
+    Typically this is a list of 
+    [`CupertinoDialogAction`](https://flet.dev/docs/controls/cupertinodialogaction) 
+    controls.
+    """
+
     inset_animation: Animation = field(
         default_factory=lambda: Animation(
             curve=AnimationCurve.DECELERATE, duration=Duration(milliseconds=100)
         )
     )
+    """
+    The animation style to be used when the system keyboard intrudes into the space 
+    that the dialog is placed in.
+
+    Value is of type 
+    [`AnimationStyle`](https://flet.dev/docs/reference/types/animationstyle).
+    """
 
     def before_update(self):
         super().before_update()
         assert (
             (isinstance(self.title, str) or self.title.visible)
             or (self.content and self.content.visible)
             or any(a.visible for a in self.actions)
-        ), "AlertDialog has nothing to display. Provide at minimum one of the following: title, content, actions"
+        ), "AlertDialog has nothing to display. Provide at minimum one of the "
+        "following: title, content, actions"