Android 5.0 removes support for lockscreen widgets; it continues to support +widgets on the home screen.
\ No newline at end of file diff --git a/docs/html/guide/topics/appwidgets/index.jd b/docs/html/guide/topics/appwidgets/index.jd index a783ad1a4f05a..c9575e025f053 100644 --- a/docs/html/guide/topics/appwidgets/index.jd +++ b/docs/html/guide/topics/appwidgets/index.jd @@ -26,12 +26,6 @@ fromresizeMode). Introduced in And
the widget can be resized. This field has no effect if it is greater than {@code minWidth} or if
horizontal resizing isn't enabled (see resizeMode). Introduced in Android 4.0.widgetCategory attribute declares whether your App Widget can be displayed on the home screen,
-the lock screen (keyguard), or both. Values for this attribute include "home_screen" and "keyguard". A widget that
-is displayed on both needs to ensure that it follows the design guidelines for both widget classes. For more
-information, see Enabling App Widgets on the Lockscreen. The default value is "home_screen". Introduced in Android 4.2.
-initialKeyguardLayout attribute points to the layout resource
-that defines the lock screen App Widget layout. This works the same way as the
-{@link android.appwidget.AppWidgetProviderInfo#initialLayout android:initialLayout},
-in that it provides a layout that can appear immediately until your app widget is initialized and able to update
-the layout. Introduced in Android 4.2.widgetCategory attribute declares whether your App Widget
+can be displayed on the home screen ({@code home_screen}), the lock screen
+({@code keyguard}), or both. Only Android versions lower than 5.0 support
+lock-screen widgets. For Android 5.0 and higher, only {@code home_screen} is
+valid.Android 4.2 introduces the ability for users to add widgets to the lock screen. To indicate that your app widget is available for use on the lock screen, declare the {@link android.appwidget.AppWidgetProviderInfo#widgetCategory android:widgetCategory} attribute in the XML file that specifies your {@link android.appwidget.AppWidgetProviderInfo}. This attribute supports two values: "home_screen" and "keyguard". An app widget can declare support for one or both.
- -By default, every app widget supports placement on the Home screen, so "home_screen" is the default value for the -{@link android.appwidget.AppWidgetProviderInfo#widgetCategory android:widgetCategory} attribute. If you want your app widget to be available for the lock screen, add the "keyguard" value:
--<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android" - ... - android:widgetCategory="keyguard|home_screen"> -</appwidget-provider> -- -
If you declare a widget to be displayable on both keyguard (lockscreen) and home, it's likely that you'll want to customize the widget depending on where it is displayed. For example, you might create a separate layout file for keyguard vs. home. The next step is to detect the widget category at runtime and respond accordingly. - -You can detect whether your widget is on the lockscreen or home screen by calling -{@link android.appwidget.AppWidgetManager#getAppWidgetOptions getAppWidgetOptions()} -to get the widget's options as a {@link android.os.Bundle}. The returned bundle will include the key -{@link android.appwidget.AppWidgetManager#OPTION_APPWIDGET_HOST_CATEGORY}, whose value will be one of {@link android.appwidget.AppWidgetProviderInfo#WIDGET_CATEGORY_HOME_SCREEN} or -{@link android.appwidget.AppWidgetProviderInfo#WIDGET_CATEGORY_KEYGUARD}. This value is determined by the host into which the widget is bound. In the {@link android.appwidget.AppWidgetProvider}, you can then check the widget's category, for example:
- --AppWidgetManager appWidgetManager; -int widgetId; -Bundle myOptions = appWidgetManager.getAppWidgetOptions (widgetId); - -// Get the value of OPTION_APPWIDGET_HOST_CATEGORY -int category = myOptions.getInt(AppWidgetManager.OPTION_APPWIDGET_HOST_CATEGORY, -1); - -// If the value is WIDGET_CATEGORY_KEYGUARD, it's a lockscreen widget -boolean isKeyguard = category == AppWidgetProviderInfo.WIDGET_CATEGORY_KEYGUARD; -- -
Once you know the widget's category, you can optionally load a different base layout, set different properties, and so on. For example:
- --int baseLayout = isKeyguard ? R.layout.keyguard_widget_layout : R.layout.widget_layout; -- - -
You should also specify an initial layout for your app widget when on the lock screen with the -{@link android.appwidget.AppWidgetProviderInfo#initialKeyguardLayout android:initialKeyguardLayout} attribute. This works the same way as the -{@link android.appwidget.AppWidgetProviderInfo#initialLayout android:initialLayout}, in that it provides a layout that can appear immediately until your app widget is initialized and able to update the layout.
- -When a widget is hosted on the lockscreen, the framework ignores the {@code minWidth}, {@code minHeight}, {@code minResizeWidth}, and {@code minResizeHeight} fields. If a widget is also a home screen widget, these parameters are still needed as they're still used on home, but they will be ignored for purposes of the lockscreen.
- -The width of a lockscreen widget always fills the provided space. For the height of a lockscreen widget, you have the following options:
- -Android 3.0 introduces app widgets with collections. These kinds of App