iOS 开发 之 - UIScrollView文档

#import <Foundation/Foundation.h>
#import <CoreGraphics/CoreGraphics.h>
#import <UIKit/UIView.h>
#import <UIKit/UIGeometry.h>
#import <UIKit/UIKitDefines.h>

typedef enum {
    UIScrollViewIndicatorStyleDefault,     // black with white border. good against any background
    UIScrollViewIndicatorStyleBlack,       // black only. smaller. good against a white background
    UIScrollViewIndicatorStyleWhite        // white only. smaller. good against a black background
} UIScrollViewIndicatorStyle;

UIKIT_EXTERN const float UIScrollViewDecelerationRateNormal __OSX_AVAILABLE_STARTING(__MAC_NA,__IPHONE_3_0);
UIKIT_EXTERN const float UIScrollViewDecelerationRateFast __OSX_AVAILABLE_STARTING(__MAC_NA,__IPHONE_3_0);

@class UIEvent, UIImageView, UIPanGestureRecognizer, UIPinchGestureRecognizer;
@protocol UIScrollViewDelegate;

UIKIT_CLASS_AVAILABLE(2_0) @interface UIScrollView : UIView <NSCoding> {
  @package
    CGSize       _contentSize;
    UIEdgeInsets _contentInset;
    id           _delegate;
    UIImageView* _verticalScrollIndicator;
    UIImageView* _horizontalScrollIndicator;
    UIEdgeInsets _scrollIndicatorInset;
    struct {
        unsigned int tracking:1;
        unsigned int dragging:1;
        unsigned int verticalBounceEnabled:1;
        unsigned int horizontalBounceEnabled:1;
        unsigned int verticalBouncing:1;
        unsigned int horizontalBouncing:1;
        unsigned int bouncesZoom:1;
        unsigned int zoomBouncing:1;
        unsigned int alwaysBounceHorizontal:1;
        unsigned int alwaysBounceVertical:1;
        unsigned int canCancelContentTouches:1;
        unsigned int delaysContentTouches:1;
        unsigned int programmaticScrollDisabled:1;
        unsigned int scrollDisabled:1;
        unsigned int zoomDisabled:1;
        unsigned int scrollTriggered:1;
        unsigned int scrollDisabledOnTouchBegan:1;
        unsigned int ignoreNextTouchesMoved:1;
        unsigned int cancelNextContentTouchEnded:1;
        unsigned int inContentViewCall:1;
        unsigned int dontSelect:1;
        unsigned int contentTouched:1;
        unsigned int cantCancel:1;
        unsigned int directionalLockEnabled:1;
        unsigned int directionalLockAutoEnabled:1;
        unsigned int lockVertical:1;
        unsigned int lockHorizontal:1;
        unsigned int keepLocked:1;
        unsigned int showsHorizontalScrollIndicator:1;
        unsigned int showsVerticalScrollIndicator:1;
        unsigned int indicatorStyle:2;
        unsigned int inZoom:1;
        unsigned int hideIndicatorsInZoom:1;
        unsigned int pushedTrackingMode:1;
        unsigned int multipleDrag:1;
        unsigned int displayingScrollIndicators:1;
        unsigned int verticalIndicatorShrunk:1;
        unsigned int horizontalIndicatorShrunk:1;
        unsigned int contentFitDisableScrolling:1;
        unsigned int pagingEnabled:1;
        unsigned int pagingLeft:1;
        unsigned int pagingRight:1;
        unsigned int pagingUp:1;
        unsigned int pagingDown:1;
        unsigned int lastHorizontalDirection:1;
        unsigned int lastVerticalDirection:1;
        unsigned int dontScrollToTop:1;
        unsigned int scrollingToTop:1;
        unsigned int useGestureRecognizers:1;
        unsigned int autoscrolling:1;
        unsigned int automaticContentOffsetAdjustmentDisabled:1;
        unsigned int skipStartOffsetAdjustment:1;
        unsigned int delegateScrollViewDidScroll:1;
        unsigned int delegateScrollViewDidZoom:1;
        unsigned int delegateContentSizeForZoomScale:1;
        unsigned int preserveCenterDuringRotation:1;
        unsigned int delaysTrackingWhileDecelerating:1;
        unsigned int pinnedZoomMin:1;
        unsigned int pinnedXMin:1;
        unsigned int pinnedYMin:1;
        unsigned int pinnedXMax:1;
        unsigned int pinnedYMax:1;
        unsigned int skipLinkChecks:1;
        unsigned int staysCenteredDuringPinch:1;
        unsigned int wasDelayingPinchForSystemGestures:1;
        unsigned int systemGesturesRecognitionPossible:1;
        unsigned int disableContentOffsetRounding:1;
        unsigned int adjustedDecelerationTargetX:1;
        unsigned int adjustedDecelerationTargetY:1;
    } _scrollViewFlags;
    CGFloat           _farthestDistance;
    CGPoint           _initialTouchPosition;
    CGPoint           _startTouchPosition;
    CFTimeInterval    _startTouchTime;
    double            _startOffsetX;
    double            _startOffsetY;
    double            _lastUpdateOffsetX;
    double            _lastUpdateOffsetY;
    CGPoint           _lastTouchPosition;
    CFTimeInterval    _lastTouchTime;
    CFTimeInterval    _lastUpdateTime;
    UIView           *_contentView;
    float             _minimumZoomScale;
    float             _maximumZoomScale;
    UIView           *_zoomView;
    double            _horizontalVelocity;
    double            _verticalVelocity;
    double            _previousHorizontalVelocity;
    double            _previousVerticalVelocity;
    CFTypeRef         _scrollHeartbeat;
    CGPoint           _pageDecelerationTarget;
    CGSize            _decelerationFactor;
    CGPoint           _adjustedDecelerationTarget;
    CGSize            _adjustedDecelerationFactor;
    double            _decelerationLnFactorH;
    double            _decelerationLnFactorV;
    NSArray*          _deferredBeginTouchesInfo;
    UIImageView * __strong *_shadows;
    id                _scrollNotificationViews;
    CFTimeInterval    _contentOffsetAnimationDuration;
    id                _animation;
    id                _pinch;
    id                _pan;
    id                _swipe;
    CGFloat           _pagingSpringPull;
    CGFloat           _pagingFriction;
    NSInteger         _fastScrollCount;
    CGFloat           _fastScrollMultiplier;
    CGFloat           _fastScrollStartMultiplier;
    CFTimeInterval    _fastScrollEndTime;
    CGPoint           _parentAdjustment;
    CGPoint           _rotationCenterPoint;
    CGFloat           _accuracy;
    CGFloat           _hysteresis;
    NSUInteger        _zoomAnimationCount;
}

