Display Contact Names in Android

There are a lot of tutorial on this but most of them either failed when you run the codes or they forgat to tell you something, while i don't guaranty anything coz it took me 3 hours to figure what's wrong with what i was doing, i would try to make it as simple as i can.

First of all when you need to read Contacts on android, you need the user's permission that you will read their contact list. To do this
* Open AndroidManifest.xml and add the following codes in between manifest tags

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

- On eclipse, open AndroidManifest.xml then go to Permissions Tab, Click Add, Click on "Uses Permission", on the right side, on the name field select android.permission.READ_CONTACTS


After adding the permission, let us go to the codes: On your codes,

import android.app.ListActivity;
import android.database.Cursor;
import android.os.Bundle;
import android.provider.Contacts.People;
import android.widget.ListAdapter;
import android.widget.SimpleCursorAdapter;

public class Main extends ListActivity {
  /** Called when the activity is first created. */
  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    Cursor contactsCursor = this.managedQuery(People.CONTENT_URI, null, null, null, null);
    startManagingCursor(contactsCursor);

    String[] columnsToMap = new String[] {People.NAME};
    int[] mapTo = new int[] {android.R.id.text1};

    ListAdapter mAdapter = new SimpleCursorAdapter(this, android.R.layout.simple_list_item_1, contactsCursor, columnsToMap, mapTo);
    this.setListAdapter(mAdapter);
  }
}

A brief explanation to the core codes:
Cursor contactsCursor = this.managedQuery(People.CONTENT_URI, null, null, null, null);
-- This would query our Contacts, you can treat this somehow like SQL statement, we query the People.CONTENT_URI model, you can find out what the null represents in here

startManagingCursor(contactsCursor);
-- Tell it to start managing this cursor

String[] columnsToMap = new String[] {People.NAME};
-- As stated, you can treat this as sql, what we just did here is that we put the field People.NAME to an Array of String, you may have many fields as possible in this array. Here you can see we use People.NAME instead of a string field name, well this is the same except the class People has a static variable named NAME which translate to the string field name. The whole list of possible fields are in here

int[] mapTo = new int[] {android.R.id.text1};
-- This part is confusing but to explain it, we would map the People.NAME field to a textbox, now where did we specify the textbox?

ListAdapter mAdapter = new SimpleCursorAdapter(this, android.R.layout.simple_list_item_1, contactsCursor, columnsToMap, mapTo);
-- SimpleCursorAdaptor would bind/map our Cursor with our layout, you can refer here on what the parameters represent. The 2nd parameter here is layout, android by default has a lot of layout given to you by default, one of the layout that it has is the simple_list_item_1 layout, the 2nd comment on this thread would help you understand why we need the textbox mentioned on the top. The 3rd parameter is our cursor, the fourth is the fields/columns we need from our cursor to be mapped to our fifth parameters.

Hope i didn't confuse you and hope it helps :)

Update History
   Jan 17, 2012 - Visual Update