Android API 中文 (42) —— ListView

正文

　　一、結構

　　　　public class RatingBar extends AbsSeekBar

　　　　java.lang.Object

　　　　　　　　android.view.ViewGroup

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

                            　　android.widget.AbsListView

                                 　　 android.widget.ListView

　　　　直接子類

　　　　　　ExpandableListView （使用豎滾動條檢視的兩級清單視圖）

　　二、概述

　　三、内部類

         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。

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

android:headerDividersEnabled

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

可參看全局屬性資源符号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)

                　　v                         要加的視圖

                　　data                   和此視圖關聯的資料

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

　 public void addHeaderView (View v)

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

               　　 v      要加的視圖

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

                　　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 ()

         傳回被選中項目的索引集合。隻有當選擇模式沒有被設定為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（不處理該事件）。

                            repeatedCount         實作動作的次數

　 public boolean onKeyUp (int keyCode, KeyEvent event)

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

　 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)

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

                            若視圖被成功删除，則傳回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)

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

                            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像素的位置（若為觸摸模式，則指定項目不會被選中，但位置變化一樣）。

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

本文轉自over140 51CTO部落格，原文連結：http://blog.51cto.com/over140/582608，如需轉載請自行聯系原作者