From 8b3494ad0dbfc928ee6cc6909773e4d57a492258 Mon Sep 17 00:00:00 2001
From: Stefan Andonian <andonian@google.com>
Date: Thu, 29 May 2025 14:53:00 -0700
Subject: [PATCH] Add Documentation for LauncherProvider's Preferred Methods.

This will make it easier for both the Cross OEM developers and also for
others to be able to use these APIs and figure out why their home screen
data is not showing up properly.

Bug: 379378706
Test: EXEMPT comment
Flag: EXEMPT comment
Change-Id: If25bb9d394cc90bb7bd074f4d3d6244dad22818c
---
 .../android/launcher3/LauncherProvider.java   | 52 +++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/src/com/android/launcher3/LauncherProvider.java b/src/com/android/launcher3/LauncherProvider.java
index e61519f058..5cc135664c 100644
--- a/src/com/android/launcher3/LauncherProvider.java
+++ b/src/com/android/launcher3/LauncherProvider.java
@@ -46,6 +46,58 @@ import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.ExecutionException;
 import java.util.function.ToIntFunction;
 
+/**
+ * This provider facilitates the import and export of home screen metadata within the
+ * Launcher's database. This includes managing shortcut placement, launch intents, and labels.
+ * Each row in the Launcher3 database corresponds to a single item on the workspace (often
+ * referred to as "favorites").
+ *
+ * <p>Only applications installed on the system partition or those possessing the platform's
+ * signature can access this provider.
+ *
+ * <p>After data insertion into the Launcher's database, a row may be deleted during Launcher
+ * startup if any of these conditions are true. This list is not exhaustive:
+ * <ul>
+ * <li>Missing or invalid launch intent: This includes a null intent, one without a target
+ * package, or one referencing a non-existent activity.</li>
+ * <li>When an app previously installed doesn't exist or fails to restore properly.</li>
+ * <li>If ShortcutManager/WidgetManager haven't finished restoring by the time Launcher loads</li>
+ * <li>If the App Store hasn't finished restoring when Launcher starts loading.</li>
+ * <li>The item is linked to a profile that no longer exists (e.g., a deleted work profile).</li>
+ * <li>A widget's metadata specifies an invalid height or width.</li>
+ * <li>Incorrect item container: For instance, widgets can only be on the desktop or hotseat<li>
+ * <li>If the launcher is restoring, but the item isn't flagged as restoring/installing.</li>
+ * <li>If a widget fails to inflate within AppWidgetManagerService for any reason.</li>
+ * <li>When items in the database occupy the same or overlapping positions.</li>
+ * </ul>
+ *
+ * <p>Although query, bulkInsert, and insert methods are available, their direct use is not
+ * recommended. Instead, prefer the XML-based insertion methods accessible via the
+ * {@code call()} method. This preference is due to several reasons, including:
+ * <ul>
+ * <li>The insert methods can can lead to unpredictable behavior if invoked while Launcher
+ * is in the process of loading.</li>
+ * <li>The XML approach allows for custom tags which can be ingested for proprietary variants
+ * of workspace items.</li>
+ * <li>The XML method clears old data and inserts new data as a single, atomic action. Direct
+ * Delete/Insert usage requires at least 2 binder calls that are not atomic.</li>
+ * </ul>
+ *
+ * <p>It's important to note that the XML format has non-obvious and strict requirements. For
+ * instance:
+ * <ul>
+ * <li>The Launcher uses the "screen" value to determine hot seat placement order.</li>
+ * <li>Conversely, for items within a folder, the rank db column dictates their placement
+ * order.</li>
+ * <li>When an item is on the top-level workspace (i.e., not in the hot seat), the "screen"
+ * value signifies its workspace page.</li>
+ * </ul>
+ *
+ * <p>During a launcher restore, a grid migration might occur, either due to user preference or
+ * design updates. This migration can cause items to be repositioned or moved to different pages,
+ * depending on the old and new grid sizes. Therefore, precise placement cannot be guaranteed
+ * in all situations.
+ */
 public class LauncherProvider extends ContentProvider {
     private static final String TAG = "LauncherProvider";