Added in API level 21

LauncherApps

open class LauncherApps
kotlin.Any
   ↳ android.content.pm.LauncherApps

Class for retrieving a list of launchable activities for the current user and any associated managed profiles that are visible to the current user, which can be retrieved with getProfiles. This is mainly for use by launchers. Apps can be queried for each user profile. Since the PackageManager will not deliver package broadcasts for other profiles, you can register for package changes here.

To watch for managed profiles being added or removed, register for the following broadcasts: Intent#ACTION_MANAGED_PROFILE_ADDED and Intent#ACTION_MANAGED_PROFILE_REMOVED.

Note as of Android O, apps on a managed profile are no longer allowed to access apps on the main profile. Apps can only access profiles returned by getProfiles().

Summary

Nested classes
abstract

Callbacks for package changes to this and related managed profiles.

Represents a "pin shortcut" or a "pin appwidget" request made by an app, which is sent with an ACTION_CONFIRM_PIN_SHORTCUT or ACTION_CONFIRM_PIN_APPWIDGET intent respectively to the default launcher app.

open

Represents a query passed to getShortcuts(android.content.pm.LauncherApps.ShortcutQuery,android.os.UserHandle).

Constants
static String

Activity Action: For the default launcher to show the confirmation dialog to create a pinned app widget.

static String

Activity Action: For the default launcher to show the confirmation dialog to create a pinned shortcut.

static String

An extra for ACTION_CONFIRM_PIN_SHORTCUT & ACTION_CONFIRM_PIN_APPWIDGET containing a PinItemRequest of appropriate type asked to pin.

Public methods
open MutableList<LauncherActivityInfo!>!
getActivityList(packageName: String!, user: UserHandle!)

Retrieves a list of activities that specify Intent#ACTION_MAIN and Intent#CATEGORY_LAUNCHER, across all apps, for a specified user.

open MutableList<PackageInstaller.SessionInfo!>

Return list of all known install sessions in this user and managed profiles, regardless of the installer.

open ApplicationInfo!
getApplicationInfo(packageName: String, flags: Int, user: UserHandle)

Returns ApplicationInfo about an application installed for a specific user profile.

open LauncherApps.PinItemRequest!

A helper method to extract a PinItemRequest set to the EXTRA_PIN_ITEM_REQUEST extra.

open MutableList<UserHandle!>!

Return a list of profiles that the caller can access via the LauncherApps APIs.

open Drawable!

Returns the shortcut icon with badging appropriate for the profile.

open IntentSender?

Returns an intent sender which can be used to start the configure activity for creating custom shortcuts.

open MutableList<LauncherActivityInfo!>!

Retrieves a list of config activities for creating ShortcutInfo.

open Drawable!

Returns the icon for this shortcut, without any badging for the profile.

open PendingIntent?
getShortcutIntent(packageName: String, shortcutId: String, opts: Bundle?, user: UserHandle)

Returns PendingIntent associated with specified shortcut.

open MutableList<ShortcutInfo!>?

Returns ShortcutInfos that match query.

open Bundle?

Gets the launcher extras supplied to the system when the given package was suspended via PackageManager#setPackagesSuspended(String[], boolean, PersistableBundle, PersistableBundle, String).

open Boolean

Returns whether the caller can access the shortcut information.

open Boolean

Checks if the activity exists and it enabled for a profile.

open Boolean
isPackageEnabled(packageName: String!, user: UserHandle!)

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

open Unit
pinShortcuts(packageName: String, shortcutIds: MutableList<String!>, user: UserHandle)

Pin shortcuts on a package.

open Unit

Registers a callback for changes to packages in this user and managed profiles.

open Unit

Registers a callback for changes to packages in this user and managed profiles.

open Unit

Register a callback to watch for session lifecycle events in this user and managed profiles.

open LauncherActivityInfo!
resolveActivity(intent: Intent!, user: UserHandle!)