@property(nonatomic)         CGPoint                      contentOffset;                  
// default CGPointZero。
//在滚轴视图中，contentOffset属性可以跟踪UIScrollView的具体位置，你能够自己获取和设置它，contentOffset的值是你当前可视内容在滚轴视图上面偏移原来的左上角那个点的偏移量，有contentOffset.x和contentOffset.y。

@property(nonatomic)         CGSize                       contentSize;                    
// default CGSizeZero。
//contentSize是内容的大小，也就是可以滚动的大小。默认是0，没有滚动效果。

@property(nonatomic)         UIEdgeInsets                 contentInset; 
// default UIEdgeInsetsZero. add additional scroll area around content
//contentInset增加你在contentSize中指定的内容能够滚动的上下左右区域数量。contentInset.top、contentInset.buttom、contentInset.left、contentInset.right分别表示上面，下面，左边和右边的距离。

@property(nonatomic,assign) id<UIScrollViewDelegate>      delegate;                       
// default nil. weak reference
//设置代理

@property(nonatomic,getter=isDirectionalLockEnabled) BOOL directionalLockEnabled;         
// default NO. if YES, try to lock vertical or horizontal scrolling while dragging
//默认是NO，可以在垂直和水平方向同时运动。当值是YES时，假如一开始是垂直或者是水平运动，那么接下来会锁定另外一个方向的滚动。假如一开始是对角方向移动，则不会禁止某个方向。

@property(nonatomic)         BOOL                         bounces;                        
// default YES. if YES, bounces past edge of content and back again
//默认是YES，就是滚动超过边界会反弹，有反弹回来的效果。如果是NO，那么滚动到达边界会立即停止

@property(nonatomic)         BOOL                         alwaysBounceVertical;           // default NO. if YES and bounces is YES, even if content is smaller than bounds, allow drag vertically
@property(nonatomic)         BOOL                         alwaysBounceHorizontal;         // default NO. if YES and bounces is YES, even if content is smaller than bounds, allow drag horizontally
@property(nonatomic,getter=isPagingEnabled) BOOL          pagingEnabled;                  
// default NO. if YES, stop on multiples of view bounds
//当值是YES会自动滚到subview的边界，默认为NO

@property(nonatomic,getter=isScrollEnabled) BOOL          scrollEnabled;                  
// default YES. turn off any dragging temporarily
//决定是否可以滚动

@property(nonatomic)         BOOL                         showsHorizontalScrollIndicator; 
// default YES. show indicator while we are tracking. fades out after tracking
//滚动时是否显示水平滚动条

