From 421435d2bede2788b74b07b1bab893fef98047c5 Mon Sep 17 00:00:00 2001 From: Joe Malin Date: Tue, 15 Jan 2013 15:06:08 -0800 Subject: Android Training: Accessing Contacts Change-Id: I4de9f2a9ef18415225e1c85d53602bbaacbb7bb6 --- .../training/contacts-provider/ContactsList.zip | Bin 0 -> 483676 bytes .../contacts-provider/display-contact-badge.jd | 635 ++++++++++++++++ docs/html/training/contacts-provider/index.jd | 97 +++ .../html/training/contacts-provider/modify-data.jd | 305 ++++++++ .../training/contacts-provider/retrieve-details.jd | 378 ++++++++++ .../training/contacts-provider/retrieve-names.jd | 815 +++++++++++++++++++++ docs/html/training/training_toc.cs | 34 +- 7 files changed, 2262 insertions(+), 2 deletions(-) create mode 100644 docs/html/training/contacts-provider/ContactsList.zip create mode 100644 docs/html/training/contacts-provider/display-contact-badge.jd create mode 100644 docs/html/training/contacts-provider/index.jd create mode 100644 docs/html/training/contacts-provider/modify-data.jd create mode 100644 docs/html/training/contacts-provider/retrieve-details.jd create mode 100644 docs/html/training/contacts-provider/retrieve-names.jd diff --git a/docs/html/training/contacts-provider/ContactsList.zip b/docs/html/training/contacts-provider/ContactsList.zip new file mode 100644 index 000000000000..d2a5cfb5a196 Binary files /dev/null and b/docs/html/training/contacts-provider/ContactsList.zip differ diff --git a/docs/html/training/contacts-provider/display-contact-badge.jd b/docs/html/training/contacts-provider/display-contact-badge.jd new file mode 100644 index 000000000000..f08935d1262d --- /dev/null +++ b/docs/html/training/contacts-provider/display-contact-badge.jd @@ -0,0 +1,635 @@ +page.title=Displaying the Quick Contact Badge + +trainingnavtop=true +@jd:body + + +
+
+ + +

This lesson teaches you to

+
    +
  1. + Add a QuickContactBadge View +
    2. +
  2. + Set the Contact URI and Thumbnail +
    3. +
  3. + + Add a QuickContactBadge to a ListView + +
    4. +
+ + +

You should also read

+ + +

Try it out

+ +
+ + Download the sample + +

ContactsList.zip

+
+ +
+
+

+ This lesson shows you how to add a {@link android.widget.QuickContactBadge} to your UI + and how to bind data to it. A {@link android.widget.QuickContactBadge} is a widget that + initially appears as a thumbnail image. Although you can use any {@link android.graphics.Bitmap} + for the thumbnail image, you usually use a {@link android.graphics.Bitmap} decoded from the + contact's photo thumbnail image. +

+

+ The small image acts as a control; when users click on the image, the + {@link android.widget.QuickContactBadge} expands into a dialog containing the following: +

+
+
A large image
+
+ The large image associated with the contact, or no image is available, a placeholder + graphic. +
+
+ App icons +
+
+ An app icon for each piece of detail data that can be handled by a built-in app. For + example, if the contact's details include one or more email addresses, an email icon + appears. When users click the icon, all of the contact's email addresses appear. When users + click one of the addresses, the email app displays a screen for composing a message to the + selected email address. +
+
+

+ The {@link android.widget.QuickContactBadge} view provides instant access to a contact's + details, as well as a fast way of communicating with the contact. Users don't have to look up + a contact, find and copy information, and then paste it into the appropriate app. Instead, they + can click on the {@link android.widget.QuickContactBadge}, choose the communication method they + want to use, and send the information for that method directly to the appropriate app. +

+

Add a QuickContactBadge View

+

+ To add a {@link android.widget.QuickContactBadge}, insert a + <QuickContactBadge> element in your layout. For example: +

+
+<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
+                android:layout_width="match_parent"
+                android:layout_height="match_parent">
+...
+    <QuickContactBadge
+               android:id=@+id/quickbadge
+               android:layout_height="wrap_content"
+               android:layout_width="wrap_content"
+               android:scaleType="centerCrop"/>
+    ...
+</RelativeLayout>
+
+

Retrieve provider data

+

+ To display a contact in the {@link android.widget.QuickContactBadge}, you need a content URI + for the contact and a {@link android.graphics.Bitmap} for the small image. You generate + both the content URI and the {@link android.graphics.Bitmap} from columns retrieved from the + Contacts Provider. Specify these columns as part of the projection you use to load data into + your {@link android.database.Cursor}. +

+

+ For Android 3.0 (API level 11) and later, include the following columns in your projection:

+ +

+ For Android 2.3.3 (API level 10) and earlier, use the following columns: +

+ +

+ The remainder of this lesson assumes that you've already loaded a + {@link android.database.Cursor} that contains these columns as well as others you may have + chosen. To learn how to retrieve this columns in a {@link android.database.Cursor}, read the + lesson Retrieving a List of Contacts. +

+

Set the Contact URI and Thumbnail

+

+ Once you have the necessary columns, you can bind data to the + {@link android.widget.QuickContactBadge}. +

+

Set the Contact URI

+

+ To set the content URI for the contact, call + {@link android.provider.ContactsContract.Contacts#getLookupUri getLookupUri(id,lookupKey)} to + get a {@link android.provider.ContactsContract.Contacts#CONTENT_LOOKUP_URI}, then + call {@link android.widget.QuickContactBadge#assignContactUri assignContactUri()} to set the + contact. For example: +

+
+    // The Cursor that contains contact rows
+    Cursor mCursor;
+    // The index of the _ID column in the Cursor
+    int mIdColumn;
+    // The index of the LOOKUP_KEY column in the Cursor
+    int mLookupKeyColumn;
+    // A content URI for the desired contact
+    Uri mContactUri;
+    // A handle to the QuickContactBadge view
+    QuickContactBadge mBadge;
+    ...
+    mBadge = (QuickContactBadge) findViewById(R.id.quickbadge);
+    /*
+     * Insert code here to move to the desired cursor row
+     */
+    // Gets the _ID column index
+    mIdColumn = mCursor.getColumnIndex(Contacts._ID);
+    // Gets the LOOKUP_KEY index
+    mLookupKeyColumn = mCursor.getColumnIndex(Contacts.LOOKUP_KEY);
+    // Gets a content URI for the contact
+    mContactUri =
+            Contacts.getLookupUri(
+                Cursor.getLong(mIdColumn),
+                Cursor.getString(mLookupKeyColumn)
+            );
+    mBadge.assignContactUri(mContactUri);
+
+

+ When users click the {@link android.widget.QuickContactBadge} icon, the contact's + details automatically appear in the dialog. +

+

Set the photo thumbnail

+

+ Setting the contact URI for the {@link android.widget.QuickContactBadge} does not automatically + load the contact's thumbnail photo. To load the photo, get a URI for the photo from the + contact's {@link android.database.Cursor} row, use it to open the file containing the compressed + thumbnail photo, and read the file into a {@link android.graphics.Bitmap}. +

+

+ Note: The + {@link android.provider.ContactsContract.Contacts#PHOTO_THUMBNAIL_URI} column isn't available + in platform versions prior to 3.0. For those versions, you must retrieve the URI + from the {@link android.provider.ContactsContract.Contacts.Photo Contacts.Photo} subtable. +

+

+ First, set up variables for accessing the {@link android.database.Cursor} containing the + {@link android.provider.ContactsContract.Contacts#_ID Contacts._ID} and + {@link android.provider.ContactsContract.Contacts#LOOKUP_KEY Contacts.LOOKUP_KEY} columns, as + described previously: +

+
+    // The column in which to find the thumbnail ID
+    int mThumbnailColumn;
+    /*
+     * The thumbnail URI, expressed as a String.
+     * Contacts Provider stores URIs as String values.
+     */
+    String mThumbnailUri;
+    ...
+    /*
+     * Gets the photo thumbnail column index if
+     * platform version >= Honeycomb
+     */
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB) {
+        mThumbnailColumn =
+                mCursor.getColumnIndex(Contacts.PHOTO_THUMBNAIL_URI);
+    // Otherwise, sets the thumbnail column to the _ID column
+    } else {
+        mThumbnailColumn = mIdColumn;
+    }
+    /*
+     * Assuming the current Cursor position is the contact you want,
+     * gets the thumbnail ID
+     */
+    mThumbnailUri = Cursor.getString(mThumbnailColumn);
+    ...
+
+

+ Define a method that takes photo-related data for the contact and dimensions for the + destination view, and returns the properly-sized thumbnail in a + {@link android.graphics.Bitmap}. Start by constructing a URI that points to the + thumbnail: +

+

+    /**
+     * Load a contact photo thumbnail and return it as a Bitmap,
+     * resizing the image to the provided image dimensions as needed.
+     * @param photoData photo ID Prior to Honeycomb, the contact's _ID value.
+     * For Honeycomb and later, the value of PHOTO_THUMBNAIL_URI.
+     * @return A thumbnail Bitmap, sized to the provided width and height.
+     * Returns null if the thumbnail is not found.
+     */
+    private Bitmap loadContactPhotoThumbnail(String photoData) {
+        // Creates an asset file descriptor for the thumbnail file.
+        AssetFileDescriptor afd = null;
+        // try-catch block for file not found
+        try {
+            // Creates a holder for the URI.
+            Uri thumbUri;
+            // If Android 3.0 or later
+            if (Build.VERSION.SDK_INT
+                    >=
+                Build.VERSION_CODES.HONEYCOMB) {
+                // Sets the URI from the incoming PHOTO_THUMBNAIL_URI
+                thumbUri = Uri.parse(photoData);
+            } else {
+            // Prior to Android 3.0, constructs a photo Uri using _ID
+                /*
+                 * Creates a contact URI from the Contacts content URI
+                 * incoming photoData (_ID)
+                 */
+                final Uri contactUri = Uri.withAppendedPath(
+                        Contacts.CONTENT_URI, photoData);
+                /*
+                 * Creates a photo URI by appending the content URI of
+                 * Contacts.Photo.
+                 */
+                thumbUri =
+                        Uri.withAppendedPath(
+                                contactUri, Photo.CONTENT_DIRECTORY);
+            }
+    
+        /*
+         * Retrieves an AssetFileDescriptor object for the thumbnail
+         * URI
+         * using ContentResolver.openAssetFileDescriptor
+         */
+        afd = getActivity().getContentResolver().
+                openAssetFileDescriptor(thumbUri, "r");
+        /*
+         * Gets a file descriptor from the asset file descriptor.
+         * This object can be used across processes.
+         */
+        FileDescriptor fileDescriptor = afd.getFileDescriptor();
+        // Decode the photo file and return the result as a Bitmap
+        // If the file descriptor is valid
+        if (fileDescriptor != null) {
+            // Decodes the bitmap
+            return BitmapFactory.decodeFileDescriptor(
+                    fileDescriptor, null, null);
+            }
+        // If the file isn't found
+        } catch (FileNotFoundException e) {
+            /*
+             * Handle file not found errors
+             */
+        }
+        // In all cases, close the asset file descriptor
+        } finally {
+            if (afd != null) {
+                try {
+                    afd.close();
+                } catch (IOException e) {}
+            }
+        }
+        return null;
+    }
+
+

+ Call the loadContactPhotoThumbnail() method in your code to get the + thumbnail {@link android.graphics.Bitmap}, and use the result to set the photo thumbnail in + your {@link android.widget.QuickContactBadge}: +

+
+    ...
+    /*
+     * Decodes the thumbnail file to a Bitmap.
+     */
+    Bitmap mThumbnail =
+            loadContactPhotoThumbnail(mThumbnailUri);
+    /*
+     * Sets the image in the QuickContactBadge
+     * QuickContactBadge inherits from ImageView, so
+     */
+    mBadge.setImageBitmap(mThumbnail);
+
+

Add a QuickContactBadge to a ListView

+

+ A {@link android.widget.QuickContactBadge} is a useful addition to a + {@link android.widget.ListView} that displays a list of contacts. Use the + {@link android.widget.QuickContactBadge} to display a thumbnail photo for each contact; when + users click the thumbnail, the {@link android.widget.QuickContactBadge} dialog appears. +

+

Add the QuickContactBadge element

+

+ To start, add a {@link android.widget.QuickContactBadge} view element to your item layout + For example, if you want to display a {@link android.widget.QuickContactBadge} and a name for + each contact you retrieve, put the following XML into a layout file: +

+
+<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
+                android:layout_width="match_parent"
+                android:layout_height="wrap_content">
+    <QuickContactBadge
+        android:id="@+id/quickcontact"
+        android:layout_height="wrap_content"
+        android:layout_width="wrap_content"
+        android:scaleType="centerCrop"/>
+    <TextView android:id="@+id/displayname"
+              android:layout_width="match_parent"
+              android:layout_height="wrap_content"
+              android:layout_toRightOf="@+id/quickcontact"
+              android:gravity="center_vertical"
+              android:layout_alignParentRight="true"
+              android:layout_alignParentTop="true"/>
+</RelativeLayout>
+
+

+ In the following sections, this file is referred to as contact_item_layout.xml. +

+

Set up a custom CursorAdapter

+

+ To bind a {@link android.support.v4.widget.CursorAdapter} to a {@link android.widget.ListView} + containing a {@link android.widget.QuickContactBadge}, define a custom adapter that + extends {@link android.support.v4.widget.CursorAdapter}. This approach allows you to process the + data in the {@link android.database.Cursor} before you bind it to the + {@link android.widget.QuickContactBadge}. This approach also allows you to bind multiple + {@link android.database.Cursor} columns to the {@link android.widget.QuickContactBadge}. Neither + of these operations is possible in a regular {@link android.support.v4.widget.CursorAdapter}. +

+

+ The subclass of {@link android.support.v4.widget.CursorAdapter} that you define must + override the following methods: +

+
+
{@link android.support.v4.widget.CursorAdapter#newView CursorAdapter.newView()}
+
+ Inflates a new {@link android.view.View} object to hold the item layout. In the override + of this method, store handles to the child {@link android.view.View} objects of the layout, + including the child {@link android.widget.QuickContactBadge}. By taking this approach, you + avoid having to get handles to the child {@link android.view.View} objects each time you + inflate a new layout. +

+ You must override this method so you can get handles to the individual child + {@link android.view.View} objects. This technique allows you to control their binding in + {@link android.support.v4.widget.CursorAdapter#bindView CursorAdapter.bindView()}. +

+
+
{@link android.support.v4.widget.CursorAdapter#bindView CursorAdapter.bindView()}
+
+ Moves data from the current {@link android.database.Cursor} row to the child + {@link android.view.View} objects of the item layout. You must override this method so + you can bind both the contact's URI and thumbnail to the + {@link android.widget.QuickContactBadge}. The default implementation only allows a 1-to-1 + mapping between a column and a {@link android.view.View} +
+
+

+ The following code snippet contains an example of a custom subclass of + {@link android.support.v4.widget.CursorAdapter}: +

+

Define the custom list adapter

+

+ Define the subclass of {@link android.support.v4.widget.CursorAdapter} including its + constructor, and override + {@link android.support.v4.widget.CursorAdapter#newView newView()} and + {@link android.support.v4.widget.CursorAdapter#bindView bindView()}: +

+
+    /**
+     *
+     *
+     */
+    private class ContactsAdapter extends CursorAdapter {
+        private LayoutInflater mInflater;
+        ...
+        public ContactsAdapter(Context context) {
+            super(context, null, 0);
+
+            /*
+             * Gets an inflater that can instantiate
+             * the ListView layout from the file.
+             */
+            mInflater = LayoutInflater.from(context);
+            ...
+        }
+        ...
+        /**
+         * Defines a class that hold resource IDs of each item layout
+         * row to prevent having to look them up each time data is
+         * bound to a row.
+         */
+        private class ViewHolder {
+            TextView displayname;
+            QuickContactBadge quickcontact;
+        }
+        ..
+        @Override
+        public View newView(
+                Context context,
+                Cursor cursor,
+                ViewGroup viewGroup) {
+            /* Inflates the item layout. Stores resource IDs in a
+             * in a ViewHolder class to prevent having to look
+             * them up each time bindView() is called.
+             */
+            final View itemView =
+                    mInflater.inflate(
+                            R.layout.contact_list_layout,
+                            viewGroup,
+                            false
+                    );
+            final ViewHolder holder = new ViewHolder();
+            holder.displayname =
+                    (TextView) view.findViewById(R.id.displayname);
+            holder.quickcontact =
+                    (QuickContactBadge)
+                            view.findViewById(R.id.quickcontact);
+            view.setTag(holder);
+            return view;
+        }
+        ...
+        @Override
+        public void bindView(
+                View view,
+                Context context,
+                Cursor cursor) {
+            final ViewHolder holder = (ViewHolder) view.getTag();
+            final String photoData =
+                    cursor.getString(mPhotoDataIndex);
+            final String displayName =
+                    cursor.getString(mDisplayNameIndex);
+            ...
+            // Sets the display name in the layout
+            holder.displayname = cursor.getString(mDisplayNameIndex);
+            ...
+            /*
+             * Generates a contact URI for the QuickContactBadge.
+             */
+            final Uri contactUri = Contacts.getLookupUri(
+                    cursor.getLong(mIdIndex),
+                    cursor.getString(mLookupKeyIndex));
+            holder.quickcontact.assignContactUri(contactUri);
+            String photoData = cursor.getString(mPhotoDataIndex);
+            /*
+             * Decodes the thumbnail file to a Bitmap.
+             * The method loadContactPhotoThumbnail() is defined
+             * in the section "Set the Contact URI and Thumbnail"
+             */
+            Bitmap thumbnailBitmap =
+                    loadContactPhotoThumbnail(photoData);
+            /*
+             * Sets the image in the QuickContactBadge
+             * QuickContactBadge inherits from ImageView
+             */
+            holder.quickcontact.setImageBitmap(thumbnailBitmap);
+    }
+
+ +

Set up variables

+

+ In your code, set up variables, including a {@link android.database.Cursor} projection that + includes the necessary columns. +

+

+ Note: The following code snippets use the method + loadContactPhotoThumbnail(), which is defined in the section + Set the Contact URI and Thumbnail +

+

+ For example: +

+
+public class ContactsFragment extends Fragment implements
+        LoaderManager.LoaderCallbacks<Cursor> {
+...
+    // Defines a ListView
+    private ListView mListView;
+    // Defines a ContactsAdapter
+    private ContactsAdapter mAdapter;
+    ...
+    // Defines a Cursor to contain the retrieved data
+    private Cursor mCursor;
+    /*
+     * Defines a projection based on platform version. This ensures
+     * that you retrieve the correct columns.
+     */
+    private static final String[] PROJECTION =
+            {
+                Contacts._ID,
+                Contacts.LOOKUP_KEY,
+                (Build.VERSION.SDK_INT >=
+                 Build.VERSION_CODES.HONEYCOMB) ?
+                        Contacts.DISPLAY_NAME_PRIMARY :
+                        Contacts.DISPLAY_NAME
+                (Build.VERSION.SDK_INT >=
+                 Build.VERSION_CODES.HONEYCOMB) ?
+                        Contacts.PHOTO_THUMBNAIL_ID :
+                        /*
+                         * Although it's not necessary to include the
+                         * column twice, this keeps the number of
+                         * columns the same regardless of version
+                         */
+                        Contacts_ID
+                ...
+            };
+    /*
+     * As a shortcut, defines constants for the
+     * column indexes in the Cursor. The index is
+     * 0-based and always matches the column order
+     * in the projection.
+     */
+    // Column index of the _ID column
+    private int mIdIndex = 0;
+    // Column index of the LOOKUP_KEY column
+    private int mLookupKeyIndex = 1;
+    // Column index of the display name column
+    private int mDisplayNameIndex = 3;
+    /*
+     * Column index of the photo data column.
+     * It's PHOTO_THUMBNAIL_URI for Honeycomb and later,
+     * and _ID for previous versions.
+     */
+    private int mPhotoDataIndex =
+            Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB ?
+            3 :
+            0;
+    ...
+
+

Set up the ListView

+

+ In {@link android.support.v4.app.Fragment#onCreate Fragment.onCreate()}, instantiate the custom + cursor adapter and get a handle to the {@link android.widget.ListView}: +

+
+    @Override
+    public void onCreate(Bundle savedInstanceState) {
+        ...
+        /*
+         * Instantiates the subclass of
+         * CursorAdapter
+         */
+        ContactsAdapter mContactsAdapter =
+                new ContactsAdapter(getActivity());
+        /*
+         * Gets a handle to the ListView in the file
+         * contact_list_layout.xml
+         */
+        mListView = (ListView) findViewById(R.layout.contact_list_layout);
+        ...
+    }
+    ...
+
+

+ In {@link android.support.v4.app.Fragment#onActivityCreated onActivityCreated()}, bind the + ContactsAdapter to the {@link android.widget.ListView}: +

+
+    @Override
+    public void onActivityCreated(Bundle savedInstanceState) {
+        ...
+        // Sets up the adapter for the ListView
+        mListView.setAdapter(mAdapter);
+        ...
+    }
+    ...
+
+

+ When you get back a {@link android.database.Cursor} containing the contacts data, usually in + {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onLoadFinished onLoadFinished()}, + call {@link android.support.v4.widget.CursorAdapter#swapCursor swapCursor()} to move the + {@link android.database.Cursor} data to the {@link android.widget.ListView}. This displays the + {@link android.widget.QuickContactBadge} for each entry in the list of contacts: +

+
+    public void onLoadFinished(Loader<Cursor> loader, Cursor cursor) {
+        // When the loader has completed, swap the cursor into the adapter.
+        mContactsAdapter.swapCursor(cursor);
+    }
+
+

+ When you bind a {@link android.database.Cursor} to a + {@link android.widget.ListView} with a {@link android.support.v4.widget.CursorAdapter} + (or subclass), and you use a {@link android.support.v4.content.CursorLoader} to load the + {@link android.database.Cursor}, always clear references to the {@link android.database.Cursor} + in your implementation of + {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onLoaderReset onLoaderReset()}. + For example: +

+
+    @Override
+    public void onLoaderReset(Loader<Cursor> loader) {
+        // Removes remaining reference to the previous Cursor
+        mContactsAdapter.swapCursor(null);
+    }
+
diff --git a/docs/html/training/contacts-provider/index.jd b/docs/html/training/contacts-provider/index.jd new file mode 100644 index 000000000000..f380d9562e8a --- /dev/null +++ b/docs/html/training/contacts-provider/index.jd @@ -0,0 +1,97 @@ +page.title=Accessing Contacts Data + +trainingnavtop=true +startpage=true + +@jd:body + +
+
+ + +

Dependencies and prerequisites

+
    +
  • Android 2.0 (API Level 5) or higher
    • +
  • Experience in using {@link android.content.Intent} objects
    • +
  • Experience in using content providers
    • +
+ + +

You should also read

+ + +

Try it out

+ +
+ + Download the sample + +

ContactsList.zip

+
+ +
+
+ +

+ The Contacts Provider is + the central repository of the user's contacts information, including data from contacts apps and + social networking apps. In your apps, you can access Contacts Provider information directly by + calling {@link android.content.ContentResolver} methods or by sending intents to a contacts app. +

+

+ This class focuses on retrieving lists of contacts, displaying the details for a particular + contact, and modifying contacts using intents. The basic techniques described + here can be extended to perform more complex tasks. In addition, this class helps you + understand the overall structure and operation of the + Contacts Provider. +

+

Lessons

+ +
+
+ Retrieving a List of Contacts +
+
+ Learn how to retrieve a list of contacts for which the data matches all or part of a search + string, using the following techniques: +
    +
  • Match by contact name
    • +
  • Match any type of contact data
    • +
  • Match a specific type of contact data, such as a phone number
    • +
+
+
+ Retrieving Details for a Contact +
+
+ Learn how to retrieve the details for a single contact. A contact's details are data + such as phone numbers and email addresses. You can retrieve all details, or you can + retrieve details of a specific type, such as all email addresses. +
+
+ Modifying Contacts Using Intents +
+
+ Learn how to modify a contact by sending an intent to the People app. +
+
+ + Displaying the Quick Contact Badge + +
+
+ Learn how to display the {@link android.widget.QuickContactBadge} widget. When the user + clicks the contact badge widget, a dialog opens that displays the contact's details and + action buttons for apps that can handle the details. For example, if the contact has an + email address, the dialog displays an action button for the default email app. +
+
diff --git a/docs/html/training/contacts-provider/modify-data.jd b/docs/html/training/contacts-provider/modify-data.jd new file mode 100644 index 000000000000..64853ef3a7b8 --- /dev/null +++ b/docs/html/training/contacts-provider/modify-data.jd @@ -0,0 +1,305 @@ +page.title=Modifying Contacts Using Intents +trainingnavtop=true +@jd:body +
+ +
+

+ This lesson shows you how to use an {@link android.content.Intent} to insert a new contact or + modify a contact's data. Instead of accessing the Contacts Provider directly, an + {@link android.content.Intent} starts the contacts app, which runs the appropriate + {@link android.app.Activity}. For the modification actions described in this lesson, + if you send extended data in the {@link android.content.Intent} it's entered into the UI of the + {@link android.app.Activity} that is started. +

+

+ Using an {@link android.content.Intent} to insert or update a single contact is the preferred + way of modifying the Contacts Provider, for the following reasons: +

+ +

Insert a New Contact Using an Intent

+

+ You often want to allow the user to insert a new contact when your app receives new data. For + example, a restaurant review app can allow users to add the restaurant as a contact as they're + reviewing it. To do this using an intent, create the intent using as much data as you have + available, and then send the intent to the contacts app. +

+

+ Inserting a contact using the contacts app inserts a new raw contact into the Contacts + Provider's {@link android.provider.ContactsContract.RawContacts} table. If necessary, + the contacts app prompts users for the account type and account to use when creating the raw + contact. The contacts app also notifies users if the raw contact already exists. Users then have + option of canceling the insertion, in which case no contact is created. To learn + more about raw contacts, see the + Contacts Provider + API guide. +

+ +

Create an Intent

+

+ To start, create a new {@link android.content.Intent} object with the action + {@link android.provider.ContactsContract.Intents.Insert#ACTION Intents.Insert.ACTION}. + Set the MIME type to {@link android.provider.ContactsContract.RawContacts#CONTENT_TYPE + RawContacts.CONTENT_TYPE}. For example: +

+
+...
+// Creates a new Intent to insert a contact
+Intent intent = new Intent(Intents.Insert.ACTION);
+// Sets the MIME type to match the Contacts Provider
+intent.setType(ContactsContract.RawContacts.CONTENT_TYPE);
+
+

+ If you already have details for the contact, such as a phone number or email address, you can + insert them into the intent as extended data. For a key value, use the appropriate constant from + {@link android.provider.ContactsContract.Intents.Insert Intents.Insert}. The contacts app + displays the data in its insert screen, allowing users to make further edits and additions. +

+
+/* Assumes EditText fields in your UI contain an email address
+ * and a phone number.
+ *
+ */
+private EditText mEmailAddress = (EditText) findViewById(R.id.email);
+private EditText mPhoneNumber = (EditText) findViewById(R.id.phone);
+...
+/*
+ * Inserts new data into the Intent. This data is passed to the
+ * contacts app's Insert screen
+ */
+// Inserts an email address
+intent.putExtra(Intents.Insert.EMAIL, mEmailAddress.getText())
+/*
+ * In this example, sets the email type to be a work email.
+ * You can set other email types as necessary.
+ */
+      .putExtra(Intents.Insert.EMAIL_TYPE, CommonDataKinds.Email.TYPE_WORK)
+// Inserts a phone number
+      .putExtra(Intents.Insert.PHONE, mPhoneNumber.getText())
+/*
+ * In this example, sets the phone type to be a work phone.
+ * You can set other phone types as necessary.
+ */
+      .putExtra(Intents.Insert.PHONE_TYPE, Phone.TYPE_WORK);
+
+
+

+ Once you've created the {@link android.content.Intent}, send it by calling + {@link android.support.v4.app.Fragment#startActivity startActivity()}. +

+
+    /* Sends the Intent
+     */
+    startActivity(intent);
+
+

+ This call opens a screen in the contacts app that allows users to enter a new contact. The + account type and account name for the contact is listed at the top of the screen. Once users + enter the data and click Done, the contacts app's contact list appears. Users return to + your app by clicking Back. +

+

Edit an Existing Contact Using an Intent

+

+ Editing an existing contact using an {@link android.content.Intent} is useful if the user + has already chosen a contact of interest. For example, an app that finds contacts that have + postal addresses but lack a postal code could give users the option of looking up the code and + then adding it to the contact. +

+

+ To edit an existing contact using an intent, use a procedure similar to + inserting a contact. Create an intent as described in the section + Insert a New Contact Using an Intent, but add the contact's + {@link android.provider.ContactsContract.Contacts#CONTENT_LOOKUP_URI + Contacts.CONTENT_LOOKUP_URI} and the MIME type + {@link android.provider.ContactsContract.Contacts#CONTENT_ITEM_TYPE + Contacts.CONTENT_ITEM_TYPE} to the intent. If you want to edit the contact with details you + already have, you can put them in the intent's extended data. Notice that some + name columns can't be edited using an intent; these columns are listed in the summary + section of the API reference for the class {@link android.provider.ContactsContract.Contacts} + under the heading "Update". +

+

+ Finally, send the intent. In response, the contacts app displays an edit screen. When the user + finishes editing and saves the edits, the contacts app displays a contact list. When the user + clicks Back, your app is displayed. +

+
+
+

Contacts Lookup Key

+

+ A contact's {@link android.provider.ContactsContract.ContactsColumns#LOOKUP_KEY} value is + the identifier that you should use to retrieve a contact. It remains constant, + even if the provider changes the contact's row ID to handle internal operations. +

+
+
+

Create the Intent

+

+ To edit a contact, call {@link android.content.Intent#Intent Intent(action)} to + create an intent with the action {@link android.content.Intent#ACTION_EDIT}. Call + {@link android.content.Intent#setDataAndType setDataAndType()} to set the data value for the + intent to the contact's {@link android.provider.ContactsContract.Contacts#CONTENT_LOOKUP_URI + Contacts.CONTENT_LOOKUP_URI} and the MIME type to + {@link android.provider.ContactsContract.Contacts#CONTENT_ITEM_TYPE + Contacts.CONTENT_ITEM_TYPE} MIME type; because a call to + {@link android.content.Intent#setType setType()} overwrites the current data value for the + {@link android.content.Intent}, you must set the data and the MIME type at the same time. +

+

+ To get a contact's {@link android.provider.ContactsContract.Contacts#CONTENT_LOOKUP_URI + Contacts.CONTENT_LOOKUP_URI}, call + {@link android.provider.ContactsContract.Contacts#getLookupUri + Contacts.getLookupUri(id, lookupkey)} with the contact's + {@link android.provider.ContactsContract.Contacts#_ID Contacts._ID} and + {@link android.provider.ContactsContract.Contacts#LOOKUP_KEY Contacts.LOOKUP_KEY} values as + arguments. +

+

+ The following snippet shows you how to create an intent: +

+
+    // The Cursor that contains the Contact row
+    public Cursor mCursor;
+    // The index of the lookup key column in the cursor
+    public int mLookupKeyIndex;
+    // The index of the contact's _ID value
+    public int mIdIndex;
+    // The lookup key from the Cursor
+    public String mCurrentLookupKey;
+    // The _ID value from the Cursor
+    public long mCurrentId;
+    // A content URI pointing to the contact
+    Uri mSelectedContactUri;
+    ...
+    /*
+     * Once the user has selected a contact to edit,
+     * this gets the contact's lookup key and _ID values from the
+     * cursor and creates the necessary URI.
+     */
+    // Gets the lookup key column index
+    mLookupKeyIndex = mCursor.getColumnIndex(Contacts.LOOKUP_KEY);
+    // Gets the lookup key value
+    mCurrentLookupKey = mCursor.getString(mLookupKeyIndex);
+    // Gets the _ID column index
+    mIdIndex = mCursor.getColumnIndex(Contacts._ID);
+    mCurrentId = mCursor.getLong(mIdIndex);
+    mSelectedContactUri =
+            Contacts.getLookupUri(mCurrentId, mCurrentLookupKey);
+    ...
+    // Creates a new Intent to edit a contact
+    Intent editIntent = new Intent(Intent.ACTION_EDIT);
+    /*
+     * Sets the contact URI to edit, and the data type that the
+     * Intent must match
+     */
+    editIntent.setDataAndType(mSelectedContactUri,Contacts.CONTENT_ITEM_TYPE);
+
+

Add the navigation flag

+

+ In Android 4.0 (API version 14) and later, a problem in the contacts app causes incorrect + navigation. When your app sends an edit intent to the contacts app, and users edit and save a + contact, when they click Back they see the contacts list screen. To navigate back to + your app, they have to click Recents and choose your app. +

+

+ To work around this problem in Android 4.0.3 (API version 15) and later, add the extended + data key {@code finishActivityOnSaveCompleted} to the intent, with a value of {@code true}. + Android versions prior to Android 4.0 accept this key, but it has no effect. To set the + extended data, do the following: +

+
+    // Sets the special extended data for navigation
+    editIntent.putExtra("finishActivityOnSaveCompleted", true);
+
+

Add other extended data

+

+ To add additional extended data to the {@link android.content.Intent}, call + {@link android.content.Intent#putExtra putExtra()} as desired. + You can add extended data for common contact fields by using the key values specified in + {@link android.provider.ContactsContract.Intents.Insert Intents.Insert}. Remember that some + columns in the {@link android.provider.ContactsContract.Contacts} table can't be modified. + These columns are listed in the summary section of the API reference for the class + {@link android.provider.ContactsContract.Contacts} under the heading "Update". +

+ +

Send the Intent

+

+ Finally, send the intent you've constructed. For example: +

+
+    // Sends the Intent
+    startActivity(editIntent);
+
+

Let Users Choose to Insert or Edit Using an Intent

+

+ You can allow users to choose whether to insert a contact or edit an existing one by sending + an {@link android.content.Intent} with the action + {@link android.content.Intent#ACTION_INSERT_OR_EDIT}. For example, an email client app could + allow users to add an incoming email address to a new contact, or add it as an additional + address for an existing contact. Set the MIME type for this intent to + {@link android.provider.ContactsContract.Contacts#CONTENT_ITEM_TYPE Contacts.CONTENT_ITEM_TYPE}, + but don't set the data URI. +

+

+ When you send this intent, the contacts app displays a list of contacts. + Users can either insert a new contact or pick an existing contact and edit it. + Any extended data fields you add to the intent populates the screen that appears. You can use + any of the key values specified in {@link android.provider.ContactsContract.Intents.Insert + Intents.Insert}. The following code snippet shows how to construct and send the intent: +

+
+    // Creates a new Intent to insert or edit a contact
+    Intent intentInsertEdit = new Intent(Intent.ACTION_INSERT_OR_EDIT);
+    // Sets the MIME type
+    intentInsertEdit.setType(Contacts.CONTENT_ITEM_TYPE);
+    // Add code here to insert extended data, if desired
+    ...
+    // Sends the Intent with an request ID
+    startActivity(intentInsertEdit);
+
diff --git a/docs/html/training/contacts-provider/retrieve-details.jd b/docs/html/training/contacts-provider/retrieve-details.jd new file mode 100644 index 000000000000..0de3b6750be4 --- /dev/null +++ b/docs/html/training/contacts-provider/retrieve-details.jd @@ -0,0 +1,378 @@ +page.title=Retrieving Details for a Contact + +trainingnavtop=true +@jd:body + +
+
+ + +

This lesson teaches you to

+
    +
  1. Retrieve All Details for a Contact
    2. +
  2. Retrieve Specific Details for a Contact
    3. +
+ + +

You should also read

+ + +

Try it out

+ +
+ + Download the sample + +

ContactsList.zip

+
+ +
+
+

+ This lesson shows how to retrieve detail data for a contact, such as email addresses, phone + numbers, and so forth. It's the details that users are looking for when they retrieve a contact. + You can give them all the details for a contact, or only display details of a particular type, + such as email addresses. +

+

+ The steps in this lesson assume that you already have a + {@link android.provider.ContactsContract.Contacts} row for a contact the user has picked. + The Retrieving Contact Names lesson shows how to + retrieve a list of contacts. +

+

Retrieve All Details for a Contact

+

+ To retrieve all the details for a contact, search the + {@link android.provider.ContactsContract.Data} table for any rows that contain the contact's + {@link android.provider.ContactsContract.Data#LOOKUP_KEY}. This column is available in + the {@link android.provider.ContactsContract.Data} table, because the Contacts + Provider makes an implicit join between the {@link android.provider.ContactsContract.Contacts} + table and the {@link android.provider.ContactsContract.Data} table. The + {@link android.provider.ContactsContract.Contacts#LOOKUP_KEY} column is described + in more detail in the Retrieving Contact Names lesson. +

+

+ Note: Retrieving all the details for a contact reduces the performance of a + device, because it needs to retrieve all of the columns in the + {@link android.provider.ContactsContract.Data} table. Consider the performance impact before + you use this technique. +

+

Request permissions

+

+ To read from the Contacts Provider, your app must have + {@link android.Manifest.permission#READ_CONTACTS READ_CONTACTS} permission. + To request this permission, add the following child element of + + <manifest> to your manifest file: +

+
+    <uses-permission android:name="android.permission.READ_CONTACTS" />
+
+

Set up a projection

+

+ Depending on the data type a row contains, it may use only a few columns or many. In addition, + the data is in different columns depending on the data type. + To ensure you get all the possible columns for all possible data types, you need to add all the + column names to your projection. Always retrieve + {@link android.provider.ContactsContract.Data#_ID Data._ID} if you're binding the result + {@link android.database.Cursor} to a {@link android.widget.ListView}; otherwise, the binding + won't work. Also retrieve {@link android.provider.ContactsContract.Data#MIMETYPE Data.MIMETYPE} + so you can identify the data type of each row you retrieve. For example: +

+
+    private static final String PROJECTION =
+            {
+                Data._ID,
+                Data.MIMETYPE,
+                Data.DATA1,
+                Data.DATA2,
+                Data.DATA3,
+                Data.DATA4,
+                Data.DATA5,
+                Data.DATA6,
+                Data.DATA7,
+                Data.DATA8,
+                Data.DATA9,
+                Data.DATA10,
+                Data.DATA11,
+                Data.DATA12,
+                Data.DATA13,
+                Data.DATA14,
+                Data.DATA15
+            };
+
+

+ This projection retrieves all the columns for a row in the + {@link android.provider.ContactsContract.Data} table, using the column names defined in + the {@link android.provider.ContactsContract.Data} class. +

+

+ Optionally, you can also use any other column constants defined in or inherited by the + {@link android.provider.ContactsContract.Data} class. Notice, however, that the columns + {@link android.provider.ContactsContract.DataColumns#SYNC1} through + {@link android.provider.ContactsContract.DataColumns#SYNC4} are meant to be used by sync + adapters, so their data is not useful. +

+

Define the selection criteria

+

+ Define a constant for your selection clause, an array to hold selection arguments, and a + variable to hold the selection value. Use + the {@link android.provider.ContactsContract.Contacts#LOOKUP_KEY Contacts.LOOKUP_KEY} column to + find the contact. For example: +

+
+    // Defines the selection clause
+    private static final String SELECTION = Data.LOOKUP_KEY + " = ?";
+    // Defines the array to hold the search criteria
+    private String[] mSelectionArgs = { "" };
+    /*
+     * Defines a variable to contain the selection value. Once you
+     * have the Cursor from the Contacts table, and you've selected
+     * the desired row, move the row's LOOKUP_KEY value into this
+     * variable.
+     */
+    private String mLookupKey;
+
+

+ Using "?" as a placeholder in your selection text expression ensures that the resulting search + is generated by binding rather than SQL compilation. This approach eliminates the + possibility of malicious SQL injection. +

+

Define the sort order

+

+ Define the sort order you want in the resulting {@link android.database.Cursor}. To + keep all rows for a particular data type together, sort by + {@link android.provider.ContactsContract.Data#MIMETYPE Data.MIMETYPE}. This query argument + groups all email rows together, all phone rows together, and so forth. For example: +

+
+    /*
+     * Defines a string that specifies a sort order of MIME type
+     */
+    private static final String SORT_ORDER = Data.MIMETYPE;
+
+

+ Note: Some data types don't use a subtype, so you can't sort on subtype. + Instead, you have to iterate through the returned {@link android.database.Cursor}, + determine the data type of the current row, and store data for rows that use a subtype. When + you finish reading the cursor, you can then sort each data type by subtype and display the + results. +

+

Initialize the Loader

+

+ Always do retrievals from the Contacts Provider (and all other content providers) in a + background thread. Use the Loader framework defined by the + {@link android.support.v4.app.LoaderManager} class and the + {@link android.support.v4.app.LoaderManager.LoaderCallbacks} interface to do background + retrievals. +

+

+ When you're ready to retrieve the rows, initialize the loader framework by + calling {@link android.support.v4.app.LoaderManager#initLoader initLoader()}. Pass an + integer identifier to the method; this identifier is passed to + {@link android.support.v4.app.LoaderManager.LoaderCallbacks} methods. The identifier helps you + use multiple loaders in an app by allowing you to differentiate between them. +

+

+ The following snippet shows how to initialize the loader framework: +

+
+public class DetailsFragment extends Fragment implements
+        LoaderManager.LoaderCallbacks<Cursor> {
+    ...
+    // Defines a constant that identifies the loader
+    DETAILS_QUERY_ID = 0;
+    ...
+    /*
+     * Invoked when the parent Activity is instantiated
+     * and the Fragment's UI is ready. Put final initialization
+     * steps here.
+     */
+    @Override
+    onActivityCreated(Bundle savedInstanceState) {
+        ...
+        // Initializes the loader framework
+        getLoaderManager().initLoader(DETAILS_QUERY_ID, null, this);
+
+

Implement onCreateLoader()

+

+ Implement the {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onCreateLoader + onCreateLoader()} method, which is called by the loader framework immediately after you call + {@link android.support.v4.app.LoaderManager#initLoader initLoader()}. Return a + {@link android.support.v4.content.CursorLoader} from this method. Since you're searching + the {@link android.provider.ContactsContract.Data} table, use the constant + {@link android.provider.ContactsContract.Data#CONTENT_URI Data.CONTENT_URI} as the content URI. + For example: +

+
+    @Override
+    public Loader<Cursor> onCreateLoader(int loaderId, Bundle args) {
+        // Choose the proper action
+        switch (loaderId) {
+            case DETAILS_QUERY_ID:
+            // Assigns the selection parameter
+            mSelectionArgs[0] = mLookupKey;
+            // Starts the query
+            CursorLoader mLoader =
+                    new CursorLoader(
+                            getActivity(),
+                            Data.CONTENT_URI,
+                            PROJECTION,
+                            SELECTION,
+                            mSelectionArgs,
+                            SORT_ORDER
+                    );
+            ...
+    }
+
+

Implement onLoadFinished() and onLoaderReset()

+

+ Implement the + {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onLoadFinished onLoadFinished()} + method. The loader framework calls + {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onLoadFinished onLoadFinished()} + when the Contacts Provider returns the results of the query. For example: +

+
+    public void onLoadFinished(Loader<Cursor> loader, Cursor cursor) {
+        switch (loader.getId()) {
+            case DETAILS_QUERY_ID:
+                    /*
+                     * Process the resulting Cursor here.
+                     */
+                }
+                break;
+            ...
+        }
+    }
+
+

+

+ The method {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onLoaderReset + onLoaderReset()} is invoked when the loader framework detects that the data backing the result + {@link android.database.Cursor} has changed. At this point, remove any existing references + to the {@link android.database.Cursor} by setting them to null. If you don't, the loader + framework won't destroy the old {@link android.database.Cursor}, and you'll get a memory + leak. For example: +

+    @Override
+    public void onLoaderReset(Loader<Cursor> loader) {
+        switch (loader.getId()) {
+            case DETAILS_QUERY_ID:
+                /*
+                 * If you have current references to the Cursor,
+                 * remove them here.
+                 */
+                }
+                break;
+    }
+
+

Retrieve Specific Details for a Contact

+

+ Retrieving a specific data type for a contact, such as all the emails, follows the same pattern + as retrieving all details. These are the only changes you need to make to the code + listed in Retrieve All Details for a Contact: +

+
+
+ Projection +
+
+ Modify your projection to retrieve the columns that are specific to the + data type. Also modify the projection to use the column name constants defined in the + {@link android.provider.ContactsContract.CommonDataKinds} subclass corresponding to the + data type. +
+
+ Selection +
+
+ Modify the selection text to search for the + {@link android.provider.ContactsContract.Data#MIMETYPE MIMETYPE} value that's specific to + your data type. +
+
+ Sort order +
+
+ Since you're only selecting a single detail type, don't group the returned + {@link android.database.Cursor} by {@link android.provider.ContactsContract.Data#MIMETYPE + Data.MIMETYPE}. +
+
+

+ These modifications are described in the following sections. +

+

Define a projection

+

+ Define the columns you want to retrieve, using the column name constants in the subclass + of {@link android.provider.ContactsContract.CommonDataKinds} for the data type. + If you plan to bind your {@link android.database.Cursor} to a {@link android.widget.ListView}, + be sure to retrieve the _ID column. For example, to retrieve email data, define the + following projection: +

+
+    private static final String[] PROJECTION =
+            {
+                Email._ID,
+                Email.ADDRESS,
+                Email.TYPE,
+                Email.LABEL
+            };
+
+

+ Notice that this projection uses the column names defined in the class + {@link android.provider.ContactsContract.CommonDataKinds.Email}, instead of the column names + defined in the class {@link android.provider.ContactsContract.Data}. Using the email-specific + column names makes the code more readable. +

+

+ In the projection, you can also use any of the other columns defined in the + {@link android.provider.ContactsContract.CommonDataKinds} subclass. +

+

Define selection criteria

+

+ Define a search text expression that retrieves rows for a specific contact's + {@link android.provider.ContactsContract.Data#LOOKUP_KEY} and the + {@link android.provider.ContactsContract.Data#MIMETYPE Data.MIMETYPE} of the details you + want. Enclose the {@link android.provider.ContactsContract.Data#MIMETYPE MIMETYPE} value in + single quotes by concatenating a "'" (single-quote) character to the start and end + of the constant; otherwise, the provider interprets the constant as a variable name rather + than as a string value. You don't need to use a placeholder for this value, because you're + using a constant rather than a user-supplied value. For example: +

+
+    /*
+     * Defines the selection clause. Search for a lookup key
+     * and the Email MIME type
+     */
+    private static final String SELECTION =
+            Data.LOOKUP_KEY + " = ?" +
+            " AND " +
+            Data.MIMETYPE + " = " +
+            "'" + Email.CONTENT_ITEM_TYPE + "'";
+    // Defines the array to hold the search criteria
+    private String[] mSelectionArgs = { "" };
+
+

Define a sort order

+

+ Define a sort order for the returned {@link android.database.Cursor}. Since you're retrieving a + specific data type, omit the sort on {@link android.provider.ContactsContract.Data#MIMETYPE}. + Instead, if the type of detail data you're searching includes a subtype, sort on it. + For example, for email data you can sort on + {@link android.provider.ContactsContract.CommonDataKinds.Email#TYPE Email.TYPE}: +

+
+    private static final String SORT_ORDER = Email.TYPE + " ASC ";
+
diff --git a/docs/html/training/contacts-provider/retrieve-names.jd b/docs/html/training/contacts-provider/retrieve-names.jd new file mode 100644 index 000000000000..b034a6a26d40 --- /dev/null +++ b/docs/html/training/contacts-provider/retrieve-names.jd @@ -0,0 +1,815 @@ +page.title=Retrieving a List of Contacts + +trainingnavtop=true +@jd:body + +
+ +
+

+ This lesson shows you how to retrieve a list of contacts whose data matches all or part of a + search string, using the following techniques: +

+
+
Match contact names
+
+ Retrieve a list of contacts by matching the search string to all or part of the contact + name data. The Contacts Provider allows multiple instances of the same name, so this + technique can return a list of matches. +
+
Match a specific type of data, such as a phone number
+
+ Retrieve a list of contacts by matching the search string to a particular type of detail + data such as an email address. For example, this technique allows you to list all of the + contacts whose email address matches the search string. +
+
Match any type of data
+
+ Retrieve a list of contacts by matching the search string to any type of detail data, + including name, phone number, street address, email address, and so forth. For example, + this technique allows you to accept any type of data for a search string and then list the + contacts for which the data matches the string. +
+
+

+ Note: All the examples in this lesson use a + {@link android.support.v4.content.CursorLoader} to retrieve data from the Contacts + Provider. A {@link android.support.v4.content.CursorLoader} runs its query on a + thread that's separate from the UI thread. This ensures that the query doesn't slow down UI + response times and cause a poor user experience. For more information, see the Android + training class + Loading Data in the Background. +

+

Request Permission to Read the Provider

+

+ To do any type of search of the Contacts Provider, your app must have + {@link android.Manifest.permission#READ_CONTACTS READ_CONTACTS} permission. + To request this, add this +<uses-permission> + element to your manifest file as a child element of +<manifest>: +

+
+    <uses-permission android:name="android.permission.READ_CONTACTS" />
+
+

Match a Contact by Name and List the Results

+

+ This technique tries to match a search string to the name of a contact or contacts in the + Contact Provider's {@link android.provider.ContactsContract.Contacts} table. You usually want + to display the results in a {@link android.widget.ListView}, to allow the user to choose among + the matched contacts. +

+

Define ListView and item layouts

+

+ To display the search results in a {@link android.widget.ListView}, you need a main layout file + that defines the entire UI including the {@link android.widget.ListView}, and an item layout + file that defines one line of the {@link android.widget.ListView}. For example, you can define + the main layout file res/layout/contacts_list_view.xml that contains the + following XML: +

+
+<?xml version="1.0" encoding="utf-8"?>
+<ListView xmlns:android="http://schemas.android.com/apk/res/android"
+          android:id="@android:id/list"
+          android:layout_width="match_parent"
+          android:layout_height="match_parent"/>
+
+

+ This XML uses the built-in Android {@link android.widget.ListView} widget + {@link android.R.id#list android:id/list}. +

+

+ Define the item layout file contacts_list_item.xml with the following XML: +

+
+<?xml version="1.0" encoding="utf-8"?>
+<TextView xmlns:android="http://schemas.android.com/apk/res/android"
+          android:id="@android:id/text1"
+          android:layout_width="match_parent"
+          android:layout_height="wrap_content"
+          android:clickable="true"/>
+
+

+ This XML uses the built-in Android {@link android.widget.TextView} widget + {@link android.R.id#text1 android:text1}. +

+

+ Note: This lesson doesn't describe the UI for getting a search string from the + user, because you may want to get the string indirectly. For example, you can give the user + an option to search for contacts whose name matches a string in an incoming text message. +

+

+ The two layout files you've written define a user interface that shows a + {@link android.widget.ListView}. The next step is to write code that uses this UI to display a + list of contacts. +

+

Define a Fragment that displays the list of contacts

+

+ To display the list of contacts, start by defining a {@link android.support.v4.app.Fragment} + that's loaded by an {@link android.app.Activity}. Using a + {@link android.support.v4.app.Fragment} is a more flexible technique, because you can use + one {@link android.support.v4.app.Fragment} to display the list and a second + {@link android.support.v4.app.Fragment} to display the details for a contact that the user + chooses from the list. Using this approach, you can combine one of the techniques presented in + this lesson with one from the lesson + Retrieving Details for a Contact. +

+

+ To learn how to use one or more {@link android.support.v4.app.Fragment} objects from an + an {@link android.app.Activity}, read the training class + + Building a Dynamic UI with Fragments. +

+

+ To help you write queries against the Contacts Provider, the Android framework provides a + contracts class called {@link android.provider.ContactsContract}, which defines useful + constants and methods for accessing the provider. When you use this class, you don't have to + define your own constants for content URIs, table names, or columns. To use this class, + include the following statement: +

+
+import android.provider.ContactsContract;
+
+

+ Since the code uses a {@link android.support.v4.content.CursorLoader} to retrieve data + from the provider, you must specify that it implements the loader interface + {@link android.support.v4.app.LoaderManager.LoaderCallbacks}. Also, to help detect which contact + the user selects from the list of search results, implement the adapter interface + {@link android.widget.AdapterView.OnItemClickListener}. For example: +

+
+...
+import android.support.v4.app.Fragment;
+import android.support.v4.app.LoaderManager.LoaderCallbacks;
+import android.widget.AdapterView;
+...
+public class ContactsFragment extends Fragment implements
+        LoaderManager.LoaderCallbacks<Cursor>,
+        AdapterView.OnItemClickListener {
+
+

Define global variables

+

+ Define global variables that are used in other parts of the code: +

+
+    ...
+    /*
+     * Defines an array that contains column names to move from
+     * the Cursor to the ListView.
+     */
+    @SuppressLint("InlinedApi")
+    private final static String[] FROM_COLUMNS = {
+            Build.VERSION.SDK_INT
+                    >= Build.VERSION_CODES.HONEYCOMB ?
+                    Contacts.DISPLAY_NAME_PRIMARY :
+                    Contacts.DISPLAY_NAME
+    };
+    /*
+     * Defines an array that contains resource ids for the layout views
+     * that get the Cursor column contents. The id is pre-defined in
+     * the Android framework, so it is prefaced with "android.R.id"
+     */
+    private final static int[] TO_IDS = {
+           android.R.id.text1
+    };
+    // Define global mutable variables
+    // Define a ListView object
+    ListView mContactsList;
+    // Define variables for the contact the user selects
+    // The contact's _ID value
+    long mContactId;
+    // The contact's LOOKUP_KEY
+    String mContactKey;
+    // A content URI for the selected contact
+    Uri mContactUri;
+    // An adapter that binds the result Cursor to the ListView
+    private SimpleCursorAdapter mCursorAdapter;
+    ...
+
+

+ Note: Since + {@link android.provider.ContactsContract.Contacts#DISPLAY_NAME_PRIMARY + Contacts.DISPLAY_NAME_PRIMARY} requires Android 3.0 (API version 11) or later, setting your + app's minSdkVersion to 10 or below generates an Android Lint warning in + Eclipse with ADK. To turn off this warning, add the annotation + @SuppressLint("InlinedApi") before the definition of FROM_COLUMNS. +

+

Initialize the Fragment

+

+ + Initialize the {@link android.support.v4.app.Fragment}. Add the empty, public constructor + required by the Android system, and inflate the {@link android.support.v4.app.Fragment} object's + UI in the callback method {@link android.support.v4.app.Fragment#onCreateView onCreateView()}. + For example: +

+
+    // Empty public constructor, required by the system
+    public ContactsFragment() {}
+
+    // A UI Fragment must inflate its View
+    @Override
+    public View onCreateView(LayoutInflater inflater, ViewGroup container,
+            Bundle savedInstanceState) {
+        // Inflate the fragment layout
+        return inflater.inflate(R.layout.contacts_list_layout, container, false);
+    }
+
+

Set up the CursorAdapter for the ListView

+

+ Set up the {@link android.support.v4.widget.SimpleCursorAdapter} that binds the results of the + search to the {@link android.widget.ListView}. To get the {@link android.widget.ListView} object + that displays the contacts, you need to call {@link android.app.Activity#findViewById + Activity.findViewById()} using the parent activity of the + {@link android.support.v4.app.Fragment}. Use the {@link android.content.Context} of the + parent activity when you call {@link android.widget.ListView#setAdapter setAdapter()}. + For example: +

+
+    public void onActivityCreated(Bundle savedInstanceState) {
+        super.onActivityCreated(savedInstanceState);
+        ...
+        // Gets the ListView from the View list of the parent activity
+        mContactsList = (ListView) getActivity().findViewById(R.layout.contact_list_view);
+        // Gets a CursorAdapter
+        mCursorAdapter = new SimpleCursorAdapter(
+                getActivity(),
+                R.layout.contact_list_item,
+                null,
+                FROM_COLUMNS, TO_IDS,
+                0);
+        // Sets the adapter for the ListView
+        mContactsList.setAdapter(mCursorAdapter);
+    }
+
+

Set the selected contact listener

+

+ When you display the results of a search, you usually want to allow the user to select a + single contact for further processing. For example, when the user clicks a contact you can + display the contact's address on a map. To provide this feature, you first defined the current + {@link android.support.v4.app.Fragment} as the click listener by specifying that the class + implements {@link android.widget.AdapterView.OnItemClickListener}, as shown in the section + Define a Fragment that displays the list of contacts. +

+

+ To continue setting up the listener, bind it to the {@link android.widget.ListView} by + calling the method {@link android.widget.ListView#setOnItemClickListener + setOnItemClickListener()} in {@link android.support.v4.app.Fragment#onActivityCreated + onActivityCreated()}. For example: +

+
+    public void onActivityCreated(Bundle savedInstanceState) {
+        ...
+        // Set the item click listener to be the current fragment.
+        mContactsList.setOnItemClickListener(this);
+        ...
+    }
+
+

+ Since you specified that the current {@link android.support.v4.app.Fragment} is the + {@link android.widget.AdapterView.OnItemClickListener OnItemClickListener} for the + {@link android.widget.ListView}, you now need to implement its required method + {@link android.widget.AdapterView.OnItemClickListener#onItemClick onItemClick()}, which + handles the click event. This is described in a succeeding section. +

+

Define a projection

+

+ Define a constant that contains the columns you want to return from your query. Each item in + the {@link android.widget.ListView} displays the contact's display name, + which contains the main form of the contact's name. In Android 3.0 (API version 11) and later, + the name of this column is + {@link android.provider.ContactsContract.Contacts#DISPLAY_NAME_PRIMARY + Contacts.DISPLAY_NAME_PRIMARY}; in versions previous to that, its name is + {@link android.provider.ContactsContract.Contacts#DISPLAY_NAME Contacts.DISPLAY_NAME}. +

+

+ The column {@link android.provider.ContactsContract.Contacts#_ID Contacts._ID} is used by the + {@link android.support.v4.widget.SimpleCursorAdapter} binding process. + {@link android.provider.ContactsContract.Contacts#_ID Contacts._ID} and + {@link android.provider.ContactsContract.Contacts#LOOKUP_KEY} are used together to + construct a content URI for the contact the user selects. +

+
+...
+@SuppressLint("InlinedApi")
+private static final String[] PROJECTION =
+        {
+            Contacts._ID,
+            Contacts.LOOKUP_KEY,
+            Build.VERSION.SDK_INT
+                    >= Build.VERSION_CODES.HONEYCOMB ?
+                    Contacts.DISPLAY_NAME_PRIMARY :
+                    Contacts.DISPLAY_NAME
+
+        };
+
+

Define constants for the Cursor column indexes

+

+ To get data from an individual column in a {@link android.database.Cursor}, you need + the column's index within the {@link android.database.Cursor}. You can define constants + for the indexes of the {@link android.database.Cursor} columns, because the indexes are + the same as the order of the column names in your projection. For example: +

+
+// The column index for the _ID column
+private static final int CONTACT_ID_INDEX = 0;
+// The column index for the LOOKUP_KEY column
+private static final int LOOKUP_KEY_INDEX = 1;
+
+

Specify the selection criteria

+

+ To specify the data you want, create a combination of text expressions and variables + that tell the provider the data columns to search and the values to find. +

+

+ For the text expression, define a constant that lists the search columns. Although this + expression can contain values as well, the preferred practice is to represent the values with + a "?" placeholder. During retrieval, the placeholder is replaced with values from an + array. Using "?" as a placeholder ensures that the search specification is generated by binding + rather than by SQL compilation. This practice eliminates the possibility of malicious SQL + injection. For example: +

+
+    // Defines the text expression
+    @SuppressLint("InlinedApi")
+    private static final String SELECTION =
+            Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB ?
+            Contacts.DISPLAY_NAME_PRIMARY + " LIKE ?" :
+            Contacts.DISPLAY_NAME + " LIKE ?";
+    // Defines a variable for the search string
+    private String mSearchString;
+    // Defines the array to hold values that replace the ?
+    private String[] mSelectionArgs = { mSearchString };
+
+

Define the onItemClick() method

+

+ In a previous section, you set the item click listener for the {@link android.widget.ListView}. + Now implement the action for the listener by defining the method + {@link android.widget.AdapterView.OnItemClickListener#onItemClick + AdapterView.OnItemClickListener.onItemClick()}: +

+
+    @Override
+    public void onItemClick(
+        AdapterView<?> parent, View item, int position, long rowID) {
+        // Get the Cursor
+        Cursor cursor = parent.getAdapter().getCursor();
+        // Move to the selected contact
+        cursor.moveToPosition(position);
+        // Get the _ID value
+        mContactId = getLong(CONTACT_ID_INDEX);
+        // Get the selected LOOKUP KEY
+        mContactKey = getString(CONTACT_KEY_INDEX);
+        // Create the contact's content Uri
+        mContactUri = Contacts.getLookupUri(mContactId, mContactKey);
+        /*
+         * You can use mContactUri as the content URI for retrieving
+         * the details for a contact.
+         */
+    }
+
+

Initialize the loader

+

+ Since you're using a {@link android.support.v4.content.CursorLoader} to retrieve data, + you must initialize the background thread and other variables that control asynchronous + retrieval. Do the initialization in + {@link android.support.v4.app.Fragment#onActivityCreated onActivityCreated()}, which + is invoked immediately before the {@link android.support.v4.app.Fragment} UI appears, as + shown in the following example: +

+
+public class ContactsFragment extends Fragment implements
+        LoaderManager.LoaderCallbacks<Cursor> {
+    ...
+    // Called just before the Fragment displays its UI
+    @Override
+    public void onActivityCreated(Bundle savedInstanceState) {
+        // Always call the super method first
+        super.onActivityCreated(savedInstanceState);
+        ...
+        // Initializes the loader
+        getLoaderManager().initLoader(0, null, this);
+
+

Implement onCreateLoader()

+

+ Implement the method + {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()}, + which is called by the loader framework immediately after you call + {@link android.support.v4.app.LoaderManager#initLoader initLoader()}. +

+ In {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()}, + set up the search string pattern. To make a string into a pattern, insert "%" + (percent) characters to represent a sequence of zero or more characters, or "_" (underscore) + characters to represent a single character, or both. For example, the pattern "%Jefferson%" + would match both "Thomas Jefferson" and "Jefferson Davis". +

+

+ Return a new {@link android.support.v4.content.CursorLoader} from the method. For the content + URI, use {@link android.provider.ContactsContract.Contacts#CONTENT_URI Contacts.CONTENT_URI}. + This URI refers to the entire table, as shown in the following example: +

+
+    ...
+    @Override
+    public Loader<Cursor> onCreateLoader(int loaderId, Bundle args) {
+        /*
+         * Makes search string into pattern and
+         * stores it in the selection array
+         */
+        mSelectionArgs[0] = "%" + mSearchString + "%";
+        // Starts the query
+        return new CursorLoader(
+                getActivity(),
+                Contacts.CONTENT_URI,
+                PROJECTION,
+                SELECTION,
+                mSelectionArgs,
+                null
+        );
+    }
+
+

Implement onLoadFinished() and onLoaderReset()

+

+ Implement the + {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onLoadFinished onLoadFinished()} + method. The loader framework calls + {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onLoadFinished onLoadFinished()} + when the Contacts Provider returns the results of the query. In this method, put the + result {@link android.database.Cursor} in the + {@link android.support.v4.widget.SimpleCursorAdapter}. This automatically updates the + {@link android.widget.ListView} with the search results: +

+
+    public void onLoadFinished(Loader<Cursor> loader, Cursor cursor) {
+        // Put the result Cursor in the adapter for the ListView
+        mCursorAdapter.swapCursor(cursor);
+    }
+
+

+ The method {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onLoaderReset + onLoaderReset()} is invoked when the loader framework detects that the + result {@link android.database.Cursor} contains stale data. Delete the + {@link android.support.v4.widget.SimpleCursorAdapter} reference to the existing + {@link android.database.Cursor}. If you don't, the loader framework will not + recycle the {@link android.database.Cursor}, which causes a memory leak. For example: +

+
+    @Override
+    public void onLoaderReset(Loader<Cursor> loader) {
+        // Delete the reference to the existing Cursor
+        mCursorAdapter.swapCursor(null);
+
+    }
+
+ +

+ You now have the key pieces of an app that matches a search string to contact names and returns + the result in a {@link android.widget.ListView}. The user can click a contact name to select it. + This triggers a listener, in which you can work further with the contact's data. For example, + you can retrieve the contact's details. To learn how to do this, continue with the next + lesson, Retrieving Details for a Contact. +

+

+ To learn more about search user interfaces, read the API guide + Creating a Search Interface. +

+

+ The remaining sections in this lesson demonstrate other ways of finding contacts in the + Contacts Provider. +

+

Match a Contact By a Specific Type of Data

+

+ This technique allows you to specify the type of data you want to match. Retrieving + by name is a specific example of this type of query, but you can also do it for any of the types + of detail data associated with a contact. For example, you can retrieve contacts that have a + specific postal code; in this case, the search string has to match data stored in a postal code + row. +

+

+ To implement this type of retrieval, first implement the following code, as listed in + previous sections: +

+ +

+ The following steps show you the additional code you need to match a search string to + a particular type of detail data and display the results. +

+

Choose the data type and table

+

+ To search for a particular type of detail data, you have to know the custom MIME type value + for the data type. Each data type has a unique MIME type + value defined by a constant CONTENT_ITEM_TYPE in the subclass of + {@link android.provider.ContactsContract.CommonDataKinds} associated with the data type. + The subclasses have names that indicate their data type; for example, the subclass for email + data is {@link android.provider.ContactsContract.CommonDataKinds.Email}, and the custom MIME + type for email data is defined by the constant + {@link android.provider.ContactsContract.CommonDataKinds.Email#CONTENT_ITEM_TYPE + Email.CONTENT_ITEM_TYPE}. +

+

+ Use the {@link android.provider.ContactsContract.Data} table for your search. All of the + constants you need for your projection, selection clause, and sort order are defined in or + inherited by this table. +

+

Define a projection

+

+ To define a projection, choose one or more of the columns defined in + {@link android.provider.ContactsContract.Data} or the classes from which it inherits. The + Contacts Provider does an implicit join between {@link android.provider.ContactsContract.Data} + and other tables before it returns rows. For example: +

+
+    @SuppressLint("InlinedApi")
+    private static final String[] PROJECTION =
+        {
+            /*
+             * The detail data row ID. To make a ListView work,
+             * this column is required.
+             */
+            Data._ID,
+            // The primary display name
+            Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB ?
+                    Data.DISPLAY_NAME_PRIMARY :
+                    Data.DISPLAY_NAME,
+            // The contact's _ID, to construct a content URI
+            Data.CONTACT_ID
+            // The contact's LOOKUP_KEY, to construct a content URI
+            Data.LOOKUP_KEY (a permanent link to the contact
+        };
+
+

Define search criteria

+

+ To search for a string within a particular type of data, construct a selection clause from + the following: +

+ +

+ For example: +

+
+    /*
+     * Constructs search criteria from the search string
+     * and email MIME type
+     */
+    private static final String SELECTION =
+            /*
+             * Searches for an email address
+             * that matches the search string
+             */
+            Email.ADDRESS + " LIKE ? " + "AND " +
+            /*
+             * Searches for a MIME type that matches
+             * the value of the constant
+             * Email.CONTENT_ITEM_TYPE. Note the
+             * single quotes surrounding Email.CONTENT_ITEM_TYPE.
+             */
+            Data.MIMETYPE + " = '" + Email.CONTENT_ITEM_TYPE + "'";
+
+

+ Next, define variables to contain the selection argument: +

+
+    String mSearchString;
+    String[] mSelectionArgs = { "" };
+
+

Implement onCreateLoader()

+

+ Now that you've specified the data you want and how to find it, define a query in your + implementation of {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onCreateLoader + onCreateLoader()}. Return a new {@link android.support.v4.content.CursorLoader} from this + method, using your projection, selection text expression, and selection array as + arguments. For a content URI, use + {@link android.provider.ContactsContract.Data#CONTENT_URI Data.CONTENT_URI}. For example: +

+
+    @Override
+    public Loader<Cursor> onCreateLoader(int loaderId, Bundle args) {
+        // OPTIONAL: Makes search string into pattern
+        mSearchString = "%" + mSearchString + "%";
+        // Puts the search string into the selection criteria
+        mSelectionArgs[0] = mSearchString;
+        // Starts the query
+        return new CursorLoader(
+                getActivity(),
+                Data.CONTENT_URI,
+                PROJECTION,
+                SELECTION,
+                mSelectionArgs,
+                null
+        );
+    }
+
+

+ These code snippets are the basis of a simple reverse lookup based on a specific type of detail + data. This is the best technique to use if your app focuses on a particular type of data, such + as emails, and you want allow users to get the names associated with a piece of data. +

+

Match a Contact By Any Type of Data

+

+ Retrieving a contact based on any type of data returns contacts if any of their data matches a + the search string, including name, email address, postal address, phone number, and so forth. + This results in a broad set of search results. For example, if the search string + is "Doe", then searching for any data type returns the contact "John Doe"; it also returns + contacts who live on "Doe Street". +

+

+ To implement this type of retrieval, first implement the following code, as listed in + previous sections: +

+ +

+ The following steps show you the additional code you need to match a search string to + any type of data and display the results. +

+

Remove selection criteria

+

+ Don't define the SELECTION constants or the mSelectionArgs variable. + These aren't used in this type of retrieval. +

+

Implement onCreateLoader()

+

+ Implement the {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onCreateLoader + onCreateLoader()} method, returning a new {@link android.support.v4.content.CursorLoader}. + You don't need to convert the search string into a pattern, because the Contacts Provider does + that automatically. Use + {@link android.provider.ContactsContract.Contacts#CONTENT_FILTER_URI + Contacts.CONTENT_FILTER_URI} as the base URI, and append your search string to it by calling + {@link android.net.Uri#withAppendedPath Uri.withAppendedPath()}. Using this URI + automatically triggers searching for any data type, as shown in the following example: +

+
+    @Override
+    public Loader<Cursor> onCreateLoader(int loaderId, Bundle args) {
+        /*
+         * Appends the search string to the base URI. Always
+         * encode search strings to ensure they're in proper
+         * format.
+         */
+        Uri contentUri = Uri.withAppendedPath(
+                Contacts.CONTENT_FILTER_URI,
+                Uri.encode(mSearchString));
+        // Starts the query
+        return new CursorLoader(
+                getActivity(),
+                contentUri,
+                PROJECTION,
+                null,
+                null,
+                null
+        );
+    }
+
+

+ These code snippets are the basis of an app that does a broad search of the Contacts Provider. + The technique is useful for apps that want to implement functionality similar to the + People app's contact list screen. +

diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs index 79980be6d779..40273f82b21f 100644 --- a/docs/html/training/training_toc.cs +++ b/docs/html/training/training_toc.cs @@ -480,7 +480,37 @@ - +
  • -- cgit v1.2.3-59-g8ed1b