Android APIs
public class

AppWidgetHost

extends Object
java.lang.Object
   ↳ android.appwidget.AppWidgetHost

Class Overview

AppWidgetHost provides the interaction with the AppWidget service for apps, like the home screen, that want to embed AppWidgets in their UI.

Summary

Public Constructors
AppWidgetHost(Context context, int hostId)
Public Methods
int allocateAppWidgetId()
Get a appWidgetId for a host in the calling process.
final AppWidgetHostView createView(Context context, int appWidgetId, AppWidgetProviderInfo appWidget)
Create the AppWidgetHostView for the given widget.
static void deleteAllHosts()
Remove all records about all hosts for your package.
void deleteAppWidgetId(int appWidgetId)
Stop listening to changes for this AppWidget.
void deleteHost()
Remove all records about this host from the AppWidget manager.
final void startAppWidgetConfigureActivityForResult(Activity activity, int appWidgetId, int intentFlags, int requestCode, Bundle options)
Starts an app widget provider configure activity for result on behalf of the caller.
void startListening()
Start receiving onAppWidgetChanged calls for your AppWidgets.
void stopListening()
Stop receiving onAppWidgetChanged calls for your AppWidgets.
Protected Methods
void clearViews()
Clear the list of Views that have been created by this AppWidgetHost.
AppWidgetHostView onCreateView(Context context, int appWidgetId, AppWidgetProviderInfo appWidget)
Called to create the AppWidgetHostView. Override to return a custom subclass if you need it.
void onProviderChanged(int appWidgetId, AppWidgetProviderInfo appWidget)
Called when the AppWidget provider for a AppWidget has been upgraded to a new apk.
void onProvidersChanged()
Called when the set of available widgets changes (ie.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public AppWidgetHost (Context context, int hostId)

Added in API level 3

Parameters
context
hostId

Public Methods

public int allocateAppWidgetId ()

Added in API level 3

Get a appWidgetId for a host in the calling process.

Returns
int a appWidgetId

public final AppWidgetHostView createView (Context context, int appWidgetId, AppWidgetProviderInfo appWidget)

Added in API level 3

Create the AppWidgetHostView for the given widget. The AppWidgetHost retains a pointer to the newly-created View.

Parameters
context
appWidgetId
appWidget
Returns
AppWidgetHostView

public static void deleteAllHosts ()

Added in API level 3

Remove all records about all hosts for your package.

  • Call this when initializing your database, as it might be because of a data wipe.
  • Call this to have the AppWidget manager release all resources associated with your host. Any future calls about this host will cause the records to be re-allocated.

public void deleteAppWidgetId (int appWidgetId)

Added in API level 3

Stop listening to changes for this AppWidget.

Parameters
appWidgetId

public void deleteHost ()

Added in API level 3

Remove all records about this host from the AppWidget manager.

  • Call this when initializing your database, as it might be because of a data wipe.
  • Call this to have the AppWidget manager release all resources associated with your host. Any future calls about this host will cause the records to be re-allocated.

public final void startAppWidgetConfigureActivityForResult (Activity activity, int appWidgetId, int intentFlags, int requestCode, Bundle options)

Added in API level 21

Starts an app widget provider configure activity for result on behalf of the caller. Use this method if the provider is in another profile as you are not allowed to start an activity in another profile. You can optionally provide a request code that is returned in onActivityResult(int, int, android.content.Intent) and an options bundle to be passed to the started activity.

Note that the provided app widget has to be bound for this method to work.

Parameters
activity The activity from which to start the configure one.
appWidgetId The bound app widget whose provider's config activity to start.
intentFlags Optional intent flags.
requestCode Optional request code retuned with the result.
Throws
ActivityNotFoundException If the activity is not found.

See also:

public void startListening ()

Added in API level 3

Start receiving onAppWidgetChanged calls for your AppWidgets. Call this when your activity becomes visible, i.e. from onStart() in your Activity.

public void stopListening ()

Added in API level 3

Stop receiving onAppWidgetChanged calls for your AppWidgets. Call this when your activity is no longer visible, i.e. from onStop() in your Activity.

Protected Methods

protected void clearViews ()

Added in API level 11

Clear the list of Views that have been created by this AppWidgetHost.

protected AppWidgetHostView onCreateView (Context context, int appWidgetId, AppWidgetProviderInfo appWidget)

Added in API level 3

Called to create the AppWidgetHostView. Override to return a custom subclass if you need it.

Parameters
context
appWidgetId
appWidget
Returns
AppWidgetHostView

protected void onProviderChanged (int appWidgetId, AppWidgetProviderInfo appWidget)

Added in API level 3

Called when the AppWidget provider for a AppWidget has been upgraded to a new apk.

Parameters
appWidgetId
appWidget

protected void onProvidersChanged ()

Added in API level 17

Called when the set of available widgets changes (ie. widget containing packages are added, updated or removed, or widget components are enabled or disabled.)