<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements.  See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to you under the Apache License,
Version 2.0 (the "License"); you may not use this file except in
compliance with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

<document id="scroll-bars">
    <properties>
        <title>Scroll Bars</title>
        <explore>ScrollBar</explore>
    </properties>

    <body>
        <p>
            Like sliders, scroll bars allow the user to interactively select from a range of values.
            Unlike sliders, scroll bars are used to select a sub-range rather than an individual
            value. The size of this sub-range is known as the scroll bar's "extent". The extent,
            together with the start and end values of the outer range, comprise the scroll bar's
            "scope", represented by the <tt>ScrollBar.Scope</tt> enum.
        </p>

        <p>
            Visually, a scroll bar is usually presented as a scroll "handle" (sometimes called the
            "thumb") within a larger "track", with two buttons on either end of the track to move
            the handle. The track represents the outer range from which the user can select, and
            the size of the handle represents the scroll bar's extent.
        </p>

        <p>
            A scroll bar's value represents the start of the selected sub-range; its value plus its
            extent represents the end of the sub-range. Using the visual metaphor above, the start
            of the handle and the end of the handle represent the bounds of the selected sub-range.
            Note that this means that the scroll bar's value plus its extend must never exceed its
            scope; doing so would mean that the scroll bar's handle would have moved outside of the
            track.
        </p>

        <p>
            Finally, a scroll bar has a unit increment and a block increment. These values specify
            how much to adjust the scroll bar's value when a user clicks on the buttons or within
            the track, respectively.
        </p>

        <p>
            Scroll bars are used within <a href="scroll-panes.html">scroll panes</a> and are most
            often transparent to the application developer. However, they can be used directly just
            like any other components. The following application uses a scroll bar to represent a
            simple timeline.
        </p>

        <application class="org.apache.pivot.wtk.ScriptApplication" width="550" height="200">
            <libraries>
                <library>core</library>
                <library>wtk</library>
                <library>wtk-terra</library>
                <library>tutorials</library>
            </libraries>
            <startup-properties>
                <src>/org/apache/pivot/tutorials/boundedrange/scroll_bars.bxml</src>
            </startup-properties>
        </application>

        <p>
            The BXML source for this example is shown below:
        </p>

        <source type="xml" location="org/apache/pivot/tutorials/boundedrange/scroll_bars.bxml">
            <![CDATA[
            <Window title="Scroll Bars" maximized="true"
                WindowStateListener.windowOpened="init();"
                xmlns:bxml="http://pivot.apache.org/bxml"
                xmlns="org.apache.pivot.wtk">
                <bxml:script src="scroll_bars.js"/>

                <Border>
                    <TablePane>
                        <columns>
                            <TablePane.Column width="1*"/>
                        </columns>

                        <TablePane.Row>
                            <FlowPane styles="{padding:6}">
                                <bxml:define>
                                    <ButtonGroup bxml:id="ranges"
                                        ButtonGroupListener.selectionChanged="updateRange();"/>
                                </bxml:define>
                                <RadioButton bxml:id="dayButton"
                                    buttonGroup="$ranges" buttonData="Day"/>
                                <RadioButton bxml:id="weekButton"
                                    buttonGroup="$ranges" buttonData="Week"/>
                                <RadioButton bxml:id="fortnightButton"
                                    buttonGroup="$ranges" buttonData="Fortnight"/>
                                <RadioButton bxml:id="monthButton"
                                    buttonGroup="$ranges" buttonData="Month"/>
                            </FlowPane>
                        </TablePane.Row>
                        <TablePane.Row height="1*">
                            <BoxPane orientation="vertical" styles="{horizontalAlignment:'center',
                                verticalAlignment:'center'}">
                                <Label bxml:id="label"/>
                            </BoxPane>
                        </TablePane.Row>
                        <TablePane.Row>
                            <ScrollBar bxml:id="scrollBar" start="0" end="60"
                                ScrollBarListener.scopeChanged="updateLabel();"
                                ScrollBarValueListener.valueChanged="updateLabel();"/>
                        </TablePane.Row>
                    </TablePane>
                </Border>
            </Window>
            ]]>
        </source>

        <p>
            This example places the script code in an external JavaScript file,
            <tt>scroll_bars.js</tt> for readability. The source of the JavaScript is as follows:
        </p>

        <source type="js" location="org/apache/pivot/tutorials/boundedrange/scroll_bars.js">
            <![CDATA[
            /**
             * Called when the main app window is opened.
             */
            function init() {
                ranges.selection = weekButton;
            }

            /**
             * Updates the scroll bar's extent and block increment based on the selected
             * range (in the ranges button group).
             */
            function updateRange() {
                var amount;

                if (ranges.selection == dayButton) {
                    amount = 1;
                } else if (ranges.selection == weekButton) {
                    amount = 7;
                } else if (ranges.selection == fortnightButton) {
                    amount = 14;
                } else {
                    amount = 30;
                }

                scrollBar.extent = scrollBar.unitIncrement = amount;
                scrollBar.blockIncrement = 2 * amount;
            }

            /**
             * Updates the "timeline" label based on the scroll bar's value and extent.
             */
            function updateLabel() {
                var first = scrollBar.value + 1;
                var last = scrollBar.value + scrollBar.extent;
                label.setText("Days " + first + " through " + last);
            }
            ]]>
        </source>

        <p>
            Since this application is written entirely in BXML and script, there is no associated
            Java source.
        </p>
    </body>
</document>