@property(nonatomic)         BOOL                         showsVerticalScrollIndicator;   
// default YES. show indicator while we are tracking. fades out after tracking
//滚动时是否显示垂直滚动条

@property(nonatomic)         UIEdgeInsets                 scrollIndicatorInsets;          
// default is UIEdgeInsetsZero. adjust indicators inside of insets
//设置滚动条的位置

@property(nonatomic)         UIScrollViewIndicatorStyle   indicatorStyle;                 
// default is UIScrollViewIndicatorStyleDefault
//滚动条的样式，基本只是设置颜色，总共3个颜色：默认、黑、白。

@property(nonatomic)         float                        decelerationRate __OSX_AVAILABLE_STARTING(__MAC_NA,__IPHONE_3_0);
//设置手指放开后的减速率

- (void)setContentOffset:(CGPoint)contentOffset animated:(BOOL)animated;  
// animate at constant velocity to new offset
- (void)scrollRectToVisible:(CGRect)rect animated:(BOOL)animated;         
// scroll so rect is just visible (nearest edges). nothing if rect completely visible
//上面这个两个函数用来自动滚到到想要的位置，此过程中设置有动画效果，停止时，触发该函数。当animated为YES的时候有动画效果

- (void)flashScrollIndicators;             // displays the scroll indicators for a short time. This should be done whenever you bring the scroll view to front.

 

@property(nonatomic,readonly,getter=isTracking)     BOOL tracking;       
// returns YES if user has touched. may not yet have started dragging
//当touch后还没有拖动的时候是YES，否则为NO

@property(nonatomic,readonly,getter=isDragging)     BOOL dragging;        // returns YES if user has started scrolling. this may require some time and or distance to move to initiate dragging
@property(nonatomic,readonly,getter=isDecelerating) BOOL decelerating;    
// returns YES if user isn‘t dragging (touch up) but scroll view is still moving
//当滚动后，手指放开但是还在继续滚动中。这个时候是YES，其他时候 NO

@property(nonatomic) BOOL delaysContentTouches;       
// default is YES. if NO, we immediately call -touchesShouldBegin:withEvent:inContentView:
//当值是YES的时候，用户触碰开始，scroll view要延迟一会，看看是否用户有意图滚动。假如滚到了，那么捕捉touch-down事件，否则就不捕捉。假如值是NO，当用户触碰，scroll view会立即触发touchesSholdBegin:withEvent:inContentView:。默认为YES。

@property(nonatomic) BOOL canCancelContentTouches;    
// default is YES. if NO, then once we start tracking, we don‘t try to drag if the touch moves
//当值是YES的时候，用户触碰后，然后在一定时间内没有移动，scrollView发送tracking events，然后用户移动手指足够长度触发滚动事件，这个时候，scrollview发送了touchesCancelled:withEvent:到subview，然后scrollview开始滚动。假如为NO，scrollview发送tracking events后，就算用户移动手指，scrollview也不会滚动。

// override points for subclasses to control delivery of touch events to subviews of the scroll view
// called before touches are delivered to a subview of the scroll view. if it returns NO the touches will not be delivered to the subview
// default returns YES。决定自己是否接收touch事件
- (BOOL)touchesShouldBegin:(NSSet *)touches withEvent:(UIEvent *)event inContentView:(UIView *)view;

// called before scrolling begins if touches have already been delivered to a subview of the scroll view. if it returns NO the touches will continue to be delivered to the subview and scrolling will not occur
// not called if canCancelContentTouches is NO. default returns YES if view isn‘t a UIControl
- (BOOL)touchesShouldCancelInContentView:(UIView *)view;
//开始发送tracking message消息给subview的时候调用这个方法，决定是否发送tracking message消息给subview。假如返回NO，发送，YES则不发送。

 

@property(nonatomic) float minimumZoomScale;     
// default is 1.0。表示能缩最小的倍数

@property(nonatomic) float maximumZoomScale;     
// default is 1.0. must be > minimum zoom scale to enable zooming。表示能放最大的倍数

@property(nonatomic) float zoomScale __OSX_AVAILABLE_STARTING(__MAC_NA,__IPHONE_3_0);            // default is 1.0
- (void)setZoomScale:(float)scale animated:(BOOL)animated __OSX_AVAILABLE_STARTING(__MAC_NA,__IPHONE_3_0);
- (void)zoomToRect:(CGRect)rect animated:(BOOL)animated __OSX_AVAILABLE_STARTING(__MAC_NA,__IPHONE_3_0);

