AppWidgetHostView


public class AppWidgetHostView
extends FrameLayout

java.lang.Object
   ↳ android.view.View
     ↳ android.view.ViewGroup
       ↳ android.widget.FrameLayout
         ↳ android.appwidget.AppWidgetHostView


Provides the glue to show AppWidget views. This class offers automatic animation between updates, and will try recycling old views for each incoming RemoteViews.

Summary

Inherited XML attributes

Inherited constants

Inherited fields

Public constructors

AppWidgetHostView(Context context)

Create a host view.

AppWidgetHostView(Context context, int animationIn, int animationOut)

Create a host view.

Public methods

FrameLayout.LayoutParams generateLayoutParams(AttributeSet attrs)

Returns a new set of layout parameters based on the supplied attributes set.

int getAppWidgetId()
AppWidgetProviderInfo getAppWidgetInfo()
static Rect getDefaultPaddingForWidget(Context context, ComponentName component, Rect padding)

As of ICE_CREAM_SANDWICH we are automatically adding padding to widgets targeting ICE_CREAM_SANDWICH and higher.

void resetColorResources()

Reset the dynamically overloaded resources, reverting to the default values for all the colors.

void setAppWidget(int appWidgetId, AppWidgetProviderInfo info)

Set the AppWidget that will be displayed by this view.

void setColorResources(SparseIntArray colorMapping)

Set the dynamically overloaded color resources.

void setExecutor(Executor executor)

Sets an executor which can be used for asynchronously inflating.

void setOnLightBackground(boolean onLightBackground)

Sets whether the widget is being displayed on a light/white background and use an alternate UI if available.

void updateAppWidget(RemoteViews remoteViews)

Process a set of RemoteViews coming in as an update from the AppWidget provider.

void updateAppWidgetOptions(Bundle options)

Specify some extra information for the widget provider.

void updateAppWidgetSize(Bundle newOptions, int minWidth, int minHeight, int maxWidth, int maxHeight)

This method was deprecated in API level 31. use AppWidgetHostView#updateAppWidgetSize(Bundle, List) instead.

void updateAppWidgetSize(Bundle newOptions, List<SizeF> sizes)

Provide guidance about the size of this widget to the AppWidgetManager.

Protected methods

void dispatchDraw(Canvas canvas)

Called by draw to draw the child views.

void dispatchRestoreInstanceState(SparseArray<Parcelable> container)

Called by restoreHierarchyState(android.util.SparseArray) to retrieve the state for this view and its children.

void dispatchSaveInstanceState(SparseArray<Parcelable> container)

Called by saveHierarchyState(android.util.SparseArray) to store the state for this view and its children.

View getDefaultView()

Inflate and return the default layout requested by AppWidget provider.

View getErrorView()

Inflate and return a view that represents an error state.

void onLayout(boolean changed, int left, int top, int right, int bottom)

Called from layout when this view should assign a size and position to each of its children.

void prepareView(View view)

Prepare the given view to be shown.

Inherited methods

Public constructors

AppWidgetHostView

Added in API level 3
public AppWidgetHostView (Context context)

Create a host view. Uses default fade animations.

Parameters
context Context

AppWidgetHostView

Added in API level 3
public AppWidgetHostView (Context context, 
                int animationIn, 
                int animationOut)

Create a host view. Uses specified animations when pushing updateAppWidget(android.widget.RemoteViews).

Parameters
context Context

animationIn int: Resource ID of in animation to use

animationOut int: Resource ID of out animation to use

Public methods

generateLayoutParams

Added in API level 3
public FrameLayout.LayoutParams generateLayoutParams (AttributeSet attrs)

Returns a new set of layout parameters based on the supplied attributes set.

Parameters
attrs AttributeSet: the attributes to build the layout parameters from

Returns
FrameLayout.LayoutParams an instance of ViewGroup.LayoutParams or one of its descendants

getAppWidgetId

Added in API level 3
public int getAppWidgetId ()

Returns
int

getAppWidgetInfo

Added in API level 3
public AppWidgetProviderInfo getAppWidgetInfo ()

Returns
AppWidgetProviderInfo

getDefaultPaddingForWidget

Added in API level 15
public static Rect getDefaultPaddingForWidget (Context context, 
                ComponentName component, 
                Rect padding)

As of ICE_CREAM_SANDWICH we are automatically adding padding to widgets targeting ICE_CREAM_SANDWICH and higher. The new widget design guidelines strongly recommend that widget developers do not add extra padding to their widgets. This will help achieve consistency among widgets. Note: this method is only needed by developers of AppWidgetHosts. The method is provided in order for the AppWidgetHost to account for the automatic padding when computing the number of cells to allocate to a particular widget.

Parameters
context Context: the current context

component ComponentName: the component name of the widget

padding Rect: Rect in which to place the output, if null, a new Rect will be allocated and returned

Returns
Rect default padding for this widget, in pixels

resetColorResources

Added in API level 31
public void resetColorResources ()

Reset the dynamically overloaded resources, reverting to the default values for all the colors. If colors were defined before, calling this method will trigger a full re-inflation of the App Widget.

setAppWidget

Added in API level 3
public void setAppWidget (int appWidgetId, 
                AppWidgetProviderInfo info)

