Android 中文 API (100) —— ScrollView

前言

　　本章內容是android.widget.ScrollView，版本為Android 2.3 r1，翻譯來自"pengyouhong"，再次感謝"pengyouhong" ！
 

 

正文

　　一、結構

 

public class ScrollView extends FrameLayout

        

java.lang.Object

android.view.View

         android.view.ViewGroup

                   android.widget.FrameLayout

                            android.widget.ScrollView

 

 

　　二、概述

 

　　一種可供用戶滾動的層次結構布局容器，允許顯示比實際多的內容。ScrollView是一種FrameLayout，意味需要在其上放置有自己滾動內容的子元素。子元素可以是一個復雜的對象的布局管理器。通常用的子元素是垂直方向的LinearLayout，顯示在最上層的垂直方向可以讓用戶滾動的箭頭。

　　TextView類也有自己的滾動功能，所以不需要使用ScrollView，但是只有兩個結合使用，才能保證顯示較多內容時候的效率。但只有兩者結合使用才可以實現在一個較大的容器中一個文本視圖效果。

　　ScrollView只支持垂直方向的滾動。

 

 

　　三、構造函數

 

public ScrollView (Context context)

創建一個默認屬性的ScrollView實例。

 

public ScrollView (Context context, AttributeSet attrs)

創建一個帶有attrs屬性的ScrollView 實例。

 

public ScrollView (Context context, AttributeSet attrs, int defStyle)

創建一個帶有attrs屬性，並且指定其默認樣式的ScrollView實例。

 

 

　　四、公共方法

 

　  public void addView (View child)

       　　添加子視圖。如果事先沒有給子視圖設置layout參數，會采用當前ViewGroup的默認參數來設置子視圖。

              　　參數

                     　　child       所添加的子視圖

 

　　public void addView (View child, int index)

　　添加子視圖。如果事先沒有給子視圖設置layout參數，會采用當前ViewGroup的默認參數來設置子視圖。

　　  參數

　　 child       所添加的子視圖

            　　  index      添加子視圖的位置

        

　　public void addView (View child, int index, ViewGroup.LayoutParams params)

　　根據指定的layout參數添加子視圖

　　參數

             　　child       所添加的子視圖

             　　index      添加子視圖的位置

             　　params   為子視圖設置的layout參數

 

　　public void addView (View child, ViewGroup.LayoutParams params)

　　根據指定的layout參數添加子視圖。

　　參數

             　　child       所添加的子視圖

             　　params   為子視圖設置的layout參數

 

　　public boolean arrowScroll (int direction)

　　響應點擊上下箭頭時對滾動條滾動的處理。

              　　參數

                     　　direction        按下的箭頭所對應的方向

　　返回值

　　如果我們處理（消耗）了此事件返回true，否則返回false。

 

　　public void computeScroll ()

　　被父視圖調用，用於必要時候對其子視圖的值（mScrollX和mScrollY）進行更新。典型的情況如：父視圖中某個子視圖使用一個Scroller對象來實現滾動操作，會使得此方法被調用。

 

　　public boolean dispatchKeyEvent (KeyEvent event)

       　　發送一個key事件給當前焦點路徑的下一個視圖。此焦點路徑從視圖樹的頂層執行直到當前焦點視圖。如果此視圖為焦點視圖，將為自己發送。否則，會為當前焦點路徑的下一個節點發送。此方法也會激起一個key監聽器。

　　參數

                     　　event     發送的key事件

　　返回值

　　事件被處理返回true，否則返回false。

 

　　public void draw (Canvas canvas)

　　手動繪制視圖（及其子視圖）到指定的畫布(Canvas)。這個視圖必須在調用這個函數之前做好了整體布局。當實現一個視圖時，不需要繼承這個方法；相反，你應該實現onDraw(Canvas)方法。

　　參數

　　canvas    繪制視圖的畫布

 

　　public boolean executeKeyEvent (KeyEvent event)

　　當接收到key事件時，用戶可以調用此函數來使滾動視圖執行滾動，類似於處理由視圖體系發送的事件。

　　參數

　　event     需要執行key的事件

　　返回值

　　事件被處理返回true，否則返回false。

 

　　public void fling (int velocityY)

　　滾動視圖的滑動（fling）手勢。（譯者注： 如何監聽android的屏幕滑動停止事件）

　　參數

                     　　velocityY      Y方向的初始速率。正值表示手指/光標向屏幕下方滑動，而內容將向上滾動。

 

