apress beginning android 3 (2011)

The Big Picture...of This Book Now that you have the Android big picture, here is what’s coming in the rest of this book: Android environment, through a series of step-by-step, tutorial

All rights reserved No part of this work may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or by any information storage or retrieval system, without the prior written permission of the copyright owner and the publisher

ISBN-13 (pbk): 978-1-4302-3297-1

ISBN-13 (electronic): 978-1-4302-3298-8

Trademarked names, logos, and images may appear in this book Rather than use a trademark symbol with every occurrence of a trademarked name, logo, or image we use the names, logos, and images only in an editorial fashion and to the benefit of the trademark owner, with no intention of infringement of the trademark

The use in this publication of trade names, trademarks, service marks, and similar terms, even if they are not identified as such, is not to be taken as an expression of opinion as to whether or not they are subject to proprietary rights

President and Publisher: Paul Manning

Lead Editor: Steve Anglin

Development Editor: Tom Welsh

Technical Reviewer: Dylan Philips

Editorial Board: Steve Anglin, Mark Beckner, Ewan Buckingham, Gary Cornell, Jonathan Gennick, Jonathan Hassell, Michelle Lowman, Matthew Moodie, James Markham, Jeff Olson, Jeffrey Pepper, Frank Pohlmann, Douglas Pundick, Ben Renow-Clarke, Dominic Shakeshaft, Matt Wade, Tom Welsh

Coordinating Editor: Jessica Belanger

Copy Editor: William McManus

Compositor: MacPS, LLC

Indexer: John Collin

Artist: April Milne

Cover Designer: Anna Ishchenko

Distributed to the book trade worldwide by Springer Science+Business Media, LLC., 233 Spring Street, 6th Floor, New York, NY 10013 Phone 1-800-SPRINGER, fax 201-348-4505, e-mail orders-ny@springer-sbm.com, or visit www.springeronline.com

For information on translations, please e-mail rights@apress.com, or visit www.apress.com Apress and friends of ED books may be purchased in bulk for academic, corporate, or

promotional use eBook versions and licenses are also available for most titles For more

information, reference our Special Bulk Sales–eBook Licensing web page at

www.apress.com/bulk-sales

The information in this book is distributed on an “as is” basis, without warranty Although every precaution has been taken in the preparation of this work, neither the author(s) nor Apress shall have any liability to any person or entity with respect to any loss or damage caused or alleged to

be caused directly or indirectly by the information contained in this work

The source code for this book is available to readers at www.apress.com

Contents

Part I: Core Concept 1

■ Chapter 1: The Big Picture 3

Benefits and Drawbacks of Smartphone Programming 3

What Androids Are Made Of 4

Stuff at Your Disposal 5

The Big Picture of This Book 6

■ Chapter 2: How to Get Started 7

Step 1: Set Up Java 7

Install the JDK 7

Learn Java 8

Step 2: Install the Android SDK 8

Install the Base Tools 8

Install the SDKs and Add-ons 9

Step 3: Install the ADT for Eclipse 12

Step 4: Install Apache Ant 14

Step 5: Set Up the Emulator 15

Step 6: Set Up the Device 21

Windows 21

Mac OS X and Linux 22

■ Chapter 3: Your First Android Project 23

Step 1: Create the New Project 23

Eclipse 23

Command Line 26

Step 2: Build, Install, and Run the Application in Your Emulator or Device 27

Eclipse 27

Command Line 28

Root Contents 31

The Sweat Off Your Brow 32

And Now, the Rest of the Story 32

What You Get Out of It 33

Inside Your Manifest 33

In the Beginning, There Was the Root, and It Was Good 34

An Application for Your Application 35

■ Chapter 5: A Bit About Eclipse 37

What the ADT Gives You 37

Coping with Eclipse 38

How to Import a Non-Eclipse Project 38

How to Get to DDMS 42

How to Create an Emulator 43

How to Run a Project 44

How Not to Run Your Project 45

Alternative IDEs 45

IDEs and This Book 46

■ Chapter 6: Enhancing Your First Project 47

Supporting Multiple Screen Sizes 47

Specifying Versions 48

Part II: Activities 49

■ Chapter 7: Rewriting Your First Project 51

The Activity 51

Dissecting the Activity 52

Building and Running the Activity 53

■ Chapter 8: Using XML-Based Layouts 55

What Is an XML-Based Layout? 55

Why Use XML-Based Layouts? 55

OK, So What Does It Look Like? 56

What’s with the @ Signs? 57

And How Do We Attach These to the Java? 57

The Rest of the Story 58

■ Chapter 9: Employing Basic Widgets 61

Assigning Labels 61

Button, Button, Who’s Got the Button? 62

Fleeting Images 63

Fields of Green…or Other Colors 64

Just Another Box to Check 66

Turn the Radio Up 68

It’s Quite a View 70

Padding 70

Other Useful Properties 71

Useful Methods 71

Colors 71

