Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 9a1acc6b authored by Treehugger Robot's avatar Treehugger Robot Committed by Android (Google) Code Review
Browse files

Merge "Update documentation for Launcher Apps." into main

parents 0c43ad7b c37ee89e

core/java/android/content/pm/LauncherApps.java

+144 −46
Original line number Diff line number Diff line
@@ -29,6 +29,7 @@ import android.annotation.Nullable; 
import android.annotation.RequiresPermission;

import android.annotation.SdkConstant;

import android.annotation.SdkConstant.SdkConstantType;

import android.annotation.SuppressLint;

import android.annotation.SystemApi;

import android.annotation.SystemService;

import android.annotation.TestApi;
@@ -694,9 +695,16 @@ public class LauncherApps { 
     * <p>If the caller is running on a managed profile, it'll return only the current profile.

     * Otherwise it'll return the same list as {@link UserManager#getUserProfiles()} would.

     *

     * <p> To get hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have

     * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.

     * <p>To get hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},

     * caller should have either:</p>

     * <ul>

     * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}

     * permission</li>

     * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the

     * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>

     * </ul>

     */

    @SuppressLint("RequiresPermission")

    @RequiresPermission(conditional = true,

            anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})

    public List<UserHandle> getProfiles() {
@@ -756,15 +764,21 @@ public class LauncherApps { 
     * list.</li>

     * </ul>

     *

     * <p>If the user in question is a hidden profile

     * {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have

     * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.

     * <p>If the user in question is a hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},

     * caller should have either:</p>

     * <ul>

     * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}

     * permission</li>

     * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the

     * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>

     * </ul>

     *

     * @param packageName The specific package to query. If null, it checks all installed packages

     *            in the profile.

     * @param user The UserHandle of the profile.

     * @return List of launchable activities. Can be an empty list but will not be null.

     */

    @SuppressLint("RequiresPermission")

    @RequiresPermission(conditional = true,

            anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})

    public List<LauncherActivityInfo> getActivityList(String packageName, UserHandle user) {
@@ -806,15 +820,21 @@ public class LauncherApps { 
     * Returns information related to a user which is useful for displaying UI elements

     * to distinguish it from other users (eg, badges).

     *

     * <p>If the user in question is a hidden profile like

     * {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have

     * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.

     * <p>If the user in question is a hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},

     * caller should have either:</p>

     * <ul>

     * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}

     * permission</li>

     * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the

     * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>

     * </ul>

     *

     * @param userHandle user handle of the user for which LauncherUserInfo is requested.

     * @return the {@link LauncherUserInfo} object related to the user specified, null in case

     * the user is inaccessible.

     */

    @Nullable

    @SuppressLint("RequiresPermission")

    @FlaggedApi(Flags.FLAG_ALLOW_PRIVATE_PROFILE)

    @RequiresPermission(conditional = true,

            anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})
@@ -853,9 +873,14 @@ public class LauncherApps { 
     * </ul>

     * </p>

     *

     * <p>If the user in question is a hidden profile

     * {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have

     * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.

     * <p>If the user in question is a hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},

     * caller should have either:</p>

     * <ul>

     * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}

     * permission</li>

     * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the

     * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>

     * </ul>

     *

     * @param packageName the package for which intent sender to launch App Market Activity is

     *                    required.
@@ -864,6 +889,7 @@ public class LauncherApps { 
     *         there is no such activity.

     */

    @Nullable

    @SuppressLint("RequiresPermission")

    @FlaggedApi(Flags.FLAG_ALLOW_PRIVATE_PROFILE)

    @RequiresPermission(conditional = true,

            anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})
@@ -887,9 +913,14 @@ public class LauncherApps { 
     * <p>An empty list denotes that all system packages should be treated as pre-installed for that

     * user at creation.

     *

     * <p>If the user in question is a hidden profile like

     * {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have

     * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.

     * <p>If the user in question is a hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},

     * caller should have either:</p>

     * <ul>

     * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}

     * permission</li>

     * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the

     * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>

     * </ul>

     *

     * @param userHandle the user for which installed system packages are required.

     * @return {@link List} of {@link String}, representing the package name of the installed
