# Print output for @column tags ?>
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:
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()
.
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 |
class |
LauncherApps.ShortcutQuery
Represents a query passed to |
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 |
Public methods | |
---|---|
List<LauncherActivityInfo>
|
getActivityList(String packageName, UserHandle user)
Retrieves a list of activities that specify |
List<PackageInstaller.SessionInfo>
|
getAllPackageInstallerSessions()
Return list of all known install sessions in this user and managed profiles, regardless of the installer. |
ApplicationInfo
|
getApplicationInfo(String packageName, int flags, UserHandle user)
Returns |
LauncherApps.PinItemRequest
|
getPinItemRequest(Intent intent)
A helper method to extract a |
List<UserHandle>
|
getProfiles()
Return a list of profiles that the caller can access via the |
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 |
Drawable
|
getShortcutIconDrawable(ShortcutInfo shortcut, int density)
Returns the icon for this shortcut, without any badging for the profile. |
PendingIntent
|
getShortcutIntent(String packageName, String shortcutId, Bundle opts, UserHandle user)
Returns PendingIntent associated with specified shortcut. |
List<ShortcutInfo>
|
getShortcuts(LauncherApps.ShortcutQuery query, UserHandle user)
Returns |
Bundle
|
getSuspendedPackageLauncherExtras(String packageName, UserHandle user)
Gets the launcher extras supplied to the system when the given package was suspended via
|
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)
Registers a callback for changes to packages in this user and managed profiles. |
void
|
registerCallback(LauncherApps.Callback callback, Handler handler)
Registers a callback for changes to packages in this user and managed profiles. |
void
|
registerPackageInstallerSessionCallback(Executor executor, PackageInstaller.SessionCallback callback)
Register a callback to watch for session lifecycle events in this user and managed profiles. |
LauncherActivityInfo
|
resolveActivity(Intent intent, UserHandle user)
Returns the activity info for a given intent and user handle, if it resolves. |
boolean
|
shouldHideFromSuggestions(String packageName, UserHandle user)
Returns whether a package should be hidden from suggestions to the user. |
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
|
startPackageInstallerSessionDetailsActivity(PackageInstaller.SessionInfo sessionInfo, Rect sourceBounds, Bundle opts)
Starts an activity to show the details of the specified session. |
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. |
void
|
unregisterPackageInstallerSessionCallback(PackageInstaller.SessionCallback callback)
Unregisters a callback that was previously registered. |
Inherited methods | |
---|---|
public static final String ACTION_CONFIRM_PIN_APPWIDGET
Activity Action: For the default launcher to show the confirmation dialog to create a pinned app widget.
See the AppWidgetManager.requestPinAppWidget(ComponentName, Bundle, PendingIntent)
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.
See also:
Constant Value: "android.content.pm.action.CONFIRM_PIN_APPWIDGET"
public static final 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(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.
See also:
Constant Value: "android.content.pm.action.CONFIRM_PIN_SHORTCUT"
public static final String EXTRA_PIN_ITEM_REQUEST
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.
Constant Value: "android.content.pm.extra.PIN_ITEM_REQUEST"
public List<LauncherActivityInfo> getActivityList (String packageName, UserHandle user)
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:
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:
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. |
public List<PackageInstaller.SessionInfo> getAllPackageInstallerSessions ()
Return list of all known install sessions in this user and managed profiles, regardless of the installer.
Returns | |
---|---|
List<PackageInstaller.SessionInfo> |
This value cannot be null . |
See also:
public 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 cannot be null . |
flags |
int : Additional option flags PackageManager#getApplicationInfo
Value is either 0 or a combination of PackageManager.GET_META_DATA , PackageManager.GET_SHARED_LIBRARY_FILES , PackageManager.MATCH_UNINSTALLED_PACKAGES , PackageManager.MATCH_SYSTEM_ONLY , android.content.pm.PackageManager.MATCH_DEBUG_TRIAGED_MISSING, PackageManager.MATCH_DISABLED_COMPONENTS , PackageManager.MATCH_DISABLED_UNTIL_USED_COMPONENTS , android.content.pm.PackageManager.MATCH_INSTANT, android.content.pm.PackageManager.MATCH_STATIC_SHARED_LIBRARIES, PackageManager.GET_DISABLED_UNTIL_USED_COMPONENTS , PackageManager.GET_UNINSTALLED_PACKAGES , android.content.pm.PackageManager.MATCH_HIDDEN_UNTIL_INSTALLED_COMPONENTS, and PackageManager.MATCH_APEX |
user |
UserHandle : The UserHandle of the profile.
This value cannot 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 |
public LauncherApps.PinItemRequest getPinItemRequest (Intent intent)
A helper method to extract a PinItemRequest
set to
the EXTRA_PIN_ITEM_REQUEST
extra.
Parameters | |
---|---|
intent |
Intent |
Returns | |
---|---|
LauncherApps.PinItemRequest |
public 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 UserManager#getUserProfiles()
would.
Returns | |
---|---|
List<UserHandle> |
public 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. |
public 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 PinItemRequest
in onActivityResult on
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(String, UserHandle)
This value cannot be null . |
Returns | |
---|---|
IntentSender |
This value may be null . |
Throws | |
---|---|
IllegalStateException |
when the user is locked or not running. |
SecurityException |
if hasShortcutHostPermission() is false. |
public 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 cannot be null . |
Returns | |
---|---|
List<LauncherActivityInfo> |
List of config activities. Can be an empty list but will not be null. |
public 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 cannot 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. |
public PendingIntent getShortcutIntent (String packageName, String shortcutId, Bundle opts, UserHandle user)
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 . |
Returns | |
---|---|
PendingIntent |
This value may be null . |
public List<ShortcutInfo> getShortcuts (LauncherApps.ShortcutQuery query, UserHandle user)
Returns ShortcutInfo
s 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 . |
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:
public Bundle getSuspendedPackageLauncherExtras (String packageName, UserHandle user)
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. |
Returns | |
---|---|
Bundle |
A Bundle of launcher extras. Or null if the package is not currently
suspended. |
public boolean hasShortcutHostPermission ()
Returns whether the caller can access the shortcut information. Access is currently available to:
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:
public boolean isActivityEnabled (ComponentName component, UserHandle user)
Checks if the activity exists and it enabled for a profile.
The activity may still not be exported, in which case startMainActivity(ComponentName, UserHandle, Rect, Bundle)
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. |
Returns | |
---|---|
boolean |
true if the activity exists and is enabled. |
public 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. |
public 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 cannot be null . |
shortcutIds |
List : 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 . |
Throws | |
---|---|
IllegalStateException |
when the user is locked, or when the user user
is locked or not running. |
See also:
public void registerCallback (LauncherApps.Callback callback)
Registers a callback for changes to packages in this user and managed profiles.
Parameters | |
---|---|
callback |
LauncherApps.Callback : The callback to register. |
public void registerCallback (LauncherApps.Callback callback, Handler handler)
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. |
public void registerPackageInstallerSessionCallback (Executor executor, PackageInstaller.SessionCallback callback)
Register a callback to watch for session lifecycle events in this user and managed profiles.
Parameters | |
---|---|
executor |
Executor : Executor to handle the callbacks, cannot be null.
This value 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() .
To dispatch events through a shared thread pool, you can use
AsyncTask#THREAD_POOL_EXECUTOR . |
callback |
PackageInstaller.SessionCallback : The callback to register.
This value cannot be null . |
public 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. |
public boolean shouldHideFromSuggestions (String packageName, UserHandle user)
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 . |
Returns | |
---|---|
boolean |
public 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 |
public 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 |
public void startPackageInstallerSessionDetailsActivity (PackageInstaller.SessionInfo sessionInfo, Rect sourceBounds, Bundle opts)
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 . |
public 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 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 . |
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) |
public 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 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 . |
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) |
public void unregisterCallback (LauncherApps.Callback callback)
Unregisters a callback that was previously registered.
Parameters | |
---|---|
callback |
LauncherApps.Callback : The callback to unregister. |
See also:
public void unregisterPackageInstallerSessionCallback (PackageInstaller.SessionCallback callback)
Unregisters a callback that was previously registered.
Parameters | |
---|---|
callback |
PackageInstaller.SessionCallback : The callback to unregister.
This value cannot be null . |