flet 0.70.0.dev5623__py3-none-any.whl → 0.70.0.dev5774__py3-none-any.whl

flet/controls/material/form_field_control.py

@@ -33,7 +33,7 @@ class FormFieldControl(LayoutControl):
 
     text_style: TextStyle = field(default_factory=lambda: TextStyle())
     """
-    The [`TextStyle`][flet.TextStyle] to use for the
+    The [`TextStyle`][flet.] to use for the
     text being edited.
     """
 
@@ -42,7 +42,7 @@ class FormFieldControl(LayoutControl):
     Defines how the text should be aligned vertically.
 
     Value can either be a number ranging from `-1.0` (topmost location) to `1.0`
-    (bottommost location) or of type [`VerticalAlignment`][flet.VerticalAlignment]
+    (bottommost location) or of type [`VerticalAlignment`][flet.]
     Defaults to `VerticalAlignment.CENTER`.
     """
 
@@ -59,8 +59,7 @@ class FormFieldControl(LayoutControl):
 
     label_style: Optional[TextStyle] = None
     """
-    The [`TextStyle`][flet.TextStyle] to use for
-    `label`.
+    The text style to use for `label`.
     """
 
     icon: Optional[IconDataOrControl] = None
@@ -80,8 +79,10 @@ class FormFieldControl(LayoutControl):
 
     bgcolor: Optional[ColorValue] = None
     """
-    TextField background color. Will not be
-    visible if `filled=False`.
+    TextField background color.
+
+    Note:
+        Will not be visible if [`filled`][flet.FormFieldControl.] is `False`.
     """
 
     border_radius: Optional[BorderRadiusValue] = None
@@ -90,27 +91,33 @@ class FormFieldControl(LayoutControl):
 
     border_width: Optional[Number] = None
     """
-    The width of the border in virtual pixels. Set to `0` to completely remove the
-    border.
+    The width of the border in virtual pixels.
 
     Defaults to `1`.
+
+    Tip:
+        Set to `0` to completely remove the border.
     """
 
     border_color: Optional[ColorValue] = None
     """
-    Border color. Could be `transparent` to
-    hide the border.
+    The border color.
+
+    Tip:
+        Set to [`Colors.TRANSPARENT`][flet.] to invisible/hide the border.
     """
 
     focused_color: Optional[ColorValue] = None
     """
-    Text color when TextField is focused.
+    The text's color when focused.
     """
 
     focused_bgcolor: Optional[ColorValue] = None
     """
-    Background color of TextField in focused
-    state. Will not be visible if `filled=False`.
+    Background color in focused state.
+
+    Note:
+        Will not be visible if [`filled`][flet.FormFieldControl.] is `False`.
     """
 
     focused_border_width: Optional[Number] = None
@@ -130,22 +137,26 @@ class FormFieldControl(LayoutControl):
 
     dense: Optional[bool] = None
     """
-    Whether the TextField is part of a dense form (ie, uses less vertical space).
+    Whether this control is part of a dense form (ie, uses less vertical space).
     """
 
     filled: Optional[bool] = None
     """
-    If `True` the decoration's container is filled with theme `fill_color`.
+    If `True` the decoration's container is filled with theme
+    [`fill_color`][flet.FormFieldControl.].
 
-    If `filled=None`(default), then it is implicitly set to `True` when at least one of
-    the following is not `None`: `fill_color`, `focused_bgcolor`, `hover_color` and
-    `bgcolor`.
+    If `filled=None` (the default), then it is implicitly set to `True` when at least
+    one of the following is not `None`: [`fill_color`][flet.FormFieldControl.],
+    [`focused_bgcolor`][flet.FormFieldControl.],
+    [`hover_color`][flet.FormFieldControl.] and [`bgcolor`][flet.FormFieldControl.].
     """
 
     fill_color: Optional[ColorValue] = None
     """
-    Background color of TextField. Will not
-    be visible if `filled=False`.
+    Background color of TextField.
+
+    Note:
+        Will not be visible if [`filled`][flet.FormFieldControl.] is `False`.
     """
 
     focus_color: Optional[ColorValue] = None
@@ -160,22 +171,23 @@ class FormFieldControl(LayoutControl):
 
     hover_color: Optional[ColorValue] = None
     """