Returns the activity info for a given intent and user handle, if it resolves.

open Boolean

Returns whether a package should be hidden from suggestions to the user.

open Unit
startAppDetailsActivity(component: ComponentName!, user: UserHandle!, sourceBounds: Rect!, opts: Bundle!)

Starts the settings activity to show the application details for a package in the specified profile.

open Unit
startMainActivity(component: ComponentName!, user: UserHandle!, sourceBounds: Rect!, opts: Bundle!)

Starts a Main activity in the specified profile.

open Unit

Starts an activity to show the details of the specified session.

open Unit
startShortcut(packageName: String, shortcutId: String, sourceBounds: Rect?, startActivityOptions: Bundle?, user: UserHandle)

Starts a shortcut.

open Unit
startShortcut(shortcut: ShortcutInfo, sourceBounds: Rect?, startActivityOptions: Bundle?)

Launches a shortcut.

open Unit

Unregisters a callback that was previously registered.

open Unit

Unregisters a callback that was previously registered.

Constants

ACTION_CONFIRM_PIN_APPWIDGET

Added in API level 26
static val ACTION_CONFIRM_PIN_APPWIDGET: String

Activity Action: For the default launcher to show the confirmation dialog to create a pinned app widget.

See the android.appwidget.AppWidgetManager#requestPinAppWidget javadoc for details.

Use getPinItemRequest(android.content.Intent) to get a PinItemRequest object, and call PinItemRequest#accept(Bundle) if the user accepts. If the user doesn't accept, no further action is required.

Value: "android.content.pm.action.CONFIRM_PIN_APPWIDGET"

ACTION_CONFIRM_PIN_SHORTCUT

Added in API level 26
static val ACTION_CONFIRM_PIN_SHORTCUT: String

Activity Action: For the default launcher to show the confirmation dialog to create a pinned shortcut.

See the ShortcutManager javadoc for details.

Use getPinItemRequest(android.content.Intent) to get a PinItemRequest object, and call PinItemRequest#accept(Bundle) if the user accepts. If the user doesn't accept, no further action is required.

Value: "android.content.pm.action.CONFIRM_PIN_SHORTCUT"

EXTRA_PIN_ITEM_REQUEST

Added in API level 26
static val EXTRA_PIN_ITEM_REQUEST: String

An extra for ACTION_CONFIRM_PIN_SHORTCUT & ACTION_CONFIRM_PIN_APPWIDGET containing a PinItemRequest of appropriate type asked to pin.

A helper function getPinItemRequest(android.content.Intent) can be used instead of using this constant directly.

Value: "android.content.pm.extra.PIN_ITEM_REQUEST"

Public methods

getActivityList

Added in API level 21
open fun getActivityList(
    packageName: String!,
    user: UserHandle!
): MutableList<LauncherActivityInfo!>!

Retrieves a list of activities that specify Intent#ACTION_MAIN and Intent#CATEGORY_LAUNCHER, across all apps, for a specified user. If an app doesn't have any activities that specify ACTION_MAIN or CATEGORY_LAUNCHER, the system adds a synthesized activity to the list. This synthesized activity represents the app's details page within system settings.

Note: It's possible for system apps, such as app stores, to prevent the system from adding synthesized activities to the returned list.

As of Android Q, at least one of the app's activities or synthesized activities appears in the returned list unless the app satisfies at least one of the following conditions:

  • The app is a system app.
  • The app doesn't request any permissions.
  • The app doesn't have a launcher activity that is enabled by default. A launcher activity has an intent containing the ACTION_MAIN action and the CATEGORY_LAUNCHER category.

Additionally, the system hides synthesized activities for some or all apps in the following enterprise-related cases:

  • If the device is a fully managed device, no synthesized activities for any app appear in the returned list.
  • If the current user has a work profile, no synthesized activities for the user's work apps appear in the returned list.