　　public boolean fullScroll (int direction)

　　對響應“home/end”短按時響應滾動處理。此方法將視圖滾動到頂部或者底部，並且將焦點置於新的可視區域的最頂部/最底部組件。若沒有適合的組件做焦點，當前的ScrollView會收回焦點。

　　參數

　　direction 滾動方向：FOCUS_UP表示視圖向上滾動；FOCUS_DOWN表示視圖向下滾動

　　返回值

　　若key事件被消耗(consumed)返回true，其他情況返回false。

 

　　public int getMaxScrollAmount ()

　　返回值

　　當前滾動視圖響應箭頭事件能夠滾動的最大數。

 

　　public boolean isFillViewport ()

　　指示當前ScrollView的內容是否被拉伸以填充視圖可視范圍（譯者注：viewport可視范圍，參見決定Scrollviewer裡面Control的可視范圍）。

　　返回值

　　內容填充視圖返回true，否則返回false。

 

　　public boolean isSmoothScrollingEnabled ()

　　返回值

             　　按箭頭方向滾動時，是否顯示滾動的平滑效果。

 

　　public boolean onInterceptTouchEvent (MotionEvent ev)

　　實現此方法是為了攔截所有觸摸屏幕時的運動事件。可以像處理發送給子視圖的事件一樣去監視這些事件，並且獲取當前手勢在任意點的ownership

　　使用此方法時候需要注意，因為它與View.onTouchEvent(MotionEvent)有相當復雜的交互，並且前提需要正確執行View.onTouchEvent(MotionEvent)。事件將按照如下順序接收到：

　　1.    收到down事件

　　2.    Down事件或者由視圖組的一個子視圖處理，或者被用戶自己的onTouchEvent()方法處理；此處理意味你應該執行onTouchEvent()時返回true，這樣才能繼續看到剩下的手勢（取代找一個父視圖處理）。如果onTouchEvent()返回true時，你不會收到onInterceptTouchEvent()的任何事件並且所有對觸摸的處理必須在onTouchEvent()中發生。

　　3.    如果此方法返回false，接下來的事件（up to and including the final up）將最先被傳遞當此，然後是目標的onTouchEvent()。

　　4.    如果返回true，將不會收到以下任何事件：目標view將收到同樣的事件但是會伴隨ACTION_CANCEL，並且所有的更進一步的事件將會傳遞到你自己的onTouchEvent()方法中而不會再在這裡出現。

　　參數

            　　 ev          體系向下發送的動作事件

　　返回值

　 如果將運動事件從子視圖中截獲並且通過onTouchEvent()發送到當前ViewGroup ，返回true。當前目標將會收到ACTION_CANCEL事件，並且不再會有其他消息傳遞到此。

              （譯者注：onInterceptTouchEvent和onTouchEvent調用時序）

 

　　public boolean onTouchEvent (MotionEvent ev)

　　執行此方法為了處理觸摸屏幕的運動事件。

　　參數

     　　ev          運動事件

　　返回值

　　事件被處理返回true，其它返回false。

 

　　public boolean pageScroll (int direction)

　　響應短按“page up/ down”時候對滾動的處理。此方法將向上或者向下滾動一屏，並且將焦點置於新可視區域的最上/最下。如果沒有適合的component作為焦點，當前scrollView將收回焦點。

　　參數

     　　direction        滾動方向：FOCUS_UP表示向上翻一頁，FOCUS_DOWN表示向下翻一頁。

　　返回值

　　此key事件被消耗(cosumed)返回true，其他返回false。

 

　　public void requestChildFocus (View child, View focused)

　　當父視圖的一個子視圖的要獲得焦點時，調用此方法。

　　參數

     　　child              要獲得焦點的父視圖的子視圖。此視圖包含了焦點視圖。如果沒有特殊徐要求，此視圖實際上就是焦點視圖。

              　　focused        子視圖的子孫視圖並且此子孫視圖是真正的焦點視圖

 

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

　　當組裡的某個子視圖需要被定位在屏幕的某個矩形范圍時，調用此方法。重載此方法的ViewGroup可確認以下幾點：

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

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

　　重載此方法的ViewGroup應該支持以下幾點：

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

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

　　參數

　　child        發出請求的子視圖

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

　　immediate   設為true，則禁止動畫和平滑移動滾動條

      　　返回值

            　　進行了滾動操作的這個組（group），是否處理此操作。

　　public void requestLayout ()

