Skip to content

Most visited

Recently visited

navigation

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 ShortcutInfos 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

Constants

ACTION_CONFIRM_PIN_APPWIDGET

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, 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:

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

ACTION_CONFIRM_PIN_SHORTCUT

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:

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

EXTRA_PIN_ITEM_REQUEST

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

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

Get ApplicationInfo for a profile

Parameters
packageName String: The package name of the application
flags int: Additional option flags getApplicationInfo(String, int)
user UserHandle: The UserHandle of the profile.
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.

getPinItemRequest

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

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

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)
Returns
IntentSender
Throws
IllegalStateException when the user is locked or not running.
SecurityException if hasShortcutHostPermission() is false.

See also:

getShortcutConfigActivityList

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.
user UserHandle: The UserHandle of the profile.
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
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.
user UserHandle: The UserHandle of the profile.
Returns
List<ShortcutInfo> the IDs of ShortcutInfos that match the query.
Throws
IllegalStateException when the user is locked, or when the user user is locked or not running.

See also:

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:

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.
shortcutIds List: The IDs of the shortcut to be pinned.
user UserHandle: The UserHandle of the profile.
Throws
IllegalStateException when the user is locked, or when the user user is locked or not running.

See also:

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.
shortcutId String: The target shortcut ID.
sourceBounds Rect: The Rect containing the source bounds of the clicked icon.
startActivityOptions Bundle: Options to pass to startActivity.
user UserHandle: The UserHandle of the profile.
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.
sourceBounds Rect: The Rect containing the source bounds of the clicked icon.
startActivityOptions Bundle: Options to pass to startActivity.
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:

This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a one-minute survey?
Help us improve Android tools and documentation.