@property(nonatomic) BOOL  bouncesZoom;          
// default is YES. if set, user can go past min/max zoom while gesturing and the zoom will animate to the min/max value at gesture end
//和bounces类似，区别在于：这个效果反映在缩放方面假如缩放超过最大缩放，那么会有反弹效果；假如是NO，则到达最大或者最小的时候立即停止

@property(nonatomic,readonly,getter=isZooming)       BOOL zooming;      
// returns YES if user in zoom gesture。当正在缩放的时候是YES，否则为NO

@property(nonatomic,readonly,getter=isZoomBouncing)  BOOL zoomBouncing; 
//returns YES if we are in the middle of zooming back to the min/max value。
//当内容放大到最大或者最小的时候值是YES，否则为NO

// When the user taps the status bar, the scroll view beneath the touch which is closest to the status bar will be scrolled to top, but only if its `scrollsToTop` property is YES, its delegate does not return NO from `shouldScrollViewScrollToTop`, and it is not already at the top.
// On iPhone, we execute this gesture only if there‘s one on-screen scroll view with `scrollsToTop` == YES. If more than one is found, none will be scrolled.
@property(nonatomic) BOOL  scrollsToTop;          // default is YES.

// Use these accessors to configure the scroll view‘s built-in gesture recognizers.
// Do not change the gestures‘ delegates or override the getters for these properties.
@property(nonatomic, readonly) UIPanGestureRecognizer *panGestureRecognizer __OSX_AVAILABLE_STARTING(__MAC_NA, __IPHONE_5_0);
// `pinchGestureRecognizer` will return nil when zooming is disabled.
@property(nonatomic, readonly) UIPinchGestureRecognizer *pinchGestureRecognizer __OSX_AVAILABLE_STARTING(__MAC_NA, __IPHONE_5_0);

@end

@protocol UIScrollViewDelegate<NSObject>

@optional

- (void)scrollViewDidScroll:(UIScrollView *)scrollView;                                               
// any offset changes
//触摸屏幕来滚动画面还是其他的方法使得画面滚动，皆触发该函数

- (void)scrollViewDidZoom:(UIScrollView *)scrollView __OSX_AVAILABLE_STARTING(__MAC_NA,__IPHONE_3_2); // any zoom scale changes

// called on start of dragging (may require some time and or distance to move)
- (void)scrollViewWillBeginDragging:(UIScrollView *)scrollView;
// called on finger up if the user dragged. velocity is in points/second. targetContentOffset may be changed to adjust where the scroll view comes to rest. not called when pagingEnabled is YES
- (void)scrollViewWillEndDragging:(UIScrollView *)scrollView withVelocity:(CGPoint)velocity targetContentOffset:(inout CGPoint *)targetContentOffset __OSX_AVAILABLE_STARTING(__MAC_NA,__IPHONE_5_0);

// called on finger up if the user dragged. decelerate is true if it will continue moving afterwards
- (void)scrollViewDidEndDragging:(UIScrollView *)scrollView willDecelerate:(BOOL)decelerate;
//触摸屏幕并拖拽画面，再松开，最后停止时，触发该函数

- (void)scrollViewWillBeginDecelerating:(UIScrollView *)scrollView;   // called on finger up as we are moving
- (void)scrollViewDidEndDecelerating:(UIScrollView *)scrollView;     
 // called when scroll view grinds to a halt
//滚动停止时，触发该函数

- (void)scrollViewDidEndScrollingAnimation:(UIScrollView *)scrollView; // called when setContentOffset/scrollRectVisible:animated: finishes. not called if not animating

//scroll view还处理缩放和平移手势，要实现缩放和平移，必须实现委托viewForZoomingInScrollView:和scrollViewDidEndZooming:withView:atSacle:两个方法。另外maximumZoomScale和mimimumZoomScale两个属性要不一样
- (UIView *)viewForZoomingInScrollView:(UIScrollView *)scrollView;     // return a view that will be scaled. if delegate returns nil, nothing happens
- (void)scrollViewWillBeginZooming:(UIScrollView *)scrollView withView:(UIView *)view __OSX_AVAILABLE_STARTING(__MAC_NA,__IPHONE_3_2); // called before the scroll view begins zooming its content
- (void)scrollViewDidEndZooming:(UIScrollView *)scrollView withView:(UIView *)view atScale:(float)scale; // scale between minimum and maximum. called after any ‘bounce‘ animations

- (BOOL)scrollViewShouldScrollToTop:(UIScrollView *)scrollView;   // return a yes if you want to scroll to the top. if not defined, assumes YES
- (void)scrollViewDidScrollToTop:(UIScrollView *)scrollView;      // called when scrolling animation finished. may be called immediately if already at top

@end