■ Chapter 10: Working with Containers 73

Thinking Linearly 73

LinearLayout Concepts and Properties 74

LinearLayout Example 76

The Box Model 80

All Things Are Relative 81

RelativeLayout Concepts and Properties 82

RelativeLayout Example 84

Overlap 86

Tabula Rasa 87

TableLayout Concepts and Properties 87

TableLayout Example 89

Scrollwork 90

■ Chapter 11: The Input Method Framework 93

Keyboards, Hard and Soft 93

Tailored to Your Needs 94

Tell Android Where It Can Go 98

Fitting In 100

Jane, Stop This Crazy Thing! 101

■ Chapter 12: Using Selection Widgets 103

Adapting to the Circumstances 103

Using ArrayAdapter 104

Lists of Naughty and Nice 104

Selection Modes 106

Spin Control 108

Grid Your Lions (or Something Like That ) 111

Fields: Now with 35% Less Typing! 115

Galleries, Give or Take the Art 118

■ Chapter 13: Getting Fancy with Lists 119

Getting to First Base 119

A Dynamic Presentation 121

Inflating Rows Ourselves 123

A Sidebar About Inflation 123

And Now, Back to Our Story 125

Better Stronger Faster 125

Using convertView 125

Using the Holder Pattern 127

Interactive Rows 129

■ Chapter 14: Still More Widgets and Containers 135

Pick and Choose 135

Time Keeps Flowing Like a River 140

Seeking Resolution 141

Putting It on My Tab 142

The Pieces 143

Wiring It Together 144

Adding Them Up 146

Flipping Them Off 149

Getting in Somebody’s Drawer 154

Other Good Stuff 156

■ Chapter 15: Embedding the WebKit Browser 159

A Browser, Writ Small 159

Loading It Up 161

Navigating the Waters 162

Entertaining the Client 163

Settings, Preferences, and Options (Oh, My!) 165

■ Chapter 16: Applying Menus 167

Flavors of Menu 167

Menus of Options 168

Menus in Context 169

Taking a Peek 170

Yet More Inflation 175

Menu XML Structure 175

Menu Options and XML 176

Inflating the Menu 177

In the Land of Menus and Honey 178

■ Chapter 17: Showing Pop-Up Messages 179

Raising Toasts 179

Alert! Alert! 180

Checking Them Out 181

■ Chapter 18: Handling Activity Lifecycle Events 183

Schroedinger’s Activity 183

Life, Death, and Your Activity 184

onCreate() and onDestroy() 184

onStart(), onRestart(), and onStop() 185

onPause() and onResume() 185

The Grace of State 185

■ Chapter 19: Handling Rotation 187

A Philosophy of Destruction 187

It’s All the Same, Just Different 188

Picking and Viewing a Contact 189

Saving Your State 190

Now with More Savings! 193

DIY Rotation 195

But Google Does Not Recommend This 198

Forcing the Issue 198

Making Sense of It All 200

■ Chapter 20: Dealing with Threads 203

The Main Application Thread 203

Making Progress with ProgressBars 204

Getting Through the Handlers 204

Messages 205

Runnables 208

Where Oh Where Has My UI Thread Gone? 208

Asyncing Feeling 208

The Theory 208

AsyncTask, Generics, and Varargs 209

The Stages of AsyncTask 209

A Sample Task 210

Threads and Rotation 214

Manual Activity Association 215

Flow of Events 217

Why This Works 218

And Now, the Caveats 218

■ Chapter 21: Creating Intent Filters 221

What’s Your Intent? 221

Pieces of Intents 222

Intent Routing 222

Stating Your Intent(ions) 223

Narrow Receivers 224

The Pause Caveat 225

■ Chapter 22: Launching Activities and Subactivities 227

Peers and Subs 227

Start ’Em Up 228

Make an Intent 228

Make the Call 228

Tabbed Browsing, Sort Of 232

■ Chapter 23: Working with Resources 235

The Resource Lineup 235

String Theory 235

Plain Strings 236

String Formats 236

Styled Text 237

Styled Text and Formats 237

Got the Picture? 240

XML: The Resource Way 241

Miscellaneous Values 243

Dimensions 244

Colors 244

Arrays 245

Different Strokes for Different Folks 246

RTL Languages: Going Both Ways 250

■ Chapter 24: Defining and Using Styles 251

Styles: DIY DRY 251

Elements of Style 253

Where to Apply a Style 253

The Available Attributes 254

Inheriting a Style 254

The Possible Values 255

Themes: A Style by Any Other Name 256

■ Chapter 25: Handling Multiple Screen Sizes 257

Taking the Default 257

Whole in One 258

Think About Rules, Not Positions 259

Consider Physical Dimensions 260

Avoid “Real” Pixels 260

Choose Scalable Drawables 260

Tailor-Made, Just for You (and You, and You, and ) 261

Adding the <supports-screens> Element 261

Resources and Resource Sets 262

Finding Your Size 263

