From 872e91ed1994b2391452c3a4df3852873a6b4d8a Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 10:54:01 -0700 Subject: [PATCH 01/35] docstrings --- .../cupertino_action_sheet_action.py | 27 +++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_action_sheet_action.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_action_sheet_action.py index 152e1735f..869ce05cb 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_action_sheet_action.py +++ b/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() From 5c397ece554dd7c923cba11c9f77c6099e42298a Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 11:04:28 -0700 Subject: [PATCH 02/35] CupertinoActionSheet docstrings and types --- .../src/controls/cupertino_action_sheet.dart | 4 +- .../cupertino/cupertino_action_sheet.py | 38 ++++++++++++++++--- 2 files changed, 34 insertions(+), 8 deletions(-) diff --git a/packages/flet/lib/src/controls/cupertino_action_sheet.dart b/packages/flet/lib/src/controls/cupertino_action_sheet.dart index c170f5012..7b38c5222 100644 --- a/packages/flet/lib/src/controls/cupertino_action_sheet.dart +++ b/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"), ); diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_action_sheet.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_action_sheet.py index b97c4f552..24c555f8e 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_action_sheet.py +++ b/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. + """ From 8c1bcfc5d7ee6e6b3b2e1eb85a75e04e567c6a7f Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 11:06:00 -0700 Subject: [PATCH 03/35] docstrings --- .../cupertino/cupertino_activity_indicator.py | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_activity_indicator.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_activity_indicator.py index 5221b65dc..993080d3e 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_activity_indicator.py +++ b/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. + """ From decd1e09fe892c3f7a4fbb7260ac82ce6c20d5c8 Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 11:09:35 -0700 Subject: [PATCH 04/35] docstrings --- .../cupertino/cupertino_alert_dialog.py | 119 +++++++----------- 1 file changed, 42 insertions(+), 77 deletions(-) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_alert_dialog.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_alert_dialog.py index cb38aea5b..6fc44ca58 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_alert_dialog.py +++ b/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,92 +15,58 @@ 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() @@ -110,4 +74,5 @@ def before_update(self): (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" From 5632960eee168e7e0538acb0bb8ffcd1bec5b374 Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 11:13:04 -0700 Subject: [PATCH 05/35] docstrings --- .../controls/cupertino/cupertino_app_bar.py | 135 +++++++++++++++--- 1 file changed, 114 insertions(+), 21 deletions(-) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_app_bar.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_app_bar.py index 427ae381a..04fa047e5 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_app_bar.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_app_bar.py @@ -14,43 +14,136 @@ class CupertinoAppBar(Control): """ An iOS-styled application bar. - Example: - ``` - import flet as ft - - def main(page: ft.Page): - page.theme_mode = ft.ThemeMode.LIGHT - - page.appbar = ft.CupertinoAppBar( - leading=ft.Icon(ft.icons.PALETTE), - bgcolor=ft.colors.SURFACE_VARIANT, - trailing=ft.Icon(ft.icons.WB_SUNNY_OUTLINED), - middle=ft.Text("AppBar Example"), - ) - page.add(ft.Text("Body!")) - - - ft.app(target=main) - ``` - - ----- - Online docs: https://flet.dev/docs/controls/cupertinoappbar """ leading: Optional[Control] = None + """ + A `Control` to display at the start of this app bar. Typically the leading control + is an [`Icon`](https://flet.dev/docs/controls/icon) or an + [`IconButton`](https://flet.dev/docs/controls/iconbutton). + + If `None` and `automatically_imply_leading = True`, an appropriate button will be + automatically created. + """ + middle: Optional[Control] = None + """ + A `Control` to display in the middle of this app bar. Typically a + [`Text`](https://flet.dev/docs/controls/text) or a segmented control. + """ + title: Optional[Control] = None + """ + TBD + """ + trailing: Optional[Control] = None + """ + A Control to place at the end of the app bar. Normally additional actions taken on + the page such as a search or edit function. + """ + bgcolor: OptionalColorValue = None + """ + The fill [color](https://flet.dev/docs/reference/colors) to use for an AppBar. + Default color is defined by current theme. + """ + automatically_imply_leading: Optional[bool] = None + """ + Controls whether we should try to imply the leading control if None. + + If `True` and `leading` is null, automatically try to deduce what the leading + widget should be. If `False` and `leading` is None, leading space is given to + title. If leading widget is not None, this parameter has no effect. + """ + automatically_imply_middle: Optional[bool] = None + """ + Controls whether we should try to imply the middle control if None. + + If `True` and `middle` is null, automatically fill in a Text control with the + current route's title. If middle control is not None, this parameter has no effect. + """ + automatically_imply_title: Optional[bool] = None + """ + TBD + """ + border: Optional[Border] = None + """ + The border of the app bar. By default, a single pixel bottom border side is + rendered. + + Value is of type + [`Border`](https://flet.dev/docs/reference/types/border). + """ + padding: OptionalPaddingValue = None + """ + Defines the padding for the contents of the app bar. + + Padding is an instance of + [`Padding`](https://flet.dev/docs/reference/types/padding) class. + + If `None`, the app bar will adopt the following defaults: + + - vertically, contents will be sized to the same height as the app bar itself minus + the status bar. + - horizontally, padding will be `16` pixels according to iOS specifications unless + the leading widget is an automatically inserted back button, in which case the + padding will be `0`. + + Vertical padding won't change the height of the app bar. + """ + transition_between_routes: Optional[bool] = None + """ + TBD + """ + previous_page_title: Optional[str] = None + """ + TBD + """ + brightness: Optional[Brightness] = None + """ + The brightness of the specified `bgcolor`. + + Setting this value changes the style of the system status bar. It is typically used + to increase the contrast ratio of the system status bar over `bgcolor`. + + If `None` (the default), its value will be inferred from the relative luminance of + the `bgcolor`. + + Value is of type + [`Brightness`](https://flet.dev/docs/reference/types/brightness). + """ + automatic_background_visibility: Optional[bool] = None + """ + Whether the navigation bar should appear transparent when content is scrolled under + it. + + If `False`, the navigation bar will display its `bgcolor`. + + Defaults to `True`. + """ + enable_background_filter_blur: Optional[bool] = None + """ + Whether to have a blur effect when a non-opaque `bgcolor` is used. + + This will only be respected when `automatic_background_visibility` is `False` or + until content scrolls under the navbar. + + Defaults to `True`. + """ + large: Optional[bool] = None + """ + TBD + """ From 864e3d19121b2da3c9e71f4fd171f8fa06b2bef1 Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 11:15:19 -0700 Subject: [PATCH 06/35] docstrings --- .../cupertino/cupertino_bottom_sheet.py | 23 +++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_bottom_sheet.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_bottom_sheet.py index 066d1097d..0877b8f34 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_bottom_sheet.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_bottom_sheet.py @@ -12,13 +12,32 @@ class CupertinoBottomSheet(DialogControl): """ A Cupertino version of modal bottom sheet. - ----- - Online docs: https://flet.dev/docs/controls/cupertinobottomsheet """ content: Control + """ + The content of the bottom sheet. + """ + modal: bool = False + """ + Whether this bottom sheet can be dismissed/closed by clicking the area outside of + it. + """ + bgcolor: OptionalColorValue = None + """ + The sheet's background [color](https://flet.dev/docs/reference/colors). + """ + height: OptionalNumber = None + """ + The height of the bottom sheet. + """ + padding: OptionalPaddingValue = None + """ + The sheet's padding. The value is an instance of + [`Padding`](https://flet.dev/docs/reference/types/padding) class or a number. + """ From 894a3fb72555d4fbae0b46f9b959ec761cf44cdc Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 11:18:55 -0700 Subject: [PATCH 07/35] docstrings --- .../controls/cupertino/cupertino_button.py | 92 ++++++++++++++++++- 1 file changed, 90 insertions(+), 2 deletions(-) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_button.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_button.py index 8bfdd7257..9ce761a01 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_button.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_button.py @@ -30,31 +30,119 @@ class CupertinoButton(ConstrainedControl): """ An iOS-style button. - ----- - Online docs: https://flet.dev/docs/controls/cupertinobutton """ content: Optional[StrOrControl] = None + """ + A Control representing custom button content. + """ + icon: Optional[IconValueOrControl] = None + """ + Icon shown in the button. + """ + icon_color: OptionalColorValue = None + """ + Icon [color](https://flet.dev/docs/reference/colors). + """ + bgcolor: OptionalColorValue = None + """ + Button's background [color](https://flet.dev/docs/reference/colors). + """ + color: OptionalColorValue = None + """ + Button's text [color](https://flet.dev/docs/reference/colors). + """ + disabled_bgcolor: OptionalColorValue = None + """ + The background [color](https://flet.dev/docs/reference/colors) of the button when + it is disabled. + """ + opacity_on_click: Number = 0.4 + """ + Defines the opacity of the button when it is clicked. When not pressed, + the button has an opacity of `1.0`. + + Defaults to `0.4`. + """ + min_size: Number = None + """ + The minimum size of the button. + + Defaults to `44.0`. + """ + size_style: CupertinoButtonSize = CupertinoButtonSize.LARGE + """ + TBD + """ + padding: OptionalPaddingValue = None + """ + The amount of space to surround the `content` control inside the bounds of the + button. + """ + alignment: OptionalAlignment = None + """ + TBD + """ + border_radius: BorderRadiusValue = 8.0 + """ + TBD + """ + url: Optional[str] = None + """ + The URL to open when the button is clicked. If registered, `on_click` event is + fired after that. + """ + url_target: Optional[UrlTarget] = None + """ + Where to open URL in the web mode. + + Value is of type [`UrlTarget`](https://flet.dev/docs/reference/types/urltarget) and + defaults to `UrlTarget.BLANK`. + """ + autofocus: bool = False + """ + TBD + """ + focus_color: OptionalColorValue = None + """ + TBD + """ + on_click: OptionalControlEventCallable = None + """ + Fires when a user clicks the button. + """ + on_long_press: OptionalControlEventCallable = None + """ + Fires when a user long-presses the button. + """ + on_focus: OptionalControlEventCallable = None + """ + Fires when the button receives focus. + """ + on_blur: OptionalControlEventCallable = None + """ + Fires when the button loses focus. + """ def before_update(self): super().before_update() From 53147fa17e2c74284499246ab333936722300bfc Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 11:19:28 -0700 Subject: [PATCH 08/35] CupertinoCheckbox description --- .../controls/cupertino/cupertino_checkbox.py | 20 ++----------------- 1 file changed, 2 insertions(+), 18 deletions(-) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_checkbox.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_checkbox.py index 2a508e275..a903e59ee 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_checkbox.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_checkbox.py @@ -19,25 +19,9 @@ @control("CupertinoCheckbox") class CupertinoCheckbox(ConstrainedControl): """ - A macOS style checkbox. Checkbox allows to select one or more items from a group, or switch between two mutually exclusive options (checked or unchecked, on or off). + A macOS style checkbox. 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): - c = ft.CupertinoCheckbox( - label="Cupertino Checkbox", - active_color=ft.colors.GREEN, - inactive_color=ft.colors.RED, - check_color=ft.colors.BLUE, - ), - page.add(c) - - ft.app(target=main) - ``` - - ----- Online docs: https://flet.dev/docs/controls/cupertinocheckbox """ From 7df508314371372431e2ec44ef09e104669799dc Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 11:21:44 -0700 Subject: [PATCH 09/35] docstrings --- .../controls/cupertino/cupertino_checkbox.py | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_checkbox.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_checkbox.py index a903e59ee..f7e046a89 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_checkbox.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_checkbox.py @@ -26,18 +26,117 @@ class CupertinoCheckbox(ConstrainedControl): """ label: Optional[str] = None + """ + The clickable label to display on the right of a checkbox. + """ + label_position: LabelPosition = LabelPosition.RIGHT + """ + Defines on which side of the checkbox the `label` should be shown. + + Value is of type [`LabelPosition`](https://flet.dev/docs/reference/types/labelposition) + and defaults to `RIGHT`. + """ + value: Optional[bool] = None + """ + Current value of the checkbox. + """ + tristate: bool = True + """ + If `True` the checkbox's value can be `True`, `False`, or `None`. + + Checkbox displays a dash when its value is null. + """ + autofocus: bool = False + """ + True if the control will be selected as the initial focus. If there is more than + one control on a page with autofocus set, then the first one added to the page will + get focus. + """ + check_color: OptionalColorValue = None + """ + The [color](https://flet.dev/docs/reference/colors) to use for the check icon when + this checkbox is checked. + """ + active_color: OptionalColorValue = None + """ + The [color](https://flet.dev/docs/reference/colors) used to fill checkbox when it + is checked/selected. + + If `fill_color` returns a non-null color in the `SELECTED` state, it will be used + instead of this color. + + Defaults to `Colors.PRIMARY`. + """ + focus_color: OptionalColorValue = None + """ + The [color](https://flet.dev/docs/reference/colors) used for the checkbox's border + shadow when it has the input focus. + """ + fill_color: OptionalControlStateValue[ColorValue] = None + """ + The [color](https://flet.dev/docs/reference/colors) used to fill the checkbox in + all or specific [`ControlState`](https://flet.dev/docs/reference/types/controlstate) + states. + + The following states are supported: `DEFAULT`, `SELECTED`, `HOVERED`, `FOCUSED`, + and `DISABLED`. + + `active_color` is used as fallback color when the checkbox is in the `SELECTED` + state, `CupertinoColors.WHITE` at 50% opacity is used as fallback color when the + checkbox is in the `DISABLED` state, and `CupertinoColors.WHITE` otherwise. + """ + shape: Optional[OutlinedBorder] = None + """ + The shape of the checkbox. + + Value is of type [`OutlinedBorder`](https://flet.dev/docs/reference/types/outlinedborder) + and defaults to `RoundedRectangleBorder(radius=4)`. + """ + mouse_cursor: Optional[MouseCursor] = None + """ + The cursor for a mouse pointer entering or hovering over this control. + + Value is of type [`MouseCursor`](https://flet.dev/docs/reference/types/mousecursor). + """ + semantics_label: Optional[str] = None + """ + The semantic label for the checkbox that will be announced by screen readers. + + This is announced by assistive technologies (e.g TalkBack/VoiceOver) and not shown + on the UI. + """ + border_side: OptionalControlStateValue[BorderSide] = None + """ + Defines the checkbox's border sides in all or specific + [`ControlState`](https://flet.dev/docs/reference/types/controlstate) states. + + The following states are supported: `DEFAULT`, `PRESSED`, `SELECTED`, `HOVERED`, + `FOCUSED`, `DISABLED` and `ERROR`. + """ + on_change: OptionalControlEventCallable = None + """ + Fires when the state of the Checkbox is changed. + """ + on_focus: OptionalControlEventCallable = None + """ + Fires when the control has received focus. + """ + on_blur: OptionalControlEventCallable = None + """ + Fires when the control has lost focus. + """ From b9b30a09b07f7d1ba8ea916ba5a379cdb8632bd0 Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 11:22:43 -0700 Subject: [PATCH 10/35] Update cupertino_colors.py --- .../flet/src/flet/controls/cupertino/cupertino_colors.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_colors.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_colors.py index ee5a1c3e2..c92e6cca6 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_colors.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_colors.py @@ -16,7 +16,7 @@ import random from enum import Enum -from typing import TYPE_CHECKING, Dict, List, Optional, Union +from typing import TYPE_CHECKING, Optional, Union if TYPE_CHECKING: from flet.controls.types import ColorValue @@ -46,15 +46,16 @@ def with_opacity(opacity: Union[int, float], color: "ColorValue") -> str: @staticmethod def random( - exclude: Optional[List["CupertinoColors"]] = None, - weights: Optional[Dict["CupertinoColors", int]] = None, + exclude: Optional[list["CupertinoColors"]] = None, + weights: Optional[dict["CupertinoColors", int]] = None, ) -> Optional["CupertinoColors"]: """ Selects a random color, with optional exclusions and weights. Args: exclude: A list of colors members to exclude from the selection. - weights: A dictionary mapping color members to their respective weights for weighted random selection. + weights: A dictionary mapping color members to their respective weights for + weighted random selection. Returns: A randomly selected color, or None if all members are excluded. From 54032125dd9102d9b84b7109cf6fdd141eae3458 Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 11:25:33 -0700 Subject: [PATCH 11/35] docstrings --- .../cupertino_context_menu_action.py | 21 +++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_context_menu_action.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_context_menu_action.py index 511a3c469..c2a4e0946 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_context_menu_action.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_context_menu_action.py @@ -12,16 +12,33 @@ class CupertinoContextMenuAction(AdaptiveControl): """ An action that can be added to a CupertinoContextMenu. - ----- - Online docs: https://flet.dev/docs/controls/cupertinocontextmenuaction """ content: StrOrControl + """ + String or Control to be shown in this action button. + """ + default: bool = False + """ + Whether this action should receive the style of an emphasized, default action. + """ + destructive: bool = False + """ + Whether this action should receive the style of a destructive action. + """ + trailing_icon: Optional[IconValue] = None + """ + An optional icon to display at the right of the `text` or `content` control. + """ + on_click: OptionalControlEventCallable = None + """ + Fires when this action button is clicked. + """ def before_update(self): super().before_update() From 290447bdbeee330afce9c33701dffaf62a22d0d5 Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 11:27:03 -0700 Subject: [PATCH 12/35] docstrings --- .../cupertino/cupertino_context_menu.py | 22 +++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_context_menu.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_context_menu.py index fd610d675..d9994fa32 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_context_menu.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_context_menu.py @@ -1,5 +1,4 @@ from dataclasses import field -from typing import List from flet.controls.adaptive_control import AdaptiveControl from flet.controls.base_control import control @@ -13,14 +12,29 @@ class CupertinoContextMenu(AdaptiveControl): """ A full-screen modal route that opens up when the content is long-pressed. - ----- - Online docs: https://flet.dev/docs/controls/cupertinocontextmenu """ content: Control - actions: List[Control] = field(default_factory=list) + """ + The child control to be shown. This is a required property. + + When the `CupertinoContextMenu` is long-pressed, the menu will open and this widget + will be moved to the new route and be expanded. This allows the child to resize to + fit in its place in the new route, if it doesn't size itself. + """ + + actions: list[Control] = field(default_factory=list) + """ + A list of action buttons to be shown in the menu. These actions are typically + [`CupertinoContextMenuAction`](/docs/controls/cupertinocontextmenuaction)s. + This list must have at least one action. + """ + enable_haptic_feedback: bool = True + """ + Whether a click on the `actions` should produce haptic feedback. + """ def before_update(self): super().before_update() From 133afefb787e1a9458073861aa6bab5c5457d499 Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 11:33:32 -0700 Subject: [PATCH 13/35] formatting for ruf --- .../flet/controls/cupertino/cupertino_date_picker.py | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_date_picker.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_date_picker.py index 4eab105dc..737baadd6 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_date_picker.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_date_picker.py @@ -34,8 +34,6 @@ class CupertinoDatePicker(ConstrainedControl): """ An iOS-styled date picker. - ----- - Online docs: https://flet.dev/docs/controls/cupertinodatepicker """ @@ -83,12 +81,14 @@ def before_update(self): ]: assert ( 1 <= self.minimum_year <= value.year - ), f"value.year ({value.year}) can't be less than minimum_year ({self.minimum_year})" + ), f"value.year ({value.year}) can't be less than minimum_year " + f"({self.minimum_year})" if self.maximum_year: assert ( value.year <= self.maximum_year - ), f"value.year ({value.year}) can't be greater than maximum_year ({self.maximum_year})" + ), f"value.year ({value.year}) can't be greater than maximum_year " + f"({self.maximum_year})" if self.first_date: assert ( @@ -107,4 +107,5 @@ def before_update(self): assert ( value.minute % self.minute_interval == 0 - ), f"value.minute ({value.minute}) must be divisible by minute_interval ({self.minute_interval})" + ), f"value.minute ({value.minute}) must be divisible by minute_interval " + f"({self.minute_interval})" From afeff2628979c80516e82289097d0f38533d1bb1 Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 11:38:27 -0700 Subject: [PATCH 14/35] docstrings --- .../cupertino/cupertino_context_menu.py | 2 +- .../cupertino/cupertino_date_picker.py | 106 ++++++++++++++++++ 2 files changed, 107 insertions(+), 1 deletion(-) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_context_menu.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_context_menu.py index d9994fa32..61e31d051 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_context_menu.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_context_menu.py @@ -27,7 +27,7 @@ class CupertinoContextMenu(AdaptiveControl): actions: list[Control] = field(default_factory=list) """ A list of action buttons to be shown in the menu. These actions are typically - [`CupertinoContextMenuAction`](/docs/controls/cupertinocontextmenuaction)s. + [`CupertinoContextMenuAction`](https://flet.dev/docs/controls/cupertinocontextmenuaction)s. This list must have at least one action. """ diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_date_picker.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_date_picker.py index 737baadd6..450a7c78a 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_date_picker.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_date_picker.py @@ -38,18 +38,124 @@ class CupertinoDatePicker(ConstrainedControl): """ value: DateTimeValue = field(default_factory=lambda: datetime.now()) + """ + The initial date and/or time of the picker. It must conform to the intervals + set in `first_date`, `last_date`, `min_year`, and `max_year` else an error + will be `ValueError` will be raised. + + Defaults to the present date and time. + """ + first_date: Optional[DateTimeValue] = None + """ + The earliest allowable date that the user can select. + + Defaults to `None` - no limit. + + When not `None`, one can still scroll the picker to dates earlier than + `first_date`, with the exception that the `on_change` will not be called. + Once let go, the picker will scroll back to `first_date`. + + In `CupertinoDatePickerMode.TIME` mode, a time becomes unselectable if the + datetime produced by combining that particular time and the date part of + initialDateTime is earlier than `last_date`. So typically `first_date` needs + to be set to a datetime that is on the same date as initialDateTime. + """ + last_date: Optional[DateTimeValue] = None + """ + The latest allowable date that the user can select. + + When not `None`, one can still scroll the picker to dates later than + `last_date`, with the exception that the `on_change` will not be called. + Once let go, the picker will scroll back to `last_date`. + + In `CupertinoDatePickerMode.TIME` mode, a time becomes unselectable if the + datetime produced by combining that particular time and the date part of + initialDateTime is later than `last_date`. So typically `last_date` needs to + be set to a datetime that is on the same date as initialDateTime. + + Defaults to `None` - no limit. + """ + bgcolor: OptionalColorValue = None + """ + The background [color](/docs/reference/colors) of the date picker. + """ + minute_interval: int = 1 + """ + The granularity of the minutes spinner, if it is shown in the current + `date_picker_mode`. Must be an integer factor of 60. + + Defaults to `1`. + """ + minimum_year: int = 1 + """ + Minimum year to which the picker can be scrolled when in + `CupertinoDatePickerMode.DATE` mode. + + Defaults to `1`. + """ + maximum_year: Optional[int] = None + """ + Maximum year to which the picker can be scrolled when in + `CupertinoDatePickerMode.DATE` mode. + + Defaults to `None` - no limit. + """ + item_extent: Number = 32.0 + """ + The uniform height of all children. + + Defaults to `32`. + """ + use_24h_format: bool = False + """ + If `True`, 24-hour time format is used else 12-hour time format is used. + + Defaults to `False`. + """ + show_day_of_week: bool = False + """ + Whether to show day of week alongside day. + + Defaults to `False`. + """ + date_picker_mode: CupertinoDatePickerMode = CupertinoDatePickerMode.DATE_AND_TIME + """ + The mode of the date picker. + + Value is of type [`CupertinoDatePickerMode`](https://flet.dev/docs/reference/types/cupertinodatepickermode) + and defaults to `CupertinoDatePickerMode.DATE_AND_TIME`. + """ + date_order: Optional[CupertinoDatePickerDateOrder] = None + """ + The order in which the columns inside this picker are displayed. + + Value is of type [`CupertinoDatePickerDateOrder`](https://flet.dev/docs/reference/types/cupertinodatepickerdateorder). + + :::note + The final order in which the columns are displayed is also influenced by + the `date_picker_mode`. For example, when using + `date_picker_mode=CupertinoDatePickerMode.MONTH_YEAR`, + both `CupertinoDatePickerDateOrder.DAY_MONTH_YEAR` and + `CupertinoDatePickerDateOrder.MONTH_DAY_YEAR` will result in the month|year order. + ::: + """ + on_change: OptionalControlEventCallable = None + """ + Fires when the selected date and/or time changes. Will not fire if the new + selected value is not valid, or is not in the range of `first_date` and `last_date`. + """ def before_update(self): super().before_update() From d994e00279f5aaa48dfb8fbebe03828150d176f8 Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 11:47:19 -0700 Subject: [PATCH 15/35] Update cupertino_filled_button.py --- .../controls/cupertino/cupertino_filled_button.py | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_filled_button.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_filled_button.py index 5357ed5c8..5815fa4ee 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_filled_button.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_filled_button.py @@ -9,19 +9,5 @@ class CupertinoFilledButton(CupertinoButton): """ An iOS-style button filled with default background color. - Example: - ``` - import flet as ft - - - def main(page: ft.Page): - page.add( - ft.CupertinoFilledButton(text="OK"), - ) - - ft.app(target=main) - ``` - ----- - Online docs: https://flet.dev/docs/controls/cupertinofilledbutton """ From f10fb649a84873b2fa5c12818b6eecfedbde0e13 Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 11:48:08 -0700 Subject: [PATCH 16/35] Control description --- .../controls/cupertino/cupertino_list_tile.py | 32 ++----------------- 1 file changed, 2 insertions(+), 30 deletions(-) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_list_tile.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_list_tile.py index b502e73e9..b805a43cb 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_list_tile.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_list_tile.py @@ -17,36 +17,8 @@ @control("CupertinoListTile") class CupertinoListTile(ConstrainedControl): """ - An iOS-style list tile. The CupertinoListTile is a Cupertino equivalent of Material ListTile. - - Example: - - ``` - import flet as ft - - - def main(page: ft.Page): - def tile_clicked(e): - print("Tile Clicked!") - - page.add( - ft.CupertinoListTile( - notched=True, - additional_info=ft.Text("Wed Jan 25"), - bgcolor_activated=ft.colors.AMBER_ACCENT, - leading=ft.Icon(name=ft.cupertino_icons.GAME_CONTROLLER), - title=ft.Text("CupertinoListTile not notched"), - subtitle=ft.Text("Subtitle"), - trailing=ft.Icon(name=ft.cupertino_icons.ALARM), - on_click=tile_clicked, - ), - - ) - - ft.app(target=main) - ``` - - ----- + An iOS-style list tile. The CupertinoListTile is a Cupertino equivalent of Material + ListTile. Online docs: https://flet.dev/docs/controls/cupertinolisttile """ From b835afb4bae9762eef53694c38b4ee145d33118f Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 12:06:18 -0700 Subject: [PATCH 17/35] docstrings and types --- .../lib/src/controls/cupertino_list_tile.dart | 10 +- .../controls/cupertino/cupertino_icons.py | 9 +- .../controls/cupertino/cupertino_list_tile.py | 98 +++++++++++++++++-- 3 files changed, 102 insertions(+), 15 deletions(-) diff --git a/packages/flet/lib/src/controls/cupertino_list_tile.dart b/packages/flet/lib/src/controls/cupertino_list_tile.dart index 44b240a8f..dd82e459f 100644 --- a/packages/flet/lib/src/controls/cupertino_list_tile.dart +++ b/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"); diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_icons.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_icons.py index 7f749e25d..e930b6c57 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_icons.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_icons.py @@ -8,7 +8,7 @@ import random from enum import Enum -from typing import Dict, List, Optional +from typing import Optional __all__ = ["CupertinoIcons"] @@ -16,15 +16,16 @@ class CupertinoIcons(str, Enum): @staticmethod def random( - exclude: Optional[List["CupertinoIcons"]] = None, - weights: Optional[Dict["CupertinoIcons", int]] = None, + exclude: Optional[list["CupertinoIcons"]] = None, + weights: Optional[dict["CupertinoIcons", int]] = None, ) -> Optional["CupertinoIcons"]: """ Selects a random icon, with optional exclusions and weights. Args: exclude: A list of icons members to exclude from the selection. - weights: A dictionary mapping icon members to their respective weights for weighted random selection. + weights: A dictionary mapping icon members to their respective weights for + weighted random selection. Returns: A randomly selected icon, or None if all members are excluded. diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_list_tile.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_list_tile.py index b805a43cb..cd49f28a7 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_list_tile.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_list_tile.py @@ -2,12 +2,13 @@ from flet.controls.base_control import control from flet.controls.constrained_control import ConstrainedControl -from flet.controls.control import Control from flet.controls.padding import OptionalPaddingValue from flet.controls.types import ( + IconValueOrControl, OptionalColorValue, OptionalControlEventCallable, OptionalNumber, + StrOrControl, UrlTarget, ) @@ -23,18 +24,103 @@ class CupertinoListTile(ConstrainedControl): Online docs: https://flet.dev/docs/controls/cupertinolisttile """ - title: Control - subtitle: Optional[Control] = None - leading: Optional[Control] = None - trailing: Optional[Control] = None + title: StrOrControl + """ + A `Control` to display as primary content of the list tile. + + Typically a [`Text`](https://flet.dev/docs/controls/text) control. + """ + + subtitle: Optional[StrOrControl] = None + """ + Additional content displayed below the title. + + Typically a [`Text`](https://flet.dev/docs/controls/text) control. + """ + + leading: Optional[IconValueOrControl] = None + """ + A `Control` to display before the `title`. + """ + + trailing: Optional[IconValueOrControl] = None + """ + A `Control` to display after the title. + + Typically an [`Icon`](https://flet.dev/docs/controls/icon) control. + """ + bgcolor: OptionalColorValue = None + """ + The list tile's background [color](https://flet.dev/docs/reference/colors). + """ + bgcolor_activated: OptionalColorValue = None + """ + The list tile's background [color](https://flet.dev/docs/reference/colors) + after the tile was tapped. + """ + padding: OptionalPaddingValue = None + """ + The tile's internal padding. Insets a CupertinoListTile's contents: its + `leading`, `title`, `subtitle`, `additional_info` and `trailing` controls. + + Padding is an instance of + [`Padding`](https://flet.dev/docs/reference/types/padding) class. + """ + url: Optional[str] = None + """ + The URL to open when the list tile is clicked. If registered, `on_click` + event is fired after that. + """ + url_target: Optional[UrlTarget] = None + """ + Where to open URL in the web mode. + + Value is of type [`UrlTarget`](https://flet.dev/docs/reference/types/urltarget) + and defaults to `UrlTarget.BLANK`. + """ + toggle_inputs: bool = False - additional_info: Optional[Control] = None + """ + Whether clicking on a list tile should toggle the state of `Radio`, `Checkbox` + or `Switch` inside the tile. Default is `False`. + """ + + additional_info: Optional[StrOrControl] = None + """ + A `Control` to display on the right of the list tile, before `trailing`. + + Similar to `subtitle`, an `additional_info` is used to display additional + information. Usually a [`Text`](https://flet.dev/docs/controls/text) control. + """ + leading_size: OptionalNumber = None + """ + Used to constrain the width and height of `leading` control. + + Defaults to `30.0`, if `notched=True`, else `28.0`. + """ + leading_to_title: OptionalNumber = None + """ + The horizontal space between `leading` and `title`. + + Defaults to `12.0`, if `notched=True`, else `16.0`. + """ + notched: bool = False + """ + If `True`, list tile will be created in an "Inset Grouped" form, known from + either iOS Notes or Reminders app. + + Defaults to `False`. + """ + on_click: OptionalControlEventCallable = None + """ + Fires when a user clicks or taps the list tile. + """ From bb856e04049f362dd23f450bbfd5861d31c4b5a8 Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 12:07:05 -0700 Subject: [PATCH 18/35] CupertinoDialogAction description --- .../cupertino/cupertino_dialog_action.py | 46 ------------------- 1 file changed, 46 deletions(-) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_dialog_action.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_dialog_action.py index b4abf87aa..0a11e9089 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_dialog_action.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_dialog_action.py @@ -13,52 +13,6 @@ class CupertinoDialogAction(Control): """ A button typically used in a CupertinoAlertDialog. - Example: - ``` - import flet as ft - - - def main(page: ft.Page): - page.horizontal_alignment = ft.CrossAxisAlignment.CENTER - - def dialog_dismissed(e): - page.add(ft.Text("Dialog dismissed")) - - def handle_action_click(e): - page.add(ft.Text(f"Action clicked: {e.control.text}")) - page.close(cupertino_alert_dialog) - - cupertino_alert_dialog = ft.CupertinoAlertDialog( - title=ft.Text("Cupertino Alert Dialog"), - content=ft.Text("Do you want to delete this file?"), - on_dismiss=dialog_dismissed, - actions=[ - ft.CupertinoDialogAction( - content="Yes", - destructive=True, - on_click=handle_action_click, - ), - ft.CupertinoDialogAction( - content="No", - default=True, - on_click=handle_action_click - ), - ], - ) - - page.add( - ft.CupertinoFilledButton( - text="Open CupertinoAlertDialog", - on_click=lambda e: page.open(cupertino_alert_dialog), - ) - ) - - - ft.app(target=main) - ``` - - ----- - Online docs: https://flet.dev/docs/controls/cupertinodialogaction """ From 1ca9408adbf47c5650aeb563069fe5c73f2eb115 Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 12:08:32 -0700 Subject: [PATCH 19/35] Update cupertino_list_tile.py --- .../flet/src/flet/controls/cupertino/cupertino_list_tile.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_list_tile.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_list_tile.py index cd49f28a7..34d30abda 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_list_tile.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_list_tile.py @@ -124,3 +124,9 @@ class CupertinoListTile(ConstrainedControl): """ Fires when a user clicks or taps the list tile. """ + + def before_update(self): + super().before_update() + assert ( + isinstance(self.title, str) or self.title.visible + ), "title must be a string or a visible Control" From 34b6334299b3d0770d9690d8ef267bf316ad59bf Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 12:11:03 -0700 Subject: [PATCH 20/35] docstrings --- .../cupertino/cupertino_dialog_action.py | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_dialog_action.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_dialog_action.py index 0a11e9089..55771e767 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_dialog_action.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_dialog_action.py @@ -17,10 +17,37 @@ class CupertinoDialogAction(Control): """ content: StrOrControl + """ + A Control representing custom button content. + """ + default: bool = False + """ + If set to True, the button will have bold text. More than one action can have + this property set to True in CupertinoAlertDialog. + + Defaults to `False`. + """ + destructive: bool = False + """ + If set to True, the button's text color will be red. Use it for actions that + destroy objects, such as an delete that deletes an email etc. + + Defaults to `False`. + """ + text_style: Optional[TextStyle] = None + """ + The text style to use for text on the button. + + Value is of type [`TextStyle`](https://flet.dev/docs/reference/types/textstyle). + """ + on_click: OptionalControlEventCallable = None + """ + Fires when a user clicks the button. + """ def before_update(self): super().before_update() From ef961bff57d75bf15857c8f997b4bbf52e492e4f Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 12:12:06 -0700 Subject: [PATCH 21/35] Update cupertino_navigation_bar.py --- .../cupertino/cupertino_navigation_bar.py | 37 ++----------------- 1 file changed, 4 insertions(+), 33 deletions(-) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_navigation_bar.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_navigation_bar.py index 3444b8465..c80c32a6b 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_navigation_bar.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_navigation_bar.py @@ -1,5 +1,5 @@ from dataclasses import field -from typing import List, Optional +from typing import Optional from flet.controls.base_control import control from flet.controls.border import Border @@ -21,42 +21,13 @@ class CupertinoNavigationBar(ConstrainedControl): """ An iOS-styled bottom navigation tab bar. - Navigation bars offer a persistent and convenient way to switch between primary destinations in an app. - - Example: - - ``` - import flet as ft - - def main(page: ft.Page): - page.title = "CupertinoNavigationBar Example" - page.navigation_bar = ft.CupertinoNavigationBar( - bgcolor=ft.colors.AMBER_100, - inactive_color=ft.colors.GREY, - active_color=ft.colors.BLACK, - on_change=lambda e: print("Selected tab:", e.control.selected_index), - destinations=[ - ft.NavigationBarDestination(icon=ft.icons.EXPLORE, label="Explore"), - ft.NavigationBarDestination(icon=ft.icons.COMMUTE, label="Commute"), - ft.NavigationBarDestination( - icon=ft.icons.BOOKMARK_BORDER, - selected_icon=ft.icons.BOOKMARK, - label="Explore", - ), - ] - ) - page.add(ft.SafeArea(ft.Text("Body!"))) - - - ft.app(target=main) - ``` - - ----- + Navigation bars offer a persistent and convenient way to switch between primary + destinations in an app. Online docs: https://flet.dev/docs/controls/cupertinonavigationbar """ - destinations: List[NavigationBarDestination] = field(default_factory=list) + destinations: list[NavigationBarDestination] = field(default_factory=list) selected_index: int = 0 bgcolor: OptionalColorValue = None active_color: OptionalColorValue = None From 07016d956521e1cd6bfc0fda77a8a51d5367c661 Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 12:14:50 -0700 Subject: [PATCH 22/35] docstrings --- .../cupertino/cupertino_navigation_bar.py | 44 +++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_navigation_bar.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_navigation_bar.py index c80c32a6b..cce006322 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_navigation_bar.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_navigation_bar.py @@ -28,10 +28,54 @@ class CupertinoNavigationBar(ConstrainedControl): """ destinations: list[NavigationBarDestination] = field(default_factory=list) + """ + Defines the appearance of the button items that are arrayed within the navigation + bar. + + The value must be a list of two or more + [`NavigationBarDestination`](https://flet.dev/docs/controls/navigationbar#navigationbardestination-properties) + instances. + """ + selected_index: int = 0 + """ + The index into `destinations` for the current selected `NavigationBarDestination` + or `None` if no destination is selected. + """ + bgcolor: OptionalColorValue = None + """ + The [color](https://flet.dev/docs/reference/colors) of the navigation bar itself. + """ + active_color: OptionalColorValue = None + """ + The foreground [color](https://flet.dev/docs/reference/colors) of the icon and + title of the selected destination. + """ + inactive_color: ColorValue = CupertinoColors.INACTIVE_GRAY + """ + The foreground [color](https://flet.dev/docs/reference/colors) of the icon and + title of the unselected destinations. + """ + border: Optional[Border] = None + """ + Defines the border of this navigation bar. + + The value is an instance of + [`Border`](https://flet.dev/docs/reference/types/border) class. + """ + icon_size: Number = 30 + """ + The size of all destination icons. + + Defaults to `30`. + """ + on_change: OptionalControlEventCallable = None + """ + Fires when selected destination changed. + """ From 354b204c8cbc0d94b7e8e394dfb4684d0d85d0e5 Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 12:15:27 -0700 Subject: [PATCH 23/35] Update cupertino_picker.py --- .../flet/src/flet/controls/cupertino/cupertino_picker.py | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_picker.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_picker.py index 1de8b328d..f9454f3d3 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_picker.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_picker.py @@ -1,5 +1,5 @@ from dataclasses import field -from typing import List, Optional +from typing import Optional from flet.controls.base_control import control from flet.controls.constrained_control import ConstrainedControl @@ -20,12 +20,10 @@ class CupertinoPicker(ConstrainedControl): """ An iOS-styled picker. - ----- - Online docs: https://flet.dev/docs/controls/cupertinopicker """ - controls: List[Control] = field(default_factory=list) + controls: list[Control] = field(default_factory=list) item_extent: Number = 32.0 selected_index: int = 0 bgcolor: OptionalColorValue = None From 72c7f9ddcc96145abaca173636ba536e89b107e0 Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 12:18:12 -0700 Subject: [PATCH 24/35] docstrings --- .../controls/cupertino/cupertino_picker.py | 70 +++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_picker.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_picker.py index f9454f3d3..27f1ab0c8 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_picker.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_picker.py @@ -24,18 +24,88 @@ class CupertinoPicker(ConstrainedControl): """ controls: list[Control] = field(default_factory=list) + """ + A list of controls representing items in this picker. + """ + item_extent: Number = 32.0 + """ + The uniform height of all children. + + Defaults to `32`. + """ + selected_index: int = 0 + """ + The index (starting from 0) of the selected item in the `controls` list. + """ + bgcolor: OptionalColorValue = None + """ + The background [color](https://flet.dev/docs/reference/colors) of the timer picker. + """ + use_magnifier: bool = False + """ + Whether to use the magnifier for the center item of the wheel. + """ + looping: bool = False + """ + If `True`, children on a wheel can be scrolled in a loop. + + Defaults to `False`. + """ + magnification: Number = 1.0 + """ + The zoomed-in rate of the magnifier, if it is used. + + If the value is greater than `1.0`, the item in the center will be zoomed in by that + rate, and it will also be rendered as flat, not cylindrical like the rest of the + list. The item will be zoomed-out if magnification is less than `1.0`. + + Defaults to `1.0` - normal. + """ + squeeze: Number = 1.45 + """ + The angular compactness of the children on the wheel. + """ + diameter_ratio: Number = 1.07 + """ + Relative ratio between this picker's height and the simulated cylinder's diameter. + + Smaller values create more pronounced curvatures in the scrollable wheel. + """ + off_axis_fraction: Number = 0.0 + """ + How much the wheel is horizontally off-center, as a fraction of its width. + """ + selection_overlay: Optional[Control] = None + """ + A control overlaid on the picker to highlight the selected entry, centered and + matching the height of the center row. + + Defaults to a rounded rectangle in iOS 14 style with + `default_selection_overlay_bgcolor` as background color. + """ + default_selection_overlay_bgcolor: ColorValue = CupertinoColors.TERTIARY_SYSTEM_FILL + """ + The default background [color](https://flet.dev/docs/reference/colors) of the + `selection_overlay`. + + Defaults to `CupertinoColors.TERTIARY_SYSTEM_FILL`. + """ + on_change: OptionalControlEventCallable = None + """ + Fires when the selection changes. + """ def before_update(self): super().before_update() From 48f08dd25ede84089ff18e98b088ef437fdc35fb Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 12:22:33 -0700 Subject: [PATCH 25/35] docstrings --- .../controls/cupertino/cupertino_radio.py | 70 ++++++++++++++++++- 1 file changed, 68 insertions(+), 2 deletions(-) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_radio.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_radio.py index b6f806f86..69e5f2e70 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_radio.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_radio.py @@ -17,21 +17,87 @@ class CupertinoRadio(ConstrainedControl): """ Radio buttons let people select a single option from two or more choices. - ----- - Online docs: https://flet.dev/docs/controls/cupertinoradio """ label: Optional[str] = None + """ + The clickable label to display on the right of a Radio. + """ + value: str = "" + """ + The value to set to containing `RadioGroup` when the radio is selected. + """ + label_position: LabelPosition = LabelPosition.RIGHT + """ + The position of the label relative to the radio. + + Value is of type + [LabelPosition](https://flet.dev/docs/reference/types/labelposition) and + defaults to `LabelPosition.RIGHT`. + """ + fill_color: OptionalColorValue = None + """ + The [color](https://flet.dev/docs/reference/colors) that fills the radio. + """ + active_color: OptionalColorValue = None + """ + The [color](https://flet.dev/docs/reference/colors) used to fill this radio + when it is selected. + """ + inactive_color: OptionalColorValue = None + """ + The [color](https://flet.dev/docs/reference/colors) used to fill this radio + when it is not selected. + + Defaults to `colors.WHITE`. + """ + autofocus: bool = False + """ + True if the control will be selected as the initial focus. + + If there is more than one control on a page with autofocus set, then the first + one added to the page will get focus. + """ + use_checkmark_style: bool = False + """ + Defines whether the radio displays in a checkbox style or the default radio style. + + Defaults to `False`. + """ + toggleable: bool = False + """ + Set to `True` if this radio button is allowed to be returned to an indeterminate + state by selecting it again when selected. + + Defaults to `False`. + """ + focus_color: OptionalColorValue = None + """ + The [color](https://flet.dev/docs/reference/colors) for the radio's border + when it has the input focus. + """ + mouse_cursor: Optional[MouseCursor] = None + """ + TBD + """ + on_focus: OptionalControlEventCallable = None + """ + Fires when the control has received focus. + """ + on_blur: OptionalControlEventCallable = None + """ + Fires when the control has lost focus. + """ From d5aaf614b329b71c8e3d321bafe848d9aa9a4909 Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 12:48:56 -0700 Subject: [PATCH 26/35] docstrings --- .../cupertino/cupertino_segmented_button.py | 53 +++++++++++++++++-- 1 file changed, 49 insertions(+), 4 deletions(-) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_segmented_button.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_segmented_button.py index 9998ed0d1..8e04cccf7 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_segmented_button.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_segmented_button.py @@ -1,5 +1,4 @@ from dataclasses import field -from typing import List from flet.controls.base_control import control from flet.controls.constrained_control import ConstrainedControl @@ -15,21 +14,67 @@ class CupertinoSegmentedButton(ConstrainedControl): """ An iOS-style segmented button. - ----- - Online docs: https://flet.dev/docs/controls/cupertinosegmentedbutton """ - controls: List[Control] = field(default_factory=list) + controls: list[Control] = field(default_factory=list) + """ + A list of `Control`s to display as segments inside the CupertinoSegmentedButton. + """ + selected_index: int = 0 + """ + The index (starting from 0) of the selected segment in the `controls` list. + """ + selected_color: OptionalColorValue = None + """ + The [color](https://flet.dev/docs/reference/colors) of the button when it is + selected. + """ + unselected_color: OptionalColorValue = None + """ + The [color](https://flet.dev/docs/reference/colors) of the button when it is not + selected. + """ + border_color: OptionalColorValue = None + """ + The [color](https://flet.dev/docs/reference/colors) of the button's border. + """ + padding: OptionalPaddingValue = None + """ + The button's padding. + + Padding value is an instance of + [Padding](https://flet.dev/docs/reference/types/padding) class. + """ + click_color: OptionalColorValue = None + """ + The [color](https://flet.dev/docs/reference/colors) used to fill the background + of this control when temporarily interacting with through a long press or drag. + + Defaults to the `selected_color` with 20% opacity. + """ + disabled_color: OptionalColorValue = None + """ + TBD + """ + disabled_text_color: OptionalColorValue = None + """ + TBD + """ + on_change: OptionalControlEventCallable = None + """ + Fires when the state of the button is changed - when one of the `controls` is + clicked. + """ def before_update(self): super().before_update() From 7b93f526602f1752ddf2369702fafd842f6baeea Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 12:50:29 -0700 Subject: [PATCH 27/35] Control description --- .../flet/src/flet/controls/cupertino/cupertino_slider.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_slider.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_slider.py index 8cb9e5069..2f51b09eb 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_slider.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_slider.py @@ -17,11 +17,12 @@ class CupertinoSlider(ConstrainedControl): """ An iOS-type slider. - It provides a visual indication of adjustable content, as well as the current setting in the total range of content. + It provides a visual indication of adjustable content, as well as the current + setting in the total range of content. - Use a slider when you want people to set defined values (such as volume or brightness), or when people would benefit from instant feedback on the effect of setting changes. - - ----- + Use a slider when you want people to set defined values (such as volume or + brightness), or when people would benefit from instant feedback on the effect of + setting changes. Online docs: https://flet.dev/docs/controls/cupertinoslider """ From 91cb9314f9c75fb85b9df6be20e47a25b06f0a27 Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 12:52:07 -0700 Subject: [PATCH 28/35] docstrings --- .../controls/cupertino/cupertino_slider.py | 63 +++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_slider.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_slider.py index 2f51b09eb..b4dda89f1 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_slider.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_slider.py @@ -28,17 +28,80 @@ class CupertinoSlider(ConstrainedControl): """ value: OptionalNumber = None + """ + The currently selected value for this slider. + + The slider's thumb is drawn at a position that corresponds to this value. + """ + min: Number = 0.0 + """ + The minimum value the user can select. + + Defaults to `0.0`. Must be less than or equal to `max`. + + If the `max` is equal to the `min`, then the slider is disabled. + """ + max: Number = 1.0 + """ + The maximum value the user can select. + + Defaults to `1.0`. Must be greater than or equal to `min`. + + If the `max` is equal to the `min`, then the slider is disabled. + """ + divisions: Optional[int] = None + """ + The number of discrete divisions. + + If not set, the slider is continuous. + """ + round: int = 0 + """ + TBD + """ + active_color: OptionalColorValue = None + """ + The [color](https://flet.dev/docs/reference/colors) to use for the portion of the + slider track that is active. + + The "active" side of the slider is the side between the thumb and the minimum + value. + """ + thumb_color: OptionalColorValue = None + """ + The [color](https://flet.dev/docs/reference/colors) of the thumb. + """ + on_change: OptionalControlEventCallable = None + """ + Fires when the state of the Slider is changed. + """ + on_change_start: OptionalControlEventCallable = None + """ + Fires when the user starts selecting a new value for the slider. + """ + on_change_end: OptionalControlEventCallable = None + """ + Fires when the user is done selecting a new value for the slider. + """ + on_focus: OptionalControlEventCallable = None + """ + Fires when the control has received focus. + """ + on_blur: OptionalControlEventCallable = None + """ + Fires when the control has lost focus. + """ def before_update(self): super().before_update() From 1fe3188ea0c73a8cf4c94a98911cd230c96d5269 Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 12:52:28 -0700 Subject: [PATCH 29/35] Update cupertino_sliding_segmented_button.py --- .../controls/cupertino/cupertino_sliding_segmented_button.py | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_sliding_segmented_button.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_sliding_segmented_button.py index 450ee11bc..7f58cb308 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_sliding_segmented_button.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_sliding_segmented_button.py @@ -1,5 +1,4 @@ from dataclasses import field -from typing import List from flet.controls.base_control import control from flet.controls.constrained_control import ConstrainedControl @@ -20,12 +19,10 @@ class CupertinoSlidingSegmentedButton(ConstrainedControl): """ A CupertinoSlidingSegmentedButton. - ----- - Online docs: https://flet.dev/docs/controls/cupertinoslidingsegmentedbutton """ - controls: List[Control] = field(default_factory=list) + controls: list[Control] = field(default_factory=list) selected_index: int = 0 bgcolor: ColorValue = CupertinoColors.TERTIARY_SYSTEM_FILL thumb_color: OptionalColorValue = None From 105e914fc557392dcfa30882d1dfcdcf3e311bcc Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 12:54:23 -0700 Subject: [PATCH 30/35] docstrings --- .../cupertino_sliding_segmented_button.py | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_sliding_segmented_button.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_sliding_segmented_button.py index 7f58cb308..514f662bc 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_sliding_segmented_button.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_sliding_segmented_button.py @@ -23,14 +23,47 @@ class CupertinoSlidingSegmentedButton(ConstrainedControl): """ controls: list[Control] = field(default_factory=list) + """ + A list of `Control`s to display as segments inside the CupertinoSegmentedButton. + Must have at least 2 items. + """ + selected_index: int = 0 + """ + The index (starting from 0) of the selected segment in the `controls` list. + """ + bgcolor: ColorValue = CupertinoColors.TERTIARY_SYSTEM_FILL + """ + The background [color](https://flet.dev/docs/reference/colors) of the button. + """ + thumb_color: OptionalColorValue = None + """ + The [color](https://flet.dev/docs/reference/colors) of the button when it is not + selected. + """ + padding: PaddingValue = field( default_factory=lambda: Padding.symmetric(vertical=2, horizontal=3) ) + """ + The button's padding. + + Padding value is an instance of + [Padding](https://flet.dev/docs/reference/types/padding) class. + """ + proportional_width: bool = False + """ + TBD + """ + on_change: OptionalControlEventCallable = None + """ + Fires when the state of the button is changed - when one of the `controls` is + clicked. + """ def before_update(self): super().before_update() From 0f679d9fcb19b0cfaeb582f5c50ee7339d056261 Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 12:54:39 -0700 Subject: [PATCH 31/35] Update cupertino_switch.py --- .../controls/cupertino/cupertino_switch.py | 20 ------------------- 1 file changed, 20 deletions(-) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_switch.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_switch.py index e18205851..22c3a1b2c 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_switch.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_switch.py @@ -20,26 +20,6 @@ class CupertinoSwitch(ConstrainedControl): """ An iOS-style switch. Used to toggle the on/off state of a single setting. - Example: - ``` - import flet as ft - - def main(page: ft.Page): - page.add( - ft.CupertinoSwitch(label="Cupertino Switch", value=True), - ft.Switch(label="Material Checkbox", value=True), - ft.Container(height=20), - ft.Text( - "Adaptive Switch shows as CupertinoSwitch on macOS and iOS and " - "as Switch on other platforms:" - ), - ft.Switch(adaptive=True, label="Adaptive Switch", value=True), - ) - - ft.app(target=main) - ``` - ----- - Online docs: https://flet.dev/docs/controls/cupertinoswitch """ From b67f41747184c5ae11bdd43b2763d90b4c04d637 Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 12:56:35 -0700 Subject: [PATCH 32/35] docstrings --- .../controls/cupertino/cupertino_switch.py | 106 ++++++++++++++++++ 1 file changed, 106 insertions(+) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_switch.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_switch.py index 22c3a1b2c..5f4f167b0 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_switch.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_switch.py @@ -24,22 +24,128 @@ class CupertinoSwitch(ConstrainedControl): """ label: Optional[str] = None + """ + The clickable label to display on the right of the switch. + """ + value: bool = False + """ + Current value of the switch. + """ + label_position: LabelPosition = LabelPosition.RIGHT + """ + The position of the label relative to the switch. + + Value is of type + [LabelPosition](https://flet.dev/docs/reference/types/labelposition) and defaults + to `LabelPosition.RIGHT`. + """ + thumb_color: OptionalColorValue = None + """ + The [color](https://flet.dev/docs/reference/colors) of the switch's thumb. + """ + focus_color: OptionalColorValue = None + """ + The [color](https://flet.dev/docs/reference/colors) to use for the focus highlight + for keyboard interactions. + """ + autofocus: bool = False + """ + True if the control will be selected as the initial focus. + + If there is more than one control on a page with autofocus set, then the first one + added to the page will get focus. + """ + on_label_color: OptionalColorValue = None + """ + The [color](https://flet.dev/docs/reference/colors) to use for the accessibility + label when the switch is on. + """ + off_label_color: OptionalColorValue = None + """ + The [color](https://flet.dev/docs/reference/colors) to use for the accessibility + label when the switch is off. + """ + active_thumb_image: Optional[str] = None + """ + An image to use on the thumb of this switch when the switch is on. + + Can be a local file path or URL. + """ + inactive_thumb_image: Optional[str] = None + """ + An image to use on the thumb of this switch when the switch is off. + + Can be a local file path or URL. + """ + active_track_color: OptionalColorValue = None + """ + The [color](https://flet.dev/docs/reference/colors) to use on the track when this + switch is on. + """ + inactive_thumb_color: OptionalColorValue = None + """ + The [color](https://flet.dev/docs/reference/colors) to use on the thumb when this + switch is off. + + If `None`, defaults to `thumb_color`, or `CupertinoColors.WHITE` if `thumb_color` + is also `None`. + """ + inactive_track_color: OptionalColorValue = None + """ + The [color](https://flet.dev/docs/reference/colors) to use on the track when this + switch is off. + """ + track_outline_color: OptionalControlStateValue[ColorValue] = None + """ + The outline [color](https://flet.dev/docs/reference/colors) of this switch's track + in various + [ControlState](https://flet.dev/docs/reference/types/controlstate) states. + """ + track_outline_width: OptionalControlStateValue[OptionalNumber] = None + """ + The outline width of this switch's track in all or specific + [ControlState](https://flet.dev/docs/reference/types/controlstate) states. + """ + thumb_icon: OptionalControlStateValue[IconValue] = None + """ + The icon of this Switch's thumb in various + [ControlState](https://flet.dev/docs/reference/types/controlstate) states. + + Supported values: `SELECTED`, `HOVERED`, `DISABLED`, `FOCUSED`, `DEFAULT`. + """ + on_change: OptionalControlEventCallable = None + """ + Fires when the state of the switch is changed. + """ + on_focus: OptionalControlEventCallable = None + """ + Fires when the control has received focus. + """ + on_blur: OptionalControlEventCallable = None + """ + Fires when the control has lost focus. + """ + on_image_error: OptionalControlEventCallable = None + """ + Fires when the image (`active_thumb_image` or `inactive_thumb_image`) fails to + load. + """ From 1c49bb214dee1a8b514ba6e40fa58523e3e7bb5d Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 13:00:29 -0700 Subject: [PATCH 33/35] docstrings --- .../controls/cupertino/cupertino_textfield.py | 84 ++++++++++++++++++- 1 file changed, 82 insertions(+), 2 deletions(-) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_textfield.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_textfield.py index a85002ecc..ef6bd873e 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_textfield.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_textfield.py @@ -24,19 +24,99 @@ class CupertinoTextField(TextField): """ An iOS-style text field. - ----- - Online docs: https://flet.dev/docs/controls/cupertinotextfield """ placeholder_text: Optional[str] = None + """ + A lighter colored placeholder hint that appears on the first line of the text + field when the text entry is empty. + + Defaults to an empty string. + """ + placeholder_style: Optional[TextStyle] = None + """ + The [TextStyle](https://flet.dev/docs/reference/types/textstyle) to use for + `placeholder_text`. + """ + gradient: Optional[Gradient] = None + """ + Configures gradient background. + + Value is of type [Gradient](https://flet.dev/docs/reference/types/gradient). + """ + blend_mode: Optional[BlendMode] = None + """ + The blend mode applied to the `color` or `gradient` background. + + Value is of type [BlendMode](https://flet.dev/docs/reference/types/blendmode) and + defaults to `BlendMode.MODULATE`. + """ + shadow: OptionalShadowValue = None + """ + A list of shadows behind the text field. + """ + prefix_visibility_mode: VisibilityMode = VisibilityMode.ALWAYS + """ + Defines the visibility of the `prefix` control based on the state of text entry. + + Has no effect if `prefix` is not specified. + + Value is of type + [VisibilityMode](https://flet.dev/docs/reference/types/visibilitymode) and + defaults to `VisibilityMode.ALWAYS`. + """ + suffix_visibility_mode: VisibilityMode = VisibilityMode.ALWAYS + """ + Defines the visibility of the `suffix` control based on the state of text entry. + + Has no effect if `suffix` is not specified. + + Value is of type + [VisibilityMode](https://flet.dev/docs/reference/types/visibilitymode) and + defaults to `VisibilityMode.ALWAYS`. + """ + clear_button_visibility_mode: VisibilityMode = VisibilityMode.NEVER + """ + Defines the visibility of the clear button based on the state of text entry. + + Will appear only if no `suffix` is provided. + + Value is of type + [VisibilityMode](https://flet.dev/docs/reference/types/visibilitymode) and + defaults to `VisibilityMode.NEVER`. + """ + clear_button_semantics_label: Optional[str] = None + """ + The semantic label for the clear button used by screen readers. + + This will be used by screen reading software to identify the clear button widget. + + Defaults to `"Clear"`. + """ + image: Optional[DecorationImage] = None + """ + An image to paint above the `bgcolor` or `gradient`. + + Value is of type + [DecorationImage](https://flet.dev/docs/reference/types/decorationimage). + """ + padding: OptionalPaddingValue = None + """ + The padding around the text entry area between the `prefix` and `suffix` or the + clear button when `clear_button_mode` is not `VisibilityMode.NEVER`. + + Value is of type + [Padding](https://flet.dev/docs/reference/types/padding) and defaults to padding + of `7` pixels on all sides. + """ From 5a19fd72ef49787b3e6eb7f2a106723555ec9739 Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 13:04:58 -0700 Subject: [PATCH 34/35] docstrings --- .../cupertino/cupertino_timer_picker.py | 64 ++++++++++++++++--- 1 file changed, 56 insertions(+), 8 deletions(-) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_timer_picker.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_timer_picker.py index c79bac3e9..eaa5fbd9e 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_timer_picker.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_timer_picker.py @@ -4,7 +4,6 @@ from flet.controls.alignment import Alignment from flet.controls.base_control import control from flet.controls.constrained_control import ConstrainedControl -from flet.controls.control_event import ControlEvent from flet.controls.duration import Duration, DurationValue from flet.controls.types import Number, OptionalColorValue, OptionalControlEventCallable @@ -22,21 +21,66 @@ class CupertinoTimerPicker(ConstrainedControl): """ A countdown timer picker in iOS style. - It can show a countdown duration with hour, minute and second spinners. The duration is bound between 0 and 23 hours 59 minutes 59 seconds. - - ----- + It can show a countdown duration with hour, minute and second spinners. The + duration is bound between 0 and 23 hours 59 minutes 59 seconds. Online docs: https://flet.dev/docs/controls/cupertinotimerpicker """ value: DurationValue = field(default_factory=lambda: Duration()) + """ + The initial duration in seconds of the countdown timer. + + Defaults to `0`. + """ + alignment: Alignment = field(default_factory=lambda: Alignment.center()) + """ + Defines how the timer picker should be positioned within its parent. + + Value is of type [Alignment](https://flet.dev/docs/reference/types/alignment) and + defaults to `alignment.center`. + """ + second_interval: int = 1 + """ + The granularity of the second spinner. + + Must be a positive integer factor of 60. Defaults to `1`. + """ + minute_interval: int = 1 + """ + The granularity of the minute spinner. + + Must be a positive integer factor of 60. Defaults to `1`. + """ + mode: CupertinoTimerPickerMode = CupertinoTimerPickerMode.HOUR_MINUTE_SECONDS + """ + The mode of the timer picker. + + Value is of type + [CupertinoTimerPickerMode](https://flet.dev/docs/reference/types/cupertinotimerpickermode) + and defaults to `CupertinoTimerPickerMode.HOUR_MINUTE_SECOND`. + """ + bgcolor: OptionalColorValue = None + """ + The background [color](https://flet.dev/docs/reference/colors) of the timer picker. + """ + item_extent: Number = 32.0 + """ + The uniform height of all children. + + Defaults to `32`. + """ + on_change: OptionalControlEventCallable = None + """ + Fires when the timer duration changes. + """ def before_update(self): super().before_update() @@ -49,14 +93,18 @@ def before_update(self): assert value < Duration(hours=24), "value must be strictly less than 24 hours" assert ( self.minute_interval > 0 and 60 % self.minute_interval == 0 - ), f"minute_interval ({self.minute_interval}) must be a positive integer factor of 60" + ), f"minute_interval ({self.minute_interval}) must be a positive integer " + "factor of 60" assert ( self.second_interval > 0 and 60 % self.second_interval == 0 - ), f"second_interval ({self.second_interval}) must be a positive integer factor of 60" + ), f"second_interval ({self.second_interval}) must be a positive integer " + "factor of 60" assert ( value.in_minutes % self.minute_interval == 0 - ), f"value ({value.in_minutes} minutes) must be a multiple of minute_interval ({self.minute_interval})" + ), f"value ({value.in_minutes} minutes) must be a multiple of minute_interval " + f"({self.minute_interval})" assert ( value.in_seconds % self.second_interval == 0 - ), f"value ({value.in_seconds} seconds) must be a multiple of second_interval ({self.second_interval})" + ), f"value ({value.in_seconds} seconds) must be a multiple of second_interval " + f"({self.second_interval})" assert self.item_extent > 0, "item_extent must be strictly greater than 0" From 3d411d63f6ddd79d8e0d9cad3b4a90144dbb18a1 Mon Sep 17 00:00:00 2001 From: InesaFitsner Date: Thu, 8 May 2025 13:05:36 -0700 Subject: [PATCH 35/35] Update cupertino_tinted_button.py --- .../controls/cupertino/cupertino_tinted_button.py | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_tinted_button.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_tinted_button.py index ff1ae3592..e99d1d8ea 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_tinted_button.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_tinted_button.py @@ -9,19 +9,5 @@ class CupertinoTintedButton(CupertinoButton): """ An iOS-style button filled with default background color. - Example: - ``` - import flet as ft - - - def main(page: ft.Page): - page.add( - ft.CupertinoTintedButton(text="OK"), - ) - - ft.app(target=main) - ``` - ----- - Online docs: https://flet.dev/docs/controls/cupertinofilledbutton """