# launcher3-dev/launcher3 architecture

> Architecture diagram of the GitHub repository launcher3-dev/launcher3, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/launcher3-dev/launcher3
- Repository: https://github.com/launcher3-dev/launcher3

## Overview

##### Project context
- This is an Android-only launcher app (Launcher3).
- We’re focusing on the “widget” submodule under src/com/android/launcher3/widget.
- This submodule provides everything needed to display, add, preview and manage home-screen widgets.

1. WidgetCell
2. WidgetCellPreview
3. WidgetImageView
4. BaseLauncherAppWidgetHostView
5. NavigableAppWidgetHostView
6. PendingAppWidgetHostView
7. AddItemWidgetsBottomSheet
8. BaseWidgetSheet
9. LauncherWidgetHolder

1. WidgetManagerHelper
2. WidgetSections
3. WidgetItemComparator

1. LauncherAppWidgetHost
2. LauncherAppWidgetProviderInfo

1. DatabaseWidgetPreviewLoader
2. LocalColorExtractor

1. WidgetAddFlowHandler
2. WidgetInflater (Kotlin)
3. WidgetHostViewLoader
4. PendingItemDragHelper
5. PendingAddWidgetInfo
6. PendingAddShortcutInfo
7. WidgetSections

- Flow:
AddItemWidgetsBottomSheet
→ invokes WidgetSections to list widget categories
→ feeds selected PendingAddWidgetInfo / PendingAddShortcutInfo to WidgetAddFlowHandler
→ WidgetAddFlowHandler
- uses WidgetManagerHelper to resolve provider info
- uses LauncherAppWidgetHost & ProviderInfo model to allocate IDs
- inflates the host view via WidgetHostViewLoader & WidgetInflater
- displays in BaseWidgetSheet / BottomSheet

- Preview & coloring:
WidgetCell → WidgetCellPreview → DatabaseWidgetPreviewLoader

- Host & navigation:
LauncherAppWidgetHost
→ instantiates BaseLauncherAppWidgetHostView
→ can navigate internally via NavigableAppWidgetHostView
→ handles pending via PendingAppWidgetHostView

- Sorting & organization:
WidgetSections groups by category
WidgetItemComparator orders items within a section

##### Details to capture
- Explicitly show PendingAddWidgetInfo and PendingAddShortcutInfo feeding into WidgetAddFlowHandler.
- LauncherAppWidgetHost interacting with provider info model.
- DatabaseWidgetPreviewLoader’s relationship to LocalColorExtractor and WidgetImageView.
- WidgetSections as the entry point for the sheet’s content grouping.

