アプリ ウィジェットを構成できる。たとえば時計ウィジェットでは 表示するタイムゾーンを設定します。
ユーザーがウィジェットの設定を構成できるようにするには、ウィジェット構成 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
から直接更新をリクエストします。
ウィジェットを適切に更新して設定アクティビティを閉じる手順の概要は以下のとおりです。
アクティビティを起動したインテントからアプリ ウィジェット 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); }
アクティビティの結果を
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);
ユーザーの設定に応じてウィジェットを構成します。
設定が完了したら、
getInstance(Context)
を呼び出してAppWidgetManager
のインスタンスを取得します。Kotlin
val appWidgetManager = AppWidgetManager.getInstance(context)
Java
AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
updateAppWidget(int,RemoteViews)
を呼び出して、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);
返すインテントを作成し、アクティビティの結果で設定してから、アクティビティを終了します。
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)をタップすることで、ウィジェットを再設定できます。
ウィジェットのデフォルト設定を使用する
ユーザーが
行います。これを行うには、両方の
configuration_optional
widgetFeatures
フィールドの reconfigurable
フラグ。これにより、ユーザーがウィジェットを追加した後の設定アクティビティの起動が省略されます前述のとおり
ユーザーは、引き続きウィジェットを再構成できます。
できます。たとえば、時計ウィジェットは初期設定をバイパスして、
デバイスのタイムゾーンをデフォルトで表示します。
次に、構成アクティビティを両方としてマークする方法の例を示します。 再構成可能(オプション):
<appwidget-provider
android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>