Parameters
packageName String!: The specific package to query. If null, it checks all installed packages in the profile.
user UserHandle!: The UserHandle of the profile.
Return
MutableList<LauncherActivityInfo!>! List of launchable activities. Can be an empty list but will not be null.

getAllPackageInstallerSessions

Added in API level 29
open fun getAllPackageInstallerSessions(): MutableList<PackageInstaller.SessionInfo!>

Return list of all known install sessions in this user and managed profiles, regardless of the installer. Callers need to either declare <queries> element with the specific package name in the app's manifest, have the android.permission.QUERY_ALL_PACKAGES, or be the session owner to retrieve these details.

Return
MutableList<PackageInstaller.SessionInfo!> This value cannot be null.

getApplicationInfo

Added in API level 26
open fun getApplicationInfo(
    packageName: String,
    flags: Int,
    user: UserHandle
): ApplicationInfo!

Returns ApplicationInfo about an application installed for a specific user profile.

Parameters
packageName String: The package name of the application This value cannot be null.
flags Int: Additional option flags android.content.pm.PackageManager#getApplicationInfo Value is either 0 or a combination of android.content.pm.PackageManager#GET_META_DATA, android.content.pm.PackageManager#GET_SHARED_LIBRARY_FILES, android.content.pm.PackageManager#MATCH_UNINSTALLED_PACKAGES, android.content.pm.PackageManager#MATCH_SYSTEM_ONLY, android.content.pm.PackageManager.MATCH_DEBUG_TRIAGED_MISSING, android.content.pm.PackageManager#MATCH_DISABLED_COMPONENTS, android.content.pm.PackageManager#MATCH_DISABLED_UNTIL_USED_COMPONENTS, android.content.pm.PackageManager.MATCH_INSTANT, android.content.pm.PackageManager.MATCH_STATIC_SHARED_AND_SDK_LIBRARIES, android.content.pm.PackageManager#GET_DISABLED_UNTIL_USED_COMPONENTS, android.content.pm.PackageManager#GET_UNINSTALLED_PACKAGES, android.content.pm.PackageManager.MATCH_HIDDEN_UNTIL_INSTALLED_COMPONENTS, android.content.pm.PackageManager#MATCH_APEX, and android.content.pm.PackageManager.MATCH_ARCHIVED_PACKAGES
user UserHandle: The UserHandle of the profile. This value cannot be null.
Return
ApplicationInfo! ApplicationInfo containing information about the package. Returns null if the package isn't installed for the given profile, or the profile isn't enabled.

getPinItemRequest

Added in API level 26
open fun getPinItemRequest(intent: Intent!): LauncherApps.PinItemRequest!

A helper method to extract a PinItemRequest set to the EXTRA_PIN_ITEM_REQUEST extra.

getProfiles

Added in API level 26
open fun getProfiles(): MutableList<UserHandle!>!

Return a list of profiles that the caller can access via the LauncherApps APIs.

If the caller is running on a managed profile, it'll return only the current profile. Otherwise it'll return the same list as UserManager#getUserProfiles() would.

getShortcutBadgedIconDrawable

Added in API level 25
open fun getShortcutBadgedIconDrawable(
    shortcut: ShortcutInfo!,
    density: Int
): Drawable!

Returns the shortcut icon with badging appropriate for the profile.

The calling launcher application must be allowed to access the shortcut information, as defined in hasShortcutHostPermission().

Parameters
density Int: Optional density for the icon, or 0 to use the default density. Use
Return
Drawable! A badged icon for the shortcut.
Exceptions
java.lang.IllegalStateException when the user is locked, or when the user user is locked or not running.

getShortcutConfigActivityIntent

Added in API level 26
open fun getShortcutConfigActivityIntent(info: LauncherActivityInfo): IntentSender?

Returns an intent sender which can be used to start the configure activity for creating custom shortcuts. Use this method if the provider is in another profile as you are not allowed to start an activity in another profile.

