[[["わかりやすい","easyToUnderstand","thumb-up"],["問題の解決に役立った","solvedMyProblem","thumb-up"],["その他","otherUp","thumb-up"]],[["必要な情報がない","missingTheInformationINeed","thumb-down"],["複雑すぎる / 手順が多すぎる","tooComplicatedTooManySteps","thumb-down"],["最新ではない","outOfDate","thumb-down"],["翻訳に関する問題","translationIssue","thumb-down"],["サンプル / コードに問題がある","samplesCodeIssue","thumb-down"],["その他","otherDown","thumb-down"]],["最終更新日 2025-08-21 UTC。"],[],[],null,["# Enable users to configure app widgets\n\nApp widgets can be configurable. For example, a clock widget can let users\nconfigure which time zone to display.\n\nIf you want to let users configure your widget's settings, create a widget\nconfiguration [`Activity`](/reference/android/app/Activity). This activity is\nautomatically launched by the app widget host either when the widget is created\nor later, depending on the [configuration options](#widget-config-options) you\nspecify.\n\nDeclare the configuration activity\n----------------------------------\n\nDeclare the configuration activity as a normal activity in the Android manifest\nfile. The app widget host launches it with the\n[`ACTION_APPWIDGET_CONFIGURE`](/reference/android/appwidget/AppWidgetManager#ACTION_APPWIDGET_CONFIGURE)\naction, so the activity needs to accept this intent. For example: \n\n \u003cactivity android:name=\".ExampleAppWidgetConfigurationActivity\"\u003e\n \u003cintent-filter\u003e\n \u003caction android:name=\"android.appwidget.action.APPWIDGET_CONFIGURE\"/\u003e\n \u003c/intent-filter\u003e\n \u003c/activity\u003e\n\nDeclare the activity in the `AppWidgetProviderInfo.xml` file with the\n`android:configure` attribute. See more information about\n[declaring this file](/guide/topics/appwidgets#AppWidgetProviderInfo). Here's an example of\nhow to declare the configuration activity: \n\n \u003cappwidget-provider xmlns:android=\"http://schemas.android.com/apk/res/android\"\n ...\n android:configure=\"com.example.android.ExampleAppWidgetConfigurationActivity\"\n ... \u003e\n \u003c/appwidget-provider\u003e\n\nThe activity is declared with a fully qualified namespace, because the launcher\nreferences it from outside your package scope.\n\nThat's all you need to start a configuration activity. Next, you need to\nimplement the actual activity.\n\nImplement the configuration activity\n------------------------------------\n\nThere are two important points to remember when you implement the activity:\n\n- The app widget host calls the configuration activity, and the configuration activity must always return a result. The result must include the App Widget ID passed by the intent that launched the activity---saved in the intent extras as [`EXTRA_APPWIDGET_ID`](/reference/android/appwidget/AppWidgetManager#EXTRA_APPWIDGET_ID).\n- The system doesn't send the [`ACTION_APPWIDGET_UPDATE`](/reference/android/appwidget/AppWidgetManager#ACTION_APPWIDGET_UPDATE) broadcast when a configuration activity is launched, which means it doesn't call the [`onUpdate()`](/reference/android/appwidget/AppWidgetProvider#onUpdate(android.content.Context,%20android.appwidget.AppWidgetManager,%20int[])) method when the widget is created. It's the responsibility of the configuration activity to request an update from the `AppWidgetManager` when creating the widget for the first time. However, `onUpdate()` is called for subsequent updates---it is only skipped the first time.\n\nSee the code snippets in the following section for an example of how to return a\nresult from the configuration and update the widget.\n\n### Update the widget from the configuration activity\n\nWhen a widget uses a configuration activity, it's the responsibility of\nthe activity to update the widget when configuration is complete. You can do so\nby requesting an update directly from the\n[`AppWidgetManager`](/reference/android/appwidget/AppWidgetManager).\n\nHere's a summary of the procedure to properly update the widget and close the\nconfiguration activity:\n\n1. Get the App Widget ID from the intent that launched the activity:\n\n ### Kotlin\n\n ```kotlin\n val appWidgetId = intent?.extras?.getInt(\n AppWidgetManager.EXTRA_APPWIDGET_ID,\n AppWidgetManager.INVALID_APPWIDGET_ID\n ) ?: AppWidgetManager.INVALID_APPWIDGET_ID\n ```\n\n ### Java\n\n ```java\n Intent intent = getIntent();\n Bundle extras = intent.getExtras();\n int appWidgetId = AppWidgetManager.INVALID_APPWIDGET_ID;\n if (extras != null) {\n appWidgetId = extras.getInt(\n AppWidgetManager.EXTRA_APPWIDGET_ID,\n AppWidgetManager.INVALID_APPWIDGET_ID);\n }\n ```\n2. Set the activity result to `RESULT_CANCELED`.\n\n This way, if the user backs out of the activity before reaching the end, the\n system notifies the app widget host that the configuration is canceled and\n the host doesn't add the widget: \n\n ### Kotlin\n\n ```kotlin\n val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)\n setResult(Activity.RESULT_CANCELED, resultValue)\n ```\n\n ### Java\n\n ```java\n int resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);\n setResult(Activity.RESULT_CANCELED, resultValue);\n ```\n3. Configure the widget according to the user's preferences.\n\n4. When the configuration is complete, get an instance of the\n `AppWidgetManager` by calling [`getInstance(Context)`](/reference/android/appwidget/AppWidgetManager#getInstance(android.content.Context)):\n\n ### Kotlin\n\n ```kotlin\n val appWidgetManager = AppWidgetManager.getInstance(context)\n ```\n\n ### Java\n\n ```java\n AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);\n ```\n5. Update the widget with a\n [`RemoteViews`](/reference/android/widget/RemoteViews) layout by calling\n [`updateAppWidget(int,RemoteViews)`](/reference/android/appwidget/AppWidgetManager#updateAppWidget(int,%20android.widget.RemoteViews)):\n\n ### Kotlin\n\n ```kotlin\n val views = RemoteViews(context.packageName, R.layout.example_appwidget)\n appWidgetManager.updateAppWidget(appWidgetId, views)\n ```\n\n ### Java\n\n ```java\n RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget);\n appWidgetManager.updateAppWidget(appWidgetId, views);\n ```\n6. Create the return intent, set it with the activity result, and\n finish the activity:\n\n ### Kotlin\n\n ```kotlin\n val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)\n setResult(Activity.RESULT_OK, resultValue)\n finish()\n ```\n\n ### Java\n\n ```java\n Intent resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);\n setResult(RESULT_OK, resultValue);\n finish();\n ```\n\nSee the\n[`ListWidgetConfigureActivity.kt`](https://github.com/android/user-interface-samples/blob/main/AppWidget/app/src/main/java/com/example/android/appwidget/rv/list/ListWidgetConfigureActivity.kt)\nsample class on GitHub for an example.\n\nWidget configuration options\n----------------------------\n\nBy default, the app widget host only launches the configuration activity once,\nimmediately after the user adds the widget to their home screen. However, you\ncan specify options that let you enable users to reconfigure existing widgets or\nskip initial widget configuration by providing a default widget configuration.\n| **Note:** These options are only available starting in Android 12 (API level 31). You can specify them for previous versions of Android, but the system ignores them and follows the default behavior.\n\n### Enable users to reconfigure placed widgets\n\nTo let users reconfigure existing widgets, specify the\n[`reconfigurable`](/reference/android/appwidget/AppWidgetProviderInfo#WIDGET_FEATURE_RECONFIGURABLE)\nflag in the\n[`widgetFeatures`](/reference/android/appwidget/AppWidgetProviderInfo#widgetFeatures)\nattribute of `appwidget-provider`. See the guide to [declaring the\n`AppWidgetProviderInfo.xml` file](/guide/topics/appwidgets#AppWidgetProviderInfo) for more\ninformation. For example: \n\n \u003cappwidget-provider\n android:configure=\"com.myapp.ExampleAppWidgetConfigurationActivity\"\n android:widgetFeatures=\"reconfigurable\"\u003e\n \u003c/appwidget-provider\u003e\n\nUsers can reconfigure their widget by touching \\& holding the widget and tapping\nthe **Reconfigure** button, which is labeled\n1 in figure 1.\n**Figure 1.** Widget **Reconfigure** button. **Note:** The `reconfigurable` flag was introduced in Android 9 (API level 28), but it was not widely supported until Android 12.\n\n### Use the widget's default configuration\n\nYou can provide a more seamless widget experience by letting users skip the\ninitial configuration step. To do this, specify both the\n[`configuration_optional`](/reference/android/appwidget/AppWidgetProviderInfo#WIDGET_FEATURE_CONFIGURATION_OPTIONAL)\nand `reconfigurable` flags in the `widgetFeatures` field. This bypasses\nlaunching the configuration activity after a user adds the widget. As mentioned\npreviously, the user can still [reconfigure the widget](#reconfigure-widgets)\nafterward. For example, a clock widget can bypass the initial configuration and\nshow the device time zone by default.\n\nHere is an example of how to mark your configuration activity as both\nreconfigurable and optional: \n\n \u003cappwidget-provider\n android:configure=\"com.myapp.ExampleAppWidgetConfigurationActivity\"\n android:widgetFeatures=\"reconfigurable|configuration_optional\"\u003e\n \u003c/appwidget-provider\u003e"]]
