lightbulb_outline Please take our October 2018 developer survey. Start survey

AppWidgetHost

public class AppWidgetHost
extends Object

java.lang.Object
   ↳ android.appwidget.AppWidgetHost


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.

int[] getAppWidgetIds()

Gets a list of all the appWidgetIds that are bound to the current host

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.

Inherited methods

Public constructors

AppWidgetHost

added in API level 3
public AppWidgetHost (Context context, 
                int hostId)

Parameters
context Context

hostId int

Public methods

allocateAppWidgetId

added in API level 3
public int allocateAppWidgetId ()

Get a appWidgetId for a host in the calling process.

Returns
int a appWidgetId

createView

added in API level 3
public final AppWidgetHostView createView (Context context, 
                int appWidgetId, 
                AppWidgetProviderInfo appWidget)

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

Parameters
context Context

appWidgetId int

appWidget AppWidgetProviderInfo

Returns
AppWidgetHostView

deleteAllHosts

added in API level 3
public static void deleteAllHosts ()

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.

deleteAppWidgetId

added in API level 3
public void deleteAppWidgetId (int appWidgetId)

Stop listening to changes for this AppWidget.

Parameters
appWidgetId int

deleteHost

added in API level 3
public void deleteHost ()

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.

getAppWidgetIds

added in API level 26
public int[] getAppWidgetIds ()

Gets a list of all the appWidgetIds that are bound to the current host

Returns
int[]

startAppWidgetConfigureActivityForResult

added in API level 21
public 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. 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 Activity.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 Activity: The activity from which to start the configure one.

This value must never be null.

appWidgetId int: The bound app widget whose provider's config activity to start.

intentFlags int: Optional intent flags.

requestCode int: Optional request code retuned with the result.

options Bundle

This value may be null.

Throws
ActivityNotFoundException If the activity is not found.

startListening

added in API level 3
public void startListening ()

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

stopListening

added in API level 3
public void stopListening ()

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

clearViews

added in API level 11
protected void clearViews ()

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

onCreateView

added in API level 3
protected AppWidgetHostView onCreateView (Context context, 
                int appWidgetId, 
                AppWidgetProviderInfo appWidget)

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

Parameters
context Context

appWidgetId int

appWidget AppWidgetProviderInfo

Returns
AppWidgetHostView

onProviderChanged

added in API level 3
protected void onProviderChanged (int appWidgetId, 
                AppWidgetProviderInfo appWidget)

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

Parameters
appWidgetId int

appWidget AppWidgetProviderInfo

onProvidersChanged

added in API level 17
protected void onProvidersChanged ()

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