AppleScrollView - UBogun/Xojo-iosLib GitHub Wiki
Inherits from AppleView
Memory leak check: not yet done.
Status: complete.
This is an implementation of UIScrollView, a subclass of UIView that can contain a ContentView that is bigger than its own bounds which it can scroll and zoom. It is the base class for other scrollable views too.
General information
A ScrollView works on another AppleView as its ContentView. By default, there is none. The usual first action (preferable in the Shown event or shortly before) will be therefore to create a new AppleView and assign it to the ContentView property of the ScrollView. Its bounds will determine the scrollable area.
You can use the convenience method CreateContentView (Width as Double, Height As Double) to perform this action.
With the usual AddSubiew methods of AppleView, you can attach subviews to the ContentView which which be scrolled together with it. These can of course be controls which stay responsible as long as the Contentiew’s UserInteractionEnabled property is true and its ExclusiveTouch property is False.
This custom implementation features two additional standard GestureRecognizers like proposed on this Ray Wenderlich tutorial:
- a DoubleTapRecognizer for zooming into the view and
- a TwoFingerTapRecognizer for zooming out again.
You can disable their features by returning True in the DoubleTap and TwoFingerTap event handlers or by changing the ZoomOnDoubleTap Boolean property.
In short:
Use an AppleScrollView to
- scroll content that is bigger than the current view bounds,
- magnify and minify content via twitch gestures or code or
- magnify content via double tap and
- minify content via two finger taps.
You can also use the convenience methods of the wrapper control class iOSLibScrollView to automatically create a vertical scrolling row of several iOSViews and create a scrollable UI.
Xojo integration
To make easy use of a Scrollview, instantiate the customcontrol iOSLibScrollView. In addition to being a simple scroll/zoomview, iOSLibScrollView features a SetMultiViewScrollContent custom method too which enables you to use it for displaying vertically scrolling user interfaces.
Constructor
Constructor (aFrame AS NSRect): Creates a new UIScrollView with the dimensions in aFrame. Adds two custom GestureRecognizers to itself to enable double-tap in- and two-finger-tap out-zooming.
Properties
AlwaysBounceHorizontal As Boolean: Whether bouncing always occurs when horizontal scrolling reaches the end of the content view. Default False.
AlwaysBounceVertical As Boolean: Whether bouncing always occurs when vertical scrolling reaches the end of the content view. Default False.
Bounces As Boolean: Whether the scroll view bounces past the edge of content and back again.
BouncesZoom As Boolean: Whether the scroll view bounces past the maximum dimensions during a Zoom operation or simply stops at the limit.
CanCancelContentTouches As Boolean: Whether touches in the content view always lead to tracking.
ContentInset As UIEdgeInsets: The distance that the content view is inset from the enclosing scroll view.
ContentOffset As NSPoint: The point at which the origin of the content view is offset from the origin of the scroll view.
ContentSize As NSSize / Xojo.Core.Size: The size of the content.
ContentView As AppleView: This is the content the Scrollview should display.
Decelerating As Boolean (read-only): True if the content is moving after the user has lifted his finger.
DecelerationRate As Double: The rate at which the content is stopped from moving after the user lifted his finger. Default is 0.998.
DelaysContentTouches As Boolean: If true, the scrollview delays handling the touch-down gesture until it can determine if scrolling is the intent. If False , the scroll view immediately calls touchesShouldBegin:withEvent:inContentView:. Default is True.
DirectionalLock As Boolean: If True, the user cannot change from horizontal to vertical scroll direction until the move stopped. Default False.
DoubleTapRecognizer As AppleTapRecognizer (read-only): This is the Recognizer used to recognize double taps for zooming in on them.
Dragging As Boolean (read-only): True if the user is currently scrolling content.
ForwardTouchesToViewController As Boolean (AppleScrollView only): If True, forwards touches from a touchesShouldBegin Event to the AppleScrollViewer control.
IndicatorStyle As UIScrollViewIndicatorStyle: Lets you switch the appearance of the scroll indicators between default, black and white.
KeyboardDismissMode As UIScrollViewKeyboardDismissMode: Selects the keyboard dismiss mode: None, On Drag or Interactive.
MaximumZoomScale As Double: Exactly that: the maximum content zoom scale.
MinimumZoomScale As Double: Exactly that: the minimum content zoom scale.
PagingEnabled As Boolean: if True, scrolls pagewise.
PanGestureRecognizer As ApplePanGestureRecognizer (read-only): The recognizer used for panning/dragging gestures.
PinchGestureRecognizer As ApplePinchGestureRecognizer (read-only): The recognizer used for pinching/zooming gestures.
ScrollEnabled As Boolean: Toggles scrolling ability of the control. Default True.
ScrollIndicatorInsets As UIEdgeInsets: The distance from the scroll indicators to the border of the view. AppleScrollView property only, on view use SetScrollIndicatorInsets method.
ScrollsToTop As Boolean: If True, a double tap on the status bar scrolls the top of the content to the upper border of the view. Default True.
ShowsHorizontalScrollIndicator As Boolean: the potential visibility of the horizontal scroll bar.
ShowsVerticalScrollIndicator As Boolean: the potential visibility of the vertical scroll bar.
Tracking As Boolean (read-only): True if the user has touched the view but started no scroll or zoom movement.
TwoFingerTapRecognizer As AppleTapGestureRecognizer (read-only): The recognizer used for zooiming out via two-finger tap.
Zoomable As Boolean: A convenience property that either sets MinimumZoomScale, MaximumZoomScale and ZoomScale to 1.0 (False) or if MimimumZoomScale = MaximumZoomScale Minimum to 0.5 and Maximum to 2 (True).
ZoomBouncing As Boolean: If True, Scaling beyond zoom limits will give a bounce effect. Default True.
Zooming As Boolean (read-only): True if the user is currently zooming.
ZoomOnDoubleTap As Boolean: Convenience property to enable zoom by doubletap and zoom out by two-finger tap.
ZoomScale As Double: The scale factor of the contentView.
Methods
AnimateContentOffset (Offset As NSPoint): Animates the contentOffset change.
CenterContentView(): a convenience method for centering the contentView after a rescale of the content so that a minification will not push the content to the upper left corner. Called automatically by the DidZoom event. Override informOnDidZoom or didZoom if you don't want this to happen.
CreateContentView (Width as double, height as Double): Creates a ContentView with the specified dimensions.
FlashScrollIndicators(): Makes the scrollbars show shortly.
SetContentInset (Top, Left, bottom, right as double): Sets the distance of the content to the outer borders. AppleScrollViewer convenience method for contentInset.
SetContentOffset (Left As Double, Top as Double, opt. animated as boolean = true: Sets the offset of the contentview's content to the bounds’ origin of the contentview.
ScrollToRect (Rect As NSRect / X, Y, W, H As Double (AppleScrollViewer): Animates the visible content to the defined rect if within the zoom parameters.
SetZoomScale (Value As Double): Animates ZoomScale to the new value.
ZoomToRect (ARect As NSRect / x, y, width, height as double; opt. Animated as Boolean = true): Zooms to the new rect if inside zoom parameters.
Events
Besides the events available from its superclass AppleView (but not Draw and LayoutSubViews as well as the Touch_ events which are handled by the instance, AppleScrollView features these events:
DidDecelerate(): The contentview has stopped its scrolling motion.
DidDrag (WillDecelerate As Boolean): The user stopped dragging the content. If WillDecelerate is True, the scroll motion will continue and fade. If False, is has stopped already.
DidEndZoom(View As AppleView, Scale As Double): Fires when the Zoom gesture has completed. View is the portion of the content to scale and scale the new scalefactor.
DidScroll(): That user has scrolled the content.
DidScrollToTop(): Fires when the view was moved to top by a double-tap on the status bar.
DidZoom(): The scrollview's zoomfactor changed.
DoubleTap() As Boolean: The user doubletapped the view. Return True if you do not want the view to zoom in.
ScrollingAnimationEnded(): The content scrolling animation finished.
ShouldScrollToTop() As Boolean: If the user doubletaps on the status bar, this event fires. Return true if you want to intercept the behavior defined by the ScrollsToTop property.
TwoFingerTap() As Boolean: The user made a two-finger-tap on the view. Return true if you do not want to zoom out.
WillDecelerate(): The user started a scroll and his finger has left the view now which starts decelerating.
WillDrag(): The scroll view is about to start scrolling its content.
WillEndDrag (Velocity As NSPoint / xojo.core.point, TargetContentOffset As NSPoint / xojo.Core.Point): The user finished scrolling the control. The control has a speed vector of velocity and is estimated to come to a rest at TargetContentOffset away from its 0 position.
WillZoom (View As AppleView): The scrollview is about to zoom. View is simply its contentView.