tutorials/www/scroll-bars.xml - pivot - Git at Google

 <?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>
	<?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>