Android 3.0 r1开发者指南——(待审核)App Widgets(qx.ouyang)

sunglowmaizeΚινητά – Ασύρματες Τεχνολογίες

10 Δεκ 2013 (πριν από 3 χρόνια και 7 μήνες)

392 εμφανίσεις


App Widgets

A偐
小工具】

Quickview



App Widgets provide users access to some of your application features directly from the Home
screen (without the need to launch an activity)



App Widgets are backed by a special kind of broadcast receiver that handles the App W
idget
lifecycle

In this document

1.

The Basics

2.

Declaring an App Widget in the Manifest

3.

Adding the AppWidgetProviderInfo Metadata

4.

Creating the App Widget Layout

5.

Using the AppWidgetProvider Class

1.

Receiving App Widget

broadcast Intents

6.

Creating an App Widget Configuration Activity

1.

Updating the App Widget from the configuration Activity

Key classes

1.

AppWidgetProvider

2.

AppWidgetProviderInfo

3.

AppWidgetManager

See also

1.

App Widget Design Guidelines

2.

Introducing home screen widgets and the AppWidget framework »

App Widgets are miniature application views that can be embedded in other applications (such
as th
e Home screen) and receive periodic updates. These views are referred to as Widgets in
the user interface, and you can publish one with an App Widget provider. An application
component that is able to hold other App Widgets is called an App Widget host. Th
e
screenshot below shows the Music App Widget.

app
小工具是微型的
view(
如主页
),
它可以嵌
入其他的应用
,
或者周期性更新
.
这些
views
在用户界面通常被称作
widgets,
你可以发布一个
App
小工具的提供玩意儿
.
一个
APP
的可以控制其他
APP widgets
的组建称之为
app widget host.

面的截图显示了音乐
app widget




This document describes how to publish an App Widget using an App Widget provider.
【这篇
文章描述了如何使用
App Widget provider
发布一个
app widget


The Basics

To create an App Widget, you need the following:

AppWidgetProviderInfo

object

AppWidgetProviderInfo
对象】

Describes the metadata for an App Widget, such as the App Widget's layout, update
frequency, an
d the AppWidgetProvider class. This should be defined in XML.
【描述
app widget
的元数据
,
例如
app widget

layout,
更新频率
,

appwidgetprovider
的类
.
这些都应该定义在
XML
文件中】

AppWidgetProvider

class implementation

AppWidgetProvider
实现类】

Defines the basic methods that allow you to programmatically interface with the App
Widget, based on broadcast events. Through it, you will receive broadcasts when the
App Widget is updated
, enabled, disabled and deleted.
【定义可以让你的
App Widget
界面基本的程序方法
(

broadcast
事件为基础
).
用它
,
当你的
app widget
更新
,
可用
,
不可
用或者删除时能接收广播】

View layout
【】

Defines the initial layout for the App Widget, defined in XML.
【在
XML
中初始化
app
widget

layout


Additionally, you can implement an App

Widget configuration Activity. This is an
optional

Activity

that launches when the user adds your App Widget and allows him or
her to modify App Widg
et settings at create
-
time.
【另外
,
你可以实现一个
app widget
配置
Acitivity.
这是一个可选的
Activity,
当用户在创建时添加你的
app widget
并允许他修改

app
widget
设置】

The following sections describe how to setup each of these components.
【】


Declaring an App Widget in the Manifest
【在
䵡M楦敳t
声明
A灰pW楤来g


First, declare the

AppWidgetProvider

class in your
application's

AndroidManifest.xml

file. For example:
【】

<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_i
nfo"

/>

</receiver>

The

<recei
ver>

element requires the

android:name

attribute, which specifies
the

AppWidgetProvider

used by the App Widget.

receiver
指定了被
App Widget
使用

AppWidgetProvider


The

<intent
-
filter>

element must include an

<action>

element with
the

android:name

attribute. This attribute specifies that
the

AppWidgetProvider

accepts the

ACTION_APPWIDGET_UPDATE

broadcast.
This

is the only broadcast that you must explicitly declare.
The

AppWidgetManager

automatically sends all other App Widget broadcasts to the