Ain’t Nothing Like the Real Thing 263

Density Differs 264

Adjusting the Density 264

Ruthlessly Exploiting the Situation 265

Replace Menus with Buttons 265

Replace Tabs with a Simple Activity 266

Consolidate Multiple Activities 266

Example: EU4You 266

The First Cut 267

Fixing the Fonts 272

Fixing the Icons 274

Using the Space 274

What If It Is Not a Browser? 276

Part III: Honeycomb and Tablets 279

■ Chapter 26: Introducing the Honeycomb UI 281

Why Honeycomb? 281

What the User Sees 282

The Holographic Theme 285

Dealing with the Rest of the Devices 286

■ Chapter 27: Using the Action Bar 289

Enabling the Action Bar 289

Promoting Menu Items to the Action Bar 290

Responding to the Logo 291

Adding Custom Views to the Action Bar 291

Defining the Layout 292

Putting the Layout in the Menu 293

Getting Control of User Input 294

Don’t Forget the Phones! 295

■ Chapter 28: Fragments 297

Introducing Fragments 297

The Problem Addressed by Fragments 297

The Fragments Solution 298

The Android Compatibility Library 299

Creating Fragment Classes 300

General Fragments 300

ListFragment 301

Other Fragment Base Classes 306

Fragments, Layouts, Activities, and Multiple Screen Sizes 306

EU4You 307

DetailsActivity 311

Fragments and Configuration Changes 312

Designing for Fragments 312

■ Chapter 29: Handling Platform Changes 313

Things That Make You Go Boom 313

View Hierarchy 313

Changing Resources 314

Handling API Changes 314

Minimum, Maximum, Target, and Build Versions 315

Detecting the Version 316

Wrapping the API 317

Patterns for Honeycomb 318

The Action Bar 319

Writing Tablet-Only Apps 321

■ Chapter 30: Accessing Files 323

You and the Horse You Rode in On 323

Readin’ ’n Writin’ 326

External Storage: Giant Economy-Size Space 330

Where to Write 330

When to Write 331

StrictMode: Avoiding Janky Code 331

Setting Up StrictMode 332

Seeing StrictMode in Action 332

Development Only, Please! 333

Conditionally Being Strict 333

Linux File Systems: You Sync, You Win 335

Part IV: Data Stores, Network Services, and APIs 337

■ Chapter 31: Using Preferences 339

Getting What You Want 339

Stating Your Preference 340

Introducing PreferenceActivity 340

Letting Users Have Their Say 341

Adding a Wee Bit o’ Structure 345

The Kind of Pop-Ups You Like 347

Preferences via Fragments 350

The Honeycomb Way 351

Adding Backward Compatibility 354

■ Chapter 32: Managing and Accessing Local Databases 357

A Quick SQLite Primer 359

Start at the Beginning 359

Setting the Table 362

Makin’ Data 362

What Goes Around, Comes Around 364

Raw Queries 364

Regular Queries 364

Using Cursors 365

Custom CursorAdapters 366

Making Your Own Cursors 366

Flash: Sounds Faster Than It Is 367

Data, Data, Everywhere 367

■ Chapter 33: Leveraging Java Libraries 369

Ants and JARs 369

The Outer Limits 370

Following the Script 371

Reviewing the Script 374

■ Chapter 34: Communicating via the Internet 377

REST and Relaxation 377

HTTP Operations via Apache HttpClient 378

Parsing Responses 379

Stuff to Consider 381

AndroidHttpClient 382

Leveraging Internet-Aware Android Components 382

Downloading Files 383

Continuing Our Escape from Janky Code 391

Part V: Services 393

■ Chapter 35: Services: The Theory 395

Why Services? 395

Setting Up a Service 396

Service Class 396

Lifecycle Methods 396

Manifest Entry 397

Communicating to Services 397

Sending Commands with startService() 397

Binding with bindService() 398

Communicating from Services 399

Callback/Listener Objects 400

Broadcast Intents 400

Pending Results 400

Messenger 401

Notifications 401

■ Chapter 36: Basic Service Patterns 403

The Downloader 403

The Design 403

The Service Implementation 404

Using the Service 406

The Music Player 407

The Design 407

The Service Implementation 408

Using the Service 409

The Web Service Interface 410

The Design 411

The Rotation Challenge 411

The Service Implementation 411

Using the Service 416

■ Chapter 37: Alerting Users via Notifications 423

Notification Configuration 423

Hardware Notifications 424

Icons 424

Notifications in Action 425

Staying in the Foreground 429

FakePlayer, Redux 430

Notifications and Honeycomb 431

Part VI: Other Android Capabilities 435

■ Chapter 38: Requesting and Requiring Permissions 437

Mother, May I? 437

Halt! Who Goes There? 438

Enforcing Permissions via the Manifest 439

Enforcing Permissions Elsewhere 440

May I See Your Documents? 440

New Permissions in Old Applications 440

Permissions: Up Front or Not at All 441

