Android API 中文 ListView

正文

　　一、結構

　　　　public class RatingBar extends AbsSeekBar

 

　　　　java.lang.Object

　　　　　　android.view.View

　　　　　　　　android.view.ViewGroup

android.widget.AdapterView

　　android.widget.AbsListView

　　 android.widget.ListView

 

　　　　直接子類

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

 

　　二、概述

　　　　

　　　　通過豎滾動條查看的列表視圖。ListAdapter裡包含的內容和此視圖相關聯。參見List View tutorial。

 

　　三、內部類

 

class ListView.FixedViewInfo

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

 

　　四、XML屬性

 

屬性名稱

描述

android:choiceMode

規定此ListView所使用的選擇模式。缺省狀態下，list沒有選擇模式。

屬性值必須設置為下列常量之一： none，值為0，表示無選擇模式；

singleChoice，值為1，表示最多可以有一項被選中；

multipleChoice，值為2，表示可以多項被選中。

可參看全局屬性資源符號choiceMode。

android:divider

規定List項目之間用某個圖形或顏色來分隔。可以用@[+][package:]type:name或者?[package:][type:]name（主題屬性）的形式來指向某個已有資源；也可以用#rgb，#argb，#rrggbb或者#aarrggbb的格式來表示某個顏色。

可參看全局屬性資源符號divider。

android:dividerHeight

分隔符的高度。若沒有指明高度，則用此分隔符固有的高度。必須為帶單位的浮點數，如14.5sp。可用的單位如px（pixel像素），dp（density-independent pixels 與密集度無關的像素）, sp（scaled pixels based on preferred font size基於字體大小的固定比例的像素）， in (inches英寸), mm (millimeters毫米)。

可以用@[package:]type:name

或者?[package:][type:]name（主題屬性）的格式來指向某個包含此類型值的資源。

可參看全局屬性資源符號dividerHeight。

android:entries

引用一個將使用在此ListView裡的數組。若數組是固定的，使用此屬性將比在程序中寫入更為簡單。

必須以@[+][package:]type:name或者 ?[package:][type:]name的形式來指向某個資源。

可參看全局屬性資源符號entries。

android:footerDividersEnabled

設成flase時，此ListView將不會在頁腳視圖前畫分隔符。此屬性缺省值為true。

屬性值必須設置為true或false。

可以用@[package:]type:name

或者?[package:][type:]name（主題屬性）的格式來指向某個包含此類型值的資源。

可參看全局屬性資源符號footerDividersEnabled。

android:headerDividersEnabled

設成flase時，此ListView將不會在頁眉視圖後畫分隔符。此屬性缺省值為true。

屬性值必須設置為true或false。

可以用@[package:]type:name

或者?[package:][type:]name（主題屬性）的格式來指向某個包含此類型值的資源。

可參看全局屬性資源符號headerDividersEnabled。

　　五、常量

 

Int CHOICE_MODE_MULTIPLE

　（常量值為2）列表允許同時選取多項

　 Int CHOICE_MODE_NONE

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

　 Int CHOICE_MODE_SINGLE

　（常量值為1）列表只允許選取最多一項

　　六、公共方法

 

public void addFooterView (View v)

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

注意：在調用setAdapter之前調用此方法。這樣的話，可以利用點擊光標來收起有header view和footer view的ListView。

　　參數

　　v 要加的視圖

 

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

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

注意：在調用setAdapter之前調用此方法。這樣的話，可以利用點擊光標來收起有header view和footer view的ListView。

　　參數

　　v 要加的視圖

　　data 和此視圖關聯的數據

　　isSelectable 設為true則表示footer view可以被選中

 

　 public void addHeaderView (View v)

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

注意：在調用setAdapter之前調用此方法。這樣的話，可以利用點擊光標來收起有header view和footer view的ListView。

　　參數

　　 v 要加的視圖

 

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

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

注意：在調用setAdapter之前調用此方法。這樣的話，可以利用點擊光標來收起有header view和footer view的ListView。

　　參數

　　v 要加的視圖

　　data 和此視圖關聯的數據

　　isSelectable 表示此header view可選與否

 

　 public void clearChoices ()

取消之前設置的任何選擇

 

　 public boolean dispatchKeyEvent (KeyEvent event)

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

　　參數

event 被分派的事件

　　返回

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

 

　 public boolean dispatchPopulateAccessibilityEvent (AccessibilityEvent event)

在視圖的子項目被構建時，分派一個輔助事件。

參數

event 事件

返回

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

 

　 public ListAdapter getAdapter ()

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

返回

當前用來顯示ListView中數據的適配器

參見

setAdapter(ListAdapter)

 

　 public long[] getCheckItemIds ()

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

返回被選中項目的索引集合。只有當選擇模式沒有被設置為CHOICE_MODE_NONE時才有效。

 

