feat: `LayoutControl.on_size_change` event for size-awareness #6099

ndonkoHenri · 2026-01-30T21:25:51Z

Test code

import flet as ft


def main(page: ft.Page):
    def handle_size_change(e: ft.LayoutSizeChangeEvent[ft.Container]):
        e.control.content.value = f"{int(e.width)} x {int(e.height)}"

    page.add(
        ft.Container(
            expand=True,
            alignment=ft.Alignment.CENTER,
            bgcolor=ft.Colors.BLUE_ACCENT,
            content=ft.Text(color=ft.Colors.WHITE, weight=ft.FontWeight.BOLD),
            size_change_interval=100,
            on_size_change=handle_size_change,
        )
    )


if __name__ == "__main__":
    ft.run(main)

Summary by Sourcery

Add an opt-in layout size change event to layout-based controls and migrate dependent widgets to use the unified LayoutControl wrapper.

New Features:

Introduce LayoutSizeChangeEvent and on_size_change callback on LayoutControl to notify when a control's rendered size changes.
Add size_change_interval property to control how frequently size change events are fired.

Enhancements:

Wrap layout children in a SizeChangeObserver/MeasureSize layer when size change events are enabled, throttling notifications to reduce layout overhead.
Replace the legacy ConstrainedControl wrapper with LayoutControl across video, charts, ads, map, webview, and related Flutter integrations.
Refine various control and gesture documentation examples for clarity and consistency, including container and reorderable list view docs.

Documentation:

Document size-aware container usage and add a corresponding screenshot to the container control docs, while simplifying other container doc images.

Tests:

Add screenshot-based integration tests for size-aware container and nested themes container examples.

sourcery-ai

We've reviewed this pull request using the Sourcery rules engine

Copilot

Pull request overview

This PR introduces a size-change event for layout-based controls, wires it through the Flutter side, and updates container examples, docs, and tests to demonstrate size-aware behavior.

Changes:

Add LayoutSizeChangeEvent, on_size_change, and size_change_interval to LayoutControl and implement a throttled SizeChangeObserver on the Flutter side, enabling controls to be notified when their rendered size changes.
Update various Flutter plugin controls (maps, charts, ads, video, webview, rive, lottie, datatable2) to wrap content with LayoutControl instead of ConstrainedControl, and expose LayoutSizeChangeEvent at the Python flet API.
Refresh container docs and examples (including a new size-aware example and an animated overlay menu), and add integration screenshot tests and goldens for container size-awareness and nested themes.

Reviewed changes