■ Chapter 39: Accessing Location-Based Services 443

Location Providers: They Know Where You're Hiding 443

Finding Yourself 444

On the Move 445

Are We There Yet? Are We There Yet? 446

Testing Testing 447

■ Chapter 40: Mapping with MapView and MapActivity 449

Terms, Not of Endearment 449

Piling On 450

The Key to It All 450

The Bare Bones 451

Optional Maps 452

Exercising Your Control 453

Zoom 453

Center 454

Layers Upon Layers 454

Overlay Classes 454

Drawing the ItemizedOverlay 454

Handling Screen Taps 456

My, Myself, and MyLocationOverlay 456

Rugged Terrain 458

Maps and Fragments 459

Limit Yourself to Android 3.0 459

Use onCreateView() and onActivityCreated() 460

Host the Fragment in a MapActivity 461

■ Chapter 41: Handling Telephone Calls 463

Report to the Manager 463

You Make the Call! 464

No, Really, You Make the Call! 466

■ Chapter 42: Fonts 467

Love the One You’re With 467

Additional Fonts 469

Here a Glyph, There a Glyph 470

■ Chapter 43: More Development Tools 473

Hierarchy Viewer: How Deep Is Your Code? 473

DDMS: Under Android’s Hood 477

Logging 479

File Push and Pull 480

Screenshots 481

Location Updates 481

Placing Calls and Messages 482

Memory Management 485

adb: Like DDMS, with More Typing 487

Part VII: Alternative Application Environments 489

■ Chapter 44: The Role of Alternative Environments 491

In the Beginning, There Was Java 491

And It Was OK 492

Bucking the Trend 492

Support, Structure 493

Caveat Developer 493

■ Chapter 45: HTML5 495

Offline Applications 495

What Does It Mean? 495

How Do You Use It? 496

Web Storage 500

What Does It Mean? 500

How Do You Use It? 501

Web SQL Database 502

Going to Production 502

Testing 503

Signing and Distribution 503

Updates 503

Issues You May Encounter 503

Android Device Versions 503

Screen Sizes and Densities 504

Limited Platform Integration 504

Performance and Battery 505

Look and Feel 505

Distribution 505

HTML5 and Alternative Android Browsers 506

HTML5: The Baseline 506

■ Chapter 46: PhoneGap 507

What Is PhoneGap? 507

What Do You Write In? 507

What Features Do You Get? 508

What Do Apps Look Like? 508

How Does Distribution Work? 509

What About Other Platforms? 509

Using PhoneGap 510

Installation 510

Creating and Installing Your Project 510

PhoneGap Build 511

PhoneGap and the Checklist Sample 514

Sticking to the Standards 515

Adding PhoneGap APIs 517

Issues You May Encounter 519

Security 519

Screen Sizes and Densities 521

Look and Feel 521

For More Information 522

■ Chapter 47: Other Alternative Environments 523

Rhodes 523

Flash, Flex, and AIR 524

JRuby and Ruboto 524

Mono for Android 524

App Inventor 525

Titanium Mobile 526

Other JVM Compiled Languages 527

Part VIII: The Ever-Evolving Android 529

■ Chapter 48: Dealing with Devices 531

This App Contains Explicit Instructions 531

Explicit Feature Requests 531

Implied Feature Requests 532

A Guaranteed Market 533

Other Stuff That Varies 534

Bugs, Bugs, Bugs 534

Device Testing 535

■ Chapter 49: Where Do We Go from Here? 537

Questions, Sometimes with Answers 537

Heading to the Source 538

Getting Your News Fix 539

Index 541

Part Core Concept

I

3

The Big Picture

Android is everywhere Phones Tablets TVs and set-top boxes powered by Google TV

Soon, Android will be in cars and all sort of other places as well

However, the general theme of Android devices will be smaller screens and/or no

hardware keyboard And, by the numbers, Android will probably be associated mostly

with smartphones for the foreseeable future For developers, this has both benefits and

drawbacks, as described next This chapter also describes the main components in an

Android application and the Android features that you can exploit when developing your

applications

Benefits and Drawbacks of Smartphone

Programming

On the plus side, Android-style smartphones are sexy Offering Internet services over

mobile devices dates back to the mid-1990s and the Handheld Device Markup

Language (HDML) However, only in recent years have phones capable of Internet

access taken off Now, thanks to trends like text messaging and products like Apple’s

iPhone, phones that can serve as Internet-access devices are rapidly gaining popularity

So, working on Android 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 the pain of phones

simply being small in all sorts of dimensions:

LCD in your pocket, or ?”)

1

Pointing devices, if they exist, are annoying (as anyone who has lost

their stylus will tell you) or inexact (large fingers and “multitouch” LCDs can sometimes be problematic)

desktops and servers

Moreover, applications running on a phone have to deal with the fact that they’re on a phone

People with mobile phones tend to get very irritated when those phones do not work Similarly, those same people will get irritated if your program “breaks” their phones by