-    Background color of TextField when
-    hovered. Will not be visible if `filled=False`.
+    Background color of TextField when hovered.
+
+    Note:
+        Will not be visible if [`filled`][flet.FormFieldControl.] is `False`.
     """
 
     hint_text: Optional[str] = None
     """
     Text that suggests what sort of input the field accepts.
 
-    Displayed on top of the input when the it's empty and either (a) `label` is null or
-    (b) the input has the focus.
+    Displayed on top of the input when the it's empty and either
+    (a) [`label`][flet.FormFieldControl.] is `None` or (b) the input has the focus.
     """
 
     hint_style: Optional[TextStyle] = None
     """
-    The [`TextStyle`][flet.TextStyle] to use for
-    `hint_text`.
+    The text style to use for [`hint_text`][flet.FormFieldControl.].
     """
 
     hint_fade_duration: Optional[DurationValue] = None
@@ -194,14 +206,14 @@ class FormFieldControl(LayoutControl):
     used.
 
     If non-null, the text is displayed below the input decorator, in the same location
-    as `error_text`. If a non-null `error_text` value is specified then the helper text
-    is not shown.
+    as [`error`][flet.FormFieldControl.]. If a non-null
+    [`error`][flet.FormFieldControl.] value is specified then the helper text is not
+    shown.
     """
 
     helper_style: Optional[TextStyle] = None
     """
-    The [`TextStyle`][flet.TextStyle] to use for
-    `helper_text`.
+    The text style to use for [`helper`][flet.FormFieldControl.].
     """
 
     helper_max_lines: Optional[int] = None
@@ -213,27 +225,25 @@ class FormFieldControl(LayoutControl):
     """
     A `Control` to place below the line as a character count.
 
-    If `None` or an empty string and `counter_text` isn't specified, then nothing will
-    appear in the counter's location.
+    If `None` or an empty string then nothing will appear in the counter's location.
     """
 
     counter_style: Optional[TextStyle] = None
     """
-    The [`TextStyle`][flet.TextStyle] to use for
-    `counter_text`.
+    The text style to use for `counter`.
     """
 
     error: Optional[StrOrControl] = None
     """
     Text that appears below the input border.
 
-    If non-null, the border's color animates to red and the `helper_text` is not shown.
+    If non-null, the border's color animates to red
+    and the [`helper`][flet.FormFieldControl.] is not shown.
     """
 
     error_style: Optional[TextStyle] = None
     """
-    The [`TextStyle`][flet.TextStyle] to use for
-    `error_text`.
+    The text style to use for [`error`][flet.FormFieldControl.].
     """
 
     error_max_lines: Optional[int] = None
@@ -243,21 +253,22 @@ class FormFieldControl(LayoutControl):
 
     prefix: Optional[StrOrControl] = None
     """
-    Optional `Control` to place on the line before the input.
+    A `Control` to place on the line before the input.
+
+    It appears after the [`prefix_icon`][flet.FormFieldControl.], if both are specified.
 
     This can be used, for example, to add some padding to text that would otherwise be
-    specified using `prefix_text`, or to add a custom control in front of the input.
+    specified using `prefix`, or to add a custom control in front of the input.
     The control's baseline is lined up with the input baseline.
-
-    Only one of `prefix` and `prefix_text` can be specified.
-
-    The `prefix` appears after the `prefix_icon`, if both are specified.
     """
 
     prefix_icon: Optional[IconDataOrControl] = None
     """
-    An icon that appears before the `prefix` or `prefix_text` and before the editable
-    part of the text field, within the decoration's container.
+    An icon that appears before the editable part of the text field,
+    within the decoration's container.
+
+    If [`prefix`][flet.FormFieldControl.] is specified and visible,
+    this icon will appear to its left.
     """
 
     prefix_icon_size_constraints: Optional[BoxConstraints] = None
