Android

™

A Programmer’s Guide

This page intentionally left blank

Android

™

A Programmer’s Guide

J.F. DiMarzio

New York Chicago San Francisco Lisbon London Madrid Mexico City Milan New Delhi San Juan Seoul Singapore Sydney Toronto

Copyright © 2008 by The McGraw-Hill Companies. All rights reserved. Manufactured in the United States of America. Except as permitted under the United States Copyright Act of 1976, no part of this publication may be reproduced or distributed in any form or by any means, or stored in a database or retrieval system, without the prior written permission of the publisher. 0-07-159989-4 The material in this eBook also appears in the print version of this title: 0-07-159988-6. All trademarks are trademarks of their respective owners. Rather than put a trademark symbol after every occurrence of a trademarked name, we use names in an editorial fashion only, and to the benefit of the trademark owner, with no intention of infringement of the trademark. Where such designations appear in this book, they have been printed with initial caps. McGraw-Hill eBooks are available at special quantity discounts to use as premiums and sales promotions, or for use in corporate training programs. For more information, please contact George Hoare, Special Sales, at george_hoare@mcgraw-hill.com or (212) 904-4069. TERMS OF USE This is a copyrighted work and The McGraw-Hill Companies, Inc. (“McGraw-Hill”) and its licensors reserve all rights in and to the work. Use of this work is subject to these terms. Except as permitted under the Copyright Act of 1976 and the right to store and retrieve one copy of the work, you may not decompile, disassemble, reverse engineer, reproduce, modify, create derivative works based upon, transmit, distribute, disseminate, sell, publish or sublicense the work or any part of it without McGraw-Hill’s prior consent. You may use the work for your own noncommercial and personal use; any other use of the work is strictly prohibited. Your right to use the work may be terminated if you fail to comply with these terms. THE WORK IS PROVIDED “AS IS.” McGRAW-HILL AND ITS LICENSORS MAKE NO GUARANTEES OR WARRANTIES AS TO THE ACCURACY, ADEQUACY OR COMPLETENESS OF OR RESULTS TO BE OBTAINED FROM USING THE WORK, INCLUDING ANY INFORMATION THAT CAN BE ACCESSED THROUGH THE WORK VIA HYPERLINK OR OTHERWISE, AND EXPRESSLY DISCLAIM ANY WARRANTY, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. McGraw-Hill and its licensors do not warrant or guarantee that the functions contained in the work will meet your requirements or that its operation will be uninterrupted or error free. Neither McGraw-Hill nor its licensors shall be liable to you or anyone else for any inaccuracy, error or omission, regardless of cause, in the work or for any damages resulting therefrom. McGraw-Hill has no responsibility for the content of any information accessed through the work. Under no circumstances shall McGraw-Hill and/or its licensors be liable for any indirect, incidental, special, punitive, consequential or similar damages that result from the use of or inability to use the work, even if any of them has been advised of the possibility of such damages. This limitation of liability shall apply to any claim or cause whatsoever whether such claim or cause arises in contract, tort or otherwise. DOI: 10.1036/0071599886

Professional

Want to learn more?
We hope you enjoy this McGraw-Hill eBook! If you’d like more information about this book, its author, or related books and websites, please click here.

This book is dedicated to Suzannah, Christian, and Sophia

About the Author
J.F. DiMarzio is a developer with over 15 years of experience in networking and application development and is the author of seven books on computing technologies. He has become a leading resource in the fields of IT consulting and development. He lives in Central Florida.

About the Technical Editor
Gilbert L. Polo is a software developer with over 20 years of experience working in the telecommunications, financial, and, most recently, educational industries. He has programmed in various languages including C, C++, Java, and C#.

Copyright © 2008 by The McGraw-Hill Companies. Click here for terms of use.

Contents at a Glance
1 What Is Android? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Downloading and Installing Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Downloading and Installing the Android SDK 4 Exploring the Android SDK

1 9 21 35 53 83

.......................

......................................

5 Application: Hello World! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Using the Command-Line Tools and the Android Emulator . . . . . . . . . . . .

7 Using Intents and the Phone Dialer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 8 Lists, Menus, and Other Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 9 Using the Cell Phone’s GPS Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 10 Using the Google API with GTalk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 11 Application: Find a Friend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 12 Android SDK Tool Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

vii

This page intentionally left blank

For more information about this title, click here

Contents
ACKNOWLEDGMENTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii xv

1 What Is Android? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Brief History of Embedded Device Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Open Handset Alliance and Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Introduction to Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Downloading and Installing Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Why Eclipse? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Downloading and Installing the JRE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Downloading and Installing Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Downloading and Installing the Android SDK . . . . . . . . . . . . . . . . . . . . . . . Downloading the Android SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Downloading and Installing the Android Plugin for Eclipse . . . . . . . . . . . . . . . . . . . . . . Configuring the Android Plugin for Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1
2 5 6

9
11 12 18

21
24 24 30

ix

x

Android: A Programmer’s Guide

4 Exploring the Android SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is in the Android SDK? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Android Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Android Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Try This: Run the API Demos Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . Android Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Application Life Cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Standard ASP Application Life Cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Android Application Life Cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Application: Hello World! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Your First Android Project in Eclipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Examining the Android-Created Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AndroidManifest.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Referenced Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Hello World! Again . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Hello World! Using an Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Hello World! Code-Based UI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Hello World! XML-Based UI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Try This: Use TextView and ImageView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

35
37 38 39 41 45 48 49 49 50

53
55 61 62 62 63 69 72 75 78 81

6 Using the Command-Line Tools and the Android Emulator . . . . . . . . . . . . 83 Creating a Shell Activity Using the Windows CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 Running the ActivityCreator.bat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 The Project Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Creating the Hello World! Activity in the Windows CLI . . . . . . . . . . . . . . . . . . . . . . . . 95 Editing the Project Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Adding the JAVA_HOME Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Compiling and Installing the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Hello World! on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Configuring the PATH Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Try This: Create an Image-Based Hello World! in the CLI . . . . . . . . . . . . . . . . . . . 115 7 Using Intents and the Phone Dialer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Are Intents? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Dialer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Placing a Call from Your Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding the Intent to Your Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing Activity Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

117
119 124 128 129 131

Contents

xi

Modifying the AndroidPhoneDialer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding a Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Implementing an EditText View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Try This: Modify the AndroidPhoneDialer Project . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Lists, Menus, and Other Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Building the Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Intent Code for the .xml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Intent Code for the .java File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying the AndroidManifest.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating the Activity for AutoComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CheckBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EditText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RadioGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Spinner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Try This: Modify More View Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Using the Cell Phone’s GPS Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Android Location-Based API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a kml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Is a track File? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting the nmea File in Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Getting the nmea File in Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reading the GPS with the Android Location-Based API . . . . . . . . . . . . . . . . . . . . . . . . Creating the AndroidLBS Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Passing Coordinates to Google Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding Zoom Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Try This: Toggling Between MapView’s Standard and Satellite Views . . . . . . . . . . 10 Using the Google API with GTalk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring the Android Emulator for GTalk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Implementing GTalk in Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating the Activity’s Layout in the GoogleAPI.xml . . . . . . . . . . . . . . . . . . . . . Adding Packages to GoogleAPI.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Implementing the View.OnClickListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Compiling and Running GoogleAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Try This: Add a Settings Feature to Your GoogleAPI Activity . . . . . . . . . . . . . . . .

136 136 141 145

149
151 152 154 155 157 163 173 178 183 189 195 202

203
204 205 208 208 210 212 212 222 226 232

239
241 244 245 247 248 252 255

xii

Android: A Programmer’s Guide

11 Application: Find a Friend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a SQLite Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Custom Content Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing the strings.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Your Content Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating the FindAFriend Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Editing AndroidManifest.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating the NameEditor Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating the LocationEditor Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating the FriendsMap Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating the FindAFriend Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running the FindAFriend Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Try This: Real-Time Location Updating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

257
259 263 263 265 276 276 278 283 293 299 302 305

12 Android SDK Tool Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307 Android Emulator Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308 Android Debug Bridge Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

Acknowledgments
I
would like to thank everyone who participated in the creation of this book. My agent, Neil Salkind; Roger, Carly, Janet, Bill, and the crew at McGraw-Hill; Gil Polo; and everyone at Studio B. I would also like to thank my family, Suzannah, Christian, and Sophia; Brett, Robert, Roger, Zack, Mark, Kurt, Walter, Walter, Walter, Steve, Steve, Steve, and Gary—and all my colleagues in Central Florida; and anyone else whom I may have forgotten.

xiii
Copyright © 2008 by The McGraw-Hill Companies. Click here for terms of use.

This page intentionally left blank

Introduction elcome to Android: A Programmer’s Guide. This book has been designed to give you the best first step toward the exciting new frontier of open source mobile development. Android is the newest mobile device operating system, and this is one of the first books to help the average programmer become a fearless Android developer. Through the course of this book, you will be introduced to the fundamentals of mobile device application development using the Open Handset Alliance’s Android platform. By the end of this book, you will be able to confidently create your own mobile device programs. The format of this book is such that it will take you through Android application development in a logical manner. The book begins by examining the architecture of Android as a platform, looking at how it was developed, what it can run on, and what tools are required to develop programs for it. After discussing and installing the development tools, Android SDK, and the Eclipse development environment (Chapters 2, 3, and 4), the book dives directly into designing and creating Android applications (Chapter 5). The book concludes with instructions on tying your applications to existing Google tools such as Google Maps (Chapters 9 and 11) and GTalk (Chapter 10). A quick reference guide is also included in Chapter 12. This book is a programmer’s guide, not a beginner’s guide, meaning that you do need to possess some programming skills to get the most from it. Foremost among these skills is a working knowledge of Java programming fundamentals. Android applications are

W

xv
Copyright © 2008 by The McGraw-Hill Companies. Click here for terms of use.

xvi

Android: A Programmer’s Guide

developed in Java and run on the Linux 2.6 kernel. If you are a quick learner, you may be able to understand what is going on with just some basic object-oriented programming (OOP) experience. Chapter 2 explains how to download and install the preferred integrated development environment, Eclipse. All the code samples and screenshots in this book are provided using Eclipse (Europa release) and the Android plugin for Eclipse. Any comments, questions, or suggestions about any of the material in this book can be forwarded directly to the author at jfdimarzio@jfdimarzio.com.

Chapter

1

What Is Android?

Copyright © 2008 by The McGraw-Hill Companies. Click here for terms of use.

2

Android: A Programmer’s Guide

Key Skills & Concepts
● ● ●

History of embedded device programming Explanation of Open Handset Alliance First look at the Android home screen

I

t can be said that, for a while, traditional desktop application developers have been spoiled. This is not to say that traditional desktop application development is easier than other forms of development. However, as traditional desktop application developers, we have had the ability to create almost any kind of application we can imagine. I am including myself in this grouping because I got my start in desktop programming. One aspect that has made desktop programming more accessible is that we have had the ability to interact with the desktop operating system, and thus interact with any underlying hardware, pretty freely (or at least with minimal exceptions). This kind of freedom to program independently, however, has never really been available to the small group of programmers who dared to venture into the murky waters of cell phone development.

NOTE
I refer to two different kinds of developers in this discussion: traditional desktop application developers, who work in almost any language and whose end product, applications, are built to run on any “desktop” operating system; and Android developers, Java developers who develop for the Android platform. This is not for the purposes of saying one is by any means better or worse than the other. Rather, the distinction is made for purposes of comparing the development styles and tools of desktop operating system environments to the mobile operating system environment, Android.

Brief History of Embedded Device Programming
For a long time, cell phone developers comprised a small sect of a slightly larger group of developers known as embedded device developers. Seen as a less “glamorous” sibling to desktop—and later web—development, embedded device development typically got the

Chapter 1:

What Is Android?

3

proverbial short end of the stick as far as hardware and operating system features, because embedded device manufacturers were notoriously stingy on feature support. Embedded device manufacturers typically needed to guard their hardware secrets closely, so they gave embedded device developers few libraries to call when trying to interact with a specific device. Embedded devices differ from desktops in that an embedded device is typically a “computer on a chip.” For example, consider your standard television remote control; it is not really seen as an overwhelming achievement of technological complexity. When any button is pressed, a chip interprets the signal in a way that has been programmed into the device. This allows the device to know what to expect from the input device (key pad), and how to respond to those commands (for example, turn on the television). This is a simple form of embedded device programming. However, believe it or not, simple devices such as these are definitely related to the roots of early cell phone devices and development. Most embedded devices ran (and in some cases still run) proprietary operating systems. The reason for choosing to create a proprietary operating system rather than use any consumer system was really a product of necessity. Simple devices did not need very robust and optimized operating systems. As a product of device evolution, many of the more complex embedded devices, such as early PDAs, household security systems, and GPSs, moved to somewhat standardized operating system platforms about five years ago. Small-footprint operating systems such as Linux, or even an embedded version of Microsoft Windows, have become more prevalent on many embedded devices. Around this time in device evolution, cell phones branched from other embedded devices onto their own path. This branching is evident when you examine their architecture. Nearly since their inception, cell phones have been fringe devices insofar as they run on proprietary software—software that is owned and controlled by the manufacturer, and is almost always considered to be a “closed” system. The practice of manufacturers using proprietary operating systems began more out of necessity than any other reason. That is, cell phone manufacturers typically used hardware that was completely developed in-house, or at least hardware that was specifically developed for the purposes of running cell phone equipment. As a result, there were no openly available, off-the-shelf software packages or solutions that would reliably interact with their hardware. Since the manufacturers also wanted to guard very closely their hardware trade secrets, some of which could be revealed by allowing access to the software level of the device, the common practice

4

Android: A Programmer’s Guide

was, and in most cases still is, to use completely proprietary and closed software to run their devices. The downside to this is that anyone who wanted to develop applications for cell phones needed to have intimate knowledge of the proprietary environment within which it was to run. The solution was to purchase expensive development tools directly from the manufacturer. This isolated many of the “homebrew” developers.

NOTE
A growing culture of homebrew developers has embraced cell phone application development. The term “homebrew” refers to the fact that these developers typically do not work for a cell phone development company and generally produce small, one-off products on their own time.

Another, more compelling “necessity” that kept cell phone development out of the hands of the everyday developer was the hardware manufacturers’ solution to the “memory versus need” dilemma. Until recently, cell phones did little more than execute and receive phone calls, track your contacts, and possibly send and receive short text messages; not really the “Swiss army knives” of technology they are today. Even as late as 2002, cell phones with cameras were not commonly found in the hands of consumers. By 1997, small applications such as calculators and games (Tetris, for example) crept their way onto cell phones, but the overwhelming function was still that of a phone dialer itself. Cell phones had not yet become the multiuse, multifunction personal tools they are today. No one yet saw the need for Internet browsing, MP3 playing, or any of the multitudes of functions we are accustomed to using today. It is possible that the cell phone manufacturers of 1997 did not fully perceive the need consumers would have for an all-in-one device. However, even if the need was present, a lack of device memory and storage capacity was an even bigger obstacle to overcome. More people may have wanted their devices to be all-in-one tools, but manufacturers still had to climb the memory hurdle. To put the problem simply, it takes memory to store and run applications on any device, cell phones included. Cell phones, as a device, until recently did not have the amount of memory available to them that would facilitate the inclusion of “extra” programs. Within the last two years, the price of memory has reached very low levels. Device manufacturers now have the ability to include more memory at lower prices. Many cell phones now have more standard memory than the average PC had in the mid-1990s. So, now that we have the need, and the memory, we can all jump in and develop cool applications for cell phones around the world, right? Not exactly.

Chapter 1:

What Is Android?

5

Device manufacturers still closely guard the operating systems that run on their devices. While a few have opened up to the point where they will allow some Java-based applications to run within a small environment on the phone, many do not allow this. Even the systems that do allow some Java apps to run do not allow the kind of access to the “core” system that standard desktop developers are accustomed to having.

Open Handset Alliance and Android
This barrier to application development began to crumble in November of 2007 when Google, under the Open Handset Alliance, released Android. The Open Handset Alliance is a group of hardware and software developers, including Google, NTT DoCoMo, Sprint Nextel, and HTC, whose goal is to create a more open cell phone environment. The first product to be released under the alliance is the mobile device operating system, Android. (For more information about the Open Handset Alliance, see www.openhandsetalliance.com.) With the release of Android, Google made available a host of development tools and tutorials to aid would-be developers onto the new system. Help files, the platform software development kit (SDK), and even a developers’ community can be found at Google’s Android website, http://code.google.com/android. This site should be your starting point, and I highly encourage you to visit the site.

NOTE
Google, in promoting the new Android operating system, even went as far as to create a $10 million contest looking for new and exciting Android applications.

While cell phones running Linux, Windows, and even PalmOS are easy to find, as of this writing, no hardware platforms have been announced for Android to run on. HTC, LG Electronics, Motorola, and Samsung are members of the Open Handset Alliance, under which Android has been released, so we can only hope that they have plans for a few Android-based devices in the near future. With its release in November 2007, the system itself is still in a software-only beta. This is good news for developers because it gives us a rare advance look at a future system and a chance to begin developing applications that will run as soon as the hardware is released.

6

Android: A Programmer’s Guide

NOTE
This strategy clearly gives the Open Handset Alliance a big advantage over other cell phone operating system developers, because there could be an uncountable number of applications available immediately for the first devices released to run Android.

Introduction to Android
Android, as a system, is a Java-based operating system that runs on the Linux 2.6 kernel. The system is very lightweight and full featured. Figure 1-1 shows the unmodified Android home screen.

Figure 1-1 The current Android home screen as seen on the Android Emulator.

Chapter 1:

What Is Android?

7

Android applications are developed using Java and can be ported rather easily to the new platform. If you have not yet downloaded Java or are unsure about which version you need, I detail the installation of the development environment in Chapter 2. Other features of Android include an accelerated 3-D graphics engine (based on hardware support), database support powered by SQLite, and an integrated web browser. If you are familiar with Java programming or are an OOP developer of any sort, you are likely used to programmatic user interface (UI) development—that is, UI placement which is handled directly within the program code. Android, while recognizing and allowing for programmatic UI development, also supports the newer, XML-based UI layout. XML UI layout is a fairly new concept to the average desktop developer. I will cover both the XML UI layout and the programmatic UI development in the supporting chapters of this book. One of the more exciting and compelling features of Android is that, because of its architecture, third-party applications—including those that are “home grown”—are executed with the same system priority as those that are bundled with the core system. This is a major departure from most systems, which give embedded system apps a greater execution priority than the thread priority available to apps created by third-party developers. Also, each application is executed within its own thread using a very lightweight virtual machine. Aside from the very generous SDK and the well-formed libraries that are available to us to develop with, the most exciting feature for Android developers is that we now have access to anything the operating system has access to. In other words, if you want to create an application that dials the phone, you have access to the phone’s dialer; if you want to create an application that utilizes the phone’s internal GPS (if equipped), you have access to it. The potential for developers to create dynamic and intriguing applications is now wide open. On top of all the features that are available from the Android side of the equation, Google has thrown in some very tantalizing features of its own. Developers of Android applications will be able to tie their applications into existing Google offerings such as Google Maps and the omnipresent Google Search. Suppose you want to write an application that pulls up a Google map of where an incoming call is emanating from, or you want to be able to store common search results with your contacts; the doors of possibility have been flung wide open with Android.

8

Android: A Programmer’s Guide

Chapter 2 begins your journey to Android development. You will learn the hows and whys of using specific development environments or integrated development environments (IDE), and you will download and install the Java IDE Eclipse.

Ask the Expert
Q: A: Q: A:
What is the difference between Google and the Open Handset Alliance? Google is a member of the Open Handset Alliance. Google, after purchasing the original developer of Android, released the operating system under the Open Handset Alliance. Is Android capable of running any Linux software? Not necessarily. While I am sure that there will be ways to get around most any open source system, applications need to be compiled using the Android SDK to run on Android. The main reason for this is that Android applications execute files in a specific format; this will be discussed in later chapters.

Chapter

2

Downloading and Installing Eclipse

Copyright © 2008 by The McGraw-Hill Companies. Click here for terms of use.

10

Android: A Programmer’s Guide

Key Skills & Concepts
● ● ●

Selecting a development environment Downloading Eclipse Installing and configuring Eclipse

A
TIP

ndroid applications are developed in Java. Android itself is not a language, but rather an environment within which to run applications. As such, you can theoretically use any distribution or integrated development environment (IDE) you have at your disposal to begin your development. In fact, you can choose to use no IDE at all.

In later chapters of this book, I will give you an introduction to developing Android applications without the use of an IDE—or “in the command-line interface (CLI).” While I will not cover every example in the book using this technique, you will get the basics of how to develop in the CLI.

If you are more comfortable with one Java IDE over any other, such as JBuilder by Borland or the open source NetBeans, feel free to use it. With a moderate level of experience, you should still be able to follow along with the majority of the examples in this book. However, the Open Handset Alliance and Google do endorse one Java IDE over any others: Eclipse.

NOTE
If you choose to follow the examples in this book without using Eclipse, you need to check your IDE’s documentation for compiling and testing your Android apps. The examples in this book give instructions only for compiling and testing in Eclipse, using the Android plugin for Eclipse.

This chapter concisely outlines the steps for downloading and installing Eclipse and the required Java Runtime Environment (JRE). Too many times, installation guides and

Chapter 2:

Downloading and Installing Eclipse

11

tutorials, in a quest to not shut out more technologically advanced readers, tend to skip simple steps such as this. I have found that texts that skip these smaller steps often overlook important items. For this reason, I am including all of the download and installation steps in this chapter.

Why Eclipse?
Why is Eclipse the recommended IDE for Android applications? There are a few reasons for this particular endorsement:
●

In keeping with the Open Handset Alliance’s theme of truly opening the mobile development market, Eclipse is one of the most fully featured, free, Java IDEs available. Eclipse is also very easy to use, with a minimal learning curve. This makes Eclipse a very attractive IDE for solid, open Java development. The Open Handset Alliance has released an Android plugin for Eclipse that allows you to create Android-specific projects, compile them, and use the Android Emulator to run and debug them. These tools and abilities will prove invaluable when you are creating your first Android apps. You can still create Android apps in other IDEs, but the Android plugin for Eclipse creates certain setup elements—such as files and compiler settings—for you. The help provided by the Android plugin for Eclipse saves you precious development time and greatly reduces the learning curve, which means you can spend more time creating incredible applications.

●

NOTE
Eclipse is also available for Mac and Linux. Having greater availability, on numerous operating systems, means that almost anyone can develop Android applications on any computer. However, the examples and screenshots in this book are given from the Microsoft Windows version of Eclipse. Keep this in mind if you are using Eclipse in a non-Microsoft environment; your interface may look slightly different from the screenshots, but the overall functionality should not change. If there is a major change in operation of Eclipse under Linux, I will include an example of that change. I will provide several examples from within a Linux environment. The majority of these examples will be from the Linux/Android command-line environment.

12

Android: A Programmer’s Guide

Downloading and Installing the JRE
Before you begin downloading and installing Eclipse, you have to make sure you have the Java Runtime Environment (JRE) downloaded and installed on your machine. Because Eclipse as an application was written in Java, it requires the JRE to run. If the JRE is not installed or is not detected, you will see the following error if you try to open the Eclipse environment:

If you are an existing Java developer and already have Java installed on your computer, you will still want to follow along here, just to be sure you have the correct version of the JRE installed.

NOTE
Most people who have used the Web, or applications that are web-based, have the JRE installed. The JRE allows you to run Java-based applications, but it does not allow you to create them. To create Java applications, you need to download and install the Java Development Kit (JDK), which contains all the tools and libraries needed to create Java applications. If you are not familiar with Java, keep these differences in mind. For the examples in this book, I will be downloading the JDK, because it also includes the JRE. Although you don’t need the JDK to run Eclipse, you can use it for other development later in the book.

Chapter 2:

Downloading and Installing Eclipse

13

Navigate to the Sun Developer Network (SDN) Downloads page at http:// developers.sun.com/downloads/, as shown in the following illustration. Normally you only need the JRE to run Eclipse, but for purposes of this book you should download the full JDK, which includes the JRE. The reason for downloading the full JDK is that later in the book I will also give some examples of how to create Android applications outside Eclipse, using just the JDK tools. If you want to follow along with these tutorials, you will need the full JDK.

14

Android: A Programmer’s Guide

From the SDN Downloads page, navigate to the download section for the proper JDK. Select and initiate the download, as shown in the following illustration:

For the examples in this book, I chose to go with the Java 5 JDK update 14 because it is explicitly defined in the Eclipse documentation as the “supported” version of Java. To download the Java 5 JDK, select the platform for which you want to download. You should be able to follow along just as easily if you choose to download the Java 6 JDK. However, if you do want to download the older JDK 5, you need to click the Previous Releases link, as shown next:

Chapter 2:

Downloading and Installing Eclipse

15

NOTE
You must agree to and accept the Sun licensing agreement on this page before you can initiate your download.

On the Java SE Previous Releases Downloads page, click the J2SE 5.0 Downloads link, and then click the Download button for JDK 5.0 Update x, where x is the latest update number (14 at the time of this writing but likely different by the time you read this).

16

Android: A Programmer’s Guide

If you are downloading to a Microsoft Windows environment, when you see the notification in the following illustration, click Run to begin the installation of the JDK.

CAUTION
If you want to retain a copy of the JDK package, click Save rather than Run. However, if you choose to save the JDK, be sure to note the location. After the download completes, you will need to navigate to the download location and execute the package manually.

During the installation process, you will be prompted to read and accept the License Agreement, shown next. After agreeing to the standard License Agreement and clicking Next, you will be able to select your custom setup options.

Chapter 2:

Downloading and Installing Eclipse

17

There is very little you need to change here, unless you are a more seasoned Java veteran and have particular options that you want to choose, in which case you should feel free to change the selections as you see fit. The following illustration shows the Custom Setup screen for the Java JDK.

To keep the process simple, and fairly standardized, you should accept the suggested packages—by default everything is selected—and continue the installation by clicking Next. Once again, if you are comfortable with making specific changes, feel free to do so. However, if you have trouble in later chapters, you will want to modify your installation options. When the Installation Completed page appears, shown in the following illustration, click Finish and your installation should be completed.

18

Android: A Programmer’s Guide

Once you complete the Java JDK installation—and by default the JRE installation—you can begin to install Eclipse.

Downloading and Installing Eclipse
Navigate to the Eclipse Downloads page at www.eclipse.org/downloads, shown in the following illustration. As the opening paragraph states, the JRE is required (Java 5 JRE recommended) to develop in Eclipse, which you took care of in the previous section. Download the Eclipse IDE for Java Developers from this site. The package is relatively small (79MB) and should download fairly quickly. Be sure not to download the Eclipse IDE for Java EE Developers, as this is a slightly different product and I will not be covering its usage.

Chapter 2:

Downloading and Installing Eclipse

19

After you have downloaded Eclipse, it is time to install it. Navigate to the location where you downloaded the Eclipse package. As of the writing of this book, the latest Eclipse package file for Microsoft Windows is eclipse-java-europa-fall2-win32.zip. Expand the package and run the eclipse.exe file. Eclipse installs to your User directory by default (under Microsoft Windows), but you may want to install it to your Program Files directory. This will keep your applications in order and still allow you to set a different location for your workspaces. The following illustration shows the Eclipse title screen that appears upon startup.

NOTE
If you do not see the splash screen shown in the illustration, try rebooting your machine. If rebooting does not help, download and install the Java 5 JRE only.

Once the Eclipse installation commences, you will be prompted to create a default workspace, or folder. Just as in most development environments, projects are created in, and saved to, a workspace. The default path for the workspace is your User directory, as shown in the illustration that follows. To select a different location, click Browse and navigate to it.

20

Android: A Programmer’s Guide

I recommend that you also check the check box that defaults all of your projects to the specified workspace. By checking this box, you will have one less thing to worry about when creating new projects and you will always know in what directory structure to find your source files. In this book, sometimes you will be navigating to the project files to work on them outside of the Android development environment, so knowing exactly where they are will be helpful. After you select a location for your workspace, click OK. At this point, your development environment is downloaded and installed. While the installation of Eclipse seemed deceivingly quick, you still need to do some configuration work before you can create your first Android project. Much of the configuration work that you need to do centers on the Android SDK and the Android plugin for Eclipse. Next you need to download and install the Android SDK, download and install the Android plugin for Eclipse, and configure the Eclipse settings. By the end of Chapter 3 you will have a fully configured development environment within which you can begin to create your applications. You will then explore the Android SDK and begin creating your first Hello World! application in Chapter 5.

