Implement MenuControllerDecorator for animating menus. #163481

davidhicks980 · 2025-02-17T14:36:54Z

This PR adds a MenuControllerDecorator ~~mixin~~ class that intercepts calls to MenuController.open() and MenuController.close() to allow users to run animations or add a delay prior to a menu opening or closing.

Additionally, this PR adds a MenuController.animationStatus getter and a MenuController.maybeAnimationStatusOf static method to interrogate the current animation status of the nearest menu. I was torn between creating a new enum, such as

enum MenuStatus  {
  opened,
  opening,
  closed,
  closing
}

and sticking with AnimationStatus. I stuck with AnimationStatus, but let me know if you have a preference.

Precursor for #143416, #135025, #143712

Demo

Screen.Recording.2025-02-17.at.8.58.43.AM.mov

Basic usage:

class _MenuAnimator extends MenuControllerDecorator {
  const _MenuAnimator({required super.menuController, required this.animationController});
  final AnimationController animationController;

  @override
  void handleMenuOpenRequest({ui.Offset? position}) {
    // Call whenComplete() rather than whenCompleteOrCancel() to avoid marking
    // the menu as opened when the [AnimationStatus] moves from forward to
    // reverse.
    animationController.forward().whenComplete(markMenuOpened);
  }

  @override
  void handleMenuCloseRequest() {
    // Animate the children of this menu closed.
    closeChildren();
    animationController.reverse().whenComplete(markMenuClosed);
  }
}

class Menu extends StatefulWidget {
  const Menu({super.key});

  @override
  State<Menu> createState() => _MenuState();
}

class _MenuState extends State<MenuControllerDecoratorExample>
    with SingleTickerProviderStateMixin {
  late final AnimationController animationController;
  late final _MenuAnimator menuAnimator;

  @override
  void initState() {
    super.initState();
    animationController = AnimationController.unbounded(vsync: this);
    menuAnimator = _MenuAnimator(
      menuController: MenuController(),
      animationController: animationController,
    );
  }

  @override
  void dispose() {
    animationController.dispose();
    super.dispose();
  }

 @override
  Widget build(BuildContext context) {
    return RawMenuAnchor(
      controller: menuAnimator,  // Pass in the decorator
      overlayBuilder: (context, info) {
          // Use your animation controller to animate the menu
      },
      child: widget.child
    );
  }

Full example using simulations

/// Flutter code sample for a [MenuControllerDecorator] that animates a
/// [RawMenuAnchor] with a [SpringSimulation].
void main() {
  runApp(const MenuControllerDecoratorApp());
}

class _MenuAnimator extends MenuControllerDecorator {
  const _MenuAnimator({required super.menuController, required this.animationController});

  final AnimationController animationController;
  SpringSimulation get forwardSpring => SpringSimulation(
    SpringDescription.withDampingRatio(mass: 1.0, stiffness: 150, ratio: 0.7),
    animationController.value,
    1.0,
    0.0,
  );
  SpringSimulation get reverseSpring => SpringSimulation(
    SpringDescription.withDampingRatio(mass: 1.0, stiffness: 200, ratio: 0.7),
    animationController.value,
    0.0,
    0.0,
  );

  @override
  void handleMenuOpenRequest({ui.Offset? position}) {
    // Call whenComplete() rather than whenCompleteOrCancel() to avoid marking
    // the menu as opened when the [AnimationStatus] moves from forward to
    // reverse.
    animationController.animateWith(forwardSpring).whenComplete(markMenuOpened);
  }

  @override
  void handleMenuCloseRequest() {
    // Call whenComplete() rather than whenCompleteOrCancel() to avoid marking
    // the menu as closed when the [AnimationStatus] moves from reverse to
    // forward.
    animationController.animateBackWith(reverseSpring).whenComplete(markMenuClosed);
  }
}

class MenuControllerDecoratorExample extends StatefulWidget {
  const MenuControllerDecoratorExample({super.key});

  @override
  State<MenuControllerDecoratorExample> createState() => _MenuControllerDecoratorExampleState();
}

class _MenuControllerDecoratorExampleState extends State<MenuControllerDecoratorExample>
    with SingleTickerProviderStateMixin {
  late final AnimationController animationController;
  late final _MenuAnimator menuController;

  @override
  void initState() {
    super.initState();
    // Use an unbounded animation controller to allow simulations to run
    // indefinitely.
    animationController = AnimationController.unbounded(vsync: this);
    menuController = _MenuAnimator(
      menuController: MenuController(),
      animationController: animationController,
    );
  }

  @override
  void dispose() {
    animationController.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return RawMenuAnchor(
      controller: menuController,
      overlayBuilder: (BuildContext context, RawMenuOverlayInfo info) {
        // Center the menu below the anchor.
        final ui.Offset position = info.anchorRect.bottomCenter.translate(-75, 4);
        final ColorScheme colorScheme = ColorScheme.of(context);
        return Positioned(
          top: position.dy,
          left: position.dx,
          child: Semantics(
            explicitChildNodes: true,
            scopesRoute: true,
            child: ExcludeFocus(
              excluding: MenuController.maybeAnimationStatusOf(context) == AnimationStatus.reverse,
              child: TapRegion(
                groupId: info.tapRegionGroupId,
                onTapOutside: (PointerDownEvent event) {
                  menuController.close();
                },
                child: ScaleTransition(
                  scale: animationController.view,
                  child: FadeTransition(
                    opacity: animationController.drive(
                      Animatable<double>.fromCallback(
                        (double value) => ui.clampDouble(value, 0, 1),
                      ),
                    ),
                    child: Material(
                      elevation: 8,
                      clipBehavior: Clip.antiAlias,
                      borderRadius: BorderRadius.circular(16),
                      color: colorScheme.primary,
                      child: SizeTransition(
                        axisAlignment: -1,
                        sizeFactor: animationController.view,
                        fixedCrossAxisSizeFactor: 1.0,
                        child: SizedBox(
                          height: 200,
                          width: 150,
                          child: Text(
                            'ANIMATION STATUS:\n${animationController.status.name}',
                            textAlign: TextAlign.center,
                            style: TextStyle(color: colorScheme.onPrimary, fontSize: 12),
                          ),
                        ),
                      ),
                    ),
                  ),
                ),
              ),
            ),
          ),
        );
      },
      builder: (BuildContext context, MenuController menuController, Widget? child) {
        return FilledButton(
          onPressed: () {
            if (menuController.animationStatus.isForwardOrCompleted) {
              menuController.close();
            } else {
              menuController.open();
            }
          },
          child: Text(menuController.animationStatus.isForwardOrCompleted ? 'Close' : 'Open'),
        );
      },
    );
  }
}

class MenuControllerDecoratorApp extends StatelessWidget {
  const MenuControllerDecoratorApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData.from(
        useMaterial3: true,
        colorScheme: ColorScheme.fromSeed(
          seedColor: Colors.blue,
          dynamicSchemeVariant: DynamicSchemeVariant.vibrant,
        ),
      ),
      home: const Scaffold(body: Center(child: MenuControllerDecoratorExample())),
    );
  }
}

