How to use the Feathers
ScrollContainer class provides a generic container for display object layout and scrolling a view port. By default, you can position components manually, but you can also pass in a layout to position the children automatically. Scrolling is vertical or horizontal, and is enabled when the width or height of the content exceeds the width or height of the container. You can also disable scrolling completely, if desired.
First, let's create a
ScrollContainer component and add it to the display list:
ScrollContainer works a lot like any
DisplayObjectContainer, so you can use the standard
removeChild() and other display list manipulation functions.
The children of a
ScrollContainer do not need to be Feathers UI controls. As you can see above, we've added some Starling
By default, the
ScrollContainer will automatically resize itself to fit the area that the children occupy. We can set the width and height manually, if desired, to override this behavior:
We manually positioned the quads in the example code above. Instead, let's pass a
HorizontalLayout to the
layout property of the
ScrollContainer. This layout will calculate the positioning of children for us automatically:
Here, we've set the
gap property, but
HorizontalLayout provides many more useful features. See How to use
HorizontalLayout with Feathers containers for complete details.
The skins for a
ScrollContainer control are mainly the background skins and some basic styles, and the scroll bars may be skinned too. For full details about what skin and style properties are available, see the
ScrollContainer API reference. We'll look at a few of the most common ways of styling a scroll container below.
We can give the
ScrollContainer a background skin that stretches to fill the entire width and height of the scroll container. In the following example, we pass in a
starling.display.Image, but the skin may be any Starling display object:
It's as simple as setting the
We can give the
ScrollContainer a different background when it is disabled:
backgroundDisabledSkin is displayed when the scroll container is disabled. If the
backgroundDisabledSkin isn't provided to a disabled scroll container, it will fall back to using the
backgroundSkin in the disabled state.
Padding may be added around the edges of the container's content. This padding is different than any type of padding that may be provided by the layout. The layout padding is applied inside the container's content, but the container's padding is applied outside of the content, and is generally used to show a bit of the background as a border around the content.
If all four padding values should be the same, you may use the
padding property to quickly set them all at once:
Skinning the Scroll Bars
This section only explains how to access the horizontal scroll bar and vertical scroll bar sub-components. Please read How to use the Feathers
ScrollBar component (or
SimpleScrollBar) for full details about the skinning properties that are available on scroll bar components.
With a Theme
If you're creating a theme, you can target the
Scroller.DEFAULT_CHILD_STYLE_NAME_HORIZONTAL_SCROLL_BAR style name for the horizontal scroll bar and the
Scroller.DEFAULT_CHILD_STYLE_NAME_VERTICAL_SCROLL_BAR style name for the vertical scroll bar.
getStyleProviderForClass( ScrollBar ) .setFunctionForStyleName( Scroller.DEFAULT_CHILD_STYLE_NAME_HORIZONTAL_SCROLL_BAR, setHorizontalScrollBarStyles ); getStyleProviderForClass( ScrollBar ) .setFunctionForStyleName( Scroller.DEFAULT_CHILD_STYLE_NAME_VERTICAL_SCROLL_BAR, setVerticalScrollBarStyles );
The styling function for the horizontal scroll bar might look like this:
You can override the default style names to use different ones in your theme, if you prefer:
You can set the function for the
customHorizontalScrollBarStyleName and the
customVerticalScrollBarStyleName like this:
Without a Theme
If you are not using a theme, you can use
verticalScrollBarFactory to provide skins for the container's scroll bars:
Customize scrolling behavior
A number of properties are available to customize scrolling behavior and the scroll bars.
Scrolling containers provide two main interaction modes, which can be changed using the
By default, you can scroll using touch, just like you would on many mobile devices including smartphones and tablets. This mode allows you to grab the container anywhere within its bounds and drag it around to scroll. This mode is defined by the constant,
Alternatively, you can set
ScrollInteractionMode.MOUSE. This mode allows you to scroll using the horizontal or vertical scroll bar sub-components. You can also use the mouse wheel to scroll vertically.
Finally, you can set
ScrollInteractionMode.TOUCH_AND_SCROLL_BARS. This mode allows you to scroll both by dragging the container's content and by using the scroll bars.
Scroll Bar Display Mode
scrollBarDisplayMode property controls how and when scroll bars are displayed. This value may be overridden by the scroll policy, as explained below.
The default value is
ScrollBarDisplayMode.FLOAT, which displays the scroll bars as an overlay above the view port's content, rather than affecting the size of the view port. When the scroll bars are floating, they fade out when the container is not actively scrolling. This is a familiar behavior for scroll bars in the touch interaction mode. In the mouse interaction mode, the scroll bars will appear when the mouse hovers over them and then disappear when the hover ends.
To completely hide the scroll bars, but still allow scrolling, you can set
If you want the scroll bars to always be visible outside of the content in a fixed position, you can set
ScrollBarDisplayMode.FIXED. This is best for traditional desktop scrollable content.
Finally, you can set
ScrollBarDisplayMode.FIXED_FLOAT to display the scroll bar as an overlay above the view port's content, but it does not fade away.
The two previous properties control how scrolling works. The
verticalScrollPolicy properties control whether scrolling is enabled or not.
The default scroll policy for both directions is
ScrollPolicy.AUTO. If the content's width is greater than the view port's width, the scroll container may scroll horizontally (same for height and vertical scrolling). If not, then the scroll container will not scroll in that direction. In addition to the
scrollBarDisplayMode, this can affect whether the scroll bar is visible or not.
You can completely disable scrolling in either direction, set the scroll policy to
ScrollPolicy.OFF. The scroll bar will not be visible, and the scroll container won't scroll, even if the content is larger than the view port.
Finally, you can ensure that scrolling is always enabled by setting the scroll policy to
ScrollPolicy.ON. If combined with
hasElasticEdges in the touch interaction mode, it will create a playful edge that always bounces back, even when the content is smaller than the view port. If using the mouse interaction mode, the scroll bar may always be visible under the same circumstances, though it may be disabled if the content is smaller than the view port.
snapToPages property to true to make the scroll position snap to the nearest full page. A page is defined as a multiple of the view ports width or height. If the view port is 100 pixels wide, then the first horizontal page starts at 0 pixels, the second at 100, and the third at 200.
pageHeight properties may be used to customize the size of a page. Rather than using the full view port width or height, any pixel value may be specified for page snapping.
Many developers try to use
ScrollContainer any time that they need to scroll some content. This will work for a small set of children, but especially on mobile, there are limits to what
ScrollContainer can handle. If your layout contains many children that basically look the same, and maybe you're referring to them as "cells" or "items", then
ScrollContainer is probably not the correct component for this type of UI. Instead, you should probably use the
List is much better at supporting layouts with dozens or hundreds of items, and its item renderers can be customized to completely change their appearance. If you need grouping with headers or footers,
GroupedList might be a better choice.