to be placed, because the program doesn’t work properly with the rest

of the phone’s operating system

like a sieve

Hence, developing programs for a phone is a different experience than developing desktop applications, web sites, or back-end server processes The tools look different, the frameworks behave differently, and you have more limitations on what you can do with your programs

What Android tries to do is meet you halfway:

commonly used libraries (e.g., some Apache Commons APIs), with support for tools you may be used to using (Eclipse)

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 itself

As you might expect, much of this book deals with that framework and how you write programs that work within its confines and take advantage of its capabilities

What Androids Are Made Of

When you write a desktop application, you are “master of your own domain.” You launch your main window and any child windows—like dialog boxes—that are needed From your standpoint, you are your own world, leveraging features supported by the operating system, but largely ignorant of any other program that may be running on the computer at the same time If you do interact with other programs, it is typically through

an application programming interface (API), such as Java Database Connectivity (JDBC),

or frameworks atop it, to communicate with MySQL or another database

CHAPTER 1: The Big Picture 5

Android has similar concepts, but they are packaged differently and structured to make

phones more crash-resistant:

can think of an activity as being the Android analogue for the window

or dialog box in a desktop application or the page in a classic web

application Android is designed to support lots of cheap activities, so

you can allow users to keep tapping to open new activities and

tapping the Back button to back up, just like they do in a web browser

Services, on the other hand, are designed to keep running, if needed,

independent of any activity You might use a service to check for

updates to an RSS feed or to play back music even if the controlling

activity is no longer operating You will also use services for scheduled

tasks (“cron jobs”) and for exposing custom APIs to other applications

on the device, though those are relatively advanced capabilities

any data stored on the device that is accessible by multiple

applications The Android development model encourages you to

make your own data available to other applications, as well as your

own applications Building a content provider lets you do that, while

maintaining complete control over how your data gets accessed

device and notify applications of various events, from hardware state

changes (e.g., an SD card was inserted), to incoming data (e.g., a

Short Message Service [SMS] message arrived), to application events

(e.g., your activity was launched from the device’s main menu) Not

only can you respond to an Intent, but you can create your own to

launch other activities or to let you know when specific situations arise

(e.g., raise such-and-so Intent when the user gets within 100 meters

of this-and-such location)

Stuff at Your Disposal

that do not change, such as icons or help files You also can carve out

a small bit of space on the device itself, for databases or files

containing user-entered or retrieved data needed by your application

And, if the user supplies bulk storage, like an SD card, you can read

and write files on there as needed

Network: Android devices generally are Internet-ready, through one

communications medium or another You can take advantage of the Internet access at any level you wish, from raw Java sockets all the way up to a built-in WebKit-based web browser widget you can embed in your application

audio and video While the specifics may vary from device to device, you can query the device to learn its capabilities and then take advantage of the multimedia capabilities as you see fit, whether that is

to play back music, take pictures with the camera, or use the microphone for audio note-taking

access to location providers, such as GPS, that can tell your applications where the device is on the face of the Earth In turn, you can display maps or otherwise take advantage of the location data, such as to track a device’s movements if the device has been stolen

software can initiate calls, send and receive SMS messages, and do everything else you expect from a modern bit of telephony technology

The Big Picture of This Book

Now that you have the Android big picture, here is what’s coming in the rest of this book:

Android environment, through a series of step-by-step, tutorial-style instructions for setting up the tools you need, creating your first project, and getting that first project running on the Android emulator

happened in Chapters 2 and 3 We examine the Android project that

we created, talk a bit more about Eclipse, and discuss some things we could add to the project to help it run on more devices and enhance its capabilities

APIs—how to create components like activities, how to access the Internet and local databases, how to get your location and show it on

a map, and so forth

7

How to Get Started

Without further ado, let’s get you set up with the pieces and parts necessary to build an

Android app

NOTE: The instructions presented here are accurate as of the time of this writing However, the

tools change rapidly, so these instructions may be out of date by the time you read this Please

refer to the Android Developers web site for current instructions, using this as a base guideline of

what to expect

Step 1: Set Up Java

When you write Android applications, you typically write them in Java source code That

Java source code is then turned into the stuff that Android actually runs (Dalvik

bytecode in an Android package [APK] file)

Hence, the first thing you need to do is get set up with a Java development environment

so that you are prepared to start writing Java classes

Install the JDK

You need to obtain and install the official Sun/Oracle Java SE SDK (JDK) You can

obtain this from the Oracle Java web site for Windows and Linux, and presumably from

Apple for Mac OS X The plain JDK (sans any “bundles”) should suffice Follow the

instructions supplied by Oracle or Apple for installing it on your machine At the time of

this writing, Android supports Java 5 and Java 6, the latter being the now-current

edition

Alternative Java Compilers

In principle, you are supposed to use the official Sun/Oracle Java SE Development Kit

(JDK) In practice, it appears that OpenJDK also works, at least on Ubuntu However, the

