DOCSEARCHbyAlgolia
Submit Docs

Lawnchair Launcher

repository·16-dev·Indexed 11 days ago

https://github.com/lawnchairlauncher/lawnchair

An open-source Android launcher based on Launcher3 that ports Pixel Launcher features and provides deep customization, including Material 3 theming and icon pack support. The documentation covers development details for Lawnchair 16, the compatLib Quickstep module for Android 10-16, the Flowerpot ruleset format for app categorization, and AOSP dependency requirements for building the project.

Tokens
10.2K
Snippets
19
Records
54
Agent score
95%

What's inside Lawnchair

  1. Overview of the SystemUI Module

    16-dev
    The SystemUI module contains the core components required for the SystemUI application, derived from the Android upstream source code. It is organized into several submodules designed for specific purposes, such as shared helpers, utility stripping, and specialized view handling.

  2. Overview of Lawnchair 16

    16-dev

    Lawnchair is a free, open-source Android home app based on Launcher3. It ports Pixel Launcher features and provides extensive customization.

    Note for Lawnchair 16 users: This branch is currently in development and is based on Launcher3 from Android 16. Because it contains major changes from the rebase of Launcher3, it may cause crashes or break. Regular users are recommended to stay on Lawnchair 15 Beta 3.

  3. Overview of the flowerpot ruleset format

    16-dev
    Flowerpot is a compact, human-readable, line-delimited file format used for storing rules that categorize apps into folders and tabs. The format is designed to be easily parsed by code and is primarily composed of filters, with specific leading characters identifying the type of rule or metadata.

  4. What is the Lawnchair Quickstep compat module?

    16-dev

    The compatLib module is a compatibility layer designed to allow Lawnchair to integrate with Quickstep (the system component responsible for the Recents screen) across various Android versions.

    It is specifically useful when the system's Quickstep implementation does not match the expected version, such as when using tools like QuickSwitch or the legacy Lawnstep app to replace the system Recents provider. This layer ensures that Recents integration remains functional despite differences in the underlying Android implementation.

  5. Manage finish-transaction ordering for task cleanup

    16-dev

    When using bookend transitions, ensure that any necessary task cleanup occurs on the bookend's finish transaction rather than the finish transaction provided when the initial transient-launch transition was started.

    If cleanup is performed on the initial transition's finish transaction, properties on the tasks might be overwritten by the default finish transaction created by WM Core.

    Correct Ordering:

    1. Start START (Core builds finishT1 to reset state).
    2. Start BOOKEND (Core builds finishT2 to reset state).
    3. Merge BOOKEND into START.
    4. Update finish transaction properties here (on the bookend's transaction).
    5. Finish BOOKEND (Shell applies finishT1 then finishT2 in order).

  6. Use the `common` submodule for shared helper libraries

    16-dev

    The SystemUICommon module acts as a host for standalone helper libraries intended for use by other SystemUI modules.

    Usage Constraints:

    • Avoid Circular Dependencies: Do not add dependencies to other SystemUI modules within SystemUICommon. It must remain independent.
    • Organization: To maintain module structure, do not add components at the top level. Instead, place new components into specific sub-packages (e.g., systemui/common/buffer/).

  7. Key features of Lawnchair

    16-dev

    Lawnchair provides several advanced customization and integration features:

    • Material 3 Expressive theming: Follows your wallpaper and system colors.
    • At a Glance widget support: Includes integration for Smartspacer.
    • QuickSwitch support: Enables Android Recents integration on Android 10-15 (requires root).
    • Global search: Search for apps, contacts, and web results directly from the home screen.
    • Customization: Options for icon packs, fonts, and color settings.

  8. How to implement interfaces between SysUI and Shell components

    16-dev

    Because WM Shell components may run on a different thread than the main SysUI thread, you must enforce explicit interfaces to manage threading and logic isolation.

    Pattern for implementing a new feature:

    1. Define the Interface (Shell side): Create an interface (e.g., ShellFeature) that SysUI will use.
    2. Implement the Controller (Shell side): Create a controller (e.g., ShellFeatureController) that implements the interface and handles posting tasks to the main Shell thread.
    3. Inject into SysUI: Inject Optional<ShellFeature> into the SysUI application initialization.
    4. Consume in SysUI: Create a SysUI component (e.g., SysUIFeature) that depends on the ShellFeature interface.
    5. Handle Callbacks (SysUI side): When the SysUI component injects Optional<ShellFeature>, set up a callback for the Shell to call. Crucially, the callback must post to the main SysUI thread before executing logic.

  9. Identify available WMShell threads

    16-dev

    WMShell utilizes several specialized threads depending on the product configuration:

    • SysUI main thread: The standard SystemUI main thread. Accessible via the @Main annotation.
    • ShellMainThread: Used for UI and windowing-critical components. It runs with THREAD_PRIORITY_DISPLAY priority. It is only a separate thread if config_enableShellMainThread is true (e.g., on phones); otherwise, it falls back to the SysUI main thread. Its Handler/Executor is async.
    • ShellBackgroundThread: Used for long-running tasks to avoid blocking the Shell main thread. It runs with THREAD_PRIORITY_BACKGROUND but can be boosted to THREAD_PRIORITY_FOREGROUND.
    • ShellAnimationThread: Currently used for Transitions and Splitscreen animations.
    • ShellSplashScreenThread: Dedicated to splashscreen operations.

  11. How the WindowManager Shell (WMShell) is architected

    16-dev

    The WindowManager Shell (WMShell) library is designed to scale WindowManager by separating window management policy from surface presentation.

    It achieves this through a clear boundary between two components:

    1. WMCore: Responsible for the policy of managing windows.
    2. WMShell: Responsible for the presentation of surfaces.

    This separation allows developers to create windowing features tailored to different Android products and form factors (such as handhelds, TV, Auto, Arc++, and Wear) safely and easily.

  12. Avoid deadlocks when using bookend transitions with transient-launch

    16-dev

    When using a 'bookend' transition (a new transition END_T started to finalize the state after a transient-launch START_T), you must carefully manage incoming transitions to avoid deadlocks.

    Deadlocks occur if a new transition OTHER_T is queued instead of merged, causing the system to wait for a bookend transition that can never complete.

    To prevent deadlocks, you must ensure that if a bookend transition is queued or posted, you either:

    1. Preempt the bookend transition by finishing the transient-launch transition immediately.
    2. Handle the merge of the new incoming transition so it does not get queued.

    Recommended Flow:

    1. Start transient-launch transition START_T.
    2. ... (animation plays)
    3. Start bookend transition END_T.
    4. Handler receives END_T, merges it, and then finishes START_T.