@@ -897,6 +928,7 @@ public class LauncherApps { 
     */

    @FlaggedApi(Flags.FLAG_ALLOW_PRIVATE_PROFILE)

    @NonNull

    @SuppressLint("RequiresPermission")

    @RequiresPermission(conditional = true,

            anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})

    public List<String> getPreInstalledSystemPackages(@NonNull UserHandle userHandle) {
@@ -936,14 +968,20 @@ public class LauncherApps { 
     * Returns the activity info for a given intent and user handle, if it resolves. Otherwise it

     * returns null.

     *

     * <p>If the user in question is a hidden profile

     * {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have

     * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.

     * <p>If the user in question is a hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},

     * caller should have either:</p>

     * <ul>

     * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}

     * permission</li>

     * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the

     * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>

     * </ul>

     *

     * @param intent The intent to find a match for.

     * @param user The profile to look in for a match.

     * @return An activity info object if there is a match.

     */

    @SuppressLint("RequiresPermission")

    @RequiresPermission(conditional = true,

            anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})

    public LauncherActivityInfo resolveActivity(Intent intent, UserHandle user) {
@@ -995,15 +1033,21 @@ public class LauncherApps { 
    /**

     * Starts a Main activity in the specified profile.

     *

     * <p>If the user in question is a hidden profile

     * {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have

     * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.

     * <p>If the user in question is a hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},

     * caller should have either:</p>

     * <ul>

     * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}

     * permission</li>

     * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the

     * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>

     * </ul>

     *

     * @param component The ComponentName of the activity to launch

     * @param user The UserHandle of the profile

     * @param sourceBounds The Rect containing the source bounds of the clicked icon

     * @param opts Options to pass to startActivity

     */

    @SuppressLint("RequiresPermission")

    @RequiresPermission(conditional = true,

            anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})

    public void startMainActivity(ComponentName component, UserHandle user, Rect sourceBounds,
@@ -1043,15 +1087,21 @@ public class LauncherApps { 
     * Starts the settings activity to show the application details for a

     * package in the specified profile.

     *

     * <p>If the user in question is a hidden profile

     * {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have

     * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.

     * <p>If the user in question is a hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},

     * caller should have either:</p>

     * <ul>

     * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}

     * permission</li>

     * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the

     * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>

     * </ul>

     *

     * @param component The ComponentName of the package to launch settings for.

     * @param user The UserHandle of the profile

     * @param sourceBounds The Rect containing the source bounds of the clicked icon

     * @param opts Options to pass to startActivity

     */

    @SuppressLint("RequiresPermission")

    @RequiresPermission(conditional = true,

            anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})

    public void startAppDetailsActivity(ComponentName component, UserHandle user,
@@ -1165,15 +1215,21 @@ public class LauncherApps { 
    /**

     * Checks if the package is installed and enabled for a profile.

     *

     * <p>If the user in question is a hidden profile

     * {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have

     * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.

     * <p>If the user in question is a hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},

     * caller should have either:</p>

     * <ul>

     * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}

     * permission</li>

     * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the

     * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>

     * </ul>

     *

     * @param packageName The package to check.

     * @param user The UserHandle of the profile.

     *

     * @return true if the package exists and is enabled.

     */

    @SuppressLint("RequiresPermission")

    @RequiresPermission(conditional = true,

            anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})

    public boolean isPackageEnabled(String packageName, UserHandle user) {
@@ -1193,9 +1249,14 @@ public class LauncherApps { 
     * <p>The contents of this {@link Bundle} are supposed to be a contract between the suspending

     * app and the launcher.

     *

     * <p>If the user in question is a hidden profile

     * {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have

     * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.

     * <p>If the user in question is a hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},

     * caller should have either:</p>

     * <ul>

     * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}

     * permission</li>

     * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the

     * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>

     * </ul>

     *

     * <p>Note: This just returns whatever extras were provided to the system, <em>which might

     * even be {@code null}.</em>
@@ -1208,6 +1269,7 @@ public class LauncherApps { 
     * @see Callback#onPackagesSuspended(String[], UserHandle, Bundle)

     * @see PackageManager#isPackageSuspended()

     */

    @SuppressLint("RequiresPermission")

    @RequiresPermission(conditional = true,

            anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})

    public @Nullable Bundle getSuspendedPackageLauncherExtras(String packageName, UserHandle user) {
@@ -1224,14 +1286,20 @@ public class LauncherApps { 
     * could be done because the package was marked as distracting to the user via

     * {@code PackageManager.setDistractingPackageRestrictions(String[], int)}.

     *

     * <p>If the user in question is a hidden profile

     * {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have

     * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.

     * <p>If the user in question is a hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},

     * caller should have either:</p>

     * <ul>

     * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}

     * permission</li>

     * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the

     * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>

     * </ul>

     *

     * @param packageName The package for which to check.

     * @param user the {@link UserHandle} of the profile.

     * @return

     */

    @SuppressLint("RequiresPermission")

    @RequiresPermission(conditional = true,

            anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})

    public boolean shouldHideFromSuggestions(@NonNull String packageName,
@@ -1248,9 +1316,14 @@ public class LauncherApps { 
    /**

     * Returns {@link ApplicationInfo} about an application installed for a specific user profile.

     *

     * <p>If the user in question is a hidden profile

     * {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have

     * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.

     * <p>If the user in question is a hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},

     * caller should have either:</p>

     * <ul>

     * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}

     * permission</li>

     * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the

     * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>

     * </ul>

     *

     * @param packageName The package name of the application

     * @param flags Additional option flags {@link PackageManager#getApplicationInfo}
@@ -1260,6 +1333,7 @@ public class LauncherApps { 
     *         {@code null} if the package isn't installed for the given profile, or the profile

     *         isn't enabled.

     */

    @SuppressLint("RequiresPermission")

    @RequiresPermission(conditional = true,

            anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})

    public ApplicationInfo getApplicationInfo(@NonNull String packageName,
@@ -1311,15 +1385,21 @@ public class LauncherApps { 
     * <p>The activity may still not be exported, in which case {@link #startMainActivity} will

     * throw a {@link SecurityException} unless the caller has the same UID as the target app's.

     *

     * <p>If the user in question is a hidden profile

     * {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have

     * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.

     * <p>If the user in question is a hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},

     * caller should have either:</p>

     * <ul>

     * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}

     * permission</li>

     * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the

     * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>

     * </ul>

     *

     * @param component The activity to check.

     * @param user The UserHandle of the profile.

     *

     * @return true if the activity exists and is enabled.

     */

    @SuppressLint("RequiresPermission")

    @RequiresPermission(conditional = true,

            anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})

    public boolean isActivityEnabled(ComponentName component, UserHandle user) {
@@ -1881,11 +1961,17 @@ public class LauncherApps { 
     * Registers a callback for changes to packages in this user and managed profiles.

     *

     * <p>To receive callbacks for hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},

     * caller should have {@link android.app.role.RoleManager.ROLE_HOME} and either of the

     * permissions required.

     * caller should have either:</p>

     * <ul>

     * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}

     * permission</li>

     * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the

     * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>

     * </ul>

     *

     * @param callback The callback to register.

     */

    @SuppressLint("RequiresPermission")

    @RequiresPermission(conditional = true,

            anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})

    public void registerCallback(Callback callback) {
@@ -1896,12 +1982,18 @@ public class LauncherApps { 
     * Registers a callback for changes to packages in this user and managed profiles.

     *

     * <p>To receive callbacks for hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},

     * caller should have {@link android.app.role.RoleManager.ROLE_HOME} and either of the

     * permissions required.

     * caller should have either:</p>

     * <ul>

     * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES_FULL}

     * permission</li>

     * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the

     * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>

     * </ul>

     *

     * @param callback The callback to register.

     * @param handler that should be used to post callbacks on, may be null.

     */

    @SuppressLint("RequiresPermission")

    @RequiresPermission(conditional = true,

            anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})

    public void registerCallback(Callback callback, Handler handler) {
@@ -2354,12 +2446,18 @@ public class LauncherApps { 
     * package name in the app's manifest, have the android.permission.QUERY_ALL_PACKAGES, or be

     * the session owner to retrieve these details.

     *

     * <p>If the user in question is a hidden profile

     * {@link UserManager.USER_TYPE_PROFILE_PRIVATE}, caller should have

     * {@link android.app.role.RoleManager.ROLE_HOME} and either of the permissions required.

     * <p>To receive callbacks for hidden profile {@link UserManager.USER_TYPE_PROFILE_PRIVATE},

     * caller should have either:</p>

     * <ul>

     * <li>the privileged {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES}

     * permission</li>

     * <li>the normal {@link android.Manifest.permission.ACCESS_HIDDEN_PROFILES} permission and the

     * {@link android.app.role.RoleManager.ROLE_HOME} role. </li>

     * </ul>

     *

     * @see PackageInstaller#getAllSessions()

     */

    @SuppressLint("RequiresPermission")

    @RequiresPermission(conditional = true,

            anyOf = {ACCESS_HIDDEN_PROFILES_FULL, ACCESS_HIDDEN_PROFILES})

    public @NonNull List<SessionInfo> getAllPackageInstallerSessions() {