　 public long[] getCheckedItemIds ()

返回被選中項目的索引集合。只有當選擇模式沒有被設置為CHOICE_MODE_NONE，並且適配器有穩定的 ID（hasStableIds()==true）時，結果才有效。

　　返回

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

 

　 public int getCheckedItemPosition ()

返回當前被選中的項目。只有當選擇模式已被設置為CHOICE_MODE_SINGLE時，結果才有效。

　　返回

　　返回當前被選中的項目的索引；若沒有項目被選中，則返回INVALID_POSITION

參見

　　setChoiceMode(int)

 

　 public SparseBooleanArray getCheckedItemPositions ()

返回當前被選中的項目集合。只有當選擇模式沒有被設置為CHOICE_MODE_NONE時，結果才有效。

　　返回

　　類型為SparseBooleanArray的值，其中，對每一個索引所代表的項目，若被選中，則返回true；當選擇模式被設置為CHOICE_MODE_NONE時，返回null。

 

　 public int getChoiceMode ()

返回

返回當前的選擇模式

參見

setChoiceMode(int)

 

　 public Drawable getDivider ()

返回

返回當前畫在列表元素之間，作為分隔符的圖形

 

　 public int getDividerHeight ()

返回

返回分隔符的高度

 

　 public int getFooterViewsCount ()

返回

列表中的頁腳視圖數量；缺省實現時，數量為0

 

　 public int getHeaderViewsCount ()

返回

列表中的頁眉視圖數量；缺省實現時，數量為0

 

　 public boolean getItemsCanFocus ()

返回

ListAdapter所生成的視圖是否可以包含能取得焦點的項目

 

　 public int getMaxScrollAmount ()

　　返回

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

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

 

　 public boolean isItemChecked (int position)

對於由position指定的項目，返回其是否被選中。只有當選擇模式已被設置為CHOICE_MODE_SINGLE或CHOICE_MODE_MULTIPLE時，結果才有效。

參數

position 要返回選中狀態的項目

返回

返回項目的選中狀態；若選擇模式無效，則返回false

 

　 public boolean onKeyDown (int keyCode, KeyEvent event)

KeyEvent.Callback.onKeyMultiple()的缺省實現：若視圖被激活並且可以被點擊，當出現KEYCODE_DPAD_CENTER和KEYCODE_ENTER代表的行為時，做點擊該視圖的動作。

參數

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

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

返回

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

 

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

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

參數

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

repeatedCount 實現動作的次數

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

返回

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

 

　 public boolean onKeyUp (int keyCode, KeyEvent event)

KeyEvent.Callback.onKeyMultiple()的缺省實現：當出現KEYCODE_DPAD_CENTER和KEYCODE_ENTER代表的行為時，做點擊該視圖的動作。

參數

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

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

返回

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

 

　 public void onRestoreInstanceState (Parcelable state)

重新創建並顯示一個視圖，此視圖擁有之前onSaveInstanceState()保存的內部狀態。當state為null時，此方法不會被調用。

參數

state 之前onSaveInstanceState()保存的狀態

 

　 public Parcelable onSaveInstanceState ()

保存視圖的內部狀態，用於以後創建新的擁有同樣狀態的實例。可保存的狀態只包含非持久性的，或者可重新組建的信息。比如，永遠不可能保存你當前在屏幕上的位置，因為當新的實例被放置於視圖層次體系中時，位置會被重新計算。

一些可以被保存的狀態：文本視圖（但是通常不是指文本本身，因為文本是被保存在內容提供商或其他持久性的儲存體中）中當前的光標位置；列表視圖中當前的選中項。

　　返回

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

 

　 public boolean onTouchEvent (MotionEvent ev)

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

參數

ev 動作事件

返回

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

 

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

調用定義好的OnItemClickListener。

參數

view AdapterView中被點擊到的視圖

position 視圖在適配器中的索引

id 被點擊到的項目的行id

返回

若有定義好的OnItemClickListener被成功調用，則返回true；否則返回false

 

　 public boolean removeFooterView (View v)

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

參數

v 要刪除的視圖

返回

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

 

　 public boolean removeHeaderView (View v)

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

參數

v 要刪除的視圖

返回

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

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

當組裡的某個子項需要被定位在屏幕的某個矩形范圍時，調用此方法。

重載此方法的ViewGroup可確認以下幾點：

·子項目將是組裡的直系子項

·矩形將在子項目的坐標體系中

重載此方法的ViewGroup必須保證以下幾點：

·若矩形已經是可見的，則沒有東西會改變

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

參數

child 發出請求的子項目

rect 子項目坐標系內的矩形，即此子項目希望在屏幕上的定位

immediate 設為true，則禁止動畫和緩釋移動滾動條

返回

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

 

　 public void setAdapter (ListAdapter adapter)

