ユーザーがアプリ ウィジェットを設定できるようにする

アプリ ウィジェットは構成可能です。たとえば、時計ウィジェットでは、表示するタイムゾーンをユーザーが構成できます。

ユーザーがウィジェットの設定を構成できるようにするには、ウィジェット 構成 Activityを作成します。このアクティビティは 指定した構成オプションに応じて、ウィジェットの作成時 または後で、アプリ ウィジェット ホストによって自動的に起動されます。

構成アクティビティを宣言する

構成アクティビティは、Android マニフェスト ファイルで通常のアクティビティとして宣言します。アプリ ウィジェット ホストは ACTION_APPWIDGET_CONFIGURE アクションで起動するため、アクティビティはこのインテントを受け入れる必要があります。例:

<activity android:name=".ExampleAppWidgetConfigurationActivity">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
    </intent-filter>
</activity>

AppWidgetProviderInfo.xml ファイルで、android:configure 属性を使用してアクティビティを宣言します。このファイルの宣言について詳しくは、こちらをご覧ください 。構成アクティビティを宣言する方法の例を次に示します。

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    ... >
</appwidget-provider>

ランチャーはパッケージ範囲外から参照するため、アクティビティは完全修飾名前空間を使用して宣言されます。

これで、構成アクティビティを開始する準備ができました。次に、実際のアクティビティを実装する必要があります。

構成アクティビティを実装する

アクティビティを実装する際は、次の 2 つの重要な点に注意してください。

  • アプリ ウィジェット ホストが構成アクティビティを呼び出し、構成アクティビティは常に結果を返す必要があります。結果には、アクティビティを起動したインテントから渡されたアプリ ウィジェット ID（インテント エクストラに EXTRA_APPWIDGET_IDとして保存される）が含まれている必要があります。
  • 構成アクティビティが起動されると、システムは ACTION_APPWIDGET_UPDATE ブロードキャストを送信しません。つまり、ウィジェットの作成時に onUpdate() メソッドは呼び出されません。 ウィジェットを初めて作成するときに AppWidgetManager から更新をリクエストするのは、構成アクティビティの役割です。ただし、onUpdate() は以後の更新のときには呼び出されます。スキップされるのは初回だけです。

設定から結果を返してウィジェットを更新する方法の例として、次のセクションのコード スニペットをご覧ください。

構成アクティビティからウィジェットを更新する

ウィジェットで構成アクティビティを使用する場合、構成完了時にウィジェットを更新することはアクティビティの責任です。これを行うには、 AppWidgetManagerから直接更新をリクエストします。

ウィジェットを適切に更新して構成アクティビティを閉じる手順の概要は次のとおりです。

  1. アクティビティを起動したインテントからアプリ ウィジェット ID を取得します。

    Kotlin

    val appWidgetId = intent?.extras?.getInt(
        AppWidgetManager.EXTRA_APPWIDGET_ID,
        AppWidgetManager.INVALID_APPWIDGET_ID
) ?: AppWidgetManager.INVALID_APPWIDGET_ID

    Java

    Intent intent = getIntent();
Bundle extras = intent.getExtras();
int appWidgetId = AppWidgetManager.INVALID_APPWIDGET_ID;
if (extras != null) {
    appWidgetId = extras.getInt(
            AppWidgetManager.EXTRA_APPWIDGET_ID,
            AppWidgetManager.INVALID_APPWIDGET_ID);
}

  2. アクティビティの結果を RESULT_CANCELED に設定します。

    このようにすると、ユーザーが最後まで完了する前にアクティビティを停止した場合、構成がキャンセルされたことがシステムからアプリ ウィジェット ホストに通知され、ホストはウィジェットを追加しません。

    Kotlin

    val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
setResult(Activity.RESULT_CANCELED, resultValue)

    Java

    int resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
setResult(Activity.RESULT_CANCELED, resultValue);

  3. ユーザーの設定に従ってウィジェットを構成します。

  4. 構成が完了したら、 AppWidgetManager を呼び出して getInstance(Context) のインスタンスを取得します。

    Kotlin

    val appWidgetManager = AppWidgetManager.getInstance(context)

    Java

    AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

  5. RemoteViews レイアウトでウィジェットを更新します。 updateAppWidget(int,RemoteViews) を呼び出して

    Kotlin

    val views = RemoteViews(context.packageName, R.layout.example_appwidget)
appWidgetManager.updateAppWidget(appWidgetId, views)

    Java

    RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget);
appWidgetManager.updateAppWidget(appWidgetId, views);

  6. 返すインテントを作成し、アクティビティの結果で設定してから、アクティビティを終了します。

    Kotlin

    val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
setResult(Activity.RESULT_OK, resultValue)
finish()

    Java

    Intent resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
setResult(RESULT_OK, resultValue);
finish();

例については、GitHub の ListWidgetConfigureActivity.kt サンプルクラスをご覧ください。

ウィジェットの構成オプション

デフォルトでは、アプリ ウィジェット ホストは、ユーザーがウィジェットをホーム画面に追加した直後に、構成アクティビティを 1 回だけ起動します。ただし、デフォルトのウィジェット構成を指定することで、ユーザーが既存のウィジェットを再構成できるようにするオプションや、初期ウィジェット構成をスキップするオプションを指定できます。

配置したウィジェットをユーザーが再設定できるようにする

ユーザーが既存のウィジェットを再構成できるようにするには、 reconfigurable フラグを widgetFeatures のappwidget-provider属性で指定します。詳しくは、ファイル の宣言に関するガイドをご覧くださいAppWidgetProviderInfo.xml 。例:

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable">
</appwidget-provider>

ユーザーは、ウィジェットを長押しして、 [**再設定**] ボタンをタップすることで、ウィジェットを再構成できます。このボタンは、図 1 の 1 のラベルが付いています。

右下にボタンが表示される
図 1. ウィジェットの [再設定] ボタン。

ウィジェットのデフォルト設定を使用する

ユーザーが初期設定の手順をスキップできるようにすることで、ウィジェットのエクスペリエンスをよりシームレスにすることができます。これを行うには、 configuration_optional と reconfigurable フラグの両方を widgetFeatures フィールドで指定します。これにより、ユーザーがウィジェットを追加した後の設定アクティビティの起動が省略されます 前述のように、ユーザーは後でウィジェットを再構成できます。たとえば、時計ウィジェットでは初期設定を省略して、デフォルトでデバイスのタイムゾーンを表示できます。

構成アクティビティを再構成可能かつ省略可能としてマークする方法の例を次に示します。

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>