Android API 中文 (42) —— ListView

前言

　　關鍵字：Android API 中文 , Android 中文 API , android.widget.ListView
 

　　本章內容是 android.widget.ListView，譯爲"列表視圖"，版本爲Android 2.2 r1，翻譯來自"Tina"，這是翻譯組至今獨立完成翻譯最長的一篇 ，再次感謝"Tina"爲你們帶來優質的翻譯稿 ！期待你一塊兒參與Android API 的中文翻譯，聯繫我over140@gmail.com。

 

聲明

　　歡迎轉載，但請保留文章原始出處:)
 

　　　　農民伯伯：http://over140.blog.51cto.com/

　　　　Android中文翻譯組：http://www.cnblogs.com/over140/  

 

正文

　　1、結構

　　　　public class RatingBar extends AbsSeekBar

 

　　　　java.lang.Object

　　　　　　android.view.View

　　　　　　　　android.view.ViewGroup

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

                            　　android.widget.AbsListView

                                 　　 android.widget.ListView

 
 

　　　　直接子類

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

 

　　2、概述

 

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

 

　　3、內部類

 

         class ListView.FixedViewInfo

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

 

　　4、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。

 

　　5、常量

 

         Int    CHOICE_MODE_MULTIPLE    

　（常量值爲2）列表容許同時選取多項

　 Int    CHOICE_MODE_NONE            

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

　 Int    CHOICE_MODE_SINGLE         

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

 
 

　　6、公共方法

 

         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（包括間隙）頂端的位置 

 

　　7、受保護方法

 

         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大小改變以前的高度 

 

　　8、補充
 

 

　　　　參考連接

                   Android入門第六篇之ListView (一)

                   android ListView詳解

                   android異步加載ListView中的圖片

                   Google I/O 2010 - The world of ListView

                   Android: 顯示SD卡文件列表

                   Android: 帶圖標的ListView實現

 

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

 

 

結束
 

　　聲明：圖片採用文章5的圖片。 這篇文章翻譯得很是優秀，譯者很是認真負責，並且這也是其第一篇譯文，再次感謝"Tina"辛勤的付出！