2

further removed you get from the official Sun/Oracle implementation, the less likely it is that it will work For example, the GNU Compiler for Java (GCJ) may not work with Android

Step 2: Install the Android SDK

The Android SDK gives you all the tools you need to create and test Android

applications It comes in two parts: the base tools, and version-specific SDKs and related add-ons

Install the Base Tools

You can find the Android developer tools on the Android Developers web site Download the ZIP file that is appropriate for your platform and unzip it in a logical location on your

CHAPTER 2: How to Get Started 9

machine—no specific path is required Windows users also have the option of running a

self-installing EXE file

Install the SDKs and Add-ons

Inside the tools/ directory of your Android SDK installation from the previous step, you

will see an android batch file or shell script If you run that, you will be presented with

the Android SDK and AVD Manager, shown in Figure 2–1

Figure 2–1 Android SDK and AVD Manager

At this point, you have some of the build tools, but you lack the Java files necessary to

compile an Android application You also lack a few additional build tools, and the files

necessary to run an Android emulator To address this, click the Available packages

option on the left to open the screen shown in Figure 2–2

Figure 2–2 Android SDK and AVD Manager available packages

Open the Android Repository branch of the tree After a short pause, you will see a screen similar to Figure 2–3

Figure 2–3 Android SDK and AVD Manager available Android packages

Check the boxes for the following items:

older releases if you wish Then, open the Third party Add-ons branch of the tree After a short pause, you will see

a screen similar to Figure 2–4

CHAPTER 2: How to Get Started 11

Figure 2–4 Android SDK and AVD Manager available third-party add-ons

Click the “Google Inc add-ons” branch to open it, as shown in Figure 2–5

Figure 2–5 Android SDK and AVD Manager available Google add-ons

Most likely, you will want to check the boxes for the “Google APIs by Google Inc.” items

that match up with the SDK versions you selected in the Android Repository branch The

Google APIs include support for Google Maps, both from your code and in the Android

emulator

After you have checked all the items you want to download, click the Install Selected

button, which brings up a license confirmation dialog box, shown in Figure 2–6

Figure 2–6 Android SDK and AVD Manger license agreement screen

Review and accept the licenses if you agree with the terms, and then click the Install button At this point, this is a fine time to go get lunch or dinner Unless you have a substantial Internet connection, downloading all of this data and unpacking it will take a fair bit of time

When the download is complete, you can close the SDK and AVD Manager if you wish, though you will use it to set up the emulator in Step 5 of this chapter

Step 3: Install the ADT for Eclipse

If you will not be using Eclipse for your Android development, you can skip to the next section If you will be using Eclipse but have not yet installed it, you will need to do that first Eclipse can be downloaded from the Eclipse web site, www.eclipse.org/ The Eclipse IDE for Java Developers package will work fine

Next, you need to install the Android Developer Tools (ADT) plug-in To do this, open Eclipse and choose Help ➤ Install New Software Then, in the Install dialog box, click the Add button to add a new source of plug-ins Give it a name (e.g., Android) and supply the following URL: https://dl-ssl.google.com/android/eclipse/ That should trigger Eclipse to download the roster of plug-ins available from that site (see Figure 2–7)

CHAPTER 2: How to Get Started 13

Figure 2–7 Eclipse ADT plug-in installation

Check the Developer Tools check box and click the Next button Follow the rest of the

wizard steps to review the tools to be downloaded and review and accept their respective

license agreements When the Finish button is enabled, click it, and Eclipse will download

and install the plug-ins When it’s done, Eclipse will ask to restart; let it do so

Then, you need to show ADT where to locate your Android SDK installation from the

preceding section To do this, choose Window ➤ Preferences from the Eclipse main

menu (or the equivalent Preferences option for Mac OS X) Click the Android entry in the

list pane of the Preferences dialog box, as shown in Figure 2–8

Figure 2–8 Eclipse ADT configuration

Then, click the Browse button to find the directory where you installed the SDK After choosing it, click Apply in the Preferences dialog box, and you should see the Android SDK versions you installed previously Then, click OK, and the ADT will be ready for use

Step 4: Install Apache Ant

If you will be doing all of your development from Eclipse, you can skip to the next section If you wish to develop using command-line build tools, you need to install Apache Ant You may have this installed already from previous Java development work,

as it is fairly common in Java projects However, you need Ant version 1.8.1 or later, so check your current copy (e.g., ant -version)

If you do not have Ant or do not have the correct version, you can obtain it from the Apache Ant web site, at http://ant.apache.org/ Full installation instructions are available in the Ant manual, but the basic steps are as follows:

installed, if you do not have one already

you unpacked Ant in step 1

CHAPTER 2: How to Get Started 15

Step 5: Set Up the Emulator

The Android tools include an emulator, a piece of software that pretends to be an

Android device This is very useful for development—it not only enables you to get

started on your Android development without a device, but also enables you to test

