flet 0.70.0.dev6370__tar.gz → 0.70.0.dev6425__tar.gz

{flet-0.70.0.dev6370 → flet-0.70.0.dev6425}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flet
-Version: 0.70.0.dev6370
+Version: 0.70.0.dev6425
 Summary: Flet for Python - easily build interactive multi-platform apps in Python
 Author-email: "Appveyor Systems Inc." <hello@flet.dev>
 License-Expression: Apache-2.0

{flet-0.70.0.dev6370 → flet-0.70.0.dev6425}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flet"
-version = "0.70.0.dev6370"
+version = "0.70.0.dev6425"
 description = "Flet for Python - easily build interactive multi-platform apps in Python"
 authors = [{name = "Appveyor Systems Inc.", email = "hello@flet.dev"}]
 license = "Apache-2.0"

flet-0.70.0.dev6425/src/flet/components/hooks/use_state.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, TypeVar
+
+from flet.components.hooks.hook import Hook
+from flet.components.observable import Observable, ObservableSubscription
+from flet.components.utils import current_component
+
+StateT = TypeVar("StateT")
+Updater = Callable[[StateT], StateT]
+
+
+@dataclass
+class StateHook(Hook):
+    value: Any
+    subscription: ObservableSubscription | None = None
+    version: int = 0
+
+
+def use_state(
+    initial: StateT | Callable[[], StateT],
+) -> tuple[StateT, Callable[[StateT | Updater], None]]:
+    """
+    Adds state to a function component, similar to React's useState().
+
+    The returned setter accepts either:
+      - a new value, or
+      - a function receiving the previous state and returning the next one.
+
+    Args:
+        initial: Initial state value or a function returning it.
+
+    Returns:
+        (value, set_value) tuple.
+    """
+    component = current_component()
+    hook = component.use_hook(
+        lambda: StateHook(
+            component,
+            initial() if callable(initial) else initial,
+        )
+    )
+
+    def update_subscription(h: StateHook):
+        # Detach previous subscription if any
+        if h.subscription:
+            component._detach_observable_subscription(h.subscription)
+            h.subscription = None
+
+        # Attach new subscription if value is Observable
+        if isinstance(h.value, Observable):
+            h.subscription = component._attach_observable_subscription(h.value)
+
+    update_subscription(hook)
+
+    def set_state(new_value_or_fn: StateT | Updater):
+        """
+        Update the state value.
+
+        Can be called with either:
+          - a direct new value, or
+          - a function that takes the current value and returns the next one.
+        """
+        # Compute next value
+        new_value = (
+            new_value_or_fn(hook.value)
+            if callable(new_value_or_fn)
+            else new_value_or_fn
+        )
+
+        # Only trigger update if value changed (shallow equality)
+        if new_value != hook.value:
+            hook.value = new_value
+            update_subscription(hook)
+            hook.version += 1
+            if hook.component:
+                hook.component._schedule_update()
+
+    return hook.value, set_state

{flet-0.70.0.dev6370 → flet-0.70.0.dev6425}/src/flet/controls/core/stack.py

