v1: Refactor NavigationDrawer, Pagelet API and usage (#5754)

* Refactor Pagelet drawer handling and update examples

Refactored Pagelet drawer and end drawer open/close logic to use async invoke methods instead of property updates. Updated Python examples to use new async drawer methods and added a declarative example. Cleaned up related Dart code and removed unused imports.

* Clip scaffold when drawer is present in Pagelet

Wraps the scaffold in a ClipRect when a drawer or endDrawer is present to ensure drawer animations remain hidden outside the pagelet bounds.

* Refactor NavigationDrawer API and usage

Removed NavigationDrawerPosition enum and dialog-based drawer handling. NavigationDrawer is now set via 'drawer' and 'end_drawer' properties on Page/Pagelet, with new async methods for showing and closing drawers. Updated Dart and Python code to support direct drawer control, removed ScaffoldKeyProvider, and revised examples and tests to use the new API.

Fix #5386

* Remove NavigationDrawerPosition type documentation

Deleted the navigationdrawerposition.md documentation file and its reference from mkdocs.yml, likely because the type is deprecated or no longer relevant.

* Refactor navigation drawer tests to use resize_page

Replaces manual window size assignments in navigation drawer integration tests with the new async resize_page method for consistency and reliability. Adds the resize_page utility to FletTestApp, improving test maintainability and accuracy. Updates golden images to reflect new window dimensions.

* Improve window resize handling in FletTestApp

Replaces event-based waiting with polling to ensure window dimensions are updated correctly before and after adjusting for window chrome size. This change improves reliability of window resizing during tests.

* Simplify window size adjustment logic

Refactored the method to set window size by removing redundant update and wait steps. The window size is now set directly with chrome adjustments, improving efficiency.

* Refactor Pagelet usage in basic_declarative.py

Simplifies Pagelet reference handling by removing the use of ft.Ref and cast, assigning the Pagelet instance directly to a variable. Updates drawer handler functions to use the new variable reference.

* Add shape drawer example and update test resizing

Added a new declarative shape drawer example app using Flet's canvas. Updated integration tests for Cupertino and Material controls to use the new `resize_page` method for setting window size, replacing direct window property assignments. Updated multiple golden image files for test cases.

* Refactor window resizing in integration tests

Replaces direct assignment of page window width and height with calls to the async resize_page method across multiple integration test files. This improves consistency and ensures proper asynchronous handling of window resizing for screenshot-based tests. Also updates related golden images to reflect any visual changes from the new resizing approach.

* Improve screenshot similarity assertion message

Enhanced the assertion error message in flet_test_app.py to include actual and threshold similarity values for easier debugging. Updated golden image for Cupertino bottom sheet basic test.

* Refactor shader mask test and update golden image

Reordered imports and function calls in test_shader_mask.py for clarity and consistency. Updated the golden image for shader mask on macOS. Minor changes in flet_test_app.py to support integration testing.

* Rename Dropdown 'change' event to 'text_change'

Updated the event name from 'change' to 'text_change' for dropdown controls in Dart and Python implementations. Adjusted related handler and usage in example code to improve clarity between selection changes and text input changes.

Close #5760

---------

Co-authored-by: InesaFitsner <[email protected]>

Author: FeodorFitsner

packages/flet/lib/src/controls/dropdown.dart

@@ -33,7 +33,7 @@ class _DropdownControlState extends State<DropdownControl> {
     debugPrint("Typed text: ${_controller.text}");
     if (_controller.text != widget.control.getString("text")) {
       widget.control.updateProperties({"text": _controller.text});
-      widget.control.triggerEvent("change", _controller.text);
+      widget.control.triggerEvent("text_change", _controller.text);
     }
   }
 

packages/flet/lib/src/controls/navigation_drawer.dart

@@ -6,7 +6,6 @@ import '../utils/colors.dart';
 import '../utils/edge_insets.dart';
 import '../utils/icons.dart';
 import '../utils/numbers.dart';
-import '../widgets/scaffold_key_provider.dart';
 import 'base_controls.dart';
 import 'control_widget.dart';
 
@@ -83,21 +82,6 @@ class _NavigationDrawerControlState extends State<NavigationDrawerControl> {
       }).toList(),
     );
 
