Android Avanzado PDF

The Busy Coder's Guide to Advanced Android
Development
by Mark L. Murphy
Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
The Busy Coder's Guide to Advanced Android Development
by Mark L. Murphy
Copyright 2009 CommonsWare, LLC. All Rights Reserve.
!rinte in the "nite #tates o$ Ameri%a.
CommonsWare books may be pur%hase in printe &bulk' or igital $orm $or eu%ational or
business use. (or more in$ormation, %onta%t direct@commonsware.com.
!rinting )istory*
+ul 2009* ,ersion -.0 .#/0* 91230392-41203-34
5he CommonsWare name an logo, 6/usy Coer7s 8uie9, an relate trae ress are
traemarks o$ CommonsWare, LLC.
All other traemarks re$eren%e in this book are traemarks o$ their respe%tive $irms.
5he publisher an author&s' assume no responsibility $or errors or omissions or $or amages
resulting $rom the use o$ the in$ormation %ontaine herein.
Table of Contents
Welcome to the Warescription!............................................................ix
Preface....................................................................................................xi
Wel%ome to the /ook:.................................................................................;i
!rere<uisites.................................................................................................;i
Wares%ription.............................................................................................;ii
/ook /ug /ounty.......................................................................................;iii
#our%e Coe Li%ense..................................................................................;iv
Creative Commons an the (our3to3(ree &=2(' 8uarantee...................;iv
Li$e%y%le o$ a CommonsWare /ook..........................................................;v
We!ie"# $nside and %ut........................................................................&
(riens >ith /ene$its....................................................................................-
5urnabout is (air !lay..................................................................................4
8earing "p....................................................................................................9
/a%k 5o 5he (uture......................................................................................--
Craftin' (our %"n !ie"s.......................................................................&)
8etting Meta................................................................................................-?
5he Wiget Layout...............................................................................-=
5he Attribute @e%larations..................................................................-=
5he Wiget .mplementation...............................................................-A
iii
"sing the Wiget..................................................................................-9
Change o$ #tate............................................................................................2-
Changing /utton /a%kgrouns............................................................2-
Changing Che%k/o; #tates..................................................................2A
*ore +un With ,ist!ie"s......................................................................-.
8iant B%onomy3#iCe @iviers....................................................................29
Choosing What .s #ele%table...............................................................?0
Composition $or #e%tions.....................................................................?-
(rom )ea 5o 5oe......................................................................................?2
Control Dour #ele%tion...............................................................................=2
Create a "ni$ie Ro> ,ie>..................................................................=2
Con$igure the List, 8et Control on #ele%tion.....................................=?
Change the Ro>...................................................................................=4
/ho" 0p At 1ome.................................................................................2.
Bast is Bast, an West is West...................................................................=9
5he /ig !i%ture $or a #mall App Wiget...................................................A0
Cra$ting App Wigets.................................................................................A-
5he Mani$est.........................................................................................A2
5he Metaata........................................................................................A?
5he Layout............................................................................................A=
5he /roa%astRe%eiver.........................................................................AA
5he #ervi%e............................................................................................A4
5he Con$iguration A%tivity..................................................................A2
5he Result..............................................................................................4-
Another an Another.................................................................................4=
App Wigets* 5heir Li$e an 5imes..........................................................4A
Controlling Dour &App Wiget7s' @estiny................................................44
iv
/eing a 8oo )ost.....................................................................................44
Creatin' Dra"ales................................................................................3&
5raversing Along a 8raient......................................................................1-
A #tit%h .n 5ime #aves 0ine......................................................................1A
5he 0ame an the /orer...................................................................14
!aing an the /o;............................................................................14
#tret%h Eones........................................................................................11
5ooling..................................................................................................12
"sing 0ine3!at%h .mages....................................................................20
Animatin' Wid'ets................................................................................43
.t7s 0ot +ust (or 5oons Anymore...............................................................21
A Fuirky 5ranslation.................................................................................22
Me%hani%s o$ 5ranslation....................................................................22
.magining a #liing !anel...................................................................29
5he A$termath......................................................................................29
.ntrou%ing #liing!anel....................................................................90
"sing the Animation............................................................................92
(aing 5o /la%k. Gr #ome Gther Color....................................................92
Alpha 0umbers....................................................................................9?
Animations in HML..............................................................................9?
"sing HML Animations.......................................................................9=
When .t7s All #ai An @one....................................................................9=
)it 5he A%%elerator....................................................................................9A
Animate. #et. Mat%h...................................................................................94
Playin' *edia..........................................................................................
8et Dour Meia Gn....................................................................................99
Making 0oise.............................................................................................-00
v
Moving !i%tures.........................................................................................-0A
0sin' the Camera..................................................................................&&&
#neaking a !eek..........................................................................................---
5he !ermission....................................................................................--2
5he #ur$a%e,ie>..................................................................................--?
5he Camera..........................................................................................--?
.mage .s Bverything...................................................................................--4
Asking $or a (ormat.............................................................................--1
Conne%ting the Camera /utton..........................................................--1
5aking a !i%ture...................................................................................--2
"sing Asyn%5ask..................................................................................--9
/ensors..................................................................................................&-)
5he #i;th #ense. Gr !ossibly the #eventh...............................................-2?
Grienting Doursel$.....................................................................................-2=
#teering Dour !hone..................................................................................-21
@o I5he #hakeI..........................................................................................-29
Dataases and Content Providers.......................................................&)5
@istribute @ata........................................................................................-?4
#FLite* Gn3@evi%e, Gn3@esktop.......................................................-?1
B;porting a @atabase..........................................................................-?1
Loaing the B;porte @atabase.........................................................-?9
B;amining Dour Relationships.................................................................-=2
Conta%t !ermissions...........................................................................-=2
!re3+oine @ata...................................................................................-=?
5he #ample A%tivity............................................................................-=?
A%%essing !eople.................................................................................-=4
A%%essing !hone 0umbers.................................................................-=1
vi
A%%essing Bmail Aresses................................................................-=2
Rummaging 5hrough Dour !hone Re%ors............................................-A0
Come 5ogether, Right 0o>.......................................................................-A-
CursorWrapper....................................................................................-A2
.mplementing a +oinCursor................................................................-A2
"sing a +oinCursor..............................................................................-A1
1andlin' /ystem 6vents......................................................................&73
8et Moving, (irst 5hing............................................................................-41
5he !ermission...................................................................................-42
5he Re%eiver Blement.........................................................................-42
5he Re%eiver .mplementation...........................................................-49
. #ense a Conne%tion /et>een "s............................................................-10
(eeling @raine..........................................................................................-1?
0sin' /ystem /ervices..........................................................................&3.
8et Alarme...............................................................................................-19
Con%ept o$ WakeLo%ks.......................................................................-20
#%heuling Alarms...............................................................................-2-
Arranging $or Work (rom Alarms.....................................................-22
#taying A>ake At Work.....................................................................-2=
#etting B;pe%tations.................................................................................-22
/asi% #ettings......................................................................................-22
#e%ure #ettings.....................................................................................-9-
Can Dou )ear Me 0o>J GK, )o> About 0o>J....................................-92
Reusing Meter.....................................................................................-9?
Atta%hing Meters to ,olume #treams...............................................-9?
(our %"n 8Advanced9 /ervices...........................................................&.3
When .!C Atta%ks:....................................................................................-91
vii
Write the A.@L...................................................................................-92
.mplement the .nter$a%e....................................................................-99
A Consumer B%onomy.............................................................................200
/oun $or #u%%ess..............................................................................200
Re<uest $or #ervi%e.............................................................................20-
!rometheus "nboun........................................................................20-
#ervi%e (rom A$ar.....................................................................................202
#ervi%e 0ames.....................................................................................202
5he #ervi%e..........................................................................................20?
5he Client...........................................................................................20A
#ervi%ing the #ervi%e.................................................................................201
Callba%ks via A.@L.............................................................................202
Revising the Client.............................................................................209
Revising the #ervi%e.............................................................................2--
+indin' Availale Actions via $ntrospection......................................-&5
!i%k 7Bm......................................................................................................2-4
Woul Dou Like to #ee the MenuJ..........................................................220
Asking Aroun..........................................................................................222
Testin' (our Patience..........................................................................--5
Dou 8et What 5hey 8ive Dou..................................................................22A
Bre%ting More #%a$$oling.......................................................................224
5esting Real #tu$$......................................................................................229
A%tivity.nstrumentation5estCase.....................................................229
Anroi5estCase.................................................................................2?-
Gther Alternatives..............................................................................2??
Monkeying Aroun...................................................................................2??
viii
Welcome to the Warescription!
We hope you enLoy this igital book an its upates M keep tabs on the
Wares%ription $ee o$$ the CommonsWare site to learn >hen ne> eitions
o$ this book, or other books in your Wares%ription, are available.
Ba%h Wares%ription igital book is li%ense $or the e;%lusive use o$ its
subs%riber an is tagge >ith the subs%ribers name. We ask that you not
istribute these books. .$ you >ork $or a $irm an >ish to have several
employees have a%%ess, enterprise Wares%riptions are available. +ust %onta%t
us at enterpriseN%ommons>are.%om.
Also, bear in min that eventually this eition o$ this title >ill be release
uner a Creative Commons li%ense M more on this in the pre$a%e.
Remember that the CommonsWare Web site has errata an resour%es &e.g.,
sour%e %oe' $or ea%h o$ our titles. +ust visit the Web page $or the book you
are intereste in an $ollo> the links.
#ome notes $or $irst3generation Kinle users*
Dou may >ish to rop your $ont siCe to level 2 $or easier reaing
#our%e %oe listings are in%orporate as graphi%s so as to retain the
monospa%e $ont, though this means the sour%e %oe listings o not
honor %hanges in Kinle $ont siCe
ix
Preface
Welcome to the Book!
.$ you %ome to this book a$ter having rea its %ompanion volume, 5he /usy
Coer7s 8uie to Anroi @evelopment, thanks $or sti%king >ith the series:
CommonsWare aims to have the most %omprehensive set o$ Anroi
evelopment resour%es &outsie o$ the Gpen )anset Allian%e itsel$', an
>e appre%iate your interest.
.$ you %ome to this book having learne about Anroi $rom other sour%es,
thanks $or Loining the CommonsWare %ommunity: Anroi, >hile aime at
small evi%es, is a surprisingly vast plat$orm, making it i$$i%ult $or any
given book, training, >iki, or other sour%e to %ompletely %over everything
one nees to kno>. 5his book >ill hope$ully augment your kno>lege o$
the ins an outs o$ Anroi3om an make it easier $or you to %reate Ikiller
appsI that use the Anroi plat$orm.
An, most o$ all, thanks $or your interest in this book: . sin%erely hope you
$in it use$ul an at least o%%asionally entertaining.
Prerequisites
5his book assumes you have e;perien%e in Anroi evelopment, >hether
$rom a CommonsWare resour%e or somepla%e else. .n other >ors, you
shoul have*
xi
A >orking Anroi evelopment environment, >hether it is base
on B%lipse, another .@B, or Lust the %omman3line tools that
a%%ompany the Anroi #@K
A strong unerstaning o$ ho> to %reate a%tivities an the various
sto%k >igets available in Anroi
A >orking kno>lege o$ the Intent system, ho> it serves as a
message bus, an ho> to use it to laun%h other a%tivities
B;perien%e in %reating, or at least using, %ontent proviers an
servi%es
.$ you pi%ke this book up e;pe%ting to learn those topi%s, you really nee
another sour%e $irst, sin%e this book $o%uses on other topi%s. While >e are
$ans o$ 5he /usy Coer7s 8uie to Anroi @evelopment, there are plenty
o$ other books available %overing the Anroi basi%s, blog posts, >ikis, an,
o$ %ourse, the main Anroi site itsel$. A list o$ %urrently3available Anroi
books %an be $oun on the Anroi !rogramming knol.
#ome %hapters may re$eren%e material in previous %hapters, though usually
>ith a link ba%k to the pre%eing se%tion o$ relevan%e. Many %hapters >ill
re$eren%e material in 5he /usy Coer7s 8uie to Anroi @evelopment,
sometimes via the shorthan BCG to Android moniker.
.n orer to make e$$e%tive use o$ this book, you >ill >ant to o>nloa the
sour%e %oe $or it o$$ o$ the book7s page on the CommonsWare site.
Warescription
5his book >ill be publishe both in print an in igital $orm. 5he igital
versions o$ all CommonsWare titles are available via an annual subs%ription
M the Wares%ription.
5he Wares%ription entitles you, $or the uration o$ your subs%ription, to
igital $orms o$ all CommonsWare titles, not Lust the one you are reaing.
!resently, CommonsWare o$$ers !@( an KinleO other igital $ormats >ill
be ae base on interest an the openness o$ the $ormat.
xii
Ba%h subs%riber gets personaliCe eitions o$ all eitions o$ ea%h title* both
those mirroring printe eitions an in3bet>een upates that are only
available in igital $orm. 5hat >ay, your igital books are never out o$ ate
$or long, an you %an take avantage o$ ne> material as it is mae available
instea o$ having to >ait $or a >hole ne> print eition. (or e;ample, >hen
ne> releases o$ the Anroi #@K are mae available, this book >ill be
<ui%kly upate to be a%%urate >ith %hanges in the A!.s.
(rom time to time, subs%ribers >ill also re%eive a%%ess to subs%riber3only
online material, in%luing not3yet3publishe ne> titles.
Also, i$ you o>n a print %opy o$ a CommonsWare book, an it is in goo
%lean %onition >ith no marks or sti%kers, you %an e;%hange that %opy $or a
$ree $our3month Wares%ription.
.$ you are intereste in a Wares%ription, visit the Wares%ription se%tion o$
the CommonsWare Web site.
Book Bug Bounty
(in a problem in one o$ our booksJ Let us kno>:
/e the $irst to report a uni<ue %on%rete problem in the %urrent igital
eition, an >e7ll give you a %oupon $or a si;3month Wares%ription as a
bounty $or helping us eliver a better prou%t. Dou %an use that %oupon to
get a ne> Wares%ription, rene> an e;isting Wares%ription, or give the
%oupon to a $rien, %olleague, or some ranom person you meet on the
sub>ay.
/y I%on%reteI problem, >e mean things like*
5ypographi%al errors
#ample appli%ations that o not >ork as avertise, in the
environment es%ribe in the book
(a%tual errors that %annot be open to interpretation
xiii
/y Iuni<ueI, >e mean ones not yet reporte. Ba%h book has an errata page
on the CommonsWare Web siteO most kno>n problems >ill be liste there.
Gne %oupon is given per email %ontaining vali bug reports.
:%T6* /ooks >ith version numbers lo>er than 0.9 are ineligible $or the
bounty program, as they are in various stages o$ %ompletion. We appre%iate
bug reports, though, i$ you %hoose to share them >ith us.
We appre%iate hearing about Iso$terI issues as >ell, su%h as*
!la%es >here you think >e are in error, but >here >e $eel our
interpretation is reasonable
!la%es >here you think >e %oul a sample appli%ations, or
e;pan upon the e;isting material
#amples that o not >ork ue to Ishi$ting sansI o$ the unerlying
environment &e.g., %hange A!.s >ith ne> releases o$ an #@K'
)o>ever, those Iso$terI issues o not <uali$y $or the $ormal bounty
program.
Fuestions about the bug bounty, or problems you >ish to report $or bounty
%onsieration, shoul be sent to bountyN%ommons>are.%om.
Source Code icense
5he sour%e %oe samples sho>n in this book are available $or o>nloa
$rom the CommonsWare Web site. All o$ the Anroi proLe%ts are li%ense
uner the Apa%he 2.0 Li%ense, in %ase you have the esire to reuse any o$ it.
Creative Commons and the !our"to"!ree
#$%!& 'uarantee
Ba%h CommonsWare book eition >ill be available $or use uner the
Creative Commons Attribution30on%ommer%ial3#hare Alike ?.0 li%ense as
o$ the $ourth anniversary o$ its publi%ation ate, or >hen =,000 %opies o$
the eition have been sol, >hi%hever %omes $irst. 5hat means that, on%e
$our years have elapse &perhaps sooner:', you %an use this prose $or non3
xiv
%ommer%ial purposes. 5hat is our (our3to3(ree 8uarantee to our reaers
an the broaer %ommunity. (or the purposes o$ this guarantee, ne>
Wares%riptions an rene>als >ill be %ounte as sales o$ this eition,
starting $rom the time the eition is publishe.
5his eition o$ this book >ill be available uner the a$orementione
Creative Commons li%ense on +une -# -;&). G$ %ourse, >at%h the
CommonsWare Web site, as this eition might be reli%ense sooner base
on sales.
(or more etails on the Creative Commons Attribution30on%ommer%ial3
#hare Alike ?.0 li%ense, visit the Creative Commons Web site.
0ote that $uture eitions o$ this book >ill be%ome $ree on later ates, ea%h
$our years $rom the publi%ation o$ that eition or base on sales o$ that
spe%i$i% eition. Releasing one eition uner the Creative Commons li%ense
oes not automati%ally release all eitions uner that li%ense.
ifecycle of a CommonsWare Book
CommonsWare books generally go through a series o$ stages.
(irst are the pre3release eitions. 5hese >ill have version numbers belo>
0.9 &e.g., 0.2'. 5hese eitions are in%omplete, o$ten times having but a $e>
%hapters to go along >ith outlines an notes. )o>ever, >e make them
available to those on the Wares%ription so they %an get early a%%ess to the
material.
Release %aniates are eitions >ith version numbers ening in I.9I &0.9,
-.9, et%.'. 5hese eitions shoul be %omplete. Gn%e again, they are mae
available to those on the Wares%ription so they get early a%%ess to the
material an %an $ile bug reports &an re%eive bounties in return:'.
MaLor eitions are those >ith version numbers ening in I.0I &-.0, 2.0, et%.'.
5hese >ill be $irst publishe igitally $or the Wares%ription members, but
>ill shortly therea$ter be available in print $rom booksellers >orl>ie.
xv
,ersions bet>een a maLor eition an the ne;t release %aniate &e.g., -.-,
-.2' >ill %ontain bug $i;es plus ne> material. Ba%h o$ these eitions shoul
also be %omplete, in that you >ill not see any I5/@I &to be one' markers
or the like. )o>ever, these eitions may have bugs, an so bug reports are
eligible $or the bounty program, as >ith release %aniates an maLor
releases.
A book usually >ill progress $airly rapily through the pre3release eitions
to the $irst release %aniate an ,ersion -.0 M o$ten times, only a $e>
months. @epening on the book7s s%ope, it may go through another %y%le o$
signi$i%ant improvement &versions -.- through 2.0', though this may take
several months to a year or more. Bventually, though, the book >ill go into
more o$ a Imaintenan%e moeI, only getting upates to $i; bugs an eal
>ith maLor e%osystem events M $or e;ample, a ne> release o$ the Anroi
#@K >ill ne%essitate an upate to all Anroi books.
xvi
PART I Advanced Widgets
CHAPTER 1
Web(ie)* +nside and ,ut
Anroi uses the WebKit bro>ser engine as the $ounation $or both its
/ro>ser appli%ation an the WebView embeable bro>sing >iget. 5he
/ro>ser appli%ation, o$ %ourse, is something Anroi users %an intera%t
>ith ire%tlyO the WebView >iget is something you %an integrate into your
o>n appli%ations $or pla%es >here an )5ML inter$a%e might be use$ul.
.n BCG to Android, >e sa> a simple integration o$ a WebView into an Anroi
a%tivity, >ith the a%tivity i%tating >hat the bro>sing >iget isplaye an
ho> it respone to links.
)ere, >e >ill e;pan on this theme, an sho> ho> to more tightly
integrate the +ava environment o$ an Anroi appli%ation >ith the
+avas%ript environment o$ WebKit.
!riends )ith Benefits
When you integrate a WebView into your a%tivity, you %an %ontrol >hat Web
pages are isplaye, >hether they are $rom a lo%al provier or %ome $rom
over the .nternet, >hat shoul happen >hen a link is %li%ke, an so $orth.
An bet>een WebView, WebViewClient, an WebSettings, you %an %ontrol a $air
bit about ho> the embee bro>ser behaves. Det, by e$ault, the bro>ser
itsel$ is Lust a bro>ser, %apable o$ sho>ing Web pages an intera%ting >ith
Web sites, but other>ise gaining nothing $rom being hoste by an Anroi
appli%ation.
-
B;%ept $or one thing* addJavascriptInterface().
5he addJavascriptInterface() metho on WebView allo>s you to inLe%t a +ava
obLe%t into the WebView, e;posing its methos, so they %an be %alle by
+avas%ript loae by the Web %ontent in the WebView itsel$.
0o> you have the po>er to provie a%%ess to a >ie range o$ Anroi
$eatures an %apabilities to your WebView3hoste %ontent. .$ you %an a%%ess it
$rom your a%tivity, an i$ you %an >rap it in something %onvenient $or use
by +avas%ript, your Web pages %an a%%ess it as >ell.
(or e;ample, 8oogle7s 8ears proLe%t o$$ers a 8eolo%ation A!., so Web pages
loae in a 8ears3enable bro>ser %an $in out >here the bro>ser is
lo%ate. 5his in$ormation %oul be use $or everything $rom $ine3tuning a
sear%h to emphasiCe lo%al %ontent to serving up lo%ale3tailore avertising.
We %an o mu%h o$ the same thing >ith Anroi an
addJavascriptInterface().
.n the WebView/GeoWeb1 proLe%t, you >ill $in a $airly simple layout
&main.xml'*
!xml version#$1.%$ encoding#$&tf'($!)
*inear*a+o&t xmlns,android#$-ttp,//sc-emas.android.com/ap./res/android$
android,orientation#$vertical$
android,la+o&t/widt-#$fill/parent$
android,la+o&t/-eig-t#$fill/parent$
)
WebView android,id#$01id/web.it$
/)
/*inear*a+o&t)
All this oes is host a $ull3s%reen WebView >iget.
0e;t, take a look at the GeoWeb2ne a%tivity %lass*
p&blic class GeoWeb2ne extends 3ctivit+ 4
private static String 562VI786#*ocation9anager.G5S/562VI786:
%
private WebView browser:
private *ocation9anager m+*ocation9anager#n&ll:

02verride
p&blic void onCreate(;&ndle icicle) 4
s&per.onCreate(icicle):

setContentView(6.la+o&t.main):
browser#(WebView)findViewById(6.id.web.it):

m+*ocation9anager#(*ocation9anager)getSystemService(Context.*2C3<I2=/S86VIC8
):

browser.getSettings().setJavaScriptEnabled(tr&e):
browser.addJavascriptInterface(new Locater()> $locater$):
browser.loadUrl($file,///android/asset/geoweb1.-tml$):
?

02verride
p&blic void onResume() 4
s&per.onResume():
m+*ocation9anager.requestLocationUpdates(562VI786> 1%%%%>
1%%.%f>
on*ocationC-ange):
?

02verride
p&blic void onause() 4
s&per.onause():
m+*ocation9anager.removeUpdates(on*ocationC-ange):
?

*ocation*istener on*ocationC-ange#new LocationListener() 4
p&blic void onLocationC!anged(*ocation location) 4
// ignore...for now
?

p&blic void onrovider"isabled(String provider) 4
// re@&ired for interface> not &sed
?

p&blic void onroviderEnabled(String provider) 4
?

p&blic void onStatusC!anged(String provider> int stat&s>
;&ndle extras) 4
?
?:

p&blic class *ocater 4
p&blic do&ble getLatitude() 4
*ocation loc#m+*ocation9anager.getLast#nownLocation(562VI786):
.

if (loc##n&ll) 4
ret&rn(%):
?

ret&rn(loc.getLatitude()):
?

p&blic do&ble getLongitude() 4

if (loc##n&ll) 4
ret&rn(%):
?

ret&rn(loc.getLongitude()):
?
?
?
5his looks a bit like some o$ the WebView e;amples in the BCG to Android7s
%hapter on integrating WebKit. )o>ever, it as three key bits o$ %oe*
-. .t sets up the *ocation9anager to provie upates >hen the evi%e
position %hanges, routing those upates to a o3nothing
*ocation*istener %allba%k obLe%t
2. .t has a *ocater inner %lass that provies a %onvenient A!. $or
a%%essing the %urrent lo%ation, in the $orm o$ latitue an longitue
values
?. .t uses addJavascriptInterface() to e;pose a *ocater instan%e uner
the name locater to the Web %ontent loae in the WebView
5he Web page itsel$ is re$eren%e in the sour%e %oe as
file,///android/asset/geoweb1.-tml, so the GeoWeb1 proLe%t has a
%orresponing assets/ ire%tory %ontaining geoweb1.-tml*
-tml)
-ead)
title)3ndroid GeoWeb2ne 7emo/title)
script lang&age#$Aavascript$)
f&nction w-ereami() 4
doc&ment.get8lement;+Id($lat$).innerB<9*#locater.get*atit&de():
doc&ment.get8lement;+Id($lon$).innerB<9*#locater.get*ongit&de():
?
/script)
/-ead)
$
bod+)
p)
Co& are at, br/) span id#$lat$)(&n.nown)/span) latit&de and br/)
span id#$lon$)(&n.nown)/span) longit&de.
/p)
p)a onClic.#$w-ereami()$)Dpdate *ocation/a)/p)
/bod+)
/-tml)
When you %li%k the I"pate Lo%ationI link, the page %alls a w-ereami()
+avas%ript $un%tion, >hi%h in turn uses the locater obLe%t to upate the
latitue an longitue, initially sho>n as I&unkno>n'I on the page.
.$ you run the appli%ation, initially, the page is pretty boring*
!igure -/ The 'eoWeb,ne sample application* as initially launched
)o>ever, i$ you >ait a bit $or a 8!# $i;, an %li%k the I"pate Lo%ationI
link...the page is still pretty boring, but it at least kno>s >here you are*
0
!igure %/ The 'eoWeb,ne sample application* after clicking the 1pdate
ocation link
Turnabout is !air Play
0o> that >e have seen ho> +avas%ript %an %all into +ava, it >oul be ni%e i$
+ava %oul someho> %all out to +avas%ript. .n our e;ample, it >oul be
help$ul i$ >e %oul e;pose automati% lo%ation upates to the Web page, so
it %oul proa%tively upate the position as the user moves, rather than >ait
$or a %li%k on the I"pate Lo%ationI link.
Well, as lu%k >oul have it, >e %an o that too. 5his is a goo thing,
other>ise, this >oul be a really >eak se%tion o$ the book.
What is unusual is ho> you %all out to +avas%ript. Gne might imagine there
>oul be an exec&teJavascript() %ounterpart to addJavascriptInterface(),
>here you %oul supply some +avas%ript sour%e an have it e;e%ute >ithin
the %onte;t o$ the %urrently3loae Web page.
Gly enough, that is not ho> this is a%%omplishe.
2
.nstea, given your snippet o$ +avas%ript sour%e to e;e%ute, you %all
loadDrl() on your WebView, as i$ you >ere going to loa a Web page, but you
put Aavascript, in $ront o$ your %oe an use that as the IaressI to loa.
.$ you have ever %reate a IbookmarkletI $or a esktop Web bro>ser, you
>ill re%ogniCe this te%hni<ue as being the Anroi analogue M the
Aavascript, pre$i; tells the bro>ser to treat the rest o$ the aress as
+avas%ript sour%e, inLe%te into the %urrently3vie>e Web page.
#o, arme >ith this %apability, let us moi$y the previous e;ample to
%ontinuously upate our position on the Web page.
5he layout $or this ne> proLe%t &WebView/GeoWebE' is the same as be$ore. 5he
+ava sour%e $or our a%tivity %hanges a bit*
p&blic class GeoWeb<wo extends 3ctivit+ 4
private static String 562VI786#$gps$:
private WebView browser:
private *ocation9anager m+*ocation9anager#n&ll:

02verride
browser#(WebView)findViewById(6.id.web.it):

m+*ocation9anager#(*ocation9anager)getSystemService(Context.*2C3<I2=/S86VIC8
):

browser.getSettings().setJavaScriptEnabled(tr&e):
browser.addJavascriptInterface(new Locater()> $locater$):
browser.loadUrl($file,///android/asset/geowebE.-tml$):
?

02verride
s&per.onResume():
m+*ocation9anager.requestLocationUpdates(562VI786> %>
%>
on*ocationC-ange):
?

02verride
s&per.onause():
m+*ocation9anager.removeUpdates(on*ocationC-ange):
?
3

*ocation*istener on*ocationC-ange#new LocationListener() 4
p&blic void onLocationC!anged(*ocation location) 4
String;&ilder b&f#new StringBuilder($Aavascript,w-ereami($):

b&f.append(String.value$f(location.getLatitude())):
b&f.append($>$):
b&f.append(String.value$f(location.getLongitude())):
b&f.append($)$):

browser.loadUrl(b&f.toString()):
?

p&blic void onrovider"isabled(String provider) 4
?

p&blic void onroviderEnabled(String provider) 4
?

p&blic void onStatusC!anged(String provider> int stat&s>
;&ndle extras) 4
?
?:

p&blic class *ocater 4
p&blic do&ble getLatitude() 4

if (loc##n&ll) 4
ret&rn(%):
?

ret&rn(loc.getLatitude()):
?

p&blic do&ble getLongitude() 4

if (loc##n&ll) 4
ret&rn(%):
?

ret&rn(loc.getLongitude()):
?
?
?
/e$ore, the on*ocationC-anged() metho o$ our *ocation*istener %allba%k
i nothing. 0o>, it buils up a %all to a w-ereami() +avas%ript $un%tion,
proviing the latitue an longitue as parameters to that %all. #o, $or
4
e;ample, i$ our lo%ation >ere =0 egrees latitue an 31A egrees longitue,
the %all >oul be w-ereami(F%>'GH). 5hen, it puts Aavascript, in $ront o$ it
an %alls loadDrl() on the WebView. 5he result is that a w-ereami() $un%tion
in the Web page gets %alle >ith the ne> lo%ation.
5hat Web page, o$ %ourse, also neee a slight revision, to a%%ommoate
the option o$ having the position be passe in*
-tml)
-ead)
title)3ndroid GeoWeb<wo 7emo/title)
script lang&age#$Aavascript$)
f&nction w-ereami(lat> lon) 4
doc&ment.get8lement;+Id($lat$).innerB<9*#lat:
doc&ment.get8lement;+Id($lon$).innerB<9*#lon:
?
/script)
/-ead)
bod+)
p)
Co& are at, br/) span id#$lat$)(&n.nown)/span) latit&de and br/)
span id#$lon$)(&n.nown)/span) longit&de.
/p)
p)a onClic.#$w-ereami(locater.get*atit&de()> locater.get*ongit&de())$)
Dpdate *ocation/a)/p)
/bod+)
/-tml)
5he basi%s are the same, an >e %an even keep our I"pate Lo%ationI link,
albeit >ith a slightly i$$erent onClic. attribute.
.$ you buil, install, an run this revise sample on a 8!#3e<uippe
Anroi evi%e, the page >ill initially isplay >ith I&unkno>n'I $or the
%urrent position. A$ter a $i; is reay, though, the page >ill automati%ally
upate to re$le%t your a%tual position. An, as be$ore, you %an al>ays %li%k
I"pate Lo%ationI i$ you >ish.
'earing 1p
.n these e;amples, >e emonstrate ho> Web,ie> %an intera%t >ith +ava
%oe, %oe that provies a servi%e a little like one o$ those $rom 8ears.
5
G$ %ourse, >hat >oul be really sli%k is i$ >e %oul use 8ears itsel$.
5he goo ne>s is that Anroi is %lose on that $ront. 8ears is a%tually
bake into Anroi. )o>ever, it is only e;pose by the /ro>ser
appli%ation, not via WebView. #o, an en user o$ an Anroi evi%e %an
leverage 8ears3enable Web pages.
(or e;ample, you %oul loa the 8eolo%ation sample appli%ation in your
Anroi evi%e7s /ro>ser appli%ation. .nitially, you >ill get the stanar
I%an >e please use 8earsJI se%urity prompt*
!igure ./ The 'ears security prompt
5hen, 8ears >ill $ire up the 8!# inter$a%e &i$ enable' an >ill $et%h your
lo%ation*
-6
!igure $/ The 'ears 'eolocation sample application
Back To The !uture
5he %ore Anroi team has ini%ate that these sorts o$ %apabilities >ill
in%rease in $uture eitions o$ the Anroi operating system. 5his %oul
in%lue support $or more types o$ plugins, a ri%her +ava3+avas%ript brige,
an so on.
Dou %an also e;pe%t some improvements %oming $rom the overall Anroi
e%osystem. (or e;ample, the !hone8ap proLe%t is attempting to buil a
$rame>ork that supports %reating Anroi appli%ations solely out o$ Web
%ontent, using Web,ie> as the $ront3en, supporting a range o$ 8ears3like
%apabilities an more, su%h as a%%elerometer a>areness.
--
CHAPTER 2
Crafting 7our ,)n (ie)s
Gne o$ the %lassi% $orms o$ %oe reuse is the 8". >iget. #in%e the avent
o$ Mi%roso$t Wino>s M an, to some e;tent, even earlier M evelopers have
been %reating their o>n >igets to e;ten an e;isting >iget set. 5hese
range $rom -43bit Wino>s I%ustom %ontrolsI to ?23bit Wino>s GCH
%omponents to the innumerable >igets available $or +ava #>ing an #W5,
an beyon. Anroi lets you %ra$t your o>n >igets as >ell, su%h as
e;tening an e;isting >iget >ith a ne> ". or ne> behaviors.
'etting 8eta
Gne %ommon >ay o$ %reating your o>n >igets is to aggregate other
>igets together into a reusable ImetaI >iget. Rather than >orry about all
the etails o$ measuring the >iget siCes an ra>ing its %ontents, you
simply >orry about %reating the publi% inter$a%e $or ho> one intera%ts >ith
the >iget.
.n this se%tion, >e >ill look at the Views/9eter sample proLe%t. )ere, >e
bunle a 5rogress;ar an t>o Image;&tton >igets into a reusable 9eter
>iget, allo>ing one to %hange a value by %li%king Iin%rementI an
Ie%rementI buttons. .n most %ases, one >oul probably be better serve
using the built3in See.;ar >iget. )o>ever, there are times >hen >e only
>ant people to %hange the value a %ertain amount at a time, $or >hi%h the
9eter is ieally suite. .n $a%t, >e >ill reuse the 9eter in a later %hapter
>hen >e sho> ho> to manipulate the various volume levels in Anroi.
-.
The id!et "ayout
5he $irst step to>ars %reating a reusable >iget is to lay it out. .n some
%ases, you may pre$er to %reate your >iget %ontents purely in +ava,
parti%ularly i$ many %opies o$ the >iget >ill be %reate an you o not
>ant to in$late them every time. )o>ever, other>ise, layout HML is simpler
in many %ases than the in3+ava alternative.
)ere is one su%h 9eter layout &res/la+o&t/meter.xml in Views/9eter'*
android,orientation#$-oriIontal$
android,la+o&t/-eig-t#$wrap/content$
)
Image;&tton android,id#$01id/decr$
android,la+o&t/-eig-t#$J%px$
android,la+o&t/widt-#$J%px$
android,src#$0drawable/decr$
/)
5rogress;ar android,id#$01id/bar$
st+le#$!android,attr/progress;arSt+leBoriIontal$
android,la+o&t/widt-#$%px$
android,la+o&t/weig-t#$1$
/)
Image;&tton android,id#$01id/incr$
android,la+o&t/-eig-t#$J%px$
android,la+o&t/widt-#$J%px$
android,src#$0drawable/incr$
/)
/*inear*a+o&t)
All >e o is line them up in a ro>, giving the 5rogress;ar any e;%ess spa%e
&via android,la+o&t/widt- # $%px$ an android,la+o&t/weig-t # $1$'. We are
using a pair o$ -4;-4 pi;el images $rom the 0uvola i%on set $or the
in%rement an e%rement button $a%es.
The Attri#ute Declarations
Wigets usually have attributes that you %an set in the HML $ile, su%h as the
android,src attribute >e spe%i$ie on the Image;&tton >igets in the layout
-$
above. Dou %an %reate your o>n %ustom attributes that %an be use in your
%ustom >iget, by %reating a res/val&es/attrs.xml $ile to spe%i$y them.
(or e;ample, here is the attributes $ile $or 9eter*
reso&rces)
declare'st+leable name#$9eter$)
attr name#$max$ format#$integer$ /)
attr name#$incr$ format#$integer$ /)
attr name#$decr$ format#$integer$ /)
/declare'st+leable)
/reso&rces)
5he declare'st+leable element es%ribes >hat attributes are available on
the >iget %lass spe%i$ie in the name attribute M in our %ase, >e >ill %all
the >iget 9eter. .nsie declare'st+leable you %an have one or more attr
elements, ea%h ini%ating the name o$ an attribute &e.g., incr' an >hat
ata type the attribute has &e.g., integer'. 5he ata type >ill help >ith
%ompile3time valiation an in getting any supplie values $or this attribute
parse into the appropriate type at runtime.
)ere, >e ini%ate there are three attributes* max &ini%ating the highest
value the 9eter >ill go to', incr &ini%ating ho> mu%h the value shoul
in%rease >hen the in%rement button is %li%ke', an decr &ini%ating ho>
mu%h the value shoul e%rease >hen the e%rement button is %li%ke'.
The id!et $mplementation
5here are many >ays to go about a%tually implementing a >iget. 5his
se%tion outlines one option* using a %ontainer %lass &spe%i$i%ally
*inear*a+o&t' an in$lating the %ontents o$ your >iget layout into the
%ontainer.
The Constructor
5o be usable insie o$ layout HML, you nee to implement a %onstru%tor
that takes t>o parameters*
-0
-. A Context obLe%t, typi%ally representing the 3ctivit+ that is in$lating
your >iget
2. An 3ttrib&teSet, representing the bunle o$ attributes in%lue in
the element in the layout being in$late that re$eren%es your >iget
.n this %onstru%tor, a$ter %haining to your super%lass, you %an o some basi%
%on$iguration o$ your >iget. /ear in min, though, that you are not in
position to %on$igure the >igets that make up your aggregate >iget M you
nee to >ait until onKinis-Inflate() be$ore you %an o anything >ith those.
Gne thing you e$initely >ant to o in the %onstru%tor, though, is use that
3ttrib&teSet to get the values o$ >hatever attributes you e$ine in your
attrs.xml $ile. (or e;ample, here is the %onstru%tor $or 9eter*
p&blic %eter(final Context ctxt> 3ttrib&teSet attrs) 4
s&per(ctxt> attrs):
t-is.set$rientation(B26IL2=<3*):
<+ped3rra+ a#ctxt.obtainStyled&ttributes(attrs>
6.st+leable.9eter>
%> %):
max#a.getInt(6.st+leable.9eter/max> 1%%):
incr3mo&nt#a.getInt(6.st+leable.9eter/incr> 1):
decr3mo&nt#'1Ma.getInt(6.st+leable.9eter/decr> 1):
a.recycle():
?
5he obtainSt+led3ttrib&tes() on Context allo>s us to %onvert the
3ttrib&teSet into use$ul values*
.t resolves re$eren%es to other resour%es, su%h as strings
.t hanles any styles that might be e%lare via the style attribute in
the layout element that re$eren%es your >iget
.t $ins the resour%es you e%lare via attrs.;ml an makes them
available to you
.n the %oe sho>n above, >e get our <+ped3rra+ via
obtainSt+led3ttrib&tes(), then %all getInt() three times to get our values
-2
out o$ the <+ped3rra+. 5he <+ped3rra+ is keye by 6.st+leable ienti$iers, so
>e use the three generate $or us by the buil tools $or max, incr, an decr.
0ote that you shoul %all rec+cle() on the <+ped3rra+ >hen one M this
makes this <+ped3rra+ available $or immeiate reuse, rather than $or%ing it
to be garbage3%olle%te.
Finishing Inflation
Dour >iget >ill also typi%ally overrie onKinis-Inflate(). At this point, you
%an turn aroun an a your o>n %ontents, via +ava %oe or, as sho>n
belo>, by in$lating a layout HML resour%e into yoursel$ as a %ontainer*
02verride
protected void on'inis!Inflate() 4
s&per.on'inis!Inflate():
((3ctivit+)getConte(t()).getLayoutInflater().inflate(6.la+o&t.meter> t-is):
bar#(5rogress;ar)findViewById(6.id.bar):
bar.set%a((max):
Image;&tton btn#(Image;&tton)findViewById(6.id.incr):
btn.set$nClic)Listener(new View.$nClic)Listener() 4
p&blic void onClic)(View v) 4
bar.incrementrogressBy(incr3mo&nt):
if (onIncrN#n&ll) 4
onIncr.onClic)(9eter.t-is):
?
?
?):
btn#(Image;&tton)findViewById(6.id.decr):
bar.incrementrogressBy(decr3mo&nt):
if (on7ecrN#n&ll) 4
on7ecr.onClic)(9eter.t-is):
?
?
?):
?
-3
G$ %ourse, on%e you have %onstru%te or in$late your %ontents, you %an
%on$igure them, parti%ularly using the attributes you e%lare in attrs.;ml
an retrieve in your %onstru%tor.
Event Handlers and Other Methods
.$ you >ish to e;pose events to the outsie >orl M su%h as 9eter e;posing
>hen the in%rement or e%rement buttons are %li%ke M you nee to o a
$e> things*
Choose or %reate an appropriate listener %lass or %lasses &e.g.,
View.2nClic.*istener'
)ol onto instan%es o$ those %lasses as ata members o$ the >iget
%lass
G$$er setters &an, optionally, getters' to e$ine those listener
obLe%ts
Call those listeners >hen appropriate
(or e;ample, 9eter hols onto a pair o$ View.2nClic.*istener instan%es*
private View.2nClic.*istener onIncr#n&ll:
private View.2nClic.*istener on7ecr#n&ll:
.t lets users o$ 9eter e$ine those listeners via getters*
p&blic void set$nIncrListener(View.2nClic.*istener onIncr) 4
t-is.onIncr#onIncr:
?
p&blic void set$n"ecrListener(View.2nClic.*istener on7ecr) 4
t-is.on7ecr#on7ecr:
?
An, as sho>n in the previous se%tion, it passes along the button %li%ks to
the listeners*
Image;&tton btn#(Image;&tton)findViewById(6.id.incr):
-4
bar.incrementrogressBy(incr3mo&nt):
if (onIncrN#n&ll) 4
onIncr.onClic)(9eter.t-is):
?
?
?):
btn#(Image;&tton)findViewById(6.id.decr):
bar.incrementrogressBy(decr3mo&nt):
if (on7ecrN#n&ll) 4
on7ecr.onClic)(9eter.t-is):
?
?
?):
0ote that >e %hange the value passe in the onClic.() metho M our
listener re%eives the Image;&tton, but >e pass the 9eter >iget on the
outboun onClic.() %all. 5his is so >e o not leak internal implementation
o$ our >iget. 5he users o$ 9eter shoul neither kno> nor %are that >e have
Image;&tton >igets as part o$ the 9eter internals.
Dour >iget may >ell re<uire other methos as >ell, $or >iget3spe%i$i%
%on$iguration or $un%tionality, though 9eter oes not.
%sin! the id!et
8iven all o$ that, using the 9eter >iget is not signi$i%antly i$$erent than
using any other >iget provie in the system...>ith a $e> minor
e;%eptions.
.n the layout, sin%e your %ustom >iget is not in the android.widget +ava
pa%kage, you nee to $ully3<uali$y the %lass name $or the >iget, as seen in
the main.xml layout $or the Views/9eter proLe%t*
xmlns,app#$-ttp,//sc-emas.android.com/ap./res/com.commonsware.android.widget$
-5
android,padding<op#$Hpx$
)
<extView
android,la+o&t/widt-#$wrap/content$
android,text#$9eter,$
/)
com.commonsware.android.widget.9eter
android,id#$01id/meter$
app,max#$1%%$
app,incr#$1$
app,decr#$H$
/)
/*inear*a+o&t)
Dou >ill also note that >e have a ne> namespa%e &xmlns,app #
$-ttp,//sc-emas.android.com/ap./res/com.commonsware.android.widget$', an
that our %ustom attributes $rom above are in that namespa%e &e.g., app,max'.
5he %ustom namespa%e is be%ause our attributes are not o$$i%ial Anroi
ones an so >ill not be re%ogniCe by the buil tools in the android,
namespa%e, so >e have to %reate our o>n. 5he value o$ the namespa%e
nees to be -ttp,//sc-emas.android.com/ap./res/ plus the name o$ the
pa%kage %ontaining the styleable attributes
&com.commonsware.android.widget'.
With Lust the sto%k generate a%tivity, >e get the $ollo>ing ".*
%6
!igure 0/ The 8eter9emo application
0ote that there is a signi$i%ant short%ut >e are taking here* our 9eter
implementation an its %onsumer &9eter7emo' are in the same +ava pa%kage.
We >ill e;pose this short%ut in a later %hapter >hen >e use the 9eter
>iget in another proLe%t.
Change of State
#ometimes, >e o not nee to %hange the $un%tionality o$ an e;isting
>iget, but >e simply >ant to %hange ho> it looks. Maybe you >ant an
oly3shape ;&tton, or a C-ec.;ox that is mu%h larger, or something. .n
these %ases, you may be able to tailor instan%es o$ the e;isting >iget as you
see $it, rather than have to roll a separate >iget yoursel$.
Chan!in! Button Bac&!rounds
#uppose you >ant a ;&tton that looks like the se%on button sho>n belo>*
%-
!igure 2/ The !ancyButton application* sho)ing a normal oval"shaped button
Moreover, it nees to not Lust sit there, but also be $o%usable*
!igure 3/ The !ancyButton application* sho)ing a focused oval"shaped button
%%
...an it nees to be %li%kable*
!igure 4/ The !ancyButton application* sho)ing a pressed oval"shaped button
.$ you i not >ant the look o$ the ;&tton to %hange, you %oul get by Lust
>ith a simple android,bac.gro&nd attribute on the ;&tton, proviing an oval
!08. )o>ever, i$ you >ant the /utton to %hange looks base on state, you
nee to %reate another $lavor o$ %ustom 7rawable M the sele%tor.
A sele%tor 7rawable is an HML $ile, akin to shapes >ith graients. )o>ever,
rather than spe%i$ying a shape, it spe%i$ies a set o$ other 7rawable resour%es
an the %ir%umstan%es uner >hi%h they shoul be applie, as es%ribe via
a series o$ states $or the >iget using the 7rawable.
(or e;ample, $rom Views/Kanc+;&tton, here is res/drawable/fanc+b&tton.xml,
implementing a sele%tor 7rawable*
selector xmlns,android#$-ttp,//sc-emas.android.com/ap./res/android$)
item
android,state/foc&sed#$tr&e$
android,state/pressed#$false$
android,drawable#$0drawable/btn/oval/selected$
%.
/)
item
android,state/foc&sed#$tr&e$
android,state/pressed#$tr&e$
android,drawable#$0drawable/btn/oval/pressed$
/)
item
android,state/foc&sed#$false$
android,state/pressed#$tr&e$
android,drawable#$0drawable/btn/oval/pressed$
/)
item
android,drawable#$0drawable/btn/oval/normal$
/)
/selector)
5here are $our states being es%ribe in this sele%tor*
-. Where the button is $o%use &android,state/foc&sed # $tr&e$' but
not presse &android,state/pressed # $false$'
2. Where the button is both $o%use an presse
?. Where the button is not $o%use but is presse
=. 5he e$ault, >here the button is neither $o%use nor presse
.n these $our states, >e spe%i$y three 7rawable resour%es, $or normal,
$o%use, an presse &the latter being use regarless o$ $o%us'.
.$ >e spe%i$y this sele%tor 7rawable resour%e as the android,bac.gro&nd o$ a
;&tton, Anroi >ill use the appropriate !08 base on the status o$ the
;&tton itsel$*
)
;&tton
android,text#$Clic. meN$
/)
;&tton
%$
android,text#$Clic. meN$
android,bac.gro&nd#$0drawable/fanc+b&tton$
/)
/*inear*a+o&t)
Chan!in! Chec&Bo' (tates
5he same basi% %on%ept %an be use to %hange the images use by a
C-ec.;ox.
.n this %ase, the $a%t that Anroi is open sour%e helps, as >e %an e;tra%t
$iles an resour%es $rom Anroi an aLust them to %reate our o>n
eitions, >ithout >orrying about li%ense hassles.
(or e;ample, here is a sele%tor 7rawable $or a $an%y C-ec.;ox, sho>ing a
iCCying array o$ possible states*
selector xmlns,android#$-ttp,//sc-emas.android.com/ap./res/android$)
N'' 8nabled states '')

item android,state/c-ec.ed#$tr&e$ android,state/window/foc&sed#$false$
android,state/enabled#$tr&e$
android,drawable#$0drawable/btn/c-ec./on$ /)
item android,state/c-ec.ed#$false$ android,state/window/foc&sed#$false$
android,drawable#$0drawable/btn/c-ec./off$ /)
item android,state/c-ec.ed#$tr&e$ android,state/pressed#$tr&e$
android,drawable#$0drawable/btn/c-ec./on/pressed$ /)
item android,state/c-ec.ed#$false$ android,state/pressed#$tr&e$
android,drawable#$0drawable/btn/c-ec./off/pressed$ /)
item android,state/c-ec.ed#$tr&e$ android,state/foc&sed#$tr&e$
android,drawable#$0drawable/btn/c-ec./on/selected$ /)
item android,state/c-ec.ed#$false$ android,state/foc&sed#$tr&e$
android,drawable#$0drawable/btn/c-ec./off/selected$ /)
item android,state/c-ec.ed#$false$
android,drawable#$0drawable/btn/c-ec./off$ /)
item android,state/c-ec.ed#$tr&e$
%0
android,drawable#$0drawable/btn/c-ec./on$ /)
N'' 7isabled states '')
item android,state/c-ec.ed#$tr&e$ android,state/window/foc&sed#$false$
android,drawable#$0drawable/btn/c-ec./on/disable$ /)
item android,state/c-ec.ed#$false$ android,state/window/foc&sed#$false$
android,drawable#$0drawable/btn/c-ec./off/disable$ /)
item android,state/c-ec.ed#$tr&e$ android,state/foc&sed#$tr&e$
android,drawable#$0drawable/btn/c-ec./on/disable/foc&sed$ /)
item android,state/c-ec.ed#$false$ android,state/foc&sed#$tr&e$
android,drawable#$0drawable/btn/c-ec./off/disable/foc&sed$ /)
item android,state/c-ec.ed#$false$
android,drawable#$0drawable/btn/c-ec./off/disable$ /)
item android,state/c-ec.ed#$tr&e$
android,drawable#$0drawable/btn/c-ec./on/disable$ /)
/selector)
Ba%h o$ the re$eren%e !08 images %an be e;tra%te $rom the android.Aar
$ile in your Anroi #@K, or obtaine $rom various online resour%es. .n the
%ase o$ Views/Kanc+C-ec., >e Coome ea%h o$ the images to 200P o$ original
siCe, to make a set o$ large &albeit $uCCy' %he%kbo; images.
!igure 5/ :n example of a ;oomed CheckBox image
.n our layout, >e %an spe%i$y that >e >ant to use our
res/drawable/fanc+c-ec..xml sele%tor 7rawable as our ba%kgroun*
)
C-ec.;ox
%2
android,text#$IOm normalN$
/)
C-ec.;ox
android,text#$ $
android,b&tton#$0drawable/fanc+c-ec.$
android,bac.gro&nd#$0drawable/btn/c-ec./label/bac.gro&nd$
/)
/*inear*a+o&t)
5his gives us a look like this*
!igure -6/ The !ancyCheck application* sho)ing a focused and checked
CheckBox
0ote that our C-ec.;ox te;t is blank. 5he reason is that C-ec.;ox is e;pe%ting
the graphi%s to be ?2p; >ie. #in%e ours are substantially larger, the
C-ec.;ox images overlap the te;t. (i;ing this >oul re<uire substantial
>ork. .t is simplest to $ill the C-ec.;ox te;t >ith some >hitespa%e, then use
a separate <extView $or our C-ec.;ox %aption.
%3
CHAPTER )
8ore !un With ist(ie)s
Gne o$ the most important >igets in your toolbelt is the *istView. #ome
a%tivities are purely a *istView, to allo> the user to si$t through a $e>
%hoi%es...or perhaps a $e> thousan. We alreay sa> in The Busy Coder's
Guide to Android Deelopment ho> to %reate I$an%y *istViewsI, >here you
have %omplete %ontrol over the list ro>s themselves. .n this %hapter, >e >ill
%over some aitional te%hni<ues you %an use to make your *istView
>igets be pleasant $or your users to >ork >ith.
'iant <conomy"Si;e 9ividers
Dou may have noti%e that the pre$eren%e ". has >hat behaves a lot like a
*istView, but >ith a %urious %hara%teristi%* not everything is sele%table*
%5
!igure --/ : PreferenceScreen 1+
Dou may have thought that this re<uire some %ustom >iget, or some
$an%y on3the3$ly View hanling, to a%hieve this e$$e%t.
.$ so, you >oul have been >rong.
.t turns out that any *istView %an e;hibit this behavior. .n this se%tion, >e
>ill see ho> this is a%hieve an a reusable $rame>ork $or %reating su%h a
*istView.
Choosin! hat $s (electa#le
5here are t>o methos in the 3dapter hierar%hy that let you %ontrol >hat is
an is not sele%table in a *istView*
are3llItemsSelectable() shoul return tr&e $or orinary *istView
>igets an false $or *istView >igets >here some items in the
Aapter are sele%table an others are not
is8nabled(), given a position, shoul return tr&e i$ the item at that
position shoul be sele%table an false other>ise
.6
8iven these t>o, it is ImerelyI a matter o$ overriing your %hosen 3dapter
%lass an implementing these t>o methos as appropriate to get the visual
e$$e%t you esire.
As one might e;pe%t, this is not <uite as easy as it may soun.
(or e;ample, suppose you have a atabase o$ books, an you >ant to
present a list o$ book titles $or the user to %hoose $rom. (urthermore,
suppose you have arrange $or the books to be in alphabeti%al orer >ithin
ea%h maLor book style &(i%tion, 0on3(i%tion, et%.', %ourtesy o$ a >ell3%ra$te
26786 ;C %lause on your <uery. An suppose you >ant to have heaings, like
on the pre$eren%es s%reen, $or those book styles.
.$ you simply take the C&rsor $rom that <uery an han it to a
SimpleC&rsor3dapter, the t>o methos %ite above >ill be implemente as
the e$ault, saying every ro> is sele%table. An, sin%e every ro> is a book,
that is >hat you >ant...$or the books.
5o get the heaings in pla%e, your 3dapter nees to mi; the heaings in
>ith the books &so they all appear in the proper se<uen%e', return a %ustom
View $or ea%h &so heaings look i$$erent than the books', an implement
the t>o methos that %ontrol >hether the heaings or books are sele%table.
5here is no easy >ay to o this $rom a simple <uery.
.nstea, you nee to be a bit more %reative, an >rap your
SimpleC&rsor3dapter in something that %an intelligently inLe%t the se%tion
heaings.
Composition *or (ections
+e$$ #harkey, author o$ CompareBvery>here an all3aroun Anroi guru,
emonstrate a >ay o$ using %omposition to %reate a *istView >ith se%tion
heaings. 5he %oe presente here is base on his implementation, >ith a
$e> alterations. As his original %oe >as release uner the 8!Lv?, bear in
min that the %oe presente here is also release uner the 8!Lv?, as
.-
oppose to the Apa%he Li%ense 2.0 that most o$ the book7s %oe uses as a
li%ense.
5he pattern is $airly simple*
Create one 3dapter $or ea%h se%tion. (or e;ample, in the book
s%enario es%ribe above, you might have one SimpleC&rsor3dapter
$or ea%h book style &one $or (i%tion, one $or 0on3(i%tion, et%.'.
!ut ea%h o$ those 3dapter obLe%ts into a %ontainer 3dapter,
asso%iating ea%h >ith a heaing name.
.mplement, on your %ontainer 3dapter sub%lass, a metho to return
the View $or a heaing, mu%h like you might implement getView() to
return a View $or a ro>
!ut the %ontainer 3dapter in the *istView, an everything $lo>s $rom
there
Dou >ill see this implemente in the *istView/Sections sample proLe%t,
>hi%h is another ri$$ on the Ilist o$ lorem ipsum >orsI sample you see
s%attere throughout the Busy Coder books.
5he layout $or the s%reen is Lust a *istView, be%ause the a%tivity M
Sectioned7emo M is Lust a *ist3ctivit+*
*istView
xmlns,android#$-ttp,//sc-emas.android.com/ap./res/android$
android,id#$0android,id/list$
android,drawSelector2n<op#$tr&e$
/)
Most o$ the smarts %an be $oun in Sectioned3dapter. 5his %lass e;tens
3dapter an elegates all o$ the 3dapter methos to a list o$ %hil 3dapter
obLe%ts*
pac.age com.commonsware.android.listview:
import android.view.View:
.%
import android.view.ViewGro&p:
import android.widget.3dapter:
import android.widget.;ase3dapter:
import Aava.&til.3rra+*ist:
import Aava.&til.*ist:
abstract p&blic class Sectioned3dapter extends ;ase3dapter 4
abstract protected View get*eaderView(String caption>
int index>
View convertView>
ViewGro&p parent):

private *istSection) sections#new 3rra+*istSection)():
private static int <C58/S8C<I2=/B83786#%:
p&blic Sectioned&dapter() 4
s&per():
?
p&blic void addSection(String caption> 3dapter adapter) 4
sections.add(new Section(caption> adapter)):
?
p&blic 2bAect getItem(int position) 4
for (Section section , t-is.sections) 4
if (position##%) 4
ret&rn(section):
?

int siIe#section.adapter.getCount()11:
if (positionsiIe) 4
ret&rn(section.adapter.getItem(position'1)):
?
position'#siIe:
?

ret&rn(n&ll):
?
p&blic int getCount() 4
int total#%:

total1#section.adapter.getCount()11: // add one for -eader
?

ret&rn(total):
?
p&blic int getView+ypeCount() 4
int total#1: // one for t-e -eader> pl&s t-ose from sections

..
total1#section.adapter.getView+ypeCount():
?

ret&rn(total):
?
p&blic int getItemView+ype(int position) 4
int t+pe2ffset#<C58/S8C<I2=/B8378611: // start co&nting from -ere

if (position##%) 4
ret&rn(<C58/S8C<I2=/B83786):
?

if (positionsiIe) 4
ret&rn(t+pe2ffset1section.adapter.getItemView+ype(position'1)):
?
position'#siIe:
t+pe2ffset1#section.adapter.getView+ypeCount():
?

ret&rn('1):
?
p&blic boolean are&llItemsSelectable() 4
ret&rn(false):
?
p&blic boolean isEnabled(int position) 4
ret&rn(getItemView+ype(position)N#<C58/S8C<I2=/B83786):
?
02verride
p&blic View getView(int position> View convertView>
ViewGro&p parent) 4
int sectionIndex#%:

if (position##%) 4
ret&rn(get*eaderView(section.caption> sectionIndex>
convertView> parent)):
?
if (positionsiIe) 4
ret&rn(section.adapter.getView(position'1>
convertView>
parent)):
?
.$
position'#siIe:
sectionIndex11:
?

ret&rn(n&ll):
?
02verride
p&blic long getItemId(int position) 4
ret&rn(position):
?
class Section 4
String caption:
3dapter adapter:

Section(String caption> 3dapter adapter) 4
t-is.caption#caption:
t-is.adapter#adapter:
?
?
?
Sectioned3dapter hols a *ist o$ Section obLe%ts, >here a Section is simply a
name an an 3dapter holing the %ontents o$ that se%tion o$ the list. Dou
%an give Sectioned3dapter the etails o$ a Section via addSection() M the
se%tions >ill appear in the orer in >hi%h they >ere ae.
Sectioned3dapter synthesiCes the overall list o$ obLe%ts $rom ea%h o$ the
aapters, plus the se%tion heaings. #o, $or e;ample, the implementation o$
getView() >alks ea%h se%tion an returns either a View $or the se%tion
heaer &i$ the re<ueste item is the $irst one $or that se%tion' or the View
$rom the se%tion7s aapter &i$ the re<ueste item is any other one in this
se%tion'. 5he same hols true $or getCo&nt() an getItem().
Gne thing that Sectioned3dapter nees to o, though, is ensure that the
pool o$ se%tion heaer View obLe%ts is re%y%le separately $rom ea%h
se%tion7s o>n pool o$ View obLe%ts. 5o o this, Sectioned3dapter takes
avantage o$ getView<+peCo&nt(), by returning the total number o$ istin%t
types o$ View obLe%ts $rom all se%tion 3dapters plus one $or its o>n heaer
View pool. #imilarly, getItemView<+pe() %onsiers the %th View type to be the
heaer View pool, >ith the pools $or ea%h 3dapter in se<uen%e starting $rom
-. 5his pattern re<uires that ea%h se%tion 3dapter have its View type numbers
.0
starting $rom 0 an in%rementing by -, but most 3dapter %lasses only use
one View type an o not even implement their o>n getView<+peCo&nt() or
getItemView<+pe(), so this >ill >ork most o$ the time.
5o use a Sectioned3dapter, Sectioned7emo simply %reates one, as in three
se%tions &>ith three sets o$ the lorem ipsum >ors', an atta%hes the
Sectioned3dapter to the *istView $or the *ist3ctivit+*
import android.app.*ist3ctivit+:
import android.content.Context:
import android.os.;&ndle:
import android.widget.3dapterView:
import android.widget.3rra+3dapter:
import android.widget.*istView:
import android.widget.<extView:
import Aava.&til.3rra+s:
import Aava.&til.Collections:
p&blic class Sectioned7emo extends *ist3ctivit+ 4
private static StringPQ items#4$lorem$> $ips&m$> $dolor$>
$sit$> $amet$> $consectet&er$>
$adipiscing$> $elit$> $morbi$>
$vel$> $lig&la$> $vitae$>
$arc&$> $ali@&et$> $mollis$>
$etiam$> $vel$> $erat$>
$placerat$> $ante$>
$porttitor$> $sodales$>
$pellentes@&e$> $a&g&e$>
$p&r&s$?:

02verride

adapter.addSection($2riginal$>
new 3rra+3dapterString)(t-is>
android.6.la+o&t.simple/list/item/1>
items)):

*istString) list#3rra+s.asList(items):

Collections.s!uffle(list):
adapter.addSection($S-&ffled$>
.2
list)):

list#3rra+s.asList(items):

adapter.addSection($6e's-&ffled$>
list)):

setList&dapter(adapter):
?

Sectioned3dapter adapter#new Sectioned&dapter() 4
protected View get*eaderView(String caption> int index>
View convertView>
ViewGro&p parent) 4
<extView res&lt#(<extView)convertView:

if (convertView##n&ll) 4
res&lt#(<extView)getLayoutInflater()
.inflate(6.la+o&t.-eader>
n&ll):
?

res&lt.set+e(t(caption):

ret&rn(res&lt):
?
?:
?
5he result is mu%h as you might e;pe%t*
.3
!igure -%/ : ist(ie) using a Sectioned:dapter* sho)ing one header and part
of a list
)ere, the heaers are simple bits o$ te;t >ith an appropriate style applie.
Dour se%tion heaers, o$ %ourse, %an be as %omple; as you like.
!rom =ead To Toe
!erhaps you o not nee se%tion heaers s%attere throughout your list. .$
you only nee e;tra I$ake ro>sI at the beginning or en o$ your list, you %an
use heaer an $ooter vie>s.
*istView supports addBeaderView() an addKooterView() methos that allo>
you to a View obLe%ts to the beginning an en o$ the list, respe%tively.
5hese View obLe%ts other>ise behave like regular ro>s, in that they are part
o$ the s%rolle area an >ill s%roll o$$ the s%reen i$ the list is long enough. .$
you >ant $i;e heaers or $ooters, rather than put them in the *istView
itsel$, put them outsie the *istView, perhaps using a *inear*a+o&t.
5o emonstrate heaer an $ooter vie>s, take a peek at
*istView/BeaderKooter, parti%ularly the BeaderKooter7emo %lass*
.4
import android.os.Bandler:
import android.os.S+stemCloc.:
import android.widget.;&tton:
import Aava.&til.3rra+s:
import Aava.&til.Collections:
import Aava.&til.conc&rrent.atomic.3tomic;oolean:
p&blic class BeaderKooter7emo extends *ist3ctivit+ 4
$placerat$> $ante$>
$p&r&s$?:
private long start<ime#S+stemCloc..uptime%illis():
private Bandler -andler#new *andler():
private 3tomic;oolean areWe7eadCet#new &tomicBoolean(false):

02verride
getListView().add*eaderView(build*eader()):
getListView().add'ooterView(build'ooter()):
setList&dapter(new 3rra+3dapterString)(t-is>
items)):
?

02verride
p&blic void on"estroy() 4
s&per.on"estroy():

areWe7eadCet.set(tr&e):
?

private View build*eader() 4
;&tton btn#new Button(t-is):

.5
btn.set+e(t($6andomiIeN$):
*istString) list#3rra+s.asList(items):


setList&dapter(new 3rra+3dapterString)(BeaderKooter7emo.t-is>
list)):
?
?):

ret&rn(btn):
?

private View build'ooter() 4
<extView txt#new +e(tView(t-is):

update'ooter(txt):

ret&rn(txt):
?

private void update'ooter(final <extView txt) 4
long r&ntime#(S+stemCloc..uptime%illis()'start<ime)/1%%%:

txt.set+e(t(String.value$f(r&ntime)1$ seconds since activit+ la&nc-ed$):

if (NareWe7eadCet.get()) 4
-andler.post"elayed(new Runnable() 4
p&blic void run() 4

update'ooter(txt):
?
?> 1%%%):
?
?
?
)ere, >e a a heaer View built via b&ildBeader(), returning a ;&tton that,
>hen %li%ke, >ill shu$$le the %ontents o$ the list. We also a a $ooter View
built via b&ildKooter(), returning a <extView that sho>s ho> long the
a%tivity has been running, upate every se%on. 5he list itsel$ is the ever3
popular list o$ lorem ipsum >ors.
When initially isplaye, the heaer is visible but the $ooter is not, be%ause
the list is too long*
$6
!igure -./ : ist(ie) )ith a header vie) sho)n
.$ you s%roll o>n>ar, the heaer >ill slie o$$ the top, an eventually the
$ooter >ill s%roll into vie>*
!igure -$/ : ist(ie) )ith a footer vie) sho)n
$-
Control 7our Selection
5he sto%k Anroi ". $or a sele%te *istView ro> is $airly simplisti%* it
highlights the ro> in orange...an nothing more. Dou %an %ontrol the
7rawable use $or sele%tion via the android,listSelector an
android,drawSelector2n<op attributes on the *istView element in your
layout. )o>ever, even those simply apply some generi% look to the sele%te
ro>.
.t may be you >ant to o something more elaborate $or a sele%te ro>, su%h
as %hanging the ro> aroun to e;pose more in$ormation. Maybe you have
thumbnail photos but only isplay the photo on the sele%te ro>. Gr
perhaps you >ant to sho> some sort o$ se%onary line o$ te;t, like a
person7s instant messenger status, only on the sele%te ro>. Gr, there may
be times you >ant a more subtle ini%ation o$ the sele%te item than having
the >hole ro> sho> up in some neon %olor. 5he sto%k Anroi ". $or
highlighting a sele%tion >ill not o any o$ this $or you.
5hat Lust means you have to o it yoursel$. 5he goo ne>s is, it is not very
i$$i%ult.
Create a %ni*ied Ro+ ,ie+
5he simplest >ay to a%%omplish this is $or ea%h ro> View to have all o$ the
>igets you >ant $or the sele%te3ro> perspe%tive, but >ith the Ie;tra stu$$I
$lagge as invisible at the outset. 5hat >ay, ro>s initially look InormalI
>hen put into the list M all you nee to o is toggle the invisible >igets to
visible >hen a ro> gets sele%te an toggle them ba%k to invisible >hen a
ro> is e3sele%te.
(or e;ample, in the *istView/Selector proLe%t, you >ill $in a ro>.;ml
layout representing a ro> in a list*
*inear*a+o&t
$%
android,la+o&t/-eig-t#$fill/parent$ )
View
android,id#$01id/bar$
android,bac.gro&nd#$RKKKK%%%%$
android,la+o&t/widt-#$Hpx$
android,visibilit+#$invisible$
/)
<extView
android,id#$01id/label$
android,textSiIe#$1%pt$
android,padding<op#$Epx$
android,padding;ottom#$Epx$
android,padding*eft#$Hpx$
/)
/*inear*a+o&t)
5here is a <extView representing the bulk o$ the ro>. /e$ore it, though, on
the le$t, is a plain View name bar. 5he ba%kgroun o$ the View is set to re
&android,bac.gro&nd # $RKKKK%%%%$' an the >ith to Hpx. More importantly,
it is set to be invisible &android,visibilit+ # $invisible$'. )en%e, >hen the
ro> is put into a *istView, the re bar is not seen...until >e make the bar
visible.
Con*i!ure the "ist- Get Control on (election
0e;t, >e nee to set up a *istView an arrange to be noti$ie >hen ro>s are
sele%te an e3sele%te. 5hat is merely a matter o$ %alling
set2nItemSelected*istener() $or the *istView, proviing a listener to be
noti$ie on a sele%tion %hange. Dou %an see that in the %onte;t o$ a
*ist3ctivit+ in our Selector7emo %lass*
import android.content.res.ColorState*ist:
$.
p&blic class Selector7emo extends *ist3ctivit+ 4
private static ColorState*ist allW-ite#ColorState*ist.value$f(%xKKKKKKKK):
$placerat$> $ante$>
$p&r&s$?:

02verride
setList&dapter(new Selector&dapter(t-is)):
getListView().set$nItemSelectedListener(listener):
?

class Selector3dapter extends 3rra+3dapter 4
Selector&dapter(Context ctxt) 4
s&per(ctxt> 6.la+o&t.row> items):
?

02verride
ViewGro&p parent) 4
SelectorWrapper wrapper#n&ll:

convertView#getLayoutInflater().inflate(6.la+o&t.row>
n&ll):
wrapper#new Selector,rapper(convertView):
wrapper.getLabel().set+e(tColor(allW-ite):
convertView.set+ag(wrapper):
?
else 4
wrapper#(SelectorWrapper)convertView.get+ag():
?

wrapper.getLabel().set+e(t(itemsPpositionQ):

ret&rn(convertView):
?
?

class SelectorWrapper 4
View row#n&ll:
<extView label#n&ll:
View bar#n&ll:
$$

Selector,rapper(View row) 4
t-is.row#row:
?

<extView getLabel() 4
if (label##n&ll) 4
label#(<extView)row.findViewById(6.id.label):
?

ret&rn(label):
?

View getBar() 4
if (bar##n&ll) 4
bar#row.findViewById(6.id.bar):
?

ret&rn(bar):
?
?

3dapterView.2nItemSelected*istener listener#new
3dapterView.$nItemSelectedListener() 4
View last6ow#n&ll:

p&blic void onItemSelected(3dapterView!) parent>
View view> int position>
long id) 4
if (last6owN#n&ll) 4
SelectorWrapper wrapper#(SelectorWrapper)last6ow.get+ag():
wrapper.getBar().setVisibility(View.I=VISI;*8):
?

SelectorWrapper wrapper#(SelectorWrapper)view.get+ag():

wrapper.getBar().setVisibility(View.VISI;*8):
last6ow#view:
?

p&blic void on-ot!ingSelected(3dapterView!) parent) 4
SelectorWrapper wrapper#(SelectorWrapper)last6ow.get+ag():
wrapper.getBar().setVisibility(View.I=VISI;*8):
last6ow#n&ll:
?
?
?:
?
$0
Selector7emo sets up a Selector3dapter, >hi%h $ollo> the vie>3>rapper
pattern establishe in The Busy Coder's Guide to Android Deelopment.
Ba%h ro> is %reate $rom the layout sho>n earlier, >ith a SelectorWrapper
proviing a%%ess to both the <extView &$or setting the te;t in a ro>' an the
bar View.
Chan!e the Ro+
Gur 3dapterView.2nItemSelected*istener instan%e keeps tra%k o$ the last
sele%te ro> &last6ow'. When the sele%tion %hanges to another ro> in
onItemSelected(), >e make the bar $rom the last sele%te ro> invisible,
be$ore >e make the bar visible on the ne>ly3sele%te ro>. .n
on=ot-ingSelected(), >e make the bar invisible an make our last sele%te
ro> be null.
5he net e$$e%t is that as the sele%tion %hanges, >e toggle the bar o$$ an on
as neee to ini%ate >hi%h is the sele%te ro>.
.n the layout $or the a%tivity7s *istView, >e turn o$$ the regular highlighting*
*istView
android,listSelector#$R%%%%%%%%$
/)
5he result is >e are %ontrolling the highlight, in the $orm o$ the re bar*
$2
!igure -0/ : ist(ie) )ith a custom"dra)n selector icon
Gbviously, >hat >e o to highlight a ro> %oul be mu%h more elaborate
than >hat is emonstrate here. At the same time, it nees to be $airly
<ui%k to e;e%ute, lest the list appear to be too sluggish.
$3
CHAPTER .
Sho) 1p :t =ome
Gne o$ the o$t3re<ueste $eatures ae in Anroi -.A is the ability to a
live elements to the home s%reen. Calle Iapp >igetsI, these %an be ae
by users via a long3tap on the home s%reen an %hoosing an appropriate
>iget $rom the available roster. Anroi ships >ith a $e> app >igets,
su%h as a musi% player, but evelopers %an a their o>n M in this %hapter,
>e >ill see ho> this is one.
(or the purposes o$ this book, Iapp >igetsI >ill re$er to these items that go
on the home s%reen. Gther uses o$ the term I>igetI >ill be reserve $or
the ". >igets, sub%lasses o$ View, usually $oun in the android.widget +ava
pa%kage.
<ast is <ast* and West is West///
!art o$ the reason it took as long as it i $or app >igets to be%ome
available is se%urity.
Anroi7s se%urity moel is base heavily on Linu; user, $ile, an pro%ess
se%urity. Ba%h appli%ation is &normally' asso%iate >ith a uni<ue user .@.
All o$ its $iles are o>ne by that user, an its pro%ess&es' run as that user.
5his prevents one appli%ation $rom moi$ying the $iles o$ another or
other>ise inLe%ting their o>n %oe into another running pro%ess.
$5
Sho) 1p :t =ome
.n parti%ular, the %ore Anroi team >ante to $in a >ay that >oul allo>
app >igets to be isplaye by the home s%reen appli%ation, yet have their
%ontent %ome $rom another appli%ation. .t >oul be angerous $or the
home s%reen to run arbitrary %oe itsel$ or someho> allo> its ". to be
ire%tly manipulate by another pro%ess.
5he app >iget ar%hite%ture, there$ore, is set up to keep the home s%reen
appli%ation inepenent $rom any %oe that puts app >igets on that home
s%reen, so bugs in one %annot harm the other.
The Big Picture for a Small :pp Widget
5he >ay Anroi pulls o$$ this bit o$ se%urity is through the use o$
6emoteViews.
5he appli%ation %omponent that supplies the ". $or an app >iget is not an
3ctivit+, but rather a ;roadcast6eceiver &o$ten in tanem >ith a Service'.
5he ;roadcast6eceiver, in turn, oes not in$late a normal View hierar%hy,
like an 3ctivit+ >oul, but instea in$lates a layout into a 6emoteViews
obLe%t.
6emoteViews en%apsulates a limite eition o$ normal >igets, in su%h a
$ashion that the 6emoteViews %an be IeasilyI transporte a%ross pro%ess
bounaries. Dou %on$igure the 6emoteViews via your ;roadcast6eceiver an
make those 6emoteViews available to Anroi. Anroi in turn elivers the
6emoteViews to the app >iget host &usually the home s%reen', >hi%h
reners them to the s%reen itsel$.
5his ar%hite%tural %hoi%e has many impa%ts*
-. Dou o not have a%%ess to the $ull range o$ >igets an %ontainers.
Dou %an use Krame*a+o&t, *inear*a+o&t, an 6elative*a+o&t $or
%ontainers, an 3nalogCloc., ;&tton, C-ronometer, Image;&tton,
ImageView, 5rogress;ar, an <extView $or >igets.
06
Sho) 1p :t =ome
2. 5he only user input you %an get is %li%ks o$ the ;&tton an
Image;&tton >igets. .n parti%ular, there is no 8dit<ext $or te;t
input.
?. /e%ause the app >igets are renere in another pro%ess, you
%annot simply register an 2nClic.*istener to get button %li%ksO
rather, you tell 6emoteViews a 5endingIntent to invoke >hen a given
button is %li%ke.
=. Dou o not hol onto the 6emoteViews an reuse them yoursel$.
Rather, the pattern appears to be that you %reate an sen out a
bran3ne> 6emoteViews >henever you >ant to %hange the %ontents
o$ the app >iget. 5his, %ouple >ith having to transport the
6emoteViews a%ross pro%ess bounaries, means that upating the app
>iget is rather e;pensive in terms o$ C!" time, memory, an
battery li$e.
A. /e%ause the %omponent hanling the upates is a
;roadcast6eceiver, you have to be <ui%k &lest you take too long an
Anroi %onsier you to have time out', you %annot use
ba%kgroun threas, an your %omponent itsel$ is lost on%e the
re<uest has been %omplete. )en%e, i$ your upate might take a
>hile, you >ill probably >ant to have the ;roadcast6eceiver start a
Service an have the Service o the long3running task an eventual
app >iget upate.
Crafting :pp Widgets
5his >ill be%ome some>hat easier to unerstan in the %onte;t o$ some
sample %oe. .n the 3ppWidget/<witterWidget proLe%t, you >ill $in an app
>iget that sho>s the latest t>eet in your 5>itter timeline. .$ you have rea
Android !ro"rammin" Tutorials, you >ill re%ogniCe the +5>itter +AR >e >ill
use $or a%%essing the 5>itter Web servi%e.
0-
Sho) 1p :t =ome
The /ani*est
(irst, >e nee to register our ;roadcast6eceiver &an, i$ relevant, Service'
implementation in our 3ndroid9anifest.xml $ile, along >ith a $e> e;tra
$eatures*
manifest xmlns,android#$-ttp,//sc-emas.android.com/ap./res/android$
pac.age#$com.commonsware.android.appwidget$
android,versionCode#$1$
android,version=ame#$1.%$)
&ses'permission android,name#$android.permission.I=<86=8<$ /)
application android,label#$0string/app/name$)
activit+ android,name#$.<W5refs$
android,label#$0string/app/name$)
intent'filter)
action android,name#$android.intent.action.93I=$ /)
categor+ android,name#$android.intent.categor+.*3D=CB86$ /)
/intent'filter)
intent'filter)
action
android,name#$android.appwidget.action.355WI7G8</C2=KIGD68$ /)
/intent'filter)
/activit+)
receiver android,name#$.<witterWidget$
android,label#$0string/app/name$
android,icon#$0drawable/tw/icon$)
intent'filter)
action
android,name#$android.appwidget.action.355WI7G8</D573<8$ /)
/intent'filter)
meta'data
android,name#$android.appwidget.provider$
android,reso&rce#$0xml/widget/provider$ /)
/receiver)
service android,name#$.<witterWidgetSDpdateService$ /)
/application)
/manifest)
)ere >e have an activit+), a receiver), an a service). G$ note*
Gur receiver) has android,label an android,icon attributes, >hi%h
are not normally neee on ;roadcast6eceiver e%larations.
)o>ever, in this %ase, those are use $or the entry that goes in the
menu o$ available >igets to a to the home s%reen. )en%e, you
>ill probably >ant to supply values $or both o$ those, an use
appropriate resour%es in %ase you >ant translations $or other
languages.
0%
Sho) 1p :t =ome
Gur receiver) has an intent'filter) $or the
android.appwidget.action.355WI7G8</D573<8 a%tion. 5his means >e
>ill get %ontrol >henever Anroi >ants us to upate the %ontent o$
our app >iget. 5here may be other a%tions >e >ant to monitor M
more on this in a later se%tion.
Gur receiver) also has a meta'data) element, ini%ating that its
android.appwidget.provider etails %an be $oun in the
res/xml/widget/provider.xml $ile. 5his metaata is es%ribe in the
ne;t se%tion.
Gur activit+) has t>o intent'filter) elements, the normal Iput
me in the Laun%herI one an one looking $or an a%tion o$
android.appwidget.action.355WI7G8</C2=KIGD68.
The /etadata
0e;t, >e nee to e$ine the app >iget provier metaata. 5his has to
resie at the lo%ation ini%ate in the mani$est M in this %ase, in
res/xml/widget/provider.xml*
appwidget'provider xmlns,android#$-ttp,//sc-emas.android.com/ap./res/android$
android,minWidt-#$ETEdip$
android,minBeig-t#$GEdip$
android,&pdate5eriod9illis#$T%%%%%$
android,config&re#$com.commonsware.android.appwidget.<W5refs$
/)
)ere, >e provie $our pie%es o$ in$ormation*
5he minimum >ith an height o$ the app >iget &android,minWidt-
an android,minBeig-t'. 5hese are appro;imate M the app >iget
host &e.g., home s%reen' >ill ten to %onvert these values into I%ellsI
base upon the overall layout o$ the ". >here the app >igets >ill
resie. )o>ever, they shoul be no smaller than the minimums
%ite here.
5he $re<uen%y in >hi%h Anroi shoul re<uest an upate o$ the
>iget7s %ontents &android,&pdate5eriod9illis'. 5his is e;presse in
terms o$ millise%ons, so a value o$ T%%%%% is a -A3minute upate
%y%le.
0.
Sho) 1p :t =ome
An a%tivity %lass that >ill be use to %on$igure the >iget >hen it is
$irst ae to the s%reen &android,config&re'. 5his >ill be es%ribe
in greater etail in a later se%tion.
5he %on$iguration a%tivity is optional. )o>ever, i$ you skip the
%on$iguration a%tivity, you o nee to tell Anroi the initial layout to use
$or the app >iget, via an android,initial*a+o&t attribute.
The "ayout
Bventually, you are going to nee a layout that es%ribes >hat the app
>iget looks like. #o long as you sti%k to the >iget an %ontainer %lasses
note above, this layout %an other>ise look like any other layout in your
proLe%t.
(or e;ample, here is the layout $or the <witterWidget*
6elative*a+o&t xmlns,android#$-ttp,//sc-emas.android.com/ap./res/android$
android,bac.gro&nd#$RKK%%%%(($
)
Image;&tton android,id#$01id/refres-$
android,la+o&t/align5arent<op#$tr&e$
android,la+o&t/align5arent6ig-t#$tr&e$
android,src#$0drawable/refres-$
/)
Image;&tton android,id#$01id/config&re$
android,la+o&t/align5arent;ottom#$tr&e$
android,la+o&t/align5arent6ig-t#$tr&e$
android,src#$0drawable/config&re$
/)
<extView android,id#$01id/friend$
android,la+o&t/align5arent<op#$tr&e$
android,la+o&t/align5arent*eft#$tr&e$
android,la+o&t/to*eft2f#$0id/refres-$
android,gravit+#$left$
0$
Sho) 1p :t =ome
android,textSt+le#$bold$
android,single*ine#$tr&e$
android,ellipsiIe#$end$
/)
<extView android,id#$01id/stat&s$
android,la+o&t/below#$0id/friend$
android,la+o&t/align5arent*eft#$tr&e$
android,la+o&t/to*eft2f#$0id/refres-$
android,gravit+#$top$
android,single*ine#$false$
android,lines#$F$
/)
/6elative*a+o&t)
All >e have is a <extView to sho> the latest t>eet, plus another one $or the
person issuing the t>eet, an a pair o$ Image;&tton >igets to allo> the user
to manually re$resh the latest t>eet an laun%h the %on$iguration a%tivity.
The BroadcastReceiver
0e;t, >e nee a ;roadcast6eciever that %an get %ontrol >hen Anroi >ants
us to upate our 6emoteViews $or our app >iget. 5o simpli$y this, Anroi
supplies an 3ppWidget5rovider %lass >e %an e;ten, instea o$ the normal
;roadcast6eceiver. 5his simply looks at the re%eive Intent an %alls out to
an appropriate li$e%y%le metho base on the re<ueste a%tion.
5he one metho that invariably nees to be implemente on the provier
is onDpdate(). Gther li$e%y%le methos may be o$ interest an are is%usse
later in this %hapter.
(or e;ample, here is the onDpdate() implementation o$ the
3ppWidget5rovider $or <witterWidget*
02verride
p&blic void onUpdate(Context ctxt>
3ppWidget9anager mgr>
intPQ appWidgetIds) 4
ctxt.startService(new Intent(ctxt> DpdateService.class)):
?
00
Sho) 1p :t =ome
.$ our 6emoteViews %oul be rapily %onstru%te, >e %oul o the >ork right
here. )o>ever, in our %ase, >e nee to make a Web servi%e %all to 5>itter,
>hi%h might take a >hile, so >e instea %all startService() on the Service
>e e%lare in our mani$est, to have it make the upates.
The (ervice
5he real >ork $or <witterWidget is mostly one in an DpdateService inner
%lass o$ <witterWidget.
DpdateService oes not e;ten Service, but rather e;tens IntentService.
IntentService is esigne $or patterns like this one, >here our servi%e is
starte multiple times, >ith ea%h IstartI representing a istin%t pie%e o$
>ork to be a%%omplishe &in this %ase, upating an app >iget $rom
5>itter'. IntentService allo>s us to implement onBandleIntent() to o this
>ork, an it arranges $or onBandleIntent() to be %alle on a ba%kgroun
threa. )en%e, >e o not nee to eal >ith starting or stopping our threa,
or even stopping our servi%e >hen there is no more >ork to be one M
Anroi hanles that automati%ally.
)ere is the onBandleIntent() implementation $rom DpdateService*
02verride
p&blic void on*andleIntent(Intent intent) 4
Component=ame me#new Component-ame(t-is>
<witterWidget.class):
3ppWidget9anager mgr#3ppWidget9anager.getInstance(t-is):
mgr.update&pp,idget(me> buildUpdate(t-is)):
?
5o upate the 6emoteViews $or our app >iget, >e nee to buil those
6emoteViews &elegate to a b&ildDpdate() helper metho' an tell an
3ppWidget9anager to upate the >iget via &pdate3ppWidget(). .n this %ase,
>e use a version o$ &pdate3ppWidget() that takes a Component=ame as the
ienti$ier o$ the >iget to be upate. 0ote that this means that >e >ill
upate all instan%es o$ this app >iget presently in use M the %on%ept o$
multiple app >iget instan%es is %overe in greater etail later in this
%hapter.
02
Sho) 1p :t =ome
Working >ith 6emoteViews is a bit like trying to tie your shoes >hile >earing
mittens M it may be possible, but it is a bit %lumsy. .n this %ase, rather than
using methos like findView;+Id() an then %alling methos on iniviual
>igets, >e nee to %all methos on 6emoteViews itsel$, proviing the
ienti$ier o$ the >iget >e >ish to moi$y. 5his is so our re<uests $or
%hanges %an be serialiCe $or transport to the home s%reen pro%ess. .t oes,
ho>ever, mean that our vie>3upating %oe looks a $air bit i$$erent than it
>oul i$ this >ere the main View o$ an a%tivity or ro> o$ a *istView.
(or e;ample, here is the b&ildDpdate() metho $rom DpdateService, >hi%h
buils a 6emoteViews %ontaining the latest 5>itter in$ormation, using
a%%ount in$ormation pulle $rom share pre$eren%es*
private 6emoteViews buildUpdate(Context context) 4
6emoteViews &pdateViews#new RemoteViews(context.getac)age-ame()>
6.la+o&t.widget):
String &ser#prefs.getString($&ser$> n&ll):
String password#prefs.getString($password$> n&ll):
if (&serN#n&ll UU passwordN#n&ll) 4
<witter client#new +witter(&ser> password):
*ist<witter.Stat&s) timeline#client.get'riends+imeline():
if (timeline.si.e())%) 4
<witter.Stat&s s#timeline.get(%):
&pdateViews.set+e(tView+e(t(6.id.friend>
s.&ser.screen=ame):
&pdateViews.set+e(tView+e(t(6.id.stat&s>
s.text):
Intent i#new Intent(t-is> <witterWidget.class):
5endingIntent pi#5endingIntent.getBroadcast(context>
% > i>
%):
&pdateViews.set$nClic)endingIntent(6.id.refres->
pi):
i#new Intent(t-is> <W5refs.class):
pi#5endingIntent.get&ctivity(context> % > i> %):
&pdateViews.set$nClic)endingIntent(6.id.config&re>
pi):
?
?
ret&rn(&pdateViews):
?
03
Sho) 1p :t =ome
5o %reate the 6emoteViews, >e use a %onstru%tor that takes our pa%kage
name an the ienti$ier o$ our layout. 5his gives us a 6emoteViews that
%ontains all o$ the >igets >e e%lare in that layout, Lust as i$ >e in$late
the layout using a *a+o&tInflater. 5he i$$eren%e, o$ %ourse, is that >e have
a 6emoteViews obLe%t, not a View, as the result.
We then use methos like*
set<extView<ext() to set the te;t on a <extView in the 6emoteViews,
given the ienti$ier o$ the <extView >ithin the layout >e >ish to
manipulate
set2nClic.5endingIntent() to provie a 5endingIntent that shoul
get $ire o$$ >hen a ;&tton or Image;&tton is %li%ke
0ote, o$ %ourse, that Anroi oes not kno> anything about 5>itter M the
5>itter obLe%t %omes $rom a +5>itter +AR lo%ate in the libs/ ire%tory o$
our proLe%t.
The Con*i!uration Activity
Way ba%k in the mani$est, >e in%lue an activit+) element $or a <W5refs
a%tivity. An, in our >iget metaata HML $ile, >e sai that <W5refs >as the
android,config&re attribute value. .n our 6emoteViews $or the >iget itsel$,
>e %onne%t a %on$igure button to laun%h <W5refs >hen %li%ke.
5he net o$ all o$ this is that <W5refs is the %on$iguration a%tivity. #pe%i$i%ally*
.t >ill be laun%he >hen >e re<uest to a this >iget to our home
s%reen
.t >ill be re3laun%he >henever >e %li%k the %on$igure button in the
>iget itsel$
(or the latter s%enario, the a%tivity nee be nothing spe%ial. .n $a%t, <W5refs
is mostly Lust a 5reference3ctivit+, upating the S-ared5references $or this
appli%ation >ith the user7s 5>itter s%reen name an pass>or, use $or
logging into 5>itter an $et%hing the latest timeline entry.
04
Sho) 1p :t =ome
5he $ormer s%enario M e$ining a %on$iguration a%tivity in the metaata M
re<uires a bit more >ork, though.
.$ >e >ere to leave this out, an not have an android,config&re attribute in
the metaata, on%e the user %hose to a our >iget to their home s%reen,
the >iget >oul immeiately appear. /ehin the s%enes, Anroi >oul
ask our 3ppWidget5rovider to supply the 6emoteViews $or the >iget boy
right a>ay.
)o>ever, >hen >e e%lare that >e >ant a %on$iguration a%tivity, >e must
buil the initial 6emoteViews ourselves an return them as the a%tivity7s
result. /ehin the s%enes, Anroi uses start3ctivit+Kor6es&lt() to laun%h
our %on$iguration a%tivity, then looks at the result an uses the asso%iate
6emoteViews to %reate the initial look o$ the >iget.
5his approa%h is prone to %oe upli%ation, an it is not %ompletely %lear
>hy Anroi ele%te to buil the >iget $rame>ork this >ay.
5hat being sai, here is the implementation o$ <W5refs*
pac.age com.commonsware.android.appwidget:
import android.app.3ctivit+:
import android.appwidget.3ppWidget9anager:
import android.appwidget.3ppWidget5rovider:
import android.content.Component=ame:
import android.content.Intent:
import android.preference.5reference3ctivit+:
import android.view.Ve+8vent:
import android.widget.6emoteViews:
p&blic class <W5refs extends 5reference3ctivit+ 4
private static String
C2=KIGD68/3C<I2=#$android.appwidget.action.355WI7G8</C2=KIGD68$:

02verride
p&blic void onCreate(;&ndle savedInstanceState) 4
s&per.onCreate(savedInstanceState):

addreferences'romResource(6.xml.preferences):
?

02verride
05
Sho) 1p :t =ome
p&blic boolean on#ey"own(int .e+Code> Ve+8vent event) 4
if (.e+Code##Ve+8vent.V8CC278/;3CV) 4
if (C2=KIGD68/3C<I2=.equals(getIntent().get&ction())) 4
Intent intent#getIntent():
;&ndle extras#intent.getE(tras():

if (extrasN#n&ll) 4
int id#extras.getInt(3ppWidget9anager.8W<63/355WI7G8</I7>
3ppWidget9anager.I=V3*I7/355WI7G8</I7):
3ppWidget9anager mgr#3ppWidget9anager.getInstance(t-is):
6emoteViews views#new RemoteViews(getac)age-ame()>
6.la+o&t.widget):

mgr.update&pp,idget(id> views):

Intent res&lt#new Intent():

res&lt.putE(tra(3ppWidget9anager.8W<63/355WI7G8</I7>
id):
setResult(68SD*</2V> res&lt):
sendBroadcast(new Intent(t-is>
<witterWidget.class)):
?
?
?

ret&rn(s&per.on#ey"own(.e+Code> event)):
?
?
We are using the same a%tivity $or t>o %ases* $or the initial %on$iguration
an $or later on3eman re%on$iguration via the %on$igure button in the
>iget. We nee to tell these apart. More importantly, >e nee to get
%ontrol at an appropriate time to set our a%tivity result in the initial
%on$iguration %ase. Alas, the normal a%tivity li$e%y%le methos &e.g.,
on7estro+()' are too late, an 5reference3ctivit+ o$$ers no other e;pli%it
hook to $in out >hen the user ismisses the pre$eren%e s%reen.
#o, >e have to %heat a bit.
#pe%i$i%ally, >e hook onVe+7own() an >at%h $or the ba%k button. When the
ba%k button is presse, i$ >e >ere laun%he by a >iget %on$iguration
Intent &C2=KIGD68/3C<I2=.e@&als(getIntent().get3ction())', then >e go
through an*
26
Sho) 1p :t =ome
8et our >iget instan%e ienti$ier &es%ribe in greater etail later
in this %hapter'
8et our 3ppWidget9anager an %reate a ne> 6emoteViews in$late $rom
our >iget layout
!ass the empty 6emoteViews to the 3ppWidget9anager via
&pdate3ppWidget()
Call set6es&lt() >ith an Intent >rapping our >iget instan%e
ienti$ier, so Anroi kno>s >e have properly %on$igure our
>iget
Raise a broa%ast Intent to ask our Widget5rovider to o the real
initial version o$ the >iget
5his minimiCes %oe upli%ation, but it oes mean there is a slight hi%%up,
>here the >iget initially appears blank, be$ore the $irst timeline entry
appears. 5his is largely unavoiable in this %ase M >e %annot >ait $or 5>itter
to respon sin%e onVe+7own() is %alle on the ". threa an >e nee to %all
set6es&lt() no> rather than >ait $or 5>itter7s response.
"noubtely, there are other patterns $or hanling this situation.
The Result
.$ you %ompile an install all o$ this, you >ill have a ne> >iget entry
available >hen you long3tap on the home s%reen ba%kgroun*
2-
Sho) 1p :t =ome
!igure -2/ The roster of available )idgets
When you %hoose 5>itter Wiget, you >ill initially be presente >ith the
%on$iguration a%tivity*
!igure -3/ The T)itterWidget configuration activity
2%
Sho) 1p :t =ome
Gn%e you set your 5>itter s%reen name an pass>or, an press the ba%k
button to e;it the a%tivity, your >iget >ill appear >ith no %ontents*
!igure -4/ T)itterWidget* immediately after being added
A$ter a moment, though, it >ill appear >ith the latest in your 5>itter
$riens timeline*
2.
Sho) 1p :t =ome
!igure -5/ T)itterWidget* )ith a timeline entry
5o %hange your 5>itter %reentials, you %an either tap the %on$igure i%on in
the >iget or run the 5>itter Wiget appli%ation in your laun%her. An,
%li%king the re$resh button, or >aiting -A minutes, >ill %ause the >iget to
upate its %ontents.
:nother and :nother
As ini%ate above, you %an have multiple instan%es o$ the same app >iget
outstaning at any one time. (or e;ample, one might have multiple pi%ture
$rames, or multiple Isho>3me3the3latest3R##3entryI app >igets, one per
$ee. Dou >ill istinguish bet>een these in your %oe via the ienti$ier
supplie in the relevant 3ppWidget5rovider %allba%ks &e.g., onDpdate()'.
.$ you >ant to support separate app >iget instan%es, you >ill nee to store
your state on a per3app3>iget3ienti$ier basis. (or e;ample, >hile
<witterWidget uses pre$eren%es $or the 5>itter a%%ount etails, you might
nee multiple pre$eren%e $iles, or use a #FLite atabase >ith an app >iget
ienti$ier %olumn, or something to istinguish one app >iget instan%e
$rom another. Dou >ill also nee to use an appropriate version o$
2$
Sho) 1p :t =ome
&pdate3ppWidget() on 3ppWidget9anager >hen you upate the app >igets,
one that takes app >iget ienti$iers as the $irst parameter, so you upate
the proper app >iget instan%es.
Conversely, there is nothing re<uiring you to support multiple instan%es as
inepenent entities. (or e;ample, i$ you a more than one <witterWidget
to your home s%reen, nothing blo>s up M they Lust sho> the same t>eet. .n
the %ase o$ <witterWidget, they might not even sho> the same t>eet all the
time, sin%e they >ill upate on inepenent %y%les, so one >ill get ne>er
t>eets be$ore another.
:pp Widgets> Their ife and Times
5>itterWiget overroe t>o 3ppWidget5rovider methos*
onDpdate(), invoke >hen the android,&pdate5eriod9illis time has
elapse
on6eceive(), the stanar ;roadcast6eceiver %allba%k, use to ete%t
>hen >e are invoke >ith no a%tion, meaning >e >ant to $or%e an
upate ue to the re$resh button being %li%ke
5here are three other li$e%y%le methos that 3ppWidget5rovider o$$ers that
you may be intereste in*
on8nabled() >ill be %alle >hen the $irst >iget instan%e is %reate
$or this parti%ular >iget provier, so i$ there is anything you nee
to o on%e $or all supporte >igets, you %an implement that logi%
here
on7eleted() >ill be %alle >hen a >iget instan%e is remove $rom
the home s%reen, in %ase there is any ata you nee to %lean up
spe%i$i% to that instan%e
on7isabled() >ill be %alle >hen the last >iget instan%e $or this
provier is remove $rom the home s%reen, so you %an %lean up
anything relate to all su%h >igets
20
Sho) 1p :t =ome
0ote, ho>ever, that there is a bug in Anroi -.Ar2, >here on7eleted() >ill
not be properly %alle. Dou >ill nee to implement on6eceive() an >at%h
$or the 3C<I2=/355WI7G8</78*8<87 a%tion in the re%eive Intent an %all
on7eleted() yoursel$. 5his shoul be $i;e in a $uture eition o$ Anroi.
Controlling 7our #:pp Widget?s& 9estiny
As <witterWidget illustrates, you are not limite to upating your app
>iget only base on the timetable spe%i$ie in your metaata. 5hat
timetable is use$ul i$ you %an get by >ith a $i;e s%heule. )o>ever, there
are %ases in >hi%h that >ill not >ork very >ell*
.$ you >ant the user to be able to %on$igure the polling perio &the
metaata is bake into your A!K an there$ore %annot be moi$ie
at runtime'
.$ you >ant the app >iget to be upate base on e;ternal $a%tors,
su%h as a %hange in lo%ation
5he re%ipe sho>n in <witterWidget >ill let you use 3larm9anager &es%ribe
in a later %hapter' or pro;imity alerts or >hatever to trigger upates. All
you nee to o is*
Arrange $or something to broa%ast an Intent that >ill be pi%ke up
by the ;roadcast6eceiver you are using $or your app >iget provier
)ave the provier pro%ess that Intent ire%tly or pass it along to a
Service &su%h as an IntentService as sho>n in <witterWidget'
Being a 'ood =ost
.n aition to %reating your o>n app >igets, it is possible to host app
>igets. 5his is mostly aime $or those %reating alternative home s%reen
appli%ations, so they %an take avantage o$ the same app >iget $rame>ork
an all the app >igets being built $or it.
5his is not very >ell o%umente at this Lun%ture, but it apparently involves
the 3ppWidgetBost an 3ppWidgetBostView %lasses. 5he latter is a View an so
22
Sho) 1p :t =ome
shoul be able to resie in an app >iget host7s ". like any other orinary
>iget.
23
PART II Advanced Media
CHAPTER 0
Creating 9ra)ables
7rawable resour%es %ome in all shapes an siCes, an not Lust in terms o$
pi;el imensions. While many 7rawable resour%es >ill be !08 or +!B8 $iles,
you %an easily %reate other resour%es that supply other sorts o$ 7rawable
obLe%ts to your appli%ation. .n this %hapter, >e >ill e;amine a $e> o$ these
that may prove use$ul as you try to make your appli%ation look its best.
Traversing :long a 'radient
8raients have long been use to a Isomething a little e;traI to a user
inter$a%e, >hether it is Mi%roso$t aing them to G$$i%e7s title bars in the
late -9907s or the seemingly enless number o$ graient buttons aorning
IWeb 2.0I sites.
An no>, you %an have graients in your Anroi appli%ations as >ell.
5he easiest >ay to %reate a graient is to use an HML $ile to es%ribe the
graient. /y pla%ing the $ile in res/drawable/, it %an be re$eren%e as a
7rawable resour%e, no i$$erent than any other su%h resour%e, like a !08
$ile.
(or e;ample, here is a graient 7rawable resour%e, active/row.xml, $rom the
7rawable/Gradient sample proLe%t*
3-
Creating 9ra)ables
s-ape xmlns,android#$-ttp,//sc-emas.android.com/ap./res/android$
android,s-ape#$rectangle$)
gradient
android,startColor#$RFFKK%%%%$
android,endColor#$RKKKK%%%%$
android,angle#$EG%$
/)
padding
android,top#$Epx$
android,bottom#$Epx$
/)
corners android,radi&s#$Xpx$ /)
/s-ape)
A graient is applie to the more general3purpose s-ape) element, in this
%ase, a re%tangle. 5he graient is e$ine as having a start an en %olor M in
this %ase, the graient is an in%reasing amount o$ re, >ith only the alpha
%hannel varying to %ontrol ho> mu%h the ba%kgroun blens in. 5he %olor
is applie in a ire%tion etermine by the number o$ egrees spe%i$ie by
the android,angle attribute, >ith EG% representing Io>nI &start %olor at the
top, en %olor at the bottom'.
As >ith any other HML3e$ine shape, you %an %ontrol various aspe%ts o$
the >ay the shape is ra>n. .n this %ase, >e put some paing aroun the
ra>able an roun o$$ the %orners o$ the re%tangle.
5o use this 7rawable in +ava %oe, you %an re$eren%e it as
6.drawable.active/row. Gne possible use o$ a graient is in %ustom *istView
ro> sele%tion, as sho>n in 7rawable/Gradient7emo*
pac.age com.commonsware.android.drawable:
import android.content.res.ColorState*ist:
p&blic class Gradient7emo extends *ist3ctivit+ 4
private static ColorState*ist allW-ite#ColorState*ist.value$f(%xKKKKKKKK):
3%
Creating 9ra)ables
$placerat$> $ante$>
$p&r&s$?:

02verride
setList&dapter(new /radient&dapter(t-is)):
getListView().set$nItemSelectedListener(listener):
?

class Gradient3dapter extends 3rra+3dapter 4
/radient&dapter(Context ctxt) 4
s&per(ctxt> 6.la+o&t.row> items):
?

02verride
ViewGro&p parent) 4
GradientWrapper wrapper#n&ll:

convertView#getLayoutInflater().inflate(6.la+o&t.row>
n&ll):
wrapper#new /radient,rapper(convertView):
convertView.set+ag(wrapper):
?
else 4
wrapper#(GradientWrapper)convertView.get+ag():
?

wrapper.getLabel().set+e(t(itemsPpositionQ):

ret&rn(convertView):
?
?

class GradientWrapper 4
View row#n&ll:
<extView label#n&ll:

/radient,rapper(View row) 4
t-is.row#row:
?

<extView getLabel() 4
if (label##n&ll) 4
3.
Creating 9ra)ables
label#(<extView)row.findViewById(6.id.label):
?

ret&rn(label):
?
?

3dapterView.2nItemSelected*istener listener#new
3dapterView.$nItemSelectedListener() 4
View last6ow#n&ll:

View view> int position>
long id) 4
last6ow.setBac)groundColor(%x%%%%%%%%):
?

view.setBac)groundResource(6.drawable.active/row):
last6ow#view:
?

last6ow.setBac)groundColor(%x%%%%%%%%):
last6ow#n&ll:
?
?
?:
?
.n an earlier %hapter, >e sho>e ho> you %an get %ontrol an %ustomiCe
ho> a sele%te ro> appears in a *istView. 5his time, >e apply the graient
roune re%tangle as the ba%kgroun o$ the ro>. We %oul have
a%%omplishe this via appropriate %hoi%es $or android,listSelector an
android,drawSelector2n<op as >ell.
5he result is a sele%tion bar implementing the graient*
3$
Creating 9ra)ables
!igure %6/ The 'radient9emo sample application
0ote that be%ause the list ba%kgroun is bla%k, the re is mi;e >ith bla%k
on the top en o$ the graient. .$ the list ba%kgroun >ere >hite, the top
en o$ the graient >oul be re mi;e >ith >hite, as etermine by the
alpha %hannel spe%i$ie on the graient7s top %olor.
: Stitch +n Time Saves @ine
As you rea through the Anroi o%umentation, you no oubt ran into
re$eren%es to Inine3pat%hI or I93pat%hI an >onere >hat Anroi ha to
o >ith <uilting. Rest assure, you >ill not nee to take up neele>ork to
be an e$$e%tive Anroi eveloper.
.$, ho>ever, you are looking to %reate ba%kgrouns $or resiCable >igets,
like a ;&tton, you >ill probably nee to >ork >ith nine3pat%h images.
As the Anroi o%umentation states, a nine3pat%h is Ia !08 image in
>hi%h you e$ine stret%hable se%tions that Anroi >ill resiCe to $it the
obLe%t at isplay time to a%%ommoate variable siCe se%tions, su%h as te;t
stringsI. /y using a spe%ially3%reate !08 $ile, Anroi %an avoi trying to
30
Creating 9ra)ables
use ve%tor3base $ormats &e.g., #,8' an their asso%iate overhea >hen
trying to %reate a ba%kgroun at runtime. Det, at the same time, Anroi
%an still resiCe the ba%kgroun to hanle >hatever you >ant to put insie o$
it, su%h as the te;t o$ a ;&tton.
.n this se%tion, >e >ill %over some o$ the basi%s o$ nine3pat%h graphi%s,
in%luing ho> to %ustomiCe an apply them to your o>n Anroi layouts.
The 1ame and the Border
0ine3pat%h graphi%s are !08 $iles >hose names en in .T.png. 5his means
they %an be eite using normal graphi%s tools, but Anroi kno>s to apply
nine3pat%h rules to their use.
What makes a nine3pat%h graphi% i$$erent than an orinary !08 is a one3
pi;el3>ie borer surrouning the image. When ra>n, Anroi >ill
remove that borer, sho>ing only the stret%he renition o$ >hat lies
insie the borer. 5he borer is use as a %ontrol %hannel, proviing
instru%tions to Anroi $or ho> to eal >ith stret%hing the image to $it its
%ontents.
Paddin! and the Bo'
Along the right an bottom sies, you %an ra> one3pi;el3>ie bla%k lines
to ini%ate the Ipaing bo;I. Anroi >ill stret%h the image su%h that the
%ontents o$ the >iget >ill $it insie that paing bo;.
(or e;ample, suppose >e are using a nine3pat%h as the ba%kgroun o$ a
;&tton. When you set the te;t to appear in the button &e.g., I)ello, >orl:I',
Anroi >ill %ompute the siCe o$ that te;t, in terms o$ >ith an height in
pi;els. 5hen, it >ill stret%h the nine3pat%h image su%h that the te;t >ill
resie insie the paing bo;. What lies outsie the paing bo; $orms the
borer o$ the button, typi%ally a roune re%tangle o$ some $orm.
32
Creating 9ra)ables
!igure %-/ The padding box* as sho)n by a set of control lines to the right and
bottom of the stretchable image
(tretch 2ones
5o tell Anroi >here on the image to a%tually o the stret%hing, ra> one3
pi;el3>ie bla%k lines on the top an le$t sies o$ the image. Anroi >ill
s%ale the graphi% only in those areas M areas outsie the stret%h Cones are
not stret%he.
!erhaps the most %ommon pattern is the %enter3stret%h, >here the mile
portions o$ the image on both a;es are %onsiere stret%hable, but the
eges are not*
33
Creating 9ra)ables
!igure %%/ The stretch ;ones* as sho)n by a set of control lines to the right and
bottom of the stretchable image
)ere, the stret%h Cones >ill be stret%he Lust enough $or the %ontents to $it
in the paing bo;. 5he eges o$ the graphi% are le$t unstret%he.
#ome aitional rules to bear in min*
.$ you have multiple is%rete stret%h Cones along an a;is &e.g., t>o
Cones separate by >hitespa%e', Anroi >ill stret%h both o$ them
but keep them in their %urrent proportions. #o, i$ the $irst Cone is
t>i%e as >ie as the se%on Cone in the original graphi%, the $irst
Cone >ill be t>i%e as >ie as the se%on Cone in the stret%he
graphi%.
.$ you leave out the %ontrol lines $or the paing bo;, it is assume
that the paing bo; an the stret%h Cones are one an the same.
Toolin!
5o e;periment >ith nine3pat%h images, you may >ish to use the drawTpatc-
program, $oun in the tools/ ire%tory o$ your #@K installation*
34
Creating 9ra)ables
!igure %./ The dra)5patch tool
While a regular graphi%s eitor >oul allo> you to ra> any %olor on any
pi;el, drawTpatc- limits you to ra>ing or erasing pi;els in the %ontrol area.
.$ you attempt to ra> insie the main image area itsel$, you >ill be
blo%ke*
35
Creating 9ra)ables
!igure %$/ The dra)5patch tool* sho)ing blocked areas
Gn the right, you >ill see samples o$ the image in various stret%he siCes, so
you %an see the impa%t as you %hange the stret%hable Cones an paing
bo;.
While this is %onvenient $or >orking >ith the nine3pat%h nature o$ the
image, you >ill still nee some other graphi%s eitor to %reate or moi$y the
boy o$ the image itsel$. (or e;ample, the image sho>n above, $rom the
7rawable/=ine5atc- proLe%t, is a moi$ie version o$ a nine3pat%h graphi%
$rom the #@K7s 3pi7emos, >here the 8.M! >as use to a the neon green
stripe a%ross the bottom portion o$ the image.
%sin! 1ine3Patch $ma!es
0ine3pat%h images are most %ommonly use as ba%kgrouns, as illustrate
by the $ollo>ing layout*
46
Creating 9ra)ables
)
<able*a+o&t
android,stretc-Col&mns#$1$
)
<able6ow
)
<extView
android,la+o&t/gravit+#$center/vertical$
android,text#$BoriIontal,$
/)
See.;ar android,id#$01id/-oriIontal$
/)
/<able6ow)
<able6ow
)
<extView
android,text#$Vertical,$
/)
See.;ar android,id#$01id/vertical$
/)
/<able6ow)
/<able*a+o&t)
*inear*a+o&t
)
;&tton android,id#$01id/resiIe$
android,la+o&t/widt-#$F(px$
android,la+o&t/-eig-t#$F(px$
android,text#$BiN$
android,bac.gro&nd#$0drawable/b&tton$
/)
/*inear*a+o&t)
/*inear*a+o&t)
4-
Creating 9ra)ables
)ere, >e have t>o See.;ar >igets, labele $or the horiContal an verti%al
a;es, plus a ;&tton set up >ith our nine3pat%h graphi% as its ba%kgroun
&android,bac.gro&nd # $0drawable/b&tton$'.
5he =ine5atc-7emo a%tivity then uses the t>o See.;ar >igets to let the user
%ontrol ho> large the button shoul be ra>n on3s%reen, starting $rom an
initial siCe o$ F(px s<uare*
pac.age com.commonsware.android.drawable:
import android.widget.*inear*a+o&t:
import android.widget.See.;ar:
p&blic class =ine5atc-7emo extends 3ctivit+ 4
See.;ar -oriIontal#n&ll:
See.;ar vertical#n&ll:
View t-ing<o6esiIe#n&ll:

02verride

t-ing<o6esiIe#findViewById(6.id.resiIe):

-oriIontal#(See.;ar)findViewById(6.id.-oriIontal):
vertical#(See.;ar)findViewById(6.id.vertical):

-oriIontal.set%a((EGE): // JE% less F( starting siIe
vertical.set%a((EGE): // .eep it s@&are 0 max

-oriIontal.set$nSee)BarC!angeListener(-):
vertical.set$nSee)BarC!angeListener(v):
?

See.;ar.2nSee.;arC-ange*istener -#new See.;ar.$nSee)BarC!angeListener() 4
p&blic void onrogressC!anged(See.;ar see.;ar>
int progress>
boolean from<o&c-) 4
ViewGro&p.*a+o&t5arams old#t-ing<o6esiIe.getLayoutarams():
ViewGro&p.*a+o&t5arams c&rrent#new *inear*a+o&t.Layoutarams(F(1progress>
old.-eig-t):

t-ing<o6esiIe.setLayoutarams(c&rrent):
?

p&blic void onStart+rac)ing+ouc!(See.;ar see.;ar) 4
4%
Creating 9ra)ables
// &n&sed
?

p&blic void onStop+rac)ing+ouc!(See.;ar see.;ar) 4
// &n&sed
?
?:

See.;ar.2nSee.;arC-ange*istener v#new See.;ar.$nSee)BarC!angeListener() 4
p&blic void onrogressC!anged(See.;ar see.;ar>
int progress>
boolean from<o&c-) 4
ViewGro&p.*a+o&t5arams old#t-ing<o6esiIe.getLayoutarams():
ViewGro&p.*a+o&t5arams c&rrent#new *inear*a+o&t.Layoutarams(old.widt->
F(1progress):

t-ing<o6esiIe.setLayoutarams(c&rrent):
?

p&blic void onStart+rac)ing+ouc!(See.;ar see.;ar) 4
// &n&sed
?

p&blic void onStop+rac)ing+ouc!(See.;ar see.;ar) 4
// &n&sed
?
?:
?
5he result is an appli%ation that %an be use mu%h like the right pane o$
drawTpatc-, to see ho> the nine3pat%h graphi% looks on an a%tual evi%e or
emulator in various siCes*
4.
Creating 9ra)ables
!igure %0/ The @inePatch sample proAect* in its initial state
!igure %2/ The @inePatch sample proAect* after making it bigger hori;ontally
4$
Creating 9ra)ables
!igure %3/ The @inePatch sample application* after making it bigger in both
dimensions
40
CHAPTER 4
:nimating Widgets
Anroi is $ull o$ things that move. Dou %an s>ipe le$t an right on the
home s%reen to vie> other panels o$ the esktop. Dou %an rag i%ons aroun
on the home s%reen. Dou %an rag o>n the noti$i%ations area or rag up
the appli%ations ra>er. An that is Lust on one s%reen:
G$ %ourse, it >oul be ni%e to employ su%h animations in your o>n
appli%ation. While this %hapter >ill not %over $ull3$lege rag3an3rop,
>e >ill %over some o$ the basi% animations an ho> to apply them to your
e;isting >igets.
+t?s @ot Bust !or Toons :nymore
Anroi has a pa%kage o$ %lasses &android.view.animation' ei%ate to
animating the movement an behavior o$ >igets.
5hey %enter aroun an 3nimation base %lass that es%ribes >hat is to be
one. /uilt3in animations e;ist to move a >iget &<ranslate3nimation',
%hange the transparen%y o$ a >iget &3lp-a3nimation', revolving a >iget
&6otate3nimation', an resiCing a >iget &Scale3nimation'. 5here is even a
>ay to aggregate animations together into a %omposite 3nimation %alle an
3nimationSet. Later se%tions in this %hapter >ill e;amine the use o$ several
o$ these animations.
8iven that you have an animation, to apply it, you have t>o main options*
43
:nimating Widgets
Dou may be using a %ontainer that supports animating its %ontents,
su%h as a ViewKlipper or <extSwitc-er. 5hese are typi%ally sub%lasses
o$ View3nimator an let you e$ine the IinI an IoutI animations to
apply. (or e;ample, >ith a ViewKlipper, you %an spe%i$y ho> it $lips
bet>een Views in terms o$ >hat animation is use to animate IoutI
the %urrently3visible View an >hat animation is use to animate
IinI the repla%ement View. B;amples o$ this sort o$ animation %an be
$oun in The Busy Coder's Guide to Android Deelopment.
Dou %an simply tell any View to start3nimation(), given the 3nimation
to apply to itsel$. 5his is the te%hni<ue >e >ill be seeing use in the
e;amples in this %hapter.
: Cuirky Translation
Animation takes some getting use to. (re<uently, it takes a $air bit o$
e;perimentation to get it all >orking as you >ish. 5his is parti%ularly true o$
<ranslate3nimation, as not everything about it is intuitive, even to authors
o$ Anroi books.
/echanics o* Translation
5he simple %onstru%tor $or <ranslate3nimation takes $our parameters
es%ribing ho> the >iget shoul move* the be$ore an a$ter H o$$sets $rom
the %urrent position, an the be$ore an a$ter D o$$sets $rom the %urrent
position. 5he Anroi o%umentation re$ers to these as fromW7elta,
toW7elta, fromC7elta, an toC7elta.
.n Anroi7s pi;el3spa%e, an (W>C) %oorinate o$ (%>%) represents the upper3
le$t %orner o$ the s%reen. )en%e, i$ toW7elta is greater than fromW7elta, the
>iget >ill move to the right, i$ toC7elta is greater than fromC7elta, the
>iget >ill move o>n, an so on.
44
:nimating Widgets
$ma!inin! a (lidin! Panel
#ome Anroi appli%ations employ a sliing panel, one that is o$$3s%reen
most o$ the time but %an be %alle up by the user &e.g., via a menu' >hen
esire. When an%hore at the bottom o$ the s%reen, the e$$e%t is akin to
the Anroi menu system, >ith a %ontainer that slies up $rom the bottom
an slies o>n an out >hen being remove. )o>ever, >hile menus are
limite to menu %hoi%es, Anroi7s animation $rame>ork lets one %reate a
sliing panel %ontaining >hatever >igets you might >ant.
Gne >ay to implement su%h a panel is to have a %ontainer &e.g., a
*inear*a+o&t' >hose %ontents are absent &G2=8' >hen the panel is %lose
an is present &VISI;*8' >hen the ra>er is open. .$ >e simply toggle
setVisibilit+() using the a$orementione values, though, the panel >oul
>ink open an %lose immeiately, >ithout any sort o$ animation. #o,
instea, >e >ant to*
Make the panel visible an animate it up $rom the bottom o$ the
s%reen >hen >e open the panel
Animate it o>n to the bottom o$ the s%reen an make the panel
gone >hen >e %lose the panel
The A*termath
5his brings up a key point >ith respe%t to <ranslate3nimation* the
animation temporarily moves the >iget, but i$ you >ant the >iget to stay
>here it is >hen the animation is over, you have to hanle that yoursel$.
Gther>ise, the >iget >ill snap ba%k to its original position >hen the
animation %ompletes.
.n the %ase o$ the panel opening, >e hanle that via the transition $rom G2=8
to VISI;*8. 5e%hni%ally speaking, the panel is al>ays IopenI, in that >e are
not, in the en, %hanging its position. /ut >hen the boy o$ the panel is
G2=8, it takes up no spa%e on the s%reenO >hen >e make it VISI;*8, it takes
up >hatever spa%e it is suppose to.
45
:nimating Widgets
Later in this %hapter, >e >ill %over ho> to use animation listeners to
a%%omplish this en $or %losing the panel.
$ntroducin! (lidin!Panel
With all that sai, turn your attention to the 3nimation/Sliding5anel proLe%t
an, in parti%ular, the Sliding5anel %lass.
5his %lass implements a layout that >orks as a panel, an%hore to the
bottom o$ the s%reen. A toggle() metho %an be %alle by the a%tivity to
hie or sho> the panel. 5he panel itsel$ is a *inear*a+o&t, so you %an put
>hatever %ontents you >ant in there.
We use t>o $lavors o$ <ranslate3nimation, one $or opening the panel an
one $or %losing it.
)ere is the opening animation*
anim#new +ranslate&nimation(%.%f> %.%f>
getLayoutarams().-eig-t>
%.%f):
Gur fromW7elta an toW7elta are both %, sin%e >e are not shi$ting the panel7s
position along the horiContal a;is. Gur fromC7elta is the panel7s height
a%%oring to its layout parameters &representing ho> big >e >ant the panel
to be', be%ause >e >ant the panel to start the animation at the bottom o$
the s%reenO our toC7elta is % be%ause >e >ant the panel to be at its InaturalI
open position at the en o$ the animation.
Conversely, here is the %losing animation*
anim#new +ranslate&nimation(%.%f> %.%f> %.%f>
getLayoutarams().-eig-t):
.t has the same basi% stru%ture, e;%ept the D values are reverse, sin%e >e
>ant the panel to start open an animate to a %lose position.
56
:nimating Widgets
5he result is a %ontainer that %an be %lose*
!igure %4/ The SlidingPanel sample application* )ith the panel closed
...or open, in this %ase toggle via a menu %hoi%e in the Sliding5anel7emo
a%tivity*
5-
:nimating Widgets
!igure %5/ The SlidingPanel sample application* )ith the panel open
%sin! the Animation
When setting up an animation, you also nee to ini%ate ho> long the
animation shoul take. 5his is one by %alling set7&ration() on the
animation, proviing the esire length o$ time in millise%ons.
When >e are reay >ith the animation, >e simply %all start3nimation() on
the Sliding5anel itsel$, %ausing it to move as spe%i$ie by the
<ranslate3nimation instan%e.
!ading To Black/ ,r Some ,ther Color/
3lp-a3nimation allo>s you to $ae a >iget in or out by making it less or
more transparent. 5he greater the transparen%y, the more the >iget
appears to be I$aingI.
5%
:nimating Widgets
Alpha 1um#ers
Dou may be use to alpha %hannels, >hen use in R3366GG;; %olor notation,
or perhaps >hen >orking >ith alpha3%apable image $ormats like !08.
#imilarly, 3lp-a3nimation allo>s you to %hange the alpha %hannel $or an
entire >iget, $rom $ully3soli to $ully3transparent.
.n Anroi, a $loat value o$ 1.% ini%ates a $ully3soli >iget, >hile a value
o$ %.% ini%ates a $ully3transparent >iget. ,alues in bet>een, o$ %ourse,
represent various amounts o$ transparen%y.
)en%e, it is %ommon $or an 3lp-a3nimation to either start at 1.% an
smoothly %hange the alpha to %.% &a $ae' or vi%e versa.
Animations in 5/"
With <ranslate3nimation, >e sho>e ho> to %onstru%t the animation in
+ava sour%e %oe. Gne %an also %reate animation resour%es, >hi%h e$ine the
animations using HML. 5his is similar to the pro%ess $or e$ining layouts,
albeit mu%h simpler.
(or e;ample, there is a se%on animation proLe%t, 3nimation/Sliding5anel8x,
>hi%h emonstrates a panel that $aes out as it is %lose. .n there, you >ill
$in a res/anim/ ire%tory, >hi%h is >here animation resour%es shoul
resie. .n there, you >ill $in fade.xml*
alp-a xmlns,android#$-ttp,//sc-emas.android.com/ap./res/android$
android,from3lp-a#$1.%$
android,to3lp-a#$%.%$ /)
5he name o$ the root element ini%ates the type o$ animation &in this %ase,
alpha $or an 3lp-a3nimation'. 5he attributes spe%i$y the %hara%teristi%s o$
the animation, in this %ase a $ae $rom 1.% to %.% on the alpha %hannel.
5his HML is the same as %alling new 3lp-a3nimation(1.%f>%.%f) in +ava.
5.
:nimating Widgets
%sin! 5/" Animations
5o make use o$ HML3e$ine animations, you nee to in$late them, mu%h as
you might in$late a View or 9en& resour%e. 5his is a%%omplishe by using the
load3nimation() stati% metho on the 3nimationDtils %lass*
fade2&t#3nimationDtils.load&nimation(ctxt> 6.anim.fade):
)ere, >e are loaing our $ae animation, given a Context. 5his is being put
into an 3nimation variable, so >e neither kno> nor %are that this parti%ular
HML that >e are loaing e$ines an 3lp-a3nimation instea o$, say, a
6otate3nimation.
When +t?s :ll Said :nd 9one
#ometimes, you nee to take a%tion >hen an animation %ompletes.
(or e;ample, >hen >e %lose the panel, >e >ant to use a
<ranslation3nimation to slie it o>n $rom the open position to
%lose...then keep it %lose. With the system use in Sliding5anel, keeping
the panel %lose is a matter o$ %alling setVisibilit+() on the %ontents >ith
G2=8.
)o>ever, you %annot o that >hen the animation beginsO other>ise, the
panel is gone by the time you try to animate its motion.
.nstea, you nee to arrange to have it be gone >hen the animation ens.
5o o that, you use a animation listener.
An animation listener is simply an instan%e o$ the 3nimation*istener
inter$a%e, provie to an animation via set3nimation*istener(). 5he listener
>ill be invoke >hen the starts, ens, or repeats &the latter %ourtesy o$
C+cleInterpolator, is%usse later in this %hapter'. Dou %an put logi% in the
on3nimation8nd() %allba%k in the listener to take a%tion >hen the animation
$inishes.
5$
:nimating Widgets
(or e;ample, here is the 3nimation*istener $or Sliding5anel*
3nimation.3nimation*istener collapse*istener#new 3nimation.&nimationListener() 4
p&blic void on&nimationEnd(3nimation animation) 4
setVisibility(View.G2=8):
?
p&blic void on&nimationRepeat(3nimation animation) 4
// not needed
?
p&blic void on&nimationStart(3nimation animation) 4
// not needed
?
?:
All >e o is set the Image;&tton7s image to be the up>ar3pointing arro>
an setting our %ontent7s visibility to be G2=8, thereby %losing the panel.
=it The :ccelerator
.n aition to the 3nimation %lasses themselves, Anroi also provies a set
o$ Interpolator %lasses. 5hese provie instru%tions $or ho> an animation is
suppose to behave uring its operating perio.
(or e;ample, the 3ccelerateInterpolator ini%ates that, uring the uration
o$ an animation, the rate o$ %hange o$ the animation shoul begin slo>ly
an a%%elerate until the en. When applie to a <ranslate3nimation, $or
e;ample, the sliing movement >ill start out slo>ly an pi%k up spee until
the movement is %omplete.
5here are several implementations o$ the .nterpolator inter$a%e besies
3ccelerateInterpolator, in%luing*
3ccelerate7ecelerateInterpolator, >hi%h starts slo>ly, pi%ks up
spee in the mile, an slo>s o>n again at the en
7ecelerateInterpolator, >hi%h starts <ui%kly an slo>s o>n
to>ars the en
*inearInterpolator, the e$ault, >hi%h ini%ates the animation
shoul pro%ee smoothly $rom start to $inish
50
:nimating Widgets
C+cleInterpolator, >hi%h repeats an animation $or a number o$
%y%les, $ollo>ing the A%%elerate@e%elerate.nterpolator pattern
&slo>, then $ast, then slo>'
5o apply an interpolator to an animation, simply %all setInterpolator() on
the animation >ith the Interpolator instan%e, su%h as the $ollo>ing line
$rom Sliding5anel*
anim.setInterpolator(new &ccelerateInterpolator(1.%f)):
Dou %an also spe%i$y one o$ the sto%k interpolators via the
android,interpolator attribute in your animation HML $ile.
:nimate/ Set/ 8atch/
(or the 3nimation/Sliding5anel8x proLe%t, though, >e >ant the panel to
slie open, but also $ae >hen it slies %lose. 5his implies t>o animations
>orking at the same time &a $ae an a slie'. Anroi supports this via the
3nimationSet %lass.
An 3nimationSet is itsel$ an 3nimation implementation. (ollo>ing the
%omposite esign pattern, it simply %as%aes the maLor 3nimation events to
ea%h o$ the animations in the set.
5o %reate a set, Lust %reate an 3nimationSet instan%e, a the animations,
an %on$igure the set. (or e;ample, here is the logi% $rom the Sliding5anel
implementation in 3nimation/Sliding5anel8x*
p&blic void toggle() 4
<ranslate3nimation anim#n&ll:
3nimationSet set#new &nimationSet(tr&e):
is2pen#Nis2pen:
if (is2pen) 4
setVisibility(View.VISI;*8):
anim#new +ranslate&nimation(%.%f> %.%f>
getLayoutarams().-eig-t>
%.%f):
?
52
:nimating Widgets
else 4
anim#new +ranslate&nimation(%.%f> %.%f> %.%f>
getLayoutarams().-eig-t):
anim.set&nimationListener(collapse*istener):
set.add&nimation(fade2&t):
?
set.add&nimation(anim):
set.set"uration(speed):
set.setInterpolator(new &ccelerateInterpolator(1.%f)):
start&nimation(set):
?
.$ the panel is to be opene, >e make the %ontents visible &so >e %an
animate the motion up>ars', an %reate a <ranslate3nimation $or the
up>ar movement. .$ the panel is to be %lose, >e %reate a
<ranslate3nimation $or the o>n>ar movement, but also a a pre3e$ine
3lp-a3nimation &fade2&t' to an 3nimationSet. .n either %ase, >e a the
<ranslate3nimation to the set, give the set a uration an interpolator, an
run the animation.
53
CHAPTER 6
Playing 8edia
!retty mu%h every phone %laiming to be a IsmartphoneI has the ability to at
least play ba%k musi%, i$ not vieo. Bven many more orinary phones are
$ull3$lege M!? players, in aition to o$$ering ringtones an >hatnot.
0ot surprisingly, Anroi has multimeia support $or you, as a eveloper,
to buil your o>n games, meia players, an so on.
5his %hapter is $o%use on auio an vieo playba%kO other %hapters >ill
ta%kle meia input, in%luing the %amera an auio re%oring.
'et 7our 8edia ,n
.n Anroi, you have $ive i$$erent pla%es you %an pull meia %lips $rom M
one o$ these >ill hope$ully $it your nees*
-. Dou %an pa%kage meia %lips as ra> resour%es &res/raw in your
proLe%t', so they are bunle >ith your appli%ation. 5he bene$it is
that you7re guarantee the %lips >ill be thereO the o>nsie is that
they %annot be repla%e >ithout upgraing the appli%ation.
2. Dou %an pa%kage meia %lips as assets &assets/ in your proLe%t' an
re$eren%e them via file,///android/asset/ "RLs in a Dri. 5he
bene$it over ra> resour%es is that this lo%ation >orks >ith A!.s that
e;pe%t Dri parameters instea o$ resour%e .@s. 5he o>nsie M
55
Playing 8edia
assets are only repla%eable >hen the appli%ation is upgrae M
remains.
?. Dou %an store meia in an appli%ation3lo%al ire%tory, su%h as
%ontent you o>nloa o$$ the .nternet. Dour meia may or may not
be there, an your storage spa%e isn7t in$inite, but you %an repla%e
the meia as neee.
=. Dou %an store meia M or re$eren%e meia that the user has store
hersel$ M that is on an #@ %ar. 5here is likely more storage spa%e on
the %ar than there is on the evi%e, an you %an repla%e the meia
as neee, but other appli%ations have a%%ess to the #@ %ar as >ell.
A. Dou %an, in some %ases, stream meia o$$ the .nternet, bypassing
any lo%al storage, as >ith the #tream(urious appli%ation
.nternet streaming is tri%ky, parti%ularly $or vieo, an is >ell beyon the
s%ope o$ this book. (or the 53Mobile 8-, the re%ommene approa%h $or
anything o$ signi$i%ant siCe is to put it on the #@ %ar, as there is very little
on3boar $lash memory $or $ile storage.
8aking @oise
5he %ru; o$ playing ba%k auio %omes in the $orm o$ the 9edia5la+er %lass.
With it, you %an $ee it an auio %lip, startQstopQpause playba%k, an get
noti$ie on key events, su%h as >hen the %lip is reay to be playe or is
one playing.
Dou have three >ays to set up a 9edia5la+er an tell it >hat auio %lip to
play*
-. .$ the %lip is a ra> resour%e, use 9edia5la+er.create() an provie
the resour%e .@ o$ the %lip
2. .$ you have a Dri to the %lip, use the Dri3$lavore version o$
9edia5la+er.create()
?. .$ you have a string path to the %lip, Lust %reate a 9edia5la+er using
the e$ault %onstru%tor, then %all set7ataSo&rce() >ith the path to
the %lip
-66
Playing 8edia
0e;t, you nee to %all prepare() or prepare3s+nc(). /oth >ill set up the %lip
to be reay to play, su%h as $et%hing the $irst $e> se%ons o$$ the $ile or
stream. 5he prepare() metho is syn%hronousO as soon as it returns, the %lip
is reay to play. 5he prepare3s+nc() metho is asyn%hronous M more on
ho> to use this version later.
Gn%e the %lip is prepare, start() begins playba%k, pa&se() pauses playba%k
&>ith start() pi%king up playba%k >here pa&se() pause', an stop() ens
playba%k. Gne %aveat* you %annot simply %all start() again on the
9edia5la+er on%e you have %alle stop() M >e7ll %over a >orkaroun a bit
later in this se%tion.
5o see this in a%tion, take a look at the 9edia/3&dio sample proLe%t. 5he
layout is pretty trivial, >ith three buttons an labels $or play, pause, an
stop*
)
*inear*a+o&t
android,padding#$Fpx$
)
Image;&tton android,id#$01id/pla+$
android,src#$0drawable/pla+$
android,padding6ig-t#$Fpx$
android,enabled#$false$
/)
<extView
android,text#$5la+$
android,gravit+#$center/vertical$
android,text3ppearance#$!android,attr/text3ppearance*arge$
/)
/*inear*a+o&t)
*inear*a+o&t
-6-
Playing 8edia
)
Image;&tton android,id#$01id/pa&se$
android,src#$0drawable/pa&se$
/)
<extView
android,text#$5a&se$
/)
/*inear*a+o&t)
*inear*a+o&t
)
Image;&tton android,id#$01id/stop$
android,src#$0drawable/stop$
/)
<extView
android,text#$Stop$
/)
/*inear*a+o&t)
/*inear*a+o&t)
5he +ava, o$ %ourse, is >here things get interesting*
p&blic class 3&dio7emo extends 3ctivit+
implements 9edia5la+er.2nCompletion*istener 4

private Image;&tton pla+:
private Image;&tton pa&se:
private Image;&tton stop:
private 9edia5la+er mp:
02verride
-6%
Playing 8edia

pla+#(Image;&tton)findViewById(6.id.pla+):
pa&se#(Image;&tton)findViewById(6.id.pa&se):
stop#(Image;&tton)findViewById(6.id.stop):

pla+.set$nClic)Listener(new View.$nClic)Listener() 4
p&blic void onClic)(View view) 4
play():
?
?):

pa&se.set$nClic)Listener(new View.$nClic)Listener() 4
pause():
?
?):

stop.set$nClic)Listener(new View.$nClic)Listener() 4
stop():
?
?):

setup():
?

02verride
s&per.on"estroy():

if (stop.isEnabled()) 4
stop():
?
?

p&blic void onCompletion(9edia5la+er mp) 4
stop():
?

private void play() 4
mp.start():

pla+.setEnabled(false):
pa&se.setEnabled(tr&e):
stop.setEnabled(tr&e):
?

private void stop() 4
mp.stop():
mp.release():
setup():
?
-6.
Playing 8edia

private void pause() 4
mp.pause():

pla+.setEnabled(tr&e):
pa&se.setEnabled(false):
stop.setEnabled(tr&e):
?

private void loadClip() 4
tr+ 4
mp#9edia5la+er.create(t-is> 6.raw.clip):
mp.set$nCompletionListener(t-is):
?
catc- (<-rowable t) 4
goBlooey(t):
?
?

private void setup() 4
loadClip():
pla+.setEnabled(tr&e):
pa&se.setEnabled(false):
stop.setEnabled(false):
?

private void goBlooey(<-rowable t) 4
3lert7ialog.;&ilder b&ilder#new 3lert7ialog.Builder(t-is):

b&ilder
.set+itle($8xceptionN$)
.set%essage(t.toString())
.setositiveButton($2V$> n&ll)
.s!ow():
?
?
.n onCreate(), >e >ire up the three buttons to appropriate %allba%ks, then
%all set&p(). .n set&p(), >e %reate our 9edia5la+er, set to play a %lip >e
pa%kage in the proLe%t as a ra> resour%e. We also %on$igure the a%tivity
itsel$ as the %ompletion listener, so >e $in out >hen the %lip is over. 0ote
that, sin%e >e use the stati% create() metho on 9edia5la+er, >e have
alreay impli%itly %alle prepare(), so >e o not nee to %all that separately
ourselves.
5he buttons simply >ork the 9edia5la+er an toggle ea%h others7 states, via
appropriately3name %allba%ks. #o, pla+() starts Meia!layer playba%k,
pa&se() pauses playba%k, an stop() stops playba%k an resets our
-6$
Playing 8edia
9edia5la+er to play again. 5he stop() %allba%k is also use $or >hen the
auio %lip %ompletes o$ its o>n a%%or.
5o reset the Meia!layer, the stop() %allba%k %alls release() on the e;isting
9edia5la+er &to release its resour%es', then %alls set&p() again, is%aring
the use 9edia5la+er an starting a $resh one.
5he ". is nothing spe%ial, but >e are more intereste in the auio in this
sample, any>ay*
!igure .6/ The :udio9emo sample application
8oving Pictures
,ieo %lips get their o>n >iget, the VideoView. !ut it in a layout, $ee it an
M!= vieo %lip, an you get playba%k:
(or e;ample, take a look at this layout, $rom the 9edia/Video sample proLe%t*
-60
Playing 8edia
)
VideoView
android,id#$01id/video$
/)
/*inear*a+o&t)
5he layout is simply a $ull3s%reen vieo player. Whether it >ill use the $ull
s%reen >ill be epenent on the vieo %lip, its aspe%t ratio, an >hether you
have the evi%e &or emulator' in portrait or lans%ape moe.
Wiring up the +ava is almost as simple*
p&blic class Video7emo extends 3ctivit+ 4
private VideoView video:
private 9ediaController ctlr:

02verride
get,indow().set'ormat(5ixelKormat.<63=S*DC8=<):

Kile clip#new 'ile($/sdcard/test.mpF$):

if (clip.e(ists()) 4
video#(VideoView)findViewById(6.id.video):
video.setVideoat!(clip.get&bsoluteat!()):

ctlr#new %ediaController(t-is):
ctlr.set%edialayer(video):
video.set%ediaController(ctlr):
video.request'ocus():
?
?
?
5he biggest tri%k >ith VideoView is getting a vieo %lip onto the evi%e.
While VideoView oes support some streaming vieo, the re<uirements on
the M!= $ile are $airly stringent. .$ you >ant to be able to play a >ier array
o$ vieo %lips, you nee to have them on the evi%e, pre$erably on an #@
%ar.
-62
Playing 8edia
5he %rue Video7emo %lass assumes there is an M!= $ile in /sdcard/test.mpF
on your emulator. 5o make this a reality*
-. (in a %lip, su%h as Aaron Rosenberg7s Documentaries and #ou $rom
@uke "niversity7s Center $or the #tuy o$ the !ubli% @omain7s
Moving .mage Contest, >hi%h >as use in the %reation o$ this book
2. "se m.sdcard &in the Anroi #@K7s tools ire%tory' to %reate a
suitably3siCe #@ %ar image &e.g., m.sdcard 1E(9 sd.img'
?. "se the 'sdcard s>it%h >hen laun%hing the emulator, proviing the
path to your #@ %ar image, so the #@ %ar is ImounteI >hen the
emulator starts
=. "se the adb p&s- %omman &or @@M# or the e<uivalent in your
.@B' to %opy the M!= $ile into /sdcard/test.mpF
Gn%e there, the +ava %oe sho>n above >ill give you a >orking vieo player*
!igure .-/ The (ideo9emo sample application* sho)ing a Creative Commons"
licensed video clip
5apping on the vieo >ill pop up the playba%k %ontrols*
-63
Playing 8edia
!igure .%/ The (ideo9emo sample application* )ith the media controls
displayed
5he vieo >ill s%ale base on spa%e, as sho>n in this rotate vie> o$ the
emulator &Ctrl)'K1E)'*
!igure ../ The (ideo9emo sample application* in landscape mode* )ith the
video clip scaled to fit
0ote that playba%k may be rather Lerky in the emulator, epening on the
po>er o$ the !C that is hosting the emulator. (or e;ample, on a !entium3M
-64
Playing 8edia
-.48)C !C, playba%k in the emulator is e;tremely Lerky, >hile playba%k on
the 53Mobile 8- is very smooth.
-65
CHAPTER 7
1sing the Camera
Most Anroi evi%es >ill have a %amera, sin%e they are $airly
%ommonpla%e on mobile evi%es these ays. Dou, as an Anroi eveloper,
%an take avantage o$ the %amera, $or everything $rom snapping tourist
photos to s%anning bar%oes. (or simple operations, the A!.s neee to use
the %amera are $airly straight3$or>ar, re<uiring a bit o$ boilerplate %oe
plus your o>n uni<ue appli%ation logi%.
What is a problem is using the %amera >ith the emulator. 5he emulator
oes not emulate a %amera, nor is there a %onvenient >ay to preten there
are pi%tures via @@M# or similar tools. (or the purposes o$ this %hapter, it is
assume you have a%%ess to an a%tual Anroi3po>ere har>are evi%e
an %an use it $or evelopment purposes.
Sneaking a Peek
(irst, it is $airly %ommon $or a %amera3using appli%ation to support a
previe> moe, to sho> the user >hat the %amera sees. 5his >ill help make
sure the %amera is line up on the subLe%t properly, >hether there is
su$$i%ient lighting, et%.
#o, let us take a look at ho> to %reate an appli%ation that sho>s su%h a live
previe>. 5he %oe snippets sho>n in this se%tion are pulle $rom the
Camera/5review sample proLe%t.
---
1sing the Camera
The Permission
(irst, you nee permission to use the %amera. 5hat >ay, >hen en users
install your appli%ation o$$ o$ the .nternet, they >ill be noti$ie that you
inten to use the %amera, so they %an etermine i$ they eem that
appropriate $or your appli%ation.
Dou simply nee the C39863 permission in your 3ndroid9anifest.xml $ile,
along >ith >hatever other permissions your appli%ation logi% might
re<uire. )ere is the mani$est $rom the Camera/5review sample proLe%t*
pac.age#$com.commonsware.android.camera$
&ses'permission android,name#$android.permission.C39863$ /)
activit+ android,name#$.5review7emo$
android,label#$0string/app/name$
android,configC-anges#$.e+boardBiddenYorientation$
android,screen2rientation#$landscape$
android,t-eme#$0android,st+le/<-eme.=o<itle;ar.K&llscreen$)
intent'filter)
/intent'filter)
/activit+)
/application)
/manifest)
Also note a $e> other things about our 5review7emo a%tivity as registere in
this mani$est*
We use android,configC-anges # $.e+boardBiddenYorientation$ to
ensure >e %ontrol >hat happens >hen the keyboar is hien or
e;pose, rather than have Anroi rotate the s%reen $or us
We use android,screen2rientation # $landscape$ to tell Anroi >e
are al>ays in lans%ape moe. 5his is ne%essary be%ause o$ a bit o$ a
bug in the %amera previe> logi%, su%h that it >orks best in
lans%ape moe.
--%
1sing the Camera
We use android,t-eme # $0android,st+le/K&llscreen$ to get ri o$
the title bar an status bar, so the previe> is truly $ull3s%reen &e.g.,
=20;?20 on a 53Mobile 8-'.
The (ur*ace,ie+
0e;t, you nee a layout supporting a S&rfaceView. S&rfaceView is use as a
ra> %anvas $or isplaying all sorts o$ graphi%s outsie o$ the realm o$ your
orinary >igets. .n this %ase, Anroi kno>s ho> to isplay a live look at
>hat the %amera sees on a S&rfaceView, to serve as a previe> pane.
(or e;ample, here is a $ull3s%reen S&rfaceView layout as use by the
5review7emo a%tivity*
android.view.S&rfaceView
android,id#$01id/preview$
)
/android.view.S&rfaceView)
The Camera
5he biggest step, o$ %ourse, is telling Anroi to use the %amera servi%e an
tie a %amera to the S&rfaceView to sho> the a%tual previe>. We >ill also
eventually nee the %amera servi%e to take real pi%tures, as >ill be
es%ribe in the ne;t se%tion.
5here are three maLor %omponents to getting pi%ture previe> >orking*
-. 5he S&rfaceView, as e$ine in our layout
2. A S&rfaceBolder, >hi%h is a means o$ %ontrolling behavior o$ the
S&rfaceView, su%h as its siCe, or being noti$ie >hen the sur$a%e
%hanges, su%h as >hen the previe> is starte
?. A Camera, obtaine $rom the open() stati% metho on the Camera %lass
--.
1sing the Camera
5o >ire these together, >e $irst nee to*
8et the S&rfaceBolder $or our S&rfaceView via getBolder()
Register a S&rfaceBolder.Callbac. >ith the S&rfaceBolder, so >e are
noti$ie >hen the S&rfaceView is reay or %hanges
5ell the S&rfaceView &via the S&rfaceBolder' that it has the
SD6K3C8/<C58/5DSB/;DKK86S type &set<+pe()' M this ini%ates
something in the system >ill be upating the S&rfaceView an
proviing the bitmap ata to isplay
5his gives us a %on$igure S&rfaceView &sho>n belo>', but >e still nee to
tie in the Camera.
02verride
preview#(S&rfaceView)findViewById(6.id.preview):
previewBolder#preview.get*older():
previewBolder.addCallbac)(s&rfaceCallbac.):
previewBolder.set+ype(S&rfaceBolder.SD6K3C8/<C58/5DSB/;DKK86S):
?
A Camera obLe%t has a set5review7ispla+() metho that takes a S&rfaceBolder
an, as you might e;pe%t, arranges $or the %amera previe> to be isplaye
on the asso%iate S&rfaceView. )o>ever, the S&rfaceView may not be reay
immeiately a$ter being %hange into SD6K3C8/<C58/5DSB/;DKK86S moe. #o,
>hile the previous setup >ork %oul be one in onCreate(), you shoul >ait
until the S&rfaceBolder.Callbac. has its s&rfaceCreated() metho %alle,
then register the Camera*
p&blic void surfaceCreated(S&rfaceBolder -older) 4
camera#Camera.open():
tr+ 4
camera.setreview"isplay(previewBolder):
?
*og.e($5review7emo's&rfaceCallbac.$>
$8xception in set5review7ispla+()$> t):
<oast
.ma)e+e(t(5review7emo.t-is> t.get%essage()> <oast.*8=G<B/*2=G)
.s!ow():
--$
1sing the Camera
?
?
0e;t, on%e the S&rfaceView is set up an siCe by Anroi, >e nee to pass
%on$iguration ata to the Camera, so it kno>s ho> big to ra> the previe>.
#in%e the previe> pane is not a $i;e siCe M it might vary base on har>are
M >e %annot sa$ely pre3etermine the siCe. .t is simplest to >ait $or our
S&rfaceBolder.Callbac. to have its s&rfaceC-anged() metho %alle, >hen
>e are tol the siCe o$ the sur$a%e. 5hen, >e %an pour that in$ormation into
a Camera.5arameters obLe%t, upate the Camera >ith those parameters, an
have the Camera sho> the previe> images via start5review()*
p&blic void surfaceC!anged(S&rfaceBolder -older>
int format> int widt->
int -eig-t) 4
Camera.5arameters parameters#camera.getarameters():
parameters.setreviewSi.e(widt-> -eig-t):
camera.setarameters(parameters):
camera.startreview():
?
Bventually, the previe> nees to stop. .n this parti%ular %ase, that >ill be as
the a%tivity is being estroye. .t is important to release the Camera at this
time M $or many evi%es, there is only one physi%al %amera, so only one
a%tivity %an be using it at a time. Gur S&rfaceBolder.Callbac. >ill be tol,
via s&rface7estro+ed(), >hen it is being %lose up, an >e %an stop the
previe> &stop5review()', release the %amera &release()', an let go o$ it
&camera # n&ll' at that point*
p&blic void surface"estroyed(S&rfaceBolder -older) 4
camera.stopreview():
camera.release():
camera#n&ll:
?
.$ you %ompile an run the Camera/5review sample appli%ation, you >ill see,
on3s%reen, >hat the %amera sees.
)ere is the $ull S&rfaceBolder.Callbac. implementation*
--0
1sing the Camera
S&rfaceBolder.Callbac. s&rfaceCallbac.#new S&rfaceBolder.Callbac)() 4
p&blic void surfaceCreated(S&rfaceBolder -older) 4
camera#Camera.open():
tr+ 4
camera.setreview"isplay(previewBolder):
?
*og.e($5review7emo's&rfaceCallbac.$>
$8xception in set5review7ispla+()$> t):
<oast
.ma)e+e(t(5review7emo.t-is> t.get%essage()> <oast.*8=G<B/*2=G)
.s!ow():
?
?
int -eig-t) 4
?
p&blic void surface"estroyed(S&rfaceBolder -older) 4
camera.release():
camera#n&ll:
?
?:
+mage +s <verything
#ho>ing the previe> imagery is ni%e an all, but it is probably more
important to a%tually take a pi%ture no> an again. 5he previe>s sho> the
user >hat the %amera sees, but >e still nee to let our appli%ation kno>
>hat the %amera sees at parti%ular points in time.
.n prin%iple, this is easy. Where things get a bit %ompli%ate %omes >ith
ensuring the appli%ation &an evi%e as a >hole' has e%ent per$orman%e,
not slo>ing o>n to pro%ess the pi%tures.
--2
1sing the Camera
5he %oe snippets sho>n in this se%tion are pulle $rom the Camera/5ict&re
sample proLe%t, >hi%h buils upon the Camera/5review sample sho>n in the
previous se%tion.
As&in! *or a 8ormat
We nee to tell the Camera >hat sort o$ pi%ture to take >hen >e e%ie to
take a pi%ture. 5he t>o options are ra> an +!B8.
At least, that is the theory.
.n pra%ti%e, the 53Mobile 8- oes not support ra> output, only +!B8. #o, >e
nee to tell the Camera that >e >ant +!B8 output.
5hat is merely a matter o$ %alling set5ict&reKormat() on the
Camera.5arameters obLe%t >hen >e %on$igure our Camera, using the value J58G
to ini%ate that >e, inee, >ant +!B8*
int -eig-t) 4
parameters.seticture'ormat(5ixelKormat.J58G):
?
Connectin! the Camera Button
#omeho>, your appli%ation >ill nee to ini%ate >hen a pi%ture shoul be
taken. 5hat %oul be via >igets on the "., though in our samples here, the
previe> is $ull3s%reen.
An alternative is to use the %amera har>are button. Like every har>are
button other than the )ome button, >e %an $in out >hen the %amera
button is %li%ke via onVe+7own()*
--3
1sing the Camera
02verride
p&blic boolean on#ey"own(int .e+Code> Ve+8vent event) 4
if (.e+Code##Ve+8vent.V8CC278/C39863 YY
.e+Code##Ve+8vent.V8CC278/S836CB) 4
ta)eicture():
ret&rn(tr&e):
?
ret&rn(s&per.on#ey"own(.e+Code> event)):
?
#in%e the )5C Magi% oes not have a har>are %amera button, >e also
>at%h $or V8CC278/S836CB $or the ei%ate sear%h key, >hi%h is in the
upper3right portion o$ the Magi%7s $a%e >hen the evi%e is hel in lans%ape
moe.
Ta&in! a Picture
Gn%e it is time to take a pi%ture, all you nee to o is*
#top the previe>
5ell the Camera to ta.e5ict&re()
5he ta.e5ict&re() metho takes three parameters, all %allba%k3style obLe%ts*
-. A IshutterI %allba%k &Camera.S-&tterCallbac.', >hi%h is noti$ie
>hen the pi%ture has been %apture by the har>are but the ata is
not yet available M you might use this to play a I%amera %li%kI soun
2. Callba%ks to re%eive the image ata, either in ra> $ormat or +!B8
$ormat
#in%e the 53Mobile 8- only supports +!B8 output, an be%ause >e o not
>ant to $uss >ith a shutter %li%k, 5ict&re7emo only passes in the thir
parameter to ta.e5ict&re()*
private void ta)eicture() 4
camera.ta)eicture(n&ll> n&ll> p-otoCallbac.):
?
--4
1sing the Camera
5he Camera.5ict&reCallbac. &p-otoCallbac.' nees to implement
on5ict&re<a.en(), >hi%h provies the pi%ture ata as a b+tePQ, plus the
Camera obLe%t that took the pi%ture. At this point, it is sa$e to start up the
previe> again.
!lus, o$ %ourse, it >oul be ni%e to o something >ith that byte array.
5he %at%h is that the byte array is going to be large M the 53Mobile 8- has a
?3megapi;el %amera, an $uture har>are is more likely to have ri%her
har>are than that. Writing that to $lash, or sening it over the net>ork, or
oing Lust about anything >ith the ata, >ill be slo>. #lo> is $ine...so long
as it is not on the ". threa.
5hat means >e nee to o a little more >ork.
%sin! AsyncTas&
.n theory, >e %oul Lust $ork a ba%kgroun threa to save o$$ the image ata
or o >hatever it is >e >ante one >ith it. )o>ever, >e %oul >in up
>ith several su%h threas, parti%ularly i$ >e are sening the image over the
.nternet an o not have a $ast %onne%tion to our estination server.
Anroi -.A o$$ers a >ork <ueue moel, in the $orm o$ 3s+nc<as.. 3s+nc<as.
manages a threa pool an >ork <ueue M all >e nee to o is han it the
>ork to be one.
#o, >e %an %reate an 3s+nc<as. implementation, %alle Save5-oto<as., as
$ollo>s*
class Save5-oto<as. extends 3s+nc<as.b+tePQ> String> String) 4
02verride
protected String doInBac)ground(b+tePQ... Apeg) 4
Kile p-oto#new 'ile(8nvironment.getE(ternalStorage"irectory()>
$p-oto.Apg$):
if (p-oto.e(ists()) 4
p-oto.delete():
?
--5
1sing the Camera
tr+ 4
Kile2&tp&tStream fos#new 'ile$utputStream(p-oto.getat!()):
fos.write(ApegP%Q):
fos.close():
?
catc- (Aava.io.I28xception e) 4
*og.e($5ict&re7emo$> $8xception in p-otoCallbac.$> e):
?
ret&rn(n&ll):
?
?
Gur doIn;ac.gro&nd() implementation gets the byte array >e re%eive $rom
Anroi. 5he byte array is simply the +!B8 itsel$, so the ata %oul be
>ritten to a $ile, trans$orme, sent to a Web servi%e, %onverte into a
;itmap7rawable $or isplay on the s%reen or >hatever.
.n the %ase o$ 5ict&re7emo, >e take the simple approa%h o$ >riting the +!B8
$ile as p-oto.Apg in the root o$ the #@ %ar. 5he byte array itsel$ >ill be
garbage %olle%te on%e >e are one saving it, so there is no e;pli%it I$reeI
operation >e nee to o to release that memory.
(inally, >e arrange $or our 5-otoCallbac. to e;e%ute our Save5-oto<as.*
Camera.5ict&reCallbac. p-otoCallbac.#new Camera.ictureCallbac)() 4
p&blic void onicture+a)en(b+tePQ data> Camera camera) 4
new Save!oto+as)().e(ecute(data):
?
?:
-%6
PART III Advanced System
CHAPTER 9
Sensors
I#ensorsI is Anroi7s overall term $or >ays that Anroi %an ete%t
elements o$ the physi%al >orl aroun it, $rom magneti% $lu; to the
movement o$ the evi%e. 0ot all evi%es >ill have all possible sensors, an
other sensors are likely to be ae over time. .n this %hapter, >e >ill
e;plore >hat sensors are theoreti%ally available an ho> to use a $e> o$
them that >ork on early Anroi evi%es like the 53Mobile 8-.
5he samples in this %hapter assume that you have a%%ess to a pie%e o$
sensor3e<uippe Anroi har>are, su%h as a 53Mobile 8-. 5he
Gpen.ntents.org proLe%t has a sensor simulator >hi%h you %an also use,
though the use o$ this tool is not %overe here.
5he author >oul like to thank #ean Catlin $or %oe samples that helpe
%lear up %on$usion surrouning the use o$ sensors.
The Sixth Sense/ ,r Possibly the Seventh/
.n theory, Anroi supports the $ollo>ing sensor types*
An a%%elerometer, that tells you the motion o$ the evi%e in spa%e
through all three imensions
An ambient light sensor, telling you ho> bright or ark the
surrounings are
-%.
Sensors
A magneti% $iel sensor, to tell you >here magneti% north is &unless
some other magneti% $iel is nearby, su%h as $rom an ele%tri%al
motor'
An orientation sensor, to tell you ho> the evi%e is positione in all
three imensions
A pro;imity sensor, to tell you ho> $ar the evi%e is $rom some
other spe%i$i% obLe%t
A temperature sensor, to tell you the temperature o$ the
surrouning environment
A tri%orer sensor, to turn the evi%e into Ia $ully $un%tional
5ri%orerI
Clearly, not all o$ these possible sensors are available toay, su%h as the last
one. What e$initely are available toay on the 53Mobile 8- are the
a%%elerometer, the magneti% $iel sensor, an the orientation sensor.
5o a%%ess any o$ these sensors, you nee a Sensor9anager, $oun in the
android.-ardware pa%kage. Like other aspe%ts o$ Anroi, the Sensor9anager
is a system servi%e, an as su%h is obtaine via the getS+stemService()
metho on your 3ctivit+ or other Context*
mgr#(Sensor9anager)getSystemService(Context.S8=S26/S86VIC8):
,rienting 7ourself
.n prin%iple, to $in out >hi%h ire%tion is north, you >oul use the
magneti% $lu; sensor an go through a lovely set o$ %al%ulations to $igure
out the appropriate ire%tion.
(ortunately $or us, Anroi i all that as part o$ the orientation sensor...so
long as the evi%e is hel $lat in the horiContal plane &e.g., on a level
tabletop'.
Akin to the lo%ation servi%es, there is no >ay to ask the Sensor9anager >hat
the %urrent value o$ a sensor is. .nstea, you nee to hook up a
-%$
Sensors
Sensor8vent*istener an respon to %hanges in the sensor values. 5o o
this, simply %all register*istener() >ith your Sensor8vent*istener an the
Sensor you >ish to hear $rom. Dou %an get the Sensor by asking the
Sensor9anager $or the e$ault Sensor $or a parti%ular type. (or e;ample, $rom
the Sensor/Compass sample proLe%t, here is >here >e register our listener*
mgr.registerListener(listener>
mgr.get"efaultSensor(Sensor.<C58/26I8=<3<I2=)>
Sensor9anager.S8=S26/78*3C/DI):
0ote that you also spe%i$y the rate at >hi%h sensor upates >ill be re%eive.
)ere, >e use S8=S26/78*3C/DI, but you %oul say S8=S26/78*3C/K3S<8S< or
various other values.
.t is important to unregister the listener >hen the a%tivity %loses o>nO
other>ise, the appli%ation >ill never really terminate an the listener >ill
get upates ine$initely. 5o o this, Lust %all &nregister*istener() $rom a
likely lo%ation, su%h as on7estro+()*
02verride
s&per.on"estroy():
mgr.unregisterListener(listener):
?
Dour Sensor8vent*istener implementation >ill nee t>o methos. 5he one
you probably >ill not use that o$ten is on3cc&rac+C-anged(), >hen you >ill
be noti$ie as a given sensor7s a%%ura%y %hanges $rom
S8=S26/S<3<DS/3CCD63CC/BIGB to S8=S26/S<3<DS/3CCD63CC/987ID9 to
S8=S26/S<3<DS/3CCD63CC/*2W to S8=S26/S<3<DS/D=68*I3;*8.
5he one you >ill use more %ommonly is onSensorC-anged(), >here you are
provie a Sensor8vent %ontaining a floatPQ o$ values $or the sensor. 5he
tri%ky part is etermining >hat these sensor values mean.
.n the %ase o$ <C58/26I8=<3<I2=, the $irst o$ the supplie values represents
the orientation o$ the evi%e in egrees o$$ o$ magneti% north. 90 egrees
means east, -20 means south, an 210 means >est, Lust like on a regular
%ompass.
-%0
Sensors
.n Sensor/Compass, >e upate a <extView >ith the ea%h reaing*
private Sensor8vent*istener listener#new SensorEventListener() 4
p&blic void onSensorC!anged(Sensor8vent e) 4
if (e.sensor.get+ype()##Sensor.<C58/26I8=<3<I2=) 4
degrees.set+e(t(String.value$f(e.val&esP%Q)):
?
?
p&blic void on&ccuracyC!anged(Sensor sensor> int acc&rac+) 4
// &n&sed
?
?:
What you get is a trivial appli%ation sho>ing >here the top o$ the phone is
pointing. 0ote that the sensor seems to take a bit to get initially stabiliCe,
then >ill ten to lag a%tual motion a bit.
!igure .$/ The Compass9emo application* sho)ing a T"8obile '- pointing
south"by"southeast
-%2
Sensors
Steering 7our Phone
.n television %ommer%ials $or other mobile evi%es, you may see them being
use like a steering >heel, o$ten times $or playing a riving simulation
game.
Anroi %an o this too. Dou %an see it in the Sensor/Steering sample
appli%ation.
.n the pre%eing se%tion, >e note that <C58/26I8=<3<I2= returns in the $irst
value o$ the floatPQ the orientation o$ the phone, %ompare to magneti%
north, i$ the evi%e is horiContal. When the evi%e is hel like a steering
>heel, the se%on value o$ the floatPQ >ill %hange as the evi%e is IsteereI.
5his sample appli%ation is very similar to the Sensor/Compass one sho>n in
the previous se%tion. 5he biggest %hange %omes in the Sensor8vent*istener
implementation*
if (e.sensor.get+ype()##Sensor.<C58/26I8=<3<I2=) 4
float orientation#e.val&esP1Q:
if (prev2rientationN#orientation) 4
if (prev2rientationorientation) 4
steerLeft(orientation>
orientation'prev2rientation):
?
else 4
steerRig!t(orientation>
prev2rientation'orientation):
?
prev2rientation#e.val&esP1Q:
?
?
?
// &n&sed
?
?:
-%3
Sensors
)ere, >e tra%k the previous orientation &prev2rientation' an %all a
steer*eft() or steer6ig-t() metho base on >hi%h ire%tion the I>heelI is
turne. (or ea%h, >e provie the ne> %urrent position o$ the >heel an the
amount the >heel turne, measure in egrees.
5he steer*eft() an steer6ig-t() methos, in turn, simply ump their
results to a Itrans%riptI* a <extView insie a ScrollView, set up to
automati%ally keep s%rolling to the bottom*
private void steerLeft(float position> float delta) 4
String;&ffer line#new StringBuffer($Steered left b+ $):
line.append(String.value$f(delta)):
line.append($ to $):
line.append(String.value$f(position)):
line.append($Zn$):
transcript.set+e(t(transcript.get+e(t().toString()1line.toString()):
scroll.fullScroll(View.K2CDS/72W=):
?
private void steerRig!t(float position> float delta) 4
String;&ffer line#new StringBuffer($Steered rig-t b+ $):
line.append(String.value$f(delta)):
line.append($ to $):
line.append(String.value$f(position)):
line.append($Zn$):
transcript.set+e(t(transcript.get+e(t().toString()1line.toString()):
?
5he result is a log o$ the steering IeventsI as the evi%e is turne like a
steering >heel. Gbviously, a real game >oul translate these events into
game a%tions, su%h as %hanging your perspe%tive o$ the riving %ourse.
-%4
Sensors
!igure .0/ The Steering9emo application
9o DThe ShakeD
Another emo you o$ten see >ith %ertain other mobile evi%es is shaking
the evi%e to %ause some on3s%reen e$$e%t, su%h as rolling i%e or s%rambling
puCCle pie%es.
Anroi %an o this as >ell, as you %an see in the Sensor/S-a.er sample
appli%ation, >ith our ata provie by the a%%elerometer sensor
&<C58/3CC8*86298<86'.
What the a%%elerometer sensor provies is the a%%leration in ea%h o$ three
imensions. At rest, the a%%eleration is e<ual to Barth7s gravity &or the
gravity o$ >herever you are, i$ you are not on Barth'. When shaken, the
a%%eleration shoul be higher than Barth7s gravity M ho> mu%h higher is
epenent on ho> har the evi%e is being shaken. While the iniviual
a;es o$ a%%eleration might tell you, at any point in time, >hat ire%tion the
evi%e is being shaken in, sin%e a shaking a%tion involves $re<uent %onstant
%hanges in ire%tion, >hat >e really >ant to kno> is ho> $ast the evi%e is
moving overall M a slo> steay movement is not a shake, but something
more aggressive is.
Gn%e again, our ". output is simply a Itrans%riptI <extView as be$ore. 5his
time, though, >e separate out the a%tual shake3ete%tion logi% into a S-a.er
%lass >hi%h our S-a.er7emo a%tivity re$eren%es, as sho>n belo>*
-%5
Sensors
pac.age com.commonsware.android.sensor:
import android.&til.*og:
import android.widget.ScrollView:
p&blic class S-a.er7emo extends 3ctivit+
implements S-a.er.Callbac. 4
private S-a.er s-a.er#n&ll:
private <extView transcript#n&ll:
private ScrollView scroll#n&ll:

02verride

transcript#(<extView)findViewById(6.id.transcript):
scroll#(ScrollView)findViewById(6.id.scroll):

s-a.er#new S!a)er(t-is> 1.EHd> H%%> t-is):
?

02verride
s&per.on"estroy():

s-a.er.close():
?

p&blic void s!a)ingStarted() 4
*og.d($S-a.er7emo$> $S-a.ing startedN$):
transcript.set+e(t(transcript.get+e(t().toString()1$S-a.ing startedZn$):
?

p&blic void s!a)ingStopped() 4
*og.d($S-a.er7emo$> $S-a.ing stoppedN$):
transcript.set+e(t(transcript.get+e(t().toString()1$S-a.ing stoppedZn$):
?
?
5he S-a.er takes $our parameters*
A Context, so >e %an get a%%ess to the Sensor9anager servi%e
An ini%ation o$ ho> har a shake shoul <uali$y as a shake,
e;presse as a ratio applie to Barth7s gravity, so a value o$ 1.EH
-.6
Sensors
means the shake has to be 2AP stronger than gravity to be
%onsiere a shake
An amount o$ time >ith belo>3threshol a%%eleration, a$ter >hi%h
the shake is %onsiere IoneI
A S-a.er.Callbac. obLe%t that >ill be noti$ie >hen a shake starts
an stops
While in this %ase, the %allba%k methos &implemente on the S-a.er7emo
a%tivity itsel$' simply log shake events to the trans%ript, a IrealI appli%ation
>oul, say, start an animation o$ i%e rolling >hen the shake starts an en
the animation shortly a$ter the shake ens.
5he S-a.er simply %onverts the three iniviual a%%eleration %omponents
into a %ombine a%%eleration value &s<uare root o$ the sum o$ the s<uares',
then %ompares that value to Barth7s gravity. .$ the ratio is higher than the
supplie threshol, then >e %onsier the evi%e to be presently shaking,
an >e %all the s-a.ingStarted() %allba%k metho i$ the evi%e >as not
shaking be$ore. Gn%e shaking ens, an time elapses, >e %all
s-a.ingStopped() on the %allba%k obLe%t an assume that the shake has
ene. A more robust implementation o$ S-a.er >oul take into a%%ount
the possibility that the sensor >ill not be upate $or a >hile a$ter the
shake ens, though in reality, normal human movement >ill ensure that
there are some sensor upates, so >e %an $in out >hen the shaking ens.
pac.age com.commonsware.android.sensor:
import android.-ardware.Sensor:
import android.-ardware.Sensor8vent:
import android.-ardware.Sensor8vent*istener:
import android.-ardware.Sensor9anager:
import Aava.&til.3rra+*ist:
p&blic class S-a.er 4
private Sensor9anager mgr#n&ll:
private long lastS-a.e<imestamp#%:
private do&ble t-res-old#1.%d:
private long gap#%:
private S-a.er.Callbac. cb#n&ll:

-.-
Sensors
p&blic S!a)er(Context ctxt> do&ble t-res-old> long gap>
S-a.er.Callbac. cb) 4
t-is.t-res-old#t-res-oldMt-res-old:
t-is.t-res-old#t-is.t-res-old
MSensor9anager.G63VI<C/836<B
MSensor9anager.G63VI<C/836<B:
t-is.gap#gap:
t-is.cb#cb:

mgr#(Sensor9anager)ctxt.getSystemService(Context.S8=S26/S86VIC8):
mgr.registerListener(listener>
mgr.get"efaultSensor(Sensor.<C58/3CC8*86298<86)>
Sensor9anager.S8=S26/78*3C/DI):
?

p&blic void close() 4
mgr.unregisterListener(listener):
?

private void isS!a)ing() 4
long now#S+stemCloc..uptime%illis():

if (lastS-a.e<imestamp##%) 4
lastS-a.e<imestamp#now:

if (cbN#n&ll) 4
cb.s!a)ingStarted():
?
?
else 4
lastS-a.e<imestamp#now:
?
?

private void is-otS!a)ing() 4
long now#S+stemCloc..uptime%illis():

if (lastS-a.e<imestamp)%) 4
if (now'lastS-a.e<imestamp)gap) 4
lastS-a.e<imestamp#%:

if (cbN#n&ll) 4
cb.s!a)ingStopped():
?
?
?
?

p&blic interface Callbac. 4
void s!a)ingStarted():
void s!a)ingStopped():
?

-.%
Sensors
if (e.sensor.get+ype()##Sensor.<C58/3CC8*86298<86) 4
do&ble netKorce#e.val&esP%QMe.val&esP%Q:

netKorce1#e.val&esP1QMe.val&esP1Q:
netKorce1#e.val&esPEQMe.val&esPEQ:

if (t-res-oldnetKorce) 4
isS!a)ing():
?
else 4
is-otS!a)ing():
?
?
?

// &n&sed
?
?:
?
All the trans%ript sho>s, o$ %ourse, is >hen shaking starts an stops*
!igure .2/ The Shaker9emo application* sho)ing a pair of shakes
-..
CHAPTER 1:
9atabases and Content
Providers
.n the abstra%t, >orking >ith #FLite atabases an Anroi3style %ontent
proviers is $airly straight3$or>ar. Ba%h supports a CR"@3style inter$a%e
&@&er+(), insert(), &pdate(), delete()' using C&rsor obLe%ts $or <uery results.
While implementing a Content5rovider is no pi%ni% $or non3#FLite ata
stores, everything else is $airly rote.
.n reality, though, atabases an %ontent proviers %ause more than their
$air share o$ hassles. Mostly, this %omes $rom everything outside o$ simple
CR"@ operations, su%h as*
)o> o >e get a atabase into our appli%ationJ
)o> o >e get ata into our appli%ation on initial installJ Gn an
upateJ
Where is the o%umentation $or the built3in Anroi %ontent
proviersJ
)o> o >e eal >ith Loins bet>een ata stores, su%h as merging
%onta%ts >ith our o>n atabase ataJ
.n this %hapter, >e e;plore these issues, to sho> ho> you %an better >ork
>ith atabases an %ontent proviers in the real >orl.
-.0
9atabases and Content Providers
9istributed 9ata
#ome atabases use by Anroi appli%ations naturally start empty. (or
e;ample, a Ipass>or sa$eI probably has no pass>ors >hen initially
laun%he by the user, an an e;pense3tra%king appli%ation probably oes
not have any e;penses re%ore at the outset.
)o>ever, sometimes, there are atabases that nee to ship >ith an
appli%ation that must be pre3populate >ith ata. (or e;ample, you might
be implementing an online %atalog, >ith a atabase o$ items $or sale
installe >ith the appli%ation an upate as neee via %alls to some Web
servi%e. 5he same stru%ture >oul hol true $or any sort o$ re$eren%e, $rom
%hemi%als to >or translations to histori%al sports re%ors.
"n$ortunately, there is no >ay to ship a atabase >ith ata in it via the
Anroi A!K pa%kaging me%hanism. An A!K is an e;e%utable blob, $rom
the stanpoint o$ Anroi an @alvik. More importantly, it is store rea3
only in a E.! $ile, >hi%h makes upates to that ata oubly impossible.
5he ne;t3best option is to ship your ata >ith the appli%ation by some
other means an loa it into a ne>ly3%reate atabase >hen the appli%ation
is $irst run. 5his oes involve t>o %opies o$ the ata* the original in your
appli%ation an the >orking %opy in the atabase. 5hat may seem >aste$ul
in terms o$ spa%e. )o>ever, %ourtesy o$ E.! %ompression, the original %opy
may not take up all that mu%h spa%e. Also, you %an turn this into a $eature,
o$$ering some sort o$ IresetI me%hanism to reloa the >orking atabase
$rom the original i$ neee.
5he %hallenge then be%omes ho> to pa%kage the atabase %ontents into the
A!K an loa it into the >orking atabase. .eally, this involves as little
>ork as possible $rom the eveloper, %an $it into the e;isting buil system,
an %an take avantage o$ e;isting atabase manipulation tools &versus,
say, han3>riting hunres o$ S[* I=S86< statements'.
0ote that another possibility e;ists* pa%kage the binary #FLite atabase $ile
in the A!K &e.g., in res/raw/' an %opy it into position using binary streams.
-.2
5his assumes the #FLite atabase $ile your evelopment environment
>oul %reate is the same as >hat is e;pe%te by the #FLite engine bake
into Anroi. 5his %an >ork, but is likely to be more prone to versioning
issues M $or e;ample, i$ your evelopment environment is upgrae to a
ne>er #FLite that has a slightly i$$erent $ile $ormat.
(;"ite< =n3Device- =n3Des&top
5his be%omes mu%h simpler >hen you realiCe that Anroi uses #FLite $or
the atabase, an #FLite >orks on Lust about every plat$orm you might
nee. .t is trivial to >ork >ith #FLite atabases on your evelopment
>orkstation, even easier than >orking >ith atabases insie an Anroi
emulator or evi%e.
5he plan, there$ore, is to allo> evelopers to %reate the atabase to be
IshippeI as a #FLite atabase, then buil tools that pa%kage the #FLite
%ontents into the Anroi A!K an turn it ba%k into a atabase >hen the
appli%ation nees it.
5his allo>s evelopers to use >hatever tools they >ant to manipulate the
#FLite atabase, ranging $rom typi%al atabase management ".s to
spe%ialiCe %onversion s%ripts to >hatever.
5o make this plan >ork, though, >e nee t>o bits o$ %oe*
-. We nee something that e;tra%ts the ata out o$ the #FLite
atabase the eveloper has prepare an puts it somepla%e insie
the Anroi A!K
2. We nee something that ties in >ith S[*ite2penBelper that takes the
A!K3pa%kage ata an turns it into an on3evi%e atabase >hen
the atabase is $irst a%%esse.
E'portin! a Data#ase
(ortunately, the s@liteJ %omman3line e;e%utable that %omes stanar
>ith #FLite o$$ers a .d&mp %omman to ump the %ontents o$ a table as a
-.3
series o$ #FL statements* one to %reate the table, plus the ne%essary S[*
I=S86< statements to populate it. All >e nee to o is tie this into the buil
system, so the a%t o$ %ompiling the A!K also eals >ith the atabase.
Dou %an $in some sample %oe that hanles this in the 7atabase/5ac.ager
sample appli%ation. #pe%i$i%ally*
5here is a #FLite atabase %ontaining ata in the db/ proLe%t
ire%tory M in this %ase, it is the atabase $rom the
Content5rovider/Constants proLe%t $rom The Busy Coder's Guide to
Android Deelopment
5here is a pac.age/db.rb Ruby s%ript that >raps aroun the .d&mp
%omman to e;port the ata
5here is a %hange to the b&ild.xml Ant s%ript to use this Ruby s%ript
The Ruby Script
Dou may or may not be a $an o$ Ruby. While this sample %oe sho>s this
utility as a Ruby s%ript, rest assure that #FLite has inter$a%es to most
programming languages &though its +ava support is not the strongest', so
you %an %reate your o>n eition o$ this s%ript in >hatever language suits
you.
5he s%ript is $airly short*
re@&ire Or&b+gemsO
re@&ire Os@liteJO
7irPOdb/MOQ.eac- do Ypat-Y
db#S[*iteJ,,7atabase.new(pat-)

begin
db.exec&te($S8*8C< name K629 s@lite/master WB868 t+pe#OtableO$) do YrowY
if 36GV.incl&de!(rowP%Q)
p&ts \s@liteJ R4pat-? $.d&mp R4rowP%Q?$\
end
end
ens&re
db.close
end
end
-.4
.t iterates over every $ile in the db/ ire%tory an opens ea%h as a #FLite
atabase. .t then <ueries the atabase $or the list o$ tables &S8*8C< name K629
s@lite/master WB868 t+pe # OtableO'. Any table mat%hing a table name
passe in on the %omman line is assume to be one neeing to be
e;porte, so it prints to stdo&t the results o$ the s@liteJ .d&mp %omman,
run on that atabase an table. We use s@liteJ be%ause there oes not
appear to be an A!. %all that implements the .d&mp $un%tionality.
5o run this s%ript, you nee #FLite? installe, >ith s@liteJ in your !A5),
an you nee the Ruby interpreter. Dou also nee to run it $rom the proLe%t
ire%tory, >ith a db/ ire%tory %ontaining one or more atabase $iles.
Running the Ruby s%ript >ill ump the spe%i$ie tables as a set o$ #FL
statements*
;8GI= <63=S3C<I2=:
C683<8 <3;*8 constants (/id I=<8G86 56I936C V8C 3D<2I=C6898=<> title <8W<> val&e
683*):
I=S86< I=<2 $constants$ V3*D8S(1>OGravit+> 7eat- Star IO>J.HJ%JX1FEHF1(TXe'%G):
I=S86< I=<2 $constants$ V3*D8S(E>OGravit+> 8art-O>T.(%XXH%1X1GFJ1X):
I=S86< I=<2 $constants$ V3*D8S(J>OGravit+> J&piterO>EJ.1E%%%%(JTEJJF):
I=S86< I=<2 $constants$ V3*D8S(F>OGravit+> 9arsO>J.G1%%%%%J(1FXTG):
I=S86< I=<2 $constants$ V3*D8S(H>OGravit+> 9erc&r+O>J.G%%%%%%FGX(JGE):
I=S86< I=<2 $constants$ V3*D8S(X>OGravit+> 9oonO>1.X%%%%%%EJ(F1(X):
I=S86< I=<2 $constants$ V3*D8S(G>OGravit+> =ept&neO>11.%):
I=S86< I=<2 $constants$ V3*D8S((>OGravit+> 5l&toO>%.X%%%%%%EJ(F1(H():
I=S86< I=<2 $constants$ V3*D8S(T>OGravit+> Sat&rnO>(.TX%%%%%J(1FXTG):
I=S86< I=<2 $constants$ V3*D8S(1%>OGravit+> S&nO>EGH.%):
I=S86< I=<2 $constants$ V3*D8S(11>OGravit+> <-e IslandO>F.(1H1XE1(1(HFEH):
I=S86< I=<2 $constants$ V3*D8S(1E>OGravit+> Dran&sO>(.X(TTTTH(%J(JJ):
I=S86< I=<2 $constants$ V3*D8S(1J>OGravit+> Ven&sO>(.(XTTTT((HHHT%():
C299I<:
.n this %ase, the %onstants table is empty, so there are no S[* I=S86<
statements. )o>ever, you %oul easily a some ro>s to the constants table
M perhaps %onstants not available in Anroi itsel$ M an ship those along
>ith the table s%hema.
"oadin! the E'ported Data#ase
5he other en o$ his pro%ess is to take the ra> #FL stores in
res/raw/pac.aged/db.txt an Iin$lateI it at runtime into a atabase. #in%e
-.5
S[*ite2penBelper is esigne to hanle su%h operations, it seems to make
sense to implement this logi% as a sub%lass. Dou %an $in su%h a %lass M
7atabaseInstaller M in the 7atabase/5ac.ager sample proLe%t*
import android.database.S[*8xception:
import android.database.s@lite.S[*ite2penBelper:
import android.database.s@lite.S[*ite7atabase:
import android.database.s@lite.S[*ite[&er+;&ilder:
import Aava.io.M:
abstract class 7atabaseInstaller extends S[*ite2penBelper 4
abstract void !andleInstallError(<-rowable t):

private Context ctxt#n&ll:

p&blic "atabaseInstaller(Context context> String name>
S[*ite7atabase.C&rsorKactor+ factor+>
int version) 4
s&per(context> name> factor+> version):

t-is.ctxt#context:
?

02verride
p&blic void onCreate(S[*ite7atabase db) 4
tr+ 4
Inp&tStream stream#ctxt
.getResources()
.openRawResource(6.raw.pac.aged/db):
Inp&tStream6eader is#new InputStreamReader(stream):
;&ffered6eader in#new BufferedReader(is):
String str:

w-ile ((str # in.readLine()) N# n&ll) 4
if (Nstr.equals($;8GI= <63=S3C<I2=:$) UU Nstr.equals($C299I<:$)) 4
db.e(ecS0L(str):
?
?

in.close():
?
catc- (I28xception e) 4
!andleInstallError(e):
?
?
?
-$6
5his %lass is abstra%t, e;pe%ting sub%lasses to implement both the
onDpgrade() path $rom S[*ite2penBelper an a -andleInstall8rror() %allba%k
in %ase something $ails uring onCreate().
Most o$ the smarts are $oun in 7atabaseInstaller7s onCreate()
implementation. #in%e S[*ite7atabase has no means to e;e%ute #FL
statements %ontaine in an Inp&tStream, >e are stu%k opening the
6.raw.pac.aged/db resour%e an reaing the statements out ourselves, one at
a time.
)o>ever, the e;porte #FL >ill likely %ontain ;8GI= <63=S3C<I2=: an
C299I<: statements, sin%e s@liteJ e;pe%ts that s@liteJ itsel$ >oul be use
to re3e;e%ute the umpe #FL s%ript. #in%e transa%tions are hanle via
A!. %alls >ith S[*ite7atabase, >e %annot e;e%ute ;8GI= <63=S3C<I2=: an
C299I<: statements via execS[*() >ithout getting a Ineste transa%tionI
error. #o, >e skip those t>o statements an e;e%ute everything else, one
line at a time.
5he net result* onCreate() takes our ra> #FL an turns it into a table in our
on3evi%e atabase.
G$ %ourse, to really use this, you >ill nee to %reate a 7atabaseInstaller
sub%lass, su%h as ConstantsInstaller*
class ConstantsInstaller extends 7atabaseInstaller 4
p&blic ConstantsInstaller(Context context> String name>
S[*ite7atabase.C&rsorKactor+ factor+>
int version) 4
s&per(context> name> factor+> version):
?

void !andleInstallError(<-rowable t) 4
*og.e($Constants$> $8xception installing database$> t):
?
02verride
p&blic void onUpgrade(S[*ite7atabase db> int oldVersion>
-$-
int newVersion) 4
db.e(ecS0L($7625 <3;*8 IK 8WIS<S constants$):
onCreate(db):
?
?
5he rest o$ this proLe%t is largely ienti%al to the Content5rovider/Constants
sample $rom The Busy Coder's Guide to Android Deelopment.
Gne possible enhan%ement to 7atabaseInstaller is to %reate our o>n
transa%tion aroun the loop o$ execS[*() %alls. 5his >oul improve
per$orman%e ramati%ally, as other>ise, ea%h execS[*() %all is its o>n
transa%tion. 5he proo$ o$ this is le$t to the reaer as an e;er%ise.
<xamining 7our Eelationships
Anroi has a built3in %onta%t manager, integrate >ith the phone ialer.
Dou %an >ork >ith the %onta%ts via the Contacts %ontent provier.
)o>ever, %ompare to %ontent proviers $oun in, say, simpli$ie book
e;amples, the Contacts %ontent provier is rather intimiating. A$ter all,
there are -4 %lasses an 9 inter$a%es all involve in a%%essing this %ontent
provier. 5his se%tion >ill attempt to illustrate some o$ the patterns $or
making use o$ Contacts.
Contact Permissions
#in%e %onta%ts are privilege ata, you nee %ertain permissions to >ork
>ith them. #pe%i$i%ally, you nee the 6837/C2=<3C<S permission to <uery
an e;amine the Contacts %ontent an W6I<8/C2=<3C<S to a, moi$y, or
remove %onta%ts $rom the system.
(or e;ample, here is the mani$est $or the 7atabase/Contacts sample
appli%ation*
-$%
pac.age#$com.commonsware.android.database$
&ses'permission android,name#$android.permission.6837/C2=<3C<S$ /)
activit+ android,name#$.Contacts7emo$
android,label#$0string/app/name$)
intent'filter)
/intent'filter)
/activit+)
/application)
/manifest)
Pre3>oined Data
While the atabase unerlying the Contacts %ontent provier is private, one
%an imagine that it has several tables* one $or people, one $or their phone
numbers, one $or their email aresses, et%. 5hese are tie together by
typi%al atabase relations, most likely -*0, so the phone number an email
aress tables >oul have a $oreign key pointing ba%k to the table
%ontaining in$ormation about people.
5o simpli$y a%%essing all o$ this through the %ontent provier inter$a%e,
Anroi pre3Loins <ueries against some o$ the tables. (or e;ample, one %an
<uery $or phone numbers an get the %onta%t name an other ata along
>ith the number, >ithout having to someho> o a Loin operation yoursel$.
The (ample Activity
5he Contacts7emo a%tivity is simply a *ist3ctivit+, though it sports a Spinner
to go along >ith the obligatory *istView*
)
Spinner android,id#$01id/spinner$
-$.
android,drawSelector2n<op#$tr&e$
/)
*istView
android,drawSelector2n<op#$false$
/)
/*inear*a+o&t)
5he a%tivity itsel$ sets up a listener on the Spinner an toggles the list o$
in$ormation sho>n in the *istView >hen the Spinner value %hanges*
pac.age com.commonsware.android.database:
import android.database.C&rsor:
import android.provider.Contacts:
import android.widget.*ist3dapter:
import android.widget.SimpleC&rsor3dapter:
import android.widget.Spinner:
p&blic class Contacts7emo extends *ist3ctivit+
implements 3dapterView.2nItemSelected*istener 4
private static StringPQ options#4$Contact =ames$>
$Contact =ames U =&mbers$>
$Contact =ames U 8mail 3ddresses$?:
private *ist3dapterPQ list3dapters#new *ist3dapterPJQ:
02verride

initList&dapters():

Spinner spin#(Spinner)findViewById(6.id.spinner):
spin.set$nItemSelectedListener(t-is):

3rra+3dapterString) aa#new 3rra+3dapterString)(t-is>
android.6.la+o&t.simple/spinner/item>
options):

aa.set"rop"ownViewResource(
android.6.la+o&t.simple/spinner/dropdown/item):
spin.set&dapter(aa):
?

-$$
View v> int position> long id) 4
setList&dapter(list3daptersPpositionQ):
?

// ignore
?

private void initList&dapters() 4
list3daptersP%Q#build-ame&dapter():
list3daptersP1Q#build!ones&dapter():
list3daptersPEQ#buildEmail&dapter():
?

private *ist3dapter build-ame&dapter() 4
StringPQ 562J8C<I2=#new StringPQ 4 Contacts.5eople./I7>
Contacts.5eopleCol&mns.=398
?:
C&rsor c#managed0uery(Contacts.5eople.C2=<8=</D6I>
562J8C<I2=> n&ll> n&ll>
Contacts.5eople.78K3D*</S26</26786):

ret&rn(new SimpleCursor&dapter( t-is>
c>
new StringPQ 4
?>
new intPQ 4
android.6.id.text1
?)):
?

private *ist3dapter build!ones&dapter() 4
StringPQ 562J8C<I2=#new StringPQ 4 Contacts.5-ones./I7>
Contacts.5-ones.=398>
Contacts.5-ones.=D9;86
?:
C&rsor c#managed0uery(Contacts.5-ones.C2=<8=</D6I>
562J8C<I2=> n&ll> n&ll>
Contacts.5-ones.78K3D*</S26</26786):

android.6.la+o&t.simple/list/item/E>
c>
new StringPQ 4
?>
new intPQ 4
android.6.id.text1>
android.6.id.textE
?)):
-$0
?

private *ist3dapter buildEmail&dapter() 4
StringPQ 562J8C<I2=#new StringPQ 4 Contacts.Contact9et-ods./I7>
Contacts.Contact9et-ods.73<3>
?:
C&rsor c#managed0uery(Contacts.Contact9et-ods.C2=<8=</893I*/D6I>
562J8C<I2=> n&ll> n&ll>
Contacts.Contact9et-ods.78K3D*</S26</26786):

c>
new StringPQ 4
Contacts.5eopleCol&mns.=398>
Contacts.Contact9et-ods.73<3
?>
new intPQ 4
android.6.id.text1>
android.6.id.textE
?)):
?
?
When the a%tivity is $irst opene, it sets up three 3dapter obLe%ts, one $or
ea%h o$ three perspe%tives on the %onta%ts ata. 5he Spinner simply resets
the list to use the 3dapter asso%iate >ith the Spinner value sele%te.
Accessin! People
5he $irst 3dapter sho>s the names o$ all o$ the %onta%ts. #in%e all the
in$ormation >e seek is in the %onta%t itsel$, >e %an use the C2=<8=</D6I
provier, retrieve all o$ the %onta%ts in the e$ault sort orer, an pour
them into a SimpleC&rsor3dapter set up to sho> ea%h person on its o>n ro>*
private *ist3dapter build-ame&dapter() 4
StringPQ 562J8C<I2=#new StringPQ 4 Contacts.5eople./I7>
?:
C&rsor c#managed0uery(Contacts.5eople.C2=<8=</D6I>
562J8C<I2=> n&ll> n&ll>
Contacts.5eople.78K3D*</S26</26786):
c>
new StringPQ 4
-$2
?>
new intPQ 4
android.6.id.text1
?)):
?
Assuming you have some %onta%ts in the atabase, they >ill appear >hen
you $irst open the Contacts7emo a%tivity, sin%e that is the e$ault perspe%tive*
!igure .3/ The Contacts9emo sample application* sho)ing all contacts
Accessin! Phone 1um#ers
Retrieving a list o$ %onta%ts by their phone number %an be one by
<uerying the C2=<8=</D6I %ontent provier*
private *ist3dapter build!ones&dapter() 4
StringPQ 562J8C<I2=#new StringPQ 4 Contacts.5-ones./I7>
?:
C&rsor c#managed0uery(Contacts.5-ones.C2=<8=</D6I>
562J8C<I2=> n&ll> n&ll>
Contacts.5-ones.78K3D*</S26</26786):
-$3
c>
new StringPQ 4
?>
new intPQ 4
android.6.id.text1>
android.6.id.textE
?)):
?
#in%e the o%umentation $or Contacts.5-ones sho>s that it in%orporates
Contacts.5eopleCol&mns an Contacts.5-onesCol&mns, >e kno> >e %an get the
phone number an the %onta%t7s name in one <uery, >hi%h is >hy both are
in%lue in our proLe%tion o$ %olumns to retrieve.
!igure .4/ The Contacts9emo sample application* sho)ing all contacts that
have phone numbers
Accessin! Email Addresses
#imilarly, to get a list o$ all the email aresses, >e %an use the
C2=<8=</893I*/D6I %ontent provier, >hi%h in%orporates the
-$4
Contacts.Contact9et-odsCol&mns an Contacts.5eopleCol&mns, so >e %an get
a%%ess to the %onta%t name as >ell as the email aress itsel$ &73<3'*
private *ist3dapter buildEmail&dapter() 4
StringPQ 562J8C<I2=#new StringPQ 4 Contacts.Contact9et-ods./I7>
Contacts.Contact9et-ods.73<3>
?:
C&rsor c#managed0uery(Contacts.Contact9et-ods.C2=<8=</893I*/D6I>
562J8C<I2=> n&ll> n&ll>
Contacts.Contact9et-ods.78K3D*</S26</26786):
c>
new StringPQ 4
Contacts.5eopleCol&mns.=398>
Contacts.Contact9et-ods.73<3
?>
new intPQ 4
android.6.id.text1>
android.6.id.textE
?)):
?
Again, the results are isplaye via a t>o3line SimpleC&rsor3dapter*
!igure .5/ The Contacts9emo sample application* sho)ing all contacts )ith
email addresses
-$5
Eummaging Through 7our Phone Eecords
5he Call*og %ontent provier in Anroi gives you a%%ess to the %alls
asso%iate >ith your phone* the %alls you pla%e, the %alls you re%eive, an
the %alls that you misse. 5his is a mu%h simpler stru%ture than the
Contacts %ontent provier es%ribe in the previous se%tion.
5he %olumns available to you %an be $oun in the Call*og.Calls %lass. 5he
%ommonly3use ones in%lue*
=D9;86* the phone number asso%iate >ith the %all
73<8* >hen the %all >as pla%e, in millise%ons3sin%e3the3epo%h
$ormat
7D63<I2=* ho> long the %all laste, in se%ons
<C58* ini%ating i$ the %all >as in%oming, outgoing, or misse
5hese, o$ %ourse, are augmente by the sto%k ;aseCol&mns, >hi%h
Call*og.Calls inherits $rom.
#o, $or e;ample, here is a proLe%tion use against the %all log, $rom the
Join7emo a%tivity in the 7atabase/JoinC&rsor proLe%t*
private static StringPQ 562J8C<I2=#new StringPQ 4 Call*og.Calls./I7>
Call*og.Calls.=D9;86>
Call*og.Calls.73<8>
Call*og.Calls.7D63<I2=
?:
)ere is >here >e get a C&rsor on that proLe%tion, >ith the most3re%ent %alls
$irst in the list*
C&rsor c#managed0uery(android.provider.Call*og.Calls.C2=<8=</D6I>
562J8C<I2=> n&ll> n&ll>
Call*og.Calls.73<81$ 78SC$):
"nlike %onta%ts, the %all log appears unmoi$iable by Anroi appli%ations.
#o >hile you %an <uery the log, you %annot a your o>n %alls, elete %alls,
et%.
-06
Also note that, to a%%ess the %all log, you nee the 6837/C2=<3C<S
permission.
Come Together* Eight @o)
.$ you have multiple tables >ithin a atabase, an you >ant a C&rsor that
represents a Loin o$ those tables, you %an a%%omplish that simply through a
>ell3%onstru%te <uery. )o>ever, i$ you have multiple atabases, or you
>ish to Loin ata in your atabase >ith ata $rom a thir3party
Content5rovider, the Loin be%omes signi$i%antly more i$$i%ult. Dou %annot
simply %onstru%t a <uery, sin%e #FLite has no $a%ility &toay' to <uery a
Content5rovider, let alone Loin a Content5rovider7s %ontents >ith those $rom
native tables.
Gne solution is to o the Loin at the C&rsor itsel$. Anroi7s C&rsors o$$er a
$airly vanilla inter$a%e, an Anroi even supplies a C&rsorWrapper %lass that
%an hanle mu%h o$ the e$$ort $or us. .n this se%tion, >e >ill e;amine the
use o$ C&rsorWrapper to %reate a JoinC&rsor, blening ata $rom a #FLite
table >ith that $rom the Call*og.
0ote that the implementation sho>n here is $or illustrative purposes only.
.t may su$$er $rom signi$i%ant per$orman%e issues, parti%ularly memory
%onsumption, that >oul nee to be aresse in a serious prou%tion
appli%ation. .$ you are intereste in perhaps pursuing an open sour%e
proLe%t to implement a better version o$ JoinC&rsor, %onta%t the author.
Also note that there is a C&rsorJoiner %lass in the android.database pa%kage
in the #@K. A C&rsorJoiner takes t>o C&rsor obLe%ts plus a list o$ key
%olumns, using the key %olumns to Loin the C&rsor values together. 5his is
more e$$i%ient but some>hat less $le;ible that the implemenation sho>n
here.
-0-
Cursorrapper
As the name suggests, C&rsorWrapper >raps a C&rsor obLe%t. #pe%i$i%ally,
C&rsorWrapper implements the C&rsor inter$a%e itsel$ an elegates all o$ the
inter$a%e7s %alls to the >rappe C&rsor.
Gn the sur$a%e, this seems pointless. A$ter all, i$ C&rsorWrapper simply serves
as a pass3through to the C&rsor, >hy not use the unerlying C&rsor ire%tlyJ
5he key is not C&rsorWrapper itsel$, but rather %ustom sub%lasses o$
C&rsorWrapper. Dou %an then overrie %ertain C&rsor methos, to per$orm
>ork in aition to, or perhaps instea o$, passing the %all to the >rappe
C&rsor.
.n this %ase, >e >ant to %reate a C&rsorWrapper sub%lass that allo>s us to
inLe%t aitional %olumns into the results. 5hese %olumns >ill be the result
o$ a Loin operation bet>een a #FLite table an the Call*og.
#pe%i$i%ally, the @atabaseQ+oinCursor proLe%t as I%all notesI M a blo%k o$
te;t about a spe%i$i% %all one mae. Dou %oul use this %on%ept in a %onta%t
management system, $or e;ample, to annotate >hat all >as is%usse in a
%all or other>ise o%ument the %all itsel$. #in%e Call*og is not moi$iable
an has no $iel $or I%all notesI any>ay, >e %annot store su%h notes in the
Call*og. .nstea, >e store those notes in a %allRnotes #FLite table, mapping
the Call*og ro> /id to the note.
(or simpli%ity, this e;ample >ill assume that there are 0 or - notes per %all,
not several. 5hat allo>s the JoinC&rsor to simply inLe%t the %all note into the
Call*og C&rsor results, >ithout having to >orry about ealing >ith several
possible notes. We o, ho>ever, nee to eal >ith the %ase >here the %all
oes not yet have a note.
$mplementin! a >oinCursor
A JoinC&rsor is a relatively %omple; %lass. #ome o$ that %omple;ity is ue to
repeate boilerplate %oe, an some is ue to the problem being solve.
-0%
What >e nee the JoinC&rsor to o is*
Gverrie C&rsor3relate methos that involve the %olumns
Che%k to see i$ there is a note $or the %urrent ro>
ALust the results o$ the metho to a%%omoate the possibility &or
reality' o$ a note
Dou %an see an implementation o$ this in the JoinC&rsor %lass in the
7atabase/JoinC&rsor proLe%t*
import android.content.ContentVal&es:
import android.database.C&rsorWrapper:
import Aava.&til.*in.edBas-9ap:
import Aava.&til.9ap:
class JoinC&rsor extends C&rsorWrapper 4
private I/JoinBandler Aoin#n&ll:
private JoinCac-e cac-e#new JoinCac!e(1%%):

JoinCursor(C&rsor main> I/JoinBandler Aoin) 4
s&per(main):

t-is.Aoin#Aoin:
?

p&blic int getColumnCount() 4
ret&rn(s&per.getColumnCount()1Aoin.getColumn-ames().lengt-):
?

p&blic int getColumnInde((String col&mn=ame) 4
for (int i#%:iAoin.getColumn-ames().lengt-:i11) 4
if (col&mn=ame.equals(Aoin.getColumn-ames()PiQ)) 4
ret&rn(s&per.getColumnCount()1i):
?
?

ret&rn(s&per.getColumnInde((col&mn=ame)):
?

p&blic int getColumnInde($r+!row(String col&mn=ame) 4
for (int i#%:iAoin.getColumn-ames().lengt-:i11) 4
if (col&mn=ame.equals(Aoin.getColumn-ames()PiQ)) 4
ret&rn(s&per.getColumnCount()1i):
?
?

ret&rn(s&per.getColumnInde($r+!row(col&mn=ame)):
?
-0.

p&blic String getColumn-ame(int col&mnIndex) 4
if (col&mnIndex)#s&per.getColumnCount()) 4
ret&rn(Aoin.getColumn-ames()Pcol&mnIndex's&per.getColumnCount()Q):
?

ret&rn(s&per.getColumn-ame(col&mnIndex)):
?

p&blic b+tePQ getBlob(int col&mnIndex) 4
ContentVal&es extras#cac-e.get(Aoin.getCac!e#ey(t-is)):
int offset#col&mnIndex's&per.getColumnCount():

ret&rn(extras.get&sByte&rray(Aoin.getColumn-ames()PoffsetQ)):
?

ret&rn(s&per.getBlob(col&mnIndex)):
?

p&blic do&ble get"ouble(int col&mnIndex) 4

ret&rn(extras.get&s"ouble(Aoin.getColumn-ames()PoffsetQ)):
?

ret&rn(s&per.get"ouble(col&mnIndex)):
?

p&blic float get'loat(int col&mnIndex) 4

ret&rn(extras.get&s'loat(Aoin.getColumn-ames()PoffsetQ)):
?

ret&rn(s&per.get'loat(col&mnIndex)):
?

p&blic int getInt(int col&mnIndex) 4

ret&rn(extras.get&sInteger(Aoin.getColumn-ames()PoffsetQ)):
?

ret&rn(s&per.getInt(col&mnIndex)):
?

p&blic long getLong(int col&mnIndex) 4
-0$

ret&rn(extras.get&sLong(Aoin.getColumn-ames()PoffsetQ)):
?

ret&rn(s&per.getLong(col&mnIndex)):
?

p&blic s-ort getS!ort(int col&mnIndex) 4

ret&rn(extras.get&sS!ort(Aoin.getColumn-ames()PoffsetQ)):
?

ret&rn(s&per.getS!ort(col&mnIndex)):
?

p&blic String getString(int col&mnIndex) 4

ret&rn(extras.get&sString(Aoin.getColumn-ames()PoffsetQ)):
?

ret&rn(s&per.getString(col&mnIndex)):
?

p&blic boolean is-ull(int col&mnIndex) 4

ret&rn(extras.get(Aoin.getColumn-ames()PoffsetQ)##n&ll):
?

ret&rn(s&per.is-ull(col&mnIndex)):
?

p&blic boolean requery() 4
cac-e.clear():

ret&rn(s&per.requery()):
?

class JoinCac-e extends *in.edBas-9apString> ContentVal&es) 4
private int capacit+#1%%:

JoinCac!e(int capacit+) 4
s&per(capacit+11> 1.1f> tr&e):
-00
t-is.capacit+#capacit+:
?

protected boolean removeEldestEntry(8ntr+String> ContentVal&es) eldest) 4
ret&rn(si.e())capacit+):
?

ContentVal&es get(String .e+) 4
ContentVal&es res&lt#s&per.get(.e+):

if (res&lt##n&ll) 4
res&lt#Aoin.getJoin(JoinC&rsor.t-is):
put(.e+> res&lt):
?

ret&rn(res&lt):
?
?
?
JoinC&rsor, >hen instantiate, gets both the C&rsor to >rap an an
I/JoinBandler instan%e. 5he Loin hanler is responsible $or getting the e;tra
%olumns $or a given ro>*
import Aava.&til.9ap:
p&blic interface I/JoinBandler 4
StringPQ getColumn-ames():
String getCac!e#ey(C&rsor c):
ContentVal&es getJoin(C&rsor c):
?
Most o$ JoinC&rsor is then using the I/JoinBandler in$ormation to aLust the
results o$ various C&rsor methos. (or e;ample*
getCol&mnCo&nt() returns the sum o$ the C&rsor7s %olumn %ount an
the number o$ e;tra %olumns returne by the Loin hanler
getCol&mnIndex() an kin nee to sear%h through the Loin hanler7s
%olumns as >ell as the C&rsor7s to $in the mat%h, i$ any
getInt(), is=&ll(), an kin nee to support retrieving values $rom
both the C&rsor an the Loin hanler
-02
5o improve per$orman%e, JoinC&rsor keeps a %a%he o$ the e;tra values $or
re<ueste ro>s, using an ILR" %a%heI3style *in.edBas-9ap an an inner
JoinCac-e %lass. 5he JoinCac-e keeps the ContentVal&es returne by
I/JoinBandler on a getJoin() %all, representing the e;tra %olumns &i$ any' $or
that parti%ular C&rsor ro>. #in%e >e are %a%hing ata, ho>ever, >e nee to
$lush that %a%he sometimesO in this %ase, >e overrie re@&er+() to $lush the
%a%he i$ the C&rsor itsel$ is being proa%tively upate.
%sin! a >oinCursor
5o use a JoinC&rsor, o$ %ourse, you nee an implementation o$
I/JoinBandler, su%h as this one $rom the Join7emo a%tivity*
I/JoinBandler Aoin#new I1Join*andler() 4
StringPQ col&mns#4=2<8/I7> =2<8?:
p&blic StringPQ getColumn-ames() 4
ret&rn(col&mns):
?
p&blic String getCac!e#ey(C&rsor c) 4
ret&rn(String.value$f(c.getInt(c.getColumnInde((Call*og.Calls./I7)))):
?
p&blic ContentVal&es getJoin(C&rsor c) 4
StringPQ args#4getCac!e#ey(c)?:
C&rsor A#get"b().raw0uery($S8*8C< /I7> note K629 call/notes WB868
call/id#!$> args):
ContentVal&es res&lt#new ContentValues():
A.move+o'irst():
if (A.is&fterLast()) 4
res&lt.put(col&mnsP%Q> '1):
res&lt.put(col&mnsP1Q> (String)n&ll):
?
else 4
res&lt.put(col&mnsP%Q> A.getInt(%)):
res&lt.put(col&mnsP1Q> A.getString(1)):
?
A.close():
ret&rn(res&lt):
?
?:
-03
5he %olumns are a $i;e pair &the note7s .@ an the note itsel$'. 5hese are
retrieve via getJoin() $rom the call/notes #FLite table. 5he %all notes
themselves are keye by the %all7s o>n /id, >hi%h is also use as the key $or
the JoinC&rsor7s %a%he o$ results. 5he net e$$e%t is that >e only ever retrieve
a note on%e $or a given %all, at least until a re@&er+(). An, i$ there is no
note $or the %all, >e use a n&ll note to ini%ate that >e are, inee, note3
$ree $or this %all.
5he note in$ormation is then use by our C&rsor3dapter sub%lass
&Call5l&s3dapter' an its asso%iate ViewWrapper, also $oun in the Join7emo
a%tivity*
class Call5l&s3dapter extends C&rsor3dapter 4
Calllus&dapter(C&rsor c) 4
s&per(Join7emo.t-is> c):
?
02verride
p&blic void bindView(View row> Context ctxt>
C&rsor c) 4
ViewWrapper wrapper#(ViewWrapper)row.get+ag():
wrapper.update(c):
?
02verride
p&blic View newView(Context ctxt> C&rsor c>
ViewGro&p parent) 4
*a+o&tInflater inflater#getLayoutInflater():
View row#inflater.inflate(6.la+o&t.row> n&ll):
ViewWrapper wrapper#new View,rapper(row):
row.set+ag(wrapper):
wrapper.update(c):
ret&rn(row):
?
?
class ViewWrapper 4
View base:
<extView n&mber#n&ll:
<extView d&ration#n&ll:
<extView time#n&ll:
ImageView icon#n&ll:
View,rapper(View base) 4
t-is.base#base:
-04
?
<extView get-umber() 4
if (n&mber##n&ll) 4
n&mber#(<extView)base.findViewById(6.id.n&mber):
?
ret&rn(n&mber):
?
<extView get"uration() 4
if (d&ration##n&ll) 4
d&ration#(<extView)base.findViewById(6.id.d&ration):
?
ret&rn(d&ration):
?
<extView get+ime() 4
if (time##n&ll) 4
time#(<extView)base.findViewById(6.id.time):
?
ret&rn(time):
?
ImageView getIcon() 4
if (icon##n&ll) 4
icon#(ImageView)base.findViewById(6.id.note):
?
ret&rn(icon):
?
void update(C&rsor c) 4
get-umber().set+e(t(c.getString(c.getColumnInde((Call*og.Calls.=D9;86))):
get+ime().set+e(t(K2693<.format(c.getInt(c.getColumnInde((Call*og.Calls.73<8
)))):
get"uration().set+e(t(c.getString(c.getColumnInde((Call*og.Calls.7D63<I2=))
1$ seconds$):
String note#c.getString(c.getColumnInde((=2<8)):
if (noteN#n&ll UU note.lengt!())%) 4
getIcon().setVisibility(View.VISI;*8):
?
else 4
getIcon().setVisibility(View.G2=8):
?
?
?
-05
Mostly, >e are populating a ro> to go in a *istView base o$$ o$ the %all ata
&e.g., uration'. )o>ever, i$ there is a non3n&ll note, >e also isplay an
i%on in the ro>, ini%ating that a note is available.
5he Join7emo a%tivity itsel$ is Lust a *ist3ctivit+, using the Call5l&s3dapter
an the Call*og C&rsor >e sa> in the previous se%tion*
import android.provider.Call*og:
import android.view.*a+o&tInflater:
import android.widget.C&rsor3dapter:
import android.widget.ImageView:
import Aava.text.Simple7ateKormat:
p&blic class Join7emo extends *ist3ctivit+ 4
p&blic static String =2<8#$/=2<8$:
private static String =2<8/I7#$=2<8/I7$:
private static StringPQ 562J8C<I2=#new StringPQ 4 Call*og.Calls./I7>
Call*og.Calls.=D9;86>
Call*og.Calls.73<8>
Call*og.Calls.7D63<I2=
?:
private static Simple7ateKormat K2693<#new Simple"ate'ormat($99/d -,mm a$):
private C&rsor c&rsor#n&ll:
private int noteCol&mn#'1:
private int idCol&mn#'1:
private int noteIdCol&mn#'1:
private S[*ite7atabase db#n&ll:

02verride

C&rsor c#managed0uery(android.provider.Call*og.Calls.C2=<8=</D6I>
562J8C<I2=> n&ll> n&ll>
Call*og.Calls.73<81$ 78SC$):

c&rsor#new JoinCursor(c> Aoin):
noteCol&mn#c&rsor.getColumnInde((=2<8):
idCol&mn#c&rsor.getColumnInde((Call*og.Calls./I7):
noteIdCol&mn#c&rsor.getColumnInde((=2<8/I7):
-26
setList&dapter(new Calllus&dapter(c&rsor)):
?

02verride
s&per.onResume():

c&rsor.requery():
?

02verride
s&per.on"estroy():

if (dbN#n&ll) 4
db.close():
?
?

02verride
protected void onListItemClic)(*istView l> View v>
int position> long id) 4
c&rsor.move+oosition(position):

String note#c&rsor.getString(noteCol&mn):

if (note##n&ll YY note.lengt!()##%) 4
Intent i#new Intent(t-is> =ote8ditor.class):

i.putE(tra(=2<8> note):
i.putE(tra($call/id$> c&rsor.getInt(idCol&mn)):
i.putE(tra($note/id$> c&rsor.getInt(noteIdCol&mn)):
start&ctivity'orResult(i> 1):
?
else 4
Intent i#new Intent(t-is> =ote3ctivit+.class):

i.putE(tra(=2<8> note):
start&ctivity(i):
?
?

02verride
protected void on&ctivityResult(int re@&estCode>
int res&ltCode>
Intent data) 4
String note#data.getStringE(tra(=2<8):

if (noteN#n&ll) 4
int noteId#data.getIntE(tra(=2<8/I7> '1):
ContentVal&es cv#new ContentValues():

cv.put($note$> note):

-2-
if (noteId##'1) 4
int callId#data.getIntE(tra($call/id$> '1):

cv.put($call/id$> callId):

get"b().insert$r+!row($call/notes$> $/id$> cv):
?
else 4
StringPQ args#4String.value$f(noteId)?:

get"b().update($call/notes$> cv> $/I7$> args):
?
?
?

S[*ite7atabase get"b() 4
if (db##n&ll) 4
db#(new -otesInstaller(Join7emo.t-is)).get,ritable"atabase():
?

ret&rn(db):
?

I/JoinBandler Aoin#new I1Join*andler() 4
StringPQ col&mns#4=2<8/I7> =2<8?:

p&blic StringPQ getColumn-ames() 4
ret&rn(col&mns):
?

p&blic String getCac!e#ey(C&rsor c) 4
ret&rn(String.value$f(c.getInt(c.getColumnInde((Call*og.Calls./I7)))):
?

p&blic ContentVal&es getJoin(C&rsor c) 4
StringPQ args#4getCac!e#ey(c)?:
C&rsor A#get"b().raw0uery($S8*8C< /I7> note K629 call/notes WB868
call/id#!$> args):
ContentVal&es res&lt#new ContentValues():

A.move+o'irst():

if (A.is&fterLast()) 4
res&lt.put(col&mnsP%Q> '1):
res&lt.put(col&mnsP1Q> (String)n&ll):
?
else 4
res&lt.put(col&mnsP%Q> A.getInt(%)):
res&lt.put(col&mnsP1Q> A.getString(1)):
?

A.close():

ret&rn(res&lt):
-2%
?
?:

class Call5l&s3dapter extends C&rsor3dapter 4
Calllus&dapter(C&rsor c) 4
s&per(Join7emo.t-is> c):
?

02verride
p&blic void bindView(View row> Context ctxt>
C&rsor c) 4
ViewWrapper wrapper#(ViewWrapper)row.get+ag():

wrapper.update(c):
?

02verride
p&blic View newView(Context ctxt> C&rsor c>
ViewGro&p parent) 4
*a+o&tInflater inflater#getLayoutInflater():

View row#inflater.inflate(6.la+o&t.row> n&ll):
ViewWrapper wrapper#new View,rapper(row):

row.set+ag(wrapper):
wrapper.update(c):

ret&rn(row):
?
?
class ViewWrapper 4
View base:
<extView n&mber#n&ll:
<extView d&ration#n&ll:
<extView time#n&ll:
ImageView icon#n&ll:

View,rapper(View base) 4
t-is.base#base:
?

<extView get-umber() 4
if (n&mber##n&ll) 4
n&mber#(<extView)base.findViewById(6.id.n&mber):
?

ret&rn(n&mber):
?

<extView get"uration() 4
if (d&ration##n&ll) 4
d&ration#(<extView)base.findViewById(6.id.d&ration):
?
-2.

ret&rn(d&ration):
?

<extView get+ime() 4
if (time##n&ll) 4
time#(<extView)base.findViewById(6.id.time):
?

ret&rn(time):
?

ImageView getIcon() 4
if (icon##n&ll) 4
icon#(ImageView)base.findViewById(6.id.note):
?

ret&rn(icon):
?

void update(C&rsor c) 4
get-umber().set+e(t(c.getString(c.getColumnInde((Call*og.Calls.=D9;86))):
get+ime().set+e(t(K2693<.format(c.getInt(c.getColumnInde((Call*og.Calls.73
<8)))):
get"uration().set+e(t(c.getString(c.getColumnInde((Call*og.Calls.7D63<I2=)
)1$ seconds$):

String note#c.getString(c.getColumnInde((=2<8)):

if (noteN#n&ll UU note.lengt!())%) 4
getIcon().setVisibility(View.VISI;*8):
?
else 4
getIcon().setVisibility(View.G2=8):
?
?
?
?
When the user %li%ks on a ro>, epening on >hether there is a note, >e
either spa>n a =ote8ditor &to %reate a ne> note' or a =ote3ctivit+ &to vie>
an e;isting note'. .n a real implementation o$ this $un%tionality, o$ %ourse,
>e >oul allo> users to eit e;isting notes, elete notes, an the like, all o$
>hi%h is skippe in this simpli$ie sample appli%ation.
,isually, the a%tivity oes not look like mu%h, but you >ill see the note i%on
on %alls %ontaining notes &>ith some phone numbers smuge $or priva%y'*
-2$
!igure $6/ The BoinCursor sample application* sho)ing one call )ith a note
-20
CHAPTER 11
=andling System <vents
.$ you have ever looke at the list o$ available Intent a%tions in the #@K
o%umentation $or the Intent %lass, you >ill see that there are lots o$
possible a%tions.
Lots an lots an lots o$ possible a%tions.
5here are even a%tions that are not liste in that spot in the o%umentation,
but are s%attere throughout the rest o$ the #@K o%umentation.
5he vast maLority o$ these you >ill never raise yoursel$. .nstea, they are
broa%ast by Anroi, to signi$y %ertain system events that have o%%urre
an that you might >ant to take note o$, i$ they a$$e%t the operation o$ your
appli%ation.
5his %hapter e;amines a $e> o$ these, to give you the sense o$ >hat is
possible an ho> to make use o$ these sorts o$ events.
'et 8oving* !irst Thing
A popular re<uest is to have a servi%e get %ontrol >hen the evi%e is
po>ere on.
-23
5his is oable but some>hat angerous, in that too many on3boot re<uests
slo> o>n the evi%e startup an may make things sluggish $or the user.
Moreover, the more servi%es that are running all the time, the >orse the
evi%e per$orman%e >ill be.
A better pattern is to get %ontrol on boot to arrange $or a servi%e to o
something perioi%ally using the 3larm9anager or via other system events. .n
this se%tion, >e >ill e;amine the on3boot portion o$ the problem M in the
ne;t %hapter, >e >ill investigate 3larm9anager an ho> it %an keep servi%es
a%tive yet not ne%essarily resient in memory all the time.
The Permission
.n orer to be noti$ie >hen the evi%e has %omplete is system boot
pro%ess, you >ill nee to re<uest the 68C8IV8/;22</C295*8<87 permission.
Without this, even i$ you arrange to re%eive the boot broa%ast .ntent, it
>ill not be ispat%he to your re%eiver.
As the Anroi o%umentation es%ribes it*
Thou"h holdin" this permission does not hae any security
implications$ it can hae a ne"atie impact on the user e%pe&
rience by increasin" the amount o' time it takes the system
to start and allowin" applications to hae themseles run&
nin" without the user bein" aware o' them. As such$ you
must e%plicitly declare your use o' this 'acility to make that
isible to the user.
The Receiver Element
5here are t>o >ays you %an re%eive a broa%ast Intent. Gne is to use
register6eceiver() $rom an e;isting 3ctivit+, Service, or Content5rovider.
5he other is to register your interest in the Intent in the mani$est in the
$orm o$ a receiver) element*
-24
pac.age#$com.commonsware.android.s+sevents.boot$
&ses'permission android,name#$android.permission.68C8IV8/;22</C295*8<87$ /)
receiver android,name#$.2n;oot6eceiver$)
intent'filter)
action android,name#$android.intent.action.;22</C295*8<87$ /)
/intent'filter)
/receiver)
/application)
/manifest)
5he above 3ndroid9anifest.xml, $rom the S+stem8vents/2n;oot sample
proLe%t, sho>s that >e have registere a broa%ast re%eiver name
2n;oot6eceiver, set to be given %ontrol >hen the
android.intent.action.;22</C295*8<87 .ntent is broa%ast.
.n this %ase, >e have no %hoi%e but to implement our re%eiver this >ay M by
the time any o$ our other %omponents &e.g., an 3ctivit+' >ere to get %ontrol
an be able to %all register6eceiver(), the ;22</C295*8<87 Intent >ill be
long gone.
The Receiver $mplementation
0o> that >e have tol Anroi that >e >oul like to be noti$ie >hen the
boot has %omplete, an given that >e have been grante permission to o
so by the user, >e no> nee to a%tually o something to re%eive the .ntent.
5his is a simple matter o$ %reating a ;roadcast6eceiver, su%h as seen in the
2n;ootCompleted implementation sho>n belo>*
pac.age com.commonsware.android.s+sevents.boot:
import android.content.;roadcast6eceiver:
p&blic class 2n;oot6eceiver extends ;roadcast6eceiver 4
02verride
p&blic void onReceive(Context context> Intent intent) 4
*og.d($2n;oot6eceiver$> $Bi> 9omN$):
-25
?
?
A ;roadcast6eceiver is not a Context, an so it gets passe a suitable Context
obLe%t in on6eceive() to use $or a%%essing resour%es an the like. 5he
on6eceive() metho also is passe the Intent that %ause our
;roadcast6eceiver to be %reate, in %ase there are Ie;trasI >e nee to pull
out &none in this %ase'.
.n on6eceive(), >e %an o >hatever >e >ant, subLe%t to some limitations*
-. We are not a Context, like an 3ctivit+, so >e %annot moi$y a ". or
anything su%h as that
2. .$ >e >ant to o anything signi$i%ant, it is better to elegate that
logi% to a servi%e that >e start $rom here &e.g., %alling startService()
on the supplie Context' rather than a%tually oing it here, sin%e
;roadcast6eceiver implementations nee to be $ast
?. We %annot start any ba%kgroun threas, ire%tly or inire%tly,
sin%e the ;roadcast6eceiver gets is%are as soon as on6eceive()
returns
.n this %ase, >e simply log the $a%t that >e got %ontrol. .n the ne;t %hapter,
>e >ill see >hat else >e %an o at boot time, to ensure one o$ our servi%es
gets %ontrol later on as neee.
5o test this, install it on an emulator &or evi%e', shut o>n the emulator,
then restart it.
+ Sense a Connection Bet)een 1s///
8enerally speaking, Anroi appli%ations o not %are >hat sort o$ .nternet
%onne%tion is being use M ?8, 8!R#, Wi(i, lots o$ traine %arrier pigeons,
or >hatever. #o long as there is an .nternet %onne%tion, the appli%ation is
happy.
-36
#ometimes, though, you may spe%i$i%ally >ant Wi(i. 5his >oul be true i$
your appli%ation is ban>ith3intensive an you >ant to ensure that,
shoul Wi(i stop being available, you %ut ba%k on your >ork so as not to
%onsume too mu%h ?8Q8!R# ban>ith, >hi%h is usually subLe%t to some
sort o$ %ap or metering.
5here is an android.net.wifi.WIKI/S<3<8/CB3=G87 Intent that >ill be
broa%ast, as the name suggests, >henever the state o$ the Wi(i %onne%tion
%hanges. Dou %an arrange to re%eive this broa%ast an take appropriate
steps >ithin your appli%ation.
5his Intent re<uires no spe%ial permission, unlike the ;22</C295*8<87 .ntent
$rom the previous se%tion. )en%e, all you nee to o is register a
;roadcast6eceiver $or android.net.wifi.WIKI/S<3<8/CB3=G87, either via
register6eceiver(), or via the receiver) element in 3ndroid9anifest.xml,
su%h as the one sho>n belo>, $rom the S+stem8vents/2nWiKiC-ange sample
proLe%t*
pac.age#$com.commonsware.android.s+sevents.wifi$
receiver android,name#$.2nWiKiC-ange6eceiver$)
intent'filter)
action android,name#$android.net.wifi.WIKI/S<3<8/CB3=G87$ /)
/intent'filter)
/receiver)
/application)
/manifest)
All >e o in the mani$est is tell Anroi to %reate an 2nWiKiC-ange6eceiver
obLe%t >hen a android.net.wifi.WIKI/S<3<8/CB3=G87 Intent is broa%ast, so
the re%eiver %an o something use$ul.
.n the %ase o$ 2nWiKiC-ange6eceiver, it e;amines the value o$ the
8W<63/WIKI/S<3<8 Ie;traI in the supplie Intent an logs an appropriate
message*
-3-
pac.age com.commonsware.android.s+sevents.wifi:
import android.net.wifi.Wifi9anager:
p&blic class 2nWiKiC-ange6eceiver extends ;roadcast6eceiver 4
02verride
int state#intent.getIntE(tra(Wifi9anager.8W<63/WIKI/S<3<8> '1):
String msg#n&ll:

switc- (state) 4
case Wifi9anager.WIKI/S<3<8/7IS3;*87,
msg#$is disabled$:
brea.:

case Wifi9anager.WIKI/S<3<8/7IS3;*I=G,
msg#$is disabling$:
brea.:

case Wifi9anager.WIKI/S<3<8/8=3;*87,
msg#$is enabled$:
brea.:

case Wifi9anager.WIKI/S<3<8/8=3;*I=G,
msg#$is enabling$:
brea.:

case Wifi9anager.WIKI/S<3<8/D=V=2W= ,
msg#$-as an error$:
brea.:

defa&lt,
msg#$is acting strangel+$:
brea.:
?

if (msgN#n&ll) 4
*og.d($2nWiKiC-anged$> $WiKi $1msg):
?
?
?
5he 8W<63/WIKI/S<3<8 Ie;traI tells you >hat the state has be%ome &e.g., >e
are no> isabling or are no> isable', so you %an take appropriate steps in
your appli%ation.
-3%
0ote that, to test this, you >ill nee an a%tual Anroi evi%e, as the
emulator oes not spe%i$i%ally support simulating Wi(i %onne%tions.
!eeling 9rained
Gne theme >ith system events is to use them to help make your users
happier by reu%ing your impa%ts on the evi%e >hile the evi%e is not in a
great state. .n the pre%eing se%tion, >e sa> ho> you %oul $in out >hen
Wi(i >as isable, so you might not use as mu%h ban>ith >hen on
?8Q8!R#. )o>ever, not every appli%ation uses so mu%h ban>ith as to
make this optimiCation >orth>hile.
)o>ever, most appli%ations are impa%te by battery li$e. @ea batteries run
no apps.
#o >hether you are implementing a battery monitor or simply >ant to
is%ontinue ba%kgroun operations >hen the battery gets lo>, you may
>ish to $in out ho> the battery is oing.
5here is an 3C<I2=/;3<<86C/CB3=G87 Intent that gets broa%ast as the battery
status %hanges, both in terms o$ %harge &e.g., 20P %harge' an %harging
&e.g., the evi%e is no> plugge into AC po>er'. Dou simply nee to register
to re%eive this Intent >hen it is broa%ast, then take appropriate steps.
Gne o$ the limitations o$ 3C<I2=/;3<<86C/CB3=G87 is that you have to use
register6eceiver() to set up a ;roadcast6eceiver to get this Intent >hen
broa%ast. Dou %annot use a mani$est3e%lare re%eiver as sho>n in the
pre%eing t>o se%tions.
.n S+stem8vents/2n;atter+, you >ill $in a layout %ontaining a 5rogress;ar, a
<extView, an an ImageView, to serve as a battery monitor*
-3.
)
5rogress;ar android,id#$01id/bar$
st+le#$!android,attr/progress;arSt+leBoriIontal$
android,la+o&t/-eig-t#$wrap/content$ /)
*inear*a+o&t
)
<extView android,id#$01id/level$
android,textSiIe#$1Xpt$
/)
ImageView android,id#$01id/stat&s$
/)
/*inear*a+o&t)
/*inear*a+o&t)
5his layout is use by a ;atter+9onitor a%tivity, >hi%h registers to re%eive
the 3C<I2=/;3<<86C/CB3=G87 Intent in on6es&me() an unregisters in
on5a&se()*
pac.age com.commonsware.android.s+sevents.batter+:
import android.content.IntentKilter:
import android.os.;atter+9anager:
import android.widget.5rogress;ar:
import android.widget.ImageView:
p&blic class ;atter+9onitor extends 3ctivit+ 4
private 5rogress;ar bar#n&ll:
private ImageView stat&s#n&ll:
private <extView level#n&ll:

02verride

bar#(5rogress;ar)findViewById(6.id.bar):
-3$
stat&s#(ImageView)findViewById(6.id.stat&s):
level#(<extView)findViewById(6.id.level):
?

02verride
s&per.onResume():

registerReceiver(on;atter+C-anged>
new Intent'ilter(Intent.3C<I2=/;3<<86C/CB3=G87)):
?

02verride
s&per.onause():

unregisterReceiver(on;atter+C-anged):
?

;roadcast6eceiver on;atter+C-anged#new BroadcastReceiver() 4
int pct#1%%Mintent.getIntE(tra($level$> 1)/intent.getIntE(tra($scale$> 1):

bar.setrogress(pct):
level.set+e(t(String.value$f(pct)):

switc-(intent.getIntE(tra($stat&s$> '1)) 4
case ;atter+9anager.;3<<86C/S<3<DS/CB36GI=G,
stat&s.setImageResource(6.drawable.c-arging):
brea.:

case ;atter+9anager.;3<<86C/S<3<DS/KD**,
int pl&gged#intent.getIntE(tra($pl&gged$> '1):

if (pl&gged##;atter+9anager.;3<<86C/5*DGG87/3C YY
pl&gged##;atter+9anager.;3<<86C/5*DGG87/DS;) 4
stat&s.setImageResource(6.drawable.f&ll):
?
else 4
stat&s.setImageResource(6.drawable.&npl&gged):
?
brea.:

defa&lt,
stat&s.setImageResource(6.drawable.&npl&gged):
brea.:
?
?
?:
?
5he key to 3C<I2=/;3<<86C/CB3=G87 is in the Ie;trasI. Many Ie;trasI are
pa%kage in the Intent, to es%ribe the %urrent state o$ the battery, su%h as*
-30
-ealt-, >hi%h shoul generally be ;3<<86C/B83*<B/G227
level, >hi%h is the proportion o$ battery li$e remaining as an
integer, spe%i$ie on the s%ale es%ribe by the s%ale Ie;traI
pl&gged, >hi%h >ill ini%ate i$ the evi%e is plugge into AC po>er
&;3<<86C/5*DGG87/3C' or "#/ po>er &;3<<86C/5*DGG87/DS;'
scale, >hi%h ini%ates the ma;imum possible value o$ level &e.g.,
1%%, ini%ating that level is a per%entage o$ %harge remaining'
stat&s, >hi%h >ill tell you i$ the battery is %harging
&;3<<86C/S<3<DS/CB36GI=G', $ull &;3<<86C/S<3<DS/KD**', or is%harging
&;3<<86C/S<3<DS/7ISCB36GI=G'
tec-nolog+, >hi%h ini%ates >hat sort o$ battery is installe &e.g.,
$*i'Ion$'
temperat&re, >hi%h tells you ho> >arm the battery is, in tenths o$ a
egree Celsius &e.g., E1J is 2-.? egrees Celsius'
voltage, ini%ating the %urrent voltage being elivere by the
battery, in millivolts
.n the %ase o$ ;atter+9onitor, >hen >e re%eive an 3C<I2=/;3<<86C/CB3=G87
.ntent, >e o three things*
-. We %ompute the per%entage o$ battery li$e remaining, by iviing
the level by the s%ale
2. We upate the 5rogress;ar an <extView to isplay the battery li$e as
a per%entage
?. We isplay an i%on, >ith the i%on sele%tion epening on >hether
>e are %harging &stat&s is ;3<<86C/S<3<DS/CB36GI=G', $ull but on the
%harger &stat&s is ;3<<86C/S<3<DS/KD** an pl&gged is
;3<<86C/5*DGG87/3C or ;3<<86C/5*DGG87/DS;', or are not plugge in
5his only really >orks on a evi%e, >here you %an plug an unplug it, plus
get a varying %harge level*
-32
!igure $-/ The Battery8onitor application
-33
CHAPTER 12
1sing System Services
Anroi o$$ers a number o$ system servi%es, usually obtaine by
getS+stemService() $rom your 3ctivit+, Service, or other Context. 5hese are
your gate>ay to all sorts o$ %apabilities, $rom settings to volume to Wi(i.
5hroughout the %ourse o$ this book an its %ompanion, >e have seen
several o$ these system servi%es. .n this %hapter, >e >ill take a look at others
that may be o$ value to you in builing %ompelling Anroi appli%ations.
'et :larmed
A %ommon <uestion >hen oing Anroi evelopment is I>here o . set
up cron LobsJI
5he cron utility M popular in Linu; M is a >ay o$ s%heuling >ork to be one
perioi%ally. Dou tea%h cron >hat to run an >hen to run it &e.g., >eekays
at noon', an cron takes %are o$ the rest. #in%e Anroi has a Linu; kernel
at its heart, one might think that cron might literally be available.
While cron itsel$ is not, Anroi oes have a system servi%e name
3larm9anager >hi%h $ills a similar role. Dou give it a 5endingIntent an a time
&an optional a perio $or repeating' an it >ill $ire o$$ the Intent as
neee. /y this me%hanism, you %an get a similar e$$e%t to cron.
5here is one small %at%h, though* Anroi is esigne to run on mobile
evi%es, parti%ularly ones po>ere by all3too3tiny batteries. .$ you >ant
-35
your perioi% tasks to be run even i$ the evi%e is IasleepI, you >ill nee to
take a $air number o$ e;tra steps, mostly stemming aroun the %on%ept o$
the Wa.e*oc..
Concept o* a&e"oc&s
Most o$ the time in Anroi, you are eveloping %oe that >ill run >hile
the user is a%tually using the evi%e. A%tivities, $or e;ample, only really
make sense >hen the evi%e is $ully a>ake an the user is tapping on the
s%reen or keyboar.
!arti%ularly >ith s%heule ba%kgroun tasks, though, you nee to bear in
min that the evi%e >ill eventually Igo to sleepI. .n $ull sleep moe, the
isplay, main C!", an keyboar are all po>ere o$$, to ma;imiCe battery
li$e. Gnly on a lo>3level system event, like an in%oming phone %all, >ill
anything >ake up.
Another thing that >ill partially >ake up the phone is an Intent raise by
the 3larm9anager. #o long as broa%ast re%eivers are pro%essing that Intent,
the 3larm9anager ensures the C!" >ill be running &though the s%reen an
keyboar are still o$$'. Gn%e the broa%ast re%eivers are one, the
3larm9anager lets the evi%e go ba%k to sleep.
Dou %an a%hieve the same e$$e%t in your %oe via a Wa.e*oc., obtaine via the
5ower9anager system servi%e. When you a%<uire a Ipartial Wa.e*oc.I
&536<I3*/W3V8/*2CV', you prevent the C!" $rom going ba%k to sleep until
you release sai Wa.e*oc.. /y proper use o$ a partial Wa.e*oc., you %an ensure
the C!" >ill not get shut o$$ >hile you are trying to o ba%kgroun >ork,
>hile still allo>ing the evi%e to sleep most o$ the time, in bet>een alarm
events.
)o>ever, using a Wa.e*oc. is a bit tri%ky, parti%ularly >hen responing to
an alarm Intent, as >e >ill see in the ne;t $e> se%tions.
-46
(chedulin! Alarms
5he $irst step to %reating a cron >orkalike is to arrange to get %ontrol >hen
the evi%e boots. A$ter all, the cron aemon starts on boot as >ell, an >e
have no other >ay o$ ensuring that our ba%kgroun tasks start $iring a$ter a
phone is reset.
We sa> ho> to o that in a previous %hapter M set up an
68C8IV8/;22</C295*8<87 ;roadcast6eceiver, >ith appropriate permissions.
)ere, $or e;ample, is the 3ndroid9anifest.xml $rom S+stemServices/3larm*
pac.age#$com.commonsware.android.s+ssvc.alarm$
&ses'permission android,name#$android.permission.68C8IV8/;22</C295*8<87$ /)
&ses'permission android,name#$android.permission.W3V8/*2CV$ /)
receiver android,name#$.2n;oot6eceiver$)
intent'filter)
action android,name#$android.intent.action.;22</C295*8<87$ /)
/intent'filter)
/receiver)
receiver android,name#$.2n3larm6eceiver$)
/receiver)
service android,name#$.3ppService$)
/service)
/application)
/manifest)
We ask $or an 2n;oot6eceiver to get %ontrol >hen the evi%e starts up, an it
is in 2n;oot6eceiver that >e s%heule our re%urring alarm*
pac.age com.commonsware.android.s+ssvc.alarm:
import android.app.3larm9anager:
import android.app.5endingIntent:
p&blic class 2n;oot6eceiver extends ;roadcast6eceiver 4
private static final int 586I27#J%%%%%: // H min&tes

-4-
02verride
3larm9anager
mgr#(3larm9anager)context.getSystemService(Context.3*369/S86VIC8):
Intent i#new Intent(context> 2n3larm6eceiver.class):
5endingIntent pi#5endingIntent.getBroadcast(context> %>
i> %):

mgr.setRepeating(3larm9anager.8*35S87/683*<I98/W3V8D5>
S+stemCloc..elapsedRealtime()>
586I27>
pi):
?
?
We get the 3larm9anager via getS+stemService(), %reate an Intent re$eren%ing
another ;roadcast6eceiver &2n3larm6eceiver', >rap that Intent in a
5endingIntent, an tell the 3larm9anager to set up a repeating alarm via
set6epeating(). /y saying >e >ant a 8*35S87/683*<I98/W3V8D5 alarm, >e
ini%ate that >e >ant the alarm to >ake up the evi%e &even i$ it is asleep'
an to e;press all times using the time base use by
S+stemCloc..elapsed6ealtime(). .n this %ase, our alarm is set to go o$$ every
$ive minutes.
5his >ill %ause the 3larm9anager to raise our Intent imminently, an every
$ive minutes therea$ter.
Arran!in! *or or& 8rom Alarms
When an alarm goes o$$, our 2n3larm6eceiver >ill get %ontrol. .t nees to
arrange $or a servi%e &in this %ase, name 3ppService' to o its >ork in the
ba%kgroun, but then release %ontrol <ui%kly M on6eceive() %annot take very
mu%h time.
)ere is the tiny implementation o$ 2n3larm6eceiver $rom
S+stemServices/3larm*
-4%
p&blic class 2n3larm6eceiver extends ;roadcast6eceiver 4
02verride
Wa.ef&lIntentService.acquireStaticLoc)(context):

context.startService(new Intent(context> 3ppService.class)):
?
?
While there is very little %oe in this %lass, it is merely e%eptively simple.
(irst, >e a%<uire a Wa.e*oc. $rom our 3ppService7s parent %lass,
Wa.ef&lIntentService via ac@&ireStatic*oc.(), sho>n belo>*
p&blic static void acquireStaticLoc)(Context context) 4
getLoc)(context).acquire():
?
s+nc-roniIed private static 5ower9anager.Wa.e*oc. getLoc)(Context context) 4
if (loc.Static##n&ll) 4
5ower9anager
mgr#(5ower9anager)context.getSystemService(Context.52W86/S86VIC8):
loc.Static#mgr.new,a)eLoc)(5ower9anager.536<I3*/W3V8/*2CV>
*2CV/=398/S<3<IC):
loc.Static.setReferenceCounted(tr&e):
?
ret&rn(loc.Static):
?
5he get*oc.() implementation laCy3%reates our Wa.e*oc. by getting the
5ower9anager, %reating a ne> partial Wa.e*oc., an setting it to be re$eren%e
%ounte &meaning i$ it is a%<uire several times, it takes a %orresponing
number o$ release() %alls to truly release the lo%k'. .$ >e have alreay
retrieve the Wa.e*oc. in a previous invo%ation, >e reuse the same lo%k.
/a%k in 2n3larm6eceiver, up until this point, the C!" >as running be%ause
3larm9anager hel a partial Wa.e*oc.. 0o>, the C!" is running be%ause both
3larm9anager and Wa.ef&lIntentService hol a partial Wa.e*oc..
5hen, 2n3larm6eceiver starts the 3ppService instan%e &remember*
ac@&ireStatic*oc.() >as a static metho' an e;its. 0otably,
-4.
2n3larm6eceiver oes not release the Wa.e*oc. it a%<uire. 5his is important,
as >e nee to ensure that the servi%e %an get its >ork one >hile the C!" is
running. )a >e release the Wa.e*oc. be$ore returning, it is possible that
the evi%e >oul $all ba%k asleep be$ore our servi%e ha a %han%e to a%<uire
a $resh Wa.e*oc.. 5his is one o$ the keys o$ using Wa.e*oc. su%%ess$ully M as
neee, use overlapping Wa.e*oc. instan%es to ensure %onstant %overage as
you pass $rom %omponent to %omponent.
0o>, our servi%e >ill start up an be able to o something, >hile the C!" is
running ue to our a%<uire Wa.e*oc..
(tayin! A+a&e At or&
#o, 3ppService >ill no> get %ontrol, uner an a%tive Wa.e*oc.. At minimum,
our servi%e >ill be %alle via onStart(), an possibly also onCreate() i$ the
servi%e ha been previously stoppe. Gur mission is to o our >ork an
release the Wa.e*oc..
#in%e servi%es shoul not o long3running tasks in onStart(), >e %oul $ork
a <-read, have it o the >ork in the ba%kgroun, then have it release the
Wa.e*oc.. 0ote that >e %annot release the Wa.e*oc. in onStart() in this %ase
M Lust be%ause >e have a ba%kgroun threa oes not mean the evi%e >ill
keep the C!" running.
5here are issues >ith $orking a <-read $or every in%oming re<uest, though*
.$ the >ork neee to be one sometimes takes longer than the
alarm perio, >e %oul >in up >ith many ba%kgroun threas,
>hi%h is ine$$i%ient. .t also means our Wa.e*oc. management gets
mu%h tri%kier, sin%e >e >ill not have release the Wa.e*oc. be$ore
the alarm tries to ac@&ire() it again.
.$ >e also are invoke in onStart() via some $oregroun a%tivity, >e
might >in up >ith many more bits o$ >ork to be one, again
%ausing %on$usion >ith our Wa.e*oc. an perhaps slo>ing things
o>n ue to too many ba%kgroun threas.
-4$
Anroi has a %lass that helps >ith parts o$ this, IntentService. .t arranges
$or a >ork <ueue o$ inboun Intents M rather than overriing onStart(), you
overrie onBandleIntent(), >hi%h is %alle $rom a ba%kgroun threa.
Anroi hanles all the etails o$ shutting o>n your servi%e >hen there is
no more outstaning >ork, managing the ba%kgroun threa, an so on.
)o>ever, IntentService oes not o anything to hol a Wa.e*oc..
)en%e, this sample proLe%t implements Wa.ef&lIntentService as a sub%lass
o$ IntentService. Wa.ef&lIntentService hanles most o$ the Wa.e*oc. logi%,
so 3ppService &inheriting $rom Wa.ef&lIntentService' %an Lust $o%us on the
>ork it nees to o.
Wa.ef&lIntentService hanles the Wa.e*oc. logi% in $our %omponents*
-. .t o$$ers the publi% stati% metho ac@&ireStatic*oc.(), >hi%h nees
to be %alle by >hoever is %alling startService() on our
Wa.ef&lIntentService sub%lass.
2. .n onCreate(), it %reates &but oes not a%<uire' another Wa.e*oc..
5he stati% Wa.e*oc. >ill be use to keep the evi%e a>ake >hile the
;roadcast6eceiver &or >hoever else is %alling startService()' starts
up the servi%e. 5he lo%al Wa.e*oc. >ill be use to keep the evi%e
a>ake so long as there is >ork to be one.
?. .n onStart(), it a%<uires the lo%al Wa.e*oc., lets the super%lass o its
>ork to en<ueue the supplie .ntent $or later pro%essing, then
releases the stati% Wa.e*oc.. At this point, the evi%e still must
remain a>ake, be%ause even though the 3larm9anager Wa.e*oc. &use
uring the %all to on6eceive() in our ;roadcast6eceiver' is release,
an our stati% Wa.e*oc. is release, our lo%al Wa.e*oc. is still hel.
=. .n onBandleIntent(), it releases the lo%al Wa.e*oc.. #in%e this
Wa.e*oc. is re$eren%e3%ounte, the lo%k >ill only $ully release on%e
every Intent en<ueue by onStart() has been hanle by
onBandleIntent().
)ere is the $ull implementation o$ Wa.ef&lIntentService*
-40
import android.app.3larm9anager:
import android.app.5endingIntent:
import android.app.IntentService:
import android.os.I;inder:
import android.os.5ower9anager:
p&blic class Wa.ef&lIntentService extends IntentService 4
p&blic static final String
*2CV/=398/S<3<IC#$com.commonsware.android.s+ssvc.3ppService.Static$:
p&blic static final String
*2CV/=398/*2C3*#$com.commonsware.android.s+ssvc.3ppService.*ocal$:
private static 5ower9anager.Wa.e*oc. loc.Static#n&ll:
private 5ower9anager.Wa.e*oc. loc.*ocal#n&ll:

p&blic static void acquireStaticLoc)(Context context) 4
getLoc)(context).acquire():
?

s+nc-roniIed private static 5ower9anager.Wa.e*oc. getLoc)(Context context) 4
if (loc.Static##n&ll) 4
5ower9anager
mgr#(5ower9anager)context.getSystemService(Context.52W86/S86VIC8):

loc.Static#mgr.new,a)eLoc)(5ower9anager.536<I3*/W3V8/*2CV>
*2CV/=398/S<3<IC):
loc.Static.setReferenceCounted(tr&e):
?

ret&rn(loc.Static):
?

p&blic ,a)efulIntentService(String name) 4
s&per(name):
?

p&blic void onCreate() 4
s&per.onCreate():

5ower9anager mgr#(5ower9anager)getSystemService(Context.52W86/S86VIC8):

loc.*ocal#mgr.new,a)eLoc)(5ower9anager.536<I3*/W3V8/*2CV>
*2CV/=398/*2C3*):
loc.*ocal.setReferenceCounted(tr&e):
?

02verride
p&blic void onStart(Intent intent> final int startId) 4
loc.*ocal.acquire():

s&per.onStart(intent> startId):
-42

getLoc)(t-is).release():
?

02verride
protected void on*andleIntent(Intent intent) 4
loc.*ocal.release():
?
?
With all that behin us, 3ppService nee only implement onBandleIntent(),
o its >ork, an then %hain up>ar to the Wa.ef&lIntentService7s
implementation o$ onBandleIntent()*
import android.os.8nvironment:
import Aava.io.;&fferedWriter:
import Aava.io.Kile:
import Aava.io.KileWriter:
import Aava.io.I28xception:
import Aava.&til.7ate:
p&blic class 3ppService extends Wa.ef&lIntentService 4
p&blic &ppService() 4
s&per($3ppService$):
?
02verride
protected void on*andleIntent(Intent intent) 4
Kile log#new 'ile(8nvironment.getE(ternalStorage"irectory()>
$3larm*og.txt$):

tr+ 4
;&fferedWriter o&t#new Buffered,riter(new
'ile,riter(log.get&bsoluteat!()> tr&e)):

o&t.write(new "ate().toString()):
o&t.write($Zn$):
o&t.close():
?
catc- (I28xception e) 4
*og.e($3ppService$> $8xception appending to log file$> e):
?

s&per.on*andleIntent(intent):
?
?
-43
5he I$ake >orkI being one by this 3ppService is simply logging the $a%t
that >ork neee to be one to a log $ile on the #@ %ar.
0ote that i$ you attempt to buil an run this proLe%t that you >ill nee an
#@ %ar in the evi%e &or %ar image atta%he to your emulator'.
Setting <xpectations
.$ you have an Anroi evi%e, you probably have spent some time in the
#ettings appli%ation, t>eaking your evi%e to >ork ho> you >ant M
ringtones, Wi(i settings, "#/ ebugging, et%. Many o$ those settings are
also available via Settings %lass &in the android.provider pa%kage', an
parti%ularly the Settings.S+stem an Settings.Sec&re publi% inner %lasses.
Basic (ettin!s
Settings.S+stem allo>s you to get an, >ith the W6I<8/S8<<I=GS permission,
alter these settings. As one might e;pe%t, there are a series o$ type getter
an setter methos on Settings.S+stem, ea%h taking a key as a parameter.
5he keys are %lass %onstants, su%h as*
I=S<3**/=2=/936V8</355S to %ontrol >hether you %an install
appli%ations on a evi%e $rom outsie o$ the Anroi Market
*2CV/53<<86=/8=3;*87 to %ontrol >hether the user nees to enter a
lo%k pattern to enable use o$ the evi%e
*2CV/53<<86=/VISI;*8 to %ontrol >hether the lo%k pattern is ra>n
on3s%reen as it is s>ipe by the user, or i$ the s>ipes are IinvisibleI
5he S+stemServices/Settings proLe%t has a SettingsSetter sample
appli%ation that isplays a %he%klist*
*istView xmlns,android#$-ttp,//sc-emas.android.com/ap./res/android$
/)
-44
!igure $%/ The SettingsSetter application
5he %he%klist itsel$ is $ille >ith a $e> ;ooleanSetting obLe%ts, >hi%h map a
isplay name >ith a Settings.S+stem key*
static class ;ooleanSetting 4
String .e+:
String displa+=ame:
BooleanSetting(String .e+> String displa+=ame) 4
t-is..e+#.e+:
t-is.displa+=ame#displa+=ame:
?
02verride
p&blic String toString() 4
ret&rn(displa+=ame):
?
boolean isC!ec)ed(Content6esolver cr) 4
tr+ 4
int val&e#Settings.S+stem.getInt(cr> .e+):
ret&rn(val&eN#%):
?
catc- (Settings.Setting=otKo&nd8xception e) 4
*og.e($SettingsSetter$> e.get%essage()):
?
ret&rn(false):
-45
?
void setC!ec)ed(Content6esolver cr> boolean val&e) 4
Settings.S+stem.putInt(cr> .e+> (val&e ! 1 , %)):
?
?
5hree su%h settings are put in the list, an as the %he%kbo;es are %he%ke
an un%he%ke, the values are passe along to the settings themselves*
02verride
getListView().setC!oice%ode(*istView.CB2IC8/9278/9D*<I5*8):
setList&dapter(new &rray&dapter(t-is>
android.6.la+o&t.simple/list/item/m&ltiple/c-oi
ce>
settings)):
Content6esolver cr#getContentResolver():
for (int i#%:isettings.si.e():i11) 4
;ooleanSetting s#settings.get(i):
getListView().setItemC!ec)ed(i> s.isC!ec)ed(cr)):
?
?
02verride
protected void onListItemClic)(*istView l> View v>
int position> long id) 4
s&per.onListItemClic)(l> v> position> id):
;ooleanSetting s#settings.get(position):
s.setC!ec)ed(getContentResolver()>
l.isItemC!ec)ed(position)):
?
5he SettingsSetter a%tivity also has an option menu %ontaining $our items*
men& xmlns,android#$-ttp,//sc-emas.android.com/ap./res/android$)
item android,id#$01id/app$
android,title#$3pplication$
android,icon#$0android,drawable/ic/men&/manage$ /)
item android,id#$01id/sec&rit+$
android,title#$Sec&rit+$
android,icon#$0android,drawable/ic/men&/close/clear/cancel$ /)
-56
item android,id#$01id/wireless$
android,title#$Wireless$
android,icon#$0android,drawable/ic/men&/set/as$ /)
item android,id#$01id/all$
android,title#$3ll Settings$
android,icon#$0android,drawable/ic/men&/preferences$ /)
/men&)
5hese items %orrespon to $our a%tivity Intent values ienti$ie by the
Settings %lass*
men&3ctivities.put(6.id.app>
Settings.3C<I2=/355*IC3<I2=/S8<<I=GS):
men&3ctivities.put(6.id.sec&rit+>
Settings.3C<I2=/S8CD6I<C/S8<<I=GS):
men&3ctivities.put(6.id.wireless>
Settings.3C<I2=/WI68*8SS/S8<<I=GS):
men&3ctivities.put(6.id.all>
Settings.3C<I2=/S8<<I=GS):
When an option menu is %hosen, the %orresponing a%tivity is laun%he*
02verride
p&blic boolean on$ptionsItemSelected(9en&Item item) 4
String activit+#men&3ctivities.get(item.getItemId()):
if (activit+N#n&ll) 4
start&ctivity(new Intent(activit+)):
ret&rn(tr&e):
?
ret&rn(s&per.on$ptionsItemSelected(item)):
?
5his >ay, you have your %hoi%e o$ either ire%tly manipulating the settings
or merely making it easier $or users to get to the Anroi3supplie a%tivity
$or manipulating those settings.
(ecure (ettin!s
Dou >ill noti%e that i$ you use the above %oe an try %hanging the value o$
IAllo> non3Market app installsI, the %hange oes not Isti%kI M on%e you e;it
an reopen the appli%ation, the setting returns to its original state.
-5-
Moreover, i$ you use the #ettings appli%ation an e;amine the setting, it is
%lear that SettingsSetter is not a%tually %hanging that parti%ular setting.
Gn%e upon a time M Anroi -.- an earlier M it i.
0o>, though, that setting is one that Anroi eems Ise%ureI. 5he %onstant
has been move $rom Settings.S+stem to Settings.Sec&re, though the ol
%onstant is still there, $lagge as epre%ate.
5hese so3%alle Ise%ureI settings are one that Anroi oes not allo>
appli%ations to %hange. 0o permission resolves this problem. 5he only
option is to isplay the o$$i%ial #ettings a%tivity an let the user %hange the
setting.
Can 7ou =ear 8e @o)F ,G* =o) :bout @o)F
5he $an%ier the evi%e, the more %ompli%ate %ontrolling soun volume
be%omes.
Gn a simple M!? player, there is usually only one volume %ontrol. 5hat is
be%ause there is only one sour%e o$ soun* the musi% itsel$, playe through
speakers or heaphones.
.n Anroi, though, there are several sour%es o$ souns*
Ringing, to signi$y an in%oming %all
,oi%e %alls
Alarms, su%h as those raise by the Alarm Clo%k appli%ation
#ystem souns &error beeps, "#/ %onne%tion signal, et%.'
Musi%, as might %ome $rom the M!? player
Anroi allo>s the user to %on$igure ea%h o$ these volume levels separately.
"sually, the user oes this via the volume ro%ker buttons on the evi%e, in
the %onte;t o$ >hatever soun is being playe &e.g., >hen on a %all, the
-5%
volume buttons %hange the voi%e %all volume'. Also, there is a s%reen in the
Anroi #ettings appli%ation that allo>s you to %on$igure various volume
levels.
5he 3&dioService in Anroi allo>s you, the eveloper, to also %ontrol these
volume levels, $or all $ive IstreamsI &i.e., sour%es o$ soun'. .n the
S+stemServices/Vol&me proLe%t, >e %reate a Vol&miIer appli%ation that
isplays an moi$ies all $ive volume levels, reusing the 9eter >iget >e
%reate in an earlier %hapter.
Reusin! /eter
8iven that 9eter >as originally evelope in a separate proLe%t, >e ha to
o a $e> things to make it usable here.
(irst, >e ha to %opy over the layout &res/la+o&t/meter.xml', sour%e
&src/com/commonsware/android/widget/9eter.Aava', an t>o 7rawable
resour%es &res/drawable/incr.png an res/drawable/decr.png'. We then
move it all into the same pa%kage as everything else
&com.commonsware.android.s+ssvc.vol&me'.
5his, o$ %ourse, e$eats mu%h o$ the reusability. Gn%e better >iget reuse
moels be%ome apparent, e;pe%t upates to this book to %over them.
Attachin! /eters to ,olume (treams
8iven that >e have our 9eter >iget to >ork >ith, setting up 9eter >igets
to >ork >ith volume streams is $airly straight$or>ar.
(irst, >e nee to %reate a layout >ith a 9eter per stream*
<able*a+o&t xmlns,android#$-ttp,//sc-emas.android.com/ap./res/android$
xmlns,app#$-ttp,//sc-emas.android.com/ap./res/com.commonsware.android.s+ssvc.v
ol&me$
android,stretc-Col&mns#$1$
-5.
)
<able6ow
android,padding<op#$1%px$
android,padding;ottom#$E%px$)
<extView android,text#$3larm,$ /)
com.commonsware.android.s+ssvc.vol&me.9eter
android,id#$01id/alarm$
app,incr#$1$
app,decr#$1$
/)
/<able6ow)
<able6ow
<extView android,text#$9&sic,$ /)
android,id#$01id/m&sic$
app,incr#$1$
app,decr#$1$
/)
/<able6ow)
<able6ow
<extView android,text#$6ing,$ /)
android,id#$01id/ring$
app,incr#$1$
app,decr#$1$
/)
/<able6ow)
<able6ow
<extView android,text#$S+stem,$ /)
android,id#$01id/s+stem$
app,incr#$1$
app,decr#$1$
/)
/<able6ow)
<able6ow)
<extView android,text#$Voice,$ /)
android,id#$01id/voice$
app,incr#$1$
-5$
app,decr#$1$
/)
/<able6ow)
/<able*a+o&t)
5hen, >e nee to >ire up ea%h o$ those meters in the onCreate() $or
Vol&miIer*
9eter alarm#n&ll:
9eter m&sic#n&ll:
9eter ring#n&ll:
9eter s+stem#n&ll:
9eter voice#n&ll:
3&dio9anager mgr#n&ll:
02verride
mgr#(3&dio9anager)getSystemService(Context.3D7I2/S86VIC8):
alarm#(9eter)findViewById(6.id.alarm):
m&sic#(9eter)findViewById(6.id.m&sic):
ring#(9eter)findViewById(6.id.ring):
s+stem#(9eter)findViewById(6.id.s+stem):
voice#(9eter)findViewById(6.id.voice):
alarm.set+ag(3&dio9anager.S<6839/3*369):
m&sic.set+ag(3&dio9anager.S<6839/9DSIC):
ring.set+ag(3&dio9anager.S<6839/6I=G):
s+stem.set+ag(3&dio9anager.S<6839/SCS<89):
voice.set+ag(3&dio9anager.S<6839/V2IC8/C3**):
init%eter(alarm):
init%eter(m&sic):
init%eter(ring):
init%eter(s+stem):
init%eter(voice):
?
We use the tag $or ea%h 9eter to hol the ienti$ier $or the stream
asso%iate >ith that spe%i$i% 9eter. 5hat >ay, ea%h 9eter kno>s its stream.
.n init9eter(), >e set the appropriate siCe $or the 9eter bar via set9ax(), set
the initial value via set5rogress(), an >ire our in%rement an e%rement
events to the appropriate methos on Vol&me9anager*
-50
final int stream#((Integer)meter.get+ag()).intValue():

meter.set%a((mgr.getStream%a(Volume(stream)):
meter.setrogress(mgr.getStreamVolume(stream)):
meter.set$nIncrListener(new View.$nClic)Listener() 4
mgr.ad2ustStreamVolume(stream>
3&dio9anager.37JDS</63IS8> %):
?
?):
meter.set$n"ecrListener(new View.$nClic)Listener() 4
mgr.ad2ustStreamVolume(stream>
3&dio9anager.37JDS</*2W86> %):
?
?):
?
?
5he net result is that >hen the user %li%ks the buttons on a meter, it aLusts
the stream to mat%h*
!igure $./ The (olumi;er application
-52
CHAPTER 1)
7our ,)n #:dvanced& Services
.n The Busy Coder's Guide to Android Deelopment, >e %overe ho> to
%reate an %onsume servi%es. 0o>, >e %an get into some more interesting
$a%ets o$ servi%e implementations, notably remote servi%es, so your servi%e
%an serve a%tivities outsie o$ your appli%ation.
When +PC :ttacks!
#ervi%es >ill ten to o$$er inter3pro%ess %ommuni%ation &.!C' as a means o$
intera%ting >ith a%tivities or other Anroi %omponents. Ba%h servi%e
e%lares >hat methos it is making available over .!CO those methos are
then available $or other %omponents to %all, >ith Anroi hanling all the
messy etails involve >ith making metho %alls a%ross %omponent or
pro%ess bounaries.
5he guts o$ this, $rom the stanpoint o$ the eveloper, is e;presse in A.@L*
the Anroi .nter$a%e @es%ription Language. .$ you have use .!C
me%hanisms like CGM, CGR/A, or the like, you >ill re%ogniCe the notion o$
.@L. A.@L es%ribes the publi% .!C inter$a%e, an Anroi supplies tools to
buil the %lient an server sie o$ that inter$a%e.
With that in min, let7s take a look at A.@L an .!C.
-53
rite the A$D"
.@Ls are $re<uently >ritten in a Ilanguage3neutralI synta;. A.@L, on the
other han, looks a lot like a +ava inter$a%e. (or e;ample, here is some
A.@L*
pac.age com.commonsware.android.advservice:
// 7eclare t-e interface.
interface IScript 4
void e(ecuteScript(String script):
?
As >ith a +ava inter$a%e, you e%lare a pa%kage at the top. As >ith a +ava
inter$a%e, the methos are >rappe in an inter$a%e e%laration &interface
IScript 4 ... ?'. An, as >ith a +ava inter$a%e, you list the methos you are
making available.
5he i$$eren%es, though, are %riti%al.
(irst, not every +ava type %an be use as a parameter. Dour %hoi%es are*
!rimitive values &int, float, do&ble, boolean, et%.'
String an C-arSe@&ence
*ist an 9ap &$rom Aava.&til'
Any other A.@L3e$ine inter$a%es
Any +ava %lasses that implement the 5arcelable inter$a%e, >hi%h is
Anroi7s $lavor o$ serialiCation
.n the %ase o$ the latter t>o %ategories, you nee to in%lue import
statements re$eren%ing the names o$ the %lasses or inter$a%es that you are
using &e.g., import com.commonsware.android.ISomet-ing'. 5his is true even i$
these %lasses are in your o>n pa%kage M you have to import them any>ay.
0e;t, parameters %an be %lassi$ie as in, o&t, or ino&t. ,alues that are o&t or
ino&t %an be %hange by the servi%e an those %hanges >ill be propagate
-54
ba%k to the %lient. !rimitives &e.g., int' %an only be inO >e in%lue in $or
the A.@L $or enable() Lust $or illustration purposes.
Also, you %annot thro> any e;%eptions. Dou >ill nee to %at%h all
e;%eptions in your %oe, eal >ith them, an return $ailure ini%ations
some other >ay &e.g., error %oe return values'.
0ame your A.@L $iles >ith the .aidl e;tension an pla%e them in the
proper ire%tory base on the pa%kage name.
When you buil your proLe%t, either via an .@B or via Ant, the aidl utility
$rom the Anroi #@K >ill translate your A.@L into a server stub an a
%lient pro;y.
$mplement the $nter*ace
8iven the A.@L3%reate server stub, no> you nee to implement the
servi%e, either ire%tly in the stub, or by routing the stub implementation to
other methos you have alreay >ritten.
5he me%hani%s o$ this are $airly straight$or>ar*
Create a private instan%e o$ the A.@L3generate .St&b %lass &e.g.,
IScript.St&b'
.mplement methos mat%hing up >ith ea%h o$ the methos you
pla%e in the A.@L
Return this private instan%e $rom your on;ind() metho in the
Service sub%lass
0ote that A.@L .!C %alls are syn%hronous, an so the %aller is blo%ke until
the .!C metho returns. )en%e, your servi%es nee to be <ui%k about their
>ork.
We >ill see e;amples o$ servi%e stubs later in this %hapter.
-55
: Consumer <conomy
G$ %ourse, >e nee to have a %lient $or A.@L3e$ine servi%es, lest these
servi%es $eel lonely.
Bound *or (uccess
5o use an A.@L3e$ine servi%e, you $irst nee to %reate an instan%e o$ your
o>n ServiceConnection %lass. ServiceConnection, as the name suggests,
represents your %onne%tion to the servi%e $or the purposes o$ making .!C
%alls.
Dour ServiceConnection sub%lass nees to implement t>o methos*
-. onServiceConnected(), >hi%h is %alle on%e your a%tivity is boun to
the servi%e
2. onService7isconnected(), >hi%h is %alle i$ your %onne%tion ens
normally, su%h as you unbining your a%tivity $rom the servi%e
Ba%h o$ those methos re%eives a Component=ame, >hi%h simply ienti$ies the
servi%e you %onne%te to. More importantly, onServiceConnected() re%eives
an I;inder instan%e, >hi%h is your gate>ay to the .!C inter$a%e. Dou >ill
>ant to %onvert the I;inder into an instan%e o$ your A.@L inter$a%e %lass, so
you %an use .!C as i$ you >ere %alling regular methos on a regular +ava
%lass &IScript.St&b.asInterface(binder)'.
5o a%tually hook your a%tivity to the servi%e, %all bindService() on the
a%tivity*
bindService(new Intent(IScript.class.get-ame())>
svcConn> Context.;I=7/3D<2/C683<8):
5he bindService() metho takes three parameters*
-. An Intent representing the servi%e you >ish to invoke
2. Dour ServiceConnection instan%e
%66
?. A set o$ $lags M most times, you >ill >ant to pass in
;I=7/3D<2/C683<8, >hi%h >ill start up the servi%e i$ it is not alreay
running
A$ter your bindService() %all, your onServiceConnected() %allba%k in the
ServiceConnection >ill eventually be invoke, at >hi%h time your
%onne%tion is reay $or use.
Re?uest *or (ervice
Gn%e your servi%e inter$a%e obLe%t is reay
&IScript.St&b.asInterface(binder)', you %an start %alling methos on it as
you nee to. .n $a%t, i$ you isable some >igets a>aiting the %onne%tion,
no> is a $ine time to re3enable them.
)o>ever, you >ill >ant to trap t>o e;%eptions. Gne is 7ead2bAect8xception
M i$ this is raise, your servi%e %onne%tion terminate une;pe%tely. .n this
%ase, you shoul un>in your use o$ the servi%e, perhaps by %alling
onService7isconnected() manually, as sho>n above. 5he other is
6emote8xception, >hi%h is a more general3purpose e;%eption ini%ating a
%ross3pro%ess %ommuni%ations problem. Again, you shoul probably %ease
your use o$ the servi%e.
Prometheus %n#ound
When you are one >ith the .!C inter$a%e, %all &nbindService(), passing in
the ServiceConnection. Bventually, your %onne%tion7s
onService7isconnected() %allba%k >ill be invoke, at >hi%h point you shoul
null out your inter$a%e obLe%t, isable relevant >igets, or other>ise $lag
yoursel$ as no longer being able to use the servi%e.
(or e;ample, in the Weather!lus implementation o$
onService7isconnected() sho>n above, >e null out the IWeat-er servi%e
obLe%t.
%6-
Dou %an al>ays re%onne%t to the servi%e, via bindService(), i$ you nee to
use it again.
Service !rom :far
Bverything $rom the pre%eing t>o se%tions %oul be use by lo%al servi%es.
.n $a%t, that prose originally appeare in The Busy Coder's Guide to Android
Deelopment spe%i$i%ally in the %onte;t o$ lo%al servi%es. )o>ever, A.@L
as a $air bit o$ overhea, >hi%h is not ne%essary >ith lo%al servi%es. A$ter
all, A.@L is esigne to marshal its parameters an transport them a%ross
pro%ess bounaries, >hi%h is >hy there are so many <uirky rules about
>hat you %an an %annot pass as parameters to your A.@L3e$ine A!.s.
#o, given our A.@L es%ription, let us e;amine some implementations,
spe%i$i%ally $or remote servi%es.
Gur sample appli%ations M sho>n in the 3dvServices/6emoteService an
3dvServices/6emoteClient sample proLe%ts M %onvert our /eanshell emo
$rom The Busy Coder's Guide to Android Deelopment into a remote servi%e.
.$ you a%tually >ante to use s%ripting in an Anroi appli%ation, >ith
s%ripts loae o$$ o$ the .nternet, isolating their e;e%ution into a servi%e
might not be a ba iea. .n the servi%e, those s%ripts are sanbo;e, only
able to a%%ess $iles an A!.s available to that servi%e. 5he s%ripts %annot
a%%ess your o>n appli%ation7s atabases, $or e;ample. .$ the s%ript3e;e%uting
servi%e is kept tightly %ontrolle, it minimiCes the mis%hie$ a rogue s%ript
%oul possibly o.
(ervice 1ames
5o bin to a servi%e7s A.@L3e$ine A!., you nee to %ra$t an .ntent that %an
ienti$y the servi%e in <uestion. .n the %ase o$ a lo%al servi%e, that .ntent %an
use the lo%al approa%h o$ ire%tly re$eren%ing the servi%e %lass.
Gbviously, that is not possible in a remote servi%e %ase, >here the servi%e
%lass is not in the same pro%ess, an may not even be kno>n by name to
the %lient.
%6%
When you e$ine a servi%e to be use by remote, you nee to a an intent3
$ilter element to your servi%e e%laration in the mani$est, ini%ating ho>
you >ant that servi%e to be re$erre to by %lients. 5he mani$est $or
6emoteService is sho>n belo>*
pac.age#$com.commonsware.android.advservice$
service android,name#$.;s-Service$)
intent'filter)
action android,name#$com.commonsware.android.advservice.IScript$ /)
/intent'filter)
/service)
/application)
/manifest)
)ere, >e say that the servi%e %an be ienti$ie by the name
com.commonsware.android.advservice.IScript. #o long as the %lient uses this
name to ienti$y the servi%e, it %an bin to that servi%e7s A!..
.n this %ase, the name is not an implementation, but the A.@L A!., as you
>ill see belo>. .n e$$e%t, this means that so long as some servi%e e;ists on
the evi%e that implements this A!., the %lient >ill be able to bin to
something.
The (ervice
/eyon the mani$est, the servi%e implementation is not too unusual. 5here
is the A.@L inter$a%e, IScript*
interface IScript 4
void e(ecuteScript(String script):
?
An there is the a%tual servi%e %lass itsel$, ;s-Service*
%6.
import android.app.Service:
import bs-.Interpreter:
p&blic class ;s-Service extends Service 4
private final IScript.St&b binder#new IScript.Stub() 4
p&blic void e(ecuteScript(String script) 4
e(ecuteScriptImpl(script):
?
?:
private Interpreter i#new Interpreter():

02verride
s&per.onCreate():

tr+ 4
i.set($context$> t-is):
?
catc- (bs-.8val8rror e) 4
*og.e($;s-Service$> $8rror exec&ting script$> e):
?
?

02verride
p&blic I;inder onBind(Intent intent) 4
ret&rn(binder):
?

02verride
s&per.on"estroy():
?

private void e(ecuteScriptImpl(String script) 4
tr+ 4
i.eval(script):
?
?
?
?
.$ you have seen the servi%e an /eanshell samples in then this
implementation >ill seem $amiliar. 5he biggest thing to note is that the
servi%e returns no result an hanles any errors lo%ally. )en%e, the %lient
>ill not get any response ba%k $rom the s%ript M the s%ript >ill Lust run. .n a
%6$
real implementation, this >oul be silly, an >e >ill >ork to re%ti$y this
later in this %hapter.
Also note that, in this implementation, the s%ript is e;e%ute ire%tly by the
servi%e on the %alling threa. Gne might think this is not a problem, sin%e
the servi%e is in its o>n pro%ess an, there$ore, %annot possibly be using the
%lient7s ". threa. )o>ever, A.@L .!C %alls are syn%hronous, so the %lient
>ill still blo%k >aiting $or the s%ript to be e;e%ute. 5his too >ill be
%orre%te later in this %hapter.
The Client
5he %lient M ;s-Service7emo out o$ 3dvServices/6emoteClient M is a $airly
straight3$or>ar mashup o$ the servi%e an /eanshell %lients, >ith t>o
t>ists*
pac.age com.commonsware.android.advservice.client:
import android.app.3lert7ialog:
import android.content.Component=ame:
import android.content.ServiceConnection:
import android.widget.;&tton:
import android.widget.8dit<ext:
import com.commonsware.android.advservice.IScript:
p&blic class ;s-Service7emo extends 3ctivit+ 4
private IScript service#n&ll:
private ServiceConnection svcConn#new ServiceConnection() 4
p&blic void onServiceConnected(Component=ame class=ame>
I;inder binder) 4
service#IScript.St&b.asInterface(binder):
?
p&blic void onService"isconnected(Component=ame class=ame) 4
service#n&ll:
?
?:
02verride
%60

;&tton btn#(;&tton)findViewById(6.id.eval):
final 8dit<ext script#(8dit<ext)findViewById(6.id.script):

String src#script.get+e(t().toString():

tr+ 4
service.e(ecuteScript(src):
?
catc- (android.os.6emote8xception e) 4
3lert7ialog.;&ilder b&ilder#
new 3lert7ialog.Builder(;s-Service7emo.t-is):

b&ilder
.set%essage(e.toString())
.s!ow():
?
?
?):

?

02verride
s&per.on"estroy():

unbindService(svcConn):
?
?
Gne t>ist is that the %lient nees its o>n %opy o$ IScript.aidl. A$ter all, it is
a totally separate appli%ation, an there$ore oes not share sour%e %oe
>ith the servi%e. .n a prou%tion environment, >e might %ra$t an
istribute a +AR $ile that %ontains the IScript %lasses, so both %lient an
servi%e %an >ork o$$ the same e$inition &see the up%oming %hapter on
reusable %omponents'. (or no>, >e >ill Lust have a %opy o$ the A.@L.
5hen, the bindService() %all uses a slightly i$$erent Intent, one that
re$eren%es the name o$ the A.@L inter$a%e7s %lass implementation. 5hat
happens to be the name the servi%e is registere uner, an that is the glue
that allo>s the %lient to $in the mat%hing servi%e.
%62
.$ you %ompile both appli%ations an uploa them to the evi%e, then start
up the %lient, you %an enter in /eanshell %oe an have it be e;e%ute by
the servi%e. 0ote, though, that you %annot per$orm ". operations &e.g., raise
a <oast' $rom the servi%e. .$ you %hoose some s%ript that is long3running,
you >ill see that the 8o: button is blo%ke until the s%ript is %omplete*
!igure $$/ The BshService9emo application* running a long script
Servicing the Service
5he pre%eing se%tion outline t>o $la>s in the implementation o$ the
/eanshell remote servi%e*
-. 5he %lient re%eive no results $rom the s%ript e;e%ution
2. 5he %lient blo%ke >aiting $or the s%ript to %omplete
.$ >e >ere not >orrie about the blo%king3%all issue, >e %oul simply have
the exec&teScript() e;porte A!. return some sort o$ result &e.g., toString()
on the result o$ the /eanshell eval() %all'. )o>ever, that >oul not solve
the $a%t that %alls to servi%e A!.s are syn%hronous even $or remote servi%es.
%63
Another approa%h >oul be to pass some sort o$ %allba%k obLe%t >ith
exec&teScript(), su%h that the server %oul run the s%ript asyn%hronously
an invoke the %allba%k on su%%ess or $ailure. 5his, though, implies that
there is some >ay to have the a%tivity e;port an A!. to the servi%e.
(ortunately, this is eminently oable, as you >ill see in this se%tion, an the
a%%ompanying samples &3dvServices/6emoteService8x an
3dvServices/6emoteClient8x'.
Call#ac&s via A$D"
A.@L oes not have any %on%ept o$ ire%tion. .t Lust kno>s inter$a%es an
stub implementations. .n the pre%eing e;ample, >e use A.@L to have the
servi%e $lesh out the stub implementation an have the %lient a%%ess the
servi%e via the A.@L3e$ine inter$a%e. )o>ever, there is nothing magi%
about servi%es implementing an %lients a%%essing M it is e<ually possible to
reverse matters an have the %lient implement something the servi%e uses
via an inter$a%e.
#o, $or e;ample, >e %oul %reate an IScript6es&lt.aidl $ile*
interface IScript6es&lt 4
void success(String res&lt):
void failure(String error):
?
5hen, >e %an augment IScript itsel$, to pass an IScript6es&lt >ith
exec&teScript()*
import com.commonsware.android.advservice.IScript6es&lt:
interface IScript 4
void e(ecuteScript(String script> IScript6es&lt cb):
?
%64
0oti%e that >e nee to spe%i$i%ally import IScript6es&lt, Lust like >e might
import some IregularI +ava inter$a%e. An, as be$ore, >e nee to make sure
the %lient an the server are >orking o$$ o$ the same A.@L e$initions, so
these t>o A.@L $iles nee to be repli%ate a%ross ea%h proLe%t.
/ut other than that one little t>ist, this is all that is re<uire, at the A.@L
level, to have the %lient pass a %allba%k obLe%t to the servi%e* e$ine the
A.@L $or the %allba%k an a it as a parameter to some servi%e A!. %all.
G$ %ourse, there is a little more >ork to o on the %lient an server sie to
make use o$ this %allba%k obLe%t.
Revisin! the Client
Gn the %lient, >e nee to implement an IScript6es&lt. Gn s&ccess(), >e
%an o something like raise a <oastO on fail&re(), >e %an perhaps sho> an
3lert7ialog.
5he %at%h is that >e %annot be %ertain >e are being %alle on the ". threa
in our %allba%k obLe%t.
#o, the sa$est >ay to o that is to make the %allba%k obLe%t use something
like r&n2nDi<-read() to ensure the results are isplaye on the ". threa*
private final IScript6es&lt.St&b callbac.#new IScript6es&lt.Stub() 4
p&blic void success(final String res&lt) 4
run$nUi+!read(new Runnable() 4
p&blic void run() 4
successImpl(res&lt):
?
?):
?
p&blic void failure(final String error) 4
run$nUi+!read(new Runnable() 4
p&blic void run() 4
failureImpl(error):
?
?):
?
?:
%65
private void successImpl(String res&lt) 4
<oast
.ma)e+e(t(;s-Service7emo.t-is> res&lt> <oast.*8=G<B/*2=G)
.s!ow():
?
private void failureImpl(String error) 4
3lert7ialog.;&ilder b&ilder#
new 3lert7ialog.Builder(;s-Service7emo.t-is):
b&ilder
.set%essage(error)
.s!ow():
?
An, o$ %ourse, >e nee to upate our %all to exec&teScript() to pass the
%allba%k obLe%t to the remote servi%e*
02verride
;&tton btn#(;&tton)findViewById(6.id.eval):
final 8dit<ext script#(8dit<ext)findViewById(6.id.script):
String src#script.get+e(t().toString():
tr+ 4
service.e(ecuteScript(src> callbac.):
?
catc- (android.os.6emote8xception e) 4
failureImpl(e.toString()):
?
?
?):
?
%-6
Revisin! the (ervice
5he servi%e also nees %hanging, to both e;e%ute the s%ripts asyn%hronously
an use the supplie %allba%k obLe%t $or the en results o$ the s%ript7s
e;e%ution.
As >as emonstrate in the %hapter on Camera, ;s-Service $rom
3dvServices/6emoteService8x uses the *in.ed;loc.ing[&e&e pattern to
manage a ba%kgroun threa. An 8xec&teScriptJob >raps up the s%ript an
%allba%kO >hen the Lob is eventually pro%esse, it uses the %allba%k to supply
the results o$ the eval() &on su%%ess' or the message o$ the 8xception &on
$ailure'*
import android.app.Service:
import Aava.&til.conc&rrent.*in.ed;loc.ing[&e&e:
import bs-.Interpreter:
p&blic class ;s-Service extends Service 4
private final IScript.St&b binder#new IScript.Stub() 4
p&blic void e(ecuteScript(String script> IScript6es&lt cb) 4
e(ecuteScriptImpl(script> cb):
?
?:
private Interpreter i#new Interpreter():
private *in.ed;loc.ing[&e&eJob) @#new *in.ed;loc.ing[&e&eJob)():

02verride
s&per.onCreate():

new +!read(@5rocessor).start():

tr+ 4
i.set($context$> t-is):
?
?
?

02verride
p&blic I;inder onBind(Intent intent) 4
ret&rn(binder):
%--
?

02verride
s&per.on"estroy():

@.add(new #illJob()):
?

private void e(ecuteScriptImpl(String script>
IScript6es&lt cb) 4
@.add(new E(ecuteScriptJob(script> cb)):
?

6&nnable @5rocessor#new Runnable() 4
p&blic void run() 4
w-ile (tr&e) 4
tr+ 4
Job A#@.ta)e():

if (A.stop+!read()) 4
brea.:
?
else 4
A.process():
?
?
catc- (Interr&pted8xception e) 4
brea.:
?
?
?
?:

class Job 4
boolean stop+!read() 4
ret&rn(false):
?

void process() 4
// no'op
?
?

class VillJob extends Job 4
02verride
boolean stop+!read() 4
ret&rn(tr&e):
?
?

class 8xec&teScriptJob extends Job 4
IScript6es&lt cb:
String script:
%-%

E(ecuteScriptJob(String script> IScript6es&lt cb) 4
t-is.script#script:
t-is.cb#cb:
?

void process() 4
tr+ 4
cb.success(i.eval(script).toString()):
?
catc- (<-rowable e) 4

tr+ 4
cb.failure(e.get%essage()):
?
*og.e($;s-Service$>
$8rror ret&rning exception to client$>
t):
?
?
?
?
?
0oti%e that the servi%e7s o>n A!. Lust nees the IScript6es&lt parameter,
>hi%h %an be passe aroun an use like any other +ava obLe%t. 5he $a%t
that it happens to %ause %alls to be mae syn%hronously ba%k to the remote
%lient is invisible to the servi%e.
5he net result is that the %lient %an %all the servi%e an get its results
>ithout tying up the %lient7s ". threa.
%-.
CHAPTER 1.
!inding :vailable :ctions via
+ntrospection
#ometimes, you kno> Lust >hat you >ant to o, su%h as isplay one o$ your
other a%tivities.
#ometimes, you have a pretty goo iea o$ >hat you >ant to o, su%h as
vie> the %ontent represente by a Dri, or have the user pi%k a pie%e o$
%ontent o$ some M.MB type.
#ometimes, you7re lost. All you have is a %ontent Dri, an you on7t really
kno> >hat you %an o >ith it.
(or e;ample, suppose you >ere %reating a %ommon tagging subsystem $or
Anroi, >here users %oul tag pie%es o$ %ontent M %onta%ts, Web "RLs,
geographi% lo%ations, et%. Dour subsystem >oul hol onto the Dri o$ the
%ontent plus the asso%iate tags, so other subsystems %oul, say, ask $or all
pie%es o$ %ontent re$eren%ing some tag.
5hat7s all >ell an goo. )o>ever, you probably nee some sort o$
maintenan%e a%tivity, >here users %oul vie> all their tags an the pie%es o$
%ontent so tagge. 5his might even serve as a <uasi3bookmark servi%e $or
items on their phone. 5he problem is, the user is going to e;pe%t to be able
to o use$ul things >ith the %ontent they $in in your subsystem, su%h as
ial a %onta%t or sho> a map $or a lo%ation.
%-0
!inding :vailable :ctions via +ntrospection
5he problem is, you have absolutely no iea >hat is all possible >ith any
given %ontent Dri. Dou probably %an vie> any o$ them, but %an you eit
themJ Can you ial themJ #in%e ne> appli%ations >ith ne> types o$
%ontent %oul be ae by any user at any time, you %an7t even assume you
kno> all possible %ombinations Lust by looking at the sto%k appli%ations
shippe on all Anroi evi%es.
(ortunately, the Anroi evelopers thought o$ this.
Anroi o$$ers various means by >hi%h you %an present to your users a set
o$ likely a%tivities to spa>n $or a given %ontent Dri...even i$ you have no
iea >hat that %ontent Dri really represents. 5his %hapter e;plores some o$
these Dri a%tion introspe%tion tools.
Pick ?<m
#ometimes, you kno> your %ontent Dri represents a %olle%tion o$ some
type, su%h as content,//contacts/people representing the list o$ %onta%ts in
the sto%k Anroi %onta%ts list. .n this %ase, you %an let the user pi%k a
%onta%t that your a%tivity %an then use &e.g., tag it, ial it'.
5o o this, you nee to %reate an intent $or the 3C<I2=/5ICV on the target
Dri, then start a sub a%tivity &via start3ctivit+Kor6es&lt()' to allo> the user
to pi%k a pie%e o$ %ontent o$ the spe%i$ie type. .$ your on3ctivit+6es&lt()
%allba%k $or this re<uest gets a 68SD*</2V result %oe, your ata string %an be
parse into a Dri representing the %hosen pie%e o$ %ontent.
(or e;ample, take a look at Introspection/5ic. in the sample appli%ations.
5his a%tivity gives you a $iel $or a %olle%tion Dri &>ith
content,//contacts/people pre3$ille in $or your %onvenien%e', plus a really
big 68imme:9 button*
)
%-2
8dit<ext android,id#$01id/t+pe$
android,c&rsorVisible#$tr&e$
android,editable#$tr&e$
android,single*ine#$tr&e$
android,text#$content,//contacts/people$
/)
;&tton
android,id#$01id/pic.$
android,text#$GimmeN$
/)
/*inear*a+o&t)
"pon being %li%ke, the button %reates the 3C<I2=/5ICV on the user3
supplie %olle%tion Dri an starts the sub3a%tivity. When that sub3a%tivity
%ompletes >ith 68SD*</2V, the 3C<I2=/VI8W is invoke on the resulting
%ontent Dri.
p&blic class 5ic.7emo extends 3ctivit+ 4
static final int 5ICV/68[D8S<#1JJG:
private 8dit<ext t+pe:
02verride
t+pe#(8dit<ext)findViewById(6.id.t+pe):

;&tton btn#(;&tton)findViewById(6.id.pic.):

Intent i#new Intent(Intent.3C<I2=/5ICV>
Dri.parse(t+pe.get+e(t().toString())):
start&ctivity'orResult(i> 5ICV/68[D8S<):
?
?):
?
02verride
protected void on&ctivityResult(int re@&estCode> int res&ltCode>
Intent data) 4
if (re@&estCode##5ICV/68[D8S<) 4
if (res&ltCode##68SD*</2V) 4
start&ctivity(new Intent(Intent.3C<I2=/VI8W>
data.get"ata())):
%-3
?
?
?
?
5he result* the user %hooses a %olle%tion, pi%ks a pie%e o$ %ontent, an vie>s
it.
!igure $0/ The Pick9emo sample application* as initially launched
%-4
!igure $2/ The same application* after clicking the D'imme!D button* sho)ing
the list of available people
!igure $3/ : vie) of a contact* launched by Pick9emo after choosing one of the
people from the pick list
%-5
Would 7ou ike to See the 8enuF
Another >ay to give the user >ays to take a%tions on a pie%e o$ %ontent,
>ithout you kno>ing >hat a%tions are possible, is to inLe%t a set o$ menu
%hoi%es into the options menu via addIntent2ptions(). 5his metho,
available on 9en&, takes an Intent an other parameters an $ills in a set o$
menu %hoi%es on the 9en& instan%e, ea%h representing one possible a%tion.
Choosing one o$ those menu %hoi%es spa>ns the asso%iate a%tivity.
5he %anoni%al e;ample o$ using addIntent2ptions() illustrates another
$lavor o$ having a pie%e o$ %ontent an not kno>ing the a%tions that %an be
taken. Anroi appli%ations are per$e%tly %apable o$ aing ne> a%tions to
e;isting %ontent types, so even though you >rote your appli%ation an
kno> >hat you e;pe%t to be one >ith your %ontent, there may be other
options you are una>are o$ that are available to users.
(or e;ample, imagine the tagging subsystem mentione in the introu%tion
to this %hapter. .t >oul be very annoying to users i$, every time they
>ante to tag a pie%e o$ %ontent, they ha to go to a separate tagging tool,
then turn aroun an pi%k the %ontent they Lust ha been >orking on &i$
that is even te%hni%ally possible' be$ore asso%iating tags >ith it. .nstea,
they >oul probably pre$er a menu %hoi%e in the %ontent7s o>n 6home9
a%tivity >here they %an ini%ate they >ant to tag it, >hi%h leas them to the
set3a3tag a%tivity an tells that a%tivity >hat %ontent shoul get tagge.
5o a%%omplish this, the tagging subsystem shoul set up an intent $ilter,
supporting any pie%e o$ %ontent, >ith their o>n a%tion &e.g., 3C<I2=/<3G'
an a %ategory o$ C3<8G26C/3*<86=3<IV8. 5he %ategory C3<8G26C/3*<86=3<IV8
is the %onvention $or one appli%ation aing a%tions to another
appli%ation7s %ontent.
.$ you >ant to >rite a%tivities that are a>are o$ possible a3ons like
tagging, you shoul use addIntent2ptions() to a those a3ons7 a%tions to
your options menu, su%h as the $ollo>ing*
Intent intent # new Intent(n&ll> m+ContentDri):
%%6
intent.addCategory(Intent.3*<86=3<IV8/C3<8G26C):
men&.addIntent$ptions(9en&.3*<86=3<IV8> %>
new Component-ame(t-is>
9+3ctivit+.class)>
n&ll> intent> %> n&ll):
)ere, m+ContentDri is the %ontent Dri o$ >hatever is being vie>e by the
user in this a%tivity, 9+3ctivit+ is the name o$ the a%tivity %lass, an men& is
the menu being moi$ie.
.n this %ase, the Intent >e are using to pi%k a%tions $rom re<uires that
appropriate intent re%eivers support the C3<8G26C/3*<86=3<IV8. 5hen, >e
a the options to the menu >ith addIntent2ptions() an the $ollo>ing
parameters*
5he sort position $or this set o$ menu %hoi%es, typi%ally set to %
&appear in the orer ae to the menu' or 3*<86=3<IV8 &appear
a$ter other menu %hoi%es'
A uni<ue number $or this set o$ menu %hoi%es, or % i$ you o not
nee a number
A Component=ame instan%e representing the a%tivity that is populating
its menu M this is use to $ilter out the a%tivity7s o>n a%tions, so the
a%tivity %an hanle its o>n a%tions as it sees $it
An array o$ Intent instan%es that are the 6spe%i$i%9 mat%hes M any
a%tions mat%hing those intents are sho>n $irst in the menu be$ore
any other possible a%tions
5he Intent $or >hi%h you >ant the available a%tions
A set o$ $lags. 5he only one o$ likely relevan%e is represente as
93<CB/78K3D*</2=*C, >hi%h means mat%hing a%tions must also
implement the 78K3D*</C3<8G26C %ategory. .$ you o not nee this,
use a value o$ % $or the $lags.
An array o$ 9en&.Item, >hi%h >ill hol the menu items mat%hing the
array o$ Intent instan%es supplie as the 6spe%i$i%s9, or n&ll i$ you o
not nee those items &or are not using 6spe%i$i%s9'
%%-
:sking :round
5he addIntent2ptions() metho in turn uses @&er+Intent3ctivit+2ptions()
$or the 6heavy li$ting9 o$ $ining possible a%tions. 5he
@&er+Intent3ctivit+2ptions() metho is implemente on 5ac.age9anager,
>hi%h is available to your a%tivity via get5ac.age9anager().
5he @&er+Intent3ctivit+2ptions() metho takes some o$ the same
parameters as oes addIntent2ptions(), notably the %aller Component=ame, the
6spe%i$i%s9 array o$ Intent instan%es, the overall Intent representing the
a%tions you are seeking, an the set o$ $lags. .t returns a *ist o$ Intent
instan%es mat%hing the state %riteria, >ith the 6spe%i$i%s9 ones $irst.
.$ you >oul like to o$$er alternative a%tions to users, but by means other
than addIntent2ptions(), you %oul %all @&er+Intent3ctivit+2ptions(), get
the Intent instan%es, then use them to populate some other user inter$a%e
&e.g., a toolbar'.
%%%
PART IV Advanced Development
CHAPTER 10
Testing 7our Patience
!resumably, you >ill >ant to test your %oe, beyon Lust playing aroun
>ith it yoursel$ by han.
5o that en, Anroi in%lues the +"nit test $rame>ork in the #@K, along
>ith spe%ial test %lasses that >ill help you buil test %ases that e;er%ise
Anroi %omponents, like a%tivities an servi%es. Bven better, Anroi -.A
has Igone the e;tra mileI an %an pre3generate your test harness $or you, to
make it easier $or you to a in your o>n tests.
5his %hapter assumes you have some $amiliarity >ith +"nit, though you
%ertainly o not nee to be an e;pert. Dou %an learn more about +"nit at the
+"nit site, $rom various books, an $rom the +"nit Dahoo $orum.
7ou 'et What They 'ive 7ou
When you %reate a proLe%t in Anroi -.A using anroi %reate proLe%t,
Anroi automati%ally %reates a ne> tests/ ire%tory insie the proLe%t
ire%tory. .$ you look in there, you >ill see a %omplete set o$ Anroi
proLe%t arti$a%ts* mani$est, sour%e ire%tories, resour%es, et%. 5his is a%tually
a test proLe%t, esigne to partner >ith the main proLe%t to %reate a
%omplete testing solution.
.n $a%t, that test proLe%t is all reay to go, other than not having any tests o$
signi$i%an%e. .$ you buil an install your main proLe%t &onto an emulator or
%%0
evi%e', then buil an install the test proLe%t, you >ill be able to run unit
tests.
Anroi ships >ith a very ruimentary +"nit runner, %alle
Instr&mentation<est6&nner. #in%e this %lass resies in the Anroi
environment &emulator or evi%e', you nee to invoke the runner to run
your tests on the emulator or evi%e itsel$. 5o o this, you %an run the
$ollo>ing %omman $rom a %onsole*
adb s-ell am instr&ment 'w
com.commonsware.android.database.tests/android.test.Instr&mentation<est6&nner
.n this %ase, >e are instru%ting Anroi to run all the available test %ases $or
the com.commonsware.android.database pa%kage, as this %hapter uses some
tests implemente on the 7atabase/Contacts sample proLe%t.
.$ you >ere to run this on your o>n proLe%t, substituting in your pa%kage
name, >ith Lust the auto3generate test $iles, you shoul see results akin to*
com.commonsware.android.database.Contacts7emo<est,.
<est res&lts for Instr&mentation<est6&nner#.
<ime, %.X1
2V (1 test)
5he $irst line >ill i$$er, base upon your pa%kage an the name o$ your
proLe%t7s initial a%tivity, but the rest shoul be the same, sho>ing that a
single test >as run, su%%ess$ully.
G$ %ourse, this is only the beginning.
<recting 8ore Scaffolding
)ere is the sour%e %oe $or the test %ase that Anroi automati%ally
generates $or you*
%%2
import android.test.3ctivit+Instr&mentation<estCase:
/MM
M <-is is a simple framewor. for a test of an 3pplication. See
M 40lin. android.test.3pplication<estCase 3pplication<estCase? for more
information on
M -ow to write and extend 3pplication tests.
M p/)
M <o r&n t-is test> +o& can t+pe,
M adb s-ell am instr&ment 'w Z
M 'e class com.commonsware.android.database.Contacts7emo<est Z
M com.commonsware.android.database.tests/android.test.Instr&mentation<est6&nner
M/
p&blic class Contacts7emo<est extends
3ctivit+Instr&mentation<estCaseContacts7emo) 4
p&blic Contacts"emo+est() 4
s&per($com.commonsware.android.database$> Contacts7emo.class):
?
?
As you %an see, there are no a%tual test methos. .nstea, >e have an
3ctivit+Instr&mentation<estCase implementation name Contacts7emo<est.
5he %lass name >as generate by aing 5est to the en o$ the main a%tivity
&Contacts7emo' o$ the proLe%t.
.n the ne;t se%tion, >e >ill e;amine 3ctivit+Instr&mentation<estCase more
%losely an see ho> you %an use it to, as the name suggests, test your
a%tivities.
)o>ever, you are >el%ome to %reate orinary +"nit test %ases in Anroi M
a$ter all, this is Lust +"nit, merely augmente by Anroi. #o, you %an %reate
%lasses like this*
import A&nit.framewor..<estCase:
p&blic class Sill+<est extends <estCase 4
protected void setUp() t-rows 8xception 4
s&per.setUp():

// do initialiIation -ere> r&n on ever+ test met-od
?

protected void tear"own() t-rows 8xception 4
%%3
// do termination -ere> r&n on ever+ test met-od
s&per.tear"own():
?

p&blic void test-onsense() 4
assert+rue(1##1):
?
?
5here is nothing Anroi3spe%i$i% in this test %ase. .t is simply stanar
+"nit, albeit a bit silly.
Dou %an also %reate test suites, to bunle up sets o$ tests $or e;e%ution.
)ere, though, i$ you >ant, you %an take avantage o$ a bit o$ Anroi
magi%* <estS&ite;&ilder. <estS&ite;&ilder uses re$le%tion to $in test %ases
that nee to be run, as sho>n belo>*
import android.test.s&iteb&ilder.<estS&ite;&ilder:
import A&nit.framewor..<est:
import A&nit.framewor..<estS&ite:
p&blic class K&llS&ite extends <estS&ite 4
p&blic static <est suite() 4
ret&rn(new +estSuiteBuilder(K&llS&ite.class)
.include&llac)agesUnder*ere()
.build()):
?
?
)ere, >e are telling Anroi to $in all test %ases lo%ate in K&llS&ite7s
pa%kage &com.commonsware.android.database' an all sub3pa%kages, an to
buil a <estS&ite out o$ those %ontents.
A test suite may or may not be ne%essary $or you. 5he %omman sho>n
above to e;e%ute tests >ill e;e%ute any test %ases it %an $in $or the pa%kage
spe%i$ie on the %omman line. .$ you >ant to limit the s%ope o$ a test run,
though, you %an use the 'e s>it%h to spe%i$y a test %ase or suite to run*
adb s-ell am instr&ment 'e class
com.commonsware.android.database.Contacts7emo<est 'w
com.commonsware.android.database.tests/android.test.Instr&mentation<est6&nner
%%4
)ere, >e ini%ate >e only >ant to run Contacts7emo<est, not all test %ases
$oun in the pa%kage.
Testing Eeal Stuff
While orinary +"nit tests are %ertainly help$ul, they are still $airly limite,
sin%e mu%h o$ your appli%ation logi% may be tie up in a%tivities, servi%es,
an the like.
5o that en, Anroi has a series o$ <estCase %lasses you %an e;ten
esigne spe%i$i%ally to assist in testing these sorts o$ %omponents.
Activity$nstrumentationTestCase
5he test %ase %reate by Anroi7s #@K tools, Contacts7emo<est in our
e;ample, is an 3ctivit+Instr&mentation<estCase. 5his %lass >ill run your
a%tivity $or you, giving you a%%ess to the 3ctivit+ obLe%t itsel$. Dou %an then*
A%%ess your >igets
.nvoke publi% an pa%kage3private methos &more on this belo>'
#imulate key events
G$ %ourse, the automati%ally3generate 3ctivit+Instr&mentation<estCase
oes none o$ that, sin%e it oes not kno> mu%h about your a%tivity. /elo>
you >ill $in an augmente version o$ Contacts7emo<est that oes a little bit
more*
import android.test.3ctivit+Instr&mentation<estCase:
p&blic class Contacts7emo<est
extends 3ctivit+Instr&mentation<estCaseContacts7emo) 4
private *istView list#n&ll:
private Spinner spinner#n&ll:

p&blic Contacts"emo+est() 4
%%5
s&per($com.commonsware.android.database$>
Contacts7emo.class):
?
02verride
s&per.setUp():

Contacts7emo activit+#get&ctivity():

list#(*istView)activit+.findViewById(android.6.id.list):
spinner#(Spinner)activit+.findViewById(6.id.spinner):
?

p&blic void testSpinnerCount() 4
assert+rue(spinner.get&dapter().getCount()##J):
?

p&blic void testList"efaultCount() 4
assert+rue(list.get&dapter().getCount())%):
?
?
)ere are the steps to making use o$ 3ctivit+Instr&mentation<estCase*
-. B;ten the %lass to %reate your o>n implementation. #in%e
3ctivit+Instr&mentation<estCase is a generi%, you nee to supply the
name o$ the a%tivity being teste &e.g.,
3ctivit+Instr&mentation<estCaseContacts7emo)'.
2. .n the %onstru%tor, >hen you %hain to the super%lass, supply the
name o$ the pa%kage o$ the a%tivity plus the a%tivity %lass itsel$. Dou
%an optionally supply a thir parameter, a boolean ini%ating i$ the
a%tivity shoul be laun%he in tou%h moe or not.
?. .n setDp(), use get3ctivit+() to get your hans on your 3ctivit+
obLe%t, alreay type%ast to the proper type &e.g., Contacts7emo'
%ourtesy o$ our generi%. Dou %an also at this time a%%ess any >igets,
sin%e the a%tivity is up an running by this point.
=. .$ neee, %lean up stu$$ in tear7own(), no i$$erent than >ith any
other +"nit test %aseQ
A. .mplement test methos to e;er%ise your a%tivity. .n this %ase, >e
simply %on$irm that the Spinner has three items in its rop3o>n
list an there is at least one %onta%t loae into the *istView by
%.6
e$ault. Dou %oul, ho>ever, use sendVe+s() an the like to simulate
user input.
.$ you are looking at your emulator or evi%e >hile this test is running, you
>ill a%tually see the a%tivity laun%he on3s%reen.
3ctivit+Instr&mentation<estCase %reates a true running %opy o$ the a%tivity.
5his means you get a%%ess to everything you neeO on the other han, it
oes mean that the test %ase runs slo>ly, sin%e the a%tivity nees to be
%reate an estroye $or ea%h test metho in the test %ase. .$ your a%tivity
oes a lot on startup anQor shuto>n, this may make running your tests a
bit sluggish.
0ote that your 3ctivit+Instr&mentation<estCase resies in the same pa%kage
as the A%tivity it is testing M Contacts7emo<est an Contacts7emo are both in
com.commonsware.android.database, $or e;ample. 5his allo>s
Contacts7emo<est to a%%ess both publi% an pa%kage3private methos an
ata members. Contacts7emo<est still %annot a%%ess private methos,
though. 5his allo>s 3ctivit+Instr&mentation<estCase to behave in a >hite3
bo; &or at least gray3bo;' $ashion, inspe%ting the insies o$ the teste
a%tivities in aition to testing the publi% A!..
0o>, espite the $a%t that Anroi7s o>n tools %reate an
3ctivit+Instr&mentation<estCase sub%lass $or you, that %lass is o$$i%ially
epre%ate. 5hey avise using 3ctivit+Instr&mentation<estCaseE instea,
>hi%h o$$ers the same basi% $un%tionality, >ith a $e> e;tras, su%h as being
able to spe%i$y the Intent that is use to laun%h the a%tivity being teste.
5his is goo $or testing sear%h proviers, $or e;ample.
AndroidTestCase
(or tests that only nee a%%ess to your appli%ation resour%es, you %an skip
some o$ the overhea o$ 3ctivit+Instr&mentation<estCase an use
3ndroid<estCase. .n 3ndroid<estCase, you are given a Context an not mu%h
more, so anything you %an rea%h $rom a Context is testable, but iniviual
a%tivities or servi%es are not.
%.-
While this may seem some>hat useless, bear in min that a lot o$ the stati%
testing o$ your a%tivities >ill %ome in the $orm o$ testing the layout* are the
>igets ienti$ie properly, are they positione properly, oes the $o%us
>ork, et%. As it turns out, none o$ that a%tually nees an 3ctivit+ obLe%t M
so long as you %an get the in$late View hierar%hy, you %an per$orm those
sorts o$ tests.
(or e;ample, here is an 3ndroid<estCase implementation,
Contacts7emo;ase<est*
import android.test.3ndroid<estCase:
import android.view.*a+o&tInflater:
p&blic class Contacts7emo;ase<est extends 3ndroid<estCase 4
private *istView list#n&ll:
private Spinner spinner#n&ll:
private ViewGro&p root#n&ll:

02verride
s&per.setUp():

*a+o&tInflater inflater#*a+o&tInflater.from(getConte(t()):

root#(ViewGro&p)inflater.inflate(6.la+o&t.main> n&ll):
root.measure(F(%> JE%):
root.layout(%> %> F(%> JE%):
list#(*istView)root.findViewById(android.6.id.list):
spinner#(Spinner)root.findViewById(6.id.spinner):
?

p&blic void testE(ists() 4
assert-ot-ull(list):
assert-ot-ull(spinner):
?

p&blic void testRelativeosition() 4
assert+rue(list.get+op())#spinner.getBottom()):
assert+rue(list.getLeft()##spinner.getLeft()):
assert+rue(list.getRig!t()##spinner.getRig!t()):
?
?
%.%
Most o$ the %ompli%ate >ork is per$orme in setDp()*
-. .n$late our layout using a *a+o&tInflater an the Context supplie
by getContext()
2. Measure an lay out the >igets in the in$late View hierar%hy M in
this %ase, >e lay them out on a =20;?20 s%reen
?. A%%ess the iniviual >igets to be teste
At that point, >e %an test stati% in$ormation on the >igets, but >e %annot
%ause them to %hange very easily &e.g., >e %annot simulate keypresses'. .n
the %ase o$ Contacts7emo;ase<est, >e simply %on$irm the >igets e;ist an
are lai out as e;pe%te. We %oul use Koc&sKinder to test >hether $o%us
%hanges $rom one >iget to the ne;t shoul >ork as e;pe%te. We %oul
ensure our resour%es e;ist uner their esire names, test to see i$ our $onts
e;ist in our assets, or anything else >e %an a%%omplish >ith Lust a Context.
#in%e >e are not %reating an estroying a%tivities >ith ea%h test %ase, these
tests shoul run substantially $aster.
=ther Alternatives
Anroi also o$$ers various other test %ase base %lasses esigne to assist in
testing Anroi %omponents, su%h as*
Service<estCase, use $or testing servi%es, as you might e;pe%t given
the name
3ctivit+Dnit<estCase, a <estCase that %reates the 3ctivit+ &like
3ctivit+Instr&mentation<estCase', but oes not $ully %onne%t it to
the environment, so you %an supply a mo%k Context, a mo%k
3pplication, an other mo%k obLe%ts to test out various s%enarios
3pplication<estCase, $or testing %ustom 3pplication sub%lasses
8onkeying :round
.nepenent $rom the +"nit system is the Monkey.
%..
5he Monkey is a test program that simulates ranom user input. .t is
esigne $or Ibash testingI, %on$irming that no matter >hat the user oes,
the appli%ation >ill not %rash. 5he appli%ation may have o results M
ranom input entere into a 5>itter %lient may, inee, post that ranom
input to 5>itter. 5he Monkey oes not test to make sure that results o$
ranom input make senseO it only tests to make sure ranom input oes not
blo> up the program.
Dou %an run the Monkey by setting up your initial starting point &e.g., the
main a%tivity in your appli%ation' on your evi%e or emulator, then running
a %omman like this*
adb s-ell mon.e+ 'p com.commonsware.android.database 'v ''t-rottle 1%% X%%
Working $rom right to le$t, >e are asking $or 400 simulate events,
throttle to run every -00 millise%ons. We >ant to see a list o$ the invoke
events &'v' an >e >ant to thro> out any event that might %ause the
Monkey to leave our appli%ation, as etermine by the appli%ation7s
pa%kage &'p com.commonsware.android.database'.
5he Monkey >ill simulate keypresses &both FWBR5D an spe%ialiCe
har>are keys, like the volume %ontrols', @3paQtra%kball moves, an
sliing the keyboar open or %lose. 0ote that the latter may %ause your
emulator some %on$usion, as the emulator itsel$ oes not itsel$ a%tually
rotate, so you may en up >ith your s%reen appearing in lans%ape >hile
the emulator is still, itsel$, portrait. +ust rotate the emulator a %ouple o$
times &e.g., Ctrl)'K1E)' to %lear up the problem.
(or playing >ith a Monkey, the above %omman >orks $ine. )o>ever, i$
you >ant to regularly test your appli%ation this >ay, you may nee some
measure o$ repeatability. A$ter all, the parti%ular set o$ input events that
trigger your %rash may not %ome up all that o$ten, an >ithout that
repeatable s%enario, it >ill be i$$i%ult to repair the bug, let alone test that
the repair >orke.
5o eal >ith this, the Monkey o$$ers the 's s>it%h, >here you provie a see
$or the ranom number generator. /y e$ault, the Monkey %reates its o>n
%.$
see, giving totally ranom results. .$ you supply the see, >hile the
se<uen%e o$ events is ranom, it is ranom $or that see M repeately using
the same see >ill give you the same events. .$ you %an arrange to ete%t a
%rash an kno> >hat see >as use to %reate that %rash, you may >ell be
able to reprou%e the %rash.
5here are many more Monkey options, to %ontrol the mi; o$ event types, to
generate pro$iling reports as tests are run, an so on. 5he Monkey
o%umentation in the #@K7s @eveloper7s 8uie %overs all o$ that an more.
%.0
Gey)ord +ndex
Class...............................................
A%%elerate@e%elerate.nterpolator...................9A
A%%elerate.nterpolator.....................................9A
A%tivity.....-4, A0, -2=, -423-10, -19, 229, 2?0, 2?2,
2??
A%tivity.nstrumentation5estCase. . .221, 22932?-,
2??
A%tivity.nstrumentation5estCase2.................2?-
A%tivity"nit5estCase.......................................2??
Aapter......................................?03?2, ?A, ?4, -=4
Aapter,ie>.Gn.tem#ele%teListener...........=4
AlarmManager.......44, -42, -19, -20, -22, -2?, -2A
Alert@ialog......................................................209
AlphaAnimation..............................21, 9239=, 91
AnalogClo%k......................................................A0
Anroi5estCase......................................2?-, 2?2
Animation........................................21, 22, 9=394
AnimationListener......................................9=, 9A
Animation#et........................................21, 94, 91
Animation"tils.................................................9=
Appli%ation......................................................2??
Appli%ation5estCase........................................2??
App#ervi%e..................................-223-2A, -21, -22
AppWiget)ost................................................44
AppWiget)ost,ie>.......................................44
AppWigetManager..............................A4, 4-, 4A
AppWiget!rovier........................AA, A9, 4=, 4A
Asyn%5ask.........................................................--9
Attribute#et.......................................................-4
Auio#ervi%e....................................................-9?
/aseColumns....................................................-A0
/atteryMonitor.........................................-1=, -14
/itmap@ra>able..............................................-20
/oolean#etting.................................................-29
/roa%astRe%eiver. A03A2, AA, 4A, 44, -493-1-, -1?,
-2-, -22, -2A
/roa%astRe%iever.............................................AA
/sh#ervi%e.................................................20?, 2--
/sh#ervi%e@emo.............................................20A
/utton.............2-, 2?, 2=, =0, A0, A-, A2, 1A, 14, 22
CallLog................................................-A03-A2, -40
%.3
Gey)ord +ndex
CallLog.Calls....................................................-A0
Call!lusAapter........................................-A2, -40
Camera......................................--?3--A, --13--9, 2--
Camera.!arameters....................................--A, --1
Camera.!i%tureCallba%k..................................--9
Camera.#hutterCallba%k..................................--2
Char#e<uen%e..................................................-92
Che%k/o;................................................2-, 2A, 21
Chronometer.....................................................A0
Component0ame.......................A4, 200, 22-, 222
Constants.nstaller............................................-=-
Conta%ts.............................................-=2, -=?, -A0
Conta%ts.Conta%tMethosColumns...............-=9
Conta%ts.!eopleColumns.........................-=2, -=9
Conta%ts.!hones..............................................-=2
Conta%ts.!honesColumns...............................-=2
Conta%ts@emo....................-=?, -=1, 221, 2?0, 2?-
Conta%ts@emo/ase5est...........................2?2, 2??
Conta%ts@emo5est...........................221, 229, 2?-
Content!rovier........................................-A-, -42
Content,alues..................................................-A1
Conte;t..............-4, 9=, -2=, -?0, -10, -19, 2?-, 2??
Cursor..............................?-, -A03-A?, -A4, -A1, -40
CursorAapter.................................................-A2
Cursor+oiner......................................................-A-
CursorWrapper..........................................-A-, -A2
Cy%le.nterpolator........................................9=, 94
@atabase.nstaller......................................-=03-=2
@eaGbLe%tB;%eption.....................................20-
@e%elerate.nterpolator.....................................9A
@ra>able...............................2?324, =2, 1-, 12, -9?
@ra>ableQ8raient@emo.................................12
Bit5e;t..............................................................A-
B;%eption..........................................................2--
B;e%ute#%ript+ob...............................................2--
(o%us(iner.....................................................2??
(rameLayout.....................................................A0
(ull#uite...........................................................222
8eoWebGne........................................................2
)eaer(ooter@emo..........................................?2
.R+oin)anler............................................-A4, -A1
./iner.............................................................200
.mage/utton...............-?, -=, -9, A0, A-, AA, A2, 9A
.mage,ie>..................................................A0, -1?
.nput#tream......................................................-=-
.nstrumentation5estRunner..........................224
.ntent ;ii, AA, 40, 4-, 44, -413-1-, -1?3-1A, -19, -20,
-22, -2A, -9-, 200, 204, 2203222, 2?-
.ntent#ervi%e........................................A4, 44, -2A
.nterpolator.................................................9A, 94
.#%ript..............................................20?, 204, 202
.#%riptResult.....................................202, 209, 2-?
+oinCa%he..........................................................-A1
+oinCursor.....................................-A-3-A?, -A43-A2
+oin@emo....................................-A0, -A1, -A2, -40
Layout.n$later............................................A2, 2??
Linear.nterpolator............................................9A
LinearLayout..............................-A, ?2, A0, 29, 90
Linke/lo%kingFueue.....................................2--
Linke)ashMap...............................................-A1
List.......................................................?A, -92, 222
%.4
Gey)ord +ndex
ListA%tivity..............................?2, ?4, =?, -=?, -40
List,ie>. 293?2, ?4, ?2, =2, =?, =4, A1, 12, 1=, -=?,
-==, -40, 2?0
Lo%ater.................................................................=
Lo%ationListener.............................................=, 2
Lo%ationManager................................................=
Map...................................................................-92
MeiaQAuio.....................................................-0-
Meia!layer................................-00, -0-, -0=, -0A
Menu..........................................................9=, 220
Menu..tem........................................................22-
Meter................................-?3-4, -2, -9, 2-, -9?, -9A
Meter@emo........................................................2-
MyA%tivity........................................................22-
0ine!at%h@emo................................................22
0oteA%tivity.....................................................-4=
0oteBitor.......................................................-4=
GnAlarmRe%eiver.....................................-223-2=
Gn/ootComplete..........................................-49
Gn/ootRe%eiver........................................-49, -2-
GnCli%kListener.................................................A-
GnWi(iChangeRe%eiver...................................-1-
!a%kageManager.............................................222
!ar%elable.........................................................-92
!ening.ntent................................A-, A2, -19, -22
!hotoCallba%k..................................................-20
!i%ture@emo.............................................--2, -20
!o>erManager..........................................-20, -2?
!re$eren%eA%tivity......................................A2, 40
!revie>@emo.............................................--2, --?
!rogress/ar...............................-?, -=, A0, -1?, -14
RelativeLayout..................................................A0
RemoteB;%eption.............................................20-
Remote#ervi%e.................................................20?
Remote,ie>s...............................A0, A-, AA3A9, 4-
RotateAnimation........................................21, 9=
#ave!hoto5ask..........................................--9, -20
#%aleAnimation.................................................21
#%roll,ie>........................................................-22
#e%tion...............................................................?A
#e%tioneAapter..................................?2, ?A, ?4
#e%tione@emo...........................................?2, ?4
#eek/ar.........................................................-?, 22
#ele%torAapter................................................=4
#ele%tor@emo..............................................=?, =4
#ele%torWrapper...............................................=4
#ensor...............................................................-2A
#ensorBvent......................................................-2A
#ensorBventListener.................................-2A, -21
#ensorManager..................................-2=, -2A, -?0
#ervi%e........................A03A2, A4, 44, -42, -19, -99
#ervi%eConne%tion...................................200, 20-
#ervi%e5estCase...............................................2??
#ettings......................................................-22, -9-
#ettings.#e%ure.........................................-22, -92
#ettings.#ystem.................................-22, -29, -92
#ettings#etter....................................-22, -90, -92
#haker.........................................................-293-?-
#haker.Callba%k................................................-?-
#haker@emo..............................................-29, -?-
#hare!re$eren%es............................................A2
%.5
Gey)ord +ndex
#impleCursorAapter....................?-, ?2, -=4, -=9
#liing!anel....................................90, 92, 9=394
#liing!anel@emo.............................................9-
#pinner.......................................-=?, -==, -=4, 2?0
#FLite@atabase................................................-=-
#FLiteGpen)elper............................-?1, -=0, -=-
#tring................................................................-92
#ur$a%e)oler.............................................--?, --=
#ur$a%e)oler.Callba%k.............................--=, --A
#ur$a%e,ie>.................................................--?3--A
5estCase....................................................229, 2??
5est#uite..........................................................222
5est#uite/uiler..............................................222
5e;t#>it%her......................................................22
5e;t,ie>. .21, =0, =?, =4, A0, AA, A2, -24, -22, -29,
-1?, -14
5hrea..............................................................-2=
5oast.........................................................201, 209
5ranslateAnimation.............21390, 92, 9?, 9A, 91
5ranslationAnimation......................................9=
5>itterWiget..................................A=3A4, 4=344
5W!re$s.......................................................A2, A9
5ypeArray....................................................-4, -1
"pate#ervi%e..............................................A4, A1
"ri..........................................99, -00, 2-A32-1, 22-
,ieo@emo......................................................-01
,ieo,ie>.................................................-0A, -04
,ie>. .?03?2, ?A, ?4, ?2, =0, =2, =?, =4, =9, A0, A1,
A2, 44, 22, 9=, 2?2, 2??
,ie>.GnCli%kListener.......................................-2
,ie>Animator...................................................22
,ie>(lipper.......................................................22
,ie>Wrapper...................................................-A2
,olumeManager...............................................-9A
,olumiCer..................................................-9?, -9A
Wake$ul.ntent#ervi%e........................-2?, -2A, -21
WakeLo%k...........................................-20, -2?3-2A
Web#ettings.........................................................-
Web,ie>.........................................-, 2, =, 1, 9, -0
Web,ie>Client....................................................-
Wiget!rovier.................................................4-
Command......................................
ab push...........................................................-01
ra>9pat%h............................................12, 19, 2?
mks%ar..........................................................-01
s<lite?..................................................-?1, -?9, -=-
Constant.........................................
AC5.G0R!.CK..........................................2-4, 2-1
AC5.G0R5A8..................................................220
AC5.G0R,.BW................................................2-1
AL5BR0A5.,B.................................................22-
/.0@RA"5GRCRBA5B....................................20-
CA5B8GRDRAL5BR0A5.,B...................220, 22-
@B(A"L5RCA5B8GRD....................................22-
MA5C)R@B(A"L5RG0LD..............................22-
RB#"L5RGK..............................................2-4, 2-1
*ethod...........................................
a%<uire&'...........................................................-2=
a%<uire#tati%Lo%k&'..................................-2?, -2A
%$6
Gey)ord +ndex
a(ooter,ie>&'...............................................?2
a)eaer,ie>&'..............................................?2
a.ntentGptions&'.................................2203222
a+avas%ript.nter$a%e&'.............................2, =, 4
a#e%tion&'......................................................?A
areAll.tems#ele%table&'....................................?0
bin#ervi%e&'....................................2003202, 204
buil(ooter&'.....................................................=0
buil)eaer&'...................................................=0
buil"pate&'..............................................A4, A1
%reate&'.............................................................-0=
elete&'..............................................................-?A
o.n/a%kgroun&'...........................................-20
enable&'............................................................-99
eval&'..........................................................201, 2--
e;e%#FL&'..................................................-=-, -=2
e;e%ute#%ript&'.................................201, 202, 2-0
$ailure&'............................................................209
$in,ie>/y.&'..................................................A1
getA%tivity&'.....................................................2?0
getColumnCount&'..........................................-A4
getColumn.ne;&'...........................................-A4
getConte;t&'.....................................................2??
getCount&'.........................................................?A
get)oler&'.......................................................--=
get.nt&'........................................................-4, -A4
get.tem&'............................................................?A
get.tem,ie>5ype&'......................................?A, ?4
get+oin&'.....................................................-A1, -A2
getLo%k&'..........................................................-2?
get!a%kageManager&'.....................................222
get#ystem#ervi%e&'............................-2=, -19, -22
get,ie>&'......................................................?2, ?A
get,ie>5ypeCount&'...................................?A, ?4
hanle.nstallBrror&'.........................................-=-
initMeter&'........................................................-9A
insert&'..............................................................-?A
isBnable&'........................................................?0
is0ull&'..............................................................-A4
loaAnimation&'...............................................9=
loa"rl&'..........................................................1, 9
obtain#tyleAttributes&'...................................-4
onA%%ura%yChange&'.....................................-2A
onA%tivityResult&'...........................................2-4
onAnimationBn&'...........................................9=
on/in&'...........................................................-99
onCli%k&'............................................................-9
onCreate&'.....................-0=, --=, -=-, -2=, -2A, -9A
on@elete&'.................................................4A, 44
on@estroy&'................................................40, -2A
on@isable&'......................................................4A
onBnable&'.......................................................4A
on(inish.n$late&'...........................................-4, -1
on)anle.ntent&'...............................A4, -2A, -21
on.tem#ele%te&'..............................................=4
onKey@o>n&'........................................40, 4-, --1
onLo%ationChange&'........................................2
on0othing#ele%te&'........................................=4
on!ause&'.........................................................-1=
on!i%ture5aken&'.............................................--9
%$-
Gey)ord +ndex
onRe%eive&'............................4A, 44, -10, -22, -2A
onResume&'......................................................-1=
on#ensorChange&'.........................................-2A
on#ervi%eConne%te&'.............................200, 20-
on#ervi%e@is%onne%te&'........................200, 20-
on#tart&'....................................................-2=, -2A
on"pate&'............................................AA, 4=, 4A
on"pgrae&'.....................................................-=-
open&'................................................................--?
pause&'.......................................................-0-, -0=
play&'................................................................-0=
prepare&'....................................................-0-, -0=
prepareAsyn%&'.................................................-0-
<uery&'..............................................................-?A
<uery.ntentA%tivityGptions&'........................222
re%y%le&'..............................................................-1
registerListener&'.............................................-2A
registerRe%eiver&'........................-42, -49, -1-, -1?
release&'...............................................-0A, --A, -2?
re<uery&'....................................................-A1, -A2
runGn"i5hrea&'...........................................209
senKeys&'........................................................2?-
setAnimationListener&'....................................9=
set@ata#our%e&'...............................................-00
set@uration&'....................................................92
set.nterpolator&'...............................................94
setMa;&'...........................................................-9A
setGnCli%k!ening.ntent&'..............................A2
setGn.tem#ele%teListener&'...........................=?
set!i%ture(ormat&'...........................................--1
set!revie>@isplay&'.........................................--=
set!rogress&'....................................................-9A
setRepeating&'..................................................-22
setResult&'..........................................................4-
set5e;t,ie>5e;t&'.............................................A2
set5ype&'...........................................................--=
setup&'.......................................................-0=, -0A
set"p&'......................................................2?0, 2??
set,isibility&'..............................................29, 9=
shaking#tarte&'...............................................-?-
shaking#toppe&'.............................................-?-
start&'................................................................-0-
startA%tivity(orResult&'.............................A9, 2-4
startAnimation&'.........................................22, 92
start!revie>&'...................................................--A
start#ervi%e&'.......................................A4, -10, -2A
steerLe$t&'.........................................................-22
steerRight&'......................................................-22
stop&'..................................................-0-, -0=, -0A
stop!revie>&'....................................................--A
su%%ess&'..........................................................209
sur$a%eChange&'.............................................--A
sur$a%eCreate&'...............................................--=
sur$a%e@estroye&'...........................................--A
take!i%ture&'.....................................................--2
tear@o>n&'......................................................2?0
toggle&'..............................................................90
to#tring&'.........................................................201
unbin#ervi%e&'...............................................20-
unregisterListener&'.........................................-2A
%$%
Gey)ord +ndex
upate&'............................................................-?A upateAppWiget&'..............................A4, 4-, 4A
%$.

Android Avanzado PDF

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Android Avanzado PDF

Uploaded by

Copyright:

Available Formats

The Busy Coder's Guide to Advanced Android

You might also like