Build 1.0_r1(from source)

android.app
Class ListActivity

java.lang.Object
  extended by android.content.Context
      extended by android.content.ContextWrapper
          extended by android.view.ContextThemeWrapper
              extended by android.app.Activity
                  extended by android.app.ListActivity
All Implemented Interfaces:
ComponentCallbacks, KeyEvent.Callback, LayoutInflater.Factory, View.OnCreateContextMenuListener, Window.Callback
Direct Known Subclasses:
LauncherActivity, PreferenceActivity, TestBrowserActivity, TestListActivity

public class ListActivity
extends Activity

An activity that displays a list of items by binding to a data source such as an array or Cursor, and exposes event handlers when the user selects an item.

ListActivity hosts a ListView object that can be bound to different data sources, typically either an array or a Cursor holding query results. Binding, screen layout, and row layout are discussed in the following sections.

Screen Layout

ListActivity has a default layout that consists of a single, full-screen list in the center of the screen. However, if you desire, you can customize the screen layout by setting your own view layout with setContentView() in onCreate(). To do this, your own view MUST contain a ListView object with the id "@android:id/list" (or R.id.list if it's in code)

Optionally, your custom view can contain another view object of any type to display when the list view is empty. This "empty list" notifier must have an id "android:empty". Note that when an empty view is present, the list view will be hidden when there is no data to display.

The following code demonstrates an (ugly) custom screen layout. It has a list with a green background, and an alternate red "no data" message.

 <?xml version="1.0" encoding="UTF-8"?>
 <LinearLayout
         android:orientation="vertical"
         android:layout_width="fill_parent" 
         android:layout_height="fill_parent"
         android:paddingLeft="8"
         android:paddingRight="8">
 
     <ListView id="android:list"
               android:layout_width="fill_parent" 
               android:layout_height="fill_parent"
               android:background="#00FF00"
               android:layout_weight="1"
               android:drawSelectorOnTop="false"/>
 
     <TextView id="android:empty"
               android:layout_width="fill_parent" 
               android:layout_height="fill_parent"
               android:background="#FF0000"
               android:text="No data"/>
 </LinearLayout>
 

Row Layout

You can specify the layout of individual rows in the list. You do this by specifying a layout resource in the ListAdapter object hosted by the activity (the ListAdapter binds the ListView to the data; more on this later).

A ListAdapter constructor takes a parameter that specifies a layout resource for each row. It also has two additional parameters that let you specify which data field to associate with which object in the row layout resource. These two parameters are typically parallel arrays.

Android provides some standard row layout resources. These are in the R.layout class, and have names such as simple_list_item_1, simple_list_item_2, and two_line_list_item. The following layout XML is the source for the resource two_line_list_item, which displays two data fields,one above the other, for each list row.

 <?xml version="1.0" encoding="utf-8"?>
 <LinearLayout
     android:layout_width="fill_parent"
     android:layout_height="wrap_content"
     android:orientation="vertical">
 
     <TextView id="text1"
         android:textSize="16"
         android:textStyle="bold"
         android:layout_width="fill_parent"
         android:layout_height="wrap_content"/>
 
     <TextView id="text2"
         android:textSize="16"
         android:layout_width="fill_parent"
         android:layout_height="wrap_content"/>
 </LinearLayout>
 

You must identify the data bound to each TextView object in this layout. The syntax for this is discussed in the next section.

Binding to Data

You bind the ListActivity's ListView object to data using a class that implements the ListAdapter interface. Android provides two standard list adapters: SimpleAdapter for static data (Maps), and SimpleCursorAdapter for Cursor query results.

The following code from a custom ListActivity demonstrates querying the Contacts provider for all contacts, then binding the Name and Company fields to a two line row layout in the activity's ListView.

 public class MyListAdapter extends ListActivity {
 
     @Override
     protected void onCreate(Bundle icicle){
         super.onCreate(icicle);
 
         // We'll define a custom screen layout here (the one shown above), but
         // typically, you could just use the standard ListActivity layout.
         setContentView(R.layout.custom_list_activity_view);
 
         // Query for all people contacts using the Contacts.People convenience class.
         // Put a managed wrapper around the retrieved cursor so we don't have to worry about
         // requerying or closing it as the activity changes state.
         mCursor = People.query(this.getContentResolver(), null);
         startManagingCursor(mCursor);
 
         // Now create a new list adapter bound to the cursor. 
         // SimpleListAdapter is designed for binding to a Cursor.
         ListAdapter adapter = new SimpleCursorAdapter(
                 this, // Context.
                 android.R.layout.two_line_list_item,  // Specify the row template to use (here, two columns bound to the two retrieved cursor 
 rows).
                 mCursor,                                    // Pass in the cursor to bind to.
                 new String[] {People.NAME, People.COMPANY}, // Array of cursor columns to bind to.
                 new int[]);                                 // Parallel array of which template objects to bind to those columns.
 
         // Bind to our new adapter.
         setListAdapter(adapter);
     }
 }
 

