The Busy Coders Guide to Android          Development         by Mark L. Murphy
The Busy Coders Guide to Android Developmentby Mark L. MurphyCopyright © 2008 CommonsWare, LLC. All Rights Reserved.Printe...
Table of ContentsWelcome to the Warescription!...............................................................................
And Now, The Rest of the Story...............................................................................................
Concepts and Properties...............................................................................................50  ...
Entertaining the Client......................................................................................................
Got the Picture?.............................................................................................................
Intent Routing...............................................................................................................
Notify-On-Change Support................................................................................................25...
Exercising Your Control......................................................................................................
Tour Update Activity...................................................................................................357...
Subscribe to updates at http://commonsware.com   Special Creative Commons BY-SA 3.0 License Edition
Welcome to the Warescription!We hope you enjoy this ebook and its updates – keep tabs on theWarescription feed off the Com...
•    You may wish to drop your font size to level 2 for easier reading     •    Source code listings are incorporated as g...
PrefaceWelcome to the Book!Thanks!Thanks for your interest in developing applications for Android!Increasingly, people wil...
The book does not cover in any detail how to download or install theAndroid development tools, either the Eclipse IDE flav...
Book Bug BountyFind a problem in one of our books? Let us know!Be the first to report a unique concrete problem, and well ...
Source Code LicenseThe source code samples shown in this book are available for downloadfrom the CommonsWare Web site. All...
PART I – Core ConceptsSubscribe to updates at http://commonsware.com   Special Creative Commons BY-SA 3.0 License Edition
Subscribe to updates at http://commonsware.com   Special Creative Commons BY-SA 3.0 License Edition
CHAPTER 1                                                     The Big PictureAndroid devices, by and large, will be mobile...
The Big Picture     •    Pointing devices, if they exist, are annoying (as anyone who has lost          their stylus will ...
The Big Picture     •    You get a fairly rigid and uncommon framework in which your          programs need to run so they...
The Big PictureContent ProvidersContent providers provide a level of abstraction for any data stored on thedevice that is ...
The Big PictureStuff At Your DisposalStorageYou can package data files with your application, for things that do notchange...
The Big PicturePhone ServicesAnd, of course, Android devices are typically phones, allowing your softwareto initiate calls...
CHAPTER 2                                                 Project StructureThe Android build system is organized around a ...
Project StructureThe Sweat Off Your BrowWhen you created the project (e.g., via activityCreator.py), you suppliedthe fully...
Project StructureWhat You Get Out Of ItWhen you compile your project (via ant or the IDE), the results go into thebin/ dir...
Subscribe to updates at http://commonsware.com   Special Creative Commons BY-SA 3.0 License Edition
CHAPTER 3                                          Inside the ManifestThe foundation for any Android application is the ma...
Inside the Manifest<manifest xmlns:android="http://schemas.android.com/apk/res/android"  package="com.commonsware.android....
Inside the Manifest<manifest xmlns:android="http://schemas.android.com/apk/res/android"  package="com.commonsware.android"...
Inside the Manifestwill be displayed. The stock activity element sets up your activity to appearin the launcher, so users ...
PART II – ActivitiesSubscribe to updates at http://commonsware.com   Special Creative Commons BY-SA 3.0 License Edition
Subscribe to updates at http://commonsware.com   Special Creative Commons BY-SA 3.0 License Edition
CHAPTER 4  Creating a Skeleton ApplicationEvery programming language or environment book starts off with the ever-popular ...
Creating a Skeleton Applicationyou want to create and a --out switch indicating where the project filesshould be generated...
Creating a Skeleton Application        updateTime();        setContentView(btn);    }    public void onClick(View view) { ...
Creating a Skeleton Applicationto trap all button clicks just within the activity itself, we also have theactivity class i...
Creating a Skeleton ApplicationWhen we open the activity (onCreate()) or when the button is clicked(onClick()), we update ...
Creating a Skeleton ApplicationYou should see an activity screen akin to:                          Figure 2. The Now demon...
CHAPTER 5                     Using XML-Based LayoutsWhile it is technically possible to create and attach widgets to our ...
Using XML-Based LayoutsAndroids SDK ships with a tool (aapt) which uses the layouts. This toolshould be automatically invo...
Using XML-Based LayoutsOK, So What Does It Look Like?Here is the Button from the previous chapters sample application, con...
Using XML-Based LayoutsSince this single widget is the only content in our activitys view, we onlyneed this single element...
Using XML-Based Layoutsfrom our layout, is accessed from that code-generated R class. All of thelayouts are accessible und...
Using XML-Based Layouts        updateTime();    }    private void updateTime() {      btn.setText(new Date().toString()); ...
CHAPTER 6                       Employing Basic WidgetsEvery GUI toolkit has some basic widgets: fields, labels, buttons, ...
Employing Basic Widgets     •    android:textColor to set the           color of the labels text, in RGB hex          form...
Employing Basic WidgetsFleeting ImagesAndroid has two widgets to help you embed images in your activities:ImageView and Im...
Employing Basic Widgetsshrouded password input, and android:phoneNumber for entering in phonenumbers. If you want to creat...
Employing Basic WidgetsThe result, once built and installed into the emulator, is:                        Figure 5. The Fi...
Employing Basic WidgetsJust Another Box to CheckThe classic checkbox has two states: checked and unchecked. Clicking thech...
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Busy codersguidetoandroid
Upcoming SlideShare
Loading in …5
×

Busy codersguidetoandroid

3,183 views

Published on

Nice book..

Published in: Technology, News & Politics
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
3,183
On SlideShare
0
From Embeds
0
Number of Embeds
5
Actions
Shares
0
Downloads
15
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

Busy codersguidetoandroid

  1. 1. The Busy Coders Guide to Android Development by Mark L. Murphy
  2. 2. The Busy Coders Guide to Android Developmentby Mark L. MurphyCopyright © 2008 CommonsWare, LLC. All Rights Reserved.Printed in the United States of America.CommonsWare books may be purchased in printed (bulk) or digital form for educational orbusiness use. For more information, contact direct@commonsware.com.Printing History: Jul 2008: Version 1.0 ISBN: 978-0-9816780-0-9The CommonsWare name and logo, “Busy Coders Guide”, and related trade dress aretrademarks of CommonsWare, LLC.All other trademarks referenced in this book are trademarks of their respective firms.The publisher and author(s) assume no responsibility for errors or omissions or for damagesresulting from the use of the information contained herein.Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  3. 3. Table of ContentsWelcome to the Warescription!..................................................................................xiiiPreface..........................................................................................................................xv Welcome to the Book!...........................................................................................................xv Prerequisites..........................................................................................................................xv Warescription.......................................................................................................................xvi Book Bug Bounty.................................................................................................................xvii Source Code License..........................................................................................................xviii Creative Commons and the Four-to-Free (42F) Guarantee............................................xviiiThe Big Picture................................................................................................................1 What Androids Are Made Of.................................................................................................3 Activities...........................................................................................................................3 Content Providers...........................................................................................................4 Intents..............................................................................................................................4 Services.............................................................................................................................4 Stuff At Your Disposal.............................................................................................................5 Storage..............................................................................................................................5 Network............................................................................................................................5 Multimedia.......................................................................................................................5 GPS...................................................................................................................................5 Phone Services.................................................................................................................6Project Structure............................................................................................................7 Root Contents..........................................................................................................................7 The Sweat Off Your Brow.......................................................................................................8 iiiSubscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  4. 4. And Now, The Rest of the Story.............................................................................................8 What You Get Out Of It.........................................................................................................9Inside the Manifest........................................................................................................11 In The Beginning, There Was the Root, And It Was Good.................................................11 Permissions, Instrumentations, and Applications (Oh, My!).............................................12 Your Application Does Something, Right?..........................................................................13Creating a Skeleton Application...................................................................................17 Begin at the Beginning...........................................................................................................17 The Activity............................................................................................................................18 Dissecting the Activity...........................................................................................................19 Building and Running the Activity.......................................................................................21Using XML-Based Layouts............................................................................................23 What Is an XML-Based Layout?...........................................................................................23 Why Use XML-Based Layouts?............................................................................................24 OK, So What Does It Look Like?..........................................................................................25 Whats With the @ Signs?....................................................................................................26 And We Attach These to the Java...How?...........................................................................26 The Rest of the Story.............................................................................................................27Employing Basic Widgets.............................................................................................29 Assigning Labels....................................................................................................................29 Button, Button, Whos Got the Button?..............................................................................30 Fleeting Images......................................................................................................................31 Fields of Green. Or Other Colors..........................................................................................31 Just Another Box to Check....................................................................................................34 Turn the Radio Up.................................................................................................................37 Its Quite a View....................................................................................................................39 Useful Properties...........................................................................................................39 Useful Methods..............................................................................................................39Working with Containers.............................................................................................41 Thinking Linearly..................................................................................................................42 Concepts and Properties...............................................................................................42 Example..........................................................................................................................45 All Things Are Relative.........................................................................................................50 ivSubscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  5. 5. Concepts and Properties...............................................................................................50 Example..........................................................................................................................53 Tabula Rasa............................................................................................................................56 Concepts and Properties...............................................................................................56 Example..........................................................................................................................59 Scrollwork..............................................................................................................................60Using Selection Widgets...............................................................................................65 Adapting to the Circumstances............................................................................................65 Using ArrayAdapter......................................................................................................66 Other Key Adapters.......................................................................................................67 Lists of Naughty and Nice....................................................................................................68 Spin Control...........................................................................................................................70 Grid Your Lions (Or Something Like That...).....................................................................74 Fields: Now With 35% Less Typing!.....................................................................................78 Galleries, Give Or Take The Art...........................................................................................82Employing Fancy Widgets and Containers..................................................................83 Pick and Choose....................................................................................................................83 Time Keeps Flowing Like a River.........................................................................................88 Making Progress....................................................................................................................89 Putting It On My Tab...........................................................................................................90 The Pieces.......................................................................................................................91 The Idiosyncrasies..........................................................................................................91 Wiring It Together........................................................................................................93 Other Containers of Note.....................................................................................................96Applying Menus............................................................................................................97 Flavors of Menu.....................................................................................................................97 Menus of Options.................................................................................................................98 Menus in Context................................................................................................................100 Taking a Peek.......................................................................................................................102Embedding the WebKit Browser................................................................................107 A Browser, Writ Small.........................................................................................................107 Loading It Up.......................................................................................................................109 Navigating the Waters..........................................................................................................111 vSubscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  6. 6. Entertaining the Client.........................................................................................................111 Settings, Preferences, and Options (Oh, My!)....................................................................114Showing Pop-Up Messages..........................................................................................117 Raising Toasts........................................................................................................................117 Alert! Alert!............................................................................................................................118 Checking Them Out.............................................................................................................119Dealing with Threads..................................................................................................123 Getting Through the Handlers............................................................................................123 Messages.......................................................................................................................124 Runnables.....................................................................................................................127 Running In Place..................................................................................................................127 Utilities (And I Dont Mean Water Works).......................................................................128 And Now, The Caveats........................................................................................................128Handling Activity Lifecycle Events..............................................................................131 Schroedingers Activity.........................................................................................................131 Life, Death, and Your Activity.............................................................................................132 onCreate() and onCompleteThaw()............................................................................132 onStart(), onRestart(), and onResume().....................................................................133 onPause(), onFreeze(), onStop(), and onDestroy()...................................................134Using Preferences........................................................................................................137 Getting What You Want......................................................................................................137 Stating Your Preference.......................................................................................................138 A Preference For Action......................................................................................................138Accessing Files.............................................................................................................143 You And The Horse You Rode In On.................................................................................143 Readin n Writin.................................................................................................................147Working with Resources..............................................................................................151 The Resource Lineup............................................................................................................151 String Theory........................................................................................................................152 Plain Strings..................................................................................................................152 String Formats..............................................................................................................153 Styled Text.....................................................................................................................153 Styled Formats..............................................................................................................154 viSubscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  7. 7. Got the Picture?...................................................................................................................158 XML: The Resource Way.....................................................................................................160 Miscellaneous Values...........................................................................................................163 Dimensions...................................................................................................................163 Colors............................................................................................................................164 Arrays............................................................................................................................165 Different Strokes for Different Folks..................................................................................166Managing and Accessing Local Databases...................................................................171 A Quick SQLite Primer........................................................................................................172 Start at the Beginning..........................................................................................................173 Setting the Table..................................................................................................................174 Makin Data..........................................................................................................................174 What Goes Around, Comes Around...................................................................................176 Raw Queries..................................................................................................................176 Regular Queries............................................................................................................177 Building with Builders.................................................................................................177 Using Cursors...............................................................................................................179 Change for the Sake of Change...................................................................................179 Making Your Own Cursors..........................................................................................180 Data, Data, Everywhere.......................................................................................................180Leveraging Java Libraries............................................................................................183 The Outer Limits..................................................................................................................183 Ants and Jars........................................................................................................................184Communicating via the Internet................................................................................187 REST and Relaxation............................................................................................................187 HTTP Operations via Apache Commons...................................................................188 Parsing Responses........................................................................................................190 Stuff To Consider.........................................................................................................192 Email over Java.....................................................................................................................193Creating Intent Filters................................................................................................199 Whats Your Intent?............................................................................................................200 Pieces of Intents..........................................................................................................200 Stock Options...............................................................................................................201 viiSubscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  8. 8. Intent Routing.............................................................................................................202 Stating Your Intent(ions)....................................................................................................203 Narrow Receivers.................................................................................................................205Launching Activities and Sub-Activities.....................................................................207 Peers and Subs.....................................................................................................................208 Start Em Up........................................................................................................................208 Make an Intent............................................................................................................209 Make the Call...............................................................................................................209Finding Available Actions via Introspection...............................................................215 Pick Em................................................................................................................................216 Adaptable Adapters.............................................................................................................220 Would You Like to See the Menu?.....................................................................................223 Asking Around.....................................................................................................................225Using a Content Provider...........................................................................................229 Pieces of Me.........................................................................................................................229 Getting a Handle.................................................................................................................230 Makin Queries.....................................................................................................................231 Adapting to the Circumstances..........................................................................................233 Doing It By Hand.................................................................................................................235 Position.........................................................................................................................235 Getting Properties.......................................................................................................236 Setting Properties........................................................................................................237 Give and Take......................................................................................................................238 Beware of the BLOB!...........................................................................................................239Building a Content Provider.......................................................................................241 First, Some Dissection.........................................................................................................241 Next, Some Typing..............................................................................................................242 Step #1: Create a Provider Class..........................................................................................243 ContentProvider..........................................................................................................243 DatabaseContentProvider...........................................................................................252 Step #2: Supply a Uri...........................................................................................................252 Step #3: Declare the Properties..........................................................................................252 Step #4: Update the Manifest.............................................................................................253 viiiSubscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  9. 9. Notify-On-Change Support................................................................................................254Requesting and Requiring Permissions.....................................................................257 Mother, May I?....................................................................................................................258 Halt! Who Goes There?.......................................................................................................259 Enforcing Permissions via the Manifest....................................................................260 Enforcing Permissions Elsewhere...............................................................................261 May I See Your Documents?...............................................................................................262Creating a Service........................................................................................................263 Getting Buzzed....................................................................................................................264 Service with Class................................................................................................................264 When IPC Attacks!..............................................................................................................266 Write the AIDL............................................................................................................267 Implement the Interface.............................................................................................268 Manifest Destiny.................................................................................................................270 Wheres the Remote?...........................................................................................................271Invoking a Service.......................................................................................................273 Bound for Success...............................................................................................................274 Request for Service..............................................................................................................276 Prometheus Unbound.........................................................................................................276 Manual Transmission..........................................................................................................276Alerting Users Via Notifications.................................................................................279 Types of Pestering...............................................................................................................279 Hardware Notifications..............................................................................................280 Icons..............................................................................................................................281 Letting Your Presence Be Felt.............................................................................................281Accessing Location-Based Services.............................................................................287 Location Providers: They Know Where Youre Hiding....................................................288 Finding Yourself..................................................................................................................288 On the Move........................................................................................................................292 Are We There Yet? Are We There Yet? Are We There Yet?............................................292 Testing...Testing..................................................................................................................296Mapping with MapView and MapActivity..................................................................299 The Bare Bones....................................................................................................................299 ixSubscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  10. 10. Exercising Your Control.......................................................................................................301 Zoom.............................................................................................................................301 Center...........................................................................................................................302 Reticle...........................................................................................................................303 Traffic and Terrain...............................................................................................................303 Follow You, Follow Me........................................................................................................305 Layers Upon Layers.............................................................................................................307 Overlay Classes............................................................................................................308 Drawing the Overlay...................................................................................................308 Handling Screen Taps..................................................................................................310Playing Media..............................................................................................................313 Get Your Media On..............................................................................................................314 Making Noise........................................................................................................................315 Moving Pictures....................................................................................................................321Handling Telephone Calls..........................................................................................325 No, No, No – Not That IPhone...........................................................................................326 Whats Our Status?..............................................................................................................326 You Make the Call!..............................................................................................................326Searching with SearchManager...................................................................................333 Hunting Season....................................................................................................................333 Search Yourself.....................................................................................................................335 Craft the Search Activity.............................................................................................336 Update the Manifest....................................................................................................340 Try It Out.....................................................................................................................342The TourIt Sample Application..................................................................................347 Installing TourIt..................................................................................................................347 Demo Location Provider.............................................................................................347 SD Card Image with Sample Tour..............................................................................348 Running TourIt....................................................................................................................349 Main Activity................................................................................................................350 Configuration Activity.................................................................................................352 Cue Sheet Activity.......................................................................................................354 Map Activity.................................................................................................................355 xSubscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  11. 11. Tour Update Activity...................................................................................................357 Help Activity................................................................................................................358 TourIts Manifest.................................................................................................................359 TourIts Content..................................................................................................................360 Data Storage.................................................................................................................361 Content Provider..........................................................................................................361 Model Classes...............................................................................................................361 TourIts Activities................................................................................................................362 TourListActivity...........................................................................................................362 TourViewActivity.........................................................................................................363 TourMapActivity..........................................................................................................367 TourEditActivity..........................................................................................................367 HelpActivity.................................................................................................................367 ConfigActivity..............................................................................................................368 xiSubscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  12. 12. Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  13. 13. Welcome to the Warescription!We hope you enjoy this ebook and its updates – keep tabs on theWarescription feed off the CommonsWare site to learn when new editionsof this book, or other books in your Warescription, are available.All editions of CommonsWare titles, print and ebook, follow a software-style numbering system. Major releases (1.0, 2.0, etc.) are available in bothprint and ebook; minor releases (0.1, 0.9, etc.) are available in ebook formfor Warescription subscribers only. Releases ending in .9 are "releasecandidates" for the next major release, lacking perhaps an index butotherwise being complete.Each Warescription ebook is licensed for the exclusive use of its subscriberand is tagged with the subscribers name. We ask that you not distributethese books. If you work for a firm and wish to have several employees haveaccess, enterprise Warescriptions are available. Just contact us atenterprise@commonsware.com.Also, bear in mind that eventually this edition of this title will be releasedunder a Creative Commons license – more on this in the preface.Remember that the CommonsWare Web site has errata and resources (e.g.,source code) for each of our titles. Just visit the Web page for the book youare interested in and follow the links.Some notes for Kindle users: xiiiSubscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  14. 14. • You may wish to drop your font size to level 2 for easier reading • Source code listings are incorporated as graphics so as to retain the monospace font, though this means the source code listings do not honor changes in Kindle font size xivSubscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  15. 15. PrefaceWelcome to the Book!Thanks!Thanks for your interest in developing applications for Android!Increasingly, people will access Internet-based services using so-called"non-traditional" means, such as mobile devices. The more we do in thatspace now, the more that people will help invest in that space to make iteasier to build more powerful mobile applications in the future. Android isnew – at the time of this writing, there are no shipping Android-powereddevices – but it likely will rapidly grow in importance due to the size andscope of the Open Handset Alliance.And, most of all, thanks for your interest in this book! I sincerely hope youfind it useful and at least occasionally entertaining.PrerequisitesIf you are interested in programming for Android, you will need at leastbasic understanding of how to program in Java. Android programming isdone using Java syntax, plus a class library that resembles a subset of theJava SE library (plus Android-specific extensions). If you have notprogrammed in Java before, you probably should quick learn how thatworks before attempting to dive into programming for Android. xvSubscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  16. 16. The book does not cover in any detail how to download or install theAndroid development tools, either the Eclipse IDE flavor or the standaloneflavor. The Android Web site covers this quite nicely. The material in thebook should be relevant whether you use the IDE or not. You shoulddownload, install, and test out the Android development tools from theAndroid Web site before trying any of the examples listed in this book.Some chapters may reference material in previous chapters, though usuallywith a link back to the preceding section of relevance.WarescriptionThis book will be published both in print and in digital (ebook) form. Theebook versions of all CommonsWare titles are available via an annualsubscription – the Warescription.The Warescription entitles you, for the duration of your subscription, toebook forms of all CommonsWare titles, not just the one you are reading.Presently, CommonsWare offers PDF and Kindle; other ebook formats willbe added based on interest and the openness of the format.Each subscriber gets personalized editions of all editions of each title: boththose mirroring printed editions and in-between updates that are onlyavailable in ebook form. That way, your ebooks are never out of date forlong, and you can take advantage of new material as it is made availableinstead of having to wait for a whole new print edition. For example, whennew releases of the Android SDK are made available, this book will bequickly updated to be accurate with changes in the APIs.From time to time, subscribers will also receive access to subscriber-onlyonline material, both short articles and not-yet-published new titles.Also, if you own a print copy of a CommonsWare book, and it is in goodclean condition with no marks or stickers, you can exchange that copy for adiscount off the Warescription price.If you are interested in a Warescription, visit the Warescription section ofthe CommonsWare Web site. xviSubscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  17. 17. Book Bug BountyFind a problem in one of our books? Let us know!Be the first to report a unique concrete problem, and well give you a couponfor a six-month Warescription as a bounty for helping us deliver a betterproduct. You can use that coupon to get a new Warescription, renew anexisting Warescription, or give the coupon to a friend, colleague, or somerandom person you meet on the subway.By "concrete" problem, we mean things like: • Typographical errors • Sample applications that do not work as advertised, in the environment described in the book • Factual errors that cannot be open to interpretationBy "unique", we mean ones not yet reported. Each book has an errata pageon the CommonsWare Web site; most known problems will be listed there.We appreciate hearing about "softer" issues as well, such as: • Places where you think we are in error, but where we feel our interpretation is reasonable • Places where you think we could add sample applications, or expand upon the existing material • Samples that do not work due to "shifting sands" of the underlying environment (e.g., changed APIs with new releases of an SDK)However, those "softer" issues do not qualify for the formal bounty program.Questions about the bug bounty, or problems you wish to report for bountyconsideration, should be sent to bounty@commonsware.com. xviiSubscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  18. 18. Source Code LicenseThe source code samples shown in this book are available for downloadfrom the CommonsWare Web site. All of the Android projects are licensedunder the Apache 2.0 License, in case you have the desire to reuse any of it.Creative Commons and the Four-to-Free(42F) GuaranteeEach CommonsWare book edition will be available for use under theCreative Commons Attribution-Noncommercial-Share Alike 3.0 license as ofthe fourth anniversary of its publication date, or when 4,000 copies of theedition have been sold, whichever comes first. That means that, once fouryears have elapsed (perhaps sooner!), you can use this prose for non-commercial purposes. That is our Four-to-Free Guarantee to our readers andthe broader community. For the purposes of this guarantee, newWarescriptions and renewals will be counted as sales of this edition, startingfrom the time the edition is published.This edition of this book will be available under the aforementionedCreative Commons license on July 1, 2012. Of course, watch theCommonsWare Web site, as this edition might be relicensed sooner basedon sales.For more details on the Creative Commons Attribution-Noncommercial-Share Alike 3.0 license, visit the Creative Commons Web site.Note that future editions of this book will become free on later dates, eachfour years from the publication of that edition or based on sales of thatspecific edition. Releasing one edition under the Creative Commons licensedoes not automatically release all editions under that license. xviiiSubscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  19. 19. PART I – Core ConceptsSubscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  20. 20. Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  21. 21. CHAPTER 1 The Big PictureAndroid devices, by and large, will be mobile phones. While the Androidtechnology is being discussed for use in other areas (e.g., car dashboard"PCs"), for the most part, you can think of Android as being used on phones.For developers, this has benefits and drawbacks.On the plus side, circa 2008, Android-style smartphones are sexy. OfferingInternet services over mobile devices dates back to the mid-1990s and theHandheld Device Markup Language (HDML). However, only in recent yearshave phones capable of Internet access taken off. Now, thanks to trends liketext messaging and to products like Apples iPhone, phones that can serve asInternet access devices are rapidly gaining popularity. So, working onAndroid applications gives you experience with an interesting technology(Android) in a fast-moving market segment (Internet-enabled phones),which is always a good thing.The problem comes when you actually have to program the darn things.Anyone with experience in programming for PDAs or phones has felt thepain of phones simply being small in all sorts of dimensions: • Screens are small (you wont get comments like, "is that a 24-inch LCD in your pocket, or...?") • Keyboards, if they exist, are small 1Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  22. 22. The Big Picture • Pointing devices, if they exist, are annoying (as anyone who has lost their stylus will tell you) or inexact (large fingers and "multi-touch" LCDs are not a good mix) • CPU speed and memory are tight compared to desktops and servers you may be used to • You can have any programming language and development framework you want, so long as it was what the device manufacturer chose and burned into the phones silicon • And so onMoreover, applications running on a phone have to deal with the fact thattheyre on a phone.People with mobile phones tend to get very irritated when those phonesdont work, which is why the "can you hear me now?" ad campaign fromVerizon Wireless has been popular for the past few years. Similarly, thosesame people will get irritated at you if your program "breaks" their phone: • ...by tying up the CPU such that calls cant be received • ...by not working properly with the rest of the phones OS, such that your application doesnt quietly fade to the background when a call comes in or needs to be placed • ...by crashing the phones operating system, such as by leaking memory like a sieveHence, developing programs for a phone is a different experience thandeveloping desktop applications, Web sites, or back-end server processes.You wind up with different-looking tools, different-behaving frameworks,and "different than youre used to" limitations on what you can do with yourprogram.What Android tries to do is meet you halfway: • You get a commonly-used programming language (Java) with some commonly used libraries (e.g., some Apache Commons APIs), with support for tools you may be used to (Eclipse) 2Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  23. 23. The Big Picture • You get a fairly rigid and uncommon framework in which your programs need to run so they can be "good citizens" on the phone and not interfere with other programs or the operation of the phone itselfAs you might expect, much of this book deals with that framework and howyou write programs that work within its confines and take advantage of itscapabilities.What Androids Are Made OfWhen you write a desktop application, you are "master of your owndomain". You launch your main window and any child windows – like dialogboxes – that are needed. From your standpoint, you are your own world,leveraging features supported by the operating system, but largely ignorantof any other program that may be running on the computer at the sametime. If you do interact with other programs, it is typically through an API,such as using JDBC (or frameworks atop it) to communicate with MySQL oranother database.Android has similar concepts, but packaged differently, and structured tomake phones more crash-resistant.ActivitiesThe building block of the user interface is the activity. You can think of anactivity as being the Android analogue for the window or dialog in a desktopapplication.While it is possible for activities to not have a user interface, most likely your"headless" code will be packaged in the form of content providers orservices, described below. 3Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  24. 24. The Big PictureContent ProvidersContent providers provide a level of abstraction for any data stored on thedevice that is accessible by multiple applications. The Android developmentmodel encourages you to make your own data available to otherapplications, as well as your own – building a content provider lets you dothat, while maintaining complete control over how your data gets accessed.IntentsIntents are system messages, running around the inside of the device,notifying applications of various events, from hardware state changes (e.g.,an SD card was inserted), to incoming data (e.g., an SMS message arrived),to application events (e.g., your activity was launched from the devicesmain menu). Not only can you respond to intents, but you can create yourown, to launch other activities, or to let you know when specific situationsarise (e.g., raise such-and-so intent when the user gets within 100 meters ofthis-and-such location).ServicesActivities, content providers, and intent receivers are all short-lived and canbe shut down at any time. Services, on the other hand, are designed to keeprunning, if needed, independent of any activity. You might use a service forchecking for updates to an RSS feed, or to play back music even if thecontrolling activity is no longer operating. 4Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  25. 25. The Big PictureStuff At Your DisposalStorageYou can package data files with your application, for things that do notchange, such as icons or help files. You also can carve out a small bit of spaceon the device itself, for databases or files containing user-entered orretrieved data needed by your application. And, if the user supplies bulkstorage, like an SD card, you can read and write files on there as needed.NetworkAndroid devices will generally be Internet-ready, through onecommunications medium or another. You can take advantage of the Internetaccess at any level you wish, from raw Java sockets all the way up to a built-inWebKit-based Web browser widget you can embed in your application.MultimediaAndroid devices have the ability to play back and record audio and video.While the specifics may vary from device to device, you can query the deviceto learn its capabilities and then take advantage of the multimediacapabilities as you see fit, whether that is to play back music, take pictureswith the camera, or use the microphone for audio note-taking.GPSAndroid devices will frequently have access to location providers, such asGPS, that can tell your applications where the device is on the face of theEarth. In turn, you can display maps or otherwise take advantage of thelocation data, such as tracking a devices movements if the device has beenstolen. 5Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  26. 26. The Big PicturePhone ServicesAnd, of course, Android devices are typically phones, allowing your softwareto initiate calls, send and receive SMS messages, and everything else youexpect from a modern bit of telephony technology. 6Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  27. 27. CHAPTER 2 Project StructureThe Android build system is organized around a specific directory treestructure for your Android project, much like any other Java project. Thespecifics, though, are fairly unique to Android and what it all does toprepare the actual application that will run on the device or emulator. Heresa quick primer on the project structure, to help you make sense of it all,particularly for the sample code referenced in this book.Root ContentsWhen you create a new Android project (e.g., via activityCreator.py), youget five key items in the projects root directory: • AndroidManifest.xml, which is an XML file describing the application being built and what components – activities, services, etc. – are being supplied by that application • build.xml, which is an Ant script for compiling the application and installing it on the device • bin/, which holds the application once it is compiled • src/, which holds the Java source code for the application • res/, which holds "resources", such as icons, GUI layouts, and the like, that get packaged with the compiled Java in the application • assets/, which hold other static files you wish packaged with the application for deployment onto the device 7Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  28. 28. Project StructureThe Sweat Off Your BrowWhen you created the project (e.g., via activityCreator.py), you suppliedthe fully-qualified class name of the "main" activity for the application (e.g.,com.commonsware.android.SomeDemo). You will then find that your projectssrc/ tree already has the namespace directory tree in place, plus a stubActivity subclass representing your main activity (e.g., src/com/commonsware/android/SomeDemo.java). You are welcome to modify this file and add othersto the src/ tree as needed to implement your application.The first time you compile the project (e.g., via ant), out in the "main"activitys namespace directory, the Android build chain will create R.java.This contains a number of constants tied to the various resources you placedout in the res/ directory tree. You should not modify R.java yourself, lettingthe Android tools handle it for you. You will see throughout many of thesamples where we reference things in R.java (e.g., referring to a layoutsidentifier via R.layout.main).And Now, The Rest of the StoryYou will also find that your project has a res/ directory tree. This holds"resources" – static files that are packaged along with your application,either in their original form or, occasionally, in a preprocessed form. Someof the subdirectories you will find or create under res/ include: • res/drawable/ for images (PNG, JPEG, etc.) • res/layout/ for XML-based UI layout specifications • res/raw/ for general-purpose files (e.g,. a CSV file of account information) • res/values/ for strings, dimensions, and the like • res/xml/ for other general-purpose XML files you wish to shipWe will cover all of these, and more, in later chapters of this book. 8Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  29. 29. Project StructureWhat You Get Out Of ItWhen you compile your project (via ant or the IDE), the results go into thebin/ directory under your project root. Specifically: • bin/classes/ holds the compiled Java classes • bin/classes.dex holds the executable created from those compiled Java classes • bin/yourapp.apk is the actual Android application (where yourapp is the name of your application)The .apk file is a ZIP archive containing the .dex file, the compiled edition ofyour resources (resources.arsc), any un-compiled resources (such as whatyou put in res/raw/) and the AndroidManifest.xml file. 9Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  30. 30. Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  31. 31. CHAPTER 3 Inside the ManifestThe foundation for any Android application is the manifest file:AndroidManifest.xml in the root of your project. Here is where you declarewhat all is inside your application – the activities, the services, and so on.You also indicate how these pieces attach themselves to the overall Androidsystem; for example, you indicate which activity (or activities) should appearon the devices main menu (a.k.a., launcher).When you create your application, you will get a starter manifest generatedfor you. For a simple application, offering a single activity and nothing else,the auto-generated manifest will probably work out fine, or perhaps requirea few minor modifications. On the other end of the spectrum, the manifestfile for the Android API demo suite is over 1,000 lines long. Your productionAndroid applications will probably fall somewhere in the middle.Most of the interesting bits of the manifest will be described in greaterdetail in the chapters on their associated Android features. For example, theservice element will be described in greater detail in the chapter on creatingservices. For now, we just need to understand what the role of the manifestis and its general overall construction.In The Beginning, There Was the Root, And ItWas GoodThe root of all manifest files is, not surprisingly, a manifest element: 11Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  32. 32. Inside the Manifest<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.commonsware.android.search">...</manifest>Note the namespace declaration. Curiously, the generated manifests onlyapply it on the attributes, not the elements (e.g., its manifest, notandroid:manifest). However, that pattern works, so unless Android changes,stick with their pattern.The biggest piece of information you need to supply on the manifestelement is the package attribute (also curiously not-namespaced). Here, youcan provide the name of the Java package that will be considered the "base"of your application. Then, everywhere else in the manifest file that needs aclass name, you can just substitute a leading dot as shorthand for thepackage. For example, if you needed to refer tocom.commonsware.android.Snicklefritz in this manifest shown above, youcould just use .Snicklefritz, since com.commonsware.android is defined as theapplications package.Permissions, Instrumentations, and Applica-tions (Oh, My!)Underneath the manifest element, you will find: • uses-permission elements, to indicate what permissions your application will need in order to function properly – see the chapter on permissions for more details • permission elements, to declare permissions that activities or services might require other applications hold in order to use your applications data or logic – again, more details are forthcoming in the chapter on permissions • instrumentation elements, to indicate code that should be invoked on key system events, such as starting up activities, for the purposes of logging or monitoring • an application element, defining the guts of the application that the manifest describes 12Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  33. 33. Inside the Manifest<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.commonsware.android"> <uses-permission android:name="android.permission.ACCESS_LOCATION" /> <uses-permission android:name="android.permission.ACCESS_GPS" /> <uses-permission android:name="android.permission.ACCESS_ASSISTED_GPS" /> <uses-permission android:name="android.permission.ACCESS_CELL_ID" /> <application>... </application></manifest>In the preceding example, the manifest has uses-permission elements toindicate some device capabilities the application will need – in this case,permissions to allow the application to determine its current location. And,there is the application element, whose contents will describe the activities,services, and whatnot that make up the bulk of the application itself.Your Application Does Something, Right?The real meat of the manifest file are the children of the applicationelement.By default, when you create a new Android project, you get a single activityelement:<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.commonsware.android.skeleton"> <application> <activity android:name=".Now" android:label="Now"> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter> </activity> </application></manifest>This element supplies android:name for the class implementing the activity,android:label for the display name of the activity, and (frequently) anintent-filter child element describing under what conditions this activity 13Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  34. 34. Inside the Manifestwill be displayed. The stock activity element sets up your activity to appearin the launcher, so users can choose to run it. As well see later in this book,you can have several activities in one project, if you so choose.You may also have one or more receiver elements, indicating non-activitiesthat should be triggered under certain conditions, such as when an SMSmessage comes in. These are called intent receivers and are described mid-way through the book.You may have one or more provider elements, indicating content providers –components that supply data to your activities and, with your permission,other activities in other applications on the device. These wrap up databasesor other data stores into a single API that any application can use. Later,well see how to create content providers and how to use content providersthat you or others create.Finally, you may have one or more service elements, describing services –long-running pieces of code that can operate independent of any activity.The quintessential example is the MP3 player, where you want the music tokeep playing even if the user pops open other activities and the MP3 playersuser interface is "misplaced". Two chapters late in the book cover how tocreate and use services. 14Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  35. 35. PART II – ActivitiesSubscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  36. 36. Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  37. 37. CHAPTER 4 Creating a Skeleton ApplicationEvery programming language or environment book starts off with the ever-popular "Hello, World!" demonstration: just enough of a program to proveyou can build things, not so much that you cannot understand what is goingon. However, the typical "Hello, World!" program has no interactivity (e.g.,just dumps the words to a console), and so is really boring.This chapter demonstrates a simple project, but one using Advanced Push-Button Technology™ and the current time, to show you how a simpleAndroid activity works.Begin at the BeginningTo work with anything in Android, you need a project. With ordinary Java, ifyou wanted, you could just write a program as a single file, compile it withjavac, and run it with java, without any other support structures. Android ismore complex, but to help keep it manageable, Google has supplied tools tohelp create the project. If you are using an Android-enabled IDE, such asEclipse with the Android plugin, you can create a project inside of the IDE(e.g., select File > New > Project, then choose Android > AndroidProject).If you are using tools that are not Android-enabled, you can use theactivityCreator.py script, found in the tools/ directory in your SDKinstallation. Just pass activityCreator.py the package name of the activity 17Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  38. 38. Creating a Skeleton Applicationyou want to create and a --out switch indicating where the project filesshould be generated. For example:./activityCreator.py --out /path/to/my/project/dir com.commonsware.android.NowYou will wind up with a handful of pre-generated files, as described in aprevious chapter.For the purposes of the samples shown in this book, you can download theirproject directories in a ZIP file on the CommonsWare Web site. Theseprojects are ready for use; you do not need to run activityCreator.py onthose unpacked samples.The ActivityYour projects src/ directory contains the standard Java-style tree ofdirectories based upon the Java package you chose when you created theproject (e.g., com.commonsware.android results insrc/com/commonsware/android/). Inside the innermost directory you shouldfind a pre-generated source file named Now.java, which where your firstactivity will go.Open Now.java in your editor and paste in the following code:package com.commonsware.android.skeleton;import android.app.Activity;import android.os.Bundle;import android.view.View;import android.widget.Button;import java.util.Date;public class Now extends Activity implements View.OnClickListener { Button btn; @Override public void onCreate(Bundle icicle) { super.onCreate(icicle); btn = new Button(this); btn.setOnClickListener(this); 18Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  39. 39. Creating a Skeleton Application updateTime(); setContentView(btn); } public void onClick(View view) { updateTime(); } private void updateTime() { btn.setText(new Date().toString()); }}Or, if you download the source files off the Web site, you can just use the Nowproject directly.Dissecting the ActivityLets examine this piece by piece:package com.commonsware.android.skeleton;import android.app.Activity;import android.os.Bundle;import android.view.View;import android.widget.Button;import java.util.Date;The package declaration needs to be the same as the one you used whencreating the project. And, like any other Java project, you need to import anyclasses you reference. Most of the Android-specific classes are in the androidpackage.Remember that not every Java SE class is available to Android programs!Visit the Android class reference to see what is and is not available.public class Now extends Activity implements View.OnClickListener { Button btn;Activities are public classes, inheriting from the android.Activity base class.In this case, the activity holds a button (btn). Since, for simplicity, we want 19Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  40. 40. Creating a Skeleton Applicationto trap all button clicks just within the activity itself, we also have theactivity class implement OnClickListener.@Overridepublic void onCreate(Bundle icicle) { super.onCreate(icicle); btn = new Button(this); btn.setOnClickListener(this); updateTime(); setContentView(btn);}The onCreate() method is invoked when the activity is started. The firstthing you should do is chain upward to the superclass, so the stock Androidactivity initialization can be done.In our implementation, we then create the button instance (newButton(this)), tell it to send all button clicks to the activity instance itself(via setOnClickListener()), call a private updateTime() method (see below),and then set the activitys content view to be the button itself (viasetContentView()).We will discuss that magical Bundle icicle in a later chapter. For themoment, consider it an opaque handle that all activities receive uponcreation.public void onClick(View view) { updateTime();}In Swing, a JButton click raises an ActionEvent, which is passed to theActionListener configured for the button. In Android, a button click causesonClick() to be invoked in the OnClickListener instance configured for thebutton. The listener is provided the view that triggered the click (in thiscase, the button). All we do here is call that private updateTime() method:private void updateTime() { btn.setText(new Date().toString());} 20Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  41. 41. Creating a Skeleton ApplicationWhen we open the activity (onCreate()) or when the button is clicked(onClick()), we update the buttons label to be the current time viasetText(), which functions much the same as the JButton equivalent.Building and Running the ActivityTo build the activity, either use your IDEs built-in Android packaging tool,or run ant in the base directory of your project. Then, to run the activity: • Launch the emulator (e.g., run tools/emulator from your Android SDK installation) • Install the package (e.g., run tools/adb install /path/to/this/example/bin/Now.apk from your Android SDK installation) • View the list of installed applications in the emulator and find the "Now" application Figure 1. The Android application "launcher" • Open that application 21Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  42. 42. Creating a Skeleton ApplicationYou should see an activity screen akin to: Figure 2. The Now demonstration activityClicking the button – in other words, pretty much anywhere on the phonesscreen – will update the time shown in the buttons label.Note that the label is centered horizontally and vertically, as those are thedefault styles applied to button captions. We can control that formatting,which will be covered in a later chapter.After you are done gazing at the awesomeness of Advanced Push-ButtonTechnology™, you can click the back button on the emulator to return to thelauncher. 22Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  43. 43. CHAPTER 5 Using XML-Based LayoutsWhile it is technically possible to create and attach widgets to our activitypurely through Java code, the way we did in the preceding chapter, the morecommon approach is to use an XML-based layout file. Dynamicinstantiation of widgets is reserved for more complicated scenarios, wherethe widgets are not known at compile-time (e.g., populating a column ofradio buttons based on data retrieved off the Internet).With that in mind, its time to break out the XML and learn out to lay outAndroid activity views that way.What Is an XML-Based Layout?As the name suggests, an XML-based layout is a specification of widgetsrelationships to each other – and to containers – encoded in XML format.Specifically, Android considers XML-based layouts to be resources, and assuch layout files are stored in the res/layout directory inside your Androidproject.Each XML file contains a tree of elements specifying a layout of widgets andcontainers that make up one View. The attributes of the XML elements areproperties, describing how a widget should look or how a container shouldbehave. For example, if a Button element has an attribute value ofandroid:textStyle = "bold", that means that the text appearing on the faceof the button should be rendered in a boldface font style. 23Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  44. 44. Using XML-Based LayoutsAndroids SDK ships with a tool (aapt) which uses the layouts. This toolshould be automatically invoked by your Android tool chain (e.g., Eclipse,Ants build.xml). Of particular importance to you as a developer is that aaptgenerates the R.java source file within your project, allowing you to accesslayouts and widgets within those layouts directly from your Java code, as willbe demonstrated .Why Use XML-Based Layouts?Most everything you do using XML layout files can be achieved through Javacode. For example, you could use setTypeface() to have a button render itstext in bold, instead of using a property in an XML layout. Since XMLlayouts are yet another file for you to keep track of, we need good reasons forusing such files.Perhaps the biggest reason is to assist in the creation of tools for viewdefinition, such as a GUI builder in an IDE like Eclipse or a dedicatedAndroid GUI designer like DroidDraw. Such GUI builders could, inprinciple, generate Java code instead of XML. The challenge is re-readingthe definition in to support edits – that is far simpler if the data is in astructured format like XML than in a programming language. Moreover,keeping the generated bits separated out from hand-written code makes itless likely that somebodys custom-crafted source will get clobbered byaccident when the generated bits get re-generated. XML forms a nice middleground between something that is easy for tool-writers to use and easy forprogrammers to work with by hand as needed.Also, XML as a GUI definition format is becoming more commonplace.Microsofts XAML, Adobes Flex, and Mozillas XUL all take a similarapproach to that of Android: put layout details in an XML file and putprogramming smarts in source files (e.g., Javascript for XUL). Many less-well-known GUI frameworks, such as ZK, also use XML for view definition.While "following the herd" is not necessarily the best policy, it does have theadvantage of helping to ease the transition into Android from any otherXML-centered view description language. 24Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  45. 45. Using XML-Based LayoutsOK, So What Does It Look Like?Here is the Button from the previous chapters sample application, convertedinto an XML layout file:<?xml version="1.0" encoding="utf-8"?><Button xmlns:android="http://schemas.android.com/apk/res/android" android:id="@+id/button" android:text="" android:layout_width="fill_parent" android:layout_height="fill_parent"/>The class name of the widget – Button – forms the name of the XMLelement. Since Button is an Android-supplied widget, we can just use thebare class name. If you create your own widgets as subclasses ofandroid.view.View, you would need to provide a full package declaration aswell (e.g., com.commonsware.android.MyWidget).The root element needs to declare the Android XML namespace:xmlns:android="http://schemas.android.com/apk/res/android"All other elements will be children of the root and will inherit thatnamespace declaration.Because we want to reference this button from our Java code, we need to giveit an identifier via the android:id attribute. We will cover this concept ingreater detail .The remaining attributes are properties of this Button instance: • android:text indicates the initial text to be displayed on the button face (in this case, an empty string) • android:layout_width and android:layout_height tell Android to have the buttons width and height fill the "parent", in this case the entire screen – these attributes will be covered in greater detail in a later chapter 25Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  46. 46. Using XML-Based LayoutsSince this single widget is the only content in our activitys view, we onlyneed this single element. Complex views will require a whole tree ofelements, representing the widgets and containers that control theirpositioning. All the remaining chapters of this book will use the XML layoutform whenever practical, so there are dozens of other examples of morecomplex layouts for you to peruse.Whats With the @ Signs?Many widgets and containers only need to appear in the XML layout file anddo not need to be referenced in your Java code. For example, a static label(TextView) frequently only needs to be in the layout file to indicate where itshould appear. These sorts of elements in the XML file do not need to havethe android:id attribute to give them a name.Anything you do want to use in your Java source, though, needs anandroid:id.The convention is to use @+id/... as the id value, where the ... representsyour locally-unique name for the widget in question. In the XML layoutexample in the preceding section, @+id/button is the identifier for the Buttonwidget.Android provides a few special android:id values, of the form@android:id/... – we will see some of these in various chapters of this book.And We Attach These to the Java...How?Given that you have painstakingly set up the widgets and containers for yourview in an XML layout file named snicklefritz.xml stored in res/layout, allyou need is one statement in your activitys onCreate() callback to use thatlayout:This is the same setLayoutView() we used earlier, passing it an instance of aView subclass (in that case, a Button). The Android-built View, constructed 26Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  47. 47. Using XML-Based Layoutsfrom our layout, is accessed from that code-generated R class. All of thelayouts are accessible under R.layout, keyed by the base name of the layoutfile – snicklefritz.xml results in R.layout.snicklefritz.To access our identified widgets, use findViewById(), passing it the numericidentifier of the widget in question. That numeric identifier was generatedby Android in the R class as R.id.something (where something is the specificwidget you are seeking). Those widgets are simply subclasses of View, justlike the Button instance we created in the previous chapter.The Rest of the StoryIn the original Now demo, the buttons face would show the current time,which would reflect when the button was last pushed (or when the activitywas first shown, if the button had not yet been pushed).Most of that logic still works, even in this revised demo ( NowRedux). However,rather than instantiating the Button in our activitys onCreate() callback, wecan reference the one from the XML layout:package com.commonsware.android.layouts;import android.app.Activity;import android.os.Bundle;import android.view.View;import android.widget.Button;import java.util.Date;public class NowRedux extends Activity implements View.OnClickListener { Button btn; @Override public void onCreate(Bundle icicle) { super.onCreate(icicle); setContentView(R.layout.main); btn=(Button)findViewById(R.id.button); btn.setOnClickListener(this); updateTime(); } public void onClick(View view) { 27Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  48. 48. Using XML-Based Layouts updateTime(); } private void updateTime() { btn.setText(new Date().toString()); }}The first difference is that rather than setting the content view to be a viewwe created in Java code, we set it to reference the XML layout(setContentView(R.layout.main)). The R.java source file will be updatedwhen we rebuild this project to include a reference to our layout file (storedas main.xml in our projects res/layout directory).The other difference is that we need to get our hands on our Button instance,for which we use the findViewById() call. Since we identified our button as@+id/button, we can reference the buttons identifier as R.id.button. Now,with the Button instance in hand, we can set the callback and set the label asneeded.The results look the same as with the original Now demo: Figure 3. The NowRedux sample activity 28Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  49. 49. CHAPTER 6 Employing Basic WidgetsEvery GUI toolkit has some basic widgets: fields, labels, buttons, etc.Androids toolkit is no different in scope, and the basic widgets will providea good introduction as to how widgets work in Android activities.Assigning LabelsThe simplest widget is the label, referred to in Android as a TextView. Like inmost GUI toolkits, labels are bits of text not editable directly by users.Typically, they are used to identify adjacent widgets (e.g., a "Name:" labelbefore a field where one fills in a name).In Java, you can create a label by creating a TextView instance. Morecommonly, though, you will create labels in XML layout files by adding aTextView element to the layout, with an android:text property to set thevalue of the label itself. If you need to swap labels based on certain criteria,such as internationalization, you may wish to use a resource reference in theXML instead, as will be described later in this book.TextView has numerous other properties of relevance for labels, such as: • android:typeface to set the typeface to use for the label (e.g., monospace) • android:textStyle to indicate that the typeface should be made bold (bold), italic (italic), or bold and italic (bold_italic) 29Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  50. 50. Employing Basic Widgets • android:textColor to set the color of the labels text, in RGB hex format (e.g., #FF0000 for red)For example, in the Label project, you will find the following layout file:<?xml version="1.0" encoding="utf-8"?><TextView xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="fill_parent" android:layout_height="wrap_content" android:text="You were expecting something profound?" />Just that layout alone, with the stub Java source provided by Androidsproject builder (e.g., activityCreator), gives you: Figure 4. The LabelDemo sample applicationButton, Button, Whos Got the Button?Weve already seen the use of the Button widget in the previous twochapters. As it turns out, Button is a subclass of TextView, so everythingdiscussed in the preceding section in terms of formatting the face of thebutton still holds. 30Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  51. 51. Employing Basic WidgetsFleeting ImagesAndroid has two widgets to help you embed images in your activities:ImageView and ImageButton. As the names suggest, they are image-basedanalogues to TextView and Button, respectively.Each widget takes an android:src attribute (in an XML layout) to specifywhat picture to use. These usually reference a drawable resource, describedin greater detail in the chapter on resources. You can also set the imagecontent based on a Uri from a content provider via setImageURI().ImageButton, a subclass of ImageView, mixes in the standard Button behaviors,for responding to clicks and whatnot.Fields of Green. Or Other Colors.Along with buttons and labels, fields are the third "anchor" of most GUItoolkits. In Android, they are implemented via the EditView widget, which isa subclass of the TextView used for labels.Along with the standard TextView properties (e.g., android:textStyle),EditView has many others that will be useful for you in constructing fields,including: • android:autoText, to control if the field should provide automatic spelling assistance • android:capitalize, to control if the field should automatically capitalize the first letter of entered text (e.g., first name, city) • android:digits, to configure the field to accept only certain digits • android:singleLine, to control if the field is for single-line input or multiple-line input (e.g., does <Enter> move you to the next widget or add a newline?)Beyond those, you can configure fields to use specialized input methods,such as android:numeric for numeric-only input, android:password for 31Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  52. 52. Employing Basic Widgetsshrouded password input, and android:phoneNumber for entering in phonenumbers. If you want to create your own input method scheme (e.g., postalcodes, Social Security numbers), you need to create your ownimplementation of the InputMethod interface, then configure the field to useit via android:inputMethod. You can see an example of this in the appendixdiscussing the TourIt sample application.For example, from the Field project, here is an XML layout file showing anEditView:<?xml version="1.0" encoding="utf-8"?><EditText xmlns:android="http://schemas.android.com/apk/res/android" android:id="@+id/field" android:layout_width="fill_parent" android:layout_height="fill_parent" android:singleLine="false" />Note that android:singleLine is false, so users will be able to enter in severallines of text.For this project, the FieldDemo.java file populates the input field with someprose:package com.commonsware.android.basic;import android.app.Activity;import android.os.Bundle;import android.widget.EditText;public class FieldDemo extends Activity { @Override public void onCreate(Bundle icicle) { super.onCreate(icicle); setContentView(R.layout.main); EditText fld=(EditText)findViewById(R.id.field); fld.setText("Licensed under the Apache License, Version 2.0 " + "(the "License"); you may not use this file " + "except in compliance with the License. You may " + "obtain a copy of the License at " + "http://www.apache.org/licenses/LICENSE-2.0"); }} 32Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  53. 53. Employing Basic WidgetsThe result, once built and installed into the emulator, is: Figure 5. The FieldDemo sample applicationNOTE: Androids emulator only allows one application in the launcher perunique Java package. Since all the demos in this chapter share thecom.commonsware.android.basic package, if you have the LabelDemoapplication installed, you will not see the FieldDemo application in thelauncher. To remove the LabelDemo application – or any application – useadb shell "rm /data/app/...", where ... is the name of the applicationsAPK file (e.g., LabelDemo.apk). Then, reinstall the formerly-hiddenapplication, and it will show up in the launcher.Another flavor of field is one that offers auto-completion, to help userssupply a value without typing in the whole text. That is provided in Androidas the AutoCompleteTextView widget, discussed in greater detail later in thisbook. 33Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition
  54. 54. Employing Basic WidgetsJust Another Box to CheckThe classic checkbox has two states: checked and unchecked. Clicking thecheckbox toggles between those states to indicate a choice (e.g., "Add rushdelivery to my order").In Android, there is a CheckBox widget to meet this need. It has TextView asan ancestor, so you can use TextView properties like android:textColor toformat the widget.Within Java, you can invoke: • isChecked() to determine if the checkbox has been checked • setChecked() to force the checkbox into a checked or unchecked state • toggle() to toggle the checkbox as if the user checked itAlso, you can register a listener object (in this case, an instance ofOnCheckedChangeListener) to be notified when the state of the checkboxchanges.For example, from the CheckBox project, here is a simple checkbox layout:<?xml version="1.0" encoding="utf-8"?><CheckBox xmlns:android="http://schemas.android.com/apk/res/android" android:id="@+id/check" android:layout_width="wrap_content" android:layout_height="wrap_content" android:text="This checkbox is: unchecked" />The corresponding CheckBoxDemo.java retrieves and configures the behaviorof the checkbox:public class CheckBoxDemo extends Activity implements CompoundButton.OnCheckedChangeListener { CheckBox cb; @Override public void onCreate(Bundle icicle) { super.onCreate(icicle); 34Subscribe to updates at http://commonsware.com Special Creative Commons BY-SA 3.0 License Edition

×