Set the AppWidget that will be displayed by this view. This method also adds default padding to widgets, as described in getDefaultPaddingForWidget(android.content.Context, android.content.ComponentName, android.graphics.Rect) and can be overridden in order to add custom padding.

Parameters
appWidgetId int

info AppWidgetProviderInfo

setColorResources

Added in API level 31
public void setColorResources (SparseIntArray colorMapping)

Set the dynamically overloaded color resources. colorMapping maps a predefined set of color resources to their ARGB representation. Any entry not in the predefined set of colors will be ignored. Calling this method will trigger a full re-inflation of the App Widget. The color resources that can be overloaded are the ones whose name is prefixed with system_neutral or system_accent, for example R.color.system_neutral1_500.

Parameters
colorMapping SparseIntArray: This value cannot be null.

setExecutor

Added in API level 26
public void setExecutor (Executor executor)

Sets an executor which can be used for asynchronously inflating. CPU intensive tasks like view inflation or loading images will be performed on the executor. The updates will still be applied on the UI thread.

Parameters
executor Executor: the executor to use or null.

setOnLightBackground

Added in API level 29
public void setOnLightBackground (boolean onLightBackground)

Sets whether the widget is being displayed on a light/white background and use an alternate UI if available.

Parameters
onLightBackground boolean

updateAppWidget

Added in API level 3
public void updateAppWidget (RemoteViews remoteViews)

Process a set of RemoteViews coming in as an update from the AppWidget provider. Will animate into these new views as needed

Parameters
remoteViews RemoteViews

updateAppWidgetOptions

Added in API level 16
public void updateAppWidgetOptions (Bundle options)

Specify some extra information for the widget provider. Causes a callback to the AppWidgetProvider.

Parameters
options Bundle: The bundle of options information.

updateAppWidgetSize

Added in API level 16
Deprecated in API level 31
public void updateAppWidgetSize (Bundle newOptions, 
                int minWidth, 
                int minHeight, 
                int maxWidth, 
                int maxHeight)

This method was deprecated in API level 31.
use AppWidgetHostView#updateAppWidgetSize(Bundle, List) instead.

Provide guidance about the size of this widget to the AppWidgetManager. The widths and heights should correspond to the full area the AppWidgetHostView is given. Padding added by the framework will be accounted for automatically. This information gets embedded into the AppWidget options and causes a callback to the AppWidgetProvider. In addition, the list of sizes is explicitly set to an empty list.

Parameters
newOptions Bundle: The bundle of options, in addition to the size information, can be null.

minWidth int: The minimum width in dips that the widget will be displayed at.

minHeight int: The maximum height in dips that the widget will be displayed at.

maxWidth int: The maximum width in dips that the widget will be displayed at.

maxHeight int: The maximum height in dips that the widget will be displayed at.

updateAppWidgetSize

Added in API level 31
public void updateAppWidgetSize (Bundle newOptions, 
                List<SizeF> sizes)

Provide guidance about the size of this widget to the AppWidgetManager. The sizes should correspond to the full area the AppWidgetHostView is given. Padding added by the framework will be accounted for automatically. This method will update the option bundle with the list of sizes and the min/max bounds for width and height.

Parameters
newOptions Bundle: The bundle of options, in addition to the size information. This value cannot be null.

sizes List: Sizes, in dips, the widget may be displayed at without calling the provider again. Typically, this will be size of the widget in landscape and portrait. On some foldables, this might include the size on the outer and inner screens. This value cannot be null.

Protected methods

dispatchDraw

Added in API level 3
protected void dispatchDraw (Canvas canvas)

Called by draw to draw the child views. This may be overridden by derived classes to gain control just before its children are drawn (but after its own view has been drawn).

Parameters
canvas Canvas: This value cannot be null.

dispatchRestoreInstanceState

Added in API level 3
protected void dispatchRestoreInstanceState (SparseArray<Parcelable> container)

Called by restoreHierarchyState(android.util.SparseArray) to retrieve the state for this view and its children. May be overridden to modify how restoring happens to a view's children; for example, some views may want to not store state for their children.

Parameters
container SparseArray: The SparseArray which holds previously saved state.

dispatchSaveInstanceState

Added in API level 3
protected void dispatchSaveInstanceState (SparseArray<Parcelable> container)

Called by saveHierarchyState(android.util.SparseArray) to store the state for this view and its children. May be overridden to modify how freezing happens to a view's children; for example, some views may want to not store state for their children.

Parameters
container SparseArray: The SparseArray in which to save the view's state.

getDefaultView

Added in API level 3
protected View getDefaultView ()

Inflate and return the default layout requested by AppWidget provider.

Returns
View

getErrorView

Added in API level 3
protected View getErrorView ()

Inflate and return a view that represents an error state.

Returns
View

onLayout

Added in API level 3
protected void onLayout (boolean changed, 
                int left, 
                int top, 
                int right, 
                int bottom)

Called from layout when this view should assign a size and position to each of its children. Derived classes with children should override this method and call layout on each of their children.

Parameters
changed boolean: This is a new size or position for this view

left int: Left position, relative to parent

top int: Top position, relative to parent

right int: Right position, relative to parent

bottom int: Bottom position, relative to parent

prepareView

Added in API level 3
protected void prepareView (View view)

Prepare the given view to be shown. This might include adjusting FrameLayout.LayoutParams before inserting.

Parameters
view View