See Also:
setListAdapter(android.widget.ListAdapter), ListView

Field Summary
protected  ListAdapter mAdapter
          This field should be made private, so it is hidden from the SDK.
protected  ListView mList
          This field should be made private, so it is hidden from the SDK.
 
Fields inherited from class android.app.Activity
DEFAULT_KEYS_DIALER, DEFAULT_KEYS_DISABLE, DEFAULT_KEYS_SEARCH_GLOBAL, DEFAULT_KEYS_SEARCH_LOCAL, DEFAULT_KEYS_SHORTCUT, FOCUSED_STATE_SET, mActivityInfo, mCalled, mConfigChangeFlags, mCurrentConfig, mDecor, mEmbeddedID, mFinished, mMainThread, mParent, mResultCode, mResultData, mStartedActivity, RESULT_CANCELED, RESULT_FIRST_USER, RESULT_OK
 
Fields inherited from class android.content.Context
ACTIVITY_SERVICE, ALARM_SERVICE, AUDIO_SERVICE, BIND_AUTO_CREATE, BIND_DEBUG_UNBIND, BLUETOOTH_SERVICE, CLIPBOARD_SERVICE, CONNECTIVITY_SERVICE, CONTEXT_IGNORE_SECURITY, CONTEXT_INCLUDE_CODE, KEYGUARD_SERVICE, LAYOUT_INFLATER_SERVICE, LOCATION_SERVICE, MODE_APPEND, MODE_PRIVATE, MODE_WORLD_READABLE, MODE_WORLD_WRITEABLE, NOTIFICATION_SERVICE, POWER_SERVICE, SEARCH_SERVICE, SENSOR_SERVICE, STATUS_BAR_SERVICE, TELEPHONY_SERVICE, VIBRATOR_SERVICE, WALLPAPER_SERVICE, WIFI_SERVICE, WINDOW_SERVICE
 
Constructor Summary
ListActivity()
           
 
Method Summary
 ListAdapter getListAdapter()
          Get the ListAdapter associated with this activity's ListView.
 ListView getListView()
          Get the activity's list view widget.
 long getSelectedItemId()
          Get the cursor row ID of the currently selected list item.
 int getSelectedItemPosition()
          Get the position of the currently selected list item.
 void onContentChanged()
          Updates the screen state (current list and other views) when the content changes.
protected  void onListItemClick(ListView l, View v, int position, long id)
          This method will be called when an item in the list is selected.
protected  void onRestoreInstanceState(Bundle state)
          Ensures the list view has been created before Activity restores all of the view states.
 void setListAdapter(ListAdapter adapter)
          Provide the cursor for the list view.
 void setSelection(int position)
          Set the currently selected list item to the specified position with the adapter's data
 
Methods inherited from class android.app.Activity
addContentView, attach, closeOptionsMenu, createPendingResult, dismissDialog, dispatchActivityResult, dispatchKeyEvent, dispatchTouchEvent, dispatchTrackballEvent, finalize, findViewById, finish, finishActivity, finishActivityFromChild, finishFromChild, getActivityToken, getApplication, getCallingActivity, getCallingPackage, getChangingConfigurations, getComponentName, getCurrentFocus, getInstanceCount, getIntent, getLastNonConfigurationInstance, getLayoutInflater, getLocalClassName, getMenuInflater, getParent, getPreferences, getRequestedOrientation, getSystemService, getTaskId, getTitle, getTitleColor, getVolumeControlStream, getWallpaperDesiredMinimumHeight, getWallpaperDesiredMinimumWidth, getWindow, getWindowManager, isChild, isFinishing, isResumed, isTaskRoot, managedCommitUpdates, managedQuery, managedQuery, moveTaskToBack, onActivityResult, onApplyThemeResource, onChildTitleChanged, onConfigurationChanged, onContextItemSelected, onContextMenuClosed, onCreate, onCreateContextMenu, onCreateDescription, onCreateDialog, onCreateOptionsMenu, onCreatePanelMenu, onCreatePanelView, onCreateThumbnail, onCreateView, onDestroy, onKeyDown, onKeyMultiple, onKeyUp, onLowMemory, onMenuItemSelected, onMenuOpened, onNewIntent, onOptionsItemSelected, onOptionsMenuClosed, onPanelClosed, onPause, onPostCreate, onPostResume, onPrepareDialog, onPrepareOptionsMenu, onPreparePanel, onRestart, onResume, onRetainNonConfigurationInstance, onSaveInstanceState, onSearchRequested, onStart, onStop, onTitleChanged, onTouchEvent, onTrackballEvent, onWindowAttributesChanged, onWindowFocusChanged, openContextMenu, openOptionsMenu, performRestart, performRestoreInstanceState, performResume, performSaveInstanceState, performStart, performStop, registerForContextMenu, removeDialog, requestWindowFeature, runOnUiThread, setContentView, setContentView, setContentView, setDefaultKeyMode, setFeatureDrawable, setFeatureDrawableAlpha, setFeatureDrawableResource, setFeatureDrawableUri, setIntent, setParent, setPersistent, setProgress, setProgressBarIndeterminate, setProgressBarIndeterminateVisibility, setProgressBarVisibility, setRequestedOrientation, setResult, setResult, setSecondaryProgress, setTitle, setTitle, setTitleColor, setVolumeControlStream, showDialog, startActivity, startActivityForResult, startActivityFromChild, startActivityIfNeeded, startManagingCursor, startNextMatchingActivity, startSearch, stopManagingCursor, takeKeyEvents, unregisterForContextMenu
 
