# Print output for @column tags ?>
public
class
AppWidgetManager
extends Object
java.lang.Object | |
↳ | android.appwidget.AppWidgetManager |
Updates AppWidget state; gets information about installed AppWidget providers and other AppWidget related state.
For more information about creating app widgets, read the App Widgets developer guide.
PackageManager#FEATURE_APP_WIDGETS
feature which can be detected using PackageManager.hasSystemFeature(String)
.
Constants | |
---|---|
String |
ACTION_APPWIDGET_BIND
Activity action to launch from your |
String |
ACTION_APPWIDGET_CONFIGURE
Sent when it is time to configure your AppWidget while it is being added to a host. |
String |
ACTION_APPWIDGET_DELETED
Sent when an instance of an AppWidget is deleted from its host. |
String |
ACTION_APPWIDGET_DISABLED
Sent when the last AppWidget of this provider is removed from the last host. |
String |
ACTION_APPWIDGET_ENABLED
Sent when an instance of an AppWidget is added to a host for the first time. |
String |
ACTION_APPWIDGET_HOST_RESTORED
Sent to widget hosts after AppWidget state related to the host has been restored from backup. |
String |
ACTION_APPWIDGET_OPTIONS_CHANGED
Sent when the custom extras for an AppWidget change. |
String |
ACTION_APPWIDGET_PICK
Activity action to launch from your |
String |
ACTION_APPWIDGET_RESTORED
Sent to an |
String |
ACTION_APPWIDGET_UPDATE
Sent when it is time to update your AppWidget. |
String |
EXTRA_APPWIDGET_ID
An intent extra (int) that contains one appWidgetId. |
String |
EXTRA_APPWIDGET_IDS
An intent extra that contains multiple appWidgetIds. |
String |
EXTRA_APPWIDGET_OLD_IDS
An intent extra that contains multiple appWidgetIds. |
String |
EXTRA_APPWIDGET_OPTIONS
An intent extra which points to a bundle of extra information for a particular widget id. |
String |
EXTRA_APPWIDGET_PREVIEW
An extra that can be passed to
|
String |
EXTRA_APPWIDGET_PROVIDER
An intent extra that contains the component name of a AppWidget provider. |
String |
EXTRA_APPWIDGET_PROVIDER_PROFILE
An intent extra that contains the user handle of the profile under which an AppWidget provider is registered. |
String |
EXTRA_CUSTOM_EXTRAS
An intent extra to pass to the AppWidget picker containing a |
String |
EXTRA_CUSTOM_INFO
An intent extra to pass to the AppWidget picker containing a |
String |
EXTRA_HOST_ID
An intent extra attached to the |
int |
INVALID_APPWIDGET_ID
A sentinel value that the AppWidget manager will never return as a appWidgetId. |
String |
META_DATA_APPWIDGET_PROVIDER
Field for the manifest meta-data tag. |
String |
OPTION_APPWIDGET_HOST_CATEGORY
A bundle extra that hints to the AppWidgetProvider the category of host that owns this this widget. |
String |
OPTION_APPWIDGET_MAX_HEIGHT
A bundle extra (int) that contains the upper bound on the current width, in dips, of a widget instance. |
String |
OPTION_APPWIDGET_MAX_WIDTH
A bundle extra (int) that contains the upper bound on the current width, in dips, of a widget instance. |
String |
OPTION_APPWIDGET_MIN_HEIGHT
A bundle extra (int) that contains the lower bound on the current height, in dips, of a widget instance. |
String |
OPTION_APPWIDGET_MIN_WIDTH
A bundle extra (int) that contains the lower bound on the current width, in dips, of a widget instance. |
String |
OPTION_APPWIDGET_RESTORE_COMPLETED
A bundle extra (boolean) that contains whether or not an app has finished restoring a widget. |
Public methods | |
---|---|
boolean
|
bindAppWidgetIdIfAllowed(int appWidgetId, ComponentName provider)
Set the component for a given appWidgetId. |
boolean
|
bindAppWidgetIdIfAllowed(int appWidgetId, UserHandle user, ComponentName provider, Bundle options)
Set the provider for a given appWidgetId if the caller has a permission. |
boolean
|
bindAppWidgetIdIfAllowed(int appWidgetId, ComponentName provider, Bundle options)
Set the component for a given appWidgetId. |
int[]
|
getAppWidgetIds(ComponentName provider)
Get the list of appWidgetIds that have been bound to the given AppWidget provider. |
AppWidgetProviderInfo
|
getAppWidgetInfo(int appWidgetId)
Get the available info about the AppWidget. |
Bundle
|
getAppWidgetOptions(int appWidgetId)
Get the extras associated with a given widget instance. |
List<AppWidgetProviderInfo>
|
getInstalledProviders()
Return a list of the AppWidget providers that are currently installed. |
List<AppWidgetProviderInfo>
|
getInstalledProvidersForPackage(String packageName, UserHandle profile)
Gets the AppWidget providers for the given package and user profile. |
List<AppWidgetProviderInfo>
|
getInstalledProvidersForProfile(UserHandle profile)
Gets the AppWidget providers for the given user profile. |
static
AppWidgetManager
|
getInstance(Context context)
Get the AppWidgetManager instance to use for the supplied |
boolean
|
isRequestPinAppWidgetSupported()
Return |
void
|
notifyAppWidgetViewDataChanged(int appWidgetId, int viewId)
Notifies the specified collection view in the specified AppWidget instance to invalidate its data. |
void
|
notifyAppWidgetViewDataChanged(int[] appWidgetIds, int viewId)
Notifies the specified collection view in all the specified AppWidget instances to invalidate their data. |
void
|
partiallyUpdateAppWidget(int appWidgetId, RemoteViews views)
Perform an incremental update or command on the widget specified by appWidgetId. |
void
|
partiallyUpdateAppWidget(int[] appWidgetIds, RemoteViews views)
Perform an incremental update or command on the widget(s) specified by appWidgetIds. |
boolean
|
requestPinAppWidget(ComponentName provider, Bundle extras, PendingIntent successCallback)
Request to pin an app widget on the current launcher. |
void
|
updateAppWidget(ComponentName provider, RemoteViews views)
Set the RemoteViews to use for all AppWidget instances for the supplied AppWidget provider. |
void
|
updateAppWidget(int[] appWidgetIds, RemoteViews views)
Set the RemoteViews to use for the specified appWidgetIds. |
void
|
updateAppWidget(int appWidgetId, RemoteViews views)
Set the RemoteViews to use for the specified appWidgetId. |
void
|
updateAppWidgetOptions(int appWidgetId, Bundle options)
Update the extras for a given widget instance. |
void
|
updateAppWidgetProviderInfo(ComponentName provider, String metaDataKey)
Updates the info for the supplied AppWidget provider. |
Inherited methods | |
---|---|
public static final String ACTION_APPWIDGET_BIND
Activity action to launch from your AppWidgetHost
activity when you want to bind
an AppWidget to display and bindAppWidgetIdIfAllowed returns false.
You must supply the following extras:
EXTRA_APPWIDGET_ID |
A newly allocated appWidgetId, which will be bound to the AppWidget provider you provide. |
EXTRA_APPWIDGET_PROVIDER |
The BroadcastReceiver that will be the AppWidget provider for this AppWidget. |
EXTRA_APPWIDGET_PROVIDER_PROFILE |
An optional handle to a user profile under which runs the provider for this AppWidget. |
The system will respond with an onActivityResult call with the following extras in the intent:
EXTRA_APPWIDGET_ID |
The appWidgetId that you supplied in the original intent. |
When you receive the result from the AppWidget bind activity, if the resultCode is
Activity.RESULT_OK
, the AppWidget has been bound. You should then
check the AppWidgetProviderInfo for the returned AppWidget, and if it has one, launch its
configuration activity. If Activity.RESULT_CANCELED
is returned, you
should delete the appWidgetId.
See also:
Constant Value: "android.appwidget.action.APPWIDGET_BIND"
public static final String ACTION_APPWIDGET_CONFIGURE
Sent when it is time to configure your AppWidget while it is being added to a host.
This action is not sent as a broadcast to the AppWidget provider, but as a startActivity
to the activity specified in the AppWidgetProviderInfo
.
The intent will contain the following extras:
EXTRA_APPWIDGET_ID |
The appWidgetId to configure. |
If you return Activity.RESULT_OK
using
Activity.setResult()
, the AppWidget will be added,
and you will receive an ACTION_APPWIDGET_UPDATE
broadcast for this AppWidget.
If you return Activity.RESULT_CANCELED
, the host will cancel the add
and not display this AppWidget, and you will receive a ACTION_APPWIDGET_DELETED
broadcast.
Constant Value: "android.appwidget.action.APPWIDGET_CONFIGURE"
public static final String ACTION_APPWIDGET_DELETED
Sent when an instance of an AppWidget is deleted from its host.
This is a protected intent that can only be sent by the system.
Constant Value: "android.appwidget.action.APPWIDGET_DELETED"
public static final String ACTION_APPWIDGET_DISABLED
Sent when the last AppWidget of this provider is removed from the last host.
This is a protected intent that can only be sent by the system.
Constant Value: "android.appwidget.action.APPWIDGET_DISABLED"
public static final String ACTION_APPWIDGET_ENABLED
Sent when an instance of an AppWidget is added to a host for the first time. This broadcast is sent at boot time if there is a AppWidgetHost installed with an instance for this provider.
This is a protected intent that can only be sent by the system.
Constant Value: "android.appwidget.action.APPWIDGET_ENABLED"
public static final String ACTION_APPWIDGET_HOST_RESTORED
Sent to widget hosts after AppWidget state related to the host has been restored from backup. The intent contains information about how to translate AppWidget ids from the restored data to their new equivalents. If an application maintains multiple separate widget host instances, it will receive this broadcast separately for each one.
The intent will contain the following extras:
EXTRA_APPWIDGET_OLD_IDS |
The set of appWidgetIds represented in a restored backup that have been successfully
incorporated into the current environment. This may be all of the AppWidgets known
to this application, or just a subset. Each entry in this array of appWidgetIds has
a corresponding entry in the EXTRA_APPWIDGET_IDS extra. |
EXTRA_APPWIDGET_IDS |
The set of appWidgetIds now valid for this application. The app should look at
its restored widget configuration and translate each appWidgetId in the
EXTRA_APPWIDGET_OLD_IDS array to its new value found at the corresponding
index within this array. |
EXTRA_HOST_ID |
The integer ID of the widget host instance whose state has just been restored. |
This is a protected intent that can only be sent by the system.
See also:
Constant Value: "android.appwidget.action.APPWIDGET_HOST_RESTORED"
public static final String ACTION_APPWIDGET_OPTIONS_CHANGED
Sent when the custom extras for an AppWidget change.
This is a protected intent that can only be sent by the system.
Constant Value: "android.appwidget.action.APPWIDGET_UPDATE_OPTIONS"
public static final String ACTION_APPWIDGET_PICK
Activity action to launch from your AppWidgetHost
activity when you want to
pick an AppWidget to display. The AppWidget picker activity will be launched.
You must supply the following extras:
EXTRA_APPWIDGET_ID |
A newly allocated appWidgetId, which will be bound to the AppWidget provider once the user has selected one. |
The system will respond with an onActivityResult call with the following extras in the intent:
EXTRA_APPWIDGET_ID |
The appWidgetId that you supplied in the original intent. |
When you receive the result from the AppWidget pick activity, if the resultCode is
Activity.RESULT_OK
, an AppWidget has been selected. You should then
check the AppWidgetProviderInfo for the returned AppWidget, and if it has one, launch its
configuration activity. If Activity.RESULT_CANCELED
is returned, you
should delete the appWidgetId.
See also:
Constant Value: "android.appwidget.action.APPWIDGET_PICK"
public static final String ACTION_APPWIDGET_RESTORED
Sent to an AppWidgetProvider
after AppWidget state related to that provider has
been restored from backup. The intent contains information about how to translate AppWidget
ids from the restored data to their new equivalents.
The intent will contain the following extras:
EXTRA_APPWIDGET_OLD_IDS |
The set of appWidgetIds represented in a restored backup that have been successfully
incorporated into the current environment. This may be all of the AppWidgets known
to this application, or just a subset. Each entry in this array of appWidgetIds has
a corresponding entry in the EXTRA_APPWIDGET_IDS extra. |
EXTRA_APPWIDGET_IDS |
The set of appWidgetIds now valid for this application. The app should look at
its restored widget configuration and translate each appWidgetId in the
EXTRA_APPWIDGET_OLD_IDS array to its new value found at the corresponding
index within this array. |
This is a protected intent that can only be sent by the system.
See also:
Constant Value: "android.appwidget.action.APPWIDGET_RESTORED"
public static final String ACTION_APPWIDGET_UPDATE
Sent when it is time to update your AppWidget.
This may be sent in response to a new instance for this AppWidget provider having
been instantiated, the requested AppWidgetProviderInfo#updatePeriodMillis
having lapsed, or the system booting.
The intent will contain the following extras:
EXTRA_APPWIDGET_IDS |
The appWidgetIds to update. This may be all of the AppWidgets created for this provider, or just a subset. The system tries to send updates for as few AppWidget instances as possible. |
See also:
Constant Value: "android.appwidget.action.APPWIDGET_UPDATE"
public static final String EXTRA_APPWIDGET_ID
An intent extra (int) that contains one appWidgetId.
The value will be an int that can be retrieved like this:
Bundle extras = intent.getExtras(); int appWidgetId = extras.getInt(AppWidgetManager.EXTRA_APPWIDGET_ID);
Constant Value: "appWidgetId"
public static final String EXTRA_APPWIDGET_IDS
An intent extra that contains multiple appWidgetIds.
The value will be an int array that can be retrieved like this:
Bundle extras = intent.getExtras(); int[] appWidgetIds = extras.getIntArray(AppWidgetManager.EXTRA_APPWIDGET_IDS);
Constant Value: "appWidgetIds"
public static final String EXTRA_APPWIDGET_OLD_IDS
An intent extra that contains multiple appWidgetIds. These are id values as
they were provided to the application during a recent restore from backup. It is
attached to the ACTION_APPWIDGET_RESTORED
broadcast intent.
The value will be an int array that can be retrieved like this:
Bundle extras = intent.getExtras(); int[] appWidgetIds = extras.getIntArray(AppWidgetManager.EXTRA_APPWIDGET_IDS);
Constant Value: "appWidgetOldIds"
public static final String EXTRA_APPWIDGET_OPTIONS
An intent extra which points to a bundle of extra information for a particular widget id.
In particular this bundle can contain OPTION_APPWIDGET_MIN_WIDTH
,
OPTION_APPWIDGET_MIN_HEIGHT
, OPTION_APPWIDGET_MAX_WIDTH
,
OPTION_APPWIDGET_MAX_HEIGHT
.
Constant Value: "appWidgetOptions"
public static final String EXTRA_APPWIDGET_PREVIEW
An extra that can be passed to
requestPinAppWidget(android.content.ComponentName, android.os.Bundle, android.app.PendingIntent)
. This would allow the
launcher app to present a custom preview to the user.
The value should be a RemoteViews
similar to what is used with
updateAppWidget(ComponentName, RemoteViews)
calls.
Constant Value: "appWidgetPreview"
public static final String EXTRA_APPWIDGET_PROVIDER
An intent extra that contains the component name of a AppWidget provider.
The value will be an ComponentName
.
Constant Value: "appWidgetProvider"
public static final String EXTRA_APPWIDGET_PROVIDER_PROFILE
An intent extra that contains the user handle of the profile under which an AppWidget provider is registered.
The value will be a UserHandle
.
Constant Value: "appWidgetProviderProfile"
public static final String EXTRA_CUSTOM_EXTRAS
An intent extra to pass to the AppWidget picker containing a List
of
Bundle
objects to mix in to the list of AppWidgets that are
installed. It will be added to the extras object on the Intent
that is returned from the picker activity.
Constant Value: "customExtras"
public static final String EXTRA_CUSTOM_INFO
An intent extra to pass to the AppWidget picker containing a List
of
AppWidgetProviderInfo
objects to mix in to the list of AppWidgets that are
installed. (This is how the launcher shows the search widget).
Constant Value: "customInfo"
public static final String EXTRA_HOST_ID
An intent extra attached to the ACTION_APPWIDGET_HOST_RESTORED
broadcast,
indicating the integer ID of the host whose widgets have just been restored.
Constant Value: "hostId"
public static final int INVALID_APPWIDGET_ID
A sentinel value that the AppWidget manager will never return as a appWidgetId.
Constant Value: 0 (0x00000000)
public static final String META_DATA_APPWIDGET_PROVIDER
Field for the manifest meta-data tag.
See also:
Constant Value: "android.appwidget.provider"
public static final String OPTION_APPWIDGET_HOST_CATEGORY
A bundle extra that hints to the AppWidgetProvider the category of host that owns this
this widget. Can have the value AppWidgetProviderInfo#WIDGET_CATEGORY_HOME_SCREEN
or AppWidgetProviderInfo#WIDGET_CATEGORY_KEYGUARD
or AppWidgetProviderInfo#WIDGET_CATEGORY_SEARCHBOX
.
Constant Value: "appWidgetCategory"
public static final String OPTION_APPWIDGET_MAX_HEIGHT
A bundle extra (int) that contains the upper bound on the current width, in dips, of a widget instance.
Constant Value: "appWidgetMaxHeight"
public static final String OPTION_APPWIDGET_MAX_WIDTH
A bundle extra (int) that contains the upper bound on the current width, in dips, of a widget instance.
Constant Value: "appWidgetMaxWidth"
public static final String OPTION_APPWIDGET_MIN_HEIGHT
A bundle extra (int) that contains the lower bound on the current height, in dips, of a widget instance.
Constant Value: "appWidgetMinHeight"
public static final String OPTION_APPWIDGET_MIN_WIDTH
A bundle extra (int) that contains the lower bound on the current width, in dips, of a widget instance.
Constant Value: "appWidgetMinWidth"
public static final String OPTION_APPWIDGET_RESTORE_COMPLETED
A bundle extra (boolean) that contains whether or not an app has finished restoring a widget.
After restore, the app should set OPTION_APPWIDGET_RESTORE_COMPLETED to true on its
widgets followed by calling updateAppWidget(ComponentName, RemoteViews)
to update the views.
See also:
Constant Value: "appWidgetRestoreCompleted"
public boolean bindAppWidgetIdIfAllowed (int appWidgetId, ComponentName provider)
Set the component for a given appWidgetId.
You need the BIND_APPWIDGET permission or the user must have enabled binding
widgets always for your component. Should be used by apps that host widgets; if this
method returns false, call ACTION_APPWIDGET_BIND
to request permission to
bind
Parameters | |
---|---|
appWidgetId |
int : The AppWidget id under which to bind the provider. |
provider |
ComponentName : The BroadcastReceiver that will be the AppWidget
provider for this AppWidget. |
Returns | |
---|---|
boolean |
true if this component has permission to bind the AppWidget |
public boolean bindAppWidgetIdIfAllowed (int appWidgetId, UserHandle user, ComponentName provider, Bundle options)
Set the provider for a given appWidgetId if the caller has a permission.
Note: You need the Manifest.permission.BIND_APPWIDGET
permission or the user must have enabled binding widgets always for your component.
Should be used by apps that host widgets. If this method returns false, call ACTION_APPWIDGET_BIND
to request permission to bind.
Parameters | |
---|---|
appWidgetId |
int : The AppWidget id under which to bind the provider. |
user |
UserHandle : The user id in which the provider resides. |
provider |
ComponentName : The component name of the provider. |
options |
Bundle : An optional Bundle containing options for the AppWidget. |
Returns | |
---|---|
boolean |
true if this component has permission to bind the AppWidget |
public boolean bindAppWidgetIdIfAllowed (int appWidgetId, ComponentName provider, Bundle options)
Set the component for a given appWidgetId.
You need the BIND_APPWIDGET permission or the user must have enabled binding
widgets always for your component. Should be used by apps that host widgets; if this
method returns false, call ACTION_APPWIDGET_BIND
to request permission to
bind
Parameters | |
---|---|
appWidgetId |
int : The AppWidget id under which to bind the provider. |
provider |
ComponentName : The BroadcastReceiver that will be the AppWidget
provider for this AppWidget. |
options |
Bundle : Bundle containing options for the AppWidget. See also
updateAppWidgetOptions(int, android.os.Bundle) |
Returns | |
---|---|
boolean |
true if this component has permission to bind the AppWidget |
public int[] getAppWidgetIds (ComponentName provider)
Get the list of appWidgetIds that have been bound to the given AppWidget provider.
Parameters | |
---|---|
provider |
ComponentName : The BroadcastReceiver that is the
AppWidget provider to find appWidgetIds for. |
Returns | |
---|---|
int[] |
public AppWidgetProviderInfo getAppWidgetInfo (int appWidgetId)
Get the available info about the AppWidget.
Parameters | |
---|---|
appWidgetId |
int |
Returns | |
---|---|
AppWidgetProviderInfo |
A appWidgetId. If the appWidgetId has not been bound to a provider yet, or you don't have access to that appWidgetId, null is returned. |
public Bundle getAppWidgetOptions (int appWidgetId)
Get the extras associated with a given widget instance.
The extras can be used to embed additional information about this widget to be accessed by the associated widget's AppWidgetProvider.
Parameters | |
---|---|
appWidgetId |
int : The AppWidget instances for which to set the RemoteViews. |
Returns | |
---|---|
Bundle |
The options associated with the given widget instance. |
See also:
public List<AppWidgetProviderInfo> getInstalledProviders ()
Return a list of the AppWidget providers that are currently installed.
Returns | |
---|---|
List<AppWidgetProviderInfo> |
public List<AppWidgetProviderInfo> getInstalledProvidersForPackage (String packageName, UserHandle profile)
Gets the AppWidget providers for the given package and user profile. User profile can only be the current user or a profile of the current user. For example, the current user may have a corporate profile. In this case the parent user profile has a child profile, the corporate one.
Parameters | |
---|---|
packageName |
String : The package for which to get providers. If null, this method is
equivalent to getInstalledProvidersForProfile(android.os.UserHandle) .
This value cannot be null . |
profile |
UserHandle : The profile for which to get providers. Passing null is equivalent
to querying for only the calling user.
This value may be null . |
Returns | |
---|---|
List<AppWidgetProviderInfo> |
The installed providers, or an empty list if none are found for the given package and user. |
Throws | |
---|---|
NullPointerException |
if the provided package name is null |
public List<AppWidgetProviderInfo> getInstalledProvidersForProfile (UserHandle profile)
Gets the AppWidget providers for the given user profile. User profile can only be the current user or a profile of the current user. For example, the current user may have a corporate profile. In this case the parent user profile has a child profile, the corporate one.
Parameters | |
---|---|
profile |
UserHandle : The profile for which to get providers. Passing null is equivalent
to querying for only the calling user.
This value may be null . |
Returns | |
---|---|
List<AppWidgetProviderInfo> |
The installed providers, or an empty list if none are found for the given user. |
public static AppWidgetManager getInstance (Context context)
Get the AppWidgetManager instance to use for the supplied Context
object.
Parameters | |
---|---|
context |
Context |
Returns | |
---|---|
AppWidgetManager |
public boolean isRequestPinAppWidgetSupported ()
Return TRUE
if the default launcher supports
requestPinAppWidget(android.content.ComponentName, android.os.Bundle, android.app.PendingIntent)
Returns | |
---|---|
boolean |
public void notifyAppWidgetViewDataChanged (int appWidgetId, int viewId)
Notifies the specified collection view in the specified AppWidget instance to invalidate its data.
Parameters | |
---|---|
appWidgetId |
int : The AppWidget instance to notify of view data changes. |
viewId |
int : The collection view id. |
public void notifyAppWidgetViewDataChanged (int[] appWidgetIds, int viewId)
Notifies the specified collection view in all the specified AppWidget instances to invalidate their data.
Parameters | |
---|---|
appWidgetIds |
int : The AppWidget instances to notify of view data changes. |
viewId |
int : The collection view id. |
public void partiallyUpdateAppWidget (int appWidgetId, RemoteViews views)
Perform an incremental update or command on the widget specified by appWidgetId.
This update differs from updateAppWidget(int, android.widget.RemoteViews)
in that the RemoteViews
object which is passed is understood to be an incomplete representation of the widget, and
hence is not cached by the AppWidgetService. Note that because these updates are not cached,
any state that they modify that is not restored by restoreInstanceState will not persist in
the case that the widgets are restored using the cached version in AppWidgetService.
Use with RemoteViews#showNext(int)
, RemoteViews#showPrevious(int)
,
RemoteViews#setScrollPosition(int, int)
and similar commands.
It is okay to call this method both inside an ACTION_APPWIDGET_UPDATE
broadcast,
and outside of the handler.
This method will only work when called from the uid that owns the AppWidget provider.
This method will be ignored if a widget has not received a full update via
updateAppWidget(int[], android.widget.RemoteViews)
.
Parameters | |
---|---|
appWidgetId |
int : The AppWidget instance for which to set the RemoteViews. |
views |
RemoteViews : The RemoteViews object containing the incremental update / command. |
public void partiallyUpdateAppWidget (int[] appWidgetIds, RemoteViews views)
Perform an incremental update or command on the widget(s) specified by appWidgetIds.
This update differs from updateAppWidget(int[], android.widget.RemoteViews)
in that the
RemoteViews object which is passed is understood to be an incomplete representation of the
widget, and hence does not replace the cached representation of the widget. As of API
level 17, the new properties set within the views objects will be appended to the cached
representation of the widget, and hence will persist.
Use with RemoteViews#showNext(int)
, RemoteViews#showPrevious(int)
,
RemoteViews#setScrollPosition(int, int)
and similar commands.
It is okay to call this method both inside an ACTION_APPWIDGET_UPDATE
broadcast,
and outside of the handler.
This method will only work when called from the uid that owns the AppWidget provider.
This method will be ignored if a widget has not received a full update via
updateAppWidget(int[], android.widget.RemoteViews)
.
Parameters | |
---|---|
appWidgetIds |
int : The AppWidget instances for which to set the RemoteViews. |
views |
RemoteViews : The RemoteViews object containing the incremental update / command. |
public boolean requestPinAppWidget (ComponentName provider, Bundle extras, PendingIntent successCallback)
Request to pin an app widget on the current launcher. It's up to the launcher to accept this
request (optionally showing a user confirmation). If the request is accepted, the caller will
get a confirmation with extra EXTRA_APPWIDGET_ID
.
When a request is denied by the user, the caller app will not get any response.
Only apps with a foreground activity or a foreground service can call it. Otherwise
it'll throw IllegalStateException
.
It's up to the launcher how to handle previous pending requests when the same package calls this API multiple times in a row. It may ignore the previous requests, for example.
Launcher will not show the configuration activity associated with the provider in this
case. The app could either show the configuration activity as a response to the callback,
or show if before calling the API (various configurations can be encapsulated in
successCallback
to avoid persisting them before the widgetId is known).
Parameters | |
---|---|
provider |
ComponentName : The ComponentName for the BroadcastReceiver provider for your AppWidget.
This value cannot be null . |
extras |
Bundle : In not null, this is passed to the launcher app. For eg EXTRA_APPWIDGET_PREVIEW can be used for a custom preview.
This value may be null . |
successCallback |
PendingIntent : If not null, this intent will be sent when the widget is created.
This value may be null . |
Returns | |
---|---|
boolean |
TRUE if the launcher supports this feature. Note the API will return without
waiting for the user to respond, so getting TRUE from this API does *not* mean
the shortcut is pinned. FALSE if the launcher doesn't support this feature. |
Throws | |
---|---|
IllegalStateException |
The caller doesn't have a foreground activity or a foreground service or when the user is locked. |
public void updateAppWidget (ComponentName provider, RemoteViews views)
Set the RemoteViews to use for all AppWidget instances for the supplied AppWidget provider.
It is okay to call this method both inside an ACTION_APPWIDGET_UPDATE
broadcast,
and outside of the handler.
This method will only work when called from the uid that owns the AppWidget provider.
Parameters | |
---|---|
provider |
ComponentName : The ComponentName for the BroadcastReceiver provider
for your AppWidget. |
views |
RemoteViews : The RemoteViews object to show. |
public void updateAppWidget (int[] appWidgetIds, RemoteViews views)
Set the RemoteViews to use for the specified appWidgetIds.
Note that the RemoteViews parameter will be cached by the AppWidgetService, and hence should
contain a complete representation of the widget. For performing partial widget updates, see
partiallyUpdateAppWidget(int[], android.widget.RemoteViews)
.
It is okay to call this method both inside an ACTION_APPWIDGET_UPDATE
broadcast,
and outside of the handler.
This method will only work when called from the uid that owns the AppWidget provider.
The total Bitmap memory used by the RemoteViews object cannot exceed that required to fill the screen 1.5 times, ie. (screen width x screen height x 4 x 1.5) bytes.
Parameters | |
---|---|
appWidgetIds |
int : The AppWidget instances for which to set the RemoteViews. |
views |
RemoteViews : The RemoteViews object to show. |
public void updateAppWidget (int appWidgetId, RemoteViews views)
Set the RemoteViews to use for the specified appWidgetId.
Note that the RemoteViews parameter will be cached by the AppWidgetService, and hence should
contain a complete representation of the widget. For performing partial widget updates, see
partiallyUpdateAppWidget(int, android.widget.RemoteViews)
.
It is okay to call this method both inside an ACTION_APPWIDGET_UPDATE
broadcast,
and outside of the handler.
This method will only work when called from the uid that owns the AppWidget provider.
The total Bitmap memory used by the RemoteViews object cannot exceed that required to fill the screen 1.5 times, ie. (screen width x screen height x 4 x 1.5) bytes.
Parameters | |
---|---|
appWidgetId |
int : The AppWidget instance for which to set the RemoteViews. |
views |
RemoteViews : The RemoteViews object to show. |
public void updateAppWidgetOptions (int appWidgetId, Bundle options)
Update the extras for a given widget instance.
The extras can be used to embed additional information about this widget to be accessed by the associated widget's AppWidgetProvider.
Parameters | |
---|---|
appWidgetId |
int : The AppWidget instances for which to set the RemoteViews. |
options |
Bundle : The options to associate with this widget |
See also:
public void updateAppWidgetProviderInfo (ComponentName provider, String metaDataKey)
Updates the info for the supplied AppWidget provider. Apps can use this to change the default behavior of the widget based on the state of the app (for e.g., if the user is logged in or not). Calling this API completely replaces the previous definition.
The manifest entry of the provider should contain an additional meta-data tag similar to
META_DATA_APPWIDGET_PROVIDER
which should point to any alternative definitions for
the provider.
This is persisted across device reboots and app updates. If this meta-data key is not present in the manifest entry, the info reverts to default.
Parameters | |
---|---|
provider |
ComponentName : ComponentName for the BroadcastReceiver provider for your AppWidget. |
metaDataKey |
String : key for the meta-data tag pointing to the new provider info. Use null
to reset any previously set info.
This value may be null . |