@@ -267,27 +278,25 @@ class FormFieldControl(LayoutControl):
 
     prefix_style: Optional[TextStyle] = None
     """
-    The [`TextStyle`][flet.TextStyle] to use for
-    `prefix_text`.
+    The text style to use for [`prefix`][flet.FormFieldControl.].
     """
 
     suffix: Optional[StrOrControl] = None
     """
-    Optional `Control` to place on the line after the input.
+    A `Control` to place on the line after the input.
+
+    It appears before the [`suffix_icon`][flet.FormFieldControl.],
+    if both are specified.
 
     This can be used, for example, to add some padding to the text that would otherwise
-    be specified using `suffix_text`, or to add a custom control after the input.
+    be specified using `suffix`, or to add a custom control after the input.
     The control's baseline is lined up with the input baseline.
-
-    Only one of `suffix` and `suffix_text` can be specified.
-
-    The `suffix` appears before the `suffix_icon`, if both are specified.
     """
 
     suffix_icon: Optional[IconDataOrControl] = None
     """
     An icon that appears after the editable part of the text field and after the
-    `suffix` or `suffix_text`, within the decoration's container.
+    [`suffix`][flet.FormFieldControl.], within the decoration's container.
     """
 
     suffix_icon_size_constraints: Optional[BoxConstraints] = None
@@ -312,8 +321,7 @@ class FormFieldControl(LayoutControl):
 
     suffix_style: Optional[TextStyle] = None
     """
-    The [`TextStyle`][flet.TextStyle] to use for
-    `suffix_text`.
+    The text style to use for [`suffix`][flet.FormFieldControl.].
     """
 
     async def focus(self):

flet/controls/material/icon_button.py

@@ -38,28 +38,28 @@ class IconButton(LayoutControl, AdaptiveControl):
 
     icon: Optional[IconDataOrControl] = None
     """
-    Icon shown in the button.
+    An icon to be shown in this button.
     """
 
     icon_color: Optional[ColorValue] = None
     """
-    The foreground color of the icon.
+    The foreground color of the [`icon`][flet.IconButton.].
     """
 
     icon_size: Optional[Number] = None
     """
-    The [`icon`][flet.IconButton.icon]'s size in virtual pixels.
+    The [`icon`][flet.IconButton.]'s size in virtual pixels.
 
     Defaults to `24`.
     """
 
     selected: Optional[bool] = None
     """
-    The optional selection state of the icon button.
+    The optional selection state of this button.
 
     If this property is not set, the button will behave as a normal push button,
-    otherwise, the button will toggle between showing [`icon`][flet.IconButton.icon]
-    (when `False`), and [`selected_icon`][flet.IconButton.selected_icon] (when `True`).
+    otherwise, the button will toggle between showing [`icon`][flet.IconButton.]
+    (when `False`), and [`selected_icon`][flet.IconButton.] (when `True`).
     """
 
     selected_icon: Optional[IconDataOrControl] = None
@@ -70,47 +70,17 @@ class IconButton(LayoutControl, AdaptiveControl):
     selected_icon_color: Optional[ColorValue] = None
     """
     The icon color for the 'selected' state of this button.
-
-    An example of icon toggle button:
-
-    <img src="/img/blog/gradients/toggle-icon-button.gif" className="screenshot-10" />
-
-    ```python
-    import flet as ft
-
-    def main(page: ft.Page):
-
-        def toggle_icon_button(e):
-            e.control.selected = not e.control.selected
-
-        page.add(
-            ft.IconButton(
-                icon=ft.Icons.BATTERY_1_BAR,
-                selected_icon=ft.Icons.BATTERY_FULL,
-                on_click=toggle_icon_button,
-                selected=False,
-                style=ft.ButtonStyle(
-                    color={
-                        ft.ControlState.SELECTED: ft.Colors.GREEN,
-                        ft.ControlState.DEFAULT: ft.Colors.RED
-                    },
-                ),
-            )
-        )
-
-    ft.run(main)
-    ```
     """
 
     bgcolor: Optional[ColorValue] = field(default=None, metadata={"skip": True})
     """
-    The button's background color.
+    The background color of this button.
     """
 
     highlight_color: Optional[ColorValue] = None
     """
-    The button's color when the button is
-    pressed. The highlight fades in quickly as the button is held down.
+    The color of this button when it is pressed.
+    The highlight fades in quickly as this button is pressed/held down.
     """
 
     style: Optional[ButtonStyle] = None
@@ -118,18 +88,15 @@ class IconButton(LayoutControl, AdaptiveControl):
     Customizes this button's appearance.
 
     Note:
