v1: Add align, margin and their animated counterparts to ConstrainedControl class
#5571
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Replaces usage of UpdateBehavior with a new context API for managing auto update state across the codebase. Updates examples, main app logic, and event handling to use ft.context methods. Removes UpdateBehavior from public API and documentation, adds integration tests for auto update behavior, and updates documentation and navigation to reflect the new context API.
Added detailed docstrings to Context class methods for better clarity and documentation. Improved type hints and assertions, including stricter return type for page property and assertion to ensure context is associated with a page.
Introduces `align` and `margin` properties with corresponding animation options (`animate_align`, `animate_margin`) to ConstrainedControl in both Dart and Python SDKs. Updates base_controls.dart to handle animated alignment and margin, adds Python examples for animating align and margin, and ensures Container skips margin property to avoid conflicts.
Renamed and enhanced the data_view decorator to cache, adding a freeze option for control freezing. Updated imports, __all__, and all usages in tests to use the new cache decorator.
Renamed and enhanced the data_view decorator to cache, adding a freeze option for control immutability. Updated imports and usages throughout the codebase to reflect the new decorator name and functionality.
Changed the target version to 0.70.0.dev(?!5399) and switched to using 'uv run' for executing pypi-cleanup. Added cleanup for the 'flet-desktop-light' package.
Eliminated the use of Debouncer in CupertinoSlider, RangeSlider, and Slider controls. Property updates and change events are now triggered immediately on value change, simplifying the code and improving responsiveness.
Introduces a new example app 'sunflower.py' using Flet in the declarative style. The app visualizes sunflower seed patterns and allows interactive adjustment of seed count via a slider.
Updated Python examples and documentation to use TabBar inside Tabs, reflecting new API structure. Changed tab animation duration default from 250ms to 100ms in both Dart and Python implementations, and fixed on_change handler type in Tabs control. This improves consistency and aligns with recent API changes. Fix #5539
Changed the center_title property from a required bool to Optional[bool] in both Dart and Python AppBar controls. This allows the default value to be determined by AppBarTheme.center_title, improving flexibility and alignment with platform conventions. Also updated related docstrings for clarity and formatting.
Introduces a cached seed view for efficient rendering, adds unique keys to seeds, and refactors state management for clarity. The UI is updated to use an app bar and dark theme, and the seed count update logic is improved for better responsiveness.
Refactored function name from _marginedControl to _marginControl for clarity and consistency in base_controls.dart.
Replaces all instances of ControlBuilder with StateView in Dart and Python code, documentation, and tests. Updates imports, class names, and references to reflect the new naming. Removes ControlBuilder documentation and adds StateView documentation. This improves clarity and consistency for state-driven UI components.
Introduces ParamSpec and TypeVar for improved type safety in the cache decorator. Adds overloads to the cache function and updates argument and return type annotations for better compatibility with type checkers.
Replaces @ft.cache() with @ft.cache to correctly apply the decorator. Updates the seed count display to handle singular and plural forms for better user feedback.
Added assertions for ft.context.page in autoupdate.py to ensure context is associated with a page. Renamed test_autoupdate.py to test_context.py and added a test to verify that accessing ft.context.page outside of a Flet app raises an exception.
Updated documentation for the Context class with usage examples and improved docstrings. Exposed Context in the public API via __init__.py and reorganized mkdocs navigation to move Context under Utility. Minor code reordering for clarity.
Co-authored-by: Copilot <[email protected]>
Introduces new integration tests for Align and Margin controls in Flet, including golden images for macOS. Also refactors sunflower.py to compute seeds in State's __post_init__ method for improved initialization.
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Pull Request Overview
This PR implements a significant refactoring of Flet's control system by adding alignment and margin properties to ConstrainedControl, introducing a new context API for auto-update management, and replacing the old ControlBuilder with a new StateView control for reactive views.
Key changes:
- Added
align,margin,animate_align, andanimate_marginproperties toConstrainedControlwith corresponding Flutter/Python implementations - Introduced a new
Contextclass replacing the staticUpdateBehaviorAPI for managing auto-update state - Replaced
ControlBuilderwithStateViewand added acachedecorator for memoizing control trees
Reviewed Changes
Copilot reviewed 49 out of 54 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
constrained_control.py |
Added align, margin, animate_align, and animate_margin properties to the base constrained control class |
context.py |
Introduced new Context class with methods for managing auto-update behavior |
state_view.py |
Renamed and refactored ControlBuilder to StateView with improved caching |
cache.py |
New decorator for memoizing control trees with optional freezing |
container.py |
Removed margin property (now inherited from ConstrainedControl) and updated skip properties |
tabs.py |
Changed default animation duration and updated event handler type annotation |
app_bar.py |
Changed center_title from bool to Optional[bool] and improved documentation formatting |
| Flutter files | Updated slider controls to remove debouncers and trigger immediate updates |
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
Deploying flet-docs with
|
| Latest commit: |
bc2882b
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://c44cff3d.flet-docs.pages.dev |
| Branch Preview URL: | https://v1-align-margin.flet-docs.pages.dev |
ndonkoHenri
reviewed
Aug 19, 2025
sdk/python/packages/flet/src/flet/controls/material/container.py
Outdated
Show resolved
Hide resolved
ndonkoHenri
reviewed
Aug 19, 2025
ndonkoHenri
reviewed
Aug 19, 2025
Improved readability of docstrings in AppBar and Container by splitting long lines and removing unnecessary noqa comments. No functional changes were made.
Eliminated the margin property and its documentation from the Card control. Updated internals to skip the margin property, likely to align with changes in theming or layout management.
Updated the cache decorator example to use ft.StateView instead of ft.ControlBuilder for rendering state-dependent UI. This aligns with current best practices and improves code clarity.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Close #4337
Summary by Sourcery
Add align and margin properties (and their animated variants) to ConstrainedControl, introduce a new context API for auto-update behavior, and replace the old ControlBuilder with a StateView + cache decorator for reactive views. Clean up related examples, tests, docs, and refactor various controls (sliders, tabs, app bar) to use the new APIs.
New Features:
align,margin,animate_align, andanimate_marginproperties to ConstrainedControl with corresponding Flutter/Python implementationsContextclass for managing auto-update state, replacing the static UpdateBehavior APIcachedecorator for memoizing control trees with optional freezingControlBuilderwith a newStateViewcontrol for data-driven viewsEnhancements:
TabBarandTabsroles and shorten default animation durationscenter_titleoptional semantics)Build:
uv runDocumentation:
StateViewandContext; remove outdated ControlBuilder and UpdateBehavior entriesTests: