ListView

翻譯人：Tina

版本：Android 2.2 r1

翻譯時間：2010年11月13日

?

public class ListView extends AbsListView

?

java.lang.Object

???????? android.view.View

?????????????????? android.view.ViewGroup

??????????????????????????? android.widget.AdapterView<T extends android.widget.Adapter>

???????????????????????????????????? android.widget.AbsListView

?????????????????????????????????????????????? android.widget.ListView

?

直接子類

???????? ExpandableListView （使用豎滾動條查看的兩級列表視圖）

?

類概述

????????

通過豎滾動條查看的列表視圖。ListAdapter里包含的內(nèi)容和此視圖相關(guān)聯(lián)。參見List View tutorial。

?

內(nèi)部類

???????? class ListView.FixedViewInfo

???????? 表示一個列表中的固定視圖，如放在最頂部的頁眉和最底部的頁腳

?

XML屬性

?

常量

???????? Int??? CHOICE_MODE_MULTIPLE????

（常量值為2）列表允許同時選取多項(xiàng)

Int??? CHOICE_MODE_NONE????????????

（常量值為0）普通列表，不指明選取模式

Int??? CHOICE_MODE_SINGLE ????????

（常量值為1）列表只允許選取最多一項(xiàng)

?

公共方法

???????? public void addFooterView (View v)

???????? 加一個固定顯示于list底部的視圖。如果此方法被調(diào)用超過一次，所加的幾個視圖將按照它們加入的順序排列。加入的視圖可取得焦點(diǎn)。

???????? 注意：在調(diào)用setAdapter之前調(diào)用此方法。這樣的話，可以利用點(diǎn)擊光標(biāo)來收起有header view和footer view的ListView。

參數(shù)

??????????????????????????? v ???? 要加的視圖

?

public void addFooterView (View v, Object data, boolean isSelectable)

???????? 加一個固定顯示于list底部的視圖。如果此方法被調(diào)用超過一次，所加的幾個視圖將按照它們加入的順序排列。加入的視圖可取得焦點(diǎn)。

???????? 注意：在調(diào)用setAdapter之前調(diào)用此方法。這樣的話，可以利用點(diǎn)擊光標(biāo)來收起有header view和footer view的ListView。

參數(shù)

??????????????????????????? v ??????????????????????? 要加的視圖

??????????????????????????? data?????????????????? 和此視圖關(guān)聯(lián)的數(shù)據(jù)

??????????????????????????? isSelectable????? 設(shè)為true則表示footer view可以被選中

?

public void addHeaderView (View v)

???????? 加一個固定顯示于list頂部的視圖。如果此方法被調(diào)用超過一次，所加的幾個視圖將按照它們加入的順序排列。加入的視圖可取得焦點(diǎn)。

???????? 注意：在調(diào)用setAdapter之前調(diào)用此方法。這樣的話，可以利用點(diǎn)擊光標(biāo)來收起有header view和footer view的ListView。

參數(shù)

??????????????????????????? v ???? 要加的視圖

?

public void addHeaderView (View v, Object data, boolean isSelectable)

???????? 加一個固定顯示于list頂部的視圖。如果此方法被調(diào)用超過一次，所加的幾個視圖將按照它們加入的順序排列。加入的視圖可取得焦點(diǎn)。

???????? 注意：在調(diào)用setAdapter之前調(diào)用此方法。這樣的話，可以利用點(diǎn)擊光標(biāo)來收起有header view和footer view的ListView。

參數(shù)

??????????????????????????? v ??????????????????????? 要加的視圖

??????????????????????????? data?????????????????? 和此視圖關(guān)聯(lián)的數(shù)據(jù)

??????????????????????????? isSelectable????? 表示此header view可選與否

?

public void clearChoices ()

???????? 取消之前設(shè)置的任何選擇

?

public boolean dispatchKeyEvent (KeyEvent event)

???????? 按照可以獲得焦點(diǎn)的順序（從視圖樹的頂端到當(dāng)前獲得焦點(diǎn)的視圖），分派一個按鍵事件給下一個視圖。若此視圖有焦點(diǎn)，事件將會分派給它自己。否則它將按照順序，分派給下一個節(jié)點(diǎn)。此方法同時觸動所有按鍵監(jiān)聽器。

???????? 參數(shù)

?????????????????? event???????????????? 被分派的事件

???????? 返回

?????????????????? 若事件被處理，則返回true；否則為false

?

public boolean dispatchPopulateAccessibilityEvent (AccessibilityEvent event)

???????? 在視圖的子項(xiàng)目被構(gòu)建時，分派一個輔助事件。

???????? ???????? 參數(shù)

?????????????????? ???????? event???????????????? 事件

???????? ???????? 返回

?????????????????? ???????? 若事件全部完成，則返回true

?

public ListAdapter getAdapter ()

???????? 返回ListView當(dāng)前用的適配器。返回的適配器不可以和傳給setAdapter(ListAdapter)的參數(shù)一樣，但是可以是WrapperListAdapter。

???????? ???????? 返回

?????????????????? ???????? 當(dāng)前用來顯示ListView中數(shù)據(jù)的適配器

???????? ???????? 參見

?????????????????? ???????? setAdapter(ListAdapter)

?

public long[] getCheckItemIds ()

此方法已經(jīng)過時了。使用getCheckedItemIds()代替。

???????? 返回被選中項(xiàng)目的索引集合。只有當(dāng)選擇模式?jīng)]有被設(shè)置為CHOICE_MODE_NONE時才有效。

?

public long[] getCheckedItemIds ()

???????? 返回被選中項(xiàng)目的索引集合。只有當(dāng)選擇模式?jīng)]有被設(shè)置為CHOICE_MODE_NONE，并且適配器有穩(wěn)定的 ID（hasStableIds()==true） 時，結(jié)果才有效。

???????? 返回

?????????????????? 一個新的數(shù)組，包含列表中每個被選中的索引（id）

?

public int getCheckedItemPosition ()

???????? 返回當(dāng)前被選中的項(xiàng)目。只有當(dāng)選擇模式已被設(shè)置為CHOICE_MODE_SINGLE時 ，結(jié)果才有效。

???????? ???????? 返回

?????????????????? ???????? 返回當(dāng)前被選中的項(xiàng)目的索引；若沒有項(xiàng)目被選中，則返回INVALID_POSITION

???????? ???????? 參見

?????????????????? ???????? setChoiceMode(int)

?

public SparseBooleanArray getCheckedItemPositions ()

???????? 返回當(dāng)前被選中的項(xiàng)目集合。只有當(dāng)選擇模式?jīng)]有被設(shè)置為CHOICE_MODE_NONE時 ，結(jié)果才有效。

???????? ???????? 返回

?????????????????? ???????? 類型為SparseBooleanArray的值，其中，對每一個索引所代表的項(xiàng)目，若被選中，則返回true；當(dāng)選擇模式被設(shè)置為CHOICE_MODE_NONE時 ，返回null。

?

public int getChoiceMode ()

???????? ???????? 返回

?????????????????? ???????? 返回當(dāng)前的選擇模式

???????? ???????? 參見

?????????????????? ???????? setChoiceMode(int)

?

public Drawable getDivider ()

???????? ???????? 返回

?????????????????? ???????? 返回當(dāng)前畫在列表元素之間，作為分隔符的圖形

?

public int getDividerHeight ()

???????? ???????? 返回

?????????????????? ???????? 返回分隔符的高度

?

public int getFooterViewsCount ()

???????? ???????? 返回

?????????????????? ???????? 列表中的頁腳視圖數(shù)量；缺省實(shí)現(xiàn)時，數(shù)量為0

?

public int getHeaderViewsCount ()

???????? ???????? 返回

?????????????????? ???????? 列表中的頁眉視圖數(shù)量；缺省實(shí)現(xiàn)時，數(shù)量為0

?

public boolean getItemsCanFocus ()

???????? ???????? 返回

?????????????????? ???????? ListAdapter所生成的視圖是否可以包含能取得焦點(diǎn)的項(xiàng)目

?

public int getMaxScrollAmount ()

???????? 返回

?????????????????? The maximum amount a list view will scroll in response to an arrow event.

?????????????????? 響應(yīng)箭頭事件時，列表視圖可以滾動的最大值。（譯者注：此處翻譯待改進(jìn)，恐怕需要仔細(xì)查看源代碼才能明白其含義，也可以用Google Code搜索相關(guān)的代碼）

?

public boolean isItemChecked (int position)

???????? 對于由position指定的項(xiàng)目，返回其是否被選中。只有當(dāng)選擇模式已被設(shè)置為CHOICE_MODE_SINGLE或CHOICE_MODE_MULTIPLE時 ，結(jié)果才有效。

???????? ???????? 參數(shù)

??????????????????????????? position????????????????????? 要返回選中狀態(tài)的項(xiàng)目

???????? ???????? 返回

?????????????????? ???????? 返回項(xiàng)目的選中狀態(tài)；若選擇模式無效，則返回false

?

public boolean onKeyDown (int keyCode, KeyEvent event)

???????? KeyEvent.Callback.onKeyMultiple()的缺省實(shí)現(xiàn)：若視圖被激活并且可以被點(diǎn)擊，當(dāng)出現(xiàn)KEYCODE_DPAD_CENTER和KEYCODE_ENTER代表的行為時，做點(diǎn)擊該視圖的動作。

???????? ???????? 參數(shù)

??????????????????????????? keyCode???????????????????? 表示按某個按鍵的按鍵代號，參見KeyEvent

??????????????????????????? event?????????????????????????? 定義按鍵動作的按鍵事件對象

???????? ???????? 返回

?????????????????? ???????? 若事件被成功處理，則返回true；若想要下一個接收器處理該事件，則返回false

?

public boolean onKeyMultiple (int keyCode, int repeatCount, KeyEvent event)

???????? KeyEvent.Callback.onKeyMultiple()的缺省實(shí)現(xiàn)：總是返回false（不處理該事件）。

???????? ???????? 參數(shù)

??????????????????????????? keyCode???????????????????? 表示按某個按鍵的按鍵代號，參見KeyEvent

??????????????????????????? repeatedCount???????? 實(shí)現(xiàn)動作的次數(shù)

??????????????????????????? event?????????????????????????? 定義按鍵動作的按鍵事件對象

???????? ???????? 返回

?????????????????? ???????? 若事件被成功處理，則返回true；若想要下一個接收器處理該事件，則返回false

?

public boolean onKeyUp (int keyCode, KeyEvent event)

???????? KeyEvent.Callback.onKeyMultiple()的缺省實(shí)現(xiàn)：當(dāng)出現(xiàn)KEYCODE_DPAD_CENTER和KEYCODE_ENTER代表的行為時，做點(diǎn)擊該視圖的動作。

???????? ???????? 參數(shù)

??????????????????????????? keyCode???????????????????? 表示按某個按鍵的按鍵代號，參見KeyEvent

??????????????????????????? event?????????????????????????? 定義按鍵動作的按鍵事件對象

???????? ???????? 返回

?????????????????? ???????? 若事件被成功處理，則返回true；若想要下一個接收器處理該事件，則返回false

?

public void onRestoreInstanceState (Parcelable state)

???????? 重新創(chuàng)建并顯示一個視圖，此視圖擁有之前onSaveInstanceState()保存的內(nèi)部狀態(tài)。當(dāng)state為null時，此方法不會被調(diào)用。

???????? ???????? 參數(shù)

??????????????????????????? state?????????????????????????? 之前onSaveInstanceState()保存的狀態(tài)

?

public Parcelable onSaveInstanceState ()

???????? 保存視圖的內(nèi)部狀態(tài)，用于以后創(chuàng)建新的擁有同樣狀態(tài)的實(shí)例?？杀４娴臓顟B(tài)只包含非持久性的，或者可重新組建的信息。比如，永遠(yuǎn)不可能保存你當(dāng)前在屏幕上的位置，因?yàn)楫?dāng)新的實(shí)例被放置于視圖層次體系中時，位置會被重新計(jì)算。

???????? 一些可以被保存的狀態(tài)：文本視圖（但是通常不是指文本本身，因?yàn)槲谋臼潜槐４嬖趦?nèi)容提供商或其他持久性的儲存體中）中當(dāng)前的光標(biāo)位置；列表視圖中當(dāng)前的選中項(xiàng)。

返回??????????????????

返回一個包含視圖當(dāng)前動態(tài)狀態(tài)的接口方法對象；若沒有東西被保存，則返回null。缺省情況下返回null。

?

public boolean onTouchEvent (MotionEvent ev)

???????? 此方法用于處理觸摸屏的動作事件。

???????? ???????? 參數(shù)

??????????????????????????? ev??????????????????????? 動作事件

???????? ???????? 返回

?????????????????? ???????? 若事件被成功處理，則返回true；否則返回false

?

public boolean performItemClick (View view, int position, long id)

???????? 調(diào)用定義好的OnItemClickListener。

???????? ???????? 參數(shù)

??????????????????????????? view?????????????????? AdapterView中被點(diǎn)擊到的視圖

??????????????????????????? position???????????? 視圖在適配器中的索引

??????????????????????????? id???????????????????????? 被點(diǎn)擊到的項(xiàng)目的行id

???????? ???????? 返回

?????????????????? ???????? 若有定義好的OnItemClickListener被成功調(diào)用，則返回true；否則返回false

?

public boolean removeFooterView (View v)

???????? 刪除之前加入的某個頁腳視圖。

???????? ???????? 參數(shù)

??????????????????????????? v???????????????? 要刪除的視圖

???????? ???????? 返回

?????????????????? ???????? 若視圖被成功刪除，則返回true；若此視圖不是頁腳視圖，則返回false

?

public boolean removeHeaderView (View v)

???????? 刪除之前加入的某個頁眉視圖。

???????? ???????? 參數(shù)

??????????????????????????? v???????????????? 要刪除的視圖

???????? ???????? 返回

?????????????????? ???????? 若視圖被成功刪除，則返回true；若此視圖不是頁眉視圖，則返回false?????????????

public boolean requestChildRectangleOnScreen (View child, Rect rect, boolean immediate)

???????? 當(dāng)組里的某個子項(xiàng)需要被定位在屏幕的某個矩形范圍時，調(diào)用此方法。????

???????? 重載此方法的ViewGroup可確認(rèn)以下幾點(diǎn)：

?????????????????? · 子項(xiàng)目將是組里的直系子項(xiàng)

?????????????????? · 矩形將在子項(xiàng)目的坐標(biāo)體系中

???????? 重載此方法的ViewGroup必須保證以下幾點(diǎn)：

???????? ???????? · 若矩形已經(jīng)是可見的，則沒有東西會改變

?????????????????? · 為使矩形區(qū)域全部可見，視圖將可以被滾動顯示

???????? ???????? 參數(shù)

??????????????????????????? child?????????????????? 發(fā)出請求的子項(xiàng)目

??????????????????????????? rect??????????????????? 子項(xiàng)目坐標(biāo)系內(nèi)的矩形，即此子項(xiàng)目希望在屏幕上的定位

??????????????????????????? immediate??????? 設(shè)為true，則禁止動畫和緩釋移動滾動條

???????? ???????? 返回

?????????????????? ???????? 這個可滾動顯示的組，是否接受請求

?

public void setAdapter (ListAdapter adapter)

???????? 設(shè)置ListView背后的數(shù)據(jù)。根據(jù)ListView目前使用的特性，adapter可能被WrapperListAdapter收起。例如：加頁眉和/或頁腳會使adapter被收起。

???????? ???????? 參數(shù)

??????????????????????????? adapter???????????? 負(fù)責(zé)維護(hù)列表背后的數(shù)據(jù)，以及生成視圖來顯示數(shù)據(jù)里的項(xiàng)目

???????? ???????? 參見

?????????????????? ???????? getAdapter()????????????

?

public void setCacheColorHint (int color)

???????? 當(dāng)color的值不為0時，此值表示的顏色將提示使用者，列表正在一片單色不透明的背景上被畫出。

???????? ???????? 參數(shù)

??????????????????????????? color?????????????????? 背景色

?

public void setChoiceMode (int choiceMode)

???????? 設(shè)置List的選擇模式。缺省情況下，列表沒有選擇模式（即值為CHOICE_MODE_NONE）。

???????? ???????? 參數(shù)

??????????????????????????? choiceMode????????????? 值可為CHOICE_MODE_NONE，CHOICE_MODE_NONE和CHOICE_MODE_NONE中的一種

?

public void setDivider (Drawable divider)

???????? 設(shè)置將畫在列表中每個項(xiàng)目之間的圖形。如果圖形沒有已設(shè)定好的高度，則必須同時調(diào)用setDividerHeight(int)。

???????? ???????? 參數(shù)

??????????????????????????? divider?????????????? 將用作分隔符的圖形

?

public void setDividerHeight (int height)

???????? 設(shè)置分隔符（畫在列表中每個項(xiàng)目之間）的高度。調(diào)用此方法將覆蓋由setDivider(Drawable)設(shè)置的高度。

???????? ???????? 參數(shù)

??????????????????????????? height?????? 分隔符的新高度，單位為像素

?

public void setFooterDividersEnabled (boolean footerDividersEnabled)

???????? 設(shè)置可以或者不可以為頁腳視圖畫上分隔符。

???????? ???????? 參數(shù)

?????????????????? ???????? headerDividersEnabled??????????? 設(shè)為true，表明可以畫；設(shè)為false則不可以

???????? ???????? 參見

?????????????????? ???????? setHeaderDividerEnabled(boolean)

?????????????????? ???????? addFooterView(android.view.View)

?

public void setHeaderDividersEnabled (boolean headerDividersEnabled)

???????? 設(shè)置可以或者不可以為頁眉視圖畫上分隔符。

???????? ???????? 參數(shù)

??????????????????????????? headerDividersEnabled??????????? 設(shè)為true，表明可以畫；設(shè)為false則不可以

???????? ???????? 參見

?????????????????? ???????? setFooterDividerEnabled(boolean)

?????????????????? ???????? addHeaderView(android.view.View)

?

public void setItemChecked (int position, boolean value)

???????? 設(shè)置position所指定項(xiàng)目的選擇狀態(tài)。只有選擇模式為CHOICE_MODE_SINGLE或者CHOICE_MODE_MULTIPLE時，此設(shè)置才有效。

???????? ???????? 參數(shù)

??????????????????????????? position???????????? 需要改變選擇狀態(tài)的項(xiàng)目的索引

??????????????????????????? value????????????????? 新的選擇狀態(tài)

?

public void setItemsCanFocus (boolean itemsCanFocus)

???????? 表明在由ListAdapter創(chuàng)建的視圖中，可包含能獲得焦點(diǎn)的項(xiàng)目。

???????? ???????? 參數(shù)

??????????????????????????? itemsCanFocus???????? 若項(xiàng)目能獲得焦點(diǎn)，則設(shè)為true；否則為false

?

public void setSelection (int position)

???????? 選中position指定的項(xiàng)目。若為觸摸模式，則指定項(xiàng)目不會被選中，但位置變化一樣。若position的值小于0，則position為0的項(xiàng)目將被選中。

???????? ???????? 參數(shù)

??????????????????????????? position???????????? 需要選中的項(xiàng)目的索引（從0開始）

?

public void setSelectionAfterHeaderView ()

???????? 選中頁眉視圖下的第一個列表項(xiàng)目。

?

public void setSelectionFromTop (int position, int y)

???????? 選中position指定的項(xiàng)目，并將所選項(xiàng)置于距離ListView頂端y像素的位置（若為觸摸模式，則指定項(xiàng)目不會被選中，但位置變化一樣）。

???????? ???????? 參數(shù)

??????????????????????????? position???????????? 需要選中的項(xiàng)目的索引（從0開始）

??????????????????????????? y?????? ??????????????? 距離ListView（包括間隙）頂端的位置

?

受保護(hù)方法

???????? protected boolean canAnimate ()

???????? 表示此視圖組是否可以在第一次被布局后，仍可以動態(tài)調(diào)整其子項(xiàng)。

???????? ???????? 返回

??????????????????????????? 若可以則為true，否則為false

?

protected void dispatchDraw (Canvas canvas)

???????? 調(diào)用此方法來繪出子視圖?？杀谎苌愔貙?，以便在其子項(xiàng)被畫出之前取得控制權(quán)。

???????? ???????? 參數(shù)

???????? ?????????????????? canvas ???????????? 繪出View所用的canvas（畫布？）

?

protected View findViewTraversal (int id)

???????? ???????? 參數(shù)

??????????????????????????? id???????????????????????? 要找的View的id

???????? ???????? 返回值

??????????????????????????? 有此id的View，若沒有找到則為null