The caller should receive PinItemRequest in onActivityResult on android.app.Activity#RESULT_OK.

Callers must be allowed to access the shortcut information, as defined in hasShortcutHostPermission().

Parameters
info LauncherActivityInfo: a configuration activity returned by getShortcutConfigActivityList This value cannot be null.
Return
IntentSender? This value may be null.
Exceptions
java.lang.IllegalStateException when the user is locked or not running.
java.lang.SecurityException if hasShortcutHostPermission() is false.

getShortcutConfigActivityList

Added in API level 26
open fun getShortcutConfigActivityList(
    packageName: String?,
    user: UserHandle
): MutableList<LauncherActivityInfo!>!

Retrieves a list of config activities for creating ShortcutInfo.

Parameters
packageName String?: The specific package to query. If null, it checks all installed packages in the profile.
user UserHandle: The UserHandle of the profile. This value cannot be null.
Return
MutableList<LauncherActivityInfo!>! List of config activities. Can be an empty list but will not be null.

getShortcutIconDrawable

Added in API level 25
open fun getShortcutIconDrawable(
    shortcut: ShortcutInfo,
    density: Int
): Drawable!

Returns the icon for this shortcut, without any badging for the profile.

The calling launcher application must be allowed to access the shortcut information, as defined in hasShortcutHostPermission().

Parameters
density Int: The preferred density of the icon, zero for default density. Use density DPI values from DisplayMetrics.
shortcut ShortcutInfo: This value cannot be null.
Return
Drawable! The drawable associated with the shortcut.
Exceptions
java.lang.IllegalStateException when the user is locked, or when the user user is locked or not running.

getShortcutIntent

Added in API level 31
open fun getShortcutIntent(
    packageName: String,
    shortcutId: String,
    opts: Bundle?,
    user: UserHandle
): PendingIntent?

Returns PendingIntent associated with specified shortcut.

Parameters
packageName String: The packageName of the shortcut This value cannot be null.
shortcutId String: The id of the shortcut This value cannot be null.
opts Bundle?: This parameter is no longer supported This value may be null.
user UserHandle: The UserHandle of the profile This value cannot be null.
Return
PendingIntent? This value may be null.

getShortcuts

Added in API level 25
open fun getShortcuts(
    query: LauncherApps.ShortcutQuery,
    user: UserHandle
): MutableList<ShortcutInfo!>?

Returns ShortcutInfos that match query.

Callers must be allowed to access the shortcut information, as defined in hasShortcutHostPermission().

Parameters
query LauncherApps.ShortcutQuery: result includes shortcuts matching this query. This value cannot be null.
user UserHandle: The UserHandle of the profile. This value cannot be null.
Return
MutableList<ShortcutInfo!>? the IDs of ShortcutInfos that match the query. This value may be null.
Exceptions
java.lang.IllegalStateException when the user is locked, or when the user user is locked or not running.

getSuspendedPackageLauncherExtras

Added in API level 28
open fun getSuspendedPackageLauncherExtras(
    packageName: String!,
    user: UserHandle!
): Bundle?

Gets the launcher extras supplied to the system when the given package was suspended via PackageManager#setPackagesSuspended(String[], boolean, PersistableBundle, PersistableBundle, String).

The contents of this Bundle are supposed to be a contract between the suspending app and the launcher.

Note: This just returns whatever extras were provided to the system, which might even be null.

Parameters
packageName String!: The package for which to fetch the launcher extras.
user UserHandle!: The UserHandle of the profile.
Return
Bundle? A Bundle of launcher extras. Or null if the package is not currently suspended.

hasShortcutHostPermission

Added in API level 25
open fun hasShortcutHostPermission(): Boolean

Returns whether the caller can access the shortcut information. Access is currently available to:

  • The current launcher (or default launcher if there is no set current launcher).
  • The currently active voice interaction service.