設置ListView背後的數據。根據ListView目前使用的特性，adapter可能被WrapperListAdapter收起。例如：加頁眉和/或頁腳會使adapter被收起。

參數

adapter 負責維護列表背後的數據，以及生成視圖來顯示數據裡的項目

參見

getAdapter()

 

　 public void setCacheColorHint (int color)

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

參數

color 背景色

 

　 public void setChoiceMode (int choiceMode)

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

參數

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

 

　 public void setDivider (Drawable divider)

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

參數

divider 將用作分隔符的圖形

 

　 public void setDividerHeight (int height)

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

參數

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

 

　 public void setFooterDividersEnabled (boolean footerDividersEnabled)

設置可以或者不可以為頁腳視圖畫上分隔符。

參數

headerDividersEnabled 設為true，表明可以畫；設為false則不可以

參見

setHeaderDividerEnabled(boolean)

addFooterView(android.view.View)

 

　 public void setHeaderDividersEnabled (boolean headerDividersEnabled)

設置可以或者不可以為頁眉視圖畫上分隔符。

參數

headerDividersEnabled 設為true，表明可以畫；設為false則不可以

參見

setFooterDividerEnabled(boolean)

addHeaderView(android.view.View)

 

　 public void setItemChecked (int position, boolean value)

設置position所指定項目的選擇狀態。只有選擇模式為CHOICE_MODE_SINGLE或者CHOICE_MODE_MULTIPLE時，此設置才有效。

參數

position 需要改變選擇狀態的項目的索引

value 新的選擇狀態

 

　 public void setItemsCanFocus (boolean itemsCanFocus)

表明在由ListAdapter創建的視圖中，可包含能獲得焦點的項目。

參數

itemsCanFocus 若項目能獲得焦點，則設為true；否則為false

 

　 public void setSelection (int position)

選中position指定的項目。若為觸摸模式，則指定項目不會被選中，但位置變化一樣。若position的值小於0，則position為0的項目將被選中。

參數

position 需要選中的項目的索引（從0開始）

 

　 public void setSelectionAfterHeaderView ()

選中頁眉視圖下的第一個列表項目。

 

　 public void setSelectionFromTop (int position, int y)

選中position指定的項目，並將所選項置於距離ListView頂端y像素的位置（若為觸摸模式，則指定項目不會被選中，但位置變化一樣）。

參數

position 需要選中的項目的索引（從0開始）

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

 

　　七、受保護方法

 

protected boolean canAnimate ()

表示此視圖組是否可以在第一次被布局後，仍可以動態調整其子項。

返回

若可以則為true，否則為false

 

　 protected void dispatchDraw (Canvas canvas)

調用此方法來繪出子視圖。可被衍生類重寫，以便在其子項被畫出之前取得控制權。

參數

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

 

　 protected View findViewTraversal (int id)

參數

id 要找的View的id

返回值

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

 

　 protected View findViewWithTagTraversal (Object tag)

參數

tag 要找的View的標簽

返回值

有此標簽的View，若沒有找到則為null

 

　 protected void layoutChildren ()

子類必須重寫此方法來布局其子項。

 

　 protected void onFinishInflate ()

當View以及所有子項從XML中導入時被調用，是導入的最後一步。即使子類重寫onFinishInflate，也必須保證有調用超方法，這樣，方法才會被調用。

 

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

當View的焦點改變時被調用。重寫時，要確保超類的直接調用，這樣取得焦點的方式才是標准的。

　 　　參數

　　gainFocus 若View有焦點，則為True；否則為False。

　　direction 當requestFocus()被調用時，方向焦點被移動。其值可為FOCUS_UP，FOCUS_DOWN，FOCUS_LEFT或FOCUS_RIGHT。在使用缺省條件的情況下，direction並不總是可用。

　　previouslyFocusedRect 之前得到焦點的View的坐標系統所構成的矩形。如果可用，這個將被當成精確信息（表明焦點從何而來以及從何方向而來）來傳遞；否則將傳遞null。

 

　 protected void onMeasure (int widthMeasureSpec, int heightMeasureSpec)

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

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

編寫基類的確認大小的方法，缺省情況下是根據其背景大小來確認，除非MeasureSepc允許有更大的高度或寬度。子類必須重寫onMeasure(int,int)以得到對其內容大小的更准確的測量。

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

　 　　參數

　　widthMeaureSpec 受上一層大小影響下的對水平空間的要求。可參看View.MeasureSpec。

　　heightMeasureSpec 受上一層大小影響下的對垂直空間的要求。可參看View.MeasureSpec。

 

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

當VIew的大小改變時此方法被調用。如果VIew是剛剛被加入，則視之前的值為0。

參數

　　w View的當前寬度

　　h View的當前高度

　　oldw View大小改變之前的寬度

oldh View大小改變之前的高度