AppWidgetProvider as necessary.
【此项必须包含
<action>
元素并且有
android:name
属性
.
上面
这个属性指定了
AppWidgetProvider
接收
ACTION_APPWIDGET_UPDATE
广播
,
这是唯一一个
你需要明确声明的广播
.
当必要时
AppwidgetManager
自动发送所有
App Widget broadcasts

AppWidgetProvider


The

<meta
-
data>

element specifies the

AppWidgetProviderInfo

resource and
requires the following attributes:

<meta
-
data>
指定了
AppWidgetProviderInfo
资源和他需要的属性




android:name

-

Specifies the

metadata name.
Use

android.appwidget.provider

to identify the data as
the

AppWidgetProviderInfo

descriptor.
【使用
android.appwidget.pr
ovider
来作为
AppWidgetProvidreInfo
的标识】



android:resource

-

Specifies the

AppWidgetProviderInfo

resource
location.
【指定
AppWidgetProviderInf
o
资源定位】


Adding the AppWidgetProviderInfo Metadata
【 添 加
A 灰 p 楤 来 g 偲 潶 楤 敲 䥮 景
元 数 据 】

T h e

AppWidgetProviderInfo

defines the essential qualit
ies of an App Widget, such
as its minimum layout dimensions, its initial layout resource, how often to update the App
Widget, and (optionally) a configuration Activity to launch at create
-
time. Define the
AppWidgetProviderInfo object in an XML resource usi
ng a
single

<appwidget
-
provider>

element and save it in the
project's

res/xml/

folder.
【】

For example:

<appwidget
-
provider

xmlns:android
=
"http://schemas.android.com/apk/res/androi
d"





android:minWidth
=
"294dp"





android:minHeight
=
"72dp"





android:updatePeriodMillis
=
"86400000"





android:initialLayout
=
"@layout/example_appwidget"





and
roid:configure
=
"com.example.android.ExampleAppWid
getConfigure"

>

</appwidget
-
provider>

Here's a summary of the

<appwidget
-
provider>

attributes:
【这里是对
<appwidget
-
provider>
的属性一些概括】



The values for the

minWidth

and

minHeight

attributes specify the minimum
area r
equired by the App Widget's layout.

【】

The default Home screen positions App Widgets in its window based on a grid of cells that
have a defined height and width. If the values for an App Widget's minimum width or height
don't match the dimensions of the ce
lls, then the App Widget dimensions round

up

to the
nearest cell size. (See the

App Widget Design Guidelines

for more information on the
Home
screen cell sizes.)
【缺省的
Home

windows

App Widgets
定位建立在有预定义的高宽单元
格上
.
如果
App Widget's
的最小宽和高值不符合单元格尺寸
,
那么
App Widget
尺寸会以最接近的
cell
大小为准
,


Because the Home screen's layout orientation (and thus, the cell sizes) can change, as a rule
of thumb, you should assume the worst
-
case cell size of

74 pixels for the height

and

width of a
cell. However, you must subtract 2 from the final dimension to account for any integer rounding
errors that occur in the pixel count. To find your minimum width and height in
density
-
independent pixels (dp), use thi
s formula:
【因为
Home screen
的原始
layout
可以改变
,
根据经验来说
,
你应该以
74*74
像素的宽高来假定最坏的
cell size.
无论如何
,
你必须从最后的尺寸

减去
2
以便适应由于在像素计算时整数舍入误差的积累
.
为了在非密度制约的像素中找出最小的
宽高
,
请使用下面的公式】

(number of cells * 74)
-

2

Following this formula, you should use 72 dp for a height of one cell, 294 dp and for a width
of
four cells.
【根据这个公式
,
你必须使用
72dp
作为一个
cell
的高
,294dp
作为
4

cells
的宽】



The

updatePeriodMillis

attribute defines how often the App Widget
framework should request an update from the

AppWidgetProvider

by calling
the

onUpdate()

method. The actual update is not guaranteed to occur exactly on time with
this value and we suggest updating as infrequently as possible

perhaps no more than once
an hour to conserve the battery. You might also allow the user to a
djust the frequency in a
configuration

some people might want a stock ticker to update every 15 minutes, or maybe
only four times a day.


updatePeriodMillis
属性定义了
App Widget framework
应该
多久从
AppWidgetProvider