　　當有改變引起當前視圖重新布局時，調用此函數。它將規劃一個視圖樹的layout路徑。

 

　　public void scrollTo (int x, int y)

　　設置當前視圖滾動到的位置。此函數會引起對onScrollChanged(int, int, int, int)函數的調用並且會讓視圖更新。

當前版本取消了在子視圖中的滾動。

　　參數

     　　x     滾動到的X位置

              　　y     滾動到的Y位置

 

　　public void setFillViewport (boolean fillViewport)

　　設置當前滾動視圖是否將內容高度拉伸以填充視圖可視范圍（譯者注：viewport可視范圍，參見決定Scrollviewer裡面Control的可視范圍）。

　　參數

     　　fillViewport    設置為true表示拉伸內容高度來適應視口邊界；其他設為false。

 

　　public void setOverScrollMode (int mode)

　　為視圖設置over-scroll模式。有效的over-scroll模式有OVER_SCROLL_ALWAYS（缺省值），OVER_SCROLL_IF_CONTENT_SCROLLS（只允許當視圖內容大過容器時，進行over-scrolling）和OVER_SCROLL_NEVER。只有當視圖可以滾動時，此項設置才起作用。

（譯者注：這個函數是2.3 r1 中新增的，API Level 9。關於over-scroll這裡譯為彈性滾動，即，參見帖子：類似iPhone的彈性ListView滾動）

         參數

                   mode       The new over-scroll mode for this view.

 

　　public void setSmoothScrollingEnabled (boolean smoothScrollingEnabled)

　　用來設置箭頭滾動是否可以引發視圖滾動。

　　參數

              　　smoothScrollingEnabled    設置箭頭滾動是否可以引起內容的滾動的bool值

 

　　public final void smoothScrollBy (int dx, int dy)

　　類似於scrollBy(int, int)，但是滾動時候是平緩的而不是立即滾動到某處。

　　參數

     　　dx   在X方向滾動的像素數

     　　dy   在Y方向滾動的像素數

 

　　public final void smoothScrollTo (int x, int y)

　　類似於scrollTo(int, int)，但是滾動時候是平緩的而不是立即滾動到某處。

　　參數

     　　x     要滾動到位置的X坐標

             　　 y     要滾動到位置的Y坐標

 

 

　　五、受保護方法

 

　　protected int computeScrollDeltaToGetChildRectOnScreen (Rect rect)

　　計算X方向滾動的總合，以便在屏幕上顯示子視圖的完整矩形（或者，若矩形寬度超過屏幕寬度，至少要填滿第一個屏幕大小）。

　　參數

     　　rect        矩形

　　返回值

　　滾動差值

 

　　protected int computeVerticalScrollOffset ()

　　計算垂直方向滾動條的滑塊的偏移。此值用來計算滾動條軌跡的滑塊的位置。

　　范圍可以以任意單位表示，但是必須與computeVerticalScrollRange()和computeVerticalScrollExtent()的單位一致。

　　缺省的偏移是在當前視圖滾動的偏移。

　　返回值

　　滾動條的滑塊垂直方向的偏移。

 

　　protected int computeVerticalScrollRange ()

　　滾動視圖的可滾動范圍是所有子元素的高度。

　　返回值

　　由垂直方向滾動條代表的所有垂直范圍，缺省的范圍是當前視圖的畫圖高度。

 

　　protected float getBottomFadingEdgeStrength ()

　　返回滾動底部的能見度。能見度的值的范圍是0.0（沒有消失）到1.0（完全消失）之間。缺省的執行返回值為0.0或者1.0，而不是他們中間的某個值。滾動時子類需要重載這個方法來提供一個平緩的漸隱的實現。

　　返回值

　　滾動底部能見度，值的范圍在浮點數0.0f到1.0f之間。

 

　　protected float getTopFadingEdgeStrength ()

　　返回滾動頂部的能見度。能見度的值的范圍是0.0（沒有消失）到1.0（完全消失）之間。缺省的執行返回值為0.0或者1.0，而不是他們中間的某個值。滾動時子類需要重載這個方法來提供一個平緩的漸隱的實現。

　　返回值

　　滾動頂部能見度，值的范圍在浮點數0.0f到1.0f之間。

 

　　protected void measureChild (View child, int parentWidthMeasureSpec, int parentHeightMeasureSpec)

　　要求當前視圖的一個子視圖測量自己，同時兼顧到當前視圖的MeasureSpec的要求和它的空白。子視圖必須有MarginLayoutParams。比較復雜的工作是在getChildMeasureSpec中完成的。