-        - Only honoured in Material 3 design
-            ([`Theme.use_material3`][flet.Theme.use_material3] is `True` - default).
-        - If [`Theme.use_material3`][flet.Theme.use_material3] is `True`,
+        - Only honoured in Material 3 design ([`Theme.use_material3`][flet.] is `True`).
+        - If [`Theme.use_material3`][flet.] is `True`,
             any parameters defined in style will be overridden by the
-            corresponding parameters in this `IconButton`.
-            For example, if icon button
-            [`visual_density`][flet.IconButton.visual_density]
-            is set to [`VisualDensity.STANDARD`][flet.VisualDensity.STANDARD] and
-            style's [`visual_density`][flet.ButtonStyle.visual_density] is
-            set to [`VisualDensity.COMPACT`][flet.VisualDensity.COMPACT], the icon
-            button will have [`VisualDensity.STANDARD`][flet.VisualDensity.STANDARD]
-            to define the button's layout.
+            corresponding parameters in this button.
+            For example, if icon button [`visual_density`][flet.IconButton.]
+            is set to [`VisualDensity.STANDARD`][flet.] and
+            style's [`visual_density`][flet.ButtonStyle.] is
+            set to [`VisualDensity.COMPACT`][flet.], [`VisualDensity.STANDARD`][flet.]
+            will be used.
     """
 
     autofocus: bool = False
@@ -141,8 +108,7 @@ class IconButton(LayoutControl, AdaptiveControl):
 
     disabled_color: Optional[ColorValue] = None
     """
-    The color to use for the icon inside the
-    button when disabled.
+    The color to use for the icon inside the button when disabled.
     """
 
     hover_color: Optional[ColorValue] = None
@@ -157,8 +123,7 @@ class IconButton(LayoutControl, AdaptiveControl):
 
     splash_color: Optional[ColorValue] = None
     """
-    The primary color of the button when the
-    button is in the down (pressed) state.
+    The primary color of this button when it is in the pressed state.
     """
 
     splash_radius: Optional[Number] = None
@@ -167,15 +132,14 @@ class IconButton(LayoutControl, AdaptiveControl):
 
     Note:
         This value is honoured only when in Material 2
-        ([`Theme.use_material3`][flet.Theme.use_material3] is `False`).
+        ([`Theme.use_material3`][flet.] is `False`).
     """
 
     alignment: Optional[Alignment] = None
     """
-    Defines how the icon is positioned within the IconButton. Alignment is an instance
-    of [`Alignment`][flet.Alignment] class.
+    Defines how the icon is positioned within this button.
 
-    Defaults to [`Alignment.CENTER`][flet.Alignment.CENTER].
+    Defaults to [`Alignment.CENTER`][flet.].
     """
 
     padding: Optional[PaddingValue] = None
@@ -197,7 +161,7 @@ class IconButton(LayoutControl, AdaptiveControl):
     """
     The URL to open when this button is clicked.
 
-    Additionally, if [`on_click`][flet.IconButton.on_click] event callback is provided,
+    Additionally, if [`on_click`][flet.IconButton.] event callback is provided,
     it is fired after that.
     """
 
@@ -211,7 +175,7 @@ class IconButton(LayoutControl, AdaptiveControl):
         default=None, metadata={"skip": True}
     )
     """
-    Defines how compact the control's layout will be.
+    Defines how compact this button's layout will be.
     """
 
     size_constraints: Optional[BoxConstraints] = None
@@ -226,12 +190,12 @@ class IconButton(LayoutControl, AdaptiveControl):
 
     on_focus: Optional[ControlEventHandler["IconButton"]] = None
     """
-    Called when the control has received focus.
+    Called when this button has received focus.
     """
 
     on_blur: Optional[ControlEventHandler["IconButton"]] = None
     """
-    Called when the control has lost focus.
+    Called when this button has lost focus.
     """
 
     def before_update(self):
@@ -261,7 +225,7 @@ class IconButton(LayoutControl, AdaptiveControl):
 @control("FilledIconButton")
 class FilledIconButton(IconButton):
     """
-    A filled variant of [`IconButton`][flet.IconButton].
+    A filled variant of [`IconButton`][flet.].
 
     Filled icon buttons have higher visual impact and should be used for high emphasis
     actions, such as turning off a microphone or camera.
@@ -271,7 +235,7 @@ class FilledIconButton(IconButton):
 @control("FilledTonalIconButton")
 class FilledTonalIconButton(IconButton):
     """
