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

Instances of this class must be obtained using Context.getSystemService(Class) with the argument LauncherApps.class or Context.getSystemService(String) with the argument Context.LAUNCHER_APPS_SERVICE.

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)

Returns ApplicationInfo about an application installed for a specific user 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

added in API level 26
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:

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

ACTION_CONFIRM_PIN_SHORTCUT

added in API level 26
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

added in API level 26
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

added in API level 26
ApplicationInfo getApplicationInfo (String packageName, 
                int flags, 
                UserHandle user)

Returns ApplicationInfo about an application installed for a specific user 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 ApplicationInfo containing information about the package. Returns null if the package isn't installed for the given profile, or the profile isn't enabled.

Throws
PackageManager.NameNotFoundException

getPinItemRequest

added in API level 26
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

added in API level 26
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

added in API level 26
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

added in API level 26
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.

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

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.

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:

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:

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

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Follow Google Developers on WeChat

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

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 short survey?
Help us improve the Android developer experience.
(Sep 2017 survey)