added in API level 21

Summary: Nested Classes | Constants | Methods | Inherited Methods | [Expand All]

LauncherApps

public class LauncherApps
extends Object

java.lang.Object
↳	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: ACTION_MANAGED_PROFILE_ADDED and 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
`class`	`LauncherApps.Callback` Callbacks for package changes to this and related managed profiles.
`class`	`LauncherApps.PinItemRequest` 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.
`class`	`LauncherApps.ShortcutQuery` Represents a query passed to `getShortcuts(ShortcutQuery, UserHandle)`.

Constants
`String`	`ACTION_CONFIRM_PIN_APPWIDGET` Activity Action: For the default launcher to show the confirmation dialog to create a pinned app widget.
`String`	`ACTION_CONFIRM_PIN_SHORTCUT` Activity Action: For the default launcher to show the confirmation dialog to create a pinned shortcut.
`String`	`EXTRA_PIN_ITEM_REQUEST` An extra for `ACTION_CONFIRM_PIN_SHORTCUT` & `ACTION_CONFIRM_PIN_APPWIDGET` containing a `LauncherApps.PinItemRequest` of appropriate type asked to pin.

Public methods
`List<LauncherActivityInfo>`	`getActivityList(String packageName, UserHandle user)` Retrieves a list of launchable activities that match `ACTION_MAIN` and `CATEGORY_LAUNCHER`, for a specified user.
`ApplicationInfo`	`getApplicationInfo(String packageName, int flags, UserHandle user)` Get `ApplicationInfo` for a profile
`LauncherApps.PinItemRequest`	`getPinItemRequest(Intent intent)` A helper method to extract a `LauncherApps.PinItemRequest` set to the `EXTRA_PIN_ITEM_REQUEST` extra.
`List<UserHandle>`	`getProfiles()` Return a list of profiles that the caller can access via the `LauncherApps` APIs.
`Drawable`	`getShortcutBadgedIconDrawable(ShortcutInfo shortcut, int density)` Returns the shortcut icon with badging appropriate for the profile.
`IntentSender`	`getShortcutConfigActivityIntent(LauncherActivityInfo info)` Returns an intent sender which can be used to start the configure activity for creating custom shortcuts.
`List<LauncherActivityInfo>`	`getShortcutConfigActivityList(String packageName, UserHandle user)` Retrieves a list of config activities for creating `ShortcutInfo`.
`Drawable`	`getShortcutIconDrawable(ShortcutInfo shortcut, int density)` Returns the icon for this shortcut, without any badging for the profile.
`List<ShortcutInfo>`	`getShortcuts(LauncherApps.ShortcutQuery query, UserHandle user)` Returns `ShortcutInfo`s that match `query`.
`boolean`	`hasShortcutHostPermission()` Returns whether the caller can access the shortcut information.
`boolean`	`isActivityEnabled(ComponentName component, UserHandle user)` Checks if the activity exists and it enabled for a profile.
`boolean`	`isPackageEnabled(String packageName, UserHandle user)` Checks if the package is installed and enabled for a profile.
`void`	`pinShortcuts(String packageName, List<String> shortcutIds, UserHandle user)` Pin shortcuts on a package.
`void`	`registerCallback(LauncherApps.Callback callback, Handler handler)` Registers a callback for changes to packages in current and managed profiles.
`void`	`registerCallback(LauncherApps.Callback callback)` Registers a callback for changes to packages in current and managed profiles.
`LauncherActivityInfo`	`resolveActivity(Intent intent, UserHandle user)` Returns the activity info for a given intent and user handle, if it resolves.
`void`	`startAppDetailsActivity(ComponentName component, UserHandle user, Rect sourceBounds, Bundle opts)` Starts the settings activity to show the application details for a package in the specified profile.
`void`	`startMainActivity(ComponentName component, UserHandle user, Rect sourceBounds, Bundle opts)` Starts a Main activity in the specified profile.
`void`	`startShortcut(String packageName, String shortcutId, Rect sourceBounds, Bundle startActivityOptions, UserHandle user)` Starts a shortcut.
`void`	`startShortcut(ShortcutInfo shortcut, Rect sourceBounds, Bundle startActivityOptions)` Launches a shortcut.
`void`	`unregisterCallback(LauncherApps.Callback callback)` Unregisters a callback that was previously registered.

Inherited methods

From class


  
    java.lang.Object

