builder property

CupertinoContextMenuBuilder builder
final

A function that returns a widget to be used alternatively from child.

The widget returned by the function will be shown at all times: when the CupertinoContextMenu is closed, when it is in the middle of opening, and when it is fully open. This will overwrite the default animation that matches the behavior of an iOS 16.0 context menu.

This builder can be used instead of the child when the intended child has a property that would conflict with the default animation, such as a border radius or a shadow, or if a more custom animation is needed.

In addition to the current BuildContext, the function is also called with an Animation. The complete animation goes from 0 to 1 when the CupertinoContextMenu opens, and from 1 to 0 when it closes, and it can be used to animate the widget in sync with this opening and closing.

The animation works in two stages. The first happens on press and hold of the widget from 0 to animationOpensAt, and the second stage for when the widget fully opens up to the menu, from animationOpensAt to 1.

Below is an example of using builder to show an image tile setup to be opened in the default way to match a native iOS 16.0 app. The behavior will match what will happen if the simple child image was passed as just the child parameter, instead of builder. This can be manipulated to add more customizability to the widget's animation.
link
CupertinoContextMenu.builder(
  actions: <Widget>[
    CupertinoContextMenuAction(
      child: const Text('Action one'),
      onPressed: () {},
    ),
  ],
  builder:(BuildContext context, Animation<double> animation) {
    final Animation<BorderRadius?> borderRadiusAnimation = BorderRadiusTween(
      begin: BorderRadius.circular(0.0),
      end: BorderRadius.circular(CupertinoContextMenu.kOpenBorderRadius),
    ).animate(
      CurvedAnimation(
        parent: animation,
        curve: Interval(
          CupertinoContextMenu.animationOpensAt,
          1.0,
        ),
      ),
     );

    final Animation<Decoration> boxDecorationAnimation = DecorationTween(
      begin: const BoxDecoration(
       color: Color(0xFFFFFFFF),
       boxShadow: <BoxShadow>[],
      ),
      end: const BoxDecoration(
       color: Color(0xFFFFFFFF),
       boxShadow: CupertinoContextMenu.kEndBoxShadow,
      ),
     ).animate(
       CurvedAnimation(
        parent: animation,
        curve: Interval(
          0.0,
          CupertinoContextMenu.animationOpensAt,
        ),
      ),
    );

    return Container(
      decoration:
        animation.value < CupertinoContextMenu.animationOpensAt ? boxDecorationAnimation.value : null,
      child: FittedBox(
        fit: BoxFit.cover,
        child: ClipRRect(
          borderRadius: borderRadiusAnimation.value ?? BorderRadius.circular(0.0),
          child: SizedBox(
            height: 150,
            width: 150,
            child: Image.network('https://flutter.github.io/assets-for-api-docs/assets/widgets/owl-2.jpg'),
          ),
        ),
      ),
    );
  },
)

Additionally below is an example of a real world use case for builder.

If a widget is passed to the child parameter with properties that conflict with the default animation, in this case the border radius, unwanted behaviors can arise. Here a boxed shadow will wrap the widget as it is expanded. To handle this, a more custom animation and widget can be passed to the builder, using values exposed by CupertinoContextMenu, like CupertinoContextMenu.kEndBoxShadow, to match the native iOS animation as close as desired.

link

To create a local project with this code sample, run:
flutter create --sample=cupertino.CupertinoContextMenu.builder.2 mysample

Implementation

final CupertinoContextMenuBuilder builder;