onUpdate()
方法更新
.
实际上这个更新并不能保证在这个值准时刷

.
因此我们建议尽可能少的更新
,
最好
一小时不超过一次
,
节约电
.
你也许允许用户调整更新频率
-
某些人可能想一个股票报时器能
15
分钟更新
,
或者可能一天只更新
4
次】

Note:

If the device is asleep when it is time for an update (as defined
by

updatePeriodMillis
), then the device will wake up in order to perform the update.
If you don't update more than once per

hour, this probably won't cause significant problems for
the battery life. If, however, you need to update more frequently and/or you do not need to
update while the device is asleep, then you can instead perform updates based on an alarm
that will not wa
ke the device. To do so, set an alarm with an Intent that your
AppWidgetProvider receives, using the
AlarmManager
. Set the alarm type to
either

ELAPSED_REALTIME

or

RTC
, which will only deliver the alarm when the device is
awake. Then set

updatePeriodMillis

to zero (
"0"
).
【注意
,
如果手机在更新时处于睡
眠状态
,
那么他为了更新会唤醒手机
.
如果你不需要每小时不止一次的更新
,
这虽然不会导致明显
的手机电池寿命问题
,
但是
,
不管怎样
,
当手机睡眠时
,
需要频繁
/
不频繁更新你都能用
alarm
替代
platform
更新
,
这样是不会唤醒手机的
.
因此
,

intent
设置一个
AppWidgetProvider
接收的
alarm,alarm type
既可以设置为
Elapsed_REALTIME
或者
RTC,
这些都只会在手机非睡眠状态传

alarm.
然后请设置
updatePeriodMillis

0




The

initialLayout

attribute points to the layout resource that defines the App
Widget layout.
【】



The

configure

attribute defines the

Activity

to launch wh
en the user adds the
App Widget, in order for him or her to configure App Widget properties. This is optional
(read

Creatin
g an App Widget Configuration Activity
below).
【定义了当用户添加的
app Widget
时的
Activity,
为了能配置
app widget
属性
,
这是可选的】

See the

AppWidgetProviderInfo

class for more information on the attributes
accepted by the

<appwidget
-
provider>

element.
【】

Creating the App Widget Layout
【创建
慰a w楤来g
布局文件】

You must define an initial layout for your App Widget in XML and save it in the
project's

res/layout/

directory. You can design your App Widget using the View

objects

listed below, but before you begin designing your App Widget, please read and understand
the

App Widget Design Guidelines
.
【你必须在
X
ML
文件中定义一个初始化的
App Widget

layout,
然后保存在
res/layout/
目录
.
你可以用下面列的
View
对象来设计一个你自己的
App
Widget,
但在你开始设计前
.
请阅读并理解

App Widget Design Guidelines


Creatin
g the App Widget layout is simple if you're familiar with

Declaring Layout in XML
.
However, you must be aware that App Widget layouts are based on

RemoteViews
, which
do not support every kind of layout or view widget.
【创建
app widget
的布局文件是很简单的
,
如果你对
Declaring Layout in XML
很熟悉的话
.
然而
,
你必须小心
App Widget

layout
都是建立

RemotViews

,

RemoteViews
并不是支持任何一种
layout
或者
View
小工具】

A RemoteVie
ws object (and, consequently, an App Widget) can support the following layout
classes:

RemoteViews
对象可以支持一下布局类和
View widget




FrameLayout



LinearLayout



RelativeLayout

And the f
ollowing widget classes:



AnalogClock
【模拟时钟】



Button



Chronometer
【计时器】



ImageButton



ImageView



ProgressBar



TextView

Descendants of these classes are not supported.
【这些类的子类不支持】

Using the AppWidgetProvider Class
【】

You must declare your AppWidgetProvider class implementation as a broadcast receiver using
the
<receiver>

element in the AndroidManifest (see
Declaring an App Widget in the
Manifest

above).

The

AppWidgetProvider

class

extends BroadcastReceiver as a convenience class to
handle the App Widget broadcasts. The AppWidgetProvider receives only the event
broadcasts that are relevant to the App Widget, such as when the App Widget is updated,
deleted, enabled, and disabled. Whe
n these broadcast events occur, the AppWidgetProvider
receives the following method calls:

AppWidgetProvider
类为了能方便的处理
App Widget
广

,
它继承自
BroadcastReceiver.
AppWidgetProvider
只接受和
App Widget
相关的广播事件
,

如当
app widget
更新
,
删除
,
可用
,
不可用
,
如果这些广播事件发生
,
那么
AppWidgetProvider
接收入
如下方法的调用】

onUpdate(Context, AppWidgetManager, int[])


This is called to update the App Widget at intervals defined by
the

updatePeriodMillis

attribute in the AppWidgetProviderInfo (see

Adding
the AppWidgetProviderInfo Metadata

above). This method is also called when the
user adds the App Widget, so it should perform the
essential setup, such as define
event handlers for Views and start a temporary

Service
, if necessary. However, if
you have declared a configuration Act
ivity,

this method is not called

when the user
adds the App Widget, but is called for the subsequent updates. It is the responsibility
of the configuration Activity to perform the first update when configuration is done.
(See

Creating an App Widget Configuration Activity

below.)
【 它 在
AppWidgetProviderInfo

updatePeriodMillis
属性定义的时间到时调用
.
当用户添加
App Widget

,
这个方法也会调用
.
因此它应该进行必要的安装
,
例如为
Vi
ews
定义事件
处理
,
并启动临时服务
.
然而
,
如果你声明了一个配置
Activity,
那么当添加
app Widget
时是
不会调用这个方法的
,
但是更新是会调用的
.
当配置完成时
,
配置
Activity
有责任进行第一
次更新
.


onDeleted(Context, int[])

This is called every time an App Widget is deleted from the App Widget host.
【当
app
widget

app widget host
删除时调用】

onEnabled(Context)

This is called when an instance the App Widget is created for the first time. For
example, if the user adds two instances of your App Widget, this is only called the first
time
. If you need to open a new database or perform other setup that only needs to
occur once for all App Widget instances, then this is a good place to do it.

app widget
第一次初始化调用
.
例如
,
如果用户添加了两个你的
app widget
实力
,
那只会在第一次时调
用一次
.
如果你需要打开一个新的数据库或者运行一些只需要为所有
app widget
实例只
执行一次的
setup,
那么
,
这是个好地方
.


onDisabled(Context)

This is called when the last instance of your App Widget is deleted from the App
Widget host. This is where you should clean up any work done
in

onEnabled(Context)
, such as delete a temporary database.
【当最后一个
app
widget
实例从
app widget host
删除时调用
.
这是清除你在
onEnable(Context)
所执行操
作的好地方
.
例如
,
删除一个临时的数据库】

onReceive(Context, Intent)

This is called for every broadcast and before each of the above callback methods. You
normally don't need to implement this method because the default AppWidgetProvider
implementation filters all App Widget broad
casts and calls the above methods as
appropriate.
【这个方法会在以上所有回调方法之前
,
以及为每个
broadcast
时调用
.
你一
半不需要实现这个方法
,
因为缺省的
appWidgetProvider
实现过滤了所有
app widget
broadcasts
并且适时调用了以上方法
.


Note:

In Android 1.5, there is a known issue in which the

onDeleted()

method will
not be called when it should be. To work around this issue, y
ou can

implement

onReceive()

as described in this

Group post

to receive
the

onDeleted()

callback.

【请注意
.

1.5

onDeleted()
方法有个已知的问题不会
适时调用
.
为了处理这种问题
,
你应该实现
onReceive()
正如
Grouppost
接收
onDeleted()

调方法所描述的那些】

The most important AppWidgetProvider callback is

onUpdated()

because it is called
when each App Widget is added to a host (unless you use a configuration Activity). If your App
Widget accepts any user interactio
n events, then you need to register the event handlers in
this callback. If your App Widget doesn't create temporary files or databases, or perform other
work that requires clean
-
up, then

onUpdated()

may be the only callback method you
need to define. For example, if you want an App Widget with a button that

launches an Activity
when clicked, you could use the following implementation of AppWidgetProvider:

onUpdate()
是最重要的
AppWidgetProvider
回调方法
,
因为它能在
AppWidget
添加到
host(
除非在
Activity
配置过
)
时调用
.
如果你的
AppWidget
接收了所有用户交互事件
,
那你需要在回调中注册这个事件
处理
.
如果你的
AppWidget
没有创建临时文件或者数据库
,
或者运行一些其他的需要清空的操作
,

onUpdate()
方法也许是你需要定义的唯一回调方法
.
例如
,
如果你想有一个在按钮点击后启动
一个
Activity

AppWidget,
你可以使用如下的
AppWidgetProvid
er
实现】

public

class

ExampleAppWidgetProvider

extends

AppWidgetProvider

{






public

void

onUpdate
(
Context

context
,

AppWidgetManager

appWidgetManager
,

int
[]

appWidgetIds
)

{









final

int

N
=

appWidgetIds
.
length
;










// Perform this loop procedure f
or each App Widget
that belongs to this provider









for

(
int

i
=
0
;

i
<
N
;

i
++)

{













int

appWidgetId
=

appWidgetIds
[
i
];














// Create an Intent to launch ExampleActivity













Intent

intent
=

new

Intent
(
context
,

ExampleActivity
.
cla
ss
);













PendingIntent

pendingIntent
=

PendingIntent
.
getActivity
(
context
,

0
,

intent
,

0
);














// Get the layout for the App Widget and attach
an on
-
click listener to the button













RemoteViews

views
=

new

RemoteViews
(
context
.
getPackageName
(),

R
.
layout
.
appwidget_provider_layout
);













views
.
setOnClickPendingIntent
(
R
.
id
.
button
,

pendingIntent
);















// Tell the AppWidgetManager to perform an update
on the current App Widget













appWidgetManager
.
updateAppWid
get
(
appWidgetId
,

views
);









}





}

}

This AppWidgetProvider defines only the

onUpdated()

method for the purpose of defining
a

PendingIntent

that launches an

Activity

and attaching it to the App Widget's
button with

setOnClickPendingIntent(int, PendingIntent)
. Notice that
it includes a loop that iterates through each entry in

appWidgetIds
, which is an array of
IDs that identify each App Widget created by this provider. In
this way, if the user creates more
than one instance of the App Widget, then they are all updated simultaneously. However, only
one

updatePeriodMillis

schedule will be managed for all instances of the App
Widget. For example, if the update schedule is defi
ned to be every two hours, and a second
instance of the App Widget is added one hour after the first one, then they will both be updated
on the period defined by the first one and the second update period will be ignored (they'll both
be updated every two
hours, not every hour).

AppWidgetProvider



PendingIntent(
用于启
动一个
Activity
并用

setOnclickPendingIntent(int,PendingIntent)
绑定
AppWidget
的按钮
)
定义了
一个
onUpdate()
方法
.
注意
:
这包含了一个根据在
provider
创建的
AppWidget
所标识的
IDs
数组

appWidgetIds
所作的遍历循环
.
根据这种方法
,
如果用户创建超过一次的
App Widget
实例
,

他们将会同时全部更新
.
然而
.
只有一个
updatePeriodMills
计划会管理所有的
appwidget
实例
.


,
如果一个

更新计划是定义每两小时更新
,
并且下一个
appwidget
实例在第一个一小时后添加
,
那他们按照第一次定义的时间更新
,
而接下来的更新时间会被忽略
(
即他们都会在每两小时更新
,
而不是一小时
).


Note:

Because

AppWidgetProvider

is an extension
of

BroadcastReceiver
, your process is not guaranteed to keep running after th
e
callback methods return (see

BroadcastReceiver

for information about the
broadcast lifecycle). If your App Widget setup process can tak
e several seconds
(perhaps while performing web requests) and you require that your process continues,
consider starting a

Service

in the

onUpdated()
method. From within the Service,
you can perform your o
wn updates to the App Widget without worrying about the
AppWidgetProvider closing down due to an

Application Not Responding

(ANR) error.
See th
e

Wiktionary sample's AppWidgetProvider

for an example of an App Widget
running a

Service
.
【注意
#####
因为
AppWidgetProvider