`Object`	`clone()` Creates and returns a copy of this object.
`boolean`	`equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void`	`finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>`	`getClass()` Returns the runtime class of this `Object`.
`int`	`hashCode()` Returns a hash code value for the object.
`final void`	`notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void`	`notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String`	`toString()` Returns a string representation of the object.
`final void`	`wait(long millis, int nanos)` Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed.
`final void`	`wait(long millis)` Causes the current thread to wait until either another thread invokes the `notify()` method or the `notifyAll()` method for this object, or a specified amount of time has elapsed.
`final void`	`wait()` Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object.

Constants

ACTION_CONFIRM_PIN_APPWIDGET

Android O Developer Preview

String ACTION_CONFIRM_PIN_APPWIDGET

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

See the requestPinAppWidget(ComponentName, Bundle, PendingIntent) javadoc for details.

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

See also:

EXTRA_PIN_ITEM_REQUEST

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

ACTION_CONFIRM_PIN_SHORTCUT

Android O Developer Preview

String ACTION_CONFIRM_PIN_SHORTCUT

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

See the ShortcutManager javadoc for details.

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

See also:

EXTRA_PIN_ITEM_REQUEST

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

EXTRA_PIN_ITEM_REQUEST

Android O Developer Preview

String EXTRA_PIN_ITEM_REQUEST

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

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

See also:

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

Public methods

getActivityList

added in API level 21

List<LauncherActivityInfo> getActivityList (String packageName, 
                UserHandle user)

Retrieves a list of launchable activities that match ACTION_MAIN and CATEGORY_LAUNCHER, for a specified user.

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.

Returns
`List<LauncherActivityInfo>`	List of launchable activities. Can be an empty list but will not be null.

getApplicationInfo

Android O Developer Preview

ApplicationInfo getApplicationInfo (String packageName, 
                int flags, 
                UserHandle user)

Get ApplicationInfo for a profile

Parameters
`packageName`	`String`: The package name of the application This value must never be `null`.
`flags`	`int`: Additional option flags `getApplicationInfo(String, int)` Value is either `0` or combination of `GET_META_DATA`, `GET_SHARED_LIBRARY_FILES`, `MATCH_UNINSTALLED_PACKAGES`, `MATCH_SYSTEM_ONLY`, `MATCH_DISABLED_COMPONENTS` or `MATCH_DISABLED_UNTIL_USED_COMPONENTS`.
`user`	`UserHandle`: The UserHandle of the profile. This value must never be `null`.

Returns
`ApplicationInfo`	An `ApplicationInfo` containing information about the package or null if the package isn't installed for the given user, or the target user is not enabled.

Throws
`PackageManager.NameNotFoundException`

getPinItemRequest

Android O Developer Preview

LauncherApps.PinItemRequest getPinItemRequest (Intent intent)

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

Parameters
`intent`	`Intent`

Returns
`LauncherApps.PinItemRequest`

getProfiles

Android O Developer Preview

List<UserHandle> getProfiles ()

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 getUserProfiles() would.

Returns
`List<UserHandle>`

getShortcutBadgedIconDrawable

added in API level 25

Drawable getShortcutBadgedIconDrawable (ShortcutInfo shortcut, 
                int density)

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
`shortcut`	`ShortcutInfo`
`density`	`int`: Optional density for the icon, or 0 to use the default density. Use

Returns
`Drawable`	A badged icon for the shortcut.

Throws
`IllegalStateException`	when the user is locked, or when the `user` user is locked or not running.

See also:

getShortcutConfigActivityIntent

Android O Developer Preview

IntentSender getShortcutConfigActivityIntent (LauncherActivityInfo info)

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 LauncherApps.PinItemRequest in onActivityResult on RESULT_OK.

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

Parameters
`info`	`LauncherActivityInfo`: a configuration activity returned by `getShortcutConfigActivityList(String, UserHandle)` This value must never be `null`.

Returns
`IntentSender`	This value may be `null`.

Throws
`IllegalStateException`	when the user is locked or not running.
`SecurityException`	if `hasShortcutHostPermission()` is false.

See also:

getShortcutConfigActivityList

Android O Developer Preview

List<LauncherActivityInfo> getShortcutConfigActivityList (String packageName, 
                UserHandle user)

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. This value may be `null`.
`user`	`UserHandle`: The UserHandle of the profile. This value must never be `null`.

Returns
`List<LauncherActivityInfo>`	List of config activities. Can be an empty list but will not be null.

See also:

getShortcutIconDrawable

added in API level 25