How it works/why it's complicated

Say you have this simplified setup

// Simplified version of MenuAnchor
class AnimatedMenu extends StatefulWidget {
  const AnimatedMenu({
    super.key,
    required this.userController,
  });

  // ~~ REASON FOR COMPLEXITY ~~
  // This is an external controller, passed in by a user.
  // 
  // We want to allow users to call userController.open() and have menu animate open, 
  // without giving the user access to the internal decorated controller
  final MenuController userController;

  @override
  State<AnimatedMenu> createState() => _AnimatedMenuState();
}

class _DecoratedMenuState extends State<DecoratedMenu> {
  // Wraps the userController to intercept open and close requests
  late MenuControllerDecorator _menuAnimator;

  @override
  void initState() {
    super.initState();
    animationController = AnimationController(
      duration: const Duration(milliseconds: 200),
      vsync: this,
    );
    _menuAnimator = _MenuAnimator(
      menuController: widget.userController,
    );
  }

  @override
  void didUpdateWidget(covariant DecoratedMenu oldWidget) {
    super.didUpdateWidget(oldWidget);
    if (widget.userController != oldWidget.userController) {
      _menuAnimator = _MenuAnimator(
        menuController: widget.userController,
        animationController: animationController,
      );
    }
  }

  @override
  void dispose() {
    animationController.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    // Build the menu
    return RawMenuAnchor(
      controller: _menuAnimator,
      // .. 
     )
  }
}

Changes in this PR:

I'll use menu in place of _RawMenuAnchorBaseMixin, which is the class that controls the internal state of the menu.

Before change:

userController.open() -> menu.open()

After change:
With controllers that are not animated:

userController.open() -> menu.requestOpen() -> userController._handleOpenRequest() -> menu.open()

With controllers that are animated (such as the AnimatedMenu example):

userController.open() -> menu.requestOpen() -> animatedController._handleOpenRequest() -> menu.open()

So, the important bit is that _handleOpenRequest() will be called on the controller that is passed into the anchor (animatedController in the animated example, and userController in the sync example), regardless of which controller is calling open(). _handleOpenRequest calls handleMenuOpenRequest, which allows us to customize how the menu behaves when opening.

The same sequence of methods is called in when closing, except open is replaced with closed

@marcglasberg I'm tagging you because I've seen you request this on a few threads.

If you had to change anything in the flutter/tests repo, include a link to the migration guide as per the breaking change policy.

I also fixed the grammar of 3 test names.. this may need to be split out.

~~TODO: Add a menu position test.~~

Pre-launch Checklist

I read the Contributor Guide and followed the process outlined there for submitting PRs.
I read the Tree Hygiene wiki page, which explains my responsibilities.
I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
I signed the CLA.
I listed at least one issue that this PR fixes in the description above.
I updated/added relevant documentation (doc comments with ///).
I added new tests to check the change I am making, or this PR is test-exempt.
I followed the breaking change policy and added Data Driven Fixes where supported.
[] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

justinmc · 2025-02-18T23:06:03Z

@QuncCccccc I added you as a reviewer since this seems to be related to your PR #143416.

QuncCccccc · 2025-02-18T23:10:11Z

Ah thanks for letting me know🤩!

@davidhicks980 Thanks so much for adding the animation feature🥳! That's the thing that I wanted to implement but never really finished. I will take a look when I get any chance!

davidhicks980 · 2025-02-19T01:20:58Z

@QuncCccccc No worries! This doesn't implement the material animations, but it should make it much simpler to add them without having to worry about internal menu state or changing the MenuController api.

The way the decorator works is a bit complicated, and I'm not sure whether it can be further simplified without complicating the external interface, so I'll add a summary up above for why the complexity exists and why it may be unavoidable. But, by all means, let me know if there's a better way of handling this problem, or ask clarifying questions.

QuncCccccc · 2025-02-20T21:04:23Z

Since this is related to RawMenuAnchor, I might need to ask some help from @dkwingsmt. Not super familiar with this new widget:)

dkwingsmt

Sorry for late review. Besides some minor doc suggestions (which can be addressed later), I'm mostly asking the reasoning behind the current design: What problem is this trying to fix? What's the current MenuController incapable of? Why is this new abstract class considered the better approach? What kind of customization are we expecting from app code here?

dkwingsmt · 2025-02-28T21:59:27Z