BroadcastReceiver
的一个
延伸
,
你的进程不能保证在回调方法返回后继续运行
(
请参看
BroadcastReceiver
的关于
broadcast
生命周期的信息
).
如果你的
AppWidget
启动进程要花费好几秒
,
并且你需要你的
线程能继续
,
可以考虑在
onUpdate()
方法内启动一个服务
.
根据
Service,
你可以运行你的
Appwidget
更新而不需要担心由于
Application NotResponding(ANR)
错误导致的
AppWidgetProvider
关闭
,
请请看
******,
那里有在
AppWidget
运行
Service
的例子】

Also see the

ExampleAppWidgetProvider.java

sample class.
【】


Receiving App Widget broadcast Intents
【接收
A灰pW楤来g
广播意图】

AppWidgetProvider

is just a convenience class. If you would like to receive the App
Widget broadcasts directly, you can implement your own

BroadcastReceiver

or
override the

onReceive(C
ontext, Intent)

callback. The four Intents you need to
care about are:

AppWidgetProvider
是一个很方便的类
,
如果你想直接接收
AppWidget
广播
,

可以事项你自己的
Broadcas
tReceiver
或者覆盖
onReceive(Context,Intent)
回调方法
.
以下四个
意图你需要关心】



ACTION_APPWIDGET_UPDATE



ACTION_APPWIDGET_DELETED



ACTION_APPWIDGET_ENABLED



ACTION_APPWIDGET_DISABLED

Creating an
App Widget Configuration Activity
【创建
慰a w 楤来g
配置
A捴楶楴y


If you would like the user to configure settings when he or she adds a new App Widget, you
can create an App Widget configuration Activity. This

Activity

will be automatically
launched by the App Widget host and allows the user to configure available settings for the
App Widget at create
-
time, such as the App Widget color, size, update period or o
ther
functionality settings.
【如果你希望用户在添加一个新
AppWidget
时可以配置设置
,
那你可以创建
一个
App Widget
配置
Activity.
这个
Acitivty
将会被
App Widget host
自动启动
,
并允许用户在创

App Widget
时配置可用设置
,
例如
App Widget
颜色
,
大小
,
更新时间
,
或者其他的功能设置
.


The configuration Activity should be declared as a normal Activity in the
Android manifest file.
However, it will be launched by the App Widget host with
the

ACTION_APPWIDGET_CONF
IGURE

action, so the Activity needs to accept this
Intent. For example:
【配置
Activity
应该和普通
Activity
一样在
android
配置文件中声明
.
然而
,

是由
App Widget host
根据
ACTION_APPWIDGET_CONFIGURE

action
来启动
,
所以需要接
收这个意图
,
例如】

<activity

android:name
=
".ExampleAppWidgetConfigure"
>





<intent
-
fi
lter>









<action

android:name
=
"android.appwidget.action.APPWIDGET_CONFIGU
RE"

/>





</intent
-
filter>

</activity>


Also, the Activity must be declared in the AppWidgetProviderInfo XML file, with
the

android:configure

attribute (see

Adding the AppWidgetProviderInfo
Metadata

above). For example, the configuration Activity can be declared like this:
【当

,Activity
必须在
AppWidgetProviderI
nfo XML
文件中由
android:configure
属性声明】

<appwidget
-
provider

xmlns:android
=
"http://schemas.android.com/apk/res/androi
d"





...





android:configure
=
"com.example.android.ExampleAppWid
getConfigure"






...
>

</appwidget
-
provider>

Notice that the Activity is decl
ared with a fully
-
qualified namespace, because it will be
referenced from outside your package scope.
【注意
:
这个
Activity
是用全命名空间声明的
,
因为
它可能在你的包外范围被引用到】

That's all you need to get started with a configuration Activity. Now all you need is the actual
Activity. There

are, however, two important things to remember when you implement the
Activity:
【这就是你启动一个配置
Activity
所需要做的全部工作
,
现在你需要的是一个实际
Activity.
然而
,
有两点重要的事情是你实现
Activity
时需要记住的】



The App Widget host calls the configuration Activity and the configuration Activity
should alway
s return a result. The result should include the App Widget ID passed by the
Intent that launched the Activity (saved in the Intent extras as

EXTRA_APPWIDGET_ID
).
【第

