Android 原始碼徹底研究系列 - 鬧鐘程式, App Widgets (2)

Android Source Code Internals - Alarm Clock, App Widgets (2)

從 Android v1.5 開始，終於開放 APIs，讓第三方開發者可以寫些 widgets，讓使用者可以放在手機的桌面上。一般手機就有內建幾個小 widgets，其中的 "Analog Clock" widget，就是由 Alarm Clock 這隻鬧鐘程式所提供的。

這次我們就來研究一下，這個 Analog Clock widget 是如何寫出來的。

不過，如果你對如何寫 App Widgets 一點概念都沒有的話，底下有幾個很好的參考資料，一定要先讀過：

• App Widgets Developer Guide - 這有很詳細的入門介紹與說明，建議你先讀這篇。
• Introducing home screen widgets and the AppWidget framework - 這篇以一個實例來說明如何寫 App Widgets。
• Widget Design Guidelines - 這篇說明的是，設計 widget UI 時，應該要注意的事項，及所要遵循的法則。
• 另外，在 API Demos 這個範例程式中，也有個 App Widgets 的範例。

要寫個 App Widget，首先你要先用 XML 寫個 AppWidgetProviderInfo，而且這個檔案建議放在 res/xml 中。在鬧鐘程式中，你可以找到 res/xml/analog_appwidget.xml 這個檔案。它的內容如下：

//res/xml/analog_appwidget.xml <appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android" android:minWidth="146dip" android:minHeight="146dip" android:updatePeriodMillis="0" android:initialLayout="@layout/analog_appwidget" > </appwidget-provider>

由 minWidth 及 minHeight 這兩個屬性來看，就可以了解，這個 App Widget 要佔桌面 2x2 cells 大小的空間。

updatePeriodMillis 的值為 0？那這個時鐘是如何自己動的呢？這我在 Android 原始碼徹底研究系列 - 鬧鐘程式, AnalogClock (1) 一文中，就已經解釋過 Analog Clock 是如何自我更新的。還不清楚的，先讀一下這篇。

initialLayout 這個屬性，從名字看起來，就知道它是用來描述這個 App Widget 的畫面設計。由其值我們可以知道，這個 App Widget 的畫面設計，是在 res/layout/analog_appwidget.xml 中。它的內容如下：

//res/layout/analog_appwidget.xml <AnalogClock xmlns:android="http://schemas.android.com/apk/res/android" android:dial="@drawable/appwidget_clock_dial" android:hand_hour="@drawable/appwidget_clock_hour" android:hand_minute="@drawable/appwidget_clock_minute" android:layout_width="fill_parent" android:layout_height="fill_parent" />

果然不出我們所料，這個 App Widget 的畫面設計，就只是一個簡單的 AnalogClock 。時鐘與時，分針圖檔就是分別透過 dial, hand_hour, hand_minute 這三個屬性來指定。

要注意的是，目前在 App Widget 的畫面設計檔中，你只能使用 FrameLayout, LinearLayout, RelativeLayout, AnalogClock, Button, Chronometer, ImageButton, ImageView, ProgressBar, TextView 等元件，其他元件都不能用。

寫好 AppWidgetProviderInfo XML 檔與 App Widget 畫面設計檔，別忘了，還要在 AndroidManifest.xml 中，宣告你的 App Widget Provider。

//AndroidManifest.xml, #55~#60 <receiver android:name="AnalogAppWidgetProvider" android:label="@string/analog_gadget"> <intent-filter> <action android:name="android.appwidget.action.APPWIDGET_UPDATE" /> </intent-filter> <meta-data android:name="android.appwidget.provider" android:resource="@xml/analog_appwidget" /> </receiver>

在這裡，他指明了這個 App Widget Provider 是要由 AnalogAppWidgetProvider 這個類別來處理。這個類別的原始碼就是 AnalogAppWidgetProvider.java。

//#49~#65 public class AnalogAppWidgetProvider extends BroadcastReceiver { static final String TAG = "AnalogAppWidgetProvider"; public void onReceive(Context context, Intent intent) { String action = intent.getAction(); if (AppWidgetManager.ACTION_APPWIDGET_UPDATE.equals(action)) { RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.analog_appwidget); int[] appWidgetIds = intent.getIntArrayExtra(AppWidgetManager.EXTRA_APPWIDGET_IDS); AppWidgetManager gm = AppWidgetManager.getInstance(context); gm.updateAppWidget(appWidgetIds, views); } } }

在這個類別中，主要的工作就是建立 App Widget，並透過 AppWidgetManager 發佈到桌面上。

鬧鐘程式所提供的 "Analog Clock" widget，其實功能很陽春，也沒有用到所有 App Widgets 提供的所有功能。不過，對於想要了解如何寫個 App Widget 的你，應該是有很大的幫助。如果你想要找個較為完整的 App Widget 範例，我建議你看一下 API Demos 這個範例程式。