Ask the Expert
Q: A: Q: A:
Eclipse is used to develop applications in Java, but can Android run applications written in any other languages? As of the writing of this book, there were no other SDKs or emulators available to allow Android development in any language other than Java. Can you use Eclipse (and the Android SDK) with a version of the JRE other than version 5? Technically you can use Eclipse with versions 5 and newer. However, the latest version of Eclipse was only tested on the Java 5 JRE.

Chapter

3

Downloading and Installing the Android SDK

Copyright © 2008 by The McGraw-Hill Companies. Click here for terms of use.

22

Android: A Programmer’s Guide

Key Skills & Concepts
● ● ● ●

Downloading the Android SDK Using the Update feature of Eclipse Downloading, installing, and configuring the Android plugin for Eclipse Checking the PATH statement

I

n the previous chapter, you downloaded and installed your primary development environment, Eclipse. Now that your initial development environment is established, using Eclipse as your Java IDE, you can use it to develop Java applications, but you have one more step before you can begin creating mobile phone applications. You must configure it in a way that will facilitate Android development. Because Eclipse is a Java development environment, you can create and edit Java projects with great ease. However, given that you have no libraries yet for understanding how Android applications should behave, you cannot develop anything that will run on an Android-based device. To begin creating Android projects, you need to download and install the Android SDK. You must then download the related Android plugin for Eclipse to utilize the SDK within the Eclipse IDE. With these pieces in place, you can begin your development. If you have any development experience, you are most likely familiar with the process of using an SDK. Desktop application developers, regardless of the platform they are developing on, use SDKs to create applications that will run on the desired system they are developing on. The Android SDK is no different from any other SDK in that it contains all the Java code libraries needed to create applications that run specifically on the Android platform. The SDK also includes help files, documentation, an Android Emulator, and a host of other development and debugging tools.

NOTE
Chapter 4 covers most of the functionality of the Android SDK in depth.

To begin, you are going to download the Android SDK from the Google Android development site, located at http://code.google.com/android. The Google Android

Chapter 3: Downloading and Installing the Android SDK

23

development home page contains a host of valuable tools and documents about developing for the Android platform, including links to the Android developer forum (or “community”). Figure 3-1 shows the home page for Google Android development.

TIP
If you ever encounter a problem while you are developing an Android application, the first place you should look for an answer is the Android developers’ forum at http://code.google.com/android/groups.html. There are discussion groups for beginners, developers, and “hackers,” and a general-issue discussion group. Given that Android is such a new platform, the Android developers’ forum is one of the few places to find comprehensive, reliable information about developing for the product.

Figure 3-1 The Google Android development home page.

24

Android: A Programmer’s Guide

Downloading the Android SDK
The Android SDK is easily accessible from the http://code.google.com/android page. From the development home page, click the Download the SDK link under Getting Started. After you agree to the terms of the Android SDK License Agreement, you will see the Download the Android SDK page. The Android SDK is downloaded in a 79MB (for Windows) package and it should download fairly quickly. Click the package name for your operating system to begin the download.

NOTE
Download sizes for other operating systems may vary.

There is no “setup” or installation process to speak of for the Android SDK; rather, you must follow a series of steps to associate the SDK with your Eclipse development environment. The first of these steps is to obtain the Android plugin for Eclipse, after which you will configure it.

Downloading and Installing the Android Plugin for Eclipse
The first step in setting up the Android SDK within the Eclipse development environment is to download and install the Android plugin for Eclipse. Both tasks of downloading and installing the plugin can be performed at the same time, and are relatively easy to do:
1. Open the Eclipse application. You will download the Android plugin for Eclipse from

within the Eclipse IDE.
2. Choose Help | Software Updates | Find and Install.

Chapter 3: Downloading and Installing the Android SDK

25

3. In the Install/Update window, which allows you to begin the process of downloading

and installing any of the plugins that are available to you for Eclipse, click the Search for New Features to Install radio button and then click Next.

26

Android: A Programmer’s Guide

4. The Update Sites to Visit page of the Install window, shown next, lists all the default

websites used for obtaining Eclipse plugins. However, the plugin you want, Android for Eclipse, is not available from the default sites. To download the Android plugin, you must tell Eclipse where to look for it, so click the New Remote Site button.

5. In the New Update Site dialog box, shown next, you must enter two pieces of

information to continue: a name for your new site, and its associated URL. The name is only for display purposes and does not affect the downloading of the plugin. In the Name field, enter Android Plugin. In the URL field, enter the URL from which Eclipse will obtain information about the plugins that are available: https://dl-ssl.google.com/android/eclipse/. Click OK.

Chapter 3: Downloading and Installing the Android SDK

27

NOTE
The name for your site can be anything you want, as long as it will help you identify what the link is. Feel free to use something other than Android Plugin.

6. A new site named Android Plugin should now be in your list of available sites:

28

Android: A Programmer’s Guide

At this point Eclipse has not yet looked for the plugin; this is just a list of paths that you can tell Eclipse to check when looking for new plugins to install.
7. Check the check box next to Android Plugin and then click Finish. Eclipse searches the

URL associated with the Android Plugin site for any available plugins.
8. On the Search Results page of the Updates window, select the Android Plugin and then

click Finish.

Chapter 3: Downloading and Installing the Android SDK

29

9. On the Feature License page of the Install window, shown next, accept the licensing

agreement for the Android Development Tools and click Next.

NOTE
Keep in mind that all Eclipse plugins are installed to the %installpath%/eclipse/plugins directory. This information will help you if you need to locate the files that make up the Android plugin.

30

Android: A Programmer’s Guide

10. Eclipse downloads the Android plugin. At the time of this writing, the plugin version is

0.4.0.200802081635. On the final plugin installation page, Feature Verification, click Install All to complete the installation of the Android plugin.

With the Android plugin installed, the last step you have to perform is to configure the plugin.

Configuring the Android Plugin for Eclipse
After installing the Android plugin for Eclipse, Eclipse should have prompted you to restart the application. If it did not prompt you, restart Eclipse now. Restarting Eclipse will ensure that the program has a chance to reinitialize with the plugin installed. It is

Chapter 3: Downloading and Installing the Android SDK

31

important to make sure configuration steps like this are followed in order to reduce the chance of misconfigurations. The Android plugin for Eclipse is configured from the Preferences window of Eclipse. Proceed as follows:
1. From the main Eclipse window, choose Window | Preferences. 2. In the Preferences window, shown next, select Android in the menu on the left. On the

right side of the window, click Browse, find the location of the Android SDK on your hard drive, and enter it in the SDK Location field. Eclipse needs this information to be able to access all the tools that are supplied with Android, such as the emulator.

32

Android: A Programmer’s Guide

3. Check the Automatically Sync Projects to Current SDK check box and then

click Apply.

NOTE
The Android plugin for Windows is shipped in a zip file that contains a directory with a very long directory name: android-sdk_m5-rc14-win32. It may help you in future chapters, especially when command-line programming, to rename this directory to something more manageable. You may also want to extract the SDK to the Program Files directory.

4. The final step in setting up the Android SDK is to put it into your PATH statement. If

you are using a Microsoft Windows machine, right-click Computer (or My Computer, depending on your version of Windows) and select Properties to open the System Properties dialog box. Click the Advanced tab.
5. Click Environment Variables to display the window of the same name, shown in the

following illustration. This is where you can edit your PATH statement.

Chapter 3: Downloading and Installing the Android SDK

33

6. Under System Variables, find the variable PATH and double-click it. 7. In the Edit System Variable dialog box, shown next, add the location of your Android

SDK—separated from the existing paths by a semicolon—and click OK to apply your changes, and click OK again in the Environment Variables window.

The Android SDK, Eclipse, and the Android plugin for Eclipse are now fully configured and ready for development. In the next chapter, you will explore the Android SDK, and learn about its features. The Android SDK contains many tools to help you develop full-featured cell phone applications, and the next chapter provides a good overview.

Ask the Expert
Q: A: Q: A:
Is the Android SDK available for any languages other than Java? No. Android applications can be developed only in Java. Will there be updates to the Android SDK? Yes! Even during the writing of this book, an SDK update was released that addresses many issues within the platform. I suggest checking the development page often for the latest updates.

(continued)

34

Android: A Programmer’s Guide

Q: A:

If an update is released, how do I upgrade my SDK? Upgrading the SDK can be very tricky. When a new SDK is released, chances are a new plugin is also released. During the writing of this book, both a new SDK and a new plugin were released. I attempted to use the “provided” upgrade tools to change versions. However, this proved fruitless and left me with two conflicting versions, neither of which worked correctly. I eventually had to uninstall both versions and reinstall only the latest version. The newest SDK then worked correctly. I suggest that anyone faced with the possibility of upgrading from one version of an SDK/plugin combo to another use this same process: simply uninstall the older version, and install the newer one, rather than upgrading.

Chapter

4

Exploring the Android SDK

Copyright © 2008 by The McGraw-Hill Companies. Click here for terms of use.

36

Android: A Programmer’s Guide

Key Skills & Concepts
● ● ● ●

Using the Android SDK documentation Using the Android SDK tools Using the sample applications Learning the life cycle of an Android application

N

ow that you have your development environment established, you are ready to explore the Android SDK, which contains multiple files and tools specifically intended to help you design and develop applications that run on the Android platform. These tools are very well designed and can help you make some incredible applications. You really need to be familiar with the Android SDK and its tools before you begin programming. The Android SDK also contains libraries for tying your applications into core Android features such as those associated with cell phone functions (making and receiving calls), GPS functionality, and text messaging. These libraries make up the core of the SDK and will be the ones that you use most often, so take the time to learn all about these core libraries. This chapter covers all of the important items contained within the Android SDK. By the end of the chapter, after familiarizing yourself with the contents of the Android SDK, you will be comfortable enough to begin writing applications. However, as with any subject, before you can dive into the practice of the discipline, you must familiarize yourself with its contents and instructions.

CAUTION
I am not going to go over every minute detail of the Android SDK; Google does a very good job of that within its documentation. To avoid the risk of spending too much time discussing how things work instead of showing you how they work, I have tried to keep this discussion as brief as possible. I cover only the most important topics and items, leaving you free to explore the rest in more depth yourself, at your own pace.

Chapter 4:

Exploring the Android SDK

37

What Is in the Android SDK?
The Android SDK is downloaded in a simple zipped package (as described in Chapter 3). The bulk of the Android SDK, in number of files, consists of documentation, with programming APIs, tools, and samples comprising the rest. This section provides a closer look at exactly what is included in the Android SDK.

TIP
Chapter 3 suggested that you extract the Android SDK to the Program Files folder, so that it would be easier to track. If you are having trouble finding the SDK because you used the default extraction setting, it should be in the following folder: /%downloadfolder%/android-sdk_m5-rc14_windows/android-sdk_m5-rc14_windows.

Navigate to the folder where you unpacked the Android SDK so that you can begin to explore the folder structure within. While there are a few files in the root folder, like android.jar (a compiled Java application containing the core SDK libraries and APIs) and some release notes, the remainder of the Android SDK is divided into three main folders:
●

Docs

Contains all of the accompanying Android documentation

NOTE
Much of the documentation found in the Docs folder can also be found on the http://code.google.com/android Android development site.
●

Samples Contains six sample applications that you can compile and test from within Eclipse Tools Contains all of the development, compilation, and debugging tools that you need throughout the development process of an Android application

●

The following sections discuss in a bit more detail what is included in each of the SDK folders. Each API demo is compiled and run to illustrate the capabilities of Android. Many of the tools are discussed and demonstrated in later chapters as you learn how to create and compile applications using the command-line options of Microsoft Windows and Linux.

38

Android: A Programmer’s Guide

Android Documentation
The Android documentation is located in the Docs folder within the Android SDK at ../%sdk folder%/DOCS. The documentation that is supplied with the SDK includes steps on downloading and installing the SDK, “Getting Started” quick steps for developing applications, and package definitions. The documentation is in HTML format and can be accessed though the documentation.html file in the root of the SDK folder. The following illustration depicts the main page of the Android SDK documentation.

You can navigate to all of the documentation that is included in the Android SDK by using the links within documentation.html.

Chapter 4:

Exploring the Android SDK

39

CAUTION
As you are navigating the Android SDK, you may think some pages are mislinked or missing, because the right side of the screen may be blank when you click some links. However, if you scroll down you will see that the pages are just misaligned.

In working with the Android SDK, I have found that there are sections of the documentation that I refer to more than others. For me, the most valuable segments of the Android SDK documentation are as follows (as they appear in the navigation bar):
●

Reference Information
● ● ●

Class Index List of Permissions List of Resource Types

●

FAQs
●

Troubleshooting

The Troubleshooting subsection of the documentation will be especially helpful as you are starting out. As you progress through the book and begin to develop your own Android applications, you will find that the Reference Information section of the documentation is more helpful. For example, while it would have little to no use to you now, the List of Permissions subsection will be very helpful to you when you progress to the section of the book that deals with creating more complex applications. Take some time to familiarize yourself with the Android SDK documentation and the hundreds of documents that have been provided for you.

Android Samples
The Samples folder, ../%sdk folder%/SAMPLES, contains six sample applications that demonstrate a good cross-section of Android functionality:
● ● ●

API Demos Hello, Activity! Lunar Lander

40

Android: A Programmer’s Guide

● ● ●

Note Pad Skeleton App Snake

These sample applications are provided by Google to give you a quick idea of how to develop an Android application. Each sample application demonstrates a different piece of Android’s functionality. You can open and run these applications from within Eclipse. Following is a brief description of each.

API Demos
The API Demos application is a host application that demonstrates multiple API functions in a single Activity.

TIP
An Activity is an Android application. Activities are covered in more depth in the following chapters.

The API Demos application, as shown in the following illustration, contains multiple, smaller, examples of different Android functions:

Chapter 4:

Exploring the Android SDK

41

Some of the applications included in the API Demos sample include 3-D image transitions, list and progress dialog boxes, and a finger-painting demo.

Try This

Run the API Demos Sample Application

Using Eclipse, load the API Demos application as a New Android Project. To do this, select File | New | Project from the Eclipse menu bar; a New Android Project wizard opens. Do not worry about the options in this wizard for now. Simply select Create Project From Existing Source and browse to the folder with the API Demo application in it. When the project is loaded, choose Run to see it execute in the Android Emulator. Navigate your way through the more than 40 different applications. Use each application to become familiar with the terminology and function of each API tool it demonstrates.

Hello, Activity!
The Hello, Activity! application, shown in the following illustration, is a simple Hello World!–style application. Though simple in its design, Hello, Activity! does a good job of showing off the abilities of the platform. You will create your own Hello World!–style applications in the next chapter.

42

Android: A Programmer’s Guide

Lunar Lander
Lunar Lander, shown next, is a small game that plays on the Android Emulator. Lunar Lander shows how a simple 2-D game works on Android. The controls are fairly simple, and the game is not very complex. However, given these drawbacks, it is a great starter for game development.

Lunar Lander implements a simple control scheme (Up, Down, Left, and Right). The game also displays relatively fluid graphics and looks impressive given the platform. Complex game theories such as collision detection are used in a simple way. Although this book does not cover programming games for the Android platform, if you are interested in doing so, you may want to look at Lunar Lander for some tips.

Chapter 4:

Exploring the Android SDK

43

Note Pad
Note Pad, as shown in the illustration that follows, allows you to open, create, and edit small notes. Note Pad is not a full-featured word editor, so do not expect it to be something to rival Word for Windows Mobile. However, it does a good job as a demonstration tool to show what is possible with a relatively small amount of code.

Skeleton App
Skeleton App, shown next, is an application shell. This is more of a base application that demonstrates a couple of different application features, such as fonts, buttons, images, and forms. If you are going to run Skeleton App by itself, you really are not going to get much

44

Android: A Programmer’s Guide

out of it. You will be better served by referring to Skeleton App as a resource for how to implement specific items.

Snake
The final demo that is included with the Android SDK is Snake. This is a small, SNAFU-style game that is far more simplistic than Lunar Lander. This illustration shows what Snake looks like when run.

Chapter 4:

Exploring the Android SDK

45

NOTE
If you navigate to the base folder of each of the sample applications, you will see a folder named src. This is the source code folder for the given sample application. You can use this to view, edit, and recompile the code for any of the applications. Take advantage of this source code to learn some tricks and tips about the Android platform.

Android Tools
The Android SDK supplies developers with a number of powerful and useful tools. Throughout this book, you will use only a handful of them directly. This section takes a quick look at just a few of these tools, which will be covered in much more depth in the following chapters, as you dive into command-line development.

NOTE
For more detailed information about the other tools included in the Android SDK, consult the Android doc files.

emulator.exe
Arguably one of the most important tools included in the Android SDK is emulator.exe. emulator.exe launches the Android Emulator. The Android Emulator is used to run your applications in a pseudo-Android environment. Given that, as of the writing of this book, there were no hardware devices yet released for the Android platform, emulator.exe is going to be your only means to test applications on a “native” platform. You can run emulator.exe from the command line or execute it from within Eclipse. In this book, you’ll usually let Eclipse launch the Android Emulator environment for you. However, in the interest of giving you all the information you need to program with the Android SDK outside of Eclipse, Chapter 6 covers command-line usage of emulator.exe when you create your Hello World! applications. When using the Android Emulator to test your applications, you have two choices for navigating the user interface. First, the emulator comes with usable buttons, as shown in Figure 4-1. You can use these buttons to navigate Android and any applications that you develop for the platform.

TIP
The Power On/Off, Volume Up, and Volume Down buttons are slightly hidden to the sides of the virtual device. They identify themselves when you hover the mouse pointer over them.

46

Android: A Programmer’s Guide

Volume up

Volume down

Power on/off

Full QWERTY keyboard

Full telephone keypad

Menu Home Send call Back End call

Left, right, up, down, and Select pad

Figure 4-1 Navigating with the Android Emulator

Given that many higher-end phones now include a touch screen, the second input choice you have when using the emulator is a simulated touch screen. You use your mouse as a stylus. The objects on the emulator’s screen can be interacted with using the mouse.

adb.exe
Another tool that will become very useful to you when you are using command-line programming is Android Debug Bridge or adb (adb.exe). This tool allows you to issue

Chapter 4:

Exploring the Android SDK

47

commands to the Emulator.exe tool. When you are working in a command-line environment, the adb tool allows you to do the following:
● ● ●

Start and stop the server Install and uninstall applications Move files to and from the emulator

MKSDCARD.exe
MKSDCARD.exe is a very useful tool if you are testing an application that will need to read or write files to or from an SD Memory Card inserted into the mobile device. MKSDCARD.exe creates a small partition drive on your drive that will hold and retain the test files. The emulator will treat this partition like an SD Memory Card.

DX.exe
DX.exe is the compiler of the Android SDK. When run against your Java files, DX.exe will create files with .dex extensions—Dalvik executable format. These files are in the correct format to be understood by, and run on, an Android device.

NOTE
Android executable files are called Dalvik executable files as a reference to the Dalvik virtual machine that Android used to run all applications. The Dalvik virtual machine runs each application in its own thread with the same priority as core Android applications.

activityCreator(.bat or .pn) activityCreator is a simple command-line tool that is used to set up a basic development environment. When run from the command line, activityCreator will set up the shell files needed to create a basic Android application. Having these shell files is especially useful if you are not using Eclipse. The Android plugin for Eclipse sets up these shell files for you by calling the activityCreator when you create a new project. Depending on what type of environment you are running, you will see the activityCreator represented by a different type of script file. If you are in a Windows environment, this will be a .bat file; otherwise it will be a python (.pn) script. You simply execute the script, which in turn calls the actual activityCreator process with the correct parameters.

48

Android: A Programmer’s Guide

APIs
The API, or application programming interface, is the core of the Android SDK. An API is a collection of functions, methods, properties, classes, and libraries that is used by application developers to create programs that work on specific platforms. The Android API contains all the specific information that you need to create applications that can work on and interact with an Android-based application. The Android SDK also contains two supplementary sets of APIs—the Google APIs and the Optional APIs. Subsequent chapters will focus much more on these APIs as you begin writing applications that utilize them. For now, take a quick look at what they include so that you are familiar with their uses.

Google APIs
The Google APIs are included in the Android SDK and contain the programming references that allow you to tie your applications into existing Google services. If you are writing an Android application and want to allow your user to access Google services through your application, you need to include the Google API. Located in the android.jar file, the Google API is contained within the com.google.* package. There are quite a few packages that are included with the Google API. Some of the packages that are shipped in the Google API include those for graphics, portability, contacts, and calendar utilities. However, the packages devoted to Google Maps will be the primary focus in this book. Using the com.google.android.maps package, which contains information for Google Maps, you can create applications that interact seamlessly with the already familiar interface of Google Maps. This one set of packages opens a whole world of useful applications just waiting to be created. The Google API also contains a useful set of packages that allows you to take advantage of the newer Extensible Messaging and Presence Protocol (XMPP) developed by the Jabber open source community. Using XMPP, applications can quickly become aware of other clients’ presence and availability for the purpose of messaging and communications. The API packages dealing with XMPP are very useful if you want to create a “chat”-style program that utilizes the phone messaging capabilities.

Optional APIs
The Android SDK includes a number of Optional APIs that cover functionality not covered by the standard Android APIs. These Optional APIs are considered optional because they deal with functionality that may or may not be present on a given handset

Chapter 4:

Exploring the Android SDK

49

device. That is, some devices created for the Android platform may include upgrades and features that others do not; the Optional APIs cover your programming options when trying to utilize these features in your Android applications. One of these optional features (which you will use later in the book) is a cell-phone-based GPS. The Android LBS (Location-Based Services) API deals with the functionality needed to receive and utilize information from a device’s GPS unit. (Combine the information in the Android LBS API with that in the Google Maps API, and you might have a very useful application that can automatically display a map of where you are located at any given point in time.) Other Optional APIs include those for utilizing Bluetooth, Wi-Fi, playing MP3s, and accessing 3-D—OpenGL-enable hardware.

Application Life Cycle
If you have a decent amount of experience as an application developer, you are familiar with the concept of an application life cycle. An application life cycle consists of the steps that the application’s processes must follow from execution to termination. Every application, regardless of the language it was written in, has a specific life cycle, and Android applications are no exception. This section examines the life cycle of an ASP application and compares that to an Android application’s life cycle.

Standard ASP Application Life Cycle
The life cycle of a standard ASP application is similar enough to that of an Android application to make this a good comparison. ASP applications step through five distinct processes from launch to disposal. These steps are required to be implemented by all ASP applications, and really define what an ASP application is. The steps, in order, are
1. Application_Start 2. Event 3. HTTPApplication.Init 4. Disposal 5. Application_End

50

Android: A Programmer’s Guide

TIP
Some ASP reference materials consider Disposal and Application_End to be one step in the life cycle. However, the Disposal call can be intercepted before it is passed to Application_End. This can allow the application to perform specific functions before it is actually destroyed.

Application_Start is called when the application is requested from the server. This process in turn leads into the Event process(es). When all associated application modules have loaded, HTTPApplication.Init is called. The application executes its events, and when the user attempts to close it, Dispose is called. Dispose then passes processing on to the Application_End process, which closes the application. This is a fairly standard application life cycle. Most applications follow similar life cycles: an application is created, loaded, has events, and is destroyed. The following section demonstrates how this compares to the Android application life cycle.

Android Application Life Cycle
The Android application life cycle is unique in that the system controls much of the life cycle of the application. All Android applications, or Activities, are run within their own process. All of the running processes are watched by Android and, depending on how the activity is running (this is, a foreground activity, background activity, and so forth), Android may choose to end the activity to reclaim needed resources.

NOTE
When deciding whether an activity should be shut down, Android takes into account several factors, such as user input, memory usage, and processing time.

Some of the specific methods called during the life cycle of an android activity are
● ● ● ● ●

onCreate onStart Process-specific events (for example: launching activities or accessing a database) onStop onDestroy

Following the same logic as other application life cycles, an Android application is created, the processes are started, events are fired, processes are stopped, and the application is destroyed. Though there are a few differences, many application developers should be comfortable with the steps in the life cycle.

Chapter 4:

Exploring the Android SDK

51

Ask the Expert
Q: A: Q: A:
Does Google ever update the Android SDK? Yes. From the time I started writing this book, Google had already updated the Android SDK three times. Google will post the updates to the Android website as they are available. Do any of the API Demos represent applications that will be in the finished product? Probably not. The API Demos were created to show off the capabilities of the product. Although there may be core “release” applications that contain some of the elements found in the API Demos, we probably will not see Lunar Lander in the finished version.

This page intentionally left blank

Chapter

5

Application: Hello World!

Copyright © 2008 by The McGraw-Hill Companies. Click here for terms of use.

54

Android: A Programmer’s Guide

Key Skills & Concepts
● ● ● ● ●

Creating new Android projects Working with Views Using a TextView Modifying the main.xml file Running applications on the Android Emulator

I

n this chapter, you will be creating your first Android Activity. This chapter examines the application-building process from start to finish. I will show you how to create an Android project in Eclipse, add code to the initial files, and run the finished application in the Android Emulator. The resulting application will be a fully functioning program running in an Android environment. Actually, as you move through this chapter, you will be creating more than one Android Activity. Computer programming tradition dictates that your first application be the typical Hello World! application, so in the first section you will create a standard Hello World! application with just a blank background and the “Hello World!” text. Then, for the sake of enabling you to get to know the language better, the next section explains in detail the files automatically created by Android for your Hello World! application. You will create two iterations of this Activity, each using different techniques for displaying information to the screen. You will also create two different versions of a Hello World! application that will display an image that delivers the “Hello World!” message. This will give you a good introduction to the controls and inner workings of Android.

NOTE
You will often see “application” and “Activity” used interchangeably. The difference between the two is that an application can be composed of multiple Activities, but one application must have at least one Activity. Each “window” or screen of your application is a separate Activity. Therefore, if you create a fairly simple application with only one screen of data (like the Hello World! application in this chapter), that will be one Activity. In future chapters you will create applications with multiple Activities.

Chapter 5:

Application: Hello World!

55

To make sure that you get a good overall look at programming in Android, in Chapter 6 you will create both of these applications in the Android SDK command-line environment for Microsoft Windows and Linux. In other words, this chapter covers the creation process in Eclipse, and Chapter 6 covers the creation process using the command-line tools. Therefore, before continuing, you should check that your Eclipse environment is correctly configured. Review the steps in Chapter 3 for setting the PATH statement for the Android SDK. You should also ensure that the JRE is correctly in your PATH statement.

TIP
If you have configuration-related issues while attempting to work with any of the command-line examples, try referring to the configuration steps in Chapters 2 and 3; and look at the Android SDK documentation.

Creating Your First Android Project in Eclipse
To start your first Android project, open Eclipse. When you open Eclipse for the first time, it opens to an empty development environment (see Figure 5-1), which is where you want to begin. Your first task is to set up and name the workspace for your application. Choose File | New | Android Project, which will launch the New Android Project wizard.

CAUTION
Do not select Java Project from the New menu. While Android applications are written in Java, and you are doing all of your development in Java projects, this option will create a standard Java application. Selecting Android Project enables you to create Android-specific applications. If you do not see the option for Android Project, this indicates that the Android plugin for Eclipse was not fully or correctly installed. Review the procedure in Chapter 3 for installing the Android plugin for Eclipse to correct this.

The New Android Project wizard creates two things for you:
●

A shell application that ties into the Android SDK, using the android.jar file, and ties the project into the Android Emulator. This allows you to code using all of the Android libraries and packages, and also lets you debug your applications in the proper environment.

56

Android: A Programmer’s Guide

Figure 5-1 The empty Eclipse development environment

●

Your first shell files for the new project. These shell files contain some of the vital application blocks upon which you will be building your programs. In much the same way as creating a Microsoft .NET application in Visual Studio generates some Windows-created program code in your files, using the Android Project wizard in Eclipse generates your initial program files and some Android-created code.

