contextMenuBuilder property

Builds the text selection toolbar when requested by the user.

The context menu is built when EditableTextState.showToolbar is called, typically by one of the callbacks installed by the widget created by TextSelectionGestureDetectorBuilder.buildGestureDetector. The widget returned by contextMenuBuilder is passed to a ContextMenuController.

If no callback is provided, no context menu will be shown.

The EditableTextContextMenuBuilder signature used by the contextMenuBuilder callback has two parameters, the BuildContext of the EditableText and the EditableTextState of the EditableText.

The EditableTextState has two properties that are especially useful when building the widgets for the context menu:

EditableTextState.contextMenuAnchors specifies the desired anchor position for the context menu.
EditableTextState.contextMenuButtonItems represents the buttons that should typically be built for this widget (e.g. cut, copy, paste).

The TextSelectionToolbarLayoutDelegate class may be particularly useful in honoring the preferred anchor positions.

For backwards compatibility, when EditableText.selectionControls is set to an object that does not mix in TextSelectionHandleControls, contextMenuBuilder is ignored and the TextSelectionControls.buildToolbar method is used instead.

{@tool dartpad} This example shows how to customize the menu, in this case by keeping the default buttons for the platform but modifying their appearance.

** See code in examples/api/lib/material/context_menu/editable_text_toolbar_builder.0.dart ** {@end-tool}

{@tool dartpad} This example shows how to show a custom button only when an email address is currently selected.

** See code in examples/api/lib/material/context_menu/editable_text_toolbar_builder.1.dart ** {@end-tool}

See also:

AdaptiveTextSelectionToolbar, which builds the default text selection toolbar for the current platform, but allows customization of the buttons.
AdaptiveTextSelectionToolbar.getAdaptiveButtons, which builds the button Widgets for the current platform given ContextMenuButtonItems.
BrowserContextMenu, which allows the browser's context menu on web to be disabled and Flutter-rendered context menus to appear.

If not provided, will build a default menu based on the ambient ThemeData.platform.

This example shows how to build a custom context menu for any selected content in a SelectionArea.

To see it in action, copy and run this code snippet on DartPad.

// This example demonstrates a custom context menu in non-editable text using
// SelectionArea.

import 'package:flutter/foundation.dart';
import 'package:flutter/services.dart';
import 'package:material_ui/material_ui.dart';

void main() => runApp(const SelectableRegionToolbarBuilderExampleApp());

const String text =
    'I am some text inside of SelectionArea. Right click (desktop) or long press (mobile) me to show the customized context menu.';

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

  @override
  State<SelectableRegionToolbarBuilderExampleApp> createState() =>
      _SelectableRegionToolbarBuilderExampleAppState();
}

class _SelectableRegionToolbarBuilderExampleAppState
    extends State<SelectableRegionToolbarBuilderExampleApp> {
  void _showDialog(BuildContext context) {
    Navigator.of(context).push(
      DialogRoute<void>(
        context: context,
        builder: (BuildContext context) =>
            const AlertDialog(title: Text('You clicked print!')),
      ),
    );
  }

  @override
  void initState() {
    super.initState();
    // On web, disable the browser's context menu since this example uses a custom
    // Flutter-rendered context menu.
    if (kIsWeb) {
      BrowserContextMenu.disableContextMenu();
    }
  }

  @override
  void dispose() {
    if (kIsWeb) {
      BrowserContextMenu.enableContextMenu();
    }
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('Context menu anywhere')),
        body: Center(
          child: SizedBox(
            width: 200.0,
            child: SelectionArea(
              contextMenuBuilder:
                  (
                    BuildContext context,
                    SelectableRegionState selectableRegionState,
                  ) {
                    return AdaptiveTextSelectionToolbar.buttonItems(
                      anchors: selectableRegionState.contextMenuAnchors,
                      buttonItems: <ContextMenuButtonItem>[
                        ...selectableRegionState.contextMenuButtonItems,
                        ContextMenuButtonItem(
                          onPressed: () {
                            ContextMenuController.removeAny();
                            _showDialog(context);
                          },
                          label: 'Print',
                        ),
                      ],
                    );
                  },
              child: ListView(
                children: const <Widget>[SizedBox(height: 20.0), Text(text)],
              ),
            ),
          ),
        ),
      ),
    );
  }
}

Implementation

SelectionArea class