AppWidgetProviderInfo  |  API reference  |  Android Developers (original) (raw)

public class AppWidgetProviderInfo
extends [Object](/reference/java/lang/Object) implements[Parcelable](/reference/android/os/Parcelable)

Describes the meta data for an installed AppWidget provider. The fields in this class correspond to the fields in the <appwidget-provider> xml tag.

Summary

Constants
int RESIZE_BOTH Widget is resizable in both the horizontal and vertical axes.
int RESIZE_HORIZONTAL Widget is resizable in the horizontal axis only.
int RESIZE_NONE Widget is not resizable.
int RESIZE_VERTICAL Widget is resizable in the vertical axis only.
int WIDGET_CATEGORY_HOME_SCREEN Indicates that the widget can be displayed on the home screen.
int WIDGET_CATEGORY_KEYGUARD Indicates that the widget can be displayed on the keyguard.
int WIDGET_CATEGORY_NOT_KEYGUARD Indicates that the widget should never be shown on the keyguard.
int WIDGET_CATEGORY_SEARCHBOX Indicates that the widget can be displayed within a space reserved for the search box.
int WIDGET_FEATURE_CONFIGURATION_OPTIONAL The widget provides a default configuration.
int WIDGET_FEATURE_HIDE_FROM_PICKER The widget is added directly by the app, and the host may hide this widget when providing the user with the list of available widgets to choose from.
int WIDGET_FEATURE_RECONFIGURABLE The widget can be reconfigured anytime after it is bound by starting theconfigure activity.
Inherited constants
From interfaceandroid.os.Parcelable int CONTENTS_FILE_DESCRIPTOR Descriptor bit used with describeContents(): indicates that the Parcelable object's flattened representation includes a file descriptor. int PARCELABLE_WRITE_RETURN_VALUE Flag for use with writeToParcel(Parcel, int): the object being written is a return value, that is the result of a function such as "Parcelable someFunction()", "void someFunction(out Parcelable)", or "void someFunction(inout Parcelable)".
Fields
public static finalCreator<AppWidgetProviderInfo> CREATOR Parcelable.Creator that instantiates AppWidgetProviderInfo objects
public int autoAdvanceViewId The view id of the AppWidget subview which should be auto-advanced by the widget's host.
publicComponentName configure The activity to launch that will configure the AppWidget.
public int descriptionRes Resource id for the description of the AppWidget.
public int generatedPreviewCategories Flags indicating the widget categories for which generated previews are available.
public int icon The icon to display for this AppWidget in the AppWidget picker.
public int initialKeyguardLayout The resource id of the initial layout for this AppWidget when it is displayed on keyguard.
public int initialLayout The resource id of the initial layout for this AppWidget.
publicString label This field was deprecated in API level 21. Use loadLabel(android.content.pm.PackageManager).
public int maxResizeHeight Maximum height (in px) which the widget can be resized to.
public int maxResizeWidth Maximum width (in px) which the widget can be resized to.
public int minHeight The default height of the widget when added to a host, in px.
public int minResizeHeight Minimum height (in px) which the widget can be resized to.
public int minResizeWidth Minimum width (in px) which the widget can be resized to.
public int minWidth The default width of the widget when added to a host, in px.
public int previewImage A preview of what the AppWidget will look like after it's configured.
public int previewLayout The layout resource id of a preview of what the AppWidget will look like after it's configured.
publicComponentName provider Identity of this AppWidget component.
public int resizeMode The rules by which a widget can be resized.
public int targetCellHeight The default height of a widget when added to a host, in units of launcher grid cells.
public int targetCellWidth The default width of a widget when added to a host, in units of launcher grid cells.
public int updatePeriodMillis How often, in milliseconds, that this AppWidget wants to be updated.
public int widgetCategory Determines whether this widget can be displayed on the home screen, the keyguard, or both.
public int widgetFeatures Flags indicating various features supported by the widget.
Public constructors
AppWidgetProviderInfo()
AppWidgetProviderInfo(Parcel in) Unflatten the AppWidgetProviderInfo from a parcel.
Public methods
AppWidgetProviderInfo clone() Creates and returns a copy of this object.
int describeContents() Describe the kinds of special objects contained in this Parcelable instance's marshaled representation.
ActivityInfo getActivityInfo() Returns the broadcast receiver that is providing this widget.
finalUserHandle getProfile() Gets the user profile in which the provider resides.
finalCharSequence loadDescription(Context context) Loads localized description for the app widget.
finalDrawable loadIcon(Context context, int density) Loads the icon to display for this AppWidget in the AppWidget picker.
finalString loadLabel(PackageManager packageManager) Loads the localized label to display to the user in the AppWidget picker.
finalDrawable loadPreviewImage(Context context, int density) Loads a preview of what the AppWidget will look like after it's configured.
String toString() Returns a string representation of the object.
void writeToParcel(Parcel out, int flags) Flatten this object in to a Parcel.
Inherited methods
From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. finalClass<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
From interface android.os.Parcelable abstract int describeContents() Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. abstract void writeToParcel(Parcel dest, int flags) Flatten this object in to a Parcel.

