Scroll views - HackMD

--- title: Scroll views tags: uikit --- # Scroll views A `UIScrollView` is a view that has two frames: * Its own, (usually smaller) external frame. * Its content, (usually larger) internal frame. `UIScrollView` acts as a "window" to its content -- at one point it only displays a part of the content. If the content is smaller than the `UIScrollView`, it will display the whole content at once and no additional behavior will be provided. However, if the content is larger in at least one axis, the `UIScrollView` will become scrollable. [TODO some (animated?) image goes here] Scrolling can be done via using a mouse scroll wheel (if using a mouse input device), via a [pan gesture](https://hackmd.io/@Shockah/rkwL75ffc) or via a pan gesture on a `UIScrollBarView` attached to the `UIScrollView`. :::warning The pan gesture is not yet implemented. The `UIScrollBarView` is not yet implemented. ::: The external frame can be referenced via the standard `UIView` anchors. The content frame can be referenced via the `ContentFrame` property, and includes the same anchors that can be found on `UIView`s. `UIScrollView` is a subclass of [`UISurfaceView`](https://hackmd.io/@Shockah/B16IO7Gz5) -- anything that applies to `UISurfaceView` also applies here. # Constraining to achieve scrollable content It is recommended to only have one content view directly inside a `UIScrollView`, and any other views being subviews of that view. To make some content scrollable, you should do the following: * Add your content views to the `UIScrollView`. * Constrain your content to the `UIScrollView`'s `ContentFrame`. * If you want to restrict horizontal scrolling (only allow vertical scrolling, fill the `UIScrollView` horizontally), constrain your content to the `UIScrollView`'s `LeftAnchor` and `RightAnchor`. * If you want to restrict vertical scrolling (only allow horizontal scrolling, fill the `UIScrollView` vertically), constrain your content to the `UIScrollView`'s `TopAnchor` and `BottomAnchor`. For example, to create a content view scrollable vertically, you would need the following constraints: * `Content.Top == ScrollView.Content.Top` * `Content.Bottom == ScrollView.Content.Bottom` * `Content.Left == ScrollView.Content.Left` * `Content.Right == ScrollView.Content.Right` * `Content.Left == ScrollView.Left` * `Content.Right == ScrollView.Right` # Accessing scroll state The `UIVector2 ContentSize` property can be used to retrieve the current size of the `UIScrollView`'s content. The `UIVector2 ContentOffset` property can be used to retrieve and modify the current scroll position. Additionally, the `ContentSizeChanged(UIScrollView, UIVector2, UIVector2)` and `ContentOffsetChanged(UIScrollView, UIVector2, UIVector2)` events can be used to be notified whenever these values change. # Controlling scrolling behavior The `bool AllowsVerticalScrolling` and `bool AllowsHorizontalScrolling` properties allow controlling whether scrolling interaction for the respective axes is enabled. The content still has to be large enough to allow scrolling. The `ContentOffset` property can still be used to change the current scroll position, even if scrolling is disabled. The `bool ReverseVerticalDirection` and `bool ReverseHorizontalDirection` properties allow reversing the scroll direction when using the mouse scroll wheel. The `UIVector2 ScrollFactor` allows modifying how much the scroll position is offset when using the mouse scroll wheel. # Infinite scrolling The `bool ClampsVerticalContentOffset` and `bool ClampsHorizontalContentOffset` properties can be set to `false` to allow infinitely scrolling in their respective axes.