In addition, the New Android Project wizard contains a few options, shown next, that you must set to initiate your Android project.

Chapter 5:

Application: Hello World!

57

For the Project Name field, for purposes of this example, use the title HelloWorldText. This name sufficiently distinguishes this Hello World! project from the others that you will be creating in this chapter. In the Contents area, keep the default selections: the Create New Project in Workspace radio button should be selected and the Use Default Location check box should be checked. This will allow Eclipse to create your project in your default workspace directory. The advantage of keeping the default options is that your projects are kept in a central location, which makes ordering, managing, and finding these projects quite easy. For example, if you are working in a Unix-based environment, this path points to your $HOME directory.

58

Android: A Programmer’s Guide

If you are working in a Microsoft Windows environment, the workspace path will be C:/Users//workspace, as shown in the previous illustration. However, for any number of reasons, you may want to uncheck the Use Default Location check box and select a different location for your project. One reason you may want to specify a different location here is simply if you want to choose a location for this specific project that is separate from other Android projects. For example, you may want to keep the projects that you create in this book in a different location from projects that you create in the future on your own. If so, simply override the Location option to specify your own custom location directory for this project. On the other hand, you may be required to specify a project location if you did not check the Use This as the Default and Do Not Ask Again check box in the Select a Default Workspace dialog box during the Eclipse setup (as recommended in the last section of Chapter 2). Checking that box during the Eclipse setup defaults all new projects to the workspace directory (and provides the default location shown in the Location field of the New Android Project wizard). If you did not check this box during the Eclipse setup process, you need to select a path for your new project now by clicking the Browse button and navigating to it. The final three options in the New Android Project wizard are in the Properties area. These properties define how your project is integrated into the Android environment. In the Package Name field, you specify the namespace given to your application package. For example, android.app.Activity or com.google.android.map.MapActivity.

CAUTION
The package name adheres to the standard Java package-naming guidelines, which were established to lower the risk of two packages being released with the same name. The top level of the package name is the domain identifier of the company (com, org, and net are examples). This is followed by the domain name, such as google. Finally, a descriptive title for the contents of the package is provided. For purposes of this chapter, my package name for the Hello World! application will omit “com” to identify that it is a text application and not meant to be published. All future packages created in this book will be publishable and use the com identifier.

For the HelloWorldText application, use the package name android_programmers_ guide.HelloWorldText. This name uniquely identifies the code that belongs to this application and differentiates this test application from others you will develop in this book.

CAUTION
If you are paying attention to the screen as you are typing, you will notice that an error message appears at the top of the wizard as you enter the package name, stating that you must fill out all the fields properly to continue. This error message is premature and can be a bit confusing because you have not even attempted to fill out the other fields in the Properties area. If you see such an error message, just ignore it and continue on and complete the next two fields in Properties area.

Chapter 5:

Application: Hello World!

59

The next Properties field, Activity Name, is required because it is the reference to the main screen of your application. That is, think of the Activity as the “window” within which your application is displayed. Without an Activity, your application would not do very much. However, because Android applications can be composed of several Activities, the New Android Project wizard needs to know which Activity will be the default. Activity Name is a required field and has no default, so you must supply one to continue (as indicated in the preceding caution). For purposes of this example, use HelloWorldText. This keeps the application simple and is just about as descriptive as it needs to be for the moment. The final Properties field, Application Name, specifies the name of your application. This is the name that will be used to manage your application when it is installed on the device. Again, for the sake of keeping things simple, go with HelloWorldText as the application name. The following illustration shows the completed New Android Project wizard.

60

Android: A Programmer’s Guide

TIP
The Application Name and the Activity Name fields do not have to match. In fact, many programmers are used to the older conventions whereby the “starting” screen of an application is usually called Main or Startup. Use whatever conventions you are comfortable with. For purposes of demonstration, this chapter assumes that you are using the names suggested.

Click Finish to kick off the creation process. The wizard runs a background process that facilitates the auto-generation of some required files, and the setup of the directory structure needed to support an Android application. When the process is complete, you will have your first Android application project, like that shown in Figure 5-2.

Figure 5-2 Your first Android application project

Chapter 5:

Application: Hello World!

61

TIP
If the Finish button is not available to you, you may have made an error in one of the fields in the Properties area. To ensure that the Properties fields are correctly filled in, Eclipse will not allow you to finish the process if any of the information that you entered may cause problems. Go back and make sure that all of the Properties fields are correctly filled in.

The next section examines the contents of the auto-generated Android files and the purpose of some of the shell items for your application.

Examining the Android-Created Files
This section discusses the new files that Android has just created for you. A fairly robust structure has been created for you, and if you do not know what you are looking at, you may end up putting some code in places that you should not. There are files provided by Android that you need to modify, and there are ones that you should not modify; knowing the difference may save you from having to re-create your project. With your new application project open, take a look at the Package Explorer, one of two tabs located in the pane to the left of the main development area. The following illustration shows what the Package Explorer should look like.

NOTE
If the Package Explorer is not open, you can activate it by choosing Window | Show View | Package Explorer.

62

Android: A Programmer’s Guide

You should see a root directory, in this case named HelloWorldText. The root directory is the home, or repository, for all of your project files. Both your user-created files and the Android auto-generated files will be placed in the directory, easily accessible from the Package Explorer. Currently there should be a few items in your root directory: an AndroidManifest.xml file, a package included in the Referenced Libraries, and three directories (res, assets, and src). These items are discussed in turn next.

AndroidManifest.xml
The AndroidManifest.xml file is where your global settings are made. If you are an ASP.NET developer, you can think of AndroidManifest.xml as Web.config and Global.asax rolled into one. (If you are not an ASP.NET developer, this means that AndroidManifest.xml is a place for storing settings.) AndroidManifest.xml will include such settings as application permissions, Activities, and intent filters. The standard AndroidManifest.xml file should contain the following information:

As you create future applications, you will be adding information to this file. Notice that the package name you supplied is listed here, as well as the action that your Activity will handle.

Referenced Libraries
A list of the Referenced Libraries is also included in the root of the project. Typically, for a beginner project, you should see only one library here. Expand the Referenced Libraries branch and examine its contents, the libraries that are currently referenced by

Chapter 5:

Application: Hello World!

63

your application project. Given that this is a new Android project, you will see one library in your project’s references, android.jar, the Android SDK. (If you are familiar with the Java SDK, android.java is analogous to Java’s rt.java file, containing many of the Java APIs found in rt.java.) The Android plugin ensures that this file is the only library referenced by your application. The application needs to reference the SDK to gain access to all the classes contained in the SDK libraries, such as your Views, Controls, and even the Google API.

CAUTION
Eclipse enables you to add other user-defined libraries and external classes to your project’s references. However, unless you are sure that those external references will work with your Android application (and thus on the Android platform), you should think twice before you add them.

Directories
There are also three directories in the project root—res, assets, and src—each of which has a distinct purpose. These directories play an integral part in the operation of your application.

res Directory
The res directory is where your in project resources are held and compiled into your application. When you create a new Android project, the res directory contains three subdirectories: drawable, layout, and values. You will use the drawable and layout directories in many of your projects to hold and display images and layouts respectively, whereas the values directory holds string globals that can be used throughout your application.

NOTE
A reference to the res directory and its contents is contained by the R.java file, located in the src directory. This file is covered in much more detail later in the chapter.

The drawable directory contains actual image files that your application can use and reference. The layout directory holds an XML file, main.xml, that is referenced by your application when building its interface. In most of the applications in this book, you will be editing the main.xml file included in the layout directory. This will allow you to insert

64

Android: A Programmer’s Guide

Views into the application’s visual layout and display them. An unaltered main.xml file contains the following code:

The last directory under res, values, holds an XML file named strings. The strings.xml file is used to hold global string values that can be referenced by your application.

assets Directory
The assets directory is used to hold raw asset files. The files contained in the assets directory can include audio files for streaming and animation assets. I will not use any audio assets in the applications for this book because the beta audio drivers for the Android Emulator are not yet optimized.

src Directory
The src directory contains all the source files for your project. When your project is first created, it will contain two files, R.java and .java (in this example, HelloWorldText.java), described next.

NOTE
.java is always named according to your Activity name.

R.java File The file R.java is an auto-generated file that is added to your application by the Android plugin. This file contains pointers into the drawable, layout, and values directories (or the items within the directories, as is the case with strings and icons). You should never have to modify this file directly. You will be referencing R.java in most of your applications. The code that was auto-generated for the HelloWorldText application follows:

Chapter 5:

Application: Hello World!

65

/* AUTO-GENERATED FILE. DO NOT MODIFY. * * This class was automatically generated by the * aapt tool from the resource data it found. It * should not be modified by hand. */ package testPackage.HelloWorldText; public final class R { public static final class attr { } public static final class drawable { public static final int icon=0x7f020000; } public static final class layout { public static final int main=0x7f030000; } public static final class string { public static final int app_name=0x7f040000; } }

NOTE
The comment section of the R.java file provides an explanation of the origin of the file. It states that the file was created by the aapt tool. In Chapter 6, when you create a command-line–only version of the Hello World! application, you will use command-line tools to create all of the auto-generated files.

.java File The file in the src directory that you will spend the most time with is .java (HelloWorldText.java in this example), which is created by the Android plugin and named to match the Activity name that you specified in the New Android Project wizard. Unlike most of the files you have examined in this section, this file is completely editable; in fact, it will do very little for you if you do not modify it with your code. After briefly looking at what is in your HelloWorldText.java file as it is created by the Android plugin, you will then edit the file to create your first Android Activity. package android_programmers_guide.HelloWorldText; import android.app.Activity; import android.os.Bundle;

66

Android: A Programmer’s Guide

public class HelloWorldText extends Activity { /** Called when the activity is first created. */ @Override public void onCreate(Bundle icicle) { super.onCreate(icicle); setContentView(R.layout.main); } }

The three lines at the top of the file are the standard preprocessor directives—that is, as in most programming languages, statements that are directives to the compiler to run before the application process. In this case, you have the definition and inclusion of your package android_programmers_guide.HelloWorldText. The next two lines import specific packages from the Android SDK via android.jar: import android.app.Activity;

and import android.os.Bundle;

These lines tell the project to include all the code from the imported packages before all the code in your application. These two lines are critical for your base Android application and should not be removed.

TIP
If you do not see the android.os.Bundle import statement in your project, expand the tree within your development window. Eclipse rolls up all the import statements under the first one, so you must expand the tree to see the rest of them.

Focusing now on your class HelloWorldText, you can see that it extends the Activity class. Activity is imported from the previous lines. All applications derive the Activity class, and this derivation is required for running an application on Android. For something to run and be displayed on the screen, it must be derived from Activity. The HelloWorldText class holds the code needed to create, display, and run your application. Right now there is only one method in your HelloWorldText class that is defined with code in it, onCreate( ). The onCreate( ) method takes in icicle as a bundle. That is, all of the current state information is bundled as an icicle object and held in memory. You will not be directly handling icicle in this application, but you need to be aware of its presence and purpose.

Chapter 5:

Application: Hello World!

67

The next line in the file is the one that really does some perceptible action: setContentView(R.layout.main); The method setContentView( ) sets the Activity’s content to the specified resource. In this case, we are using the main.xml file from the layout directory via the pointer in the R.java file. The main.xml file, right now, contains nothing more than the size of the HelloWorldText screen and a TextView. The TextView is derived from View and is used to display text in an Android environment. Reviewing the contents of main.xml, you can see that it contains the following line: android:text="Hello World, HelloWorldText"

Considering that the setContentView( ) method is being told to set main.xml as the current View, and main.xml contains a TextView that says “Hello World, HelloWorldText,” it may be safe to assume that compiling and running HelloWorldText now will give you your Hello World! application. To test this, run your unaltered HelloWorldText application. Choose Run | Run to open the Run As dialog box, select Android Application, and click OK.

68

Android: A Programmer’s Guide

The new project you just established contains the code to create a Hello World! application on its own. However, that is not very engaging, nor does it teach you very much about programming an Android application. You need to dissect the project and see exactly how the project displayed the “Hello World!” message. What happened when you created the new Android project is that the Android plugin modified main.xml. This is a perfect example of one way to modify the UI in Android. The following lines of code are added to main.xml by the Android SDK when the project is created:

While I have discussed the existence of this TextView in the xml, I have not yet discussed why it works without any corresponding code. I mentioned earlier in this book that there are two ways to design a UI for Android: through the code, and through the main.xml file. The preceding code sample creates a TextView in xml and sets the text to “Hello World, HelloWorldText.” Edit this line of the main.xml file to read as follows: android:text="This is the text of an Android TextView!"

Rerun the project, and your results should appear as they do in this illustration. Take some time and experiment with the xml TextView. Then you can move on to another way of creating a Hello World! application.

Chapter 5:

Application: Hello World!

69

Hello World! Again
In this section, you will create another Hello World! application for Android. However, this time you will program the UI in code rather than by using the xml file—and you will actually do most of the work. The first step here is to remove the TextView code that is in main.xml. The following section of code represents the TextView. Removing it essentially makes your application an empty shell.

After you have removed the TextView code, your main.xml file should look like this:

Now that you have a clean main.xml file, and thus a clean application shell, you can begin to add the code that will display “Hello World!” on the screen. Start by opening the HelloWorldText.java file and removing the following line: setContentView(R.layout.main); NOTE
You still need to set a ContentView for your new application; however, you are going to implement it slightly differently from how it is implemented here, so it is best to just remove the entire statement for now.

This line uses setContentView( ) to draw the main.xml file to the screen. Since you will not be using main.xml to define your TextView, you will not be setting it to your view. Instead, you will be building the TextView in code.

70

Android: A Programmer’s Guide

Your next step is to import the package TextView from android.widget. This will give you access to the TextView and let you create your own instance of it. Place this code near the top of your current HelloWorldText.java file, where the existing import statements are import android.widget.TextView;

Now, create an instance of TextView. By creating the TextView instance, you can use it to display text to the screen without directly modifying main.xml. Place the following code after the onCreate( ) statement is fired:
TextView HelloWorldTextView = new TextView(this);

NOTE
TextView takes a handle to the current context as an argument. Pass this to the TextView to associate it with the current context. If you follow the hierarchy through the SDK, HelloWorldText extends Activity, which extends ApplicationContext, which in turn extends Context. This is how you can pass this to your TextView.

The preceding line creates an instance of TextView named HelloWorldTextView and then instantiates HelloWorldTextView, by setting it to a new TextView. The new TextView is passed the context of this to be fully instantiated. Now that the TextView is defined, you can add your text to it. The following line of code assigns the text “Hello World!” to the TextView:
HelloWorldTextView.setText("Hello World!");

This line lets you set the text of your TextView. setText( ) lets you assign a string to the TextView. Your TextView has been created and now contains the message that you want to display. However, simply passing “Hello World!” to the TextView does not display anything to the screen. As discussed previously, you need to set the ContentView to

Chapter 5:

Application: Hello World!

71

display something to the screen. You have to use the following code to set TextView to the context and display it to the screen: setContentView(HelloWorldTextView); Examining this line, you can see that you pass to setContentView your TextView. The preceding three lines of code are what it takes to make your Hello World! application. You created a TextView, assigned your text to it, and set it to the screen. All things considered, this is not very complicated at all. The full contents of your HelloWorldText.java file should look like the following: package android_programmers_guide.HelloWorldText; import android.app.Activity; import android.os.Bundle; import android.widget.TextView; public class HelloWorldText extends Activity { /** Called when the activity is first created. */ @Override public void onCreate(Bundle icicle) { super.onCreate(icicle); /**Hello World JFD */ /**BEGIN */ /**Create TextView */ TextView HelloWorldTextView = new TextView(this); /**Set text to Hello World */ HelloWorldTextView.setText("Hello World!"); /**Set ContentView to TextView */ setContentView(HelloWorldTextView); /**END */ } }

Now compile and run your new Hello World! application in the Android Emulator. Choose Run | Run or press CTRL-F11 to launch the application in the Android

72

Android: A Programmer’s Guide

Emulator. The following illustration depicts the results of your Hello World! application.

You have just created your first full Android Activity. This small project demonstrated a fairly common execution of a Hello World! application. You set a TextView to the Activity’s ContentView and displayed the “Hello World!” message to a cell phone screen in the Android Emulator. The following section looks at a slightly different way of implementing Hello World!, using an image.

Hello World! Using an Image
In this section, you are going to use the Hello World! application to get more familiar with a relatively common practice in programming: displaying images. Modern computer displays would be exceedingly uninteresting without a graphical display. These graphical displays center on the ability to send images to the screen.

Chapter 5:

Application: Hello World!

73

As late as five years ago, displaying images was a fairly difficult thing to do on a cell phone. Working with images is just one of those things that we, as modern PC users, take for granted. We look at windows of all types everyday without even considering that they are really images sent to a screen. This version of the Hello World! application will display an image to the screen that says “Hello World!” For this application, use the New Android Project wizard to create a new project and name it HelloWorldImage, as shown in the following illustration.

With the application project created, navigate to and remove the TextView code from main.xml so that you have a clean project. If you do not remove this code, you will end up with a text-based Hello World! program again.

74

Android: A Programmer’s Guide

Before you begin writing any code, you need an image to display. Create a small image in the graphics program of your choice. For ease of use, I chose Microsoft Paint, but any program should be able to give you the desired image. The image I am using is shown here:

Name your image helloworld.png and save it to the %workspace%/HelloWorldImage/ res/drawable directory.

CAUTION
Be careful not to mix upper- and lowercase letters in your image names. Your images should be named using lowercase letters only. If you mix in some uppercase letters, you will get an error message from Eclipse when you try to use the file.

After you copy the image to the correct directory, refresh the project. The helloworld.png image should now appear in your project view, in the drawable directory, as shown in the following illustration.

Chapter 5:

Application: Hello World!

75

Open R.java and take a look at its code. Eclipse should have added a pointer to helloworld.png. Your R.java file should look similar to this:
/* AUTO-GENERATED FILE. DO NOT MODIFY. * * This class was automatically generated by the * aapt tool from the resource data it found. It * should not be modified by hand. */ package android_programmers_guide.HelloWorldImage; public final class R { public static final class attr { } public static final class drawable { public static final int helloworld=0x7f020000; public static final int icon=0x7f020001; } public static final class layout { public static final int main=0x7f030000; } public static final class string { public static final int app_name=0x7f040000; } }

With a clean application shell as your starting point, and an available handle to the image you want to display, you can begin to add your code. You are going to look at this application from two perspectives: that of the XML-based UI and that of the code-based UI.

Hello World! Code-Based UI
Assuming you were able to follow along with and understand the HelloWorldText solution, this version of Hello World! will seem very familiar. To begin, you need to import the package for displaying images. Whereas text is displayed using a TextView, images are displayed using ImageView. Therefore, you must import the ImageView package. Like TextView, ImageView is contained in android.widgets: import android.widgets.ImageView;

76

Android: A Programmer’s Guide

NOTE
Both TextView and ImageView are derived from View. This makes both of them very similar in structure and easy to implement.

With the package imported, you can create your ImageView and display it to the screen. Instantiating ImageView is the same as instantiating TextView; create an instance of ImageView and pass it the current context using this:
ImageView HelloWorldImageView = new ImageView(this);

The next line is where a difference between ImageView and TextView can be seen. This step involves setting your view to something that you want to display. In the TextView example, you used setText( ) to set the text of the TextView to “Hello World!” While both TextView and ImageView are derived from View, they are still different and therefore require some different methods. Obviously, you would not want to use setText( ) for your ImageView. You need to use setImageResource( ) to set the image in your ImageView. As shown next, pass into setImageResource( ) the handle to helloworld.png from R.java (the syntax for the handle is R.drawable.helloworld):
HelloWorldImageView.setImageResource(R.drawable.helloworld);

Finally, to send the image to the screen, you must set the ContentView. Just as you did with the TextView, you pass to the ContentView your ImageView. The job of the ContentView is then to set the object that it is passed to the screen. setContentView(HelloWorldImageView); Your final HelloWorldImage.java file should look like this: package android_programmers_guide.HelloWorldImage; import android.app.Activity; import android.os.Bundle; import android.widget.ImageView; public class HelloWorldImage extends Activity { /** Called when the activity is first created. */

Chapter 5:

Application: Hello World!

77

@Override public void onCreate(Bundle icicle) { super.onCreate(icicle); /**Hello World Image JFD*/ /**BEGIN */ /**Create the ImageView */ ImageView HelloWorldImageView = new ImageView(this); /**Set the ImageView to helloworld.png */ HelloWorldImageView.setImageResource(R.drawable.helloworld); /**Set the ContentView to the ImageView */ setContentView(HelloWorldImageView); /**END */ } }

Compile HelloWorldImage and run it in the Android Emulator. Your application should look similar to that in the following illustration.

78

Android: A Programmer’s Guide

In the next section, you will again display helloworld.png, but this time using XML rather than code.

Hello World! XML-Based UI
This section gives you a very good comparison by which to judge the processes of displaying images using the XML-based UI and the code-based UI. As you are going to see, the process of sending images to the screen using main.xml requires roughly the same amount of code as using the code-based UI. However, the syntax differs between the two processes. Using the same project as you did for the last example, remove the TextView code from the HelloWorldImage.java file. The clean file should look like this: package android_programmers_guide.HelloWorldImage; import android.app.Activity; import android.os.Bundle; public class HelloWorldImage extends Activity { /** Called when the activity is first created. */ @Override public void onCreate(Bundle icicle) { super.onCreate(icicle); } }

Now that you have a clean slate to start with, move over to main.xml. You need to add in a definition for an ImageView. Start off by adding the empty ImageView tag to your main.xml file:

You need to edit four attributes of the ImageView: android:id, android:layout_width, android:layout_height, and android:src. You are going to place these attributes in the tag, where they will govern how the tag is displayed to the screen.

Chapter 5:

Application: Hello World!

79

The android:id attribute is set to the identifier for the ImageView. The android:id attribute can be used to refer to the ImageView in your code. Use the @+id/ syntax to assign to the ImageView an identity that can be retrieved later using R.layout.imageview: android:id="@+id/imageview" This line inserts an auto-generated ID, @+id, into the R.java file under the name imageview. The next two attributes that you must define are android:layout_width and android:layout_ height. These attributes govern how the image will fill the screen. There are two options you are going to select from when assigning values to these attributes. The fill_parent value fills the screen with the image while keeping it in perspective. The wrap_content value keeps the image its defined size, possibly losing some of the image definition in the process. For this example, use wrap_content: android:layout_width="wrap_content" android:layout_height="wrap_content"

The final attribute you need to assign is arguably the most important: android:src. This attribute points to the image that you want to display to the view. For this example, point the attribute to the drawable/helloworld image: android:src="@drawable/helloworld" Your full ImageView tag should look like this:

Finally, before the image will display to the view, you must pass main.xml to setContentView in HelloWorldImage.java: setContentView(R.layout.main); 80

Android: A Programmer’s Guide

Compile and run HelloWorldImage. The results should look like the following illustration.

Before closing out this chapter, try one more thing. Go back to main.xml and change the layouts from wrap_content to fill_parent. When you are finished, your main.xml file should look like this:

Chapter 5:

Application: Hello World!

81

Run the application again to see the difference between wrap_content and fill_parent. Your new application should look like the following illustration when it is run.

Try This

Use TextView and ImageView

Use some of the skills and techniques that you learned in this chapter to create a new Hello World! application. Create an application that uses both the TextView and the ImageView to put an image on the screen with a text caption. This is slightly more difficult than using just one View on an Activity. Play with the Views and see what you can create.

The next chapter takes one more look at Hello World! applications, from the perspective of command-line programming.

82

Android: A Programmer’s Guide

Ask the Expert
Q: A: Q: A:
Does Android have a label or LabelView like most other APIs? No. All text displays are facilitated through the TextView. You can, as some people have done, create a custom View that functions like a label and name it LabelView, but there is no packaged Android LabelView. Is there an advantage to using .java rather than main.xml to create Views? While there is no documented speed or processor savings in using one over the other, there is one key advantage: By using main.xml, you have a number of Views predefined for your Activity. Then, in your code, you can jump from View to View as needed without having to manually create them in code.

Chapter

6

Using the Command-Line Tools and the Android Emulator

Copyright © 2008 by The McGraw-Hill Companies. Click here for terms of use.

84

Android: A Programmer’s Guide

Key Skills & Concepts
● ● ● ●

Using the Android SDK command-line tools Creating a command environment Navigating the Android server with a shell Using the Android SDK in Linux

S

o far this book has covered some very broad subjects to get you up and running on the Android platform. At this point, you should be fairly comfortable using Eclipse to create and run a small Android application. You created a new project, edited the main.xml and .java files, and recompiled the R.java file. These are the basic skills that you need to create Android applications. In this chapter, you are going to expand and round out those skills by experimenting with command-line application development. Android development does not have to be limited to the confines of the Eclipse IDE. The Android SDK offers a host of command-line tools that can help you develop full applications without the need of a graphical IDE. You will use these command-line tools to create, compile, and run a Hello World! application, first in Windows and then in Linux.

Creating a Shell Activity Using the Windows CLI
The Android SDK comes with multiple tools to help you create and compile Android applications. These tools are in place to help users who do not wish to, or do not have a system capable of supporting, work within a GUI IDE. However, if you are doing all of your Android development work within Eclipse, you still should be aware of the Android SDK command-line tools and their functionality. When you run Android-related functions, such as creating an Android project or running an application in the Android Emulator, you are actually calling connections to the Android command-line tools. These Android command-line tools, whether run from a command-line interface or from a GUI IDE, are the real core to the functionality of the Android SDK.

Chapter 6: Using the Command-Line Tools and the Android Emulator

85

In the following section, I demonstrate the functionality of one Android tool. The ActivityCreator.bat is a powerful tool that is used to establish shells of Activities that are ready for you to program.

Running the ActivityCreator.bat
The ActivityCreator.bat should be located in the ../tools/ directory of the Android SDK. Most of the forward-facing command-line tools are located in the root of the tools directory. “Forward-facing” tools are tools that in turn call other tools located deeper in the ../tools/ directory. ActivityCreator.bat is an example of a tool from the root of the tools directory that actually calls another tool when it is run. Using vi, Notepad, or any text editor, open ActivityCreator.bat; it should contain the following lines of code:

NOTE
ActivityCreator.bat is specific to the Microsoft Windows version of the Android SDK. In a later section of this chapter you will also learn about the ActivityCreator.py. This is the Linux version of the ActivityCreator.
@echo off rem Copyright (C) 2007 Google Inc. rem rem Licensed under the Apache License, Version 2.0 (the "License"); rem you may not use this file except in compliance with the License. rem You may obtain a copy of the License at rem rem http://www.apache.org/licenses/LICENSE-2.0 rem rem Unless required by applicable law or agreed to in writing, software rem distributed under the License is distributed on an "AS IS" BASIS, rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. rem See the License for the specific language governing permissions and rem limitations under the License. rem don't modify the caller's environment setlocal "%~dp0\lib\activityCreator\activityCreator.exe" %*

Navigating through all of the rem statements (batch file comment statements), you will see that there is one line of practical code at the bottom of the file. ActivityCreator.bat is used to call ActivityCreator.exe in the ../tools/lib/activityCreator/ directory. The ActivityCreator.bat is an example of a tool that is really just a front end of other tools in the SDK.

86

Android: A Programmer’s Guide

So, what does ActivityCreator.bat (or ActivityCreator.exe) do? ActivityCreator is used to establish your development environment to the point where it will create the initial files needed to begin developing your application. This directory structure is the same structure discussed in Chapter 5. ActivityCreator.bat creates R.java, AndroidManifest.xml, and all the supporting files needed to begin your application. Let’s now go to a command-line environment and explore the ActivityCreator. From your Start menu, click Run, type CMD or COMMAND in the Run dialog box, and click OK. Executing this command launches the command window shown next. This window is the equivalent of the older DOS operating environments.

With the command window open, enter ActivityCreator at the > prompt.

TIP
The Microsoft command-prompt interface is not case sensitive, by default. If you are using a different environment that is case sensitive, such as Linux/Unix, the screenshots in this chapter may not show the proper case for your environment.