Constants

RESIZE_BOTH

public static final int RESIZE_BOTH

Widget is resizable in both the horizontal and vertical axes.

Constant Value: 3 (0x00000003)

RESIZE_HORIZONTAL

public static final int RESIZE_HORIZONTAL

Widget is resizable in the horizontal axis only.

Constant Value: 1 (0x00000001)

RESIZE_NONE

public static final int RESIZE_NONE

Widget is not resizable.

Constant Value: 0 (0x00000000)

RESIZE_VERTICAL

public static final int RESIZE_VERTICAL

Widget is resizable in the vertical axis only.

Constant Value: 2 (0x00000002)

WIDGET_CATEGORY_HOME_SCREEN

public static final int WIDGET_CATEGORY_HOME_SCREEN

Indicates that the widget can be displayed on the home screen. This is the default value.

Constant Value: 1 (0x00000001)

WIDGET_CATEGORY_KEYGUARD

public static final int WIDGET_CATEGORY_KEYGUARD

Indicates that the widget can be displayed on the keyguard.

Constant Value: 2 (0x00000002)

WIDGET_CATEGORY_NOT_KEYGUARD

public static final int WIDGET_CATEGORY_NOT_KEYGUARD

Indicates that the widget should never be shown on the keyguard.

Some keyguard style features may decide that [WIDGET_CATEGORY_KEYGUARD](/reference/android/appwidget/AppWidgetProviderInfo#WIDGET%5FCATEGORY%5FKEYGUARD) isn't required to be added by an app to show on the feature when chosen by a user. This category allows for a stronger statement about placement of the widget that, even in the above case, this widget should not be offered on the keyguard.

Setting this category doesn't change the behavior of AppWidgetManager queries, it is the responsibility of the widget surface to respect this value.

Constant Value: 8 (0x00000008)

public static final int WIDGET_CATEGORY_SEARCHBOX

Indicates that the widget can be displayed within a space reserved for the search box.

Constant Value: 4 (0x00000004)

WIDGET_FEATURE_CONFIGURATION_OPTIONAL

public static final int WIDGET_FEATURE_CONFIGURATION_OPTIONAL

The widget provides a default configuration. The host may choose not to launch the provided configuration activity.

Constant Value: 4 (0x00000004)

WIDGET_FEATURE_HIDE_FROM_PICKER

public static final int WIDGET_FEATURE_HIDE_FROM_PICKER

The widget is added directly by the app, and the host may hide this widget when providing the user with the list of available widgets to choose from.

Constant Value: 2 (0x00000002)

WIDGET_FEATURE_RECONFIGURABLE

public static final int WIDGET_FEATURE_RECONFIGURABLE

The widget can be reconfigured anytime after it is bound by starting the[configure](/reference/android/appwidget/AppWidgetProviderInfo#configure) activity.

Constant Value: 1 (0x00000001)

Fields

autoAdvanceViewId

public int autoAdvanceViewId

The view id of the AppWidget subview which should be auto-advanced by the widget's host.

This field corresponds to the android:autoAdvanceViewId attribute in the AppWidget meta-data file.

configure

public ComponentName configure

The activity to launch that will configure the AppWidget.

This class name of field corresponds to the android:configure attribute in the AppWidget meta-data file. The package name always corresponds to the package containing the AppWidget provider.

descriptionRes

public int descriptionRes

Resource id for the description of the AppWidget.

This field corresponds to the android:description attribute in the AppWidget meta-data file.

icon

public int icon

The icon to display for this AppWidget in the AppWidget picker. If not supplied in the xml, the application icon will be used.

This field corresponds to the android:icon attribute in the <receiver> element in the AndroidManifest.xml file.

initialKeyguardLayout

public int initialKeyguardLayout

The resource id of the initial layout for this AppWidget when it is displayed on keyguard. This parameter only needs to be provided if the widget can be displayed on the keyguard, see [widgetCategory](/reference/android/appwidget/AppWidgetProviderInfo#widgetCategory).

This field corresponds to the android:initialKeyguardLayout attribute in the AppWidget meta-data file.

initialLayout

public int initialLayout

The resource id of the initial layout for this AppWidget. This should be displayed until the RemoteViews for the AppWidget is available.

This field corresponds to the android:initialLayout attribute in the AppWidget meta-data file.

maxResizeHeight

public int maxResizeHeight

Maximum height (in px) which the widget can be resized to. This field has no effect if it is smaller than minHeight or if vertical resizing isn't enabled (see [resizeMode](/reference/android/appwidget/AppWidgetProviderInfo#resizeMode)).

This field corresponds to the android:maxResizeHeight attribute in the AppWidget meta-data file.

maxResizeWidth

public int maxResizeWidth

Maximum width (in px) which the widget can be resized to. This field has no effect if it is smaller than minWidth or if horizontal resizing isn't enabled (see [resizeMode](/reference/android/appwidget/AppWidgetProviderInfo#resizeMode)).

This field corresponds to the android:maxResizeWidth attribute in the AppWidget meta-data file.

minHeight

public int minHeight

The default height of the widget when added to a host, in px. The widget will get at least this height, and will often be given more, depending on the host.

This field corresponds to the android:minHeight attribute in the AppWidget meta-data file.

minResizeHeight

public int minResizeHeight

Minimum height (in px) which the widget can be resized to. This field has no effect if it is greater than minHeight or if vertical resizing isn't enabled (see [resizeMode](/reference/android/appwidget/AppWidgetProviderInfo#resizeMode)).

This field corresponds to the android:minResizeHeight attribute in the AppWidget meta-data file.

minResizeWidth

public int minResizeWidth

Minimum width (in px) which the widget can be resized to. This field has no effect if it is greater than minWidth or if horizontal resizing isn't enabled (see [resizeMode](/reference/android/appwidget/AppWidgetProviderInfo#resizeMode)).

This field corresponds to the android:minResizeWidth attribute in the AppWidget meta-data file.

minWidth

public int minWidth

The default width of the widget when added to a host, in px. The widget will get at least this width, and will often be given more, depending on the host.

This field corresponds to the android:minWidth attribute in the AppWidget meta-data file.

previewImage

public int previewImage

A preview of what the AppWidget will look like after it's configured. If not supplied, the AppWidget's icon will be used.

This field corresponds to the android:previewImage attribute in the AppWidget meta-data file.

previewLayout

public int previewLayout

The layout resource id of a preview of what the AppWidget will look like after it's configured.

Unlike previewImage, previewLayout can better showcase AppWidget in different locales, system themes, display sizes & density etc.

If supplied, this will take precedence over the previewImage on supported widget hosts. Otherwise, previewImage will be used.

This field corresponds to the android:previewLayout attribute in the AppWidget meta-data file.

targetCellHeight

public int targetCellHeight

The default height of a widget when added to a host, in units of launcher grid cells.

This field corresponds to the android:targetCellHeight attribute in the AppWidget meta-data file.

targetCellWidth

public int targetCellWidth

The default width of a widget when added to a host, in units of launcher grid cells.

This field corresponds to the android:targetCellWidth attribute in the AppWidget meta-data file.

updatePeriodMillis

public int updatePeriodMillis

How often, in milliseconds, that this AppWidget wants to be updated. The AppWidget manager may place a limit on how often a AppWidget is updated.

This field corresponds to the android:updatePeriodMillis attribute in the AppWidget meta-data file.

Note: Updates requested with updatePeriodMillis will not be delivered more than once every 30 minutes.

widgetCategory

public int widgetCategory

Determines whether this widget can be displayed on the home screen, the keyguard, or both. A widget which is displayed on both needs to ensure that it follows the design guidelines for both widget classes. This can be achieved by querying the AppWidget options in its widget provider's update method.

This field corresponds to the widgetCategory attribute in the AppWidget meta-data file.
Value is either 0 or a combination of the following:

widgetFeatures

public int widgetFeatures

Flags indicating various features supported by the widget. These are hints to the widget host, and do not actually change the behavior of the widget.
Value is either 0 or a combination of the following:

See also:

  * `[WIDGET_FEATURE_RECONFIGURABLE](/reference/android/appwidget/AppWidgetProviderInfo#WIDGET%5FFEATURE%5FRECONFIGURABLE)`
  * `[WIDGET_FEATURE_HIDE_FROM_PICKER](/reference/android/appwidget/AppWidgetProviderInfo#WIDGET%5FFEATURE%5FHIDE%5FFROM%5FPICKER)`
  * `[WIDGET_FEATURE_CONFIGURATION_OPTIONAL](/reference/android/appwidget/AppWidgetProviderInfo#WIDGET%5FFEATURE%5FCONFIGURATION%5FOPTIONAL)`

Public constructors

AppWidgetProviderInfo

public AppWidgetProviderInfo ()

AppWidgetProviderInfo

public AppWidgetProviderInfo (Parcel in)

Unflatten the AppWidgetProviderInfo from a parcel.

Parameters
in Parcel

Public methods

clone

public AppWidgetProviderInfo clone ()

Creates and returns a copy of this object. The precise meaning of "copy" may depend on the class of the object. The general intent is that, for any object x, the expression:

x.clone() != x

will be true, and that the expression:

x.clone().getClass() == x.getClass()

will be true, but these are not absolute requirements. While it is typically the case that:

x.clone().equals(x)

will be true, this is not an absolute requirement.

By convention, the returned object should be obtained by callingsuper.clone. If a class and all of its superclasses (exceptObject) obey this convention, it will be the case thatx.clone().getClass() == x.getClass().

By convention, the object returned by this method should be independent of this object (which is being cloned). To achieve this independence, it may be necessary to modify one or more fields of the object returned by super.clone before returning it. Typically, this means copying any mutable objects that comprise the internal "deep structure" of the object being cloned and replacing the references to these objects with references to the copies. If a class contains only primitive fields or references to immutable objects, then it is usually the case that no fields in the object returned by super.clone need to be modified.

Returns
AppWidgetProviderInfo a clone of this instance.

describeContents

public int describeContents ()

Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. For example, if the object will include a file descriptor in the output of [writeToParcel(Parcel,int)](/reference/android/os/Parcelable#writeToParcel%28android.os.Parcel,%20int%29), the return value of this method must include the[CONTENTS_FILE_DESCRIPTOR](/reference/android/os/Parcelable#CONTENTS%5FFILE%5FDESCRIPTOR) bit.

Returns
int a bitmask indicating the set of special object types marshaled by this Parcelable object instance. Value is either 0 or CONTENTS_FILE_DESCRIPTOR

getActivityInfo

public ActivityInfo getActivityInfo ()

Returns the broadcast receiver that is providing this widget.

Returns
ActivityInfo This value cannot be null.

getProfile

public final UserHandle getProfile ()

Gets the user profile in which the provider resides.

Returns
UserHandle The hosting user profile.

loadDescription

public final CharSequence loadDescription (Context context)

Loads localized description for the app widget.

Description is intended to be displayed in the UI of the widget picker.

Parameters
context Context: Context for accessing resources. This value cannot be null.
Returns
CharSequence CharSequence for app widget description for the current locale. This value may be null.

loadIcon

public final Drawable loadIcon (Context context, int density)

Loads the icon to display for this AppWidget in the AppWidget picker. If not supplied in the xml, the application icon will be used. A client can optionally provide a desired density such as [DisplayMetrics.DENSITY_LOW](/reference/android/util/DisplayMetrics#DENSITY%5FLOW) [DisplayMetrics.DENSITY_MEDIUM](/reference/android/util/DisplayMetrics#DENSITY%5FMEDIUM), etc. If no density is provided, the density of the current display will be used.

The loaded icon corresponds to the android:icon attribute in the <receiver> element in the AndroidManifest.xml file.

Parameters
context Context: Context for accessing resources. This value cannot be null.
density int: The optional desired density as perDisplayMetrics.densityDpi.
Returns
Drawable The provider icon.

loadLabel

public final String loadLabel (PackageManager packageManager)

Loads the localized label to display to the user in the AppWidget picker.

Parameters
packageManager PackageManager: Package manager instance for loading resources.
Returns
String The label for the current locale.

loadPreviewImage

public final Drawable loadPreviewImage (Context context, int density)

Loads a preview of what the AppWidget will look like after it's configured. A client can optionally provide a desired density such as[DisplayMetrics.DENSITY_LOW](/reference/android/util/DisplayMetrics#DENSITY%5FLOW) [DisplayMetrics.DENSITY_MEDIUM](/reference/android/util/DisplayMetrics#DENSITY%5FMEDIUM), etc. If no density is provided, the density of the current display will be used.

The loaded image corresponds to the android:previewImage attribute in the <receiver> element in the AndroidManifest.xml file.

Parameters
context Context: Context for accessing resources. This value cannot be null.
density int: The optional desired density as perDisplayMetrics.densityDpi.
Returns
Drawable The widget preview image or null if preview image is not available.

toString

public String toString ()

Returns a string representation of the object.

Returns
String a string representation of the object.