@@ -31,6 +31,33 @@ class Stack(LayoutControl, AdaptiveControl):
     Stack is also useful if you want to implement implicit animations
     (https://flet.dev/docs/guides/python/animations/) that require knowing absolute
     position of a target value.
+
+    ```python
+    ft.Stack(
+            width=300,
+            height=300,
+            controls=[
+                ft.Image(
+                    src="https://picsum.photos/300/300",
+                    width=300,
+                    height=300,
+                    fit=ft.BoxFit.CONTAIN,
+                ),
+                ft.Row(
+                    alignment=ft.MainAxisAlignment.CENTER,
+                    controls=[
+                        ft.Text(
+                            value="Image title",
+                            color=ft.Colors.SURFACE_TINT,
+                            size=40,
+                            weight=ft.FontWeight.BOLD,
+                            opacity=0.5,
+                        )
+                    ],
+                ),
+            ],
+        )
+    ```
     """
 
     controls: list[Control] = field(default_factory=list)

{flet-0.70.0.dev6370 → flet-0.70.0.dev6425}/src/flet/controls/core/text.py

@@ -51,56 +51,96 @@ class TextSelection:
     A range of text that represents a selection.
     """
 
-    start: Optional[int] = None
-    """
-    The index of the first character in the range.
-    """
-
-    end: Optional[int] = None
-    """
-    The next index after the characters in this range.
-    """
-
-    selection: Optional[str] = None
-    """
-    The text string that is selected.
-    """
-
-    base_offset: Optional[int] = None
+    base_offset: int
     """
     The offset at which the selection originates.
     """
 
-    extent_offset: Optional[int] = None
+    extent_offset: int
     """
     The offset at which the selection terminates.
     """
 
-    affinity: Optional["TextAffinity"] = None
+    affinity: "TextAffinity" = TextAffinity.DOWNSTREAM
     """
     If the text range is collapsed and has more than one visual location (e.g., occurs
     at a line break), which of the two locations to use when painting the caret.
     """
 
-    directional: Optional[bool] = None
+    directional: bool = False
     """
     Whether this selection has disambiguated its base and extent.
     """
 
-    collapsed: Optional[bool] = None
-    """
-    Whether this range is empty (but still potentially placed inside the text).
-    """
-
-    valid: Optional[bool] = None
-    """
-    Whether this range represents a valid position in the text.
-    """
-
-    normalized: Optional[bool] = None
-    """
-    Whether the start of this range precedes the end.
-    """
+    @property
+    def start(self) -> int:
+        """
+        The index of the first character in the range.
+
+        Note:
+            This property is read-only.
+        """
+        if self.base_offset < self.extent_offset:
+            return self.base_offset
+        else:
+            return self.extent_offset
+
+    @property
+    def end(self) -> int:
+        """
+        The next index after the characters in this range.
+
+        Note:
+            This property is read-only.
+        """
+        if self.base_offset < self.extent_offset:
+            return self.extent_offset
+        else:
+            return self.base_offset
+
+    @property
+    def is_valid(self) -> bool:
+        """
+        Whether this range represents a valid position in the text.
+
+        Note:
+            This property is read-only.
+        """
+        return self.start >= 0 and self.end >= 0
+
+    @property
+    def is_collapsed(self) -> bool:
+        """
+        Whether this range is empty (but still potentially placed inside the text).
+
+        Note:
+            This property is read-only.
+        """
+        return self.start == self.end
+
+    @property
+    def is_normalized(self) -> bool:
+        """
+        Whether the start of this range precedes the end.
+
+        Note:
+            This property is read-only.
+        """
+        return self.start <= self.end
+
+    def get_selected_text(self, source_text: str) -> str:
+        """
+        Returns the selected text from the given full text.
+
+        Args:
+            source_text: The full text to get the selection from.
+
+        Raises:
+            AssertionError: If the selection is not valid,
+                i.e. [`is_valid`][(c).] is `False`.
+        """
+        assert self.is_valid
+        return source_text[self.start : self.end]
 
 
 class TextSelectionChangeCause(Enum):
@@ -166,9 +206,16 @@ class TextSelectionChangeCause(Enum):
 
 @dataclass
 class TextSelectionChangeEvent(Event[EventControlType]):
-    text: str
-    cause: TextSelectionChangeCause
+    """An event emitted when the text selection changes."""
+
+    selected_text: str
+    """The selected text."""
+
     selection: TextSelection
+    """The new text selection."""
+
+    cause: Optional[TextSelectionChangeCause] = None
+    """The cause of the selection change."""
 
 
 @control("Text")

{flet-0.70.0.dev6370 → flet-0.70.0.dev6425}/src/flet/controls/material/auto_complete.py

@@ -1,9 +1,9 @@
 from dataclasses import dataclass, field
 from typing import Optional
 
+from flet import LayoutControl
 from flet.controls.base_control import control
-from flet.controls.control import Control
-from flet.controls.control_event import Event, EventHandler
+from flet.controls.control_event import ControlEventHandler, Event, EventHandler
 from flet.controls.types import Number
 
 __all__ = ["AutoComplete", "AutoCompleteSelectEvent", "AutoCompleteSuggestion"]
@@ -11,22 +11,45 @@ __all__ = ["AutoComplete", "AutoCompleteSelectEvent", "AutoCompleteSuggestion"]
 
 @dataclass
 class AutoCompleteSuggestion:
+    """
+    Represents a suggestion item for the [`AutoComplete`][flet.] control.
+    """
+
     key: str
+    """A unique identifier or value used for filtering and selection."""
+
     value: str
+    """The display text shown to the user."""
 
 
 @dataclass
 class AutoCompleteSelectEvent(Event["AutoComplete"]):
+    """Event representing the selection of a suggestion in the AutoComplete control."""
+
+    index: int
+    """
+    The index of the selected suggestion from the corresponding
+    [`AutoComplete.suggestions`][flet.] list.
+    """
+
     selection: AutoCompleteSuggestion
+    """The selected suggestion."""
 
 
 @control("AutoComplete")
-class AutoComplete(Control):
+class AutoComplete(LayoutControl):
     """
     Helps the user make a selection by entering some text and choosing from among a
     list of displayed options.
     """
 
+    value: str = ""
+    """
+    Current text displayed in the input field.
+
+    This value reflects user input even if it does not match any provided suggestion.
+    """
+
     suggestions: list[AutoCompleteSuggestion] = field(default_factory=list)
     """
     A list of [`AutoCompleteSuggestion`][flet.]
@@ -53,7 +76,19 @@ class AutoComplete(Control):
     Called when a suggestion is selected.
     """
 
+    on_change: Optional[ControlEventHandler["AutoComplete"]] = None
+    """
+    Called when the input text changes.
+    """
+
     @property
-    def selected_index(self):
-        # TODO: check availability of _selected_index + a default if not yet available
-        return self._selected_index
+    def selected_index(self) -> Optional[int]:
+        """
+        The index of the (last) selected suggestion.
+
+        It is `None` until a suggestion has been selected from the UI.
+
+        Note:
+            This property is read-only.
+        """
+        return getattr(self, "_selected_index", None)

{flet-0.70.0.dev6370 → flet-0.70.0.dev6425}/src/flet/controls/material/form_field_control.py

@@ -324,4 +324,14 @@ class FormFieldControl(LayoutControl):
     """
 
     async def focus(self):
+        """
+        Request focus for this control.
+
+        Example:
+            ```python
+            async def main(page: ft.Page):
+                page.add(ctf := ft.TextField())
+                await ctf.focus()
+            ```
+        """
         await self._invoke_method("focus")

{flet-0.70.0.dev6370 → flet-0.70.0.dev6425}/src/flet/controls/material/menu_item_button.py

@@ -80,7 +80,7 @@ class MenuItemButton(LayoutControl):
 
     on_click: Optional[ControlEventHandler["MenuItemButton"]] = None
     """
-    Called when the button is clicked.
+    Called when the button is clicked.If not defined the button will be disabled.
     """
 
     on_hover: Optional[ControlEventHandler["MenuItemButton"]] = None

{flet-0.70.0.dev6370 → flet-0.70.0.dev6425}/src/flet/controls/material/search_bar.py

@@ -30,7 +30,8 @@ class SearchBar(LayoutControl):
     controls: list[Control] = field(default_factory=list)
     """
     The list of controls to be displayed below the search bar when in search view.
-    These controls are usually [`ListTile`][flet.]s and will be displayed
+
+    Typically [`ListTile`][flet.]s and will be displayed
     in a [`ListView`][flet.].
     """
 
@@ -42,7 +43,8 @@ class SearchBar(LayoutControl):
     bar_leading: Optional[Control] = None
     """
     A control to display before the text input field when the search view is close.
-    This is typically an `Icon` or an `IconButton`.
+
+    Typically an [`Icon`][flet.] or an [`IconButton`][flet.].
     """
 
     bar_trailing: Optional[list[Control]] = None
@@ -89,7 +91,7 @@ class SearchBar(LayoutControl):
     """
     The color and weight of the search bar's outline.
 
-    This value is combined with [`SearchBar.bar_shape`][flet.] to
+    This value is combined with [`bar_shape`][(c).] to
     create a shape decorated with an outline.
     """
 
@@ -97,8 +99,7 @@ class SearchBar(LayoutControl):
     """
     The shape of the search bar.
 
-    This shape is combined with
-    [`SearchBar.bar_border_side`][flet.] to create a shape
+    This shape is combined with [`bar_border_side`][(c).] to create a shape
     decorated with an outline.
     """
 
@@ -134,7 +135,8 @@ class SearchBar(LayoutControl):
     view_leading: Optional[Control] = None
     """
     A `Control` to display before the text input field when the search view is open.
-    Typically an `Icon` or an `IconButton`.
+
+    Typically an [`Icon`][flet.] or an [`IconButton`][flet.].
 
     Defaults to a back button which closes/pops the search view.
     """
@@ -154,8 +156,7 @@ class SearchBar(LayoutControl):
 
     view_bgcolor: Optional[ColorValue] = None
     """
-    Defines the background color of the
-    search view.
+    Defines the background color of the search view.
     """
 
     view_hint_text: Optional[str] = None
@@ -175,14 +176,12 @@ class SearchBar(LayoutControl):
 
     view_header_text_style: Optional[TextStyle] = None
     """
-    Defines the [`TextStyle`][flet.] of the
-    text being edited on the search view.
+    Defines the text style of the text being edited on the search view.
     """
 
     view_hint_text_style: Optional[TextStyle] = None
     """
-    Defines the [`TextStyle`][flet.] of
-    `view_hint_text`.
+    Defines the text style of [`view_hint_text`][(c).].
     """
 
     view_size_constraints: Optional[BoxConstraints] = None
@@ -232,7 +231,7 @@ class SearchBar(LayoutControl):
     full_screen: bool = False
     """
     Defines whether the search view grows to fill the entire screen when the search
-    bar is tapped. Defaults to `False`.
+    bar is tapped.
     """
 
     keyboard_type: KeyboardType = KeyboardType.TEXT
@@ -243,8 +242,6 @@ class SearchBar(LayoutControl):
     autofocus: bool = False
     """
     Whether the text field should focus itself if nothing else is already focused.
-
-    Defaults to `False`.
     """
 
     on_tap: Optional[ControlEventHandler["SearchBar"]] = None
@@ -254,7 +251,7 @@ class SearchBar(LayoutControl):
 
     on_tap_outside_bar: Optional[ControlEventHandler["SearchBar"]] = None
     """
-    TBD
+    Fired when the user taps outside the search bar while the search view is open.
     """
 
     on_submit: Optional[ControlEventHandler["SearchBar"]] = None
@@ -269,12 +266,12 @@ class SearchBar(LayoutControl):
 
     on_focus: Optional[ControlEventHandler["SearchBar"]] = None
     """
-    TBD
+    Fired when the search bar gains focus.
     """
 
     on_blur: Optional[ControlEventHandler["SearchBar"]] = None
     """
-    TBD
+    Fired when the search bar loses focus.
     """
 
     def __contains__(self, item):
@@ -285,15 +282,21 @@ class SearchBar(LayoutControl):
 
     # Public methods
     async def focus(self):
+        """Requests focus for this control."""
         await self._invoke_method("focus")
 
-    async def blur(self):
-        await self._invoke_method("blur")
-
     async def open_view(self):
+        """Opens the search view."""
         await self._invoke_method("open_view")
 
     async def close_view(self, text: Optional[str] = None):
+        """
+        Closes an opened search view.
+
+        Args:
+            text: The text to set in the search bar when closing the view. If not
+                provided, the current [`value`][(c).] of the search bar will be used.
+        """
         await self._invoke_method(
             "close_view", {"text": text if text is not None else self.value}
         )

{flet-0.70.0.dev6370 → flet-0.70.0.dev6425}/src/flet/controls/material/submenu_button.py

@@ -19,6 +19,25 @@ class SubmenuButton(LayoutControl):
     A menu button that displays a cascading menu.
 
     Typically used in a [`MenuBar`][flet.] control.
+
+    ```python
+    ft.SubmenuButton(
+        content=ft.Text("Choose text style"),
+        key="smbutton",
+        expand=True,
+        menu_style=ft.MenuStyle(
+            alignment=ft.Alignment.BOTTOM_LEFT, side=ft.BorderSide(1)
+        ),
+        controls=[
+            ft.MenuItemButton(
+                content=ft.Text("Underlined"),
+                on_click=lambda e: print(f"{e.control.content.value}.on_click")
+            ),
+            ft.MenuItemButton(...),
+            ...
+        ]
+    )
+    ```
     """
 
     content: Optional[StrOrControl] = None

{flet-0.70.0.dev6370 → flet-0.70.0.dev6425}/src/flet/controls/material/switch.py

@@ -26,6 +26,11 @@ class Switch(LayoutControl, AdaptiveControl):
     two mutually exclusive options.
 
     For example, "On/Off", "Show/Hide".
+
+    ```python
+        ft.Switch(label="Unchecked switch", value=False)
+        ft.Switch(label="Disabled switch", disabled=True)
+    ```
     """
 
     label: Optional[StrOrControl] = None

{flet-0.70.0.dev6370 → flet-0.70.0.dev6425}/src/flet/controls/material/text_button.py

@@ -22,6 +22,14 @@ class TextButton(LayoutControl, AdaptiveControl):
     Text buttons are used for the lowest priority actions, especially when presenting
     multiple options. Text buttons can be placed on a variety of backgrounds. Until the
     button is interacted with, its container isn’t visible.
+
+    ```python
+    ft.TextButton(
+            content="Text Button",
+            icon=ft.Icons.STAR_BORDER,
+            icon_color=ft.Colors.BLUE_300,
+        )
+    ```
     """
 
     content: Optional[StrOrControl] = None

{flet-0.70.0.dev6370 → flet-0.70.0.dev6425}/src/flet/controls/material/textfield.py

@@ -4,8 +4,9 @@ from typing import Optional, Union
 
 from flet.controls.adaptive_control import AdaptiveControl
 from flet.controls.base_control import BaseControl, control
-from flet.controls.control_event import ControlEventHandler
+from flet.controls.control_event import ControlEventHandler, EventHandler
 from flet.controls.core.autofill_group import AutofillHint
+from flet.controls.core.text import TextSelection, TextSelectionChangeEvent
 from flet.controls.material.form_field_control import FormFieldControl
 from flet.controls.padding import PaddingValue
 from flet.controls.text_style import StrutStyle
@@ -144,6 +145,19 @@ class TextField(FormFieldControl, AdaptiveControl):
     Current value of the TextField.
     """
 
+    selection: Optional[TextSelection] = None
+    """
+    Represents the current text selection or caret position in the field.
+
+    When the user selects text, this property is updated to reflect the selected range.
+    If no text is selected, it contains an empty range indicating the caret position.
+
+    Setting this property visually updates the field's selection to match the given
+    value, and hence leads to the [`on_selection_change`][(c).] event being triggered.
+    To ensure the selection is visible and the event is fired, the text field must
+    be focused. Call [`focus()`][(c).focus] on the field before setting this property.
+    """
+
     keyboard_type: KeyboardType = KeyboardType.TEXT
     """
     The type of keyboard to use for editing the text.
@@ -151,7 +165,7 @@ class TextField(FormFieldControl, AdaptiveControl):
 
     multiline: bool = False
     """
-    `True` if TextField can contain multiple lines of text.
+    Whether this field can contain multiple lines of text.
     """
 
     min_lines: Optional[int] = None
@@ -400,7 +414,8 @@ class TextField(FormFieldControl, AdaptiveControl):
     """
     Helps the autofill service identify the type of this text input.
 
-    More information [here](https://api.flutter.dev/flutter/material/TextField/autofillHints.html).
+    More information
+    [here](https://api.flutter.dev/flutter/material/TextField/autofillHints.html).
     """
 
     on_change: Optional[ControlEventHandler["TextField"]] = None
@@ -408,6 +423,16 @@ class TextField(FormFieldControl, AdaptiveControl):
     Called when the typed input for the TextField has changed.
     """
 
+    on_selection_change: Optional[
+        EventHandler[TextSelectionChangeEvent["TextField"]]
+    ] = None
+    """
+    Called when the text selection or caret position changes.
+
+    This can be triggered either by user interaction (selecting text or moving
+    the caret) or programmatically (through the [`selection`][(c).] property).
+    """
+
     on_click: Optional[ControlEventHandler["TextField"]] = None
     """
     TBD

{flet-0.70.0.dev6370 → flet-0.70.0.dev6425}/src/flet/controls/material/time_picker.py

@@ -38,6 +38,14 @@ class TimePicker(DialogControl):
 
     Depending on the `time_picker_entry_mode`, it will show either a Dial or
     an Input (hour and minute text fields) for picking a time.
+
+    ```python
+    ft.TimePicker(
+        value=time(1, 2),
+        time_picker_entry_mode=ft.TimePickerEntryMode.INPUT_ONLY,
+        open=True,
+    )
+    ```
     """
 
     value: Optional[time] = field(default_factory=lambda: datetime.now().time())