Note when this method returns false, it may be a temporary situation because the user is trying a new launcher application. The user may decide to change the default launcher back to the calling application again, so even if a launcher application loses this permission, it does not have to purge pinned shortcut information. If the calling launcher application contains pinned shortcuts, they will still work, even though the caller no longer has the shortcut host permission.

Exceptions
java.lang.IllegalStateException when the user is locked.

isActivityEnabled

Added in API level 21
open fun isActivityEnabled(
    component: ComponentName!,
    user: UserHandle!
): Boolean

Checks if the activity exists and it enabled for a profile.

The activity may still not be exported, in which case startMainActivity will throw a SecurityException unless the caller has the same UID as the target app's.

Parameters
component ComponentName!: The activity to check.
user UserHandle!: The UserHandle of the profile.
Return
Boolean true if the activity exists and is enabled.

isPackageEnabled

Added in API level 21
open fun isPackageEnabled(
    packageName: String!,
    user: UserHandle!
): Boolean

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

Parameters
packageName String!: The package to check.
user UserHandle!: The UserHandle of the profile.
Return
Boolean true if the package exists and is enabled.

pinShortcuts

Added in API level 25
open fun pinShortcuts(
    packageName: String,
    shortcutIds: MutableList<String!>,
    user: UserHandle
): Unit

Pin shortcuts on a package.

This API is NOT cumulative; this will replace all pinned shortcuts for the package. However, different launchers may have different set of pinned shortcuts.

The calling launcher application must be allowed to access the shortcut information, as defined in hasShortcutHostPermission().

Parameters
packageName String: The target package name. This value cannot be null.
shortcutIds MutableList<String!>: The IDs of the shortcut to be pinned. This value cannot be null.
user UserHandle: The UserHandle of the profile. This value cannot be null.
Exceptions
java.lang.IllegalStateException when the user is locked, or when the user user is locked or not running.

registerCallback

Added in API level 21
open fun registerCallback(callback: LauncherApps.Callback!): Unit

Registers a callback for changes to packages in this user and managed profiles.

Parameters
callback LauncherApps.Callback!: The callback to register.

registerCallback

Added in API level 21
open fun registerCallback(
    callback: LauncherApps.Callback!,
    handler: Handler!
): Unit

Registers a callback for changes to packages in this user and managed profiles.

Parameters
callback LauncherApps.Callback!: The callback to register.
handler Handler!: that should be used to post callbacks on, may be null.

registerPackageInstallerSessionCallback

Added in API level 29
open fun registerPackageInstallerSessionCallback(
    executor: Executor,
    callback: PackageInstaller.SessionCallback
): Unit

Register a callback to watch for session lifecycle events in this user and managed profiles. Callers need to either declare <queries> element with the specific package name in the app's manifest, have the android.permission.QUERY_ALL_PACKAGES, or be the session owner to watch for these events.

Parameters
callback PackageInstaller.SessionCallback: The callback to register. This value cannot be null.
executor Executor: Executor to handle the callbacks, cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.

resolveActivity

Added in API level 21
open fun resolveActivity(
    intent: Intent!,
    user: UserHandle!
): LauncherActivityInfo!

Returns the activity info for a given intent and user handle, if it resolves. Otherwise it returns null.

Parameters
intent Intent!: The intent to find a match for.
user UserHandle!: The profile to look in for a match.
Return
LauncherActivityInfo! An activity info object if there is a match.

shouldHideFromSuggestions

Added in API level 29
open fun shouldHideFromSuggestions(
    packageName: String,
    user: UserHandle
): Boolean

Returns whether a package should be hidden from suggestions to the user. Currently, this could be done because the package was marked as distracting to the user via PackageManager.setDistractingPackageRestrictions(String[], int).

Parameters
packageName String: The package for which to check. This value cannot be null.
user UserHandle: the UserHandle of the profile. This value cannot be null.
Return
Boolean