Methods inherited from class android.view.ContextThemeWrapper
attachBaseContext, getTheme, setTheme
 
Methods inherited from class android.content.ContextWrapper
bindService, checkCallingOrSelfPermission, checkCallingOrSelfUriPermission, checkCallingPermission, checkCallingUriPermission, checkPermission, checkUriPermission, checkUriPermission, clearWallpaper, createPackageContext, databaseList, deleteDatabase, deleteFile, enforceCallingOrSelfPermission, enforceCallingOrSelfUriPermission, enforceCallingPermission, enforceCallingUriPermission, enforcePermission, enforceUriPermission, enforceUriPermission, fileList, getApplicationContext, getAssets, getBaseContext, getCacheDir, getClassLoader, getContentResolver, getDatabasePath, getDir, getFilesDir, getFileStreamPath, getMainLooper, getPackageCodePath, getPackageManager, getPackageName, getPackageResourcePath, getResources, getSharedPreferences, getWallpaper, grantUriPermission, openFileInput, openFileOutput, openOrCreateDatabase, peekWallpaper, registerReceiver, registerReceiver, removeStickyBroadcast, revokeUriPermission, sendBroadcast, sendBroadcast, sendOrderedBroadcast, sendOrderedBroadcast, sendStickyBroadcast, setWallpaper, setWallpaper, startInstrumentation, startService, stopService, unbindService, unregisterReceiver
 
Methods inherited from class android.content.Context
getString, getString, getText, obtainStyledAttributes, obtainStyledAttributes, obtainStyledAttributes, obtainStyledAttributes
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

mAdapter

protected ListAdapter mAdapter
This field should be made private, so it is hidden from the SDK.


mList

protected ListView mList
This field should be made private, so it is hidden from the SDK.

Constructor Detail

ListActivity

public ListActivity()
Method Detail

onListItemClick

protected void onListItemClick(ListView l,
                               View v,
                               int position,
                               long id)
This method will be called when an item in the list is selected. Subclasses should override. Subclasses can call getListView().getItemAtPosition(position) if they need to access the data associated with the selected item.

Parameters:
l - The ListView where the click happened
v - The view that was clicked within the ListView
position - The position of the view in the list
id - The row id of the item that was clicked

onRestoreInstanceState

protected void onRestoreInstanceState(Bundle state)
Ensures the list view has been created before Activity restores all of the view states.

Overrides:
onRestoreInstanceState in class Activity
Parameters:
state - the data most recently supplied in Activity.onSaveInstanceState(android.os.Bundle).
See Also:
Activity.onRestoreInstanceState(Bundle)

onContentChanged

public void onContentChanged()
Updates the screen state (current list and other views) when the content changes.

Specified by:
onContentChanged in interface Window.Callback
Overrides:
onContentChanged in class Activity
See Also:
Activity.onContentChanged()

setListAdapter

public void setListAdapter(ListAdapter adapter)
Provide the cursor for the list view.


setSelection

public void setSelection(int position)
Set the currently selected list item to the specified position with the adapter's data

Parameters:
position -

getSelectedItemPosition

public int getSelectedItemPosition()
Get the position of the currently selected list item.


getSelectedItemId

public long getSelectedItemId()
Get the cursor row ID of the currently selected list item.


getListView

public ListView getListView()
Get the activity's list view widget.


getListAdapter

public ListAdapter getListAdapter()
Get the ListAdapter associated with this activity's ListView.


Build 1.0_r1(from source)

Please submit a feedback, bug or feature