##### Summary
– Identify components (as above),
– Label everything clearly.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "UI Containers & Views"
        WC["WidgetCell"]:::ui
        WCP["WidgetCellPreview"]:::ui
        WIV["WidgetImageView"]:::ui
        BLH["BaseLauncherAppWidgetHostView"]:::ui
        NAW["NavigableAppWidgetHostView"]:::ui
        PAW["PendingAppWidgetHostView"]:::ui
        AIBS["AddItemWidgetsBottomSheet"]:::ui
        BWS["BaseWidgetSheet"]:::ui
        LWH["LauncherWidgetHolder"]:::ui
    end

    subgraph "Managers & Helpers"
        WMH["WidgetManagerHelper"]:::mgr
        WSect["WidgetSections"]:::mgr
        WIC["WidgetItemComparator"]:::mgr
    end

    subgraph "Hosts & Providers"
        LAWH["LauncherAppWidgetHost"]:::host
        LAPI["LauncherAppWidgetProviderInfo"]:::host
    end

    subgraph "Loaders & Models"
        DBPL["DatabaseWidgetPreviewLoader"]:::loader
        LCE["LocalColorExtractor"]:::loader
    end

    subgraph "Flow Controllers"
        WAFH["WidgetAddFlowHandler"]:::flow
        WI["WidgetInflater"]:::flow
        WHVL["WidgetHostViewLoader"]:::flow
        PIDH["PendingItemDragHelper"]:::flow
        PAWI["PendingAddWidgetInfo"]:::flow
        PASI["PendingAddShortcutInfo"]:::flow
    end

    %% Add flow
    AIBS -->|"invokes"| WSect
    AIBS -->|"feeds selected"| PAWI
    AIBS -->|"feeds selected"| PASI
    PAWI -->|"to"| WAFH
    PASI -->|"to"| WAFH
    WAFH -->|"uses"| WMH
    WAFH -->|"uses"| LAWH
    WAFH -->|"inflates via"| WHVL
    WHVL -->|"calls"| WI
    WAFH -->|"displays in"| BWS

    %% Preview & coloring
    WC -->|"renders preview"| WCP
    WCP -->|"loads from"| DBPL
    DBPL -.->|"extracts colors"| LCE
    LCE -.->|"colors"| WIV

    %% Host & navigation
    LAWH -->|"instantiates"| BLH
    BLH -->|"navigates"| NAW
    BLH -->|"handles pending"| PAW

    %% Sorting & organization
    WSect -->|"groups by category"| WSect
    WSect -->|"orders using"| WIC

    %% Click Events
    click WC "https://github.com/launcher3-dev/launcher3/blob/main/src/com/android/launcher3/widget/WidgetCell.java"
    click WCP "https://github.com/launcher3-dev/launcher3/blob/main/src/com/android/launcher3/widget/WidgetCellPreview.java"
    click WIV "https://github.com/launcher3-dev/launcher3/blob/main/src/com/android/launcher3/widget/WidgetImageView.java"
    click BLH "https://github.com/launcher3-dev/launcher3/blob/main/src/com/android/launcher3/widget/BaseLauncherAppWidgetHostView.java"
    click NAW "https://github.com/launcher3-dev/launcher3/blob/main/src/com/android/launcher3/widget/NavigableAppWidgetHostView.java"
    click PAW "https://github.com/launcher3-dev/launcher3/blob/main/src/com/android/launcher3/widget/PendingAppWidgetHostView.java"
    click AIBS "https://github.com/launcher3-dev/launcher3/blob/main/src/com/android/launcher3/widget/AddItemWidgetsBottomSheet.java"
    click BWS "https://github.com/launcher3-dev/launcher3/blob/main/src/com/android/launcher3/widget/BaseWidgetSheet.java"
    click LWH "https://github.com/launcher3-dev/launcher3/blob/main/src/com/android/launcher3/widget/LauncherWidgetHolder.java"
    click WMH "https://github.com/launcher3-dev/launcher3/blob/main/src/com/android/launcher3/widget/WidgetManagerHelper.java"
    click WSect "https://github.com/launcher3-dev/launcher3/blob/main/src/com/android/launcher3/widget/WidgetSections.java"
    click WIC "https://github.com/launcher3-dev/launcher3/blob/main/src/com/android/launcher3/widget/WidgetItemComparator.java"
    click LAWH "https://github.com/launcher3-dev/launcher3/blob/main/src/com/android/launcher3/widget/LauncherAppWidgetHost.java"
    click LAPI "https://github.com/launcher3-dev/launcher3/blob/main/src/com/android/launcher3/widget/LauncherAppWidgetProviderInfo.java"
    click DBPL "https://github.com/launcher3-dev/launcher3/blob/main/src/com/android/launcher3/widget/DatabaseWidgetPreviewLoader.java"
    click LCE "https://github.com/launcher3-dev/launcher3/blob/main/src/com/android/launcher3/widget/LocalColorExtractor.java"
    click WAFH "https://github.com/launcher3-dev/launcher3/blob/main/src/com/android/launcher3/widget/WidgetAddFlowHandler.java"
    click WI "https://github.com/launcher3-dev/launcher3/blob/main/src/com/android/launcher3/widget/WidgetInflater.kt"
    click WHVL "https://github.com/launcher3-dev/launcher3/blob/main/src/com/android/launcher3/widget/WidgetHostViewLoader.java"
    click PIDH "https://github.com/launcher3-dev/launcher3/blob/main/src/com/android/launcher3/widget/PendingItemDragHelper.java"
    click PAWI "https://github.com/launcher3-dev/launcher3/blob/main/src/com/android/launcher3/widget/PendingAddWidgetInfo.java"
    click PASI "https://github.com/launcher3-dev/launcher3/blob/main/src/com/android/launcher3/widget/PendingAddShortcutInfo.java"

    %% Styles
    classDef ui fill:#add8e6,stroke:#333,stroke-width:1px;
    classDef mgr fill:#90ee90,stroke:#333,stroke-width:1px;
    classDef host fill:#ffa500,stroke:#333,stroke-width:1px;
    classDef loader fill:#ffff99,stroke:#333,stroke-width:1px;
    classDef flow fill:#dda0dd,stroke:#333,stroke-width:1px;
```
