Author: Jan Rojcek
1. Introduction
This document is the user experience specification for the JavaFX Scroll View control.
2. Scroll View Overview
A Scroll View control permits the user view content that is bigger than the scroll view itself. The content inside Scroll View can be any other control or a set of controls like list, tree, table, text, picture, formatted text, etc. The user controls which part of content is visible through Scroll View by scrolling it vertically or horizontally.
Figure 1 Various appearances of Scroll View
3. Desktop
Scroll View on desktop platform contains vertical and horizontal scroll bars that appear automatically when content size is bigger than the available scroll view size. Each scroll bar contains scroll arrows, scroll channel and scroll slider.
Figure 2 Scroll view components
3.1 Detailed Behaviors
Scroll bar
Scroll bar permits the user control the visible portion of content using a pointer. It also provides the user with visual indication about the overall size of content and which portion of content (top, left, middle, bottom, right) is visible through scroll view.
See below for detailed behavior defined for scroll arrow, slider and channel.
| State | Description |
| Visible | Scroll bar is visible automatically when content is scrolling and at the sam time content is bigger than the scroll view in corresponding direction (horizontal or vertical). |
| Hidden | Scroll bar is hidden automatically when content stops scrolling. It is also hidden if content size is smaller or equal to scroll view size in the corresponding direction. |
Scroll arrow
Scroll arrow scrolls content by a single row or column. The height of row, or width of column is set according to the content type either automatically or programmatically. Typically for text documents, the row height equals line height. For tables, it equals a table row height. For list of pictures, it may be an average size of a picture, etc.
| Pointer Gesture | Behavior |
| Left Button Press | Moves content one row up or down, or column left or right. |
| Left Button Press and Hold | Repeatedly moves content one row or column. The repeat rate is 300ms. |
| Left Button Press and Leave (and Reenter) | When the pointer leaves the scroll arrow while the button is pressed, it stops scrolling. When it enters the arrow again while still pressed, it starts scrolling. |
| Alt Key + Left Button Press | Scrolls content one page. The default page size equals visible content width/height minus one column/row. |
| If any other modifier key is pressed in conjunction with the left or right mouse button click, the behavior will be the same as no modifier key being pressed. | |
Scroll channel
Scroll channel scrolls content by a single page. The default page size is defined as height or width of visible content minus one row or column.
| Pointer Gesture | Behavior |
| Left Button Press | Scrolls content one page up or down. |
| Left Button Press and Hold | Repeatedly scrolls content one page until the slider overlaps the pointer position. The repeat rate is 300ms. |
| Left Button Press and Leave (and Reenter) | When the pointer leaves the scroll channel while the button is pressed, it stops scrolling. When it enters the channel again while still pressed, it starts scrolling. |
| Alt Key + Left Button Press | Moves slider to the pointer position. The slider midpoint matches the pointer position. Scrolls content accordingly. |
| If any other modifier key is pressed in conjunction with the left or right mouse button click, the behavior will be the same as no modifier key being pressed. | |
Scroll slider
Scroll slider permits the user scroll content to any section as it is controlled by a pointer drag gesture.
Its size is a function of content size. The bigger the content, the smaller the slider. The minimum size is TBD.
Its position inside the scroll channel is computed from the relative position of visible content within the full content.
| Pointer Gesture | Behavior |
| Drag | Moves the slider and content following the pointer dragging position. When the slider moves 1 pixel, the content moves 1 or more pixels depending on the slider position calculation. Dragging continues even if the pointer leaves the slider box. It stops only when the user stops the drag gesture. |
Content
Size of content defines behavior of scroll bars in scroll view. If a content width is smaller than a scroll view width, the horizontal scroll bar is hidden. If it is bigger, the scroll bar is visible. It works likewise for the vertical scroll bar.
Figure 3 Hidden horizontal or vertical scroll bar
Scroll view can also work in a mode when content width or height is fixed to the available width or height of scroll view. This is typically used for textual documents or lists when bidirectional scrolling is undesirable.
In Fit Width mode, textual documents or any other content have the same width as the available scroll view width. The text inside the document wraps at the width limit. The vertical scroll bar then appears when needed. The horizontal scroll bar never appears.
Figure 4 Content fits the scroll view width
In Fit Height mode, horizontal list’s (or any other content’s) height is fixed to the available height of scroll view. Horizontal scroll bar appears as needed.
Figure 5 Content fits the scroll view height
Common
Scroll wheel or any other pointer device's direct scroll gestures work with scroll view when the pointer is above scroll view.
| Pointer Gesture | Behavior |
| Scroll wheel | Scrolls the content continuously with the scroll wheel. The slider moves accordingly following the slider position calculation. It is possible that if content moves a few pixels only, the slider does not move at all. |
States
| State | Description |
| Normal/Enabled | Scroll view is ready for user interaction. It can get keyboard focus or the user can interact with it using pointing device. |
| Disabled | Scroll view is disabled for user interaction. The user cannot scroll it using pointing device and it cannot get keyboard focus. |
| Focused | Scroll view has keyboard focus and receives keyboard events. It can be focused only if the scroll view content as such is not focusable (e.g. an image). |
| Transparently Focused | Content inside scroll view has keyboard focus. Scroll view receives only those events that are not consumed by the content. |
3.2 Keyboard Support
Scroll view receives keyboard focus only if no control inside the scroll view content is focusable. In that case all key events are managed by the scroll view. An example of such case is a picture inside a scroll view.
If any control inside scroll view is focusable, it gets focus instead of the scroll view which becomes transparent to keyboard focus. The scroll view then receives only those key events that are not consumed by the focused control, or those events that are consumed and in addition also propagated to scroll view. An example of such case is a vertical list inside a scroll view. It manages key events by moving selected item up and down. When the selection reaches the scroll view border, it moves the selection and at the same time scrolls the list.
If keyboard focus is inside a scroll view and it moves to a scrolled out control (e.g. after pressing the Tab key), the scroll view automatically scroll the content to make the focused control visible.
| Key | Behavior |
| Page Up/Down | Scrolls the content one page up or down. One page size equals the height of visible content minus one row height. |
| Up/Down/Left/Right | Scrolls the content one row up or down, or column left or right. Row and column size is defined by the content type. |
| Spacebar | Scrolls the content one page down. One page size equals the height of visible content minus one row height. |
| Home | Scrolls the content to the top. |
| End | Scrolls the content to the bottom. |
| Tab (or other focus traversal event) | If a scrolled-out control inside scroll view receives focus, it scrolls to make the newly focused control visible. |
3.3 Desktop - Attributes
| Attribute name | Description | Values |
| Row height | Defines scrolling steps up and down. Used by scroll arrows. Default: 20 pixels (or determined by content). | Number of pixels |
| Column width | Defines scrolling steps left and right. Used by scroll arrows. Default: 20 pixels (or determined by content). | Number of pixels |
| Page height | Defines scrolling page step up and down. Used when clicked into the scroll channel. Default: "visible content height minus one row height" | Number of pixels |
| Page width | Defines scrolling page step left and right. Used when clicked into the scroll channel. Default: "visible content width minus one column width" | Number of pixels |
| Fit width | Defines whether the content width should match the available width of scroll view. It is exclusive with Fit height. Default: false. | True or False |
| Fit height | Defines whether the content height should match the available height of scroll view. It is exclusive with Fit width. Default: false. | True or False |
4. Touch
Scroll View on a touch platform performs scrolling as a result of touch gestures targeted on scroll view content. Simplified scroll bars appear solely as content size and position indicators. They are not active controls used for scrolling the content.
Figure 6 Scroll View components on Touch platform
4.1 Detailed Behaviors
Scroll bars
Scroll bars are hidden when the user does not interact with scroll view even if the content is bigger than the scroll view. They appear automatically after touch gestures, but only as an indicator of content size and position, not as an active control the user uses for scrolling. When scroll bars appear, they overlap visible content and do not shift it like on desktop platform. They disappear automatically when content stops scrolling.
| State | Description |
| Visible | Scroll bar is visible automatically when content is scrolling and at the sam time content is bigger than the scroll view in corresponding direction (horizontal or vertical). Automatic behavior can be suppressed by setting the show scroll bars attribute to "never". |
| Hidden | Scroll bar is hidden automatically when content stops scrolling. It is also hidden if content size is smaller or equal to scroll view size in the corresponding direction. |
Scroll slider
Scroll slider indicates the size and position of content. Its size is a function of content size - the bigger the content, the smaller the slider. The minimum slider size is TBD.
The position of slider is computed from the relative position of visible content within the full content.
Content
Size of content defines behavior of scroll bars in scroll view. If content width is smaller than scroll view width, the horizontal scroll bar is hidden. If it is bigger, the scroll bar becomes visible when the user starts dragging content. It works likewise for the vertical scroll bar.
Scroll view can also work in a mode when content width or height is fixed to the available width or height of scroll view. This is typically used for textual documents or lists when bidirectional scrolling is undesirable. In Fit Width mode, textual documents or any other content have the same width as the available scroll view width. The text inside the document wraps at the width limit. The vertical scroll bar then appears when needed. The horizontal scroll bar never appears. In Fit Height mode, horizontal list’s (or any other content’s) height is fixed to the available height of scroll view. Horizontal scroll bar appears as needed.
Common
Scroll view is controlled by touch gestures targeted on scroll view content. The applicable gestures are drag, drop, swipe and point.
When dragging, the content scrolls continuously with drag gesture. When the content border reaches the scroll view border and the user continues to drag in that direction, the content moves further uncovering the scroll view background. When the user drops the content, it automatically and smoothly returns to the border of the scroll view.
Figure 7 Dragging and "over-scrolling" the scroll view border
Swipe gesture invokes accelerated scrolling with initial speed defined by the intensity of swipe gesture. The content scrolls in the swipe direction with the scrolling speed continuously decreasing after it has been released by swipe gesture until the content stops scrolling. When the content has been released and it reaches the border of the scroll view, it stops scrolling. The user can also stop the scrolling content with point gesture targeted into any part of content.
If the user swipes content beyond the scroll view border, it automatically returns to the scroll view border after it has been released by swipe gesture.
Figure 8 Swiping and "over-scrolling" the scroll view border
Note that Touch devices can rotate. Because of this, sizes of ScrollView should adjust automatically based on the available mode (Landscape or Portrait).
| Touch gesture | Behavior |
| Drag | Scrolls the content continuously following the drag gesture. The content moves exactly the amount of pixels indicated by drag gesture in vertical and horizontal direction. The user can "over-scroll" the content by dragging it's edge beyond the scroll view border. The content moves the half number of pixels of the drag gesture. |
| Drop | When the user "over-scrolls" the content beyond the scroll view border, drop gesture releases the content and it smoothly returns to the border of the scroll view. In normal circumstances, drop gesture just stops scrolling. |
| Swipe | Invokes accelerated scrolling. The initial scrolling speed is defined by the swipe gesture intensity. It continuously slows down until it stops. |
| Point | Stops scrolling. |
States
| State | Description |
| Normal/Enabled | Scroll view is ready for user interaction. The user can interact with it using finger gestures. |
| Disabled | Scroll view is disabled for user interaction. The user cannot scroll it using finger gestures. |
4.2 Attributes
| Attribute name | Description | Values |
| Show scroll bars | Defines when to show scroll bars. Default: "When needed" | "When needed", "Never" |
| Fit width | Defines whether the content width should match the available width of scroll view. It is exclusive with Fit height. Default: false. | True or False |
| Fit height | Defines whether the content height should match the available height of scroll view. It is exclusive with Fit width. Default: false. | True or False |
5. 2D Traversal
Scroll View on a 2D traversal platform is controlled by navigation keys. Simplified scroll bars appear solely as content size and position indicators. They are not active controls used for scrolling the content.
Figure 9 Scroll View components on 2D Traversal platform
5.1 Detailed Behaviors
Scroll bars
Unlike on touch platform, scroll bars are always shown on 2D traversal platform when needed. They are visible when content is bigger than the available scroll view size and hidden otherwise. They are not active controls, they just indicate the content size and position.
| State | Description |
| Visible | Scroll bar is visible automatically when content is bigger than the available scroll view size. Automatic behavior can be suppressed by setting the show scroll bars attribute to "never". |
| Hidden | Scroll bar is hidden when content is smaller or equal to the available scroll view size. |
Scroll slider
Scroll slider indicates the size and position of content. Its size is a function of content size - the bigger the content, the smaller the slider. The minimum slider size is TBD.
The position of slider is computed from the relative position of visible content within the full content.
Content
Size of content defines behavior of scroll bars in scroll view. If a content width is smaller than a scroll view width, the horizontal scroll bar is hidden. If it is bigger, the scroll bar is visible. It works likewise for the vertical scroll bar.
Scroll view can also work in a mode when content width or height is fixed to the available width or height of scroll view. This is typically used for textual documents or lists when bidirectional scrolling is undesirable. In Fit Width mode, textual documents or any other content have the same width as the available scroll view width. The text inside the document wraps at the width limit. The vertical scroll bar then appears when needed. The horizontal scroll bar never appears. In Fit Height mode, horizontal list’s (or any other content’s) height is fixed to the available height of scroll view. Horizontal scroll bar appears as needed.
Common
Scroll view is controlled by navigation keys - up, down, left, right. Each key press scrolls content in corresponding direction by a single row or column. The height of row and width of column is set according to the content type either automatically or programmatically. Typically for text documents, the row height equals line height. For tables, it equals a table row height. For list of pictures, it may be an average size of a picture, etc.
States
| State | Description |
| Normal/Enabled | Scroll view is ready for user interaction. It can get keyboard focus. |
| Disabled | Scroll view is disabled for user interaction. It cannot get keyboard focus. |
| Focused | Scroll view has keyboard focus and receives keyboard events. It can be focused only if the scroll view content as such is not focusable (e.g. an image). |
| Transparently Focused | Content inside scroll view has keyboard focus. Scroll view receives only those events that are not consumed by the content. |
5.2 Keyboard Support
Scroll view receives keyboard focus only if no control inside the scroll view content is focusable. In that case all key events are managed by the scroll view. An example of such case is a picture inside a scroll view.
If any control inside the scroll view is focusable, it gets the focus instead of the scroll view which becomes transparent to keyboard focus. The scroll view then receives only those key events that are not consumed by the focused control, or those events that are consumed and in addition also propagated to scroll view. An example of such case is a vertical list inside a scroll view. It manages key events by moving selected item up and down. When the selection reaches the scroll view border, it moves the selection and at the same time scrolls the list.
In general, if keyboard focus is inside a scroll view and it moves to a scrolled out control (e.g. after pressing a nav key), the scroll view automatically scroll the content to make the focused control visible.
As there is no Tab key to move focus out of scroll view, the focus moves only with navigation keys. If the user presses a key in the direction where content cannot scroll, the focus moves out of scroll view following the standard focus traversal policy. This works well for one-directional scroll views (e.g. vertical or horizontal list). For bi-directional scroll views it is cumbersome, and as such it is recommended to use bi-directional scrolling only when the scroll view is the only component on the screen closed with the select key. For example a zoomed picture taking up the whole mobile device screen. It is up to the developer using scroll view to design user interface in a way that works well for the end user given this limitation.
| Key | Behavior |
| Up/Down/Left/Right | Scrolls the content one row up or down, or column left or right. Row and column size is defined by the content type. If the content is at the edge of scroll view in the direction of pressed key, it moves keyboard focus out of scroll view. |
5.3 2D Traversal - Attributes
| Attribute name | Description | Values |
| Show scroll bars | Defines when to show scroll bars. Default: "When needed" | "When needed", "Never" |
| Row height | Defines scrolling steps up and down. Default: 20 pixels (or determined by content). | Number of pixels |
| Column width | Defines scrolling steps left and right. Default: 20 pixels (or determined by content). | Number of pixels |
| Fit width | Defines whether the content width should match the available width of scroll view. It is exclusive with Fit height. Default: false. | True or False |
| Fit height | Defines whether the content height should match the available height of scroll view. It is exclusive with Fit width. Default: false. | True or False |
Overview
Content Tools
ThemeBuilder