-    A filled tonal variant of [`IconButton`][flet.IconButton].
+    A filled tonal variant of [`IconButton`][flet.].
 
     Filled tonal icon buttons are a middle ground between filled and
     outlined icon buttons. They're useful in contexts where the button requires
@@ -283,7 +247,7 @@ class FilledTonalIconButton(IconButton):
 @control("OutlinedIconButton")
 class OutlinedIconButton(IconButton):
     """
-    An outlined variant of [`IconButton`][flet.IconButton].
+    An outlined variant of [`IconButton`][flet.].
 
     Outlined icon buttons are medium-emphasis buttons.
     They're useful when an icon button needs more emphasis than a

flet/controls/material/list_tile.py

@@ -53,21 +53,21 @@ class ListTile(LayoutControl, AdaptiveControl):
     """
     A control to display as primary content of the list tile.
 
-    Typically a [`Text`][flet.Text] control. This should not
-    wrap. To enforce the single line limit, use [`Text.max_lines`][flet.Text.max_lines].
+    Typically a [`Text`][flet.] control. This should not
+    wrap. To enforce the single line limit, use [`Text.max_lines`][flet.].
     """
 
     subtitle: Optional[StrOrControl] = None
     """
     Additional content displayed below the title.
 
-    If [`is_three_line`][flet.ListTile.is_three_line] is `False`, this should not wrap.
+    If [`is_three_line`][(c).] is `False`, this should not wrap.
     If `is_three_line` is `True`, this should be configured to take a maximum of two
     lines.
-    For example, you can use [`Text.max_lines`][flet.Text.max_lines] to enforce the
+    For example, you can use [`Text.max_lines`][flet.] to enforce the
     number of lines.
 
-    Typically a [`Text`][flet.Text] control.
+    Typically a [`Text`][flet.] control.
     """
 
     is_three_line: Optional[bool] = None
@@ -81,19 +81,19 @@ class ListTile(LayoutControl, AdaptiveControl):
     treated as having two lines if the subtitle is non-null.
 
     When using a Text control for title and subtitle, you can enforce line limits
-    using [`Text.max_lines`][flet.Text.max_lines].
+    using [`Text.max_lines`][flet.].
     """
 
     leading: Optional[IconDataOrControl] = None
     """
-    A control to display before the [`title`][flet.ListTile.title].
+    A control to display before the [`title`][(c).].
     """
 
     trailing: Optional[IconDataOrControl] = None
     """
-    A control to display after the [`title`][flet.ListTile.title].
+    A control to display after the [`title`][(c).].
 
-    Typically an [`Icon`][flet.Icon] control.
+    Typically an [`Icon`][flet.] control.
     """
 
     content_padding: Optional[PaddingValue] = None
@@ -115,7 +115,9 @@ class ListTile(LayoutControl, AdaptiveControl):
 
     hover_color: Optional[ColorValue] = None
     """
-    The tile's color when hovered. Only shows if `toggle_inputs` is True.
+    The tile's color when hovered. Only takes effect if
+    [`toggle_inputs`][(c).] is True or if
+    [`on_click`][(c).] is provided.
     """
 
     selected: bool = False
@@ -140,8 +142,8 @@ class ListTile(LayoutControl, AdaptiveControl):
 
     toggle_inputs: bool = False
     """
-    Whether clicking on a list tile should toggle the state of [`Radio`][flet.Radio],
-    [`Checkbox`][flet.Checkbox] or [`Switch`][flet.Switch] inside this tile.
+    Whether clicking on a list tile should toggle the state of [`Radio`][flet.],
+    [`Checkbox`][flet.] or [`Switch`][flet.] inside this tile.
     """
 
     selected_color: Optional[ColorValue] = None
@@ -173,7 +175,7 @@ class ListTile(LayoutControl, AdaptiveControl):
     horizontal_spacing: Optional[Number] = None
     """
     The horizontal gap between the `title` and the
-    [`leading`][flet.ListTile.leading] and [`trailing`][flet.ListTile.trailing]
+    [`leading`][(c).] and [`trailing`][(c).]
     controls.
     """
 