startAppDetailsActivity

Added in API level 21
open fun startAppDetailsActivity(
    component: ComponentName!,
    user: UserHandle!,
    sourceBounds: Rect!,
    opts: Bundle!
): Unit

Starts the settings activity to show the application details for a package in the specified profile.

Parameters
component ComponentName!: The ComponentName of the package to launch settings for.
user UserHandle!: The UserHandle of the profile
sourceBounds Rect!: The Rect containing the source bounds of the clicked icon
opts Bundle!: Options to pass to startActivity

startMainActivity

Added in API level 21
open fun startMainActivity(
    component: ComponentName!,
    user: UserHandle!,
    sourceBounds: Rect!,
    opts: Bundle!
): Unit

Starts a Main activity in the specified profile.

Parameters
component ComponentName!: The ComponentName of the activity to launch
user UserHandle!: The UserHandle of the profile
sourceBounds Rect!: The Rect containing the source bounds of the clicked icon
opts Bundle!: Options to pass to startActivity

startPackageInstallerSessionDetailsActivity

Added in API level 29
open fun startPackageInstallerSessionDetailsActivity(
    sessionInfo: PackageInstaller.SessionInfo,
    sourceBounds: Rect?,
    opts: Bundle?
): Unit

Starts an activity to show the details of the specified session.

Parameters
sessionInfo PackageInstaller.SessionInfo: The SessionInfo of the session This value cannot be null.
sourceBounds Rect?: The Rect containing the source bounds of the clicked icon This value may be null.
opts Bundle?: Options to pass to startActivity This value may be null.

startShortcut

Added in API level 25
open fun startShortcut(
    packageName: String,
    shortcutId: String,
    sourceBounds: Rect?,
    startActivityOptions: Bundle?,
    user: UserHandle
): Unit

Starts a shortcut.

The calling launcher application must be allowed to access the shortcut information, as defined in hasShortcutHostPermission().

Parameters
packageName String: The target shortcut package name. This value cannot be null.
shortcutId String: The target shortcut ID. This value cannot be null.
sourceBounds Rect?: The Rect containing the source bounds of the clicked icon. This value may be null.
startActivityOptions Bundle?: Options to pass to startActivity. This value may be null.
user UserHandle: The UserHandle of the profile. This value cannot be null.
Exceptions
java.lang.IllegalStateException when the user is locked, or when the user user is locked or not running.
android.content.ActivityNotFoundException failed to start shortcut. (e.g. the shortcut no longer exists, is disabled, the intent receiver activity doesn't exist, etc)

startShortcut

Added in API level 25
open fun startShortcut(
    shortcut: ShortcutInfo,
    sourceBounds: Rect?,
    startActivityOptions: Bundle?
): Unit

Launches a shortcut.

The calling launcher application must be allowed to access the shortcut information, as defined in hasShortcutHostPermission().

Parameters
shortcut ShortcutInfo: The target shortcut. This value cannot be null.
sourceBounds Rect?: The Rect containing the source bounds of the clicked icon. This value may be null.
startActivityOptions Bundle?: Options to pass to startActivity. This value may be null.
Exceptions
java.lang.IllegalStateException when the user is locked, or when the user user is locked or not running.
android.content.ActivityNotFoundException failed to start shortcut. (e.g. the shortcut no longer exists, is disabled, the intent receiver activity doesn't exist, etc)

unregisterCallback

Added in API level 21
open fun unregisterCallback(callback: LauncherApps.Callback!): Unit

Unregisters a callback that was previously registered.

Parameters
callback LauncherApps.Callback!: The callback to unregister.

unregisterPackageInstallerSessionCallback

Added in API level 29
open fun unregisterPackageInstallerSessionCallback(callback: PackageInstaller.SessionCallback): Unit

Unregisters a callback that was previously registered.

Parameters
callback PackageInstaller.SessionCallback: The callback to unregister. This value cannot be null.