-    WidgetsBinding.instance.addPostFrameCallback((_) {
-      if (widget.control.getBool("open", false) == false) {
-        if (endDrawer &&
-            ScaffoldKeyProvider.of(context)?.currentState?.isEndDrawerOpen ==
-                true) {
-          ScaffoldKeyProvider.of(context)?.currentState?.closeEndDrawer();
-        } else if (ScaffoldKeyProvider.of(context)
-                ?.currentState
-                ?.isDrawerOpen ==
-            true) {
-          ScaffoldKeyProvider.of(context)?.currentState?.closeDrawer();
-        }
-      }
-    });
-
     return BaseControl(control: widget.control, child: drawer);
   }
 }

packages/flet/lib/src/controls/pagelet.dart

@@ -1,6 +1,5 @@
 import 'package:flet/src/utils/buttons.dart';
 import 'package:flet/src/utils/colors.dart';
-import 'package:flet/src/utils/numbers.dart';
 import 'package:flutter/cupertino.dart';
 import 'package:flutter/material.dart';
 
@@ -11,8 +10,8 @@ import '../utils/platform.dart';
 import '../widgets/error.dart';
 import 'app_bar.dart';
 import 'base_controls.dart';
+import 'control_widget.dart';
 import 'cupertino_app_bar.dart';