device configurations for devices that you do not own

The Android emulator can emulate one or several Android devices Each configuration

you want is stored in an Android Virtual Device (AVD) The Android SDK and AVD

Manager, which you used to download the SDK components earlier in this chapter, is

where you create these AVDs

If you do not have the SDK and AVD Manager running, you can run it via the android

command from your SDK’s tools/ directory, or via Window ➤ SDK and AVD Manager

from Eclipse It opens with a screen listing the AVDs you have available; initially, the list

will be empty, as shown in Figure 2–9

Figure 2–9 Android SDK and AVD Manager Android Virtual Devices list

Click the New button to create a new AVD file This opens the dialog box shown in

Figure 2–10, where you can configure how this AVD should look work

Figure 2–10 Adding a new AVD

You need to provide the following:

development machine, you are limited by the file name conventions for your operating system (e.g., no backslashes on Windows)

of the SDKs you installed via the Target drop-down list Note that in addition to “pure” Android environments, you will have options based

on the third-party add-ons you selected For example, you probably have some options for setting up AVDs containing the Google APIs, and you will need such an AVD for testing an application that uses Google Maps

devices invariably have some form of external storage, you probably want to set up an SD card, by supplying a size in the associated field However, since a file will be created on your development machine of whatever size you specify for the card, you probably do not want to create a 2GB emulated SD card 32MB is a nice starting point, though you can go larger if needed

CHAPTER 2: How to Get Started 17

you have available depend upon what target you chose The skins let

you choose a typical Android screen resolution (e.g., WVGA800 for

800
480) You can also manually specify a resolution when you want

to test a nonstandard configuration

You can skip the Hardware section of the dialog box for now, as changing those

settings is usually only required for advanced configurations

The resulting dialog box might look something like Figure 2–11

Figure 2–11 Adding a new AVD (continued)

Click the Create AVD button, and your AVD stub will be created

To start the emulator, select it in the Android Virtual Devices list and click Start You can

skip the launch options for now and just click Launch The first time you launch a new

AVD, it will take a long time to start up The second and subsequent times you start the

AVD, it will come up a bit faster, and usually you need to start it only once per day (e.g.,

when you start development) You do not need to stop and restart the emulator every

time you want to test your application, in most cases

The emulator will go through a few startup phases, the first of which displays a plain-text

ANDROID label, as shown in Figure 2–12

Figure 2–12 Android emulator, initial startup segment

The second phase displays a graphical Android logo, as shown in Figure 2–13

CHAPTER 2: How to Get Started 19

Figure 2–13 Android emulator, secondary startup segment

Finally, the emulator reaches the home screen (the first time you run the AVD; see Figure

2–14) or the keyguard (see Figure 2–15)

Figure 2–14 Android home screen

If you get the keyguard, press the Menu button or slide the green lock on the screen to the right, to get to the emulator’s home screen

Figure 2–15 Android keyguard

CHAPTER 2: How to Get Started 21

Step 6: Set Up the Device

With an emulator set up, you do not need an Android device to get started in Android

application development Having one is a good idea before you try to ship an application

(e.g., upload it to the Android Market) But perhaps you already have a device—maybe

that is what is spurring your interest in developing for Android

The first step to make your device ready for use with development is to go into the

Settings application on the device From there, choose Applications, then Development

That should give you a set of check boxes for choosing development-related options,

similar to what’s shown in Figure 2–16

Figure 2–16 Android device development settings

Generally, you will want to enable USB debugging so that you can use your device with

the Android build tools You can leave the other settings alone for now if you wish,

though you may find the Stay awake option to be handy, as it saves you from having to

unlock your phone repeatedly while it is plugged into USB

Next, you need to set up your development machine to talk to your device That process

varies by the operating system of your development machine, as covered in the

following sections

Windows

When you first plug in your Android device, Windows attempts to find a driver for it It is

possible that, by virtue of other software you have installed, the driver is ready for use If

Windows finds a driver, you are probably ready to go

If Windows doesn’t find the driver, here are some options for getting one:

to search Windows Update for drivers This is certainly worth a shot,

though not every device will have supplied its driver to Microsoft

Standard Android driver: In your Android SDK installation, you will find

a google-usb_driver directory, containing a generic Windows driver for Android devices You can try pointing the driver wizard at this directory to see if it thinks this driver is suitable for your device

the CD that came with the device (if any) or search the web site of the device manufacturer Motorola, for example, has drivers available for all of its devices in one spot for download

Mac OS X and Linux

Odds are decent that simply plugging in your device will “just work.” You can see if Android recognizes your device by running adb devices in a shell (e.g., OS X Terminal), where adb is in your platform-tools/ directory of your SDK If you get output similar to the following, Android detected your device:

List of devices attached

HT9CPP809576 device

If you are running Ubuntu (or perhaps another Linux variant) and this command did not work, you may need to add some udev rules For example, here is a 51-android.rules file that will handle the devices from a handful of manufacturers:

