This module demonstrates how to build Android AppWidgets with Jetpack Glance and Remote Compose.

The new set of APIs allows an application to build more engaging and beautiful widgets. Use this sample together with the App widget guides.

• Android 12 (API level 31) for Jetpack Glance samples; Android 17 (API level 37) for Remote Compose samples
• Android Studio Chipmunk or newer

The remote_compose directory contains the Android Pet Widget (AndroidPetWidget.kt) and StoreActivity.kt. This sample is a work in progress. We will add more features in the coming months.

For most cases, use Jetpack Glance to build Android widgets. Jetpack Glance is a backwards-compatible library with developer tools (such as Canonical Layouts) that help you build high-quality widgets across form factors.

However, you cannot build some widget use cases with Jetpack Glance, such as widgets that require animations. Jetpack Glance uses the legacy RemoteViews system:

• RemoteViews cannot evaluate mathematical expressions on the host (for example, to continuously rotate an object).
• The Android system controls RemoteViews and limits the size and frequency of widget updates.

Remote Compose does not replace Jetpack Glance. Build most production widgets with Jetpack Glance for backwards compatibility and stable developer tools. Remote Compose widgets work best on Android 17 and higher devices.

Note: Remote Compose is in alpha and the API surface can change. Send us your feedback.

These layouts demonstrate how to write responsive, high-quality layouts for use with your Glance widgets.

The layouts directory contains following layout categories:

• collections

  • Action list
  • Check list
  • Image grid
  • Image text list

• text

  • Long Text
  • Text with image
  • Full-bleed image with snap scroll

• toolbars

  • Toolbar with app name
  • Toolbar with search bar
  • Toolbar with expressive shape

Each of these layout categories contains a layout sub-directory that can be copied to your project to reuse the layouts in your code.

The {layoutType}Layout file e.g. ToolBarLayout contains:

• A top level composable e.g. ToolBarLayout,
• Sub components,
• A breakpoints definition e.g. ToolBarLayoutSize,
• Constants / dimensions e.g. ToolBarLayoutDimens,
• Followed by Android Studio Preview for the layout.

Read more about the layouts: https://developer.android.com/design/ui/mobile/guides/widgets/layouts

More showcasing resources in the screenshots folder

In addition, the AppWidgets.kt showcases how to request the launcher to “pin” an appwidget.

When creating a new run configuration, it’s important to ensure that the widget is recreated without launching a new activity. Follow these steps to do so:

1. In Android Studio, select Run > Edit Configurations.
2. In the Run/Debug Configurations dialog, select Always install with package manager….
3. Under Launch Options, in the Launch menu, select Nothing.

This will ensure that the widget is recreated but no activity is launched.

• Stack Overflow: https://stackoverflow.com/questions/tagged/glance-appwidget
• Channel #glance at KotlinLang Slack (request to join).

If you’ve found an error in this sample, please file an issue at https://github.com/android/user-interface.

For API-related issues, please file any bugs at: https://issuetracker.google.com/issues/new?component=1097239&template=1611667

Copyright 2023 The Android Open Source Project
 
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.