-import 'navigation_drawer.dart';
 
 class PageletControl extends StatefulWidget {
   final Control control;
@@ -27,6 +26,38 @@ class PageletControl extends StatefulWidget {
 class _PageletControlState extends State<PageletControl> {
   final scaffoldKey = GlobalKey<ScaffoldState>();
 
+  @override
+  void initState() {
+    super.initState();
+    widget.control.addInvokeMethodListener(_invokeMethod);
+  }
+
+  @override
+  void dispose() {
+    widget.control.removeInvokeMethodListener(_invokeMethod);
+    super.dispose();
+  }
+
+  Future<dynamic> _invokeMethod(String name, dynamic args) async {
+    debugPrint("Pagelet.$name($args)");
+    switch (name) {
+      case "show_drawer":
+        scaffoldKey.currentState?.openDrawer();
+        break;
+      case "close_drawer":
+        scaffoldKey.currentState?.closeDrawer();
+        break;
+      case "show_end_drawer":
+        scaffoldKey.currentState?.openEndDrawer();
+        break;
+      case "close_end_drawer":
+        scaffoldKey.currentState?.closeEndDrawer();
+        break;
+      default:
+        throw Exception("Unknown Pagelet method: $name");
+    }
+  }
+
   @override
   Widget build(BuildContext context) {
     debugPrint("Pagelet build: ${widget.control.id}");
@@ -38,6 +69,7 @@ class _PageletControlState extends State<PageletControl> {
     var bottomSheet = widget.control.buildWidget("bottom_sheet");
     var drawer = widget.control.child("drawer");
     var endDrawer = widget.control.child("end_drawer");
+    var hasDrawer = drawer != null || endDrawer != null;
     var fab = widget.control.buildWidget("floating_action_button");
 
     if (content == null) {
@@ -50,66 +82,10 @@ class _PageletControlState extends State<PageletControl> {
 
     var bnb = navigationBar ?? bottomAppBar;
 
-    final bool? drawerOpened = widget.control.getBool("drawer_opened");
-    final bool? endDrawerOpened = widget.control.getBool("end_drawer_opened");
-    final fabLocation = widget.control.getFloatingActionButtonLocation(
-        "floating_action_button_location",
-        FloatingActionButtonLocation.endFloat);
-
-    void dismissDrawer(dynamic id) {
-      // fixme: id
-      widget.control.updateProperties({"open": false});
-      widget.control.triggerEvent("dismiss");
+    void dismissDrawer(int id) {
+      widget.control.backend.triggerControlEventById(id, "dismiss");
     }
 
-    WidgetsBinding.instance.addPostFrameCallback((_) {
-      if (drawer != null) {
-        if (scaffoldKey.currentState?.isDrawerOpen == false &&
-            drawerOpened == true) {
-          widget.control
-              .updateProperties({"drawer_opened": false}, python: false);
-          dismissDrawer(drawer.id);
-        }
-        if (drawer.getBool("open", false)! && drawerOpened != true) {
-          if (scaffoldKey.currentState?.isEndDrawerOpen == true) {
-            scaffoldKey.currentState?.closeEndDrawer();
-          }
-          Future.delayed(const Duration(milliseconds: 1)).then((value) {
-            scaffoldKey.currentState?.openDrawer();
-            widget.control
-                .updateProperties({"drawer_opened": true}, python: false);
-          });
-        } else if (!drawer.getBool("open", false)! && drawerOpened == true) {
-          scaffoldKey.currentState?.closeDrawer();
-          widget.control
-              .updateProperties({"drawer_opened": false}, python: false);
-        }
-      }
-      if (endDrawer != null) {
-        if (scaffoldKey.currentState?.isEndDrawerOpen == false &&
-            endDrawerOpened == true) {
-          widget.control
-              .updateProperties({"end_drawer_opened": false}, python: false);
-          dismissDrawer(endDrawer.id);
-        }
-        if (endDrawer.getBool("open", false)! && endDrawerOpened != true) {
-          if (scaffoldKey.currentState?.isDrawerOpen == true) {
-            scaffoldKey.currentState?.closeDrawer();
-          }
-          Future.delayed(const Duration(milliseconds: 1)).then((value) {
-            scaffoldKey.currentState?.openEndDrawer();
-            widget.control
-                .updateProperties({"end_drawer_opened": true}, python: false);
-          });
-        } else if (!endDrawer.getBool("open", false)! &&
-            endDrawerOpened == true) {
-          scaffoldKey.currentState?.closeEndDrawer();
-          widget.control
-              .updateProperties({"end_drawer_opened": false}, python: false);
-        }
-      }
-    });
-
     var bar = appBar != null
         ? appBar.type == "AppBar"
             ? widgetsDesign == PageDesign.cupertino
@@ -126,30 +102,30 @@ class _PageletControlState extends State<PageletControl> {
         backgroundColor: widget.control.getColor("bgcolor", context) ??
             CupertinoTheme.of(context).scaffoldBackgroundColor,
         appBar: bar is AppBarControl ? bar : null,
-        drawer:
-            drawer != null ? NavigationDrawerControl(control: drawer) : null,
+        drawer: drawer != null ? ControlWidget(control: drawer) : null,
         onDrawerChanged: (opened) {
           if (drawer != null && !opened) {
-            widget.control
-                .updateProperties({"drawer_opened": false}, python: false);
             dismissDrawer(drawer.id);
           }
         },
-        endDrawer: endDrawer != null
-            ? NavigationDrawerControl(control: endDrawer)
-            : null,
+        endDrawer: endDrawer != null ? ControlWidget(control: endDrawer) : null,
         onEndDrawerChanged: (opened) {
           if (endDrawer != null && !opened) {
-            widget.control
-                .updateProperties({"end_drawer_opened": false}, python: false);
             dismissDrawer(endDrawer.id);
           }
         },
         body: content,
         bottomNavigationBar: bnb,
         bottomSheet: bottomSheet,
         floatingActionButton: fab,
-        floatingActionButtonLocation: fabLocation);
+        floatingActionButtonLocation: widget.control
+            .getFloatingActionButtonLocation("floating_action_button_location",
+                FloatingActionButtonLocation.endFloat));
+
+    if (hasDrawer) {
+      // Clip to page bounds so the drawer animation stays hidden outside the pagelet.
+      scaffold = ClipRect(child: scaffold);
+    }
 
     if (bar is CupertinoAppBarControl) {
       scaffold = CupertinoPageScaffold(

packages/flet/lib/src/controls/scrollable_control.dart

@@ -42,14 +42,14 @@ class _ScrollableControlState extends State<ScrollableControl>
 
   Future<dynamic> _invokeMethod(String name, dynamic args) async {
     debugPrint("ScrollableControl.$name($args)");
-    var offset = parseDouble(args["offset"]);
-    var delta = parseDouble(args["delta"]);
-    var scrollKey = parseKey(args["scroll_key"]);
-    var globalKey = scrollKey != null
-        ? widget.control.backend.globalKeys[scrollKey.toString()]
-        : null;
     switch (name) {
       case "scroll_to":
+        var offset = parseDouble(args["offset"]);
+        var delta = parseDouble(args["delta"]);
+        var scrollKey = parseKey(args["scroll_key"]);
+        var globalKey = scrollKey != null
+            ? widget.control.backend.globalKeys[scrollKey.toString()]
+            : null;
         var duration = parseDuration(args["duration"], Duration.zero)!;
         var curve = parseCurve(args["curve"], Curves.ease)!;
         if (globalKey != null) {

packages/flet/lib/src/controls/view.dart

@@ -1,6 +1,5 @@
 import 'dart:async';
 
-import 'package:collection/collection.dart';
 import 'package:flutter/cupertino.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
@@ -22,7 +21,6 @@ import '../utils/theme.dart';
 import '../widgets/loading_page.dart';
 import '../widgets/page_context.dart';
 import '../widgets/page_media.dart';
-import '../widgets/scaffold_key_provider.dart';
 import 'app_bar.dart';
 import 'cupertino_app_bar.dart';
 import 'scroll_notification_control.dart';
@@ -72,33 +70,32 @@ class _ViewControlState extends State<ViewControl> {
   Future<dynamic> _invokeMethod(String name, dynamic args) async {
     debugPrint("View.$name($args)");
     switch (name) {
+      case "show_drawer":
+        _scaffoldKey.currentState?.openDrawer();
+        break;
+      case "close_drawer":
+        _scaffoldKey.currentState?.closeDrawer();
+        break;
+      case "show_end_drawer":
+        _scaffoldKey.currentState?.openEndDrawer();
+        break;
+      case "close_end_drawer":
+        _scaffoldKey.currentState?.closeEndDrawer();
+        break;
       case "confirm_pop":
         if (_popCompleter != null && !_popCompleter!.isCompleted) {
           _popCompleter?.complete(args["should_pop"]);
         }
+        break;
     }
   }
 
   void _overlayOrDialogsChanged() {
     setState(() {});
   }
 
-  Future<void> _dismissDrawer(Control drawer, FletBackend backend) async {
-    await Future.delayed(const Duration(milliseconds: 250));
-    backend.updateControl(drawer.id, {"open": false});
-    backend.triggerControlEvent(drawer, "dismiss");
-  }
-
-  void _openDrawers(Control? drawer, Control? endDrawer) {
-    if (drawer != null &&
-        drawer.getBool("open", false) == true &&
-        _scaffoldKey.currentState?.isDrawerOpen == false) {
-      _scaffoldKey.currentState?.openDrawer();
-    } else if (endDrawer != null &&
-        endDrawer.getBool("open", false) == true &&
-        _scaffoldKey.currentState?.isEndDrawerOpen == false) {
-      _scaffoldKey.currentState?.openEndDrawer();
-    }
+  Future<void> _dismissDrawer(int drawerId) async {
+    widget.control.backend.triggerControlEventById(drawerId, "dismiss");
   }
 
   @override
@@ -156,20 +153,17 @@ class _ViewControlState extends State<ViewControl> {
     var overlayControls = _overlay?.children("controls");
     var dialogControls = _dialogs?.children("controls");
 
-    Control? drawer = dialogControls?.firstWhereOrNull(
-        (c) => c.type == "NavigationDrawer" && c.get("position") != "end");
-    Control? endDrawer = dialogControls?.firstWhereOrNull(
-        (c) => c.type == "NavigationDrawer" && c.get("position") == "end");
+    var drawer = widget.control.child("drawer");
+    var endDrawer = widget.control.child("end_drawer");
 
     var isRootView = control.id == pageViews.first.id;
 
     if (overlayControls != null && dialogControls != null) {
       if (control.id == pageViews.last.id) {
         overlayWidgets
             .addAll(overlayControls.map((c) => ControlWidget(control: c)));
-        overlayWidgets.addAll(dialogControls
-            .where((dialog) => dialog.type != "NavigationDrawer")
-            .map((c) => ControlWidget(control: c)));
+        overlayWidgets
+            .addAll(dialogControls.map((c) => ControlWidget(control: c)));
         overlayWidgets.add(PageMedia(view: widget.control.parent));
       }
 
@@ -179,10 +173,6 @@ class _ViewControlState extends State<ViewControl> {
       }
     }
 
-    WidgetsBinding.instance.addPostFrameCallback((_) {
-      _openDrawers(drawer, endDrawer);
-    });
-
     Widget body = Stack(children: [
       SizedBox.expand(
           child: Container(
@@ -202,37 +192,34 @@ class _ViewControlState extends State<ViewControl> {
             : parseTheme(
                 control.parent!.get("theme"), context, Brightness.dark);
 
-    Widget scaffold = ScaffoldKeyProvider(
-      scaffoldKey: _scaffoldKey,
-      child: Scaffold(
-        key: appBarWidget == null || appBarWidget is AppBarControl
-            ? _scaffoldKey
-            : null,
-        backgroundColor: control.getColor("bgcolor", context) ??
-            ((pageData?.widgetsDesign == PageDesign.cupertino)
-                ? CupertinoTheme.of(context).scaffoldBackgroundColor
-                : Theme.of(context).scaffoldBackgroundColor),
-        appBar: appBarWidget is AppBarControl ? appBarWidget : null,
-        drawer: drawer != null ? ControlWidget(control: drawer) : null,
-        onDrawerChanged: (opened) {
-          if (!opened) {
-            _dismissDrawer(drawer!, FletBackend.of(context));
-          }
-        },
-        endDrawer: endDrawer != null ? ControlWidget(control: endDrawer) : null,
-        onEndDrawerChanged: (opened) {
-          if (!opened) {
-            _dismissDrawer(endDrawer!, FletBackend.of(context));
-          }
-        },
-        body: body,
-        bottomNavigationBar: control.buildWidget("navigation_bar") ??
-            control.buildWidget("bottom_appbar"),
-        floatingActionButton: control.buildWidget("floating_action_button"),
-        floatingActionButtonLocation: control.getFloatingActionButtonLocation(
-            "floating_action_button_location",
-            FloatingActionButtonLocation.endFloat),
-      ),
+    Widget scaffold = Scaffold(
+      key: appBarWidget == null || appBarWidget is AppBarControl
+          ? _scaffoldKey
+          : null,
+      backgroundColor: control.getColor("bgcolor", context) ??
+          ((pageData?.widgetsDesign == PageDesign.cupertino)
+              ? CupertinoTheme.of(context).scaffoldBackgroundColor
+              : Theme.of(context).scaffoldBackgroundColor),
+      appBar: appBarWidget is AppBarControl ? appBarWidget : null,
+      drawer: drawer != null ? ControlWidget(control: drawer) : null,
+      onDrawerChanged: (opened) {
+        if (!opened) {
+          _dismissDrawer(drawer!.id);
+        }
+      },
+      endDrawer: endDrawer != null ? ControlWidget(control: endDrawer) : null,
+      onEndDrawerChanged: (opened) {
+        if (!opened) {
+          _dismissDrawer(endDrawer!.id);
+        }
+      },
+      body: body,
+      bottomNavigationBar: control.buildWidget("navigation_bar") ??
+          control.buildWidget("bottom_appbar"),
+      floatingActionButton: control.buildWidget("floating_action_button"),
+      floatingActionButtonLocation: control.getFloatingActionButtonLocation(
+          "floating_action_button_location",
+          FloatingActionButtonLocation.endFloat),
     );
 
     var systemOverlayStyle =