SUBSYSTEM=="usb", SYSFS{idVendor}=="0bb4", MODE="0666"

SUBSYSTEM=="usb", SYSFS{idVendor}=="22b8", MODE="0666"

SUBSYSTEM=="usb", SYSFS{idVendor}=="18d1", MODE="0666"

SUBSYSTEMS=="usb", ATTRS{idVendor}=="18d1", ATTRS{idProduct}=="0c01", MODE="0666",
OWNER="[me]"

SUBSYSTEM=="usb", SYSFS{idVendor}=="19d2", SYSFS{idProduct}=="1354", MODE="0666" SUBSYSTEM=="usb", SYSFS{idVendor}=="04e8", SYSFS{idProduct}=="681c", MODE="0666"

Drop that in your /etc/udev/rules.d directory on Ubuntu, and then either reboot the computer or otherwise reload the udev rules (e.g., sudo service udev reload) Then, unplug the device, plug it in again, and see if it is detected

23

Your First Android Project

Now that you have the Android SDK, it is time to make your first Android project The

good news is that this requires zero lines of code—Android’s tools create a “Hello,

world!” application for you as part of creating a new project All you need to do is build

it, install it, and watch it open on your emulator or device

Step 1: Create the New Project

Android’s tools can create a complete skeleton project for you, with everything you need

for a complete (albeit very trivial) Android application The process differs depending on

whether you are using Eclipse or the command line

Eclipse

From the Eclipse main menu, choose File ➤ New ➤ Project to open the New Project

dialog box, which gives you a list of project type wizards to choose from Expand the

Android option and click Android Project, as shown in Figure 3–1

3

Figure 3–1 Selecting a wizard in the Eclipse New Project dialog box

Click Next to advance to the first page of the New Android Project wizard, shown in Figure 3–2

CHAPTER 3: Your First Android Project 25

Figure 3–2 Eclipse New Android Project wizard, ready to fill in

Fill in the following and leave the default settings otherwise (the completed example for

this project is shown in Figure 3–3):

Google APIs for Android 2.3.3)

used for the caption under your icon in the launcher (e.g., Now)

belongs (e.g., com.commonsware.android.skeleton)

Figure 3–3 Eclipse New Android Project wizard, completed

At this point, click Finish to create your Eclipse project

Command Line

Here is a sample command that creates an Android project from the command line:

android create project target "Google Inc.:Google APIs:7" path Skeleton/Now
activity Now package com.commonsware.android.skeleton

This creates an application skeleton for you, complete with everything you need to build your first Android application: Java source code, build instructions, and so forth

CHAPTER 3: Your First Android Project 27

However, you’ll probably need to customize this somewhat Here are what those

command-line switches mean:

of your build process You need to supply the ID of a target that is

installed on your development machine, one you downloaded via the

Android SDK and AVD Manager You can find out which targets are

available via the android list targets command Typically, your build

process will target the newest version of Android that you have

available

Android will create a directory if the one you name does not exist For

example, in the preceding command, a Skeleton/Now/ directory will be

created (or used if it exists) under the current working directory, and

the project files will be stored there

project Do not include a package name, and make sure the name

meets Java class-naming conventions

be located This package name also uniquely identifies your project on

any device on which you install it, and it must be unique on the

Android Market if you plan on distributing your application there

Hence, typically, you should construct your package based on a

domain name you own (e.g., com.commonsware.android.skeleton), to

reduce the odds of an accidental package name collision with

somebody else

For your development machine, you need to pick a suitable target, and you may wish to

change the path You can ignore the activity and package for now

Step 2: Build, Install, and Run the Application in

Your Emulator or Device

Having a project is nice and all, but it would be even better if you could build and run it,

whether on the Android emulator or on your Android device Once again, the process

differs somewhat depending on whether you are using Eclipse or the command line

Eclipse

With your project selected on the Package Explorer panel of Eclipse, click the green play

button in the Eclipse toolbar to run your project The first time you do this, you have to go

through a few steps to set up a run configuration, so Eclipse knows what you want to do

First, in the Run As dialog box, choose Android Application, as shown in Figure 3–4

Figure 3–4 Choosing to run as an Android application in the Eclipse Run As dialog box

Click OK If you have more than one emulator AVD or device available, you will then get

an option to choose which you wish to run the application on Otherwise, if you do not have a device plugged in, the emulator will start up with the AVD you created earlier Then, Eclipse will install the application on your device or emulator and start it

Command Line

For developers who are not using Eclipse, in your terminal, change into the

Skeleton/Now directory, then run the following command:

ant clean install

The Ant-based build should emit a list of steps involved in the installation process, which looks like this:

Buildfile: /home/some-balding-guy/projects/Skeleton/Now/build.xml

[setup] Android SDK Tools Revision 10

[setup] Project Target: Android 1.6

[setup] API level: 4

[setup]

[setup] -

[setup] Resolving library dependencies:

[setup] No library dependencies