@@ -191,7 +193,7 @@ class ListTile(LayoutControl, AdaptiveControl):
     """
     The URL to open when this button is clicked.
 
-    Additionally, if [`on_click`][flet.ListTile.on_click] event callback is provided,
+    Additionally, if [`on_click`][(c).] event callback is provided,
     it is fired after that.
     """
 
@@ -207,15 +209,15 @@ class ListTile(LayoutControl, AdaptiveControl):
     icon_color: Optional[ColorValue] = None
     """
     Defines the default color for the icons
-    present in [`leading`][flet.ListTile.leading] and
-    [`trailing`][flet.ListTile.trailing].
+    present in [`leading`][(c).] and
+    [`trailing`][(c).].
     """
 
     text_color: Optional[ColorValue] = None
     """
     The color used for
-    texts in [`title`][flet.ListTile.title], [`subtitle`][flet.ListTile.subtitle],
-    [`leading`][flet.ListTile.leading], and [`trailing`][flet.ListTile.trailing].
+    texts in [`title`][(c).], [`subtitle`][(c).],
+    [`leading`][(c).], and [`trailing`][(c).].
     """
 
     shape: Optional[OutlinedBorder] = None
@@ -231,25 +233,25 @@ class ListTile(LayoutControl, AdaptiveControl):
     mouse_cursor: Optional[MouseCursor] = None
     """
     The cursor to be displayed when a mouse pointer enters or is hovering over this
-    control. The value is [`MouseCursor`][flet.MouseCursor]
+    control. The value is [`MouseCursor`][flet.]
     enum.
     """
 
     title_text_style: Optional[TextStyle] = None
     """
-    The [`TextStyle`][flet.TextStyle] for the [`title`][flet.ListTile.title]
+    The [`TextStyle`][flet.] for the [`title`][(c).]
     control.
     """
 
     subtitle_text_style: Optional[TextStyle] = None
     """
-    The [`TextStyle`][flet.TextStyle] for the
+    The [`TextStyle`][flet.] for the
     `subtitle` control.
     """
 
     leading_and_trailing_text_style: Optional[TextStyle] = None
     """
-    The [`TextStyle`][flet.TextStyle] for the
+    The [`TextStyle`][flet.] for the
     `leading` and `trailing` controls.
     """
 
@@ -259,7 +261,7 @@ class ListTile(LayoutControl, AdaptiveControl):
 
     If `None` or not set, default tile heights are `56.0`, `72.0`, and `88.0` for one,
     two, and three lines of text respectively.
-    If [`dense`][flet.ListTile.dense] is `True`, these
+    If [`dense`][(c).] is `True`, these
     defaults are changed to `48.0`, `64.0`, and `76.0`.
 
     Note that, a visual density value or a large title will also adjust the default

flet/controls/material/menu_item_button.py

@@ -39,14 +39,14 @@ class MenuItemButton(LayoutControl):
     """
     An optional control to display before the `content`.
 
-    Typically an [`Icon`][flet.Icon] control.
+    Typically an [`Icon`][flet.] control.
     """
 
     trailing: Optional[Control] = None
     """
     An optional control to display after the `content`.
 
-    Typically an [`Icon`][flet.Icon] control.
+    Typically an [`Icon`][flet.] control.
     """
 
     clip_behavior: ClipBehavior = ClipBehavior.NONE

flet/controls/material/navigation_bar.py

@@ -130,7 +130,7 @@ class NavigationBar(LayoutControl, AdaptiveControl):
     label_padding: Optional[PaddingValue] = None
     """
     The padding around the
-    [`NavigationBarDestination.label`][flet.NavigationBarDestination.label].
+    [`NavigationBarDestination.label`][flet.].
     """
 
     elevation: Optional[Number] = None
@@ -168,9 +168,9 @@ class NavigationBar(LayoutControl, AdaptiveControl):
     overlay_color: Optional[ControlStateValue[ColorValue]] = None
     """
     The highlight color of the `NavigationBarDestination` in various
-    [`ControlState`][flet.ControlState] states.
+    [`ControlState`][flet.] states.
 
-    The following [`ControlState`][flet.ControlState]
+    The following [`ControlState`][flet.]
     values are supported: `PRESSED`, `HOVERED` and `FOCUSED`.
     """