Running the command ActivityCreator, which actually runs ActivityCreator.bat, produces the following output:
Activity Creator Script Usage: activityCreator [--out outdir] [--ide intellij] yourpackagename.ActivityName

Creates the structure of a minimal Android application. The following will be created: - AndroidManifest.xml: The application manifest file. - build.xml: An Ant script to build/package the application. - res : The resource directory. - src : The source directory.

Chapter 6: Using the Command-Line Tools and the Android Emulator

87

- src/your/package/name/ActivityName.java the Activity java class. packageName is a fully qualified java Package in the format .... (with at least two components). - bin : The output folder for the build script. Options: --out : specifies where to create the files/folders. --ide intellij: creates project files for IntelliJ

This output simply indicates that you need to provide more information to run ActivityCreator. More specifically, you need to pass the command a directory location within which to build your shell application.

NOTE
The output from the ActivityCreator command gives you a lot more information than just the fact that you did not provide enough information. It gives the complete list of the files created when using the tool. This list should look similar to that covered in Chapter 5, although build.xml is not directly exposed to Eclipse users.

Go back to the command window and run ActivityCreator with the following option (ActivityCreator also accepts path parameters with Unix-style forward slashes, if you are used to programming in a Unix/Linux environment):
--out c:\AndroidHelloWorld\android_programmers_guide.HelloWorldCommandLine

The --out option tells ActivityCreator that you want it to output something. This command option takes two parameters, and . The first part of the preceding line tells ActivityCreator to build the shell application in the nonexistent folder c:\AndroidHelloWorld.

TIP
If you specify a folder or directory that does not exist, ActivityCreator will create it for you during its process.

The second parameter of the --out option is the package name and the activity name. Following the convention established in the previous chapter, this example uses android_programmers_guide as the package name and HelloWorldCommandLine as the activity name for this project.

88

Android: A Programmer’s Guide

NOTE
The parameters needed to successfully run ActivityCreator and set up your initial environment are the same as those required by the New Android Project wizard.

Run ActivityCreator with this new command-line option and its parameter. You should see the following output from the tool:

The following section covers the files created by ActivityCreator, because they do vary slightly from those created by Eclipse.

The Project Structure
ActivityCreator created a number of directories and files for you to use and begin your development. Navigate to the c:\AndroidHelloWorld\ directory to explore its structure. ActivityCreator created the structure shown in the following illustration.

Chapter 6: Using the Command-Line Tools and the Android Emulator

89

Because you are working outside of the Eclipse environment, you have a slightly different environment. When you are working within an IDE such as Eclipse, certain functions are performed behind the scenes for you. Given that you are working without any IDE help, ActivityCreator creates a file that outlines what the complier needs to do to create your project. ActivityCreator, when run manually, creates the build.xml file for your project. This file is not created when you use Eclipse to begin an Android project. It contains an instruction set that explains how to turn your .java files into a functional Android project.

90

Android: A Programmer’s Guide

The build.xml file tells the compiler what it needs to do to create your application. The compiler in this example is Apache ANT, a Java-based tool that uses build files as scripts to compile projects. You need to download ANT to compile your command-line project. Download ANT from http://ant.apache.org/bindownload.cgi. Once you have ANT downloaded and installed, you must add it to the PATH statement. From within a Windows environment, simply right-click Computer and select Properties to change the PATH statement. The build.xml file is created specifically for ANT to use in compiling your Android application. It should be located in the root of your project, as shown in the previous illustration. Open build.xml with your text editor and take a look at what is inside. The first section of build.xml contains code that is editable by the user. This section is set off from the rest of the file because the remaining portions of the file should not be modified.

The first section of build.xml contains values for the following properties:
● ● ● ● ●

Project name Android SDK location Android tools location Android framework location Output location

Chapter 6: Using the Command-Line Tools and the Android Emulator

91

If you need to change any of these parameters for your project, you can do so within this file. However, immediately following these parameters in build.xml, you should see a warning informing you that you should not edit any remaining values:

Following this warning in build.xml is a list of parameters and values that are critical to the proper creation of your project. This list includes compiler options, input directories, and tool locations. Take a look at the following output of the core processing information of build.xml:

NOTE
While Android advises against changing the following parameters, if you are very familiar with how ANT works, you can modify these options to suit a particular need you may have.

92

Android: A Programmer’s Guide

Generating R.java...

Chapter 6: Using the Command-Line Tools and the Android Emulator

93

Packaging resources and assets... Packaging resources...

94

Android: A Programmer’s Guide

Packaging java... Packaging dex... Sending package to default emulator...

Now that you have a good understanding of how build.xml is used in the manual, command-line creation of Android projects, you can begin to edit your project files and

Chapter 6: Using the Command-Line Tools and the Android Emulator

95

create an Android Activity. The first file you need to look at is main.xml. Using Windows Explorer, navigate to main.xml at AndroidHelloWorld\res\layout.

Creating the Hello World! Activity in the Windows CLI
In this section you will use the Windows command-line interface to edit the project files. The project files were created in the previous sections by the ActivityCreator.bat. You will edit these files and add code to them, without using Eclipse.

Editing the Project Files
Open main.xml in either an XML editor or (if you do not have a specific XML editor) Notepad. This will let you edit the file and remove the definition that is within it. Save main.xml as shown in the next illustration.

The result of saving main.xml is an empty shell. This gives you a platform on which to edit your .java file. The .java file is in a folder that is several directories deep, AndroidHelloWorld\src\android\programmers\guide. To create your Hello World! application, add the following lines to create, set, and use a TextView:
/**Hello World JFD */ /**BEGIN */ /**Create TextView */ TextView HelloWorldTextView = new TextView(this); /**Set text to Hello World */ HelloWorldTextView.setText("Hello World!"); /**Set ContentView to TextView */ setContentView(HelloWorldTextView); /**END */

96

Android: A Programmer’s Guide

Do not forget to add the TextView package to the beginning of the file: import android.widget.TextView;

The finished HelloWorldCommandLine.java file should look like that in the following illustration.

Your project files should now be set. You can now compile your program and run it in the Android Emulator.

Adding the JAVA_HOME Variable
Before you try compiling your project, you must add another environment variable to your PC—JAVA_HOME—that points to your JDK. Even if this path is in your PATH statement, you still need to create a new variable named JAVA_HOME.

NOTE
The JAVA_HOME variable is needed only if you are working in the command-line environment. If you are exclusively using Eclipse, you do not need to add it.

Chapter 6: Using the Command-Line Tools and the Android Emulator

97

1. Right-click My Computer and select Properties. 2. Select the Advanced tab on the System Properties window and click the Environment

Variables button. This will open an Environment Variables window.
3. Click the New button to add a new variable named JAVA_HOME. The value for the

variable should be the full path to your Java SDK, as seen in the following illustration.

Compiling and Installing the Application
It is time for the real test. You can now compile your command-line project. To compile your project, use ANT. Once the project is compiled, you will install it on your Emulator.

98

Android: A Programmer’s Guide

Compiling Your Project with ANT
After you have your JAVA_HOME environment variable set and have ANT in your PATH statement, you should be able to navigate the directory containing your build.xml file and simply run the command ant. Open a Windows command prompt to your project directory and run ant, as follows:

The result of running ant will be an .apk file that you will install directly onto your phone (Emulator). However, whereas Eclipse installs the .apk file for you directly on the Emulator, you need to install it manually. You use the Android Debug Bridge (adb) Android tool to install the application, as described in the next section.

What to Do if Running ant Produces an Error If ANT produces an error when you run it, fear not. Because Android is still in its initial release stages as of the writing of this book, several items may need to be tweaked. Small changes here and there can always be expected when you are working in a new technology. When I first tried to run ant and compile my project, I received an error like that shown in the following illustration.

Chapter 6: Using the Command-Line Tools and the Android Emulator

99

Some research on the issue at the Google Android developer’s forum turned up an interesting solution: a rewrite of build.xml that tweaked some of the commands offered to ANT. What follows is the modified build.xml file, in which the key changes have been bolded. Compare this file with the original and you will see that it differs quite noticeably.

100

Android: A Programmer’s Guide

Generating R.java...

Chapter 6: Using the Command-Line Tools and the Android Emulator

101

Packaging dex... Packaging resources and assets...

102

Android: A Programmer’s Guide

Packaging resources... Packaging java... Packaging dex...

Chapter 6: Using the Command-Line Tools and the Android Emulator

103

After modifying build.xml, you can then try to run ant again.

Installing Your Application with adb
The first step is to start your Emulator. In the Android /tools folder, find the emulator.exe file and execute it. This starts your Android server. That is, starting the Emulator also starts a virtual cell phone on your PC, as shown next. You can then use different tools to interact with the server, to do such things as install applications and call a shell environment.

To install your command-line application on your Android server, you need to use adb. adb is your connection to the Android server, which is started with your Emulator. adb contains many useful functions that allow you to interact with your Android server; one of these enables you to install applications. Table 6-1 lists and describes the commands that adb accepts.

104

Android: A Programmer’s Guide

Command install pull push shell forward start-server kill-server ppp devices help version

Description
Installs applications to the server Pulls a remote file off the server Pushes a local file to the server Opens a shell environment on the sever Forwards traffic from one port to another (to and from the server) Starts the server Stops the server Uses a PPP connection over USB Lists the available emulators Lists the adb commands Displays the adb version

Table 6-1 adb Commands

To copy your application to the server, open a Windows command prompt and navigate to the directory of your build.xml file. The command syntax for adb is as follows: adb install

If the application installs to the phone properly, you will just get the package size as feedback in return from the command, as shown next.

Chapter 6: Using the Command-Line Tools and the Android Emulator

105

Switching over to your running Android Emulator, you should now see the application installed on your phone.

What to Do if Running the Application Produces an Error The first time I ran this application, after using the new build.xml file, I received an error on the Android Emulator. Shown in the following illustration, the error pointed to a missing class.

NOTE
While you may or may not encounter this exact error, depending on what release of the Android SDK is available when this book is published, you should follow the troubleshooting steps presented here, because they will help you in later projects.

This error seems to point to the fact that my classes, somehow, are missing from the HelloWorldCommandLine.apk file. I can easily remedy this issue without using any of the Android SDK command-line tools.

106

Android: A Programmer’s Guide

As it turns out, .apk files are just .zip files. That is, you can easily open them with a .zip file decompressor and view the files within them. The following illustration shows what the inside of HelloWorldCommandLine.apk looks like using the WinRAR decompressor.

What is missing from the file is classes.dex. This is the compiled Dalvik executable of my classes. Navigating to the bin directory of my Android project, I can see that ANT did successfully compile and create the classes.dex file. The file was just left out of the HelloWorldCommandLine.apk. With the .apk file open in WinRAR, I can drag-and-drop classes.dex into HelloWorldCommandLine.apk. After classes.dex has been added to my .apk file, I can save and close the file.

Uninstalling a Prior Version of an Activity
Before you add the file to your running Android server, you are going to uninstall the prior version of HelloWorldCommandLine. Uninstalling a prior version of an application before you install another is not required. However, to get a good look at how to interact with the Android server, go ahead and uninstall your previous version before proceeding. With your Android Emulator open, return to your command prompt environment and run the command adb shell, which opens the shell environment of the Android server. If you are successful, your command prompt should turn from a > to a #. You now have an open shell into your Android server. There are a multitude of functions you can run from this point, but for now focus on one: removing the old HelloWorldCommandLine.apk file.

Chapter 6: Using the Command-Line Tools and the Android Emulator

107

TIP
Keep in mind that Android is an operating environment. The commands that you can use within the shell are standard POSIX commands.

On the Android server, user-installed applications are kept in the /data/app directory. Using cd, navigate to the app directory, as shown in the following illustration.

Run the command ls to list all the files in this directory. You should see a file named HelloWorldCommandLine.apk. This file represents the installation of your Activity. Now that you have located the application on the Android server, you can remove it. Use the command syntax rm HelloWorldCommandLine.apk to remove the application. The following illustration shows that the rm command, if run correctly, gives no feedback. A subsequent use of ls shows that the file has been removed.

CAUTION
Because you are technically logged into a Linux server via a shell, all the commands you run in the shell are case sensitive.

108

Android: A Programmer’s Guide

With the application removed, type exit to leave the shell and return to your command prompt.

Reinstalling and Launching the Application
You can now reinstall the application using adb install: adb install HelloWorldCommandLine.apk

Once the application is installed back to the server, switch to your Emulator. Launch the application from your Emulator. It should work perfectly, as shown in the following illustration.

Now that we have covered the process for creating and editing files on Windows, let’s take a look at it on Linux. Even if you are a die-hard Windows user, you may want to pay attention to the following section. I have found that there are definite advantages to programming with open source tools.

Chapter 6: Using the Command-Line Tools and the Android Emulator

109

Hello World! on Linux
Many programmers, especially those who are interested in open source software, use Linux as their platform of choice. Google and the Open Handset Alliance have made an Android SDK just for these programmers. The SDK is actually the same SDK (because Java is portable), but the tools are created specifically to run on Linux. When I started writing this book, I was using an older version of Red Hat Linux (Red Hat 9) as my Linux platform. I downloaded and installed Eclipse and the Android SDK. However, it quickly became apparent that there are limitations to the version of Linux that you can safely run Android on. As a minimum, you have to have a version of Linux that supports libstdc++.so.6. The Android documentation lists Ubuntu Dapper Drake as a tested version of Linux. If you have not yet made a decision as to which version you want to use, you can feel safe with that version. Unfortunately, with the hardware that I am running, I had a problem installing the latest version of Ubuntu. So I decided to move away from what was recommended and try something new. When I made the decision to drop Red Hat for another distribution of Linux, I decided to try Fedora 8. The remainder of this book uses Linux examples from Fedora 8; however, they should work without an issue on the distribution of your choice.

CAUTION
If you choose to use Fedora 8, it comes packaged with a custom version of Eclipse called Fedora Eclipse. If you attempt to install the Android plugin (using the steps outlined earlier in this book) for Fedora Linux, it will throw an error stating that the plugin org.eclipse.wst.sse.u is required. You can address this in either of two ways: download the latest version of Eclipse for Linux, or use Fedora’s automatic update program, which will download an update to Fedora Eclipse that will bring it up to date with the latest version of Eclipse. You can then use this version of Eclipse with the Android SDK.

Configuring the PATH Statement
The first step is to configure your PATH statement. The path is the list of directories within which the operating system will look when trying to find a command that is being run. To see what your path is currently configured to, run the following from a terminal: echo $PATH

110

Android: A Programmer’s Guide

You will get back something that resembles the PATH statement in the following illustration.

Use the export command to add Android to the PATH statement (see the next illustration): export PATH=$PATH:

Editing the PATH statement like this in Linux will change the PATH statement only for the current terminal session. To make your PATH statement change permanent, you must edit .bash_profile. Use vi to edit .bash_profile, as shown in the following illustration.

With .bash_profile open in the vi editor, it should look something like the next illustration. As you can see the PATH statement is clearly visible. Use the command

Chapter 6: Using the Command-Line Tools and the Android Emulator

111

:i to put vi in insert mode, and then add Android to the PATH statement. Then press the ESC key, use the command :w to write the file, and then use :q to quit.

The Linux version of the Android SDK comes with a Python script, activityCreator.py, that is used to create your initial projects. When running the Python script, an output directory is created for your project. However, I like to create this directory manually to make sure it is created where I need it to be. Use mkdir to create a directory for your project (see the following illustration).

112

Android: A Programmer’s Guide

After you create the project directory, you can run the activityCreator.py Python script. The syntax for the script is very close to that of the Windows .bat file: activityCreator.py --out package.activityName

Use the activityCreator.py script to set up your project. Take a look at the following illustration to see the output from the activityCreator.py script.

TIP
Notice that the activityCreator.py command is prefixed by sudo. The sudo command is used to emulate the permissions of another user (in this case, root) if you do not have sufficient permissions to run the requested command. On my installation of Fedora, my user account does not have the rights to interact with certain directories the way root does.

Chapter 6: Using the Command-Line Tools and the Android Emulator

113

With the project created, edit HelloWorldLinux.java to add the TextView. You can choose to edit the .java file a number of ways in Linux. You can use vi once again, or you can use a standard text editor as shown in the following illustration.

Finally, remove the defined TextView from main.xml. These two small changes are all you need to now compile your Linux version of the Hello World! application. To compile the application, use ANT (which is what was used in the Windows environment earlier in the chapter). Apache ANT should be preinstalled in your Linux distribution, especially if you are using Fedora 8. If you are not using Fedora 8, you need to download, install, and set the path for the Linux version of Apache ANT.

114

Android: A Programmer’s Guide

When you run ant, you should see an output like that shown in the following illustration.

Finally, you need to start up your Android Emulator and install your application. With the Emulator started and running, execute the following command: adb install HelloWorldLinux.apk

This installs the application to the Linux Android server. If the command runs successfully, you should be able to run your Activity in the Android Emulator. The next chapter explores how to use the Android SDK to react to phone events.

Chapter 6: Using the Command-Line Tools and the Android Emulator

115

Try This

Create an Image-Based Hello World! in the CLI

Using the command-line tools covered in this chapter, re-create the image-based Hello World! project from Chapter 5. When you are creating this project, keep the following items in mind:
● ● ● ●

Place the image in the res folder. Check if any tools are needed to create an R.java file with a handle into the image. Compile the project using ANT. Use the command adb install to push the application to your emulator.

Ask the Expert
Q: A:
Is one operating system better than any other when programming for Android? After using several operating systems with Android, I have not noticed any one operating system having a clear and distinct advantage over another. It is really just a matter of personal preference. However, as often happens, you may see more “tools”—of the unofficial sort—be released on the Linux platform. Because both Linux and Android are open source, more open source developers will be apt to create tools for other open source platforms. This symbiosis may even end up benefiting Android more than it benefits Linux. Are there other commands that can be run from within the adb shell environment? Yes. For example, one interesting command is the service command, which can be used to check on the status of a process, such as: service check phone

Q: A:

Assuming the phone is running, you should get back
Service phone: found

Another use of the service command is to place calls. With the Emulator running, type the following command and check the results on the Emulator interface: service call phone 2 s16 "15555551212"

This page intentionally left blank

Chapter

7

Using Intents and the Phone Dialer

Copyright © 2008 by The McGraw-Hill Companies. Click here for terms of use.

118

Android: A Programmer’s Guide

Key Skills & Concepts
● ● ●

Using Intents Creating code that interacts with the phone hardware Learning the difference between dialing and calling

he chapters up to this point have introduced you to the basics of Android programming. You have examined the outline of an Android application and installed your first applications to the Android server. You have learned how to use Views and setContentView( ), as well as how to create a UI in XML. These skills have helped you to create a static application. What you have not done yet is use the application interface to interact with the hardware that the platform was created for—the cell phone. You should not lose sight of the fact that the platform for which Android was created is, in essence, still a cell phone. The underlying hardware for the devices that Android will run on is designed for the purpose of person-to-person communication. If you strip away all the bells and whistles that the Android SDK is capable of adding to the cell phone, it must still be able to send and receive phone calls. For this reason, this chapter focuses on the code that enables you to interact with the phone hardware. By the end of this chapter, you should have the skills needed to interact with some of the basic functions of the phone. You will be able to work with the dialer to send and receive calls. These tools and skills will be your keys to creating useful applications on this flexible platform. You are reading this book because you intend to design applications that run on a cell phone, so it stands to reason that you should learn how Android allows for interaction with the phone hardware—in particular, the process that enables the phone to send and receive calls. When we think of a cell phone, a few basic functions come to mind. The first, and most obvious, of which is the ability to send and receive phone calls. This is inarguably the quintessential function of a cell phone. There are a few peripheral features that make the cell phone easier to use, such as the ability to keep and manage contacts and the ability to store and review missed calls. As you’ll read in this chapter, you can access and manipulate the code for all of these functions.

T

Chapter 7:

Using Intents and the Phone Dialer

119

The first phone function that you will look at in this chapter is the sending of calls. You will create an application, using an Intent, that controls the phone dialer and causes it to place a call to a number. As the chapter progresses, you will expand on this application and add some bells and whistles to it.

NOTE
On the Android platform, there is a difference between the actions of dialing and calling. When you dial a number, you enter the digits into the keypad (or programmatically), but no call is actually placed. That is, dialing does not encompass pressing the Send button. When you call a number, you send a signal from your handset. That is, after you enter the number into the dialer, you press the Send button—either physically or programmatically. You need to know the difference between the two actions to understand the scope of the applications you will create in this section.

What Are Intents?
Before you can begin to interact with the phone dialer, you need to understand the type of code that you will use to do the job. Android uses Intents to do specific jobs within applications. Once you master the use of Intents, a whole new world of application development will be open to you. This section defines what an Intent is and how it is used. An Intent is Android’s method for relaying certain information from one Activity to another. An Intent, in simpler terms, expresses to Android your intent to do something. You can think of an Intent as a message passed between Activities. For example, assume that you have an Activity that needs to open a web browser and display a page on your Android device. Your Activity would send an “intent to open x page in the web browser,” known as a WEB_SEARCH_ACTION Intent, to the Android Intent Resolver. The Intent Resolver parses through a list of Activities and chooses the one that would best match your Intent; in this case, the Web Browser Activity. The Intent Resolver then passes your page to the web browser and starts the Web Browser Activity. Intents are broken up into two main categories:
●

Activity Action Intents Intents used to call Activities outside of your application. Only one Activity can handle the Intent. For example, for a web browser, you need to open the Web Browser Activity to display a page. Broadcast Intents Intents that are sent out for multiple Activities to handle. An example of a Broadcast Intent would be a message sent out by Android about the current battery level. Any Activity can process this Intent and react accordingly—for example, cancel an Activity if the battery level is below a certain point.

●

120

Android: A Programmer’s Guide

Table 7-1 lists and describes the current Activity Action Intents that are available to you. As you’ll notice, in most cases, the name of the Intent does a good job of describing what that Intent does. Activity Action Intent
ADD_SHORTCUT_ACTION ALL_APPS_ACTION ANSWER_ACTION BUG_REPORT_ACTION CALL_ACTION DELETE_ACTION DIAL_ACTION EDIT_ACTION EMERGENCY_DIAL_ACTION FACTORY_TEST_ACTION GET_CONTENT_ACTION INSERT_ACTION MAIN_ACTION PICK_ACTION PICK_ACTIVITY_ACTION RUN_ACTION SEARCH_ACTION SEND_ACTION SENDTO_ACTION SETTINGS_ACTION SYNC_ACTION VIEW_ACTION (DEFAULT_ACTION) WALLPAPER_SETTINGS_ACTION WEB_SEARCH_ACTION

Message
Add a function shortcut to the Android Home Screen List all the applications available on the device Answer an incoming call Open the Bug Reporting Activity Place a call to supplied location Delete the specified data Open the Dial Activity and dial the specified number Provide editable access to the supplied data Dial an emergency number Retrieve factory test settings Select and return specified data Insert an empty item Establish the Activity start point Pick an item and return the selection Pick a given Activity (returns a class) Execute the given data Launch a search on the system Send data without specifying the recipient Send data to the recipient specified Launch System Settings Sync phone data with external source Open a View Show settings for modifying the Android Wallpaper Open Google Search, or another web page if specified

Table 7-1 Activity Action Intents

Chapter 7:

Using Intents and the Phone Dialer

121

NOTE
For the applications in this chapter, you will use two of the Intents listed in Table 7-1: CALL_ACTION and DIAL_ACTION. These Intents give you access to the phone’s dialing and calling capabilities.

Table 7-2 lists and describes the current Broadcast Intents that are available. Refer to this list when you need to establish a receiver for a specific Intent. Broadcast Intent
CALL_FORWARDING_STATE_CHANGED_ACTION CAMERA_BUTTON_ACTION CONFIGURATION_CHANGED_ACTION DATA_ACTIVITY_STATE_CHANGED_ACTION DATA_CONNECTION_STATE_CHANGED_ACTION DATE_CHANGED_ACTION FOTA_CANCEL_ACTION FOTA_INSTALL_ACTION FOTA_READY_ACTION

Message
The phone’s call forwarding state has changed The camera button has been pressed The device’s configuration has changed The device’s data activity state has changed There has been a change in the data connection state The phone’s system date has changed Cancel pending system update downloads An update has been downloaded and must be installed immediately (sent by the system) An update has been downloaded and can be installed—but does not need to be installed immediately (sent by the system) Restart a system update download Begin the download of a system update Sent when a GTALK session has been successfully established Sent when a GTALK session has been disconnected Sent when an SD Memory Card was removed but unsuccessfully unmounted from the system Sent when the media button has been pressed

FOTA_RESTART_ACTION FOTA_UPDATE_ACTION GTALK_SERVICES_CONNECTED_ACTION GTALK_SERVICES_DISCONNECTED_ACTION MEDIA_BAD_REMOVAL_ACTION

MEDIA_BUTTON_ACTION

Table 7-2 Broadcast Intents

122

Android: A Programmer’s Guide

Broadcast Intent
MEDIA_EJECT_ACTION MEDIA_MOUNTED_ACTION MEDIA_REMOVED_ACTION MEDIA_SCANNER_FINISHED_ACTION MEDIA_SHARED_STARTED_ACTION MEDIA_UNMOUNTED_ACTION MESSAGE_WAITING_STATE_CHANGED NETWORK_TICKLE_RECEIVED_ACTION PACKAGE_ADDED_ACTION PACKAGE_CHANGE_ACTION PACKAGE_INSTALL_ACTION PACKAGE_REMOVED_ACTION PHONE_INTERFACE_ADDED_ACTION PHONE_STATE_CHANGED_ACTION PROVIDER_CHANGED_ACTION PROVISIONING_CHECK_ACTION SCREEN_OFF_ACTION SCREEN_ON_ACTION SERVICE_STATE_CHANGED_ACTION SIGNAL_STRENGTH_CHANGED_ACTION

Message
Sent when the eject action has been initiated on an SD Memory Card Sent when an SD Memory Card was successfully mounted to the system Sent when an SD memory card was detected as having been removed Sent when the scanner has finished Sent when the scanner has begun Sent when an SD memory card has been detected but has not been mounted The “message waiting” state on the phone has changed A new device network notification has been received Sent when a new package has been installed on the device Sent when an existing package has been modified A package can be downloaded and installed A package has been removed The device’s phone interface has been created The device’s phone state has changed The device has received a notification from a provider Check for the latest settings from the provisioning service The screen has been shut off (sent by the device) The screen has been turned on (sent by the device) The service state has changed The signal strength has changed

Table 7-2 Broadcast Intents (continued)

Chapter 7:

Using Intents and the Phone Dialer

123

Broadcast Intent
SIM_STATE_CHANGED_ACTION TIME_CHANGED_ACTION TIME_TICK_ACTION TIMEZONE_CHANGED_ACTION UMS_CONNECTED_ACTION UMS_DISCONNECTED_ACTION WALLPAPER_CHANGED_ACTION

Message
The state of the SIM card has changed The device’s time was set The current time has changed The device’s timezone has changed The device has connected via USB The device has been disconnected from its USB host The device’s wallpaper has been changed

Table 7-2 Broadcast Intents (continued)

NOTE
Some of these Broadcast Intents are sent out quite often, such as TIME_TICK_ACTION and SIGNAL_STRENGTH_CHANGED_ACTION. Be careful how you use them. You should try not to receive such broadcasts if at all possible.

The Intent is only one-third of the picture. An Intent is really just that, an intent to do something; an Intent cannot actually do anything by itself. You need Intent Filters and Intent Receivers to listen for, and interpret, the Intents. An Intent Receiver is like the mailbox of an Activity. The Intent Receiver is used to allow an Activity to receive the specified Intent. Using the previous web browser example, the Web Browser Activity is set up to receive web browser Intents. A system like this allows unrelated Activities to ignore Intents that they would not be able to process. It also allows Activities that need the assistance of another Activity to utilize that Activity without needing to know how to call it. With Intents and Intent Receivers, one Activity can send out an Intent and another can receive it. However, there needs to be something that governs the type of information that can be sent between the two Activities. This is where Intent Filters come in. Intent Filters are used by Activities to describe the types of Intents they want to receive. More importantly, they outline the type of data that should be passed with the Intent. Therefore, in our example scenario, we want the web browser to open a web page. The Intent Filter would state that the data passed with the WEB_SEARCH_ACTION Intent should be in the form of a URL. In the next section, you will begin to use Intents to open and utilize the phone’s dialer.

124

Android: A Programmer’s Guide

Using the Dialer
Now that you know what an Intent is, it is time to see one in action. This section shows you how to use the DIAL_ACTION Intent to open the phone dialer. You will pass a telephone number with your Intent. If your application works correctly, you should see displayed in the dialer the number you pass with your Intent. The first step is to create a new project for this Activity (see Chapter 5 for instructions). Name the project AndroidPhoneDialer. The following illustration shows the New Android Project wizard for this project.

With your new application open in Eclipse, the first order of business is to remove the TextView from main.xml that contains that Hello World statement. The main.xml file should look like this after you remove the TextView:

You need to add two new packages to your project to utilize the DIAL_ACTION Intent, as follows. The first package allows you to set up Intents and the second allows you to parse URIs. import android.content.Intent; import android.net.Uri;

NOTE
There are several different Intent Filters on the DIAL_ACTION Intent that you can use. You are using the Filter that lets you pass a phone number as a URI.

The next step is to create your Intent. The syntax for creating an Intent is as follows:
Intent = new Intent(,)

For your application, replace the first parameter, , with DialIntent. To get the value for the second parameter, , refer to the list of Activity Actions in Table 7-1. You’ll find that, to call the dialer, you need to use the DIAL_ACTION Intent. To call the Intent properly, use the format Intent.DIAL_ ACTION. The last parameter, , is the phone number. The DIAL_ACTION Intent takes in data as a URI. Thus, you need to use Uri.parse to parse out your phone number. Using Uri.parse will ensure that the DIAL_ACTION Intent understands the number you are trying to dial. You pass Uri.parse a string that represents the phone number you want to dial, "tel:5551212" in this example. The final call to create an Intent for your project should look like this:
Intent DialIntent = new Intent(Intent.DIAL_ACTION,Uri.parse("tel:5551212"));

TIP
You use the notation tel: to dial a specific phone number. You can also use voicemail: instead of tel: to dial the phone’s voicemail shortcut.

126

Android: A Programmer’s Guide

With the Intent created, you now have to tell Android that you want the dialer to be launched in a new Activity. To do this, you use the setLaunchFlags( ) method of the Intent. You must pass setLaunchFlags( ) the appropriate parameter for launching. The following is a list of the possible launch flags that you can set:

NOTE
In some cases, more than one of the following flags may be set to accomplish the desired outcome.
●

NO_HISTORY_LAUNCH Launches the Activity without recording it in the system’s launch history SINGLE_TOP_LAUNCH Tells the system not to launch the Activity if it is already running NEW_TASK_LAUNCH Launches the Activity MULTIPLE_TASK_LAUNCH Launches the Activity even if it is already running FORWARD_RESULT_LAUNCH Allows the new Activity to receive results that would normally be forwarded to the existing Activity

●

● ● ●

In this case, you want to use Intent.NEW_TASK_LAUNCH, which simply lets you open a new instance of the dialer Activity:
DialIntent.setLaunchFlags(Intent.NEW_TASK_LAUNCH );

The last step to creating your dialer Intent is to actually launch the Activity. (More accurately, you are telling Android that you have an intent to launch the dialer as a New Task. It is ultimately up to Android to launch the Dialer Activity.) To tell Android that you want to start the dialer, you need to use startActivity( ): startActivity(DialIntent); Notice that you pass to startActivity( ) your Intent. The Intent is then passed to Android, and the action is resolved. The full code for AndroidPhoneDialer.java should look like this:

Chapter 7:

Using Intents and the Phone Dialer

127

package android_programmers_guide.AndroidPhoneDialer; import android.app.Activity; import android.content.Intent; import android.os.Bundle; import android.net.Uri; public class AndroidPhoneDialer extends Activity { /** Called when the Activity is first created. */ @Override public void onCreate(Bundle icicle) { super.onCreate(icicle); setContentView(R.layout.main); /** Create our Intent to call the Dialer */ /** Pass the Dialer the number 5551212 */ Intent DialIntent = new Intent(Intent.DIAL_ACTION,Uri.parse("tel:5551212")); /** Use NEW_TASK_LAUNCH to launch the Dialer Activity */ DialIntent.setLaunchFlags(Intent.NEW_TASK_LAUNCH ); /** Finally start the Activity */ startActivity(DialIntent); } }

You should now compile AndroidPhoneDialer and run it on your Emulator. The process for compiling and running applications was covered in previous chapters, so you should be familiar with that process. Once you run your application, the Emulator should launch. After the lengthy boot process, your Activity will launch.

TIP
It is a good idea to keep the Emulator running, even after you are finished with your Activity and have returned to the code window. It is most people’s instinct to close the Emulator window when they have finished testing their Activity. However, I have found that leaving the Emulator open helps with two major issues. The first is the amount of time it takes for the Emulator to start. By leaving the Emulator open, you avoid the lengthy load time. Second, I have noticed that there are times when I make minor changes to an Activity and they are not copied to the Emulator. Leaving the Emulator open seems to alleviate this issue as well. If you continue to have issues in the Emulator, remove the userdata-qemu.img file from your computer. This allows the Emulator to start up with a clean image.

128

Android: A Programmer’s Guide

If you have followed the code in the examples correctly, you should see the following:

As you can see, you have now opened the phone’s Dialer Activity. The Dialer is displaying the phone number that you passed to it, 5551212. Using the Emulator, click the Send button, and the phone should now call 555-1212—virtually of course. Just displaying the Dialer Activity is useful only if you want to create an application that allows the user to edit the number before calling it, or even confirm that they really want to make the call. What should you do if you want your application to actually place the call for you? The answer is addressed next.

Placing a Call from Your Activity
In this section you will learn what Intent to add to your Activity when calling the dialer. You will also learn where to add your chosen Intent in the Activity’s code. Further, you will learn how to parse the intended phone number as a URI. You need to make a few changes to your code to move from the Dialer Activity to the Call Activity. In this section, you are going to edit your AndroidPhoneDialer Activity to place a call after opening the dialer.

Chapter 7:

Using Intents and the Phone Dialer

129

Adding the Intent to Your Activity
You still need the Intent and Uri packages—shown here—so leave those in place at the header of your AndroidPhoneDialer.java file. import android.content.Intent; import android.net.Uri;

These packages will enable you to not only instantiate the Intent that you need, but also pass the needed telephone number data to the Intent (with the Uri package).

TIP
If you are flipping through the chapters out of order, and did not work on the project in the previous section, simply create a new project, name it AndroidPhoneDialer, and add the previous two packages to it. That will catch you up to speed.

Take a look now through the list of possible Activity Action Intents in Table 7-1, shown earlier in this chapter. True to its name, the Intent that you need in your Activity is CALL_ACTION. In much the same way that DIAL_ACTION opened the Android dialer, CALL_ACTION will launch the phone’s calling process and initiate a call to the supplied number. To create the Intent, use the same procedure as you did for the dialer, only this time call CALL_ACTION:
Intent CallIntent = new Intent(Intent.CALL_ACTION,Uri.parse("tel:5551212"));

Notice that you use Uri.parse to pass a correctly parsed telephone number to the Activity. The next step is to tell Android that you want to set this Activity to launch, and then launch it. This is accomplished using the following two lines of code.
CallIntent.setLaunchFlags(Intent.NEW_TASK_LAUNCH ); startActivity(CallIntent);

In the first line, you sent the launch flag to NEW_TASK_LAUNCH. This launches a new instance of the Call Activity. Finally, you tell Android to start the Activity using your Intent. When finished, your AndroidPhoneDialer.java file should look like this. package android_programmers_guide.AndroidPhoneDialer; import android.app.Activity;

130

Android: A Programmer’s Guide

import android.content.Intent; import android.os.Bundle; import android.net.Uri; public class AndroidPhoneDialer extends Activity { /** Called when the Activity is first created. */ @Override public void onCreate(Bundle icicle) { super.onCreate(icicle); setContentView(R.layout.main); /** Create our Intent to call the device's Call Activity */ /** Pass the Call the number 5551212 */ Intent CallIntent = new Intent(Intent.CALL_ACTION,Uri.parse("tel:5551212")); /** Use NEW_TASK_LAUNCH to launch the Call Activity */ CallIntent.setLaunchFlags(Intent.NEW_TASK_LAUNCH ); /** Finally start the Activity */ startActivity(CallIntent); } }

Compile the application now and observe the results; you should see something similar to the error in the following illustration.

Chapter 7:

Using Intents and the Phone Dialer

131

I purposely wanted you to see this error because it shows a side of Android that we have not explored yet. The text of the error should read as follows:
Application_Error: … Java.lang.SecurityException: Permission Denial: starting Intent …

Android marshals certain actions by requiring that permissions be granted to perform them, as covered next.

Editing Activity Permissions
Most Activity Action Intents fall into the category of requiring that the proper permission be set before Android will allow the action. As with many systems, Android just needs to make sure that only Activities with the correct credentials be allowed to perform actions with Activities that are outside of their base. Here are the available permissions:
● ● ● ● ● ● ● ● ● ●

ACCESS_ASSISTED_GPS ACCESS_CELL_ID ACCESS_GPS ACCESS_LOCATION ACCESS_SURFACE_FLINGER ADD_SYSTEM_SERVICE BROADCAST_PACKAGE_REMOVED BROADCAST_STICKY CALL_PHONE CHANGE_COMPONENT_ENABLED_ STATE DELETE_PACKAGES DUMP FOTA_UPDATE GET_TASKS INSTALL_PACKAGES

● ● ● ● ● ● ● ● ● ●

INTERNAL_SYSTEM_WINDOW RAISED_THREAD_PRIORITY READ_CONTACTS READ_FRAME_BUFFER RECEIVE_BOOT_COMPLETED RECEIVE_SMS RECEIVE_WAP_PUSH RUN_INSTRUMENTATION SET_ACTIVITY_WATCHER SET_PREFERRED_ APPLICATIONS SIGNAL_PERSISTENT_ PROCESSES SYSTEM_ALERT_WINDOW WRITE_CONTACTS WRITE_SETTINGS

●

●

● ● ● ●

● ● ●

132

Android: A Programmer’s Guide

Compare this list of permissions with the list of Intents in Table 7-1. You should find that most of the Intents match up with a corresponding permission. The CALL_ACTION Intent is no exception. You need to assign your Activity the CALL_PHONE permission to be able to execute your Intent. To assign your Activity the correct permission, you first need to know what permission you need to assign. The current example is using the Dialer Activity. Access to the Dialer Activity is governed by the CALL_PHONE permission. By assigning this permission to your Activity, Android will let your Intent launch the Dialer Activity. How do you add permissions to the Activity? You need to edit the Activity’s Manifest. If you are using Eclipse, double-click AndroidManifest.xml. This opens the Android Manifest Overview window, shown in the following illustration.

Chapter 7:

Using Intents and the Phone Dialer

133

To edit the Activity’s permissions, click the Permission link. This should take you to the Android Manifest Permissions window, shown in the following illustration.

This window lists the permissions that are currently assigned to your Activity. Given that you are working in a new project, you do not have any assigned permissions. Therefore, click the Add button to begin the process. In the dialog box that opens, select Uses Permission and click OK.

134

Android: A Programmer’s Guide

Back in the Android Manifest Permissions window, in the Name drop-down list, select android.permission.CALL_PHONE, as shown next. This adds the CALL_PHONE permission to your Activity.

Now that you have added the CALL_PHONE permission, take a look at AndroidManifest.xml. It should look similar to the following:

Chapter 7:

Using Intents and the Phone Dialer

135

The line of most interest is at the end of the file:

This line of code was added by the Android plugin for Eclipse. If you wanted to, you could have edited AndroidManifest.xml directly to assign the permission. However, if there are times when you are not sure what permission you need to add, or the syntax with which to add it, you can use the Manifest’s wizard. Now that the permission is in place, recompile and run your Activity. Your Emulator should now be making a phone call, as shown in the following illustration.

136

Android: A Programmer’s Guide

The Activity you created has used an Intent to launch the device’s Call Activity and call the number 555-1212. This demonstrates how you can use Intents to your benefit. However, this application does little for you practically. That is to say, how practical would it be to launch an Activity with a hard-coded phone number, just to make a call? In the following section, you are going to make your application more practical, by adding both a button, to initiate the launching of the Call_Action Intent, and a textbox, to allow the user to input a phone number of their choosing.

Modifying the AndroidPhoneDialer
This section shows you how to modify your AndroidPhoneDialer to make it a bit more practical by adding a few features. By the end of this section, you should be pretty comfortable using not only Intents, but EditTexts and Buttons.

CAUTION
If you did not follow along with the project from the last section, go back and create that Activity. The tutorial in this section assumes that you already have the completed code from the last project at your disposal.

Adding a Button
This section shows you how to modify your project to include a Button. Instead of launching the Intent when the Activity is started, it will be launched by the Button. With the exception of text, buttons are the most prevalent type of object on an application. Buttons form the main interaction between users and applications. Learning how to create and utilize buttons in Android is essential to creating a practical, user-friendly Activity. You are going to create the Button in main.xml. Think back to Chapter 5, in which you created the TextView for your Hello World! Activity. The TextView had a distinct structure to it, something like this:

NOTE
Remember, when you create a View in main.xml, you are only telling Android what you want the View to look like. You still need to assign functionality to it in AndroidPhoneDialer.java.

Chapter 7:

Using Intents and the Phone Dialer

137

This formatting is common across views, and the Button is no exception. The XML attributes you need to set for your Button are android:id, android:layout_width, android:layout_height, and android:text. These four XML attributes sufficiently describe your Button so that you can use it within your Activity.
1. Assign to your Button the ID callButton: android:id="@+id/callButton" 2. Set layout_width and layout_height to fill_parent and wrap_content, respectively: android:layout_width="fill_parent" android:layout_height="wrap_content"

3. Set the text of the Button to “Show Dialer,” which is descriptive enough to identify

what the Button will do: android:text="Show Dialer"

The full XML for the Button, with attributes, looks like this:

Take a look now at the finished main.xml file. The Button appears in context and is waiting for you to begin coding it.

To start adding functionality to the Button, you need to add another package to AndroidPhoneDialer.java. The package that contains the Button View is android.widget.Button; 138

Android: A Programmer’s Guide

You have now imported the Button widget into your project. This gives you the necessary information to begin coding your project. The ultimate outcome of what you are coding in this project should be a Button in your Activity that, when clicked, launches the Call Activity. The Call Activity should be launched with the data "tel:5551212". The resulting screen will match that from your original AndroidPhoneDialer. The described functionality encompasses a few different concepts. First, you must program a Button that uses the Button attributes you established in main.xml. Next, you have to create a function that will launch the CALL_ACTION Intent code from your previous project. Finally, your Button needs to be able to execute the function and launch the Intent. The syntax for creating your Button is final Button =

The left side of this equation creates the Button in your code. The right side of the equation is where you call the Button attributes from main.xml. To call the attributes, you use findViewById( ) and cast the result as a Button. This sounds a little more complicated than it actually is. Remember, when you added the Button attributes to main.xml, you gave the Button a specific android:id, callButton, which was registered by the Android plugin for Eclipse in the id file as R.id.callButton. Use findViewById( ) to retrieve the Button attributes from main.xml by passing it the id callButton: findViewById(R.id.callButton) Don’t forget to cast the result as a Button:
(Button) findViewById(R.id.callButton)

This statement makes up the right side of your equation. The full equation to create your Button looks like this: final Button callButton = (Button) findViewById(R.id.callButton);

You now have a Button that you can work with, but you need something for it to do. The Button by itself really does not do much without more code. For purposes of this example, you need to have it execute the CALL_ACTION Intent. Therefore, you are

Chapter 7:

Using Intents and the Phone Dialer

139

going to create a small function around your existing Intent call. This will give you something to call from when the Button is pressed. There should be no surprises here if you are familiar with Java programming. You will set up the onClick( ) method to call the Intent code from the previous section. The onClick( ) method takes a View as an argument; however, in this project, you make no calls to the View within the onClick( ) method itself: public void onClick(View v){ Intent callIntent = new Intent(Intent.CALL_ACTION,Uri.parse("tel:5551212")); callIntent.setLaunchFlags(Intent.NEW_TASK_LAUNCH ); startActivity(callIntent); }

The only piece of the application that is left to code is the listener that will tie the Button to the onClick. Listeners should be familiar to Java programmers. For those of you who are not familiar with Java or listeners, listeners are the method by which Java objects can “listen” to calls from other objects. The same concept applies within Android. You can establish listeners within Android to let Android Views handle calls from other inputs. For this project, you need to create for your Button a listener that listens for the onClick event from the Button on the Activity. When the user presses the Button, the listener will call the code in the onClick( ) method. To establish the listener you need, you use the setOnClickListener( ) method of the Button. If you are familiar with Java development, this structure should not look foreign. This is a typical onClickListener interface implementation in Java. What you will see here is the use of a Java anonymous class to implement the onClickListener for your Button. Also, as an anonymous class, you can make use of local variables—in this case the Button—if that variable is defined as final. The setOnClickListener( ) method takes a pair of arguments. The first is an instantiation of the onClickListener( ). The second is the onClick established earlier. Your setOnClickListener( ) should look like this: callButton.setOnClickListener(new Button.OnClickListener() { public void onClick(View v){ Intent callIntent = new Intent(Intent.CALL_ACTION,Uri.parse("tel:5551212"));

140

Android: A Programmer’s Guide

callIntent.setLaunchFlags(Intent.NEW_TASK_LAUNCH ); startActivity(callIntent); } });

This code segment states that when the callButton is pressed, the onClickListener will execute the code in the onClick. The code in the onClick will execute the CALL_ACTION Intent and call the phone number 555-1212. Your finished AndroidPhoneDialer.java looks like this: package android_programmers_guide.AndroidPhoneDialer; import import import import import import android.app.Activity; android.os.Bundle; android.widget.Button; android.view.View; android.content.Intent; android.net.Uri;

public class AndroidPhoneDialer extends Activity { /** Called when the activity is first created. */ @Override public void onCreate(Bundle icicle) { super.onCreate(icicle); setContentView(R.layout.main ); /** Create the Button */ final Button callButton = (Button) findViewById(R.id.callButton); /** Set the onClickListener to call the onClick */ callButton.setOnClickListener(new Button.OnClickListener() { /** Use the onClick to call the existing Intent code */ public void onClick(View v){ Intent callIntent = new Intent(Intent.CALL_ACTION,Uri.parse("tel:5551212")); callIntent.setLaunchFlags(Intent.NEW_TASK_LAUNCH ); startActivity(callIntent); } }); } }

Compile and run this Activity in the Emulator. The main Activity will display a Button labeled Show Dialer. Click the Button. It should open the Call Activity and dial 555-1212. The main Activity should look as it does in the following illustration.

Chapter 7:

Using Intents and the Phone Dialer

141

As you can see, Android is a very robust and flexible platform. With a relatively few lines of code, less than a page, you have created an Activity that utilizes the device’s phone hardware and is launched with a Button. Also, by this point you should be pretty comfortable with the way Android handles Activities, Intents, and Views. Your AndroidPhoneDialer Activity is still rather impractical. You need to add one more item to it. The final section of this chapter shows you how to use the EditText View to let the user input a phone number. The number will then be passed to the CALL_ACTION Intent (instead of the hard-coded value tel:5551212).

Implementing an EditText View
You need to add a View to your Activity that will let the user input some text. You will then parse that text and send it to the Intent call from the previous section. Because all Views inherit from the base View, they are helpfully similar in structure and usage. You will find that implementing an EditText is a very simple operation.

142

Android: A Programmer’s Guide

First, lay out the Views in your main.xml. You will actually add two Views here: a TextView to act as a label and give some direction to the user, and an EditText to accept the user’s input. Together these two Views will add the needed depth and practicality to your Activity. As you form the look of your Activity, keep in mind that the .xml file is formed visually. This means that if you want the TextView to appear above the EditText on the finished Activity, you should place it before the EditText in main.xml. Because you have used TextViews a few times now, creation of this View will not get too involved. Simply take a look at the attributes that you set in your TextView:

There is nothing out of the ordinary here. This is just a simple TextView with the text Enter Number to Dial:. This TextView will serve as a label for your EditView. Here’s how you set the attributes for the EditView.

NOTE
You do not have to set the android:text attribute because you do not need any default text.

The id is set to phoneNumber, which is the name you will use to refer to the EditText View in the code. Again, there should be no surprises when setting up main.xml. Your final file should look like this:

The main.xml file is now completed. You can move on to AndroidPhoneDialer.java. If you are not using an existing version of AndroidPhoneDialer.java—one from a previous project in this chapter—you may want to refer to the previous sections to see what code is added to the .java file. This will ensure that you start from the correct point in the code. The first item you need to add to your .java file is the package definition. You need to add packages not only for the Uri, Button, and Intent, but also for the EditText: import import import import android.widget.Button; android.content.Intent; android.net.Uri; android.widget.EditText;

The syntax to set up your EditText View is the same as that for the Button: final EditText =

Again, call your EditText phoneNumber. The code to create your EditText is as follows: final EditText phoneNumber = (EditText) findViewById(R.id.phoneNumber);

144

Android: A Programmer’s Guide

Once your phoneNumber EditText is created, you can use it to reference the text that is input on the device. All you have to do now is call phoneNumber.getText( ) to retrieve the user’s input. Replace the hard-coded value “tel:5551212” in the following line,
Intent(Intent.CALL_ACTION,Uri.parse("tel:5551212"));

with the value of getText( ):
Intent(Intent.CALL_ACTION,Uri.parse("tel:" + phoneNumber.getText()));

That is all the new code you need to update your project. With these simple two additions, you can give the user an object with which to input a phone number, and send that number to the phone’s Call Activity. The full code in the .java file should look like this: package android_programmers_guide.AndroidPhoneDialer; import import import import import import import android.app.Activity; android.os.Bundle; android.widget.Button; android.view.View; android.content.Intent; android.net.Uri; android.widget.EditText;

public class AndroidPhoneDialer extends Activity { /** Called when the activity is first created. */ @Override public void onCreate(Bundle icicle) { super.onCreate(icicle); setContentView(R.layout.main ); final EditText phoneNumber = (EditText) findViewById(R.id.phoneNumber ); final Button callButton = (Button) findViewById(R.id.callButton); callButton.setOnClickListener(new Button.OnClickListener() { public void onClick(View v){ Intent CallIntent = new Intent(Intent.CALL_ACTION,Uri.parse("tel:" + phoneNumber.getText())); CallIntent.setLaunchFlags(Intent.NEW_TASK_LAUNCH ); startActivity(CallIntent); } }); } }

Chapter 7:

Using Intents and the Phone Dialer

145

When you run the application in your Emulator, you should see a screen that resembles the following illustration.

Try This

Modify the AndroidPhoneDialer Project

If you played around with the latest version of the AndroidPhoneDialer, you may have noticed something missing. Unfortunately, the way the project is currently written, it allows you to input any type of value into the EditText View and try to send it to the Call Activity. This is really not an optimal approach to application development. Do some research and add some validation to the EditText. Use the following parameters to modify your project:
●

Use a regular expression to validate that a phone number was entered in the EditText (package java.regex). Use the showAlert( ) syntax to display a message telling the user they input something that does not match your regular expression.

●

146

Android: A Programmer’s Guide

When you feel you have a working solution, compare it against the following code.

main.xml

AndroidPhoneDialer.java package android_programmers_guide.AndroidPhoneDialer; import android.app.Activity; import android.os.Bundle; import android.widget.Button; import android.view.View; import android.content.Intent; import android.net.Uri; import android.widget.EditText; import java.util.regex.*; public class AndroidPhoneDialer extends Activity { /** Called when the activity is first created. */ @Override public void onCreate(Bundle icicle) { super.onCreate(icicle); setContentView(R.layout.main ); final EditText phoneNumber = (EditText) findViewById(R.id.phoneNumber ); final Button callButton = (Button) findViewById(R.id.callButton); callButton.setOnClickListener(new Button.OnClickListener() {

Chapter 7:

Using Intents and the Phone Dialer

147

public void onClick(View v){ if (validatePhoneNumber(phoneNumber.getText().toString())){ Intent CallIntent = new Intent(Intent.CALL_ACTION,Uri.parse("tel:" + phoneNumber.getText())); CallIntent.setLaunchFlags(Intent.NEW_TASK_LAUNCH ); startActivity(CallIntent); } else{ showAlert("Please enter a phone number in the X-XXX-XXX-XXXX format.",0, "Format Error", "Re-enter Number",false); } } }); } public boolean validatePhoneNumber(String number){ Pattern phoneNumber = Pattern.compile("(\\d-)?(\\d{3}-)?\\d{3} \\d{4}"); Matcher matcher = phoneNumber.matcher(number); return matcher.matches(); } }

When you run the project, it should produce a message similar to that in the following illustration.

148

Android: A Programmer’s Guide

In the next chapter, you will learn about more Views. You will create a multi-Activity application that will allow you to explore and create Views that have not yet been discussed in this book. You will also create and utilize a menu system that will launch your Activities.

Ask the Expert
Q: A: Q: A:
Is there a way to establish a call to or from the Emulator, to ensure that these Activities are working? As of the time this book was written, there was no way to complete a call to or from the Emulator. However, there was talk from Google that in a future release of the SDK, developers would be able to open two Emulators and complete calls between the two. Are there other types of Buttons available to Activities—with a different look or feel? Yes. You can use the style attribute to create small Buttons, or small Buttons that include a pointer up, down, left, or right.

Chapter

8

Lists, Menus, and Other Views

Copyright © 2008 by The McGraw-Hill Companies. Click here for terms of use.

150

Android: A Programmer’s Guide

Key Skills & Concepts
● ● ●

Building Activities Using Android Menus Using the AutoCompleteTextView

T

his chapter provides a more in-depth treatment of Views and Intents, which arguably are the most important features you should master as a newcomer to Android. These two entities will make up the majority of your early Activities. Almost every Activity you create will have more than one View, and most of them will also need to call an Intent or two. The best way to learn the most about these topics is to take a very hands-on approach. Reading about these topics and reviewing a list of attributes is one thing, but implementing the code on your own is something entirely different. That is, just as you have done in the previous chapters, you are going to build an Activity that uses Views and Intents rather heavily. By building this application, you will get the best experience with Views and Intents. The previous two chapters briefly introduced both Views and Intents by having you create very simple Activities that exploited the basic functions of a handful of example Views and Intents. In this chapter, you are going to build a slightly more complex Activity that uses Intents to call new Activities, which you will also create. These new Activities will showcase most of the Views that are available in the current version of the Android SDK. This chapter explains the basic functionality of these Views, such as AutoComplete lists and Galleries, and introduces variations of each View attribute for each Activity. To begin, create a new Eclipse project named AndroidViews. Create the project with the parameters shown in the following illustration: a Package Name of android_ programmers_guide.AndroidViews, an Activity Name of AndroidViews, and an Application Name of AndroidViews.

Chapter 8:

Lists, Menus, and Other Views

151

Finish creating the project and open the main.xml file. Remove the Hello World! code from main.xml. With the project created and main.xml cleaned, you can begin to add your code.

Building the Activities
Up to now, you have created only single-Activity applications. This is to say, you have created rather simplistic applications that encompass only one “screen” of data. Take a minute, and think of the last few applications you have used. Chances are, they used more than one “window.” Most applications use multiple windows to gather, display, and save data. Your Android applications should be no different.

152

Android: A Programmer’s Guide

Although you have not yet learned how to create multiple-Activity applications that run on Android, you got a hint about how to leverage multiple Activities in the last chapter. You used a new concept called Intents to call—and run—a core Android Activity. While the concept still holds true in this chapter, the execution is slightly different when you want to call Activities that you have created, as opposed to calling core Android Activities. The first thing you need to do is build the Activities. Then you can create the Intents that will call them. When building the Activities, you need to follow a three-step process.
● ● ●

Intent code for the .xml file Intent code for the .java file Calling Activities using an Intent Once you create your first additional Activity, the rest should come very easily.

NOTE
These steps are not bound to each other. You can perform them in any order.

Intent Code for the .xml File
Remember that all Android Activities comprise three main parts: the .java file that contains the code, the .xml file that holds the layout, and the package’s Manifest. To this point in the book, you have only used main.xml to control the layout of a single Activity. However, to take advantage of having multiple Activities, you must have multiple .xml layout files. To create a new .xml file, open your Eclipse project and navigate to the Package Explorer. Open the res directory, right-click the layout folder, and choose New | File.

In the New File dialog box, shown next, name your file test.xml.

Chapter 8:

Lists, Menus, and Other Views

153

CAUTION
Be sure to enter the filename test.xml in all lowercase letters. New .xml filenames must be all lowercase.

The layout file is created, but it is empty. To get the Activity off on the right foot, add the following code to test.xml. This code will provide a base for your layout. If you need to, you can simply copy this code from the existing main.xml file.

154

Android: A Programmer’s Guide

Intent Code for the .java File
Using the Package Explorer again, navigate to the src directory, open it, and right-click the android_programmers_guide.AndroidViews package, as shown in the following illustration.

Once again, you are going to add a new file to the folder. After you right-click the AndroidViews package, select New | File from the context menu. This file will hold all the code for the second Activity in this project. Name the file test.java. You should now have a nice, new (but empty) .java file. You just need to add a few lines of code to the file to make it usable: package testPackage.test; import android.app.Activity; import android.os.Bundle; public class test extends Activity { /** Called when the Activity is first created. */ @Override public void onCreate(Bundle icicle) { super.onCreate(icicle); setContentView(R.layout.test); /** This is our Test Activity All code goes below */ } }

Notice that you call test.xml in the setContentView method, using the context R.layout.test. This line tells the new Activity to use the .xml file you created as the layout file for this “page.”

Chapter 8:

Lists, Menus, and Other Views

155

Modifying the AndroidManifest.xml
Open your AndroidManifest.xml file in Eclipse. AndroidManifest.xml has not been discussed in great detail in this book. AndroidManifest.xml contains the global settings for your project. More importantly, AndroidManifest.xml also contains the Intent Filters for your project. Chapter 7 discussed how Android uses the Intent Filters to marshal what Intents can be accepted by what Activities. The information that facilitates this process is kept in AndroidManifest.xml.

NOTE
There is only one AndroidManifest.xml file per project.

If your AndroidManifest.xml file is currently open, it should appear as follows:

What you are looking at here is the Intent Filter for the AndroidViews Activity, the main Activity that was created with the project. To this file you can add any other Intent Filters that you want your project to handle. In this case, you want to add an Intent Filter that will handle the new Test Activity that you created. The following is the code for the Intent Filter that you need to add to the AndroidManifest.xml file:

Adding this code to AndroidManifest.xml enables Android to pass Intents for the Test Activity to the correct place. The full AndroidManifest.xml file should look like this:

Now your Activity can handle Intent calls for the Test Activity. To make your Intent call to the Test Activity, you are going to use a structure very similar to the one you used when calling the phone dialer in Chapter 7. The following line of code will set up your Intent:

NOTE
When you start your application, the Activity that will be opened is the AndroidViews Activity that you created with your project. Therefore, place the following code in AndroidViews.java for the purpose of starting the Test Activity. Intent testActivity = new Intent(this, test.class);

This line creates an Intent called testActivity. The parameter test.class tells the call that you want the Intent testActivity to represent the Test Activity you created that is associated with this Activity.

CAUTION
Do not forget to import the android.content.Intent package when you are working with Intents.

Finally, use the startActivity( ) method to actually start the Test Activity:

Chapter 8:

Lists, Menus, and Other Views

157

startActivity(autocomplete);

Your completed AndroidViews.java file should look like this: package android_programmers_guide.AndroidViews; import import import import android.app.Activity; android.os.Bundle; android.view.Menu; android.content.Intent;

public class AndroidViews extends Activity { /** Called when the Activity is first created. / @Override public void onCreate(Bundle icicle) { super.onCreate(icicle); setContentView(R.layout.main); /**Set up our Intent /

Run this application in your Android Emulator. Android should launch the AndroidViews Activity, followed quickly by the Test Activity. In the following section, you will use these techniques to create an application that launches multiple Activities. Each of these Activities will house one View to which you can apply different options. This will give you a great deal of practice displaying and manipulating Views as well as working with Activities.

NOTE
To work with the remaining samples in the upcoming section, remove the Test Activity that you created in this section. You will proceed with the creation of the AndroidViews project without the Test Activity.

Using the Menu
In this section, you are going to build an application that will allow a user to select from a number of different Views. When the user selects a View, a new Activity will be launched containing the selected View.

158

Android: A Programmer’s Guide

The tool you are going to use to offer the selections to the user is the Android Menu. Take a look the following illustration. The Menu is displayed when the user activates the Menu Button.

As you can see, selecting the Menu Button from the Android home screen produces a Wallpaper settings option. You are going to create a similar menu for your main Activity that will hold all the options for the Views that the user will be able to select from. Right now, the code of your AndroidViews.java file should look like this: package android_programmers_guide.AndroidViews; import android.app.Activity; import android.os.Bundle; public class AndroidViews extends Activity { /** Called when the Activity is first created. */ @Override public void onCreate(Bundle icicle) { super.onCreate(icicle);

Chapter 8:

Lists, Menus, and Other Views

159

setContentView(R.layout.main); } }

As with everything you add to your Activities, you need to import a new package to create your menu. Import the android.view.Menu into your AndroidViews Activity:
Import android.view.Menu;

To create the Menu, you need to override the onCreateOptionsMenu( ) method of the Activity. The method onCreateOptionsMenu( ) is a Boolean method that is called when the user first selects the Menu Button. You will use this method to build your Menu and add your selection items to it. Add the following code to AndroidViews.java:
@Override public boolean onCreateOptionsMenu(Menu menu) { super.onCreateOptionsMenu(menu); }

You will add the code to create the Menu inside the onCreateOptionsMenu( ) method. The items that you need to add to the Menu are the Views that you are going to create in this project. The following is the list of View names that you will need to add to the Menu:
● ● ● ● ● ●

AutoComplete Button CheckBox EditText RadioGroup Spinner

In the preceding code that you created to override the onCreateOptionsMenu( ) method, you passed in a Menu variable called menu. This variable represents the actual menu item that is created on the Android interface. To add your list of items to the Menu, you will use the menu.add( ) method. The syntax for this call is as follows: menu.add(,,) 160

Android: A Programmer’s Guide

The parameter group is used to associate the menu items. You will not be using group in this example. However, the value is very important. The parameter id is used to determine what menu item was selected. Finally, the parameter title is the text that will be displayed in the Menu. Add the following code to the onCreateOptionsMenu( ) method: menu.add(0, menu.add(0, menu.add(0, menu.add(0, menu.add(0, menu.add(0, 0, 1, 2, 3, 4, 5, "AutoComplete"); "Button"); "CheckBox"); "EditText"); "RadioGroup"); "Spinner");

Your full AndroidViews.java file should now look like this: package android_programmers_guide.AndroidViews; import android.app.Activity; import android.os.Bundle; import android.view.Menu; public class AndroidViews extends Activity { /** Called when the Activity is first created. */ @Override public void onCreate(Bundle icicle) { super.onCreate(icicle); setContentView(R.layout.main); } @Override public boolean onCreateOptionsMenu(Menu menu) { super.onCreateOptionsMenu(menu); menu.add(0, 0, menu.add(0, 1, menu.add(0, 2, menu.add(0, 3, menu.add(0, 4, menu.add(0, 5, return true; } } "AutoComplete"); "Button"); "CheckBox"); "EditText"); "RadioGroup"); "Spinner");

If you execute this code as it is written, you should see the menu shown in Figure 8-1.

Chapter 8:

Lists, Menus, and Other Views

161

Figure 8-1 Menu with six Views

This is exactly what you wanted to accomplish. However, try clicking any of the options in the Menu. You do not have anything in your Activity that handles events when the user selects a Menu item. The method you need to override to handle the calls to the Menu items is onOptionsItemSelected( ). Again, like onCreateOptionsMenu( ), onOptionsItemSelected( ) is a Boolean method that you need to override with the specific code to be executed when a Menu item is selected. The override code should look like this:
@Override public boolean onOptionsItemSelected(Menu.Item item){ }

There is one problem with this code: onOptionsItemSelected( ) is a general method that is called when any menu item is selected. You need to give onOptionsItemSelected( ) a way to differentiate between the menu items and execute code accordingly. Therefore,

162

Android: A Programmer’s Guide

use a switch/case statement to help the method select between the menu items. When you created the menu items, you specified a series of numbers from 0 to 5 as the values for your menu items. You can use a call to getId( ) in your case statement to determine which menu item was selected: switch (item.getId()) { case 0: return true; case 1: return true; case 2: return true; case 3: return true; case 4: return true; case 5: return true; } return true;

In this case statement, the action for each id is currently set to return true. This will not do anything but hold open the area where you need to add code. Your AndroidViews.java file is now ready for use to create Activities that can be launched by the new menu system. The full code of AndroidViews.java should look like this: package android_programmers_guide.AndroidViews; import android.app.Activity; import android.os.Bundle; import android.view.Menu; public class AndroidViews extends Activity { /** Called when the Activity is first created. / @Override public void onCreate(Bundle icicle) { super.onCreate(icicle); setContentView(R.layout.main); } @Override public boolean onCreateOptionsMenu(Menu menu) { super.onCreateOptionsMenu(menu);

Chapter 8:

Lists, Menus, and Other Views

163

/** Add one menu item for each View in our project */ menu.add(0, 0, "AutoComplete"); menu.add(0, 1, "Button"); menu.add(0, 2, "CheckBox"); menu.add(0, 3, "EditText"); menu.add(0, 4, "RadioGroup"); menu.add(0, 5, "Spinner"); return true; } /** Override onOptionsItemSelected to execute code for each menu item */ @Override public boolean onOptionsItemSelected(Menu.Item item){ } /** Select statement to handle calls to specific menu items */ switch (item.getId()) { case 0: return true; case 1: return true; case 2: return true; case 3: return true; case 4: return true; case 5: return true; } return true; } }

With AndroidViews.java complete, you can focus on creating your other Activities. In the following sections, you will create one Activity for each View in your project and add the code to launch that view’s Activity in your case statement.

Creating the Activity for AutoComplete
In this section, you are going to create an Activity that will show off the AutoCompleteTextView. AutoCompleteTextViews can be very powerful tools for your applications. This View is specifically helpful at making the most of the limited space available to the Android main screen.

164

Android: A Programmer’s Guide

AutoCompleteTextView, as the name implies, is a modified TextView that will refer a possible value for the completion of a word or phrase typed into it. Such Views are greatly useful in mobile applications when you do not want to devote a large amount of space to a ListView, or you want to speed along the process of entering text into your application. To begin creating your Activity for the AutoCompleteTextView, you need to add a new .xml file for that layout, a .java file for the code, and an Intent Filter to handle the calls.

TIP
The process of creating these items appeared in the “Building the Activities” section earlier in the chapter. Refer to that section as needed to create the following pieces of the project.

Create an autocomplete.xml File
Create a new .xml file in your AndroidViews project named autocomplete.xml. Keep in mind that the filename must be all lowercase. The file should appear in the layout folder in your Package Explorer. Double-click the file to edit it. This file is going to control the layout for your AutoCompleteTextView Activity, so you need to have an AutoCompleteTextView in the layout. The XML for adding an AutoCompleteTextView looks like this:

You have created a few Views now in .xml files, so you should be familiar with the format. There is nothing different or unusual about the AutoCompleteTextView. You are setting the id to testAutoComplete, and the width and height to fill_parent and wrap_content, respectively. You should add the layouts for two Buttons as well. These Buttons will be used to control the attributes that you will change. Name the Buttons autoCompleteButton and textColorButton, as follows:

With the three View layouts added, your finished autocomplete.xml file should look like this:

Create an autocomplete.java File
Follow the instructions that were introduced in the “Creating a New .java File” section earlier in this chapter to create your autocomplete.xml file. The first thing you need to do is import the packages for your Views. In this Activity, you are using two Views, the AutoCompleteTextView and the Button. You also need to work with Colors and an ArrayAdapter. Therefore, import the following packages with your Activity: package android_programmers_guide.AndroidViews; import android.app.Activity; import android.os.Bundle; import android.view.View; import android.widget.ArrayAdapter; import android.widget.AutoCompleteTextView; import android.widget.Button; import android.graphics.Color;

NOTE
While you may not know what they are for yet, just add the packages for Color and ArrayAdapter. I will explain them later in this section.

166

Android: A Programmer’s Guide

Add the initial structure for your AutoComplete class to autocomplete.java: public class AutoComplete extends Activity { @Override public void onCreate(Bundle icicle) { super.onCreate(icicle); } }

This class gives you a base to start building the rest of your Activity. All the functionality of this Activity will be built around this class. The first thing you need to do is load the layout from autocomplete.xml: setContentView(R.layout.autocomplete); For this example, you will create the AutoCompleteTextView so that it contains a list of the months of the year. When a user types into the box, it will anticipate which month they are trying to enter. Given that the AutoCompleteTextView will contain a list of the months, you need to create a list that can be assigned to the AutoCompleteTextView. Create a string array and assign the month values to it: static final String[] Months = new String[]{ "January","February","March","April","May","June","July","August", "September","October","November","December" };

The next task is to assign this string array to the AutoCompleteTextView. You have created more than a few Views by now, so the code to create the AutoCompleteTextView should look very familiar. What you have not seen before is the code to assign the string array to the View:
ArrayAdapter monthArray = new ArrayAdapter(this, android.R.layout.simple_list_item_1, Months); final AutoCompleteTextView textView = (AutoCompleteTextView) findViewById(R.id.testAutoComplete); textView.setAdapter(monthArray);

In the first line, you are taking the string array you created and assigning it to an ArrayAdapter named monthArray. Next, you instantiate your AutoCompleteTextView by locating it in the .xml layout file. Finally, you use the setAdapter( ) method to assign the monthArray ArrayAdapter to the AutoCompleteTextView.

Chapter 8:

Lists, Menus, and Other Views

167

The next snippet of code instantiates the two Buttons. This is the same code you have used in previous chapters. The only difference here from other code you have written is that you are calling two functions, changeOption and changeOption2, which have not been created yet.

NOTE
Notice that you are passing the AutoCompleteTextView into the function calls. You will need to create this parameter when you create the functions. final Button changeButton = (Button) findViewById(R.id.autoCompleteButton); changeButton.setOnClickListener(new Button.OnClickListener() { public void onClick(View v){ changeOption(textView); } }); final Button changeButton2 = (Button) findViewById(R.id.textColorButton); changeButton2.setOnClickListener(new Button.OnClickListener() { public void onClick(View v){ changeOption2(textView); } });

The functions called by these Buttons will be used to change layout attributes on the AutoCompleteTextView. The two attributes I have chosen to modify (using the Buttons) are the layout height and text color. You are going to set up one of these Buttons to change the AutoCompleteTextView’s layout height from 30 to 100 and back. The other Button will change the color of the text within the View to red. The function changeOption( ) will change the AutoCompleteTextView’s layout height. The code for this function is very simple: public void changeOption(AutoCompleteTextView text){ if (text.getHeight()==100){ text.setHeight(30); } else{ text.setHeight(100); } }

What you are doing in this function is checking the current height of the AutoCompleteTextView. If that height is 100, you set it to 30; otherwise you set it to 100.

168

Android: A Programmer’s Guide

The changeOption2( ) function is just as easy: public void changeOption2(AutoCompleteTextView text){ text.setTextColor(Color.RED); } }

This function simply sets the text color of the AutoCompleteTextView to Color.RED. The value Color.RED is imported from the android.graphics.Color package. You can browse this package and change the color to any value; I selected RED so that it would stand out. Your full autocomplete.java file should now look like this: package android_programmers_guide.AndroidViews; import import import import import import import android.app.Activity; android.os.Bundle; android.view.View; android.widget.ArrayAdapter; android.widget.AutoCompleteTextView; android.widget.Button; android.graphics.Color;

public class AutoComplete extends Activity { @Override public void onCreate(Bundle icicle) { super.onCreate(icicle); setContentView(R.layout.autocomplete); ArrayAdapter monthArray = new ArrayAdapter(this, android.R.layout.simple_list_item_1, Months); final AutoCompleteTextView textView = (AutoCompleteTextView) findViewById(R.id.testAutoComplete); textView.setAdapter(monthArray); final Button changeButton = (Button) findViewById(R.id.autoCompleteButton); changeButton.setOnClickListener(new Button.OnClickListener() { public void onClick(View v){ changeOption(textView); } }); final Button changeButton2 = (Button) findViewById(R.id.textColorButton);

Chapter 8:

Lists, Menus, and Other Views

169

changeButton2.setOnClickListener(new Button.OnClickListener() { public void onClick(View v){ changeOption2(textView); } }); } static final String[] Months = new String[]{ "January","February","March","April","May","June","July","August", "September","October","November","December" }; public void changeOption(AutoCompleteTextView text){ if (text.getHeight()==100){ text.setHeight(30); } else{ text.setHeight(100); } } public void changeOption2(AutoCompleteTextView text){ text.setTextColor(Color.RED); } }

Add an Intent Filter
The last thing you need to do before you can run this application is to set up the Intent Filter in AndroidManifest.xml. You will then be able to call that Intent from the Menu shown earlier in Figure 8-1. The code for the Intent Filter should look as follows:

Here is your completed AndroidManifest.xml file for this project:

170

Android: A Programmer’s Guide

Handling the Intent Call
With AndroidManifest.xml complete, add the following function to AndroidViews.java: public void showAutoComplete(){ Intent autocomplete = new Intent(this, AutoComplete.class); startActivity(autocomplete); }

When called from your select/case statement, this function will open your autocomplete Activity. Edit the case 0 of the select statement to let it call the new function: case 0: showAutoComplete(); return true;

Run the application in the Android Emulator. When the main Activity is launched, click the Menu Button, and you should see the menu shown earlier in Figure 8-1. Click the AutoComplete menu item. Clicking the AutoComplete Button menu item should bring up your autocomplete Activity, shown next.

Chapter 8:

Lists, Menus, and Other Views

171

To test the AutoCompleteTextView, begin typing the word January. After you type a few characters, you should see the word January appear under the text box, as shown in the following illustration.

172

Android: A Programmer’s Guide

Next, click the Change Layout Button, the result of which should be an expanded text entry box similar to that shown in the following illustration.

Now click the Change Text Color Button and type some text, as shown next.

Chapter 8:

Lists, Menus, and Other Views

173

The following sections give you the supporting code for implementing the remaining five Views in your project.

Button
Take a look at the following code. This code represents four files, AndroidManifest.xml, Button.xml, testButton.java, and AndroidViews.java. Add the code in these files to your existing AndroidViews Activity.

CAUTION
If you have not followed this chapter from the beginning, you may have trouble implementing this code. To make sure you are getting the full project, follow this chapter from the beginning.

AndroidManifest.xml . This indicates that the database itself has been successfully created but is still empty. The database contains no tables or data. With this in mind, your next step is to create a table for your Activity’s data. You need to create a table called friends. This table will hold id, name, location, created, and modified fields. These fields will offer more than enough information for your project.

262

Android: A Programmer’s Guide

TIP
If you are not familiar with SQLite, a SQLite command must terminate with a semicolon. This is helpful if you want to span commands across prompts. Pressing the ENTER key without terminating a SQLite command will give you a continuation prompt, …>. You can continue to enter your command at this prompt until you use the semicolon. SQLite will treat such continued commands as one full command once the semicolon is used.

To create your friends table within your database, enter the following command at the sqlite> prompt:
CREATE TABLE friends (_id INTEGER PRIMARY KEY, name TEXT, location TEXT, created INTEGER, modified INTEGER);

If your command executes successfully, you will be returned to the sqlite> prompt, as shown in the following illustration.

Your database is now ready to be used, and you can exit SQLite. Use the command .exit to exit. You can then quit your shell session and return to Eclipse. Creating the database was the first step in setting up your application. Now that the database and corresponding table are created, you need a method to access the data. The data access method employed by Android is a Content Provider. The following section walks you through creating a custom Content Provider for your new database and accessing your data.

Chapter 11:

Application: Find a Friend

263

Creating a Custom Content Provider
Android uses Content Providers to mitigate access to data. You used a Content Provider in Chapter 9 to access and read coordinate information from a GPS. The same process applies to databases. There are Content Providers for Contact Lists, IMs, and Recent Calls. However, there is not yet a Content Provider for your Friends database. Android is extremely flexible and allows you to create your own custom Content Providers for your own custom data. In this section you will create a Content Provider that works with your Friends database. This will be the key to access the friend data and eventually display it to the screen. In the next section you will edit the strings.xml file. This file holds some global string content that can be used throughout your Activity.

Editing the strings.xml
First, you will edit the strings.xml file for your project. The strings.xml file is created with each project but you have not used it yet. This file holds static strings that can be used in your Activities. Typically, you will not be able to determine all of the strings that you need to use in your Activity before you even write it. That is, you will usually add entries to strings.xml as you build the Activity. However, because that would break the flow of the book, I am giving you the full contents of the strings.xml file up front. Edit your strings.xml file to look as follows: FindAFriend Delete Add Friend Find Friends Revert Discard Edit location Edit name Create Friend Edit Friend Friends Location Friend Name: OK Error

264

Android: A Programmer’s Guide

Error loading note

With the strings.xml file complete, you need to create a .java file to hold your code. You should call this file FriendsProvider.java. You also need to create another .java file to hold your data definition. Name this file Friends.java, because it will define what a Friends data structure looks like and let your Content Provider access it correctly. (Because the provider will be a class that sits in your project, there is no need to build a corresponding .xml layout file.)

TIP
Technically, your custom Content Provider does not need to reside within the same project or package as the rest of the code for this application. For simplicity’s sake, I am making the Content Provider a class in the FindAFriend project. However, if you plan to create a Content Provider that may be used by multiple projects, create it in a separate package. This will let you call one package when you want to use the Content Provider only.

Let’s start with the Friends.java file. You need to import only two packages for this relatively small class: import android.net.Uri; import android.provider.BaseColumns;

BaseColumns will be implemented by a subclass off of your main Friends class. Name this subclass Friend, because it will represent one friend from the Friends dataset. The following code shows how you should set up the class outline: public final class Friends { public static final class Friend implements BaseColumns { } }

This class will hold some static variables that define each of the columns in your Friends database, the Content URI, and the default sort order for the records.

TIP
A Content URI is used to identify the content that you will handle. This value must be unique.

The strings that you need to define look like this:

Chapter 11:

Application: Find a Friend

265

public static final Uri CONTENT_URI = Uri.parse("content://android_programmers_guide.FindAFriend.Friends/friend"); public static final String DEFAULT_SORT_ORDER = "modified DESC"; public static final String NAME = "name"; public static final String LOCATION = "location"; public static final String CREATED_DATE = "created"; public static final String MODIFIED_DATE = "modified";

With these variables set, the contents of your Friends class come together perfectly. The full file should look like this: package android_programmers_guide.FindAFriend; import android.net.Uri; import android.provider.BaseColumns; public final class Friends { public static final class Friend implements BaseColumns { public static final Uri CONTENT_URI = Uri.parse("content://android_programmers_guide.FindAFriend.Friends/friend"); public static final String DEFAULT_SORT_ORDER = "modified DESC"; public static final String NAME = "name"; public static final String LOCATION = "location"; public static final String CREATED_DATE = "created"; public static final String MODIFIED_DATE = "modified"; } }

In the next section you will create your Content Provider.

Creating Your Content Provider
Using Eclipse, open FriendsProvider.java, which will become the Content Provider for your project. You are going to use this custom Content Provider in your Activity to retrieve data from your Friends database.

266

Android: A Programmer’s Guide

As always, let’s start by looking at the imports for this file. You need to import the Friends class and several other classes: import import import import import import import import import import import android_programmers_guide.FindAFriend.Friends; android.content.*; android.database.Cursor; android.database.SQLException; android.database.sqlite.SQLiteOpenHelper; android.database.sqlite.SQLiteDatabase; android.database.sqlite.SQLiteQueryBuilder; android.net.Uri; android.text.TextUtils; android.util.Log; java.util.HashMap;

As you can see, you are importing several packages here, most of which deal with SQL. I will explain these packages as you use them. The package you will be using first is android.content. To utilize and override the required methods for being a Content Provider, your FriendsProvider class needs to extend ContentProvider. Take a look at the following class outline, which includes several variable definitions that you will use throughout your provider: public class FriendsProvider extends ContentProvider { private SQLiteDatabase mDB; private static final String TAG = "FriendsProvider"; private static final String DATABASE_NAME = "friends"; private static final int DATABASE_VERSION = 2; private static HashMap FRIENDS_PROJECTION_MAP; private static final int FRIENDS = 1; private static final int FRIENDS_ID = 2; private static final UriMatcher URL_MATCHER;}

The Content Provider contains several methods that you will want to override, including onCreate( ), query( ), insert( ), delete( ), and update( ). Because these methods will be called by Activities using your Content Provider, you must override them to specifically access the Friends database. The onCreate( ) method that you will be overriding calls a SQLiteOpenHelper. Therefore, before you can override the onCreate( ) method of the ContentProvider, you have to create a class that extends SQLiteOpenHelper.

Chapter 11:

Application: Find a Friend

267

The code block that follows is a subclass of your Content Provider that extends SQLiteOpenHelper: private static class DatabaseHelper extends SQLiteOpenHelper { @Override public void onCreate(SQLiteDatabase db) { db.execSQL("CREATE TABLE friends (_id INTEGER PRIMARY KEY," + "name TEXT," + "location TEXT," + "created INTEGER," + "modified INTEGER" + ");"); } @Override public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) { Log.w(TAG, "Upgrading database from version " + oldVersion + "to " + newVersion + ", which will destroy all old data"); db.execSQL("DROP TABLE IF EXISTS friends"); onCreate(db); } }

The DatabaseHelper class you just created contains two overridden methods: onCreate( ) and onUpgrade( ). The onCreate( ) method is used when creating the database from code, or in instances where the table definition does not exist.

NOTE
Given that you created the database structure from the adb shell, you will not rely on the onCreate( ) method of DatabaseHelper to establish your database.

With the DatabaseHelper class created, you can now override the onCreate( ) method for your Content Provider:
@Override public boolean onCreate() { DatabaseHelper dbHelper = new DatabaseHelper(); mDB = dbHelper.openDatabase(getContext(), DATABASE_NAME, null, DATABASE_VERSION); return (mDB == null) ? false : true; }

This is a fairly simple method that, in the end, returns a Boolean representing whether or not your database could be opened. You use the SQLiteOpenHelper created in your

268

Android: A Programmer’s Guide

sibling class to open the Friends database. Notice that you pass the database name into the DatabaseHelper class. If the database object—mDB—is not null when it returns, then the database was successfully opened and you can query it. Next, override the query( ) method of the ContentProvider class. This will be the meat of your Content Provider. The query( ) method is called from your Activity through the Content Provider to gather the records from your database. Take a look at the code in the overridden version of the query( ) method:
@Override public Cursor query(Uri url, String[] projection, String selection, String[] selectionArgs, String sort) { SQLiteQueryBuilder qb = new SQLiteQueryBuilder(); switch (URL_MATCHER.match(url)) { case FRIENDS: qb.setTables("friends"); qb.setProjectionMap(FRIENDS_PROJECTION_MAP); break; case FRIENDS_ID: qb.setTables("friends"); qb.appendWhere("_id=" + url.getPathSegments().get(1)); break; default: throw new IllegalArgumentException("Unknown URL " + url); } String orderBy; if (TextUtils.isEmpty(sort)) { orderBy = Friends.Friend.DEFAULT_SORT_ORDER; } else { orderBy = sort; } Cursor c = qb.query(mDB, projection, selection, selectionArgs, null, null, orderBy); c.setNotificationUri(getContext().getContentResolver(), url); return c; }

The query( ) method does a little bit of housekeeping, by checking the validity of the database URL passed into it and defining a query sort order. The URL check is to ensure that you are trying to access only the Friends database. If you are attempting to access a database from another Activity, or from another Content Provider, the query( ) method throws an exception.

