iOSLibScrollView - UBogun/Xojo-iosLib GitHub Wiki
Native class: AppleScrollView
Inherits froms: iOSLibCanvas
iOSLibScrollView is the custom control of iOSLib containing an AppleScrollView as object. As long as there is no native Xojo scrollview it's the only iOSLib way of using a scrollable control.
Like all iOSLib custom controls, the control is a wrapper that contains the view and performs translations between Xojo and iOS classes / data types transparently whereever possible.
Like all iOSLib custom controls, if you want to attain maximum performance, you can always address the iOSClass itself via the Controls ID object. The ID object is always the View subclass itself, in this case AppleScrollView. The iOS class expects Apple native objects and data types of course. You can always use the included translation methods to bridge from Xojo types and classes to iOS.
General information
A ScrollView works on another AppleView as its ContentView. By default, there is none. The usual first action (preferably in the Shown event or shortly before) will be therefore to create a new ContentView with the convenience method CreateContentView (Width as Double, Height As Double).
With the usual EmbedControl methods of iOSLibScrollView or the AddSubviews method of the underlying AppleScrollView, you can attach subviews to the ContentView which which be scrolled together with it.
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 SetMultiViewScrollContent method to automatically create a vertical scrolling row of several iOSViews and create a scrollable UI.
Inspector Properties
Inspector behavior properties of iOSLibScrollView
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 xojo.core.point: The point at which the origin of the content view is offset from the origin of the scroll view.
ContentSize As xojo.core.size / 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.
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 (X as Double, y as double): Animates the contentOffset change.
CreateContentView (Width as double, Height as Double): Creates a new contentview and assigns it to the property of the scrollview.
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.
EmbedControl (c as iOSControl, opt. x as double, opt. y as double, opt. width as Double, opt. height as Double): Assigns a control as a subview to the ContentView property, with optional position or frame. Will crash if there is no ContentView attached to the scrollView.
EmbedControlFixed (c as iOSControl, opt. x as double, opt. y as double, opt. width as Double, opt. height as Double): The same as above, but in this case assigns a new AutoResizingMask to the property with a value of 0, which mens the embedded control will not resize during orientation or its content changes.
FlashScrollIndicators(): Makes the scrollbars show shortly.
ScrollContent (value as iOSControl / iOSImage / iOSView) (write-only): makes the respective object the current ContentView
SetContentInset (Top, Left, bottom, right as double): Sets the distance of the content to the outer borders. AppleScrollViewer convenience method for contentInset.
ScrollToRect (Rect As NSRect / X, Y, W, H As Double (AppleScrollViewer): Animates the visible content to the defined rect if within the zoom parameters.
SetContentInset (Left As Double, Top as Double, opt. animated as boolean = true: Sets the distance that the contentview is inset from is enclosing scroll view.
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.
SetMultiViewScreenContent (ParamArray Value() As iOSView): Takes several iOSViews, puts them together to one vertical scrolling view and assigns it to the contentview. Sets paging, therefore ideal for creating a UI that spans several pages vertically.
SetScrollIndictaorInsets (Left As Double, Top as Double, Bottom as Double, Right as Double): Sets the scroll indicator insets.
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:
Decelerated(): The contentview has stopped its scrolling motion.
DecelerateStarted(): The user has moved his finger from the view and the scrollview will start scrolling unti it comes to rest.
DoubleTap() As Boolean: User has doubletapped on the view. Return True to cancel zooming in.
DragEnded (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.
DragStarted(): The scroll view is about to start scrolling its content.
DoubleTap() As Boolean: The user doubletapped the view. Return True if you do not want the view to zoom in.
Scrolled(): The user has scrolled the content.
ScrolledToTop(): Fires when the view was moved to top by a double-tap on the status bar.
ScrollingAnimationEnded(): The content scrolling animation finished.
TwoFingerTap() As Boolean: The user made a two-finger-tap on the view. Return true if you do not want to zoom out.
UserDragEnded (Velocity As xojo.core.point, TargetContentOffset As 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.
ZoomEnded(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.
ZoomFactorChanged(): The scrollview's zoomfactor changed.
ZoomStarted (View As AppleView): The scrollview is about to zoom. View is simply its contentView.
WillScrollToTop is not implemented because you can rely on the ScrollsToTop Property. If you need this event, please let me know.