[osamalzabidi]

Description

This PR adds a new extension package, flet-quick-actions, which wraps Flutter's quick_actions package as an ft.Service. It enables Flet apps on Android and iOS to set, update, and clear home-screen quick actions (the shortcuts shown when the user long-presses the app icon), and to listen for taps on those shortcuts, including the action that launched the app.

Motivation: Flet has no way today to integrate with OS-level shortcuts. This is a natural companion to the existing Flet services extensions and follows the same ft.Service + FletService pattern.

Test code

import flet as ft
from flet_quick_actions import QuickActions, ShortcutItem


def main(page: ft.Page):
    status = ft.Text("no action set")
    qa = QuickActions()

    def on_action(e: ft.ControlEvent):
        # Fires on both warm start (app in background) and cold start
        # (app launched by tapping a shortcut).
        status.value = e.data
        page.update()

    qa.on_action = on_action

    async def install(_):
        await qa.set_shortcuts(
            [
                ShortcutItem(
                    type="action_one",
                    localized_title="Action one",
                    localized_subtitle="Action one subtitle",
                    icon="AppIcon",        # iOS asset name
                ),
                ShortcutItem(
                    type="action_two",
                    localized_title="Action two",
                    icon="ic_launcher",    # Android drawable name
                ),
            ]
        )
        status.value = "actions ready"
        page.update()

    async def clear(_):
        await qa.clear_shortcuts()
        status.value = "shortcuts cleared"
        page.update()

    page.add(
        status,
        ft.Row(
            [
                ft.FilledButton("Install shortcuts", on_click=install),
                ft.OutlinedButton("Clear", on_click=clear),
            ]
        ),
    )

ft.run(main)

Manual verification steps:

1. flet run -d android (or -d ios) on a physical device with a signed build.
2. Tap "Install shortcuts".
3. Background the app.
4. Long-press the app icon => verify "Action one" and "Action two" appear.
5. Tap "Action one" => app resumes, status text becomes action_one.
6. Kill the app entirely; launch it by tapping "Action two" from the home-screen menu => app opens, status text becomes action_two (cold-start path).
7. Tap "Clear" => shortcuts disappear from the launcher.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

Checklist

• I signed the CLA.
• I have performed a self-review of my own code.
• My code follows the style guidelines of this project.
• I have commented my code, particularly in hard-to-understand areas.
• My changes generate no new warnings.
• New and existing tests pass locally with my changes.
• I have made corresponding documentation changes, if applicable.
• I have added changelog entries for user-facing changes, if applicable.
• I have updated release guide pages and website/sidebars.yml for breaking changes, removals, and deprecations, if applicable.

Screenshots

Default Shortcuts	Updated Shortcuts	Cleared
Action one & Action two	New Message & Search	No shortcuts installed

Additional details

Summary by Sourcery

Add mobile home-screen quick actions support to Flet applications.

New Features:

• Add the flet-quick-actions service for managing Android and iOS home-screen shortcuts and handling shortcut launches, including cold starts.

Enhancements:

• Integrate the new service package into the Python workspace and expose its Flutter extension implementation.

Documentation:

• Document the Quick Actions service, platform support, installation, usage, and ShortcutItem API.

Chores:

• Add a Quick Actions example application demonstrating shortcut installation, clearing, and action handling.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook