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: +
++ 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. +
+
+ 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> ++
+ 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. +
++ Once you have the necessary columns, you can bind data to the + {@link android.widget.QuickContactBadge}. +
++ 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. +
++ 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); ++
+ 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. +
++ 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.
+
+ 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: +
++ 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()}. +
++ The following code snippet contains an example of a custom subclass of + {@link android.support.v4.widget.CursorAdapter}: +
++ 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);
+ }
+
+
++ 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;
+ ...
+
++ 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 0000000000000..f380d9562e8a3
--- /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
+
+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. +
+ContactsList.zip
++ 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: +
++ 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. +
+ ++ 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. +
++ 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. +
++ 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. +
++ 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); ++
+ 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);
+
++ 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". +
+ ++ Finally, send the intent you've constructed. For example: +
++ // Sends the Intent + startActivity(editIntent); ++
+ 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 0000000000000..0de3b6750be46 --- /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 + +
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. +
++ 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. +
+
+ 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" /> ++
+ 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 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 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. +
++ 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 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 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;
+ }
+
++ 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: +
++ These modifications are described in the following sections. +
+
+ 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 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 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 0000000000000..b034a6a26d40d --- /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 + +
ContactsList.zip
++ 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: +
++ 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. +
+
+ 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" /> ++
+ 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. +
+
+ 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. +
++ 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 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 {@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 {@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);
+ }
+
++ 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 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
+
+ };
+
++ 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; ++
+ 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 };
+
++ 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.
+ */
+ }
+
++ 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 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 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. +
++ 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: +
++ Although you're retrieving data from a different table, the order of the columns in + the projection is the same, so you can use the same indexes for the Cursor. +
++ 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. +
+
+ 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. +
++ 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
+ };
+
++ To search for a string within a particular type of data, construct a selection clause from + the following: +
+CONTENT_ITEM_TYPE in the
+ {@link android.provider.ContactsContract.CommonDataKinds} subclass. For example, the MIME
+ type value for email data is
+ {@link android.provider.ContactsContract.CommonDataKinds.Email#CONTENT_ITEM_TYPE
+ Email.CONTENT_ITEM_TYPE}. Enclose the value in single quotes by concatenating a
+ "'" (single quote) character to the start and end of the constant; otherwise,
+ the provider interprets the value 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: +
++ /* + * 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 = { "" };
+
++ 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. +
++ 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: +
++ For this type of retrieval, you're using the same table you used in the section + Match a Contact by Name and List the Results. Use the + same column indexes as well. +
++ The following steps show you the additional code you need to match a search string to + any type of data and display the results. +
+
+ Don't define the SELECTION constants or the mSelectionArgs variable.
+ These aren't used in this type of retrieval.
+
+ 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 985fc44dec21f..7a3f2ca1162fb 100644 --- a/docs/html/training/training_toc.cs +++ b/docs/html/training/training_toc.cs @@ -484,7 +484,37 @@