feat: ContextMenu control

[ndonkoHenri]

Fix #1804

Example

import flet as ft


async def main(page: ft.Page):
    # on web, disable default browser context menu
    if page.web:
        await page.browser_context_menu.disable()

    def handle_item_click(e: ft.Event[ft.PopupMenuItem]):
        action = e.control.content
        page.show_dialog(ft.SnackBar(content=f"Item '{action}' selected."))

    page.add(
        ft.ContextMenu(
            primary_items=[
                ft.PopupMenuItem(content="Primary 1", on_click=handle_item_click),
                ft.PopupMenuItem(content="Primary 2", on_click=handle_item_click),
            ],
            primary_trigger=ft.ContextMenuTrigger.DOWN,
            secondary_items=[
                ft.PopupMenuItem(content="Secondary 1", on_click=handle_item_click),
                ft.PopupMenuItem(content="Secondary 2", on_click=handle_item_click),
            ],
            secondary_trigger=ft.ContextMenuTrigger.DOWN,
            tertiary_items=[
                ft.PopupMenuItem(content="Tertiary 1", on_click=handle_item_click),
                ft.PopupMenuItem(content="Tertiary 2", on_click=handle_item_click),
            ],
            tertiary_trigger=ft.ContextMenuTrigger.DOWN,
            on_select=lambda e: print(f"Selected item: {e.item.content}"),
            on_dismiss=lambda e: print("Menu dismissed"),
            expand=True,
            content=ft.Container(
                expand=True,
                bgcolor=ft.Colors.BLUE,
                alignment=ft.Alignment.CENTER,
                border_radius=ft.BorderRadius.all(12),
                content=ft.Text("Left/middle/right click to open a context menu."),
            ),
        ),
    )

ft.run(main)

Summary by Sourcery

Implement a full‐featured ContextMenu control in Flet with multi‐button triggers, event handling, and programmatic API, while refactoring popup menu entry logic, standardizing documentation code samples, and adding relevant docs and integration tests.

New Features:

• Add ContextMenu control with support for primary/secondary/tertiary triggers, items, select and dismiss events
• Implement programmatic opening and custom trigger handling for ContextMenu in Python and Flutter packages
• Introduce ContextMenuTrigger enum and ContextMenuSelectEvent/ContextMenuDismissEvent types

Enhancements:

• Extract popup menu entry construction into a shared buildPopupMenuEntries utility in Dart
• Standardize and improve example snippets and docstring formatting across multiple controls (e.g. scrollable_control, page methods, context)
• Refine scroll_to API defaults and documentation for ScrollableControl

Documentation:

• Add mkdocs entries and markdown pages for ContextMenu and its associated event and trigger types
• Include new context menu usage examples in documentation (triggers, programmatic open, custom trigger)

Tests:

• Add Python integration tests and golden screenshot tests for ContextMenu control, including programmatic and trigger-based scenarios
• Rename existing example tests for clarity in test_card and test_expansion_tile

[sourcery-ai]

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

[Copilot]

Pull Request Overview

This PR introduces a new ContextMenu control to the Flet framework, allowing developers to display custom context menus on mouse interactions. The implementation includes support for different mouse buttons (primary, secondary, tertiary), configurable trigger modes (down, long press), and programmatic menu opening.

• Adds ContextMenu control with support for mouse button-specific menus and triggers
• Refactors popup menu building logic into a shared utility function
• Updates documentation with improved formatting and consistency across multiple files

Reviewed Changes

Copilot reviewed 26 out of 31 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
sdk/python/packages/flet/src/flet/controls/material/context_menu.py	New control implementation with event classes and trigger modes
packages/flet/lib/src/controls/context_menu.dart	Flutter implementation handling gesture detection and menu display
packages/flet/lib/src/utils/popup_menu.dart	Extracted shared popup menu building logic
packages/flet/lib/src/controls/popup_menu_button.dart	Refactored to use shared popup menu utility
sdk/python/packages/flet/src/flet/__init__.py	Exports for new ContextMenu classes
sdk/python/packages/flet/mkdocs.yml	Documentation configuration entries
Various test and example files	Integration tests and usage examples
Documentation files	Improved formatting and consistency in docstrings

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cloudflare-workers-and-pages]

Deploying flet-docs with    Cloudflare Pages

Latest commit:	0be6055
Status:	✅  Deploy successful!
Preview URL:	https://4e1dd58b.flet-docs.pages.dev
Branch Preview URL:	https://context-menu-popup.flet-docs.pages.dev

View logs