Copilot reviewed 26 out of 32 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
sdk/python/packages/flet/src/flet/controls/material/reorderable_list_view.py	Minor doc tweak adding an “Example:” label for the existing ListView example.
sdk/python/packages/flet/src/flet/controls/layout_control.py	Introduces `LayoutSizeChangeEvent`, adds `size_change_interval` and `on_size_change` to `LayoutControl`, and cleans up examples and the deprecated `ConstrainedControl` alias.
sdk/python/packages/flet/src/flet/controls/core/gesture_detector.py	Clarifies the `drag_interval` documentation wording without changing behavior.
sdk/python/packages/flet/src/flet/init.py	Re-exports `LayoutSizeChangeEvent` and adds it to the public symbol list so it’s available as `ft.LayoutSizeChangeEvent`.
sdk/python/packages/flet/integration_tests/examples/material/test_container.py	Adds screenshot-based integration tests for the `size_aware`, `nested_themes_1`, and `nested_themes_2` container examples.
sdk/python/packages/flet/integration_tests/examples/material/golden/macos/container/size_aware.png	New macOS golden image for the size-aware container example.
sdk/python/packages/flet/integration_tests/examples/material/golden/macos/container/nested_themes_2.png	New/updated macOS golden image for the `nested_themes_2` container example.
sdk/python/packages/flet/integration_tests/examples/material/golden/macos/container/nested_themes_1.png	New macOS golden image for the `nested_themes_1` container example.
sdk/python/packages/flet/docs/controls/container.md	Simplifies image includes (dropping explicit `alt` attributes), removes the old `background_color` example block, and documents the new size-aware and nested theme examples.
sdk/python/packages/flet-webview/src/flutter/flet_webview/lib/src/webview.dart	Wraps the platform-specific webview with `LayoutControl` instead of the now-removed `ConstrainedControl` widget.
sdk/python/packages/flet-video/src/flutter/flet_video/lib/src/video.dart	Uses `LayoutControl` to wrap the video player widget and slightly tidies playlist construction.
sdk/python/packages/flet-rive/src/flutter/flet_rive/lib/src/rive.dart	Wraps both placeholder and loaded rive widgets in `LayoutControl`, replacing `ConstrainedControl`.
sdk/python/packages/flet-map/src/flutter/flet_map/lib/src/tile_layer.dart	Wraps the tile layer widget in `LayoutControl` to be consistent with the new layout pipeline.
sdk/python/packages/flet-map/src/flutter/flet_map/lib/src/map.dart	Wraps the map widget with `LayoutControl` instead of `ConstrainedControl`.
sdk/python/packages/flet-lottie/src/flutter/flet_lottie/lib/src/lottie.dart	Uses `LayoutControl` to host the Lottie animation widget.
sdk/python/packages/flet-datatable2/src/flutter/flet_datatable2/lib/src/datatable2.dart	Wraps the DataTable2 widget with `LayoutControl`.
sdk/python/packages/flet-charts/src/flutter/flet_charts/lib/src/scatter_chart.dart	Replaces `ConstrainedControl` with `LayoutControl` for scatter chart rendering.
sdk/python/packages/flet-charts/src/flutter/flet_charts/lib/src/radar_chart.dart	Replaces `ConstrainedControl` with `LayoutControl` for radar chart rendering.
sdk/python/packages/flet-charts/src/flutter/flet_charts/lib/src/pie_chart.dart	Replaces `ConstrainedControl` with `LayoutControl` for pie chart rendering.
sdk/python/packages/flet-charts/src/flutter/flet_charts/lib/src/line_chart.dart	Replaces `ConstrainedControl` with `LayoutControl` for line chart rendering.
sdk/python/packages/flet-charts/src/flutter/flet_charts/lib/src/candlestick_chart.dart	Replaces `ConstrainedControl` with `LayoutControl` for candlestick chart rendering.
sdk/python/packages/flet-charts/src/flutter/flet_charts/lib/src/bar_chart.dart	Replaces `ConstrainedControl` with `LayoutControl` for bar chart rendering.
sdk/python/packages/flet-ads/src/flutter/flet_ads/lib/src/native.dart	Wraps the native ad widget in `LayoutControl` so it participates in the unified layout/event pipeline.
sdk/python/packages/flet-ads/src/flutter/flet_ads/lib/src/banner.dart	Wraps the banner ad widget in `LayoutControl`.
sdk/python/examples/controls/container/size_aware.py	Replaces the custom `SizeAwareContainer` canvas control with a simpler example using `Container.on_size_change` and `LayoutSizeChangeEvent`.
sdk/python/examples/controls/container/nested_themes_2.py	Makes the example script runnable as `__main__` without side effects on import.
sdk/python/examples/controls/container/nested_themes_1.py	Same `if __name__ == "__main__":` guard pattern added for the first nested themes example.
sdk/python/examples/controls/container/background_color.py	Removes the outdated background-color container example, consistent with the docs cleanup.
sdk/python/examples/controls/container/animate_4.py	Adds a new example showing an animated slide-in overlay menu using `Container.offset` and `animate_offset`.
sdk/python/examples/controls/container/init.py	Package file (unchanged content) enabling `examples.controls.container` imports used by the new tests.
packages/flet/lib/src/controls/base_controls.dart	Removes the `ConstrainedControl` widget, adds a `_sizeChangeObserver` hook into `LayoutControl`, and implements `SizeChangeObserver`/`MeasureSize` to trigger a throttled `"size_change"` event with measured `w`/`h`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

