ScrollViewer
Last updated
Last updated
The ScrollViewer control is a general-purpose control which can be used to display a scrollable area. The ScrollViewer exposes a control called InnerPanel which is the host for all content within the ScrollViewer. The InnerPanel is a Gum GraphialUiElement so its sizing and positioning rules are flexible and can be modified either in code or Gum.
The ScrollViewer control requires:
An object named VerticalScrollBarInstance which implements ScrollBarBehavior (is a ScrollBar)
An object named InnerPanelInstance of any type (typically a Container)
An object named ClipContainerInstance of any type (typically a Container with ClipsChildren set to true)
The clip container is a container which will hold the InnerPanelInstance. The hierarchy of controls should be:
ScrollViewerComponent
VerticalScrollBarInstance
ClipContainerInstance
InnerPanelInstance
Contents of the ScrollViewer - added at runtime through code
This hierarchy allows each control to serve a separate function. The clip container's purpose is to clip the drawing of all contained objects. The clip container prevents the inner panel (and all controls within the inner panel) from overlapping the vertical scroll bar and from spilling out of the scroll viewer. The clip container should be of standard type Container because this control is typically used for clipping children. The clip container should have its ClipsChildren variable set to true. For information on this property, see the Gum documentation on ClipsChildren: http://vchelaru.github.io/Gum/generalproperties/Clips%20Children.html The clip container will typically fill the most of the scroll viewer component, leaving room for the vertical scroll bar and any desired border. This can be accomplished by setting WidthUnits and HeightUnits to RelativeToContainer.
ScrollViewer instances support hiding or showing the VerticalScrollBarInstance. This can impact the horizontal size of the ClipContainerInstance. In the case of a hidden VerticalScrollBarInstance, the ClipContainerInstance should extend to occupy space that would otherwise be used by the VerticalScrollBarInstance. To respond to the VerticalScrollBarInstance being hidden and shown, the ScrollViewer Gum object should have a state category titled ScrollBarVisibility with two states:
NoScrollBar
VerticalScrollVisible
These two states should adjust the visibility of the VerticalScrollBarInstance and the width of the ClipContainerInstance as shown in the following diagram:
Keep in mind that this category applies to any control which inherits from ScrollBar, such as ListBox. Also, these values should not be directly assigned in code, but rather are controlled through the ScrollBar's VerticalScrollBarVisibility property (see below).
The inner panel is used to provide the following behavior:
Scrolls all contents in response to the vertical scroll bar events
Provides size information to the vertical scroll bar to resize the thumb (see more information below)
Provides a common parent to all custom content for scrolling
Currently the ScrollViewer control only supports vertical scrolling, so the inner panel should be configured to grow and shrink only on the Y axis. This can be accomplished by setting the following values on the InnerPanelInstance:
X = 0
X Units = PixelsFromLeft
Y = 0
Y Units = PixelsFromTop
Width = 0
Width Units = RelativeToContainer (makes the panel stretch horizontally to the width of the ClipContainerInstance)
Height = 0
Height Units = RelativeToChildren (makes the panel initially have no height, but makes it stretch vertically according to its contents)
Setting HeightUnits to RelativeToChildren results in the inner panel enables automatic resizing according to the inner panel's children (which are added at runtime).
As additional controls are added to inner panel, it will expand vertically. Controls which fall outside of the clip container will not be rendered. The following diagram shows this, but has controls outside of the clip container dimmed for illustrative purposes:
The inner panel can be used to hold controls which are positioned in absolute pixel values or which are automatically stacked (such as a list box). If the controls within the inner panel are to be positioned in absolute terms, the Children Layout value should be set to Regular. If the controls within the inner panel are to be stacked automatically, the inner panel Children Layout value should be set to TopToBottomStack.
The VerticalScrollBarVisibility property controls the behavior of the scrollbar in response to the number of items in the ScrollViewer. The three available values are:
Auto - the vertical scrollbar will display only if the ScrollViewer requires scrolling to display all items. This is the default functionality
Hidden - the vertical scrollbar will never show, but the ScrollViewer still supports scrolling with the mouse wheel or swiping on the touchscreen
Visibile - the vertical scrollbar will always display
When working with a ScrollViewer we need to consider two sizes:
Width and Height of the ScrollViewer itself, which can be explicitly in code or which can be set on the Gum runtime object in the Gum tool
The InnerPanel width and height, which also can be explicitly set in code or which can be set on the Gum runtime object in the Gum tool
The following code shows how a manually sized Sc