AppWidgetの作り方

AppWidget（以下、ウィジェット）は、Androidアプリに組み込まれる形で配布され、ユーザーが自身の端末のホームスクリーン上に自由に配置できる小さなアプリです。

ウィジェットの定義ファイルのなかで、更新間隔を指定しておくことで、一定の時間間隔で表示をアップデートしていくことが可能です。表示の更新のタイミングが限られているため、「常駐アプリ」とはかならずしも分類できませんが、画面＝Activityを持つAndroidアプリ本体の、高機能なランチャー程度には活用できます。

※より正確に言えば、ウィジェットとは、ユーザーがウィジェットを作成したときや、あらかじめ定められた時間間隔が経過したときに、Androidプラットフォームのシステム側からメッセージを受け取るブロードキャスト・レシーバー（AppWidgetプロバイダー）により初期化・更新されるView、です。

Androidアプリにウィジェットを組み込むには、以下のファイルが必要になります。

①AppWidgetProviderInfo （XML）
ウィジェットのメタデータを記述するもので、ウィジェットの表示を構成するためのレイアウト・リソース、表示更新の頻度、AppWidgetプロバイダー（後述）のクラス名を、XMLで記述します。

②AppWidgetProvider （Class）
ウィジェットの初期化などで呼び出される処理を実装するAppWidgetプロバイダー（ブロードキャスト・レシーバーの一種）の実装クラスです。

③レイアウト （XML）
ウィジェットの表示に使用されるレイアウト・リソースです。サイズの指定方法が独特？です。

④AndroidManifest（XML）
言わずと知れたAndroidアプリのメタデータやコンポーネントについての記述をするためのXMLです。AppWidgetProviderがブロードキャスト・レシーバーの一種であることから、記述の追加が必要になります。

以下では、Android Developpersのリファレンスのコードを参考に説明を行います。

1. AndroidManifestへの登録

Intentフィルターの部分と、AppWidgetプロバイダーのメタデータについて記述したXMLの在所を示す部分が重要です。

<receiver android:name="ExampleAppWidgetProvider">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
    <meta-data android:name="android.appwidget.provider"
               android:resource="@xml/example_appwidget_info" />

</receiver>

2. AppWidgetプロバイダーのメタデータの記述

AndroidManifestで示した場所に、プロバイダーのメタデータを記述したXMLを配置します。

ウィジェットのサイズ指定の単位となるのは、Android端末のホームスクリーンをタテヨコ4分割した「セル」の幅／高さであり、Android Developpersでは、「(セル数 * 74) - 2」という数式が紹介されています。
この数値を、dp（画面密度非依存ピクセル）でminWidthとminHeight属性に指定することで、ウィジェットのサイズを指定します。ウィジェットは、ユーザーによりサイズ変更可能です。

updatePeriodMillis属性では、ウィジェット の更新間隔を指定します。単位はミリ秒となります。
更新は最短で30分以上の間隔を置いて実行されます。この属性に0を指定すると、更新は行われなくなり、後述のAppWidgetプロバイダーのonUpdateメソッドは、ウィジェット作成時にしか呼ばれなくなります。

configure属性は、ウィジェットにセッティング用画面がある場合のものです。ウィジェットが作成された際にここで指定したActivityが実行され、ウィジェットのプロパティを初期化すること出来るようです。（詳しくはこちらを参照。）

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="294dp"
    android:minHeight="72dp"
    android:updatePeriodMillis="86400000"
    android:initialLayout="@layout/example_appwidget"
    android:configure="com.example.android.ExampleAppWidgetConfigure">
</appwidget-provider>

3. ウィジェットのレイアウトを作成

ウィジェットのレイアウトで使用できるViewGroupとViewには制限があるようです。
ViewGroupについては、FrameLayout、LinearLayout、RelativeLayout。
Viewについては、AnalogClock、Button、Chronometer、ImageButton、ImageView、ProgressBar、TextViewです。
ButtonやImageViewなどのほかに、AnalogClockなどが挙げられているのがおもしろいところです。

4. AppWidgetプロバイダーを実装

AppWidgetProviderクラスの中で、一番重要なのは、onUpdateメソッドでしょう。
このメソッドは、プロバイダーのメタデータの記述（XML）の中で指定した更新タイミングに呼び出されます。

また、より重要なこととして、 ユーザーによりウィジェットが画面に追加された際にも、このメソッドが呼び出されます。したがって、このメソッドの中でウィジェットの表示の初期化や、必要なサービスの起動などを実行することになります。

しかもです。このメソッドの第3引数は、AppWidgetインスタンスのID配列です。この点について、Android Developpersの説明では、大意以下のように述べています。

ユーザーは同じAppWidgetのインスタンスをいくつも作成することができる。例えば、あるAppWidgetが、2時間ごとに更新されるよう指定されていたとする。まず1つめのAppWidgetインスタンスがホームスクリーン上に作成され、その1時間後、もう1つのAppWidgetインスタンスが作成される。1つめのAppWidgetがスクリーン上に追加されてから2時間後、onUpdateメソッドが呼ばれる。しかしその1時間後（2つ目のインスタンスが作成されてから2時間後）にonUpdateが呼ばれることはない。更新のスケジューリングは、あくまでも1つめのAppWidgetインスタンスの生成を基準に行われる。

つまり、ここでupdatePeriodMillis属性があくまでもプロバイダーの属性であり、ウィジェットの属性ではなかったことがここで思い出されるわけですが、いずれにしてもこのメソッドはホームスクリーン上のすべてのウィジェットについて、その更新／初期化を一時に実施するものであるということです。

したがって、ウィジェットのボタンをクリックしたときに、アプリケーション本体となるActivityを起動する、といったことをする場合、以下のようなコードを記述すればよいことになります。

public class ExampleAppWidgetProvider extends AppWidgetProvider {

    public void onUpdate(Context context,
        AppWidgetManager appWidgetManager, int[] appWidgetIds) {
       
        final int N = appWidgetIds.length;

        // このプロバイダーに所属するAppWidgetのそれぞれについて処理を行う
        for (int i=0; i
            int appWidgetId = appWidgetIds[i];

            // ExampleActivityを起動するIntentを生成
            Intent intent = new Intent(context, ExampleActivity.class);
           
            // それをPendingIntentに変換する
            PendingIntent pendingIntent = PendingIntent.getActivity(context, 0, intent, 0);

            // AppWidgetのレイアウト・リソースを取得
            RemoteViews views = new RemoteViews(context.getPackageName(),
                R.layout.appwidget_provider_layout);
           
            // 第1引数にClickリスナーを設定したいViewのID、
            // 第2引数にClickされた際に発行されるPendingIntentを指定
            views.setOnClickPendingIntent(R.id.button, pendingIntent);

            // IDで指定したAppWidgetの表示を、先ほど取得し、リスナーをセットした
            // RemoteViewsで更新する／初期化するようAppWidgetManagerに指示
            appWidgetManager.updateAppWidget(appWidgetId, views);
        }
    }
}

onUpdateメソッドに対応するものとしては、onDeletedがあります。

onDeleted(Context context, int[] appWidgetIds)

その他のメソッドとしては、onEnabled、onDisabled、onReceiveがあります。これらがonUpdateメソッド同様、あくまでもプロバイダーの生成～破棄までのライフサイクルに関わってくるものであり、AppWidgetの個別のインスタンスに関連するものではない、ということに注意してください。

これらのメソッドの解説は、Android DeveloppersのAPIリファレンスにあります。