Chapter 11:

Application: Find a Friend

269

Toward the end of the method, you perform a query using a SQLiteQueryBuilder. The resulting dataset is assigned to a Cursor using the following line of code:
Cursor c = qb.query(mDB, projection, selection, selectionArgs, null, null, orderBy);

NOTE
A Cursor is a device that allows you to move through records and return information from columns.

The update( ), delete( ), and insert( ) methods are also fairly straightforward in design. Take a look at these three methods, as you should override them:
@Override public Uri insert(Uri url, ContentValues initialValues) { long rowID; ContentValues values; if (initialValues != null) { values = new ContentValues(initialValues); } else { values = new ContentValues(); } if (URL_MATCHER.match(url) != FRIENDS) { throw new IllegalArgumentException("Unknown URL " + url); } Long now = Long.valueOf(System.currentTimeMillis()); Resources r = Resources.getSystem(); if (values.containsKey(Friends.Friend.CREATED_DATE ) == false) { values.put(Friends.Friend.CREATED_DATE, now); } if (values.containsKey(Friends.Friend.MODIFIED_DATE) == false) { values.put(Friends.Friend.MODIFIED_DATE, now); } if (values.containsKey(Friends.Friend.NAME) == false) { values.put(Friends.Friend.NAME, r.getString(android.R.string.untitled)); } if (values.containsKey(Friends.Friend.LOCATION) == false) { values.put(Friends.Friend.LOCATION , ""); }

270

Android: A Programmer’s Guide

rowID = mDB.insert("friends", "friend", values); if (rowID > 0) { Uri uri = ContentUris.withAppendedId(Friends.Friend.CONTENT_URI , rowID); getContext().getContentResolver().notifyChange(uri, null); return uri; } throw new SQLException("Failed to insert row into " + url); } @Override public int delete(Uri url, String where, String[] whereArgs) { int count; long rowId = 0; switch (URL_MATCHER.match(url)) { case FRIENDS: count = mDB.delete("friends", where, whereArgs); break; case FRIENDS_ID: String segment = url.getPathSegments().get(1); rowId = Long.parseLong(segment); count = mDB .delete("friends", "_id=" + segment + (!TextUtils.isEmpty(where) ? " AND (" + where + ')' : ""), whereArgs); break; default: throw new IllegalArgumentException("Unknown URL " + url); } getContext().getContentResolver().notifyChange(url, null); return count; } @Override public int update(Uri url, ContentValues values, String where, String[] whereArgs) { int count; switch (URL_MATCHER.match(url)) { case FRIENDS: count = mDB.update("friends", values, where, whereArgs); break; case FRIENDS_ID: String segment = url.getPathSegments().get(1); count = mDB .update("friends", values, "_id=" + segment

Chapter 11:

Application: Find a Friend

271

+ (!TextUtils.isEmpty(where) ? " AND (" + where + ')' : ""), whereArgs); break; default: throw new IllegalArgumentException("Unknown URL " + url); } getContext().getContentResolver().notifyChange(url, null); return count; }

The code within these methods should be fairly self-explanatory. If you look past the housekeeping that takes place in each method, the core of the code issues a database statement to perform the requested action of updating, deleting, or inserting. The final part of the Content Provider will be a getType( ) method that returns the type of your Friends data. When creating your own type, you should always follow this convention: vnd.android.cursor.dir/vnd. Take a look at the getType( ) method:
@Override public String getType(Uri url) { switch (URL_MATCHER.match(url)) { case FRIENDS: return "vnd.android.cursor.dir/vnd.android_programmers_guide.friend"; case FRIENDS_ID: return "vnd.android.cursor.item/vnd.android_programmers_guide.friend"; default: throw new IllegalArgumentException("Unknown URL " + url); } }

That should complete your new custom Content Provider. Take a look at the completed FriendsProvider code: package android_programmers_guide.FindAFriend; import android_programmers_guide.FindAFriend.Friends; import android.content.*;

272

Android: A Programmer’s Guide

import import import import import import import import import

android.database.Cursor; android.database.SQLException; android.database.sqlite.SQLiteOpenHelper; android.database.sqlite.SQLiteDatabase; android.database.sqlite.SQLiteQueryBuilder; android.net.Uri; android.text.TextUtils; android.util.Log; java.util.HashMap;

public class FriendsProvider extends ContentProvider { private SQLiteDatabase mDB; private static final String TAG = "FriendsProvider"; private static final String DATABASE_NAME = "friends"; private static final int DATABASE_VERSION = 2; private static HashMap FRIENDS_PROJECTION_MAP; private static final int FRIENDS = 1; private static final int FRIENDS_ID = 2; private static final UriMatcher URL_MATCHER; private static class DatabaseHelper extends SQLiteOpenHelper { @Override public void onCreate(SQLiteDatabase db) { db.execSQL("CREATE TABLE friends (_id INTEGER PRIMARY KEY," + "name TEXT," + "location TEXT," + "created INTEGER," + "modified INTEGER" + ");"); } @Override public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) { Log.w(TAG, "Upgrading database from version " + oldVersion + "to " + newVersion + ", which will destroy all old data"); db.execSQL("DROP TABLE IF EXISTS friends"); onCreate(db); } } @Override public boolean onCreate() { DatabaseHelper dbHelper = new DatabaseHelper(); mDB = dbHelper.openDatabase(getContext(), DATABASE_NAME, null, DATABASE_VERSION); return (mDB == null) ? false : true; }

Chapter 11:

Application: Find a Friend

273

@Override public Cursor query(Uri url, String[] projection, String selection, String[] selectionArgs, String sort) { SQLiteQueryBuilder qb = new SQLiteQueryBuilder(); switch (URL_MATCHER.match(url)) { case FRIENDS: qb.setTables("friends"); qb.setProjectionMap(FRIENDS_PROJECTION_MAP); break; case FRIENDS_ID: qb.setTables("friends"); qb.appendWhere("_id=" + url.getPathSegments().get(1)); break; default: throw new IllegalArgumentException("Unknown URL " + url); } String orderBy; if (TextUtils.isEmpty(sort)) { orderBy = Friends.Friend.DEFAULT_SORT_ORDER; } else { orderBy = sort; } Cursor c = qb.query(mDB, projection, selection, selectionArgs, null, null, orderBy); c.setNotificationUri(getContext().getContentResolver(), url); return c; } @Override public String getType(Uri url) { switch (URL_MATCHER.match(url)) { case FRIENDS: return "vnd.android.cursor.dir/vnd.android_programmers_guide.friend"; case FRIENDS_ID: return "vnd.android.cursor.item/vnd.android_programmers_guide.friend"; default: throw new IllegalArgumentException("Unknown URL " + url); } } @Override

274

Android: A Programmer’s Guide

public Uri insert(Uri url, ContentValues initialValues) { long rowID; ContentValues values; if (initialValues != null) { values = new ContentValues(initialValues); } else { values = new ContentValues(); } if (URL_MATCHER.match(url) != FRIENDS) { throw new IllegalArgumentException("Unknown URL " + url); } Long now = Long.valueOf(System.currentTimeMillis()); Resources r = Resources.getSystem(); if (values.containsKey(Friends.Friend.CREATED_DATE ) == false) { values.put(Friends.Friend.CREATED_DATE, now); } if (values.containsKey(Friends.Friend.MODIFIED_DATE) == false) { values.put(Friends.Friend.MODIFIED_DATE, now); } if (values.containsKey(Friends.Friend.NAME) == false) { values.put(Friends.Friend.NAME, r.getString(android.R.string.untitled)); } if (values.containsKey(Friends.Friend.LOCATION) == false) { values.put(Friends.Friend.LOCATION , ""); } rowID = mDB.insert("friends", "friend", values); if (rowID > 0) { Uri uri = ContentUris.withAppendedId(Friends.Friend.CONTENT_URI , rowID); getContext().getContentResolver().notifyChange(uri, null); return uri; } throw new SQLException("Failed to insert row into " + url); } @Override public int delete(Uri url, String where, String[] whereArgs) { int count; long rowId = 0; switch (URL_MATCHER.match(url)) { case FRIENDS:

Chapter 11:

Application: Find a Friend

275

count = mDB.delete("friends", where, whereArgs); break; case FRIENDS_ID: String segment = url.getPathSegments().get(1); rowId = Long.parseLong(segment); count = mDB .delete("friends", "_id=" + segment + (!TextUtils.isEmpty(where) ? " AND (" + where + ')' : ""), whereArgs); break; default: throw new IllegalArgumentException("Unknown URL " + url); } getContext().getContentResolver().notifyChange(url, null); return count; } @Override public int update(Uri url, ContentValues values, String where, String[] whereArgs) { int count; switch (URL_MATCHER.match(url)) { case FRIENDS: count = mDB.update("friends", values, where, whereArgs); break; case FRIENDS_ID: String segment = url.getPathSegments().get(1); count = mDB .update("friends", values, "_id=" + segment + (!TextUtils.isEmpty(where) ? " AND (" + where + ')' : ""), whereArgs); break; default: throw new IllegalArgumentException("Unknown URL " + url); } getContext().getContentResolver().notifyChange(url, null); return count; } static { URL_MATCHER = new UriMatcher(UriMatcher.NO_MATCH); URL_MATCHER.addURI("android_programmers_guide.FindAFriend.Friends", "friend", FRIENDS);

276

Android: A Programmer’s Guide

URL_MATCHER.addURI("android_programmers_guide.FindAFriend.Friends", "friend/#", FRIENDS_ID); FRIENDS_PROJECTION_MAP = new HashMap(); FRIENDS_PROJECTION_MAP.put(Friends.Friend._ID, "_id"); FRIENDS_PROJECTION_MAP.put(Friends.Friend.NAME, "name"); FRIENDS_PROJECTION_MAP.put(Friends.Friend.LOCATION, "location"); FRIENDS_PROJECTION_MAP.put(Friends.Friend.CREATED_DATE, "created"); FRIENDS_PROJECTION_MAP.put(Friends.Friend.MODIFIED_DATE, "modified"); } }

With the underlying data elements now created (the database, definitions, and Content Provider), you can begin to build the surrounding Activity. Remember, this activity will use the data in your database, display it to a list, and then allow the user to launch another Activity that places database items on a Google Maps Overlay. In the following section, you will build both Activities and complete your FindAFriend application.

Creating the FindAFriend Activity
If you have taken the time to run Google’s NotePad demo, then you will be very familiar with the layout of this Activity. You will be modifying the NotePad interface to work with your Friends database and Google Maps. The FindAFriend Activity will interact with several smaller Activities: NameEditor, LocationEditor, and FriendsMap. You will build all of these Activities in the coming sections.

NOTE
In addition to NotePad, Google provides several very well-written demo Activities that outline basic techniques for multiple programming situations.

As you have done with past Activity projects from this book, start with the AndroidManifest.xml file. Being a fairly complex application, you need to make multiple changes to AndroidManifest.xml.

Editing AndroidManifest.xml
Take a look at the following AndroidManifest.xml file for the FindAFriend project. You need to add several Intent Filters for new Activities, including ones to edit a friend’s location, edit a friend’s name, and launch your Google Map. Also, pay close attention to the actions within each Intent Filter. These represent actions that will be passed to each Activity handling that Intent. Finally, do not forget

Chapter 11:

Application: Find a Friend

277

to add Access_Location and Access_GPS permission so that you can add your current location to the map as well. The full AndroidManifest.xml file should appear as follows:

278

Android: A Programmer’s Guide

In the next section, you will create the first Activity for this project—NameEditor. As the name implies, this Activity will be launched when the user wishes to edit the name of a friend.

Creating the NameEditor Activity
In this section, you will create the NameEditor Activity for the FindAFriend project. This Activity will be launched from a menu item on the main FindAFriend Activity (which you have not created yet). The purpose of the NameEditor Activity will be to modify the name field of a Friend record. Add a name_editor.xml layout file and a corresponding NameEditor.java file to your application. You will edit these files to create your Activity. First, edit name_editor.xml to create the layout for the Activity. The Activity will hold one EditText and one Button. The EditText will allow you to modify the name field, and the Button will write the results and exit. If you followed this book from the beginning, you have added quite a few View layouts to XML files. Therefore, I can spare you the details of each addition individually. The full name_editor.xml file should appear as follows:

Chapter 11:

Application: Find a Friend

279

Now, edit NameEditor.java and begin building your code. You need to import your Friends class from the previous sections and import the Cursor package to help you work with the database records: import import import import import import import android.app.Activity; android.database.Cursor; android.net.Uri; android.os.Bundle; android.view.View; android.widget.Button; android.widget.EditText;

You should establish your Activity so that you implement the View.OnClickListener( ). This will let you override the OnClickListener( ) methods in your Activity. This code sample shows the outline of your NameEditor class with some variable definitions that you will need: public class NameEditor extends Activity implements View.OnClickListener { public static final String EDIT_NAME_ACTION = "android_programmers_guide.FindAFriend.action.EDIT_NAME";

280

Android: A Programmer’s Guide

private static final int NAME_INDEX = 1; private static final String[] PROJECTION = new String[] { Friends.Friend._ID, Friends.Friend.NAME, }; Cursor mCursor; EditText mText; }

Next, you need to override some methods, starting with onCreate( ). You have seen this method overridden in other chapters. Typically, it holds all the code that should be executed when the Activity is created. public void onCreate(Bundle icicle) { super.onCreate(icicle); setContentView(R.layout.name_editor); Uri uri = getIntent().getData(); mCursor = managedQuery(uri, PROJECTION, null, null); mText = (EditText) this.findViewById(R.id.name); mText.setOnClickListener(this); Button b = (Button) findViewById(R.id.ok); b.setOnClickListener(this); }

Notice that, in the previous code sample, you assign layouts to their respective Views and initiate some of your variables. However, you may be wondering where the data is for the name field. That is, you have created a cursor, but you have not retrieved anything from it. You will use the onResume( ) method for that. The two methods that you will override next, onResume( ) and onPause( ), will do the work of reading from and writing to the database, respectively. Within the Android life cycle, onResume( ) is called when an Activity is open and on the top of the focus. onPause( ) is called when an Activity is being closed but before focus is handed to another Activity. Override your onResume( ) method to read the database and retrieve the name field: protected void onResume() { super.onResume();

Chapter 11:

Application: Find a Friend

281

if (mCursor != null) { mCursor.first(); String title = mCursor.getString(NAME_INDEX); mText.setText(title); } }

In this method, you move the Cursor to its first record, read the name field from it using the index assigned earlier, and set the EditText to the contents of the name field. This automatically populates the field with the current record’s name value. Next, modify the onPause( ) method to write the contents of the EditText back to the database: protected void onPause() { super.onPause(); if (mCursor != null) { String title = mText.getText().toString(); mCursor.updateString(NAME_INDEX, title); mCursor.commitUpdates(); } }

Finally, call the Activity method finish( ) from the onClick handler. This will clean up and close your Activity. The finished NameEditor.java file should look like this: package android_programmers_guide.FindAFriend; import import import import import import import import android_programmers_guide.FindAFriend.Friends; android.app.Activity; android.database.Cursor; android.net.Uri; android.os.Bundle; android.view.View; android.widget.Button; android.widget.EditText;

public class NameEditor extends Activity implements View.OnClickListener { public static final String EDIT_NAME_ACTION = "android_programmers_guide.FindAFriend.action.EDIT_NAME"; private static final int NAME_INDEX = 1; private static final String[] PROJECTION = new String[] { Friends.Friend._ID,

282

Android: A Programmer’s Guide

Friends.Friend.NAME, }; Cursor mCursor; EditText mText; @Override public void onCreate(Bundle icicle) { super.onCreate(icicle); setContentView(R.layout.name_editor); Uri uri = getIntent().getData(); mCursor = managedQuery(uri, PROJECTION, null, null); mText = (EditText) this.findViewById(R.id.name); mText.setOnClickListener(this); Button b = (Button) findViewById(R.id.ok); b.setOnClickListener(this); } @Override protected void onResume() { super.onResume(); if (mCursor != null) { mCursor.first(); String title = mCursor.getString(NAME_INDEX); mText.setText(title); } } @Override protected void onPause() { super.onPause(); if (mCursor != null) { String title = mText.getText().toString(); mCursor.updateString(NAME_INDEX, title); mCursor.commitUpdates(); } } public void onClick(View v) { finish(); } }

Chapter 11:

Application: Find a Friend

283

At this point, you can edit name values in the Friends database. However, there are two fields of importance in the database, name and location. In the next section, you will create an editor for the location field.

Creating the LocationEditor Activity
In this section, you will create an editor for the location field of the Friends database. You are going to make this Activity slightly different from the NameEditor Activity. Therefore, the code will be different and follow a slightly unfamiliar process. If you explored the Google demo NotePad, you should have noticed that the “notes” editor is a white screen with a dynamically drawn line on it that repeats itself as needed. This effect is performed using a custom View. You are going to use this same custom View for the LocationEditor.

location_editor.xml
The first step is to create location_editor.xml and LocationEditor.java files for the layout and code, respectively. The layout file should contain a call to the custom View layout. The full layout is as follows:

The LocationEditor will also contain a menu system that will allow the user to discard, delete, or revert any changes they make. This will be a pretty complex Activity. Therefore, it is best to start at the beginning, the imports section of the LocationEditor.java.

LocationEditor.java
Take a look at the following imports for this Activity, many of which deal with drawing the custom View on the screen: import android.app.Activity; import android.content.ComponentName;

284

Android: A Programmer’s Guide

import import import import import import import import import import import import

android.content.Context; android.content.Intent; android.database.Cursor; android.graphics.Canvas; android.graphics.Paint; android.graphics.Rect; android.net.Uri; android.os.Bundle; android.util.AttributeSet; android.view.Menu; android.widget.EditText; java.util.Map;

