介紹桌面widgets和AppWidget框架(譯)

本文翻譯自Android Developers Blog:Introducing home screen widgets and the AppWidget framework

Android 1.5 SDK一個(gè)令人興奮的新特性是AppWidget framework,這個(gè)框架允許開(kāi)發(fā)者開(kāi)發(fā)widgets，這些widgets可以被用戶(hù)拖到用戶(hù)的桌面并且可以交互。widgets可以提供一個(gè)full-featured apps的預覽，例如可以顯示即將到來(lái)的日歷事件，或者一首后臺播放的歌曲的詳細信息。

當widgets被拖到桌面上，他們被指定一個(gè)保留的空間來(lái)顯示應用提供的自定義內容。用戶(hù)可以通過(guò)這個(gè)widget來(lái)和你的應用交互，例如暫?；蚯袚Q歌曲。如果你有一個(gè)后臺服務(wù)，你可以按照你自己的schedule更新你的widget，或者使用AppWidget framework提供的一個(gè)自動(dòng)的更新機制。

在更高層次上，每個(gè)widget就是一個(gè)BroadcastReceiver，他們用XML metadata來(lái)描述widget的細節。AppWidget framework通過(guò)broadcast intents和你的widget通信，例如當需要更新的時(shí)候。Widget更新使用RemoteViews被構建和發(fā)送。這個(gè)RemoteViews被包裝成一個(gè)layout和特定內容來(lái)顯示到桌面上。

你可以非常容易的添加widgets到你的應用中，在這篇文章里我將給一個(gè)簡(jiǎn)單的例子：寫(xiě)一個(gè)widget來(lái)顯示W(wǎng)iktionary “Word of the day.”你可以從這里獲取所有的源代碼，我將在這里解釋Appwidget相關(guān)的代碼。

首先，你需要一個(gè)XML metadata描述這個(gè)widget,包括你想在桌面上保留的區域，一個(gè)你想展示的初始的layout，和你打算何時(shí)更新。Android桌面默認使用cell-based layout,因而它會(huì )rounds你請求的尺寸為最接近的cell的尺寸。這是有點(diǎn)疑惑，不過(guò)這里有個(gè)公式可以幫助你：

Minimum size in dip = (Number of cells * 74dip) – 2dip

在這個(gè)例子中，我想使我們的widget占用2 cells的寬度和1 cell的高度，這意味著(zhù)我應該請求的最小尺寸為146dip * 72dip。我們將要每天更新一次我們的widget，大約是每86,400,000毫秒更新一次。以下是我們的widget的XML metadata:

接下來(lái)，讓我們把XML metadata捆綁到AndroidManifest的BroadcasrReicever:

最后，讓我們寫(xiě)BroadcastReceiver的代碼來(lái)處理AppWidget的請求。為了幫助widgets管理所有

broadcasr事件，有個(gè)helper class叫AppWidgetProvider，這里我們將使用這個(gè)類(lèi)。其中需要注意的最重要的一件事是我們將調用一個(gè)后臺服務(wù)執行定期的更新。這是因BroadcastReceivers是一個(gè)Application Not Responding(ANR) timer,這意味著(zhù)如果運行時(shí)間太長(cháng)，可能需要提示用戶(hù)強制關(guān)閉我們的應用。制作一個(gè)web請求可能需要花費一些時(shí)間，因此我們使用服務(wù)來(lái)避免ANR timeouts.

/**

* Define a simple widget that shows the Wiktionary “Word of the day.” To build

* an update we spawn a background {@link Service} to perform the API queries.

*/

public class WordWidget extends AppWidgetProvider {

@Override

public void onUpdate(Context context, AppWidgetManager appWidgetManager,

int[] appWidgetIds) {

// To prevent any ANR timeouts, we perform the update in a service

context.startService(new Intent(context, UpdateService.class));

}

public static class UpdateService extends Service {

@Override

public void onStart(Intent intent, int startId) {

// Build the widget update for today

RemoteViews updateViews = buildUpdate(this);

// Push update for this widget to the home screen

ComponentName thisWidget = new ComponentName(this, WordWidget.class);

AppWidgetManager manager = AppWidgetManager.getInstance(this);

manager.updateAppWidget(thisWidget, updateViews);

}

/**

* Build a widget update to show the current Wiktionary

* “Word of the day.” Will block until the online API returns.

*/

public RemoteViews buildUpdate(Context context) {

// Pick out month names from resources

Resources res = context.getResources();

String[] monthNames = res.getStringArray(R.array.month_names);

// Find current month and day

Time today = new Time();

today.setToNow();

// Build today’s page title, like “Wiktionary:Word of the day/March 21″

String pageName = res.getString(R.string.template_wotd_title,

monthNames[today.month], today.monthDay);

RemoteViews updateViews = null;

String pageContent = “”;

try {

// Try querying the Wiktionary API for today’s word

SimpleWikiHelper.prepareUserAgent(context);

pageContent = SimpleWikiHelper.getPageContent(pageName, false);

} catch (ApiException e) {

Log.e(”WordWidget”, “Couldn’t contact API”, e);

} catch (ParseException e) {

Log.e(”WordWidget”, “Couldn’t parse API response”, e);

}

// Use a regular expression to parse out the word and its definition

Pattern pattern = Pattern.compile(SimpleWikiHelper.WORD_OF_DAY_REGEX);

Matcher matcher = pattern.matcher(pageContent);

if (matcher.find()) {

// Build an update that holds the updated widget contents

updateViews = new RemoteViews(context.getPackageName(), R.layout.widget_word);

String wordTitle = matcher.group(1);

updateViews.setTextViewText(R.id.word_title, wordTitle);