　　參數

　　child              需要自己測量的子視圖

　　parentWidthMeasureSpec        當前視圖要求的寬度

　　parentHeightMeasureSpec              當前視圖要求的寬度

 

　　protected void measureChildWithMargins (View child, int parentWidthMeasureSpec, int widthUsed, int parentHeightMeasureSpec, int heightUsed)

　　要求當前視圖的一個子視圖測量自己，同時兼顧到當前視圖的MeasureSpec的要求和它的空白和邊界。子視圖必須有MarginLayoutParams。比較復雜的工作是在getChildMeasureSpec中完成的。

　　參數

　　child             需要測量的子視圖

　　parentWidthMeasureSpec       當前視圖要求的寬度

　　widthUsed    水平方向上由父視圖使用的空白 (也可能是視圖的其他子視圖使用的)

　　parentHeightMeasureSpec      當前視圖要求的寬度

　　heightUsed 垂直方向上由父視圖使用的空白 (也可能是視圖的其他子視圖使用的)

 

　　protected void onLayout (boolean changed, int l, int t, int r, int b)

　　當前視圖需要為子視圖分配大小和位置時候調用，子類繼承必須要重載此方法並調用自己子視圖的layout函數。

　　參數

　　changed       當前視圖的新的大小或者位置

　　l     相對父視圖，左邊界位置

　　t     相對父視圖，上邊界位置

　　r     相對父視圖，右邊界位置

　　b    相對父視圖，下邊界位置

 

　　protected void onMeasure (int widthMeasureSpec, int heightMeasureSpec)

　　測量視圖以確定其內容寬度和高度。此方法被measure(int, int)調用。需要被子類重寫以提供對其內容准確高效的測量。

　　約定：當重寫此方法時，你必須調用setMeasuredDimension(int, int)來保存當前視圖view的寬度和高度。不成功調用此方法將會導致一個IllegalStateException異常，是由measure(int, int)拋出。所以調用父類的onMeasure(int, int)方法是必須的。

　　父類的實現是以背景大小為默認大小，除非MeasureSpec（測量細則）允許更大的背景。子類可以重寫onMeasure(int,int)以對其內容提供更佳的尺寸。

　　如果此方法被重寫，那麼子類的責任是確認測量高度和測量寬度要大於視圖view的最小寬度和最小高度（getSuggestedMinimumHeight() 和 getSuggestedMinimumWidth()），使用這兩個方法可以取得最小寬度和最小高度。

　　參數

　　widthMeasureSpec   受主窗口支配的水平空間要求。這個需求通過 View.MeasureSpec.進行編碼。

       　　 　　　heightMeasureSpec  受主窗口支配的垂直空間要求。這個需求通過 View.MeasureSpec.進行編碼。

 

　　　　protected void onOverScrolled (int scrollX, int scrollY, boolean clampedX, boolean clampedY)

       　　被overScrollBy(int, int, int, int, int, int, int, int, boolean)調用，來對一個over-scroll操作的結果進行響應。（譯者注：這個函數是2.3 r1 中新增的，API Level 9）

　　參數

　　scrollX     新的X滾動像素值

　　scrollY     新的Y滾動像素值

　　clampedX        當scrollX被over-scroll的邊界限制時，值為true

　　clampedY        當scrollY被over-scroll的邊界限制時，值為true

 

　　protected boolean onRequestFocusInDescendants (int direction, Rect previouslyFocusedRect)

　　當在滾動視圖的子視圖中查找焦點視圖時，需要注意不要將焦點設置在滾動出屏幕外的控件上。此方法會比執行缺省的ViewGroup代價高，否則此行為也會設置為缺省

　　參數

             　　direction 指定下列常量之一：FOCUS_UP, FOCUS_DOWN, FOCUS_LEFT, FOCUS_RIGHT

previouslyFocusedRect 能夠給出一個較好的提示的矩形（當前視圖的坐標系統）表示焦點從哪裡得來。如果沒有提示為null。

　　返回值

　　是否取得了焦點

 

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

布局期間當視圖的大小發生改變時調用。如果只是添加到視圖，調用時顯示的是舊值0。（譯者注：也就是添加到視圖時，oldw和oldh返回的是0）。

　　參數

　　w     視圖當前寬度

　　h     視圖當前高度

　　oldw       視圖改變前的寬度

　　oldh       視圖改變前的高度