feat: Add pop_until_with_result to Page

[brunobrown]

Description

Add Page.pop_until_with_result() method and ViewPopResultEvent to support popping multiple views from the navigation stack and returning a result to the destination view — the Flet equivalent of Flutter's Navigator.popUntilWithResult.

Fixes #6326

Test Code

import asyncio

import flet as ft


def main(page: ft.Page):
    page.title = "pop_until_with_result Example"

    result_text = ft.Text("No result yet", size=18)

    def route_change():
        page.views.clear()
        page.views.append(
            ft.View(
                route="/",
                controls=[
                    ft.AppBar(title=ft.Text("Home"), bgcolor=ft.Colors.SURFACE_BRIGHT),
                    result_text,
                    ft.Button(
                        "Start flow",
                        on_click=lambda _: asyncio.create_task(page.push_route("/step1")),
                    ),
                ],
            )
        )
        if page.route in ["/step1", "/step2"]:
            page.views.append(
                ft.View(
                    route="/step1",
                    controls=[
                        ft.AppBar(title=ft.Text("Step 1"), bgcolor=ft.Colors.SURFACE_BRIGHT),
                        ft.Button(
                            "Go to Step 2",
                            on_click=lambda _: asyncio.create_task(page.push_route("/step2")),
                        ),
                    ],
                )
            )
        if page.route == "/step2":
            page.views.append(
                ft.View(
                    route="/step2",
                    controls=[
                        ft.AppBar(title=ft.Text("Step 2 (Final)"), bgcolor=ft.Colors.SURFACE_BRIGHT),
                        ft.Text("Flow complete!"),
                        ft.Button(
                            "Finish and go Home",
                            on_click=lambda _: asyncio.create_task(
                                page.pop_until_with_result("/", result="Flow completed!")
                            ),
                        ),
                    ],
                )
            )
        page.update()

    def on_pop_result(e: ft.ViewPopResultEvent):
        result_text.value = f"Result: {e.result}"
        page.show_dialog(ft.SnackBar(ft.Text(f"Result: {e.result}")))
        page.update()

    async def view_pop(e: ft.ViewPopEvent):
        if e.view is not None:
            page.views.remove(e.view)
            top_view = page.views[-1]
            await page.push_route(top_view.route)

    page.on_route_change = route_change
    page.on_view_pop = view_pop
    page.on_view_pop_result = on_pop_result
    route_change()


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

Type of change

• New feature (non-breaking change which adds functionality)

Checklist

• I signed the CLA.
• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• My changes generate no new warnings
• New and existing tests pass locally with my changes
• I have made corresponding changes to the documentation (if applicable)

Screenshots

Additional details

• Flutter reference: Navigator.popUntilWithResult — issue #30112 (79+ reactions, 6 years open)
• No Dart-side changes needed — Python's page.update() syncs the view list and Flutter's Navigator rebuilds with correct transitions automatically
• 12 unit tests covering: event creation, exports, method behavior, edge cases, event firing
• Example app added at examples/apps/routing_navigation/pop_until_with_result.py

Files changed

File	Change
sdk/python/packages/flet/src/flet/controls/page.py	ViewPopResultEvent, pop_until_with_result(), on_view_pop_result, unified before_event
sdk/python/packages/flet/src/flet/__init__.py	Export ViewPopResultEvent
sdk/python/packages/flet/tests/test_pop_until_with_result.py	12 unit tests
sdk/python/examples/apps/routing_navigation/pop_until_with_result.py	Example app
sdk/python/packages/flet/docs/assets/navigation-routing/pop-until-with-result-example.gif	Demo GIF

Summary by Sourcery

Add support for popping multiple views with a result and wire it into page navigation events.

New Features:

• Introduce ViewPopResultEvent to carry navigation results back to the destination view when popping views.
• Add Page.pop_until_with_result() to pop back to a target route while returning a result via on_view_pop_result.
• Expose ViewPopResultEvent from the top-level flet package for direct import.
• Provide an example routing app demonstrating pop_until_with_result usage.

Tests:

• Add unit tests covering ViewPopResultEvent creation, typing, imports, the new on_view_pop_result handler, and pop_until_with_result behavior and edge cases.

[CLAassistant]

All committers have signed the CLA.

[sourcery-ai]

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

[FeodorFitsner]

Thanks for the PR!

A few notes:

• Rename pop_until_with_result() to pop_views_until() (with optional result).
• Rename on_view_pop_result to on_views_pop_until.

[FeodorFitsner]

Hey @brunobrown, can you change the base of your PR to release/v0.85.0, pull the latest from the base branch and fix integration test(s). Thanks!

[FeodorFitsner]

Could you resolve conflicts please?

[ndonkoHenri]

Please update your cross references in the modified/added docstrings to use the new style: https://github.com/flet-dev/flet/blob/main/.codex/skills/docs-conventions/SKILL.md?plain=1#L12

[ndonkoHenri]

Users dont usually have flutter knowledge, so we can remove this line.

[ndonkoHenri]

Update cross refs here too.

[ndonkoHenri]

Suggested change

	* Add `Page.pop_views_until()` to pop multiple views and return a result to the destination view ([#6326](https://github.com/flet-dev/flet/issues/6326), [#6347](https://github.com/flet-dev/flet/pull/6347)) by [@brunobrown](https://github.com/brunobrown).
	* Add `Page.pop_views_until()` to pop multiple views and return a result to the destination view ([#6326](https://github.com/flet-dev/flet/issues/6326), [#6347](https://github.com/flet-dev/flet/pull/6347)) by @brunobrown.