Next, set up your Activity’s main class outline. There are a number of variables that you need to define for use throughout the LocationEditor: public class LocationEditor extends Activity { private static final String TAG = "Friends"; private static final int FRIEND_INDEX = 1; private static final int NAME_INDEX = 2; private static final int MODIFIED_INDEX = 3; private static final String[] PROJECTION = new String[] { Friends.Friend._ID, // 0 Friends.Friend.LOCATION, // 1 Friends.Friend.NAME, // 2 Friends.Friend.MODIFIED_DATE // 3 }; private static final String ORIGINAL_CONTENT = "origContent"; private static final int REVERT_ID = Menu.FIRST; private static final int DISCARD_ID = Menu.FIRST + 1; private static final int DELETE_ID = Menu.FIRST + 2; private static final int STATE_EDIT = 0; private static final int STATE_INSERT = 1; private private private private int mState; boolean mNoteOnly = false; Uri mURI; Cursor mCursor;

Chapter 11:

Application: Find a Friend

285

private EditText mText; private String mOriginalContent; }

Having performed the tasks in the previous sections of this chapter, the variable definitions here should be rather self-explanatory. The next piece of code shows a subclass that you need to create. This subclass will draw to the screen the EditText that will be used for the LocationEditor. You are breaking this out so that you can call it as needed from the Activity. Keep in mind that you will dynamically draw a new EditText on the screen as is needed by the user. Pay special attention to the onDraw class that you need to override. public static class MyEditText extends EditText { private Rect mRect; private Paint mPaint; public MyEditText(Context context, AttributeSet attrs, Map params) { super(context, attrs, params); mRect = new Rect(); mPaint = new Paint(); mPaint.setStyle(Paint.Style.STROKE); mPaint.setColor(0xFF0000FF); } @Override protected void onDraw(Canvas canvas) { int count = getLineCount(); Rect r = mRect; Paint paint = mPaint; for (int i = 0; i < count; i++) { int baseline = getLineBounds(i, r); canvas.drawLine(r.left, baseline + 1, r.right, baseline + 1, paint); } super.onDraw(canvas); } }

Again, while this may look like a lot of code, there should be nothing foreign about it. This subclass simply draws a new EditText as needed to the screen.

286

Android: A Programmer’s Guide

Just as with the NameEditor, you will use the onResume( ) and onPause( ) methods to do your database work. Take a look at the code for each below: protected void onResume() { super.onResume(); if (mCursor != null) { mCursor.first(); if (mState == STATE_EDIT) { setTitle(getText(R.string.title_edit)); } else if (mState == STATE_INSERT) { setTitle(getText(R.string.title_create)); } String note = mCursor.getString(FRIEND_INDEX); mText.setTextKeepState(note); if (mOriginalContent == null) { mOriginalContent = note; } } else { setTitle(getText(R.string.error_title)); mText.setText(getText(R.string.error_message)); } } protected void onPause() { super.onPause(); if (mCursor != null) { String text = mText.getText().toString(); int length = text.length(); if (isFinishing() && (length == 0) && !mNoteOnly) { setResult(RESULT_CANCELED); deleteFriend(); } else { if (!mNoteOnly) { mCursor.updateLong(MODIFIED_INDEX, System.currentTimeMillis()); if (mState == STATE_INSERT) { String title = text.substring(0, Math.min(30, length));

Chapter 11:

Application: Find a Friend

287

if (length > 30) { int lastSpace = title.lastIndexOf(' '); if (lastSpace > 0) { title = title.substring(0, lastSpace); } } mCursor.updateString(NAME_INDEX, title); } } mCursor.updateString(FRIEND_INDEX, text); managedCommitUpdates(mCursor); } } }

Much like in the NameEditor, you read from the database during onResume( ) and write back to it during onPause( ). The one added feature that appears in LocationEditor as opposed to NameEditor is that you are also writing out the modified dates when you make a change. Finally, you need two methods for canceling changes and deleting friends. These methods will be called from the menu system: private final void cancelFriend() { if (mCursor != null) { if (mState == STATE_EDIT) { mCursor.updateString(FRIEND_INDEX, mOriginalContent); mCursor.commitUpdates(); mCursor.deactivate(); mCursor = null; } else if (mState == STATE_INSERT) { deleteFriend(); } } setResult(RESULT_CANCELED); finish(); } private final void deleteFriend() { if (mCursor != null) { mText.setText(""); mCursor.deleteRow(); mCursor.deactivate();

288

Android: A Programmer’s Guide

mCursor = null; } }

Given that you learned about creating menu systems in Chapter 8, simply examine the full LocationEditor.java file to see how all of these methods and subclasses work together: package android_programmers_guide.FindAFriend;

import import import import import import import import import import import import import import

android.app.Activity; android.content.ComponentName; android.content.Context; android.content.Intent; android.database.Cursor; android.graphics.Canvas; android.graphics.Paint; android.graphics.Rect; android.net.Uri; android.os.Bundle; android.util.AttributeSet; android.view.Menu; android.widget.EditText; java.util.Map;

public class LocationEditor extends Activity { private static final String TAG = "Friends"; private static final int FRIEND_INDEX = 1; private static final int NAME_INDEX = 2; private static final int MODIFIED_INDEX = 3; private static final String[] PROJECTION = new String[] { Friends.Friend._ID, // 0 Friends.Friend.LOCATION, // 1 Friends.Friend.NAME, // 2 Friends.Friend.MODIFIED_DATE // 3 }; private static final String ORIGINAL_CONTENT = "origContent"; private static final int REVERT_ID = Menu.FIRST; private static final int DISCARD_ID = Menu.FIRST + 1; private static final int DELETE_ID = Menu.FIRST + 2; private static final int STATE_EDIT = 0; private static final int STATE_INSERT = 1; private int mState;

Chapter 11:

Application: Find a Friend

289

private private private private private

boolean mNoteOnly = false; Uri mURI; Cursor mCursor; EditText mText; String mOriginalContent;

public static class MyEditText extends EditText { private Rect mRect; private Paint mPaint; public MyEditText(Context context, AttributeSet attrs, Map params) { super(context, attrs, params); mRect = new Rect(); mPaint = new Paint(); mPaint.setStyle(Paint.Style.STROKE); mPaint.setColor(0xFF0000FF); } @Override protected void onDraw(Canvas canvas) { int count = getLineCount(); Rect r = mRect; Paint paint = mPaint; for (int i = 0; i < count; i++) { int baseline = getLineBounds(i, r); canvas.drawLine(r.left, baseline + 1, r.right, baseline + 1, paint); } super.onDraw(canvas); } } @Override protected void onCreate(Bundle icicle) { super.onCreate(icicle); final Intent intent = getIntent(); final String type = intent.resolveType(this); final String action = intent.getAction(); if (action.equals(Intent.EDIT_ACTION)) { mState = STATE_EDIT; mURI = intent.getData(); } else if (action.equals(Intent.INSERT_ACTION)) { mState = STATE_INSERT;

290

Android: A Programmer’s Guide

mURI = getContentResolver().insert(intent.getData(), null); if (mURI == null) {

finish(); return; } setResult(RESULT_OK, mURI.toString()); } else { finish(); return; } setContentView(R.layout.location_editor); mText = (EditText) findViewById(R.id.location); mCursor = managedQuery(mURI, PROJECTION, null, null); if (icicle != null) { mOriginalContent = icicle.getString(ORIGINAL_CONTENT); } }

@Override protected void onResume() { super.onResume(); if (mCursor != null) { mCursor.first(); if (mState == STATE_EDIT) { setTitle(getText(R.string.title_edit)); } else if (mState == STATE_INSERT) { setTitle(getText(R.string.title_create)); } String note = mCursor.getString(FRIEND_INDEX); mText.setTextKeepState(note); if (mOriginalContent == null) { mOriginalContent = note; } } else { setTitle(getText(R.string.error_title)); mText.setText(getText(R.string.error_message)); } }

Chapter 11:

Application: Find a Friend

291

@Override protected void onFreeze(Bundle outState) { outState.putString(ORIGINAL_CONTENT, mOriginalContent); } @Override protected void onPause() { super.onPause(); if (mCursor != null) { String text = mText.getText().toString(); int length = text.length(); if (isFinishing() && (length == 0) && !mNoteOnly) { setResult(RESULT_CANCELED); deleteFriend(); } else { if (!mNoteOnly) { mCursor.updateLong(MODIFIED_INDEX, System.currentTimeMillis()); if (mState == STATE_INSERT) { String title = text.substring(0, Math.min(30, length)); if (length > 30) { int lastSpace = title.lastIndexOf(' '); if (lastSpace > 0) { title = title.substring(0, lastSpace); } } mCursor.updateString(NAME_INDEX, title); } } mCursor.updateString(FRIEND_INDEX, text); managedCommitUpdates(mCursor); } } } @Override public boolean onCreateOptionsMenu(Menu menu) { super.onCreateOptionsMenu(menu); if (mState == STATE_EDIT) { menu.add(0, REVERT_ID, R.string.menu_revert).setShortcut('0', 'r'); if (!mNoteOnly) { menu.add(0, DELETE_ID, R.string.menu_delete).setShortcut('1', 'd'); }

292

Android: A Programmer’s Guide

} else { menu.add(0, DISCARD_ID, R.string.menu_discard).setShortcut('0', 'd'); } if (!mNoteOnly) { Intent intent = new Intent(null, getIntent().getData()); intent.addCategory(Intent.ALTERNATIVE_CATEGORY); menu.addIntentOptions( Menu.ALTERNATIVE, 0, new ComponentName(this, LocationEditor.class), null, intent, 0, null); } return true; } @Override public boolean onOptionsItemSelected(Menu.Item item) { switch (item.getId()) { case DELETE_ID: deleteFriend(); finish(); break; case DISCARD_ID: cancelFriend(); break; case REVERT_ID: cancelFriend(); break; } return super.onOptionsItemSelected(item); } private final void cancelFriend() { if (mCursor != null) { if (mState == STATE_EDIT) { mCursor.updateString(FRIEND_INDEX, mOriginalContent); mCursor.commitUpdates(); mCursor.deactivate(); mCursor = null; } else if (mState == STATE_INSERT) { deleteFriend(); } } setResult(RESULT_CANCELED); finish(); } private final void deleteFriend() { if (mCursor != null) { mText.setText("");

Chapter 11:

Application: Find a Friend

293

mCursor.deleteRow(); mCursor.deactivate(); mCursor = null; } } }

In the next section, you will create the Activity that will draw your Google Maps Overlay. The FriendsMap activity will read the full recordset of friends from the Friends database and write each to the Overlay.

Creating the FriendsMap Activity
The FriendsMap Activity is the final Activity that will be callable from the main application. This Activity will call your recordset from the Friends database and draw a circle on a Google Map for each friend. The Activity will also draw a circle for you at your current location. You need to begin by adding two new files to your project, friendsmap.xml and FriendsMap.java. Because you have seen the layout for the friendsmap.xml file in Chapter 9, there is no need to fully explain it here. You are using a RelativeLayout to place four Buttons over a Google Map. The full friendsmap.xml file should look like this:

Because you have seen the overwhelming majority of the FriendsMap.java file in Chapter 9 as well, I will not go over every little detail. However, there is one method that should be explained. You will create a method called LoadFriends( ) that will access the database, read the records, and draw the Overlay. Take a look at the LoadFriends( ) code that follows. Notice that you open the database, match and parse the location field, create a point from the latitude and longitude in the location field, and draw that point to the Overlay. The last thing the method does is to grab your coordinates from the GPS and draw them to the Overlay with the label “ME”. public void LoadFriends(MapView mv, MapController mc, Cursor c){ Point myLocation = null; Double latPoint = null; Double lngPoint = null; c.first(); do{ if (c.getString(c.getColumnIndex("location")) != null) { final String geoPattern = "(geo:[\\-]?[0-9]{1,3}\\.[0 9]{1,6}\\,[\\-]?[0-9]{1,3}\\.[0-9]{1,6}\\#)"; Pattern pattern = Pattern.compile(geoPattern); CharSequence inputStr = c.getString(c.getColumnIndex("location")); Matcher matcher = Pattern.matcher(inputStr); boolean matchFound = matcher.find(); if (matchFound) { String groupStr = matcher.group(0); latPoint = Double.valueOf(groupStr.substring(groupStr.indexOf(":") + 1, groupStr.indexOf(","))) ; lngPoint = Double.valueOf(groupStr.substring(groupStr.indexOf(",") + 1, groupStr.indexOf("#"))) ; Point friendLocation = new Point(latPoint.intValue(),lngPoint.intValue());

Chapter 11:

Application: Find a Friend

295

drawFriendsOverlay.addNewFriend(c.getString(c.getColumnIndex("name")), friendLocation); } } }while(c.next()); LocationManager myManager = (LocationManager) getSystemService(Context.LOCATION_SERVICE); Double myLatPoint = myManager.getCurrentLocation("gps").getLatitude()*1E6; Double myLngPoint = myManager.getCurrentLocation("gps").getLongitude()*1E6; myLocation = new Point(myLatPoint.intValue(),myLngPoint.intValue()); drawFriendsOverlay.addNewFriend("Me", myLocation); mc.centerMapTo(myLocation, false); mc.zoomTo(9); mv = null; }

The remainder of the FriendsMap.java file operates the zoom and toggle buttons, as introduced in Chapter 10: package android_programmers_guide.FindAFriend;

import import import import import import import import import import import import import import import import import import

android.os.Bundle; android.location.LocationManager; android.view.View; android.content.Context; android.content.Intent; android.database.Cursor; android.widget.Button; java.util.regex.Pattern; java.util.regex.Matcher; android.graphics.Canvas; android.graphics.RectF; android.graphics.Paint; com.google.android.maps.MapActivity; com.google.android.maps.MapView; com.google.android.maps.Point; com.google.android.maps.MapController; com.google.android.maps.Overlay; com.google.android.maps.OverlayController;

public class FriendsMap extends MapActivity {

private static final String[] PROJECTION = new String[] { Friends.Friend.NAME, Friends.Friend.LOCATION}; public Cursor mCursor;

296

Android: A Programmer’s Guide

DrawFriendsOverlay drawFriendsOverlay = new DrawFriendsOverlay(); @Override public void onCreate(Bundle icicle) { super.onCreate(icicle); setContentView(R.layout.friendsmap); Intent intent = getIntent(); if (intent.getData() == null) { intent.setData(Friends.Friend.CONTENT_URI); } mCursor = managedQuery(getIntent().getData(), PROJECTION, null,null); final MapView myMap = (MapView) findViewById(R.id.myMap); final MapController myMapController = myMap.getController(); LoadFriends(myMap, myMapController, mCursor); OverlayController myOverlayController = myMap.createOverlayController(); myOverlayController.add(drawFriendsOverlay, true); final Button zoomIn = (Button) findViewById(R.id.buttonZoomIn); zoomIn.setOnClickListener(new Button.OnClickListener() { public void onClick(View v){ ZoomIn(myMap,myMapController); }}); final Button zoomOut = (Button) findViewById(R.id.buttonZoomOut); zoomOut.setOnClickListener(new Button.OnClickListener() { public void onClick(View v){ ZoomOut(myMap,myMapController); }}); final Button viewMap = (Button) findViewById(R.id.buttonMapView); viewMap.setOnClickListener(new Button.OnClickListener() { public void onClick(View v){ ShowMap(myMap,myMapController); }}); final Button viewSat = (Button) findViewById(R.id.buttonSatView); viewSat.setOnClickListener(new Button.OnClickListener() { public void onClick(View v){ ShowSat(myMap,myMapController); }}); } public void LoadFriends(MapView mv, MapController mc, Cursor c){ Point myLocation = null; Double latPoint = null; Double lngPoint = null; c.first(); do{ if (c.getString(c.getColumnIndex("location")) != null) { final String geoPattern = "(geo:[\\-]?[0-9]{1,3}\\.[0 9]{1,6}\\,[\\-]?[0-9]{1,3}\\.[0-9]{1,6}\\#)"; Pattern pattern = Pattern.compile(geoPattern);

Chapter 11:

Application: Find a Friend

297

CharSequence inputStr = c.getString(c.getColumnIndex("location")); Matcher matcher = pattern.matcher(inputStr); boolean matchFound = matcher.find(); if (matchFound) { String groupStr = matcher.group(0); latPoint = Double.valueOf(groupStr.substring(groupStr.indexOf(":") + 1, groupStr.indexOf(","))) ; lngPoint = Double.valueOf(groupStr.substring(groupStr.indexOf(",") + 1, groupStr.indexOf("#"))) ; Point friendLocation = new Point(latPoint.intValue(),lngPoint.intValue()); drawFriendsOverlay.addNewFriend(c.getString(c.getColumnIndex("name")), friendLocation); } } }while(c.next()); LocationManager myManager = (LocationManager) getSystemService(Context.LOCATION_SERVICE); Double myLatPoint = myManager.getCurrentLocation("gps").getLatitude()*1E6; Double myLngPoint = myManager.getCurrentLocation("gps").getLongitude()*1E6; myLocation = new Point(myLatPoint.intValue(),myLngPoint.intValue()); drawFriendsOverlay.addNewFriend("Me", myLocation); mc.centerMapTo(myLocation, false); mc.zoomTo(9); mv = null; } public void ZoomIn(MapView mv, MapController mc){ if(mv.getZoomLevel()!=21){ mc.zoomTo(mv.getZoomLevel()+ 1); } } public void ZoomOut(MapView mv, MapController mc){ if(mv.getZoomLevel()!=1){ mc.zoomTo(mv.getZoomLevel()- 1); } } public void ShowMap(MapView mv, MapController mc){ if (mv.isSatellite()){ mv.toggleSatellite(); } } public void ShowSat(MapView mv, MapController mc){ if (!mv.isSatellite()){

298

Android: A Programmer’s Guide

mv.toggleSatellite(); } } protected class DrawFriendsOverlay extends Overlay{ public String[] friendName = new String[0]; public Point[] friendPoint = new Point[0]; final Paint paint = new Paint(); @Override public void draw(Canvas canvas, PixelCalculator calculator, Boolean shadow){ for(int x=0;x 0; if (haveItems) { Uri uri = ContentUris.withAppendedId(getIntent().getData(), getSelectedItemId()); Intent[] specifics = new Intent[1]; specifics[0] = new Intent(Intent.EDIT_ACTION, uri); Menu.Item[] items = new Menu.Item[1]; Intent intent = new Intent(null, uri); intent.addCategory(Intent.SELECTED_ALTERNATIVE_CATEGORY); menu.addIntentOptions(Menu.SELECTED_ALTERNATIVE, 0, null, specifics, intent, 0, items); menu.add(Menu.SELECTED_ALTERNATIVE, DELETE_ID, R.string.menu_delete) .setShortcut('2', 'd'); menu.add(Menu.SELECTED_ALTERNATIVE, FIND_FRIENDS, R.string.find_friends).setShortcut('4', 'f'); if (items[0] != null) { items[0].setShortcut('1', 'e'); } } else { menu.removeGroup(Menu.SELECTED_ALTERNATIVE); } menu.setItemShown(DELETE_ID, haveItems); return true; } @Override public boolean onOptionsItemSelected(Menu.Item item) { switch (item.getId()) { case DELETE_ID: deleteItem();

302

Android: A Programmer’s Guide

return true; case INSERT_ID: insertItem(); return true; case FIND_FRIENDS: Intent findfriends = new Intent(this, FriendsMap.class); startActivity(findfriends); return true; } return super.onOptionsItemSelected(item); } @Override protected void onListItemClick(ListView l, View v, int position, long id) { Uri url = ContentUris.withAppendedId(getIntent().getData(), id); String action = getIntent().getAction(); if (Intent.PICK_ACTION.equals(action) || Intent.GET_CONTENT_ACTION.equals(action)) { setResult(RESULT_OK, url.toString()); } else { startActivity(new Intent(Intent.EDIT_ACTION, url)); } } private final void deleteItem() { mCursor.moveTo(getSelectedItemPosition()); mCursor.deleteRow(); } private final void insertItem() { startActivity(new Intent(Intent.INSERT_ACTION, getIntent().getData())); } }

While this was the longest Activity that you have created in this book, it should still be noted that the relative amount of programming needed to do what you did is fairly small. Next, run this Activity and see the result of all your work.

Running the FindAFriend Activity
Run the FindAFriend Activity in the Android Emulator. You should be greeted with an empty list, as shown in the following illustration. To add your first friend, click the Menu button and select the Add Friend option.

Chapter 11:

Application: Find a Friend

303

This option launches the custom View you created. Enter a friend’s name on the line provided, as shown here, and return to the main Activity by clicking the back arrow on the Emulator.

304

Android: A Programmer’s Guide

You should now have a friend’s name in the ListView. Click the Menu button again; you clearly have more options now, as shown in this illustration.

Select the Edit Location option. This should bring up your custom control yet again. Enter a coordinate-based location, as shown here.

Chapter 11:

Application: Find a Friend

305

Finally, return to the main Activity and select the Find Friends option. This should clearly map out your current location in San Francisco and your friend’s location off the coast of Africa, respectively.

Try This

Real-Time Location Updating

Try modifying the FindAFriend application to update the “ME” marker as you move. This should be fairly easy to do using the update( ) method.

Chapter 12, the final chapter, provides a reference to some of the Android SDK options, such as the adb commands and the Android Emulator options.

306

Android: A Programmer’s Guide

Ask the Expert
Q: A: Q: A:
Can a SQLite database be created in code? Yes. However, for the purposes of giving a well-rounded tutorial on Android, I chose to give an example of manually creating the database. Feel free to modify this project to include an in-code database-creation method in the FriendsProvider Content Provider. Do you need to have a separate class that implements BaseColumns? No. You can define the items from the Friends class (in this chapter’s example) directly in the calling class. However, if you are creating a Content Provider that will be implemented by other developers who may not know the underlying data structure, you will want to provide a defining class.

Chapter

12

Android SDK Tool Reference

Copyright © 2008 by The McGraw-Hill Companies. Click here for terms of use.

308

Android: A Programmer’s Guide

T

his chapter provides a valuable reference to some of the Android SDK tools that you have used over the course of this book. It gives you some of the command-line options that you can use with the Android Emulator and the Android Debugging Bridge.

Android Emulator Commands
The following table contains a list of the most common Android Emulator commands. These are the commands that were available as of the March 2008 SDK release. A short description is provided with each command. Emulator Command emulator -console emulator -data emulator -debug-kernel emulator -flash-keys emulator -help emulator -http-proxy emulator -image emulator -kernel emulator -logcat emulator -mic emulator -netdelay

Function
Enables the console shell on the current terminal Uses a different file as the working user-data disk image Sends kernel output to the console Flashes keypresses on the device skin Prints a list of all Emulator commands Makes all TCP connections through a specified HTTP/HTTPS proxy Uses as the system image Uses as the emulated kernel Enables logcat output with given tags Uses device or WAV file for audio input Sets network latency emulation to . (The parameter simulates the delay experienced on specific types of networks.) The s you can use are as follows: ● Gprs ● Edge ● Umts ● None ● ● : Shortcut for -netspeed full -netdelay none

emulator -netfast

Chapter 12:

Android SDK Tool Reference

309

Emulator Command emulator -netspeed

Function
Sets network speed emulation to . (The parameter simulates the data speed experienced on specific types of networks.) The s you can use are as follows: ● Gsm ● Hscsd ● Gprs ● Edge ● Umts ● Hsdpa ● Full ● ● : Disables Android audio support Disables JNI checks in the Dalvik virtual machine Specifies not to use any Emulator skin Uses overlay image over screen Specifies onion skin translucency value (as percent) Passes arguments to QEMU Displays QEMU help Redirects the radio modem interface to a host character device Uses as the ramdisk image Disables Unicode keyboard reverse mapping Uses as the SD Memory Card image Starts the Emulator with the specified skin: ● HVGA-L 480x320, landscape ● HVGA-P 320x480, portrait (default) ● QVGA-L 320x240, landscape ● QVGA-P 240x320, portrait Searches for Emulator skins in Searches system, ramdisk, and user-data disk images in Enables code profiling (press F9 to start), written to a specified file

emulator -noaudio emulator -nojni emulator -noskin emulator -onion emulator -onion-alpha emulator -qemu emulator -qemu -h emulator -radio emulator -ramdisk emulator -raw-keys emulator -sdcard emulator -skin

emulator -skindir emulator -system emulator -trace

310

Android: A Programmer’s Guide

Emulator Command emulator -useaudio emulator -verbose emulator -verbose-keys emulator -verbose-proxy emulator -wipe-data

Function
Enables Android audio support Enables verbose output Enables verbose keypress messages Enables verbose proxy debug messages Deletes all data on the user-data disk image (see emulator –data ) before starting

Android Debug Bridge Commands
The following commands are gsm commands. You access them by connecting to the Emulator’s terminal console. If you do not know the port terminal console, it is one less than the debug port. Execute adb devices to get a list of active devices and the related port numbers. adb Command adb Bugreport

Function
Prints dumpsys, dumpstate, and logcat data to the screen, for the purposes of bug reporting Simulates an inbound phone call from Cancels an inbound phone call from Lets you direct an adb command to a specific Emulator/device instance, referred to by its adb-assigned ID or serial number Changes the state of the GPRS data connection to Prints a list of all attached Emulator/device instances Forwards socket connections from a specified local port to a specified remote port on the Emulator/device instance Prints the adb instance identifier string Prints the adb state of an Emulator/device instance

adb call adb cancel adb -d {|}

adb data adb Devices adb forward

adb get-serialno adb get-state

Chapter 12:

Android SDK Tool Reference

311

adb Command adb help adb install

Function
Prints a list of supported adb commands Pushes an Android application (specified as a full path to an .apk file) to the data file of an Emulator/device Prints a list of available JDWP processes on a given device Terminates the adb server process Prints log data to the screen Runs PPP over USB: ● The tty for PPP stream; for example, dev:/dev/omap_csmi_ttyl ● [parm]... Zero or more PPP/PPPD options, such as defaultroute, local, notty, etc. Note that you should not automatically start a PDP connection. Copies a specified file from an Emulator/device instance to your development computer Copies a specified file from your development computer to an Emulator/device instance Starts a remote shell in the target Emulator/device instance Checks whether the adb server process is running and, if not, starts it Reports the current GSM voice/data state Indicates no network is available Prints the adb version number Changes the state of the GPRS voice connection to Blocks execution until the bootloader is online—that is, until the instance state is bootloader Blocks execution until the device is online—that is, until the instance state is device

adb jdwp adb kill-server adb logcat [] [] adb ppp [parm]...

adb pull

adb push adb Shell adb start-server adb Status adb unregistered adb Version adb voice adb wait-for-bootloader

adb wait-for-device

This page intentionally left blank

Index
A
Activities AndroidLBS Activity, 212–221 AndroidPhoneDialer, 124–128 AutoCompleteTextView, 163–172 building, 151–157 Button Activity, 173–177, 202 Call Activity, 128–136 Checkbox Activity, 178–183 creating your first Android project in Eclipse, 55–61 defined, 54 Dialer Activity, 124–128 EditText Activity, 183–189 FindAFriend Activity, 258–259, 276–305 FriendsMap Activity, 293–298 launch flags, 126 LocationEditor Activity Manifest, 132–135 NameEditor Activity, 278–283 permissions, 131–136 RadioGroup Activity, 189–195 shell Activity using Windows CLI, 84–95 Spinner View, 195–201 Test Activity, 155–157 uninstalling a prior version, 106–108 See also Hello World! Activity Action Intents CALL_ACTION, 129 defined, 119 DIAL_ACTION, 124–128 list of, 120 .java file, 65–68 activityCreator, 47 ActivityCreator.bat, 85–88 project structure, 88–95 activityCreator.py, 111–112 adb.exe, 46–47 commands, 104, 115, 310–311 installing applications with, 103–106 ls command, 211

313
Copyright © 2008 by The McGraw-Hill Companies. Click here for terms of use.

314

Android: A Programmer’s Guide

adb.exe (continued) pull command, 208, 210 reinstalling and launching an application, 108 uninstalling prior versions of an application, 106–108 Android developers’ forum, 23 developing in languages other than Java, 20 home screen, 6 and Linux, 8 overview, 6–7 release of, 5 Android applications, life cycle, 50 Android Location-Based API, 204–205 adding zoom controls, 226–232 creating .kml file, 205–208 creating the AndroidLBS Activity, 212–221 MapView, 222–225, 232–236 passing coordinates to Google Maps, 222–226 track files, 208 Android plugin for Eclipse configuring, 30–33 downloading and installing, 24–30 Android SDK, 22–23 activityCreator, 47 API Demos application, 40–41, 51 APIs, 48–49 Debug Bridge, 46–47, 310–311 Docs folder, 37 documentation, 38–39 downloading, 24 DX.exe, 47 Emulator, 45–46, 71–72, 241–244, 308–310 FAQs, 39 Hello, Activity! application, 41 languages, 33 and Linux, 109

Lunar Lander application, 42 MKSDCARD.exe, 47 Note Pad application, 43 overview, 36–37 Reference Information, 39 Samples folder, 37, 39–45 Skeleton App, 43–44 Snake, 44 tools, 45–47 Tools folder, 37 updates, 33, 51 upgrading, 34 android_programmers_guide.FindAFriend directory, 261 android.jar, 63 android.java, 63 AndroidLBS Activity adding zoom controls, 226–232 adjusting permissions, 212–214 creating the layout, 214–218 running the Activity, 220–221 writing code to run the Activity, 218–220 AndroidLBS.java, 234–236 AndroidManifest.xml, 62 adding an Intent Filter, 169–170 for Button Activity, 173 for Checkbox Activity, 178 editing to adjust permissions, 213–214 for EditText Activity, 183–184 for FindAFriend Activity, 276–278 modifying, 155–157 for RadioGroup Activity, 189–190 for Spinner View Activity, 195–196 AndroidPhoneDialer, 124–128 modifying, 136–147 AndroidPhoneDialer.java, code, 146–147 AndroidViews, 150–151 AndroidViews.java, 160, 162–163 Button Activity, 175–176 Checkbox Activity, 180–182

Index

315

for EditText Activity, 186–188 for RadioGroup Activity, 192–194 for Spinner View Activity, 198–200 ANT, 90 compiling Hello World! Activity, 98–103 errors, 98–103 and Linux, 113–114 Apache ANT. See ANT API Demos application, 40–41, 51 APIs, 48 GoogleAPIs, 48 Optional APIs, 48–49 application life cycle, 49 Android applications, 50 standard ASP applications, 49–50 .java, 82 applications, defined, 54 ASP applications, life cycle, 49–50 assets directory, 64 authenticating users, Emulator, 243–244 autocomplete.java, 165–169 AutoCompleteTextView, 163–172 autocomplete.xml, 164–165

C
Call Activity, 128–136 CALL_ACTION Intent, 129 calling, vs. dialing, 119 cell phones, 3–4, 118 Checkbox Activity, 178–183 checkbox.xml, 179 CLI. See command-line interface (CLI) command-line interface (CLI), shell Activity using Windows CLI, 84–95 command-line tools, 84 ActivityCreator.bat, 85–95 Content Providers creating, 263–276 providing a defining class, 306 ContentView, 69, 71, 76 Cursors, 269

D
Dalvik executable files, 47 DatabaseHelper class, 267 Debug Bridge, 46–47 commands, 104, 115, 310–311 installing applications with, 103–106 reinstalling and launching an application, 108 uninstalling prior versions of an application, 106–108 delete( ), 269–271 Dev Tools, 241–242 developers, 2 homebrew, 4 developers’ forum, 23 DIAL_ACTION Intent, 124–128 Dialer Activity, 124–128 dialing vs. calling, 119

B
BaseColumns, 306 Broadcast Intents defined, 119 list of, 121–123 build.xml, 89–94 Button Activity, modifying Button actions, 202 buttons adding, 136–141 Button Activity, 173–177 types of, 148 button.xml, 173–174

316

Android: A Programmer’s Guide

dialing (continued) notation to dial a specific phone number or voicemail, 125 directories, 63–68 DX.exe, 47

F
Fedora 8 Linux, 109 FindAFriend Activity, 258–259 creating, 276–302 running, 302–305 finish( ), 281 FORWARD_RESULT_LAUNCH, 126 FriendsMap Activity, 293–298

E
Eclipse, 10 advantages of using, 11 Android plugin for, 24–33 creating your first Android project, 55–61 downloading and installing, 18–20 and JRE versions, 20 EditText, 245–246 implementing an EditText view, 141–145 EditText Activity, 183–189 edittext.xml, 184–185 embedded device programming, history of, 2–5 embedded devices, 3 Emulator, 45–46, 71–72 authenticating users, 243–244 calling to or from, 148 commands, 308–310 compiling and running GoogleAPIs, 252–255 configuring for GTalk, 241–244 installing applications with, 103–106 leaving open, 127 error messages, 58 errors Call Activity, 130 running ANT, 98–103 when running Hello World! Activity, 105–106 executable files, 47

G getCurrentLocation( ), 219 getType( ), 271 Google applications, 7 and the Open Handset Alliance, 5, 8, 109 Google Android development site, 22–23 Google Calendar, 240 Google Docs, 240 Google Earth, 205–208 Google Maps and markers, 237 passing coordinates to, 222–226 Google NotePad, 259 Google Services, 240 Google Spreadsheet, 240 GoogleAPI.java, 247–248 GoogleAPIs, 48, 240 adding a settings feature, 255–256 compiling and running in the Emulator, 252–255 GoogleAPI.xml, creating an Activity’s layout in, 245–247 GPS. See Android Location-Based API GTalk, 240 adding packages to GoogleAPI.java, 247–248 communicating with other XMPP-based chat clients, 256

Index

317

compiling and running Google API, 252–255 configuring the Android Emulator for, 241–244 creating an Activity’s layout in GoogleAPI.xml, 245–247 implementing View.OnClickListener, 248–252

H
Hello World!, 41 adding the JAVA_HOME variable, 96–97 code-based UI, 75–77 compiling with ANT, 98–103 creating an image-based version, 115 editing project files, 95–96 errors, 105–106 with images, 72–81 installing with adb, 103–106 on Linux, 109–114 programming in code, 69–72 reinstalling and launching, 108 uninstalling prior versions, 106–108 XML-based UI, 78–81 HelloWorldImage, 72–81 HelloWorldText, 55–61 homebrew developers, 4

importing packages full packages vs. specific sections, 202 to GoogleAPI.java, 247–248 insert( ), 269–271 integrated development environments (IDEs), 10 See also Eclipse Intent Filters, 123 adding to AutoCompleteTextView, 169–170 for AndroidViews Activity, 155–157 and DIAL_ACTION Intent, 125 Intent Receivers, 123 Intent Resolver, 119 Intents Activity Action Intents, 119, 120 Broadcast Intents, 119, 121–123 CALL_ACTION, 129 defined, 119 DIAL_ACTION, 124–128 Intent code for .java file, 154 Intent code for .xml file, 152–153

J
Java Development Kit (JDK), downloading and installing, 12–18 .java file, Intent code for, 154 Java Runtime Environment (JRE) downloading and installing, 12–18 versions, 20 JAVA_HOME variable, 96–97 JDK. See Java Development Kit (JDK) JRE. See Java Runtime Environment (JRE)

I
IChatSession, 250–251 IDEs. See integrated development environments (IDEs) images displaying, 72–81 naming, 74 ImageView, 75–77, 78–80

K
Keyhole Markup Language file. See .kml file .kml file, 237 creating, 205–208

318

Android: A Programmer’s Guide

L labels, 82 LabelView, 82 launch flags, 126 licenses, for Java Development Kit (JDK), 15, 16 LinearLayout, 215–218, 246–247 Linux and Android, 8 Hello World! Activity, 109–114 installing the Linux Android server, 114 ListAdapter, 250 listeners, 139 ListView, 245–246 LoadCoords( ), 219 LoadFriends( ), 294 location updating in real time, 305 location_editor.xml, 283 LocationEditor Activity, 283–293 LocationEditor.java, 283–293 Lunar Lander application, 42

New Android Project wizard, 55–61 NEW_TASK_LAUNCH, 126, 129 .nmea files, 237 defined, 208 in Linux, 210–212 in Windows, 208–209 NO_HISTORY_LAUNCH, 126 Note Pad application, 43

O onCreate( ), 266, 267 onCreateOptionsMenu( ), 159–160 onOptionsItemSelected( ), 161–162 onPause( ), 281, 286, 287 onResume( ), 280–281, 286, 287 Open Handset Alliance, 5–6 and Google, 8, 109 operating systems, 115 See also Linux Optional APIs, 48–49

M main.xml, 82, 233–234 code, 146 Manifest editing, 132–135 Permissions wizard, 213 MapView, 222–225 toggling between standard and satellite views, 232–236 Menu, creating, 157–163 MKSDCARD.exe, 47 MULTIPLE_TASK_LAUNCH, 126

P
Package Explorer, 61 package name, 58 PATH statement, configuring, 109–114 permissions, 131–136, 212–214 plugins, Android plugin for Eclipse, 24–33 priority, 7

Q query( ), 268–269

N
NameEditor Activity, 278–283 National Marine Electronics Association files. See .nmea files

R
RadioGroup Activity, 189–195 radiogroup.xml, 190–191

Index

319

Referenced Libraries, 62–63 RelativeLayout, 226–228, 293 res directory, 63–64 R.java file, 64–65 root directory, 62

U
Ubuntu Dapper Drake, 109 uninstalling, prior versions of an Activity, 106–108 update( ), 269–271 updates, Android SDK, 51 Uri.parse, 125, 129 user interface (UI) development, 7

S
SDK, Android, 22–24 SDN. See Sun Developer Network (SDN) settings feature, adding to a GoogleAPI Activity, 255–256 SINGLE_TOP_LAUNCH, 126 Skeleton App, 43–44 Snake, 44 Spinner View Activity, 195–201 spinner.xml, 197 SQLite database, 250 creating, 259–262 creating in code, 306 SQLiteOpenHelper, 266–267 src directory, 64–68 src folder, 45 strings.xml, editing, 263–265 Sun Developer Network (SDN), Downloads page, 13–14 system priority, 7

V
View.OnClickListener, 248–252 voicemail, dialing shortcut, 125

X
.xml file, Intent code for, 152–153 XMPP, 240 communicating with other XMPP-based chat clients, 256 Settings, 242

Z zoom controls, 226–232

T
Test Activity, 155–157 testButton.java, 174–175 testCheckBox.java, 179–180 testEditText.java, 185–186 test.java, 154 testRadioGroup.java, 191–192 testSpinner.java, 197–198 test.xml, 152–153 TextView, 67, 68, 69–71, 82 track files, 208