cloudflare-workers-and-pages · 2026-01-30T21:34:42Z

Deploying flet-docs with Cloudflare Pages

Latest commit:	`047f534`
Status:	✅ Deploy successful!
Preview URL:	https://c879401e.flet-docs.pages.dev
Branch Preview URL:	https://size-aware.flet-docs.pages.dev

View logs

cloudflare-workers-and-pages · 2026-01-30T21:35:49Z

Deploying flet-examples with Cloudflare Pages

Latest commit:	`047f534`
Status:	✅ Deploy successful!
Preview URL:	https://c9d1c2a9.flet-examples.pages.dev
Branch Preview URL:	https://size-aware.flet-examples.pages.dev

View logs

…tionBar` + update `Tabs` example file paths to use underscores instead of hyphens

FeodorFitsner · 2026-02-01T01:27:23Z

sdk/python/packages/flet/src/flet/controls/material/navigation_bar.py

+                f"selected_index ({self.selected_index}) is out of range. "
+                f"Expected a value between 0 and {visible_destinations_count - 1} "
+                "inclusive."
+            )


Isn't it allowed to have only one tab visible?

NavBar destinations you mean? Yeah:

ndonkoHenri added 6 commits January 30, 2026 14:36

refactor: replace ConstrainedControl with LayoutControl in extensions

b654bad

initial commit

0a96572

update example

aa5f327

rename on_layout to on_size_change

09b7bcb

add tests

b62df36

Rename SizeChangeEvent to LayoutSizeChangeEvent

8212d78

ndonkoHenri requested review from FeodorFitsner and Copilot January 30, 2026 21:25

Copilot started reviewing on behalf of ndonkoHenri January 30, 2026 21:26 View session

sourcery-ai bot reviewed Jan 30, 2026

View reviewed changes

Copilot AI reviewed Jan 30, 2026

View reviewed changes

FeodorFitsner approved these changes Jan 31, 2026

View reviewed changes

add validation to ensure at least two visible destinations in `Naviga…

4cf67c9

…tionBar` + update `Tabs` example file paths to use underscores instead of hyphens

FeodorFitsner reviewed Feb 1, 2026

View reviewed changes

ndonkoHenri added 2 commits February 1, 2026 12:41

fix failing tests

2e966d3

Merge branch 'main' into size-aware

047f534

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: `LayoutControl.on_size_change` event for size-awareness #6099

feat: `LayoutControl.on_size_change` event for size-awareness #6099

Uh oh!

ndonkoHenri commented Jan 30, 2026 •

edited by sourcery-ai bot

Loading

Uh oh!

sourcery-ai bot left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

cloudflare-workers-and-pages bot commented Jan 30, 2026 •

edited

Loading

Uh oh!

cloudflare-workers-and-pages bot commented Jan 30, 2026 •

edited

Loading

Uh oh!

FeodorFitsner Feb 1, 2026

Uh oh!

ndonkoHenri Feb 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat: LayoutControl.on_size_change event for size-awareness #6099

Are you sure you want to change the base?

feat: LayoutControl.on_size_change event for size-awareness #6099

Uh oh!

Conversation

ndonkoHenri commented Jan 30, 2026 • edited by sourcery-ai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test code

Summary by Sourcery

Uh oh!

sourcery-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

cloudflare-workers-and-pages bot commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying flet-docs with Cloudflare Pages

Uh oh!

cloudflare-workers-and-pages bot commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying flet-examples with Cloudflare Pages

Uh oh!

FeodorFitsner Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

ndonkoHenri Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat: `LayoutControl.on_size_change` event for size-awareness #6099

feat: `LayoutControl.on_size_change` event for size-awareness #6099

ndonkoHenri commented Jan 30, 2026 •

edited by sourcery-ai bot

Loading

cloudflare-workers-and-pages bot commented Jan 30, 2026 •

edited

Loading

cloudflare-workers-and-pages bot commented Jan 30, 2026 •

edited

Loading