Merge change Iae0bc856 into eclair
* changes:
A sample application that demonstrates use of legacy and current contacts APIs.
diff --git a/samples/BusinessCard/Android.mk b/samples/BusinessCard/Android.mk
new file mode 100644
index 0000000..627cac1
--- /dev/null
+++ b/samples/BusinessCard/Android.mk
@@ -0,0 +1,13 @@
+LOCAL_PATH:= $(call my-dir)
+include $(CLEAR_VARS)
+
+LOCAL_MODULE_TAGS := samples
+
+# Only compile source java files in this apk.
+LOCAL_SRC_FILES := $(call all-java-files-under, src)
+
+LOCAL_PACKAGE_NAME := BusinessCard
+
+LOCAL_SDK_VERSION := current
+
+include $(BUILD_PACKAGE)
diff --git a/samples/BusinessCard/AndroidManifest.xml b/samples/BusinessCard/AndroidManifest.xml
new file mode 100644
index 0000000..186e249
--- /dev/null
+++ b/samples/BusinessCard/AndroidManifest.xml
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (C) 2009 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+ package="com.example.android.businesscard">
+
+ <!-- IMPORTANT! We want this app to run on Cupcake, Donut, Eclair and beyond -->
+ <uses-sdk android:minSdkVersion="3"/>
+
+ <uses-permission android:name="android.permission.READ_CONTACTS" />
+
+ <application android:label="@string/businesscard_app">
+ <activity android:name="BusinessCardActivity">
+ <intent-filter>
+ <action android:name="android.intent.action.MAIN" />
+ <category android:name="android.intent.category.LAUNCHER" />
+ </intent-filter>
+ </activity>
+ </application>
+</manifest>
diff --git a/samples/BusinessCard/res/layout/business_card.xml b/samples/BusinessCard/res/layout/business_card.xml
new file mode 100644
index 0000000..c7ce713
--- /dev/null
+++ b/samples/BusinessCard/res/layout/business_card.xml
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="utf-8"?>
+<RelativeLayout
+ xmlns:android="http://schemas.android.com/apk/res/android"
+ android:layout_width="fill_parent"
+ android:layout_height="fill_parent">
+ <Button
+ android:id="@+id/pick_contact_button"
+ android:layout_width="fill_parent"
+ android:layout_height="wrap_content"
+ android:layout_alignParentTop="true"
+ android:layout_margin="10dip"
+ android:text="@string/button_pick_contact"/>
+ <TextView
+ android:id="@+id/display_name_text_view"
+ android:layout_width="wrap_content"
+ android:layout_height="wrap_content"
+ android:layout_centerInParent="true"
+ android:textAppearance="?android:attr/textAppearanceLarge"/>
+ <TextView
+ android:id="@+id/phone_number_text_view"
+ android:layout_width="wrap_content"
+ android:layout_height="wrap_content"
+ android:layout_below="@id/display_name_text_view"
+ android:layout_centerHorizontal="true"
+ android:textAppearance="?android:attr/textAppearanceMedium"/>
+</RelativeLayout>
+
diff --git a/samples/BusinessCard/res/values/strings.xml b/samples/BusinessCard/res/values/strings.xml
new file mode 100644
index 0000000..8668d57
--- /dev/null
+++ b/samples/BusinessCard/res/values/strings.xml
@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (C) 2009 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<!-- This file contains resource definitions for displayed strings, allowing
+ them to be changed based on the locale and options. -->
+
+<resources>
+ <string name="businesscard_app">Business Card</string>
+ <string name="button_pick_contact">Pick Contact</string>
+</resources>
+
diff --git a/samples/BusinessCard/src/com/example/android/businesscard/BusinessCardActivity.java b/samples/BusinessCard/src/com/example/android/businesscard/BusinessCardActivity.java
new file mode 100644
index 0000000..d8d277e
--- /dev/null
+++ b/samples/BusinessCard/src/com/example/android/businesscard/BusinessCardActivity.java
@@ -0,0 +1,125 @@
+/*
+ * Copyright (C) 2009 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.android.businesscard;
+
+import android.app.Activity;
+import android.content.Intent;
+import android.net.Uri;
+import android.os.AsyncTask;
+import android.os.Bundle;
+import android.view.View;
+import android.view.View.OnClickListener;
+import android.widget.Button;
+import android.widget.TextView;
+
+/**
+ * A simple activity that shows a "Pick Contact" button and two fields: contact's name
+ * and phone number. The user taps on the Pick Contact button to bring up
+ * the contact chooser. Once this activity receives the result from contact picker,
+ * it launches an asynchronous query (queries should always be asynchronous) to load
+ * contact's name and phone number. When the query completes, the activity displays
+ * the loaded data.
+ */
+public class BusinessCardActivity extends Activity {
+
+ // Request code for the contact picker activity
+ private static final int PICK_CONTACT_REQUEST = 1;
+
+ /**
+ * An SDK-specific instance of {@link ContactAccessor}. The activity does not need
+ * to know what SDK it is running in: all idiosyncrasies of different SDKs are
+ * encapsulated in the implementations of the ContactAccessor class.
+ */
+ private final ContactAccessor mContactAccessor = ContactAccessor.getInstance();
+
+ /**
+ * Called with the activity is first created.
+ */
+ @Override
+ public void onCreate(Bundle savedInstanceState) {
+ super.onCreate(savedInstanceState);
+
+ setContentView(R.layout.business_card);
+
+ // Install a click handler on the Pick Contact button
+ Button pickContact = (Button)findViewById(R.id.pick_contact_button);
+ pickContact.setOnClickListener(new OnClickListener() {
+
+ public void onClick(View v) {
+ pickContact();
+ }
+ });
+ }
+
+ /**
+ * Click handler for the Pick Contact button. Invokes a contact picker activity.
+ * The specific intent used to bring up that activity differs between versions
+ * of the SDK, which is why we delegate the creation of the intent to ContactAccessor.
+ */
+ protected void pickContact() {
+ startActivityForResult(mContactAccessor.getPickContactIntent(), PICK_CONTACT_REQUEST);
+ }
+
+ /**
+ * Invoked when the contact picker activity is finished. The {@code contactUri} parameter
+ * will contain a reference to the contact selected by the user. We will treat it as
+ * an opaque URI and allow the SDK-specific ContactAccessor to handle the URI accordingly.
+ */
+ @Override
+ protected void onActivityResult(int requestCode, int resultCode, Intent data) {
+ if (requestCode == PICK_CONTACT_REQUEST && resultCode == RESULT_OK) {
+ loadContactInfo(data.getData());
+ }
+ }
+
+ /**
+ * Load contact information on a background thread.
+ */
+ private void loadContactInfo(Uri contactUri) {
+
+ /*
+ * We should always run database queries on a background thread. The database may be
+ * locked by some process for a long time. If we locked up the UI thread while waiting
+ * for the query to come back, we might get an "Application Not Responding" dialog.
+ */
+ AsyncTask<Uri, Void, ContactInfo> task = new AsyncTask<Uri, Void, ContactInfo>() {
+
+ @Override
+ protected ContactInfo doInBackground(Uri... uris) {
+ return mContactAccessor.loadContact(getContentResolver(), uris[0]);
+ }
+
+ @Override
+ protected void onPostExecute(ContactInfo result) {
+ bindView(result);
+ }
+ };
+
+ task.execute(contactUri);
+ }
+
+ /**
+ * Displays contact information: name and phone number.
+ */
+ protected void bindView(ContactInfo contactInfo) {
+ TextView displayNameView = (TextView) findViewById(R.id.display_name_text_view);
+ displayNameView.setText(contactInfo.getDisplayName());
+
+ TextView phoneNumberView = (TextView) findViewById(R.id.phone_number_text_view);
+ phoneNumberView.setText(contactInfo.getPhoneNumber());
+ }
+}
diff --git a/samples/BusinessCard/src/com/example/android/businesscard/ContactAccessor.java b/samples/BusinessCard/src/com/example/android/businesscard/ContactAccessor.java
new file mode 100644
index 0000000..6a402e9
--- /dev/null
+++ b/samples/BusinessCard/src/com/example/android/businesscard/ContactAccessor.java
@@ -0,0 +1,89 @@
+/*
+ * Copyright (C) 2009 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.android.businesscard;
+
+import android.content.ContentResolver;
+import android.content.Intent;
+import android.net.Uri;
+import android.os.Build;
+
+/**
+ * This abstract class defines SDK-independent API for communication with
+ * Contacts Provider. The actual implementation used by the application depends
+ * on the level of API available on the device. If the API level is Cupcake or
+ * Donut, we want to use the {@link ContactAccessorSdk3_4} class. If it is
+ * Eclair or higher, we want to use {@link ContactAccessorSdk5}.
+ */
+public abstract class ContactAccessor {
+
+ /**
+ * Static singleton instance of {@link ContactAccessor} holding the
+ * SDK-specific implementation of the class.
+ */
+ private static ContactAccessor sInstance;
+
+ public static ContactAccessor getInstance() {
+ if (sInstance == null) {
+ String className;
+
+ /*
+ * Check the version of the SDK we are running on. Choose an
+ * implementation class designed for that version of the SDK.
+ *
+ * Unfortunately we have to use strings to represent the class
+ * names. If we used the conventional ContactAccessorSdk5.class.getName()
+ * syntax, we would get a ClassNotFoundException at runtime on pre-Eclair SDKs.
+ * Using the above syntax would force Dalvik to load the class and try to
+ * resolve references to all other classes it uses. Since the pre-Eclair
+ * does not have those classes, the loading of ContactAccessorSdk5 would fail.
+ */
+ @SuppressWarnings("deprecation")
+ int sdkVersion = Integer.parseInt(Build.VERSION.SDK); // Cupcake style
+ if (sdkVersion < Build.VERSION_CODES.ECLAIR) {
+ className = "com.example.android.businesscard.ContactAccessorSdk3_4";
+ } else {
+ className = "com.example.android.businesscard.ContactAccessorSdk5";
+ }
+
+ /*
+ * Find the required class by name and instantiate it.
+ */
+ try {
+ Class<? extends ContactAccessor> clazz =
+ Class.forName(className).asSubclass(ContactAccessor.class);
+ sInstance = clazz.newInstance();
+ } catch (Exception e) {
+ throw new IllegalStateException(e);
+ }
+ }
+
+ return sInstance;
+ }
+
+ /**
+ * Returns the {@link Intent#ACTION_PICK} intent configured for the right authority: legacy
+ * or current.
+ */
+ public abstract Intent getPickContactIntent();
+
+ /**
+ * Loads contact data for the supplied URI. The actual queries will differ for different APIs
+ * used, but the result is the same: the {@link #mDisplayName} and {@link #mPhoneNumber}
+ * fields are populated with correct data.
+ */
+ public abstract ContactInfo loadContact(ContentResolver contentResolver, Uri contactUri);
+}
diff --git a/samples/BusinessCard/src/com/example/android/businesscard/ContactAccessorSdk3_4.java b/samples/BusinessCard/src/com/example/android/businesscard/ContactAccessorSdk3_4.java
new file mode 100644
index 0000000..7fcd388
--- /dev/null
+++ b/samples/BusinessCard/src/com/example/android/businesscard/ContactAccessorSdk3_4.java
@@ -0,0 +1,81 @@
+/*
+ * Copyright (C) 2009 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.android.businesscard;
+
+import android.content.AsyncQueryHandler;
+import android.content.ContentResolver;
+import android.content.Intent;
+import android.database.Cursor;
+import android.net.Uri;
+import android.provider.Contacts.People;
+import android.provider.Contacts.People.Phones;
+
+/**
+ * An implementation of {@link ContactAccessor} that uses legacy Contacts API.
+ * These APIs are deprecated and should not be used unless we are running on a
+ * pre-Eclair SDK.
+ * <p>
+ * There are several reasons why we wouldn't want to use this class on an Eclair device:
+ * <ul>
+ * <li>It would see at most one account, namely the first Google account created on the device.
+ * <li>It would work through a compatibility layer, which would make it inherently less efficient.
+ * <li>Not relevant to this particular example, but it would not have access to new kinds
+ * of data available through current APIs.
+ * </ul>
+ */
+@SuppressWarnings("deprecation")
+public class ContactAccessorSdk3_4 extends ContactAccessor {
+
+ /**
+ * Returns a Pick Contact intent using the pre-Eclair "people" URI.
+ */
+ @Override
+ public Intent getPickContactIntent() {
+ return new Intent(Intent.ACTION_PICK, People.CONTENT_URI);
+ }
+
+ /**
+ * Retrieves the contact information.
+ */
+ @Override
+ public ContactInfo loadContact(ContentResolver contentResolver, Uri contactUri) {
+ ContactInfo contactInfo = new ContactInfo();
+ Cursor cursor = contentResolver.query(contactUri,
+ new String[]{People.DISPLAY_NAME}, null, null, null);
+ try {
+ if (cursor.moveToFirst()) {
+ contactInfo.setDisplayName(cursor.getString(0));
+ }
+ } finally {
+ cursor.close();
+ }
+
+ Uri phoneUri = Uri.withAppendedPath(contactUri, Phones.CONTENT_DIRECTORY);
+ cursor = contentResolver.query(phoneUri,
+ new String[]{Phones.NUMBER}, null, null, Phones.ISPRIMARY + " DESC");
+
+ try {
+ if (cursor.moveToFirst()) {
+ contactInfo.setPhoneNumber(cursor.getString(0));
+ }
+ } finally {
+ cursor.close();
+ }
+
+ return contactInfo;
+ }
+}
diff --git a/samples/BusinessCard/src/com/example/android/businesscard/ContactAccessorSdk5.java b/samples/BusinessCard/src/com/example/android/businesscard/ContactAccessorSdk5.java
new file mode 100644
index 0000000..6855597
--- /dev/null
+++ b/samples/BusinessCard/src/com/example/android/businesscard/ContactAccessorSdk5.java
@@ -0,0 +1,88 @@
+/*
+ * Copyright (C) 2009 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.android.businesscard;
+
+import android.content.ContentResolver;
+import android.content.Intent;
+import android.database.Cursor;
+import android.net.Uri;
+import android.provider.ContactsContract.Contacts;
+import android.provider.ContactsContract.CommonDataKinds.Phone;
+
+/**
+ * An implementation of {@link ContactAccessor} that uses current Contacts API.
+ * This class should be used on Eclair or beyond, but would not work on any earlier
+ * release of Android. As a matter of fact, it could not even be loaded.
+ * <p>
+ * This implementation has several advantages:
+ * <ul>
+ * <li>It sees contacts from multiple accounts.
+ * <li>It works with aggregated contacts. So for example, if the contact is the result
+ * of aggregation of two raw contacts from different accounts, it may return the name from
+ * one and the phone number from the other.
+ * <li>It is efficient because it uses the more efficient current API.
+ * <li>Not obvious in this particular example, but it has access to new kinds
+ * of data available exclusively through the new APIs. Exercise for the reader: add support
+ * for nickname (see {@link android.provider.ContactsContract.CommonDataKinds.Nickname}) or
+ * social status updates (see {@link android.provider.ContactsContract.StatusUpdates}).
+ * </ul>
+ */
+public class ContactAccessorSdk5 extends ContactAccessor {
+
+ /**
+ * Returns a Pick Contact intent using the Eclair "contacts" URI.
+ */
+ @Override
+ public Intent getPickContactIntent() {
+ return new Intent(Intent.ACTION_PICK, Contacts.CONTENT_URI);
+ }
+
+ /**
+ * Retrieves the contact information.
+ */
+ @Override
+ public ContactInfo loadContact(ContentResolver contentResolver, Uri contactUri) {
+ ContactInfo contactInfo = new ContactInfo();
+ long contactId = -1;
+
+ // Load the display name for the specified person
+ Cursor cursor = contentResolver.query(contactUri,
+ new String[]{Contacts._ID, Contacts.DISPLAY_NAME}, null, null, null);
+ try {
+ if (cursor.moveToFirst()) {
+ contactId = cursor.getLong(0);
+ contactInfo.setDisplayName(cursor.getString(1));
+ }
+ } finally {
+ cursor.close();
+ }
+
+ // Load the phone number (if any).
+ cursor = contentResolver.query(Phone.CONTENT_URI,
+ new String[]{Phone.NUMBER},
+ Phone.CONTACT_ID + "=" + contactId, null, Phone.IS_SUPER_PRIMARY + " DESC");
+ try {
+ if (cursor.moveToFirst()) {
+ contactInfo.setPhoneNumber(cursor.getString(0));
+ }
+ } finally {
+ cursor.close();
+ }
+
+ return contactInfo;
+ }
+}
diff --git a/samples/BusinessCard/src/com/example/android/businesscard/ContactInfo.java b/samples/BusinessCard/src/com/example/android/businesscard/ContactInfo.java
new file mode 100644
index 0000000..61a6f3b
--- /dev/null
+++ b/samples/BusinessCard/src/com/example/android/businesscard/ContactInfo.java
@@ -0,0 +1,42 @@
+/*
+ * Copyright (C) 2009 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.android.businesscard;
+
+/**
+ * A model object containing contact data.
+ */
+public class ContactInfo {
+
+ private String mDisplayName;
+ private String mPhoneNumber;
+
+ public void setDisplayName(String displayName) {
+ this.mDisplayName = displayName;
+ }
+
+ public String getDisplayName() {
+ return mDisplayName;
+ }
+
+ public void setPhoneNumber(String phoneNumber) {
+ this.mPhoneNumber = phoneNumber;
+ }
+
+ public String getPhoneNumber() {
+ return mPhoneNumber;
+ }
+}