?

protected View findViewWithTagTraversal (Object tag)

???????? ???????? 參數(shù)

??????????????????????????? tag ?????????????????? 要找的View的標(biāo)簽

???????? ???????? 返回值

??????????????????????????? 有此標(biāo)簽的View，若沒有找到則為null

?

protected void layoutChildren ()

???????? 子類必須重寫此方法來布局其子項(xiàng)。

????????

protected void onFinishInflate ()

???????? 當(dāng)View以及所有子項(xiàng)從XML中導(dǎo)入時被調(diào)用，是導(dǎo)入的最后一步。即使子類重寫onFinishInflate，也必須保證有調(diào)用超方法，這樣，方法才會被調(diào)用。

????????

protected void onFocusChanged (boolean gainFocus, int direction, Rect previouslyFocusedRect)

???????? 當(dāng)View的焦點(diǎn)改變時被調(diào)用。重寫時，要確保超類的直接調(diào)用，這樣取得焦點(diǎn)的方式才是標(biāo)準(zhǔn)的。

參數(shù)

??????????????????????????? gainFocus ?????? 若View有焦點(diǎn)，則為True；否則為False。

??????????????????????????? direction?????????? 當(dāng)requestFocus()被調(diào)用時，方向焦點(diǎn)被移動。其值可為FOCUS_UP，FOCUS_DOWN，FOCUS_LEFT或FOCUS_RIGHT。在使用缺省條件的情況下，direction并不總是可用。

??????????????????????????? previouslyFocusedRect??? 之前得到焦點(diǎn)的View的坐標(biāo)系統(tǒng)所構(gòu)成的矩形。如果可用，這個將被當(dāng)成精確信息（表明焦點(diǎn)從何而來以及從何方向而來）來傳遞；否則將傳遞null。

?

protected void onMeasure (int widthMeasureSpec, int heightMeasureSpec)

???????? View調(diào)用此方法來確定本身和所包含內(nèi)容的大小。此方法被measure(int,int)喚起，而且必須被子類重寫以得到所包含內(nèi)容的確切大小。

???????? 注意：當(dāng)重寫此方法時，必須調(diào)用setMeasureDimension(int,int)來保存View的大小。如果沒有做到，將會引發(fā)一個measure(int,int)拋出的IllegalStateException（非法狀態(tài)錯誤）。超類onMeasure(int,int)可以被調(diào)用。

???????? 編寫基類的確認(rèn)大小的方法，缺省情況下是根據(jù)其背景大小來確認(rèn)，除非MeasureSepc允許有更大的高度或?qū)挾?。子類必須重?/span>onMeasure(int,int)以得到對其內(nèi)容大小的更準(zhǔn)確的測量。

???????? 若此方法被重寫，它的子類需要確保其高度和寬度至少達(dá)到View所規(guī)定的最小值（可通過getSuggestedMinimumHeight()和getSuggestedMinimumWidth()得到）。

參數(shù)

??????????????????????????? widthMeaureSpec ????????? 受上一層大小影響下的對水平空間的要求?？蓞⒖?/span>View.MeasureSpec。

??????????????????????????? heightMeasureSpec???????? 受上一層大小影響下的對垂直空間的要求?？蓞⒖?/span>View.MeasureSpec。

???????????????????????????

protected void onSizeChanged (int w, int h, int oldw, int oldh)

???????? 當(dāng)VIew的大小改變時此方法被調(diào)用。如果VIew是剛剛被加入，則視之前的值為0。

參數(shù)

??????????????????????????? w ????????????????????? View的當(dāng)前寬度

??????????????????????????? h????????????????????????? View的當(dāng)前高度

??????????????????????????? oldw?????????????????? View大小改變之前的寬度

??????????????????????????? oldh??????????????????? View大小改變之前的高度

?

補(bǔ)充

???????? 參考鏈接

?????????????????? Android入門第六篇之ListView (一)

?????????????????? android ListView詳解

?????????????????? android異步加載ListView中的圖片

?????????????????? Google I/O 2010 - The world of ListView

?????????????????? Android: 顯示SD卡文件列表

?????????????????? Android: 帶圖標(biāo)的ListView實(shí)現(xiàn)

ListView和getView的原理＋如何在ListView中放置多個item