:App Widget host
调用配置
Activity,
而配置
Activity
应该总是能返回一个结果
.
这个返回结果应
该包含由
Acitivity
启动的
Intent

App Widget ID




The

onUpdate()

method

will not be called

when the App Widget is created (the
system will not send the ACTION_APPWIDGET_UPDATE broadcast when a configuration
Ac
tivity is launched). It is the responsibility of the configuration Activity to request an update
from the AppWidgetManager when the App Widget is first created.
However,

onUpdate()

will be called for subsequent updates

it is only skipped the first time.
【第二
:onUpdate()
方法在
App Widget
创建时不能被调用
(
系统在配置
Activity
启动时不会发送
ACTION_APPWIDGET_UPDATE
广播
.).
这是对当
App Widget
第一次创建时配置
Acitvity
请求

AppWidgetManager
更新时的负责
.


See the code snippets in the following section for an example of how to return a result from the
configuration and update the App Widget.
【参看如下关于如何从配置和更新
App Widget
返回
一个结果的代
码片段】


Updating the App Widget from the configuration Activity
【通过
捯湦楧畲慴楯渠Ac瑩vity
来更新
Ap瀠p楤i整


When an App Widget uses a configuration Activity, it is the responsibility of the Activity to
update the App Widget when configuration is complete. You can
do so by requesting an
update directly from the
AppWidgetManager
.
【当
App Widget
使用配置
Activity

,
配置完
成时
,Activity
有责任更新
App Widget.
你可以通过
AppWidgetMa
nager
请求直接更新来这样做】

Here's a summary of the procedure to properly update the App Widget and close the
configuration Activity:
【这里是对适时更新
App Widget
并且关闭配置
Activity
所做的一些总结步
骤】

1.

First, get the App Widget ID from the Intent that launched the Activity:

【首先
,
从启动的
Activity

Intent
获取
App Widget ID


Intent

intent
=

getIntent
();

Bundle

extras
=

intent
.
getExtras
();

if

(
extras
!=

null
)

{





mAppWidgetId
=

extras
.
getInt
(













AppWidgetManager
.
EXTRA_APPWIDGET_ID
,














AppWidgetManager
.
INVALID_APPWIDGET_ID
);

}

2.

Perform
your App Widget configuration.
【进行你的
App Widget
配置】

3.

When the configuration is complete, get an instance of the AppWidgetManager by
calling

getInstance(Context)
:

【配置完成时
,
通过调用
getInstance(Context)
获取一个
AppwidgetManager
的实例】

AppWidgetManager

appWidgetManager
=

AppWidgetManager
.
getInstance
(
context
);

4.

Update the App Widget with a

RemoteViews

layout by
calling

updateAppWidget(int, RemoteViews)
:

【用
Remoteviews
布局
(
作为参数
),
调用
updateAppWidget(int,RemoteView)
方法来更新
App Widget


RemoteViews

views
=

new

RemoteViews
(
context
.
getPackageName
(),

R
.
layout
.
example_appwidget
);

appWidgetManager
.
updateAppWidg
et
(
mAppWidgetId
,

views
);

5.

Finally, create the return Intent, set it with the Activity result, and finish the Activity:
【最

,
创建返回的
Intent,

Activity
结果来设置
,
并结束
Activity.


Intent

resultValue
=

new

Intent
();

resultValue
.
putExtra
(
AppWidgetManager
.
EXTRA_APPWIDGET_ID

,

m
AppWidgetId
);

setResult
(
RESULT_OK
,

resultValue
);

finish
();

Tip:

When your configuration Activity first opens, set the Activity result to
RESULT_CANCELED. This way, if the user backs
-
out of the Activity before reaching the
end, the App Widget host is notifi
ed that the configuration was cancelled and the App
Widget will not be added.
【小提示
:
当第一次打开配置
Activity

,
设置
Activity result

RESULT_CANCELED.
这样
,
如果用户在
Activity
到底前退出
,
那么
App Widget host
将会被
告知配置取消了
,App Widget
将不会添加
.


See the

ExampleAppWidgetConfigure.java

sample class in ApiDemos for an example.
【请参

ApiDemos

ExampleAppWidgetConfigure.java
例子】