Drawable getShortcutIconDrawable (ShortcutInfo shortcut, 
                int density)

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
`shortcut`	`ShortcutInfo` This value must never be `null`.
`density`	`int`: The preferred density of the icon, zero for default density. Use density DPI values from `DisplayMetrics`.

Returns
`Drawable`	The drawable associated with the shortcut.

Throws
`IllegalStateException`	when the user is locked, or when the `user` user is locked or not running.

See also:

getShortcuts

added in API level 25

List<ShortcutInfo> getShortcuts (LauncherApps.ShortcutQuery query, 
                UserHandle user)

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 must never be `null`.
`user`	`UserHandle`: The UserHandle of the profile. This value must never be `null`.

Returns
`List<ShortcutInfo>`	the IDs of `ShortcutInfo`s that match the query. This value may be `null`.

Throws
`IllegalStateException`	when the user is locked, or when the `user` user is locked or not running.

See also:

ShortcutManager

hasShortcutHostPermission

added in API level 25

boolean hasShortcutHostPermission ()

Returns whether the caller can access the shortcut information.

Only the default launcher can access the shortcut information.

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.

Returns
`boolean`

Throws
`IllegalStateException`	when the user is locked.

See also:

ShortcutManager

isActivityEnabled

added in API level 21

boolean isActivityEnabled (ComponentName component, 
                UserHandle user)

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

Parameters
`component`	`ComponentName`: The activity to check.
`user`	`UserHandle`: The UserHandle of the profile.

Returns
`boolean`	true if the activity exists and is enabled.

isPackageEnabled

added in API level 21

boolean isPackageEnabled (String packageName, 
                UserHandle user)

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.

Returns
`boolean`	true if the package exists and is enabled.

pinShortcuts

added in API level 25

void pinShortcuts (String packageName, 
                List<String> shortcutIds, 
                UserHandle user)

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 must never be `null`.
`shortcutIds`	`List`: The IDs of the shortcut to be pinned. This value must never be `null`.
`user`	`UserHandle`: The UserHandle of the profile. This value must never be `null`.

Throws
`IllegalStateException`	when the user is locked, or when the `user` user is locked or not running.

See also:

ShortcutManager

registerCallback

added in API level 21

void registerCallback (LauncherApps.Callback callback, 
                Handler handler)

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

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

registerCallback

added in API level 21

void registerCallback (LauncherApps.Callback callback)

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

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

resolveActivity

added in API level 21

LauncherActivityInfo resolveActivity (Intent intent, 
                UserHandle user)

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.

Returns
`LauncherActivityInfo`	An activity info object if there is a match.

startAppDetailsActivity

added in API level 21

void startAppDetailsActivity (ComponentName component, 
                UserHandle user, 
                Rect sourceBounds, 
                Bundle opts)

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

void startMainActivity (ComponentName component, 
                UserHandle user, 
                Rect sourceBounds, 
                Bundle opts)

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

startShortcut

added in API level 25

void startShortcut (String packageName, 
                String shortcutId, 
                Rect sourceBounds, 
                Bundle startActivityOptions, 
                UserHandle user)

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 must never be `null`.
`shortcutId`	`String`: The target shortcut ID. This value must never 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 must never be `null`.

Throws
`IllegalStateException`	when the user is locked, or when the `user` user is locked or not running.
`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

void startShortcut (ShortcutInfo shortcut, 
                Rect sourceBounds, 
                Bundle startActivityOptions)

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 must never 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`.

Throws
`IllegalStateException`	when the user is locked, or when the `user` user is locked or not running.
`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

void unregisterCallback (LauncherApps.Callback callback)

Unregisters a callback that was previously registered.

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

See also:

registerCallback(Callback)

Most visited

Recently visited

Results for

LauncherApps

Summary

Nested classes

Constants

Public methods

Inherited methods

Constants

ACTION_CONFIRM_PIN_APPWIDGET

ACTION_CONFIRM_PIN_SHORTCUT

EXTRA_PIN_ITEM_REQUEST

Public methods

getActivityList

getApplicationInfo

getPinItemRequest

getProfiles

getShortcutBadgedIconDrawable

getShortcutConfigActivityIntent

getShortcutConfigActivityList

getShortcutIconDrawable

getShortcuts

hasShortcutHostPermission

isActivityEnabled

isPackageEnabled

pinShortcuts

registerCallback

registerCallback

resolveActivity

startAppDetailsActivity

startMainActivity

startShortcut

startShortcut

unregisterCallback

Classes

Exceptions