Fast Scroll

The fast scroll component shows a shortcut list that is bound to its parent scroll bar and list view.

The fast scroll component jumps the scroll view to the selected list divider. If you move the mouse over the shortcut column, the scroll view is moved to the list divider matching the text currently under the mouse cursor. A pop-up containing the text is also displayed.

To use the fast scroll component, add the data-fastscroll="true" attribute to a list view.

Table of Contents

1. Default Selectors
2. Manual Constructor
3. Options
4. Events
5. Methods

Default Selectors

By default, all list view elements (data-role="listview") with the data-fastscroll="true" attribute are displayed as fast scroll components.

Manual Constructor

To manually create a fast scroll component, use the component constructor from the tau namespace (RECOMMENDED):

<div data-role="page" id="main">
   <div data-role="content">
      <ul id="list" data-role="listview" data-fastscroll="true">
         <li data-role="list-divider">A</li>
         <li>Anton</li>
         <li>Arabella</li>
         <li data-role="list-divider">B</li>
         <li>Barry</li>
         <li>Bily</li>
      </ul>
   </div>
</div>
<script>
   var fastscroll = tau.widget.FastScroll(document.getElementById("list"));
</script>

If the jQuery library is loaded, you can use its method (support for backward compatibility):

<div data-role="page" id="main">
   <div data-role="content">
      <ul id="list" data-role="listview" data-fastscroll="true">
         <li data-role="list-divider">A</li>
         <li>Anton</li>
         <li>Arabella</li>
         <li data-role="list-divider">B</li>
         <li>Barry</li>
         <li>Bily</li>
      </ul>
   </div>
</div>
<script>
   var fastscroll = $("#list").fastscroll();
</script>

Options

The following table lists the options for the fast scroll component.

Events

The following table lists the events related to the fast scroll component.

Methods

To call a method on the component, use the TAU API:

<div data-role="page" id="main">
   <div data-role="content">
      <ul id="contacts" data-role="listview" data-fastscroll="true">
         <li data-role="list-divider">A</li>
         <li>Anton</li>
         <li>Arabella</li>
         <li data-role="list-divider">B</li>
         <li>Barry</li>
         <li>Bily</li>
      </ul>
   </div>
</div>
<script>
   var element = document.getElementById("contacts"),
       contacts = tau.widget.FastScroll(element, {fastscroll: true});
   contacts.methodName(methodArgument1, methodArgument2, ...);
</script>

Summary

destroy() 

string indexString(string? indexAlphabet) 

refresh() 

destroy

Destroys the component.

destroy()

Since: 2.0

This method destroys the current fast scroll component.

Return value:

No return value

Code example (TAU API RECOMMENDED):

<div data-role="page" id="main">
   <div data-role="content">
      <ul id="list" data-role="listview" data-fastscroll="true">
         <li data-role="list-divider">A</li>
         <li>Anton</li>
         <li>Arabella</li>
         <li data-role="list-divider">B</li>
         <li>Barry</li>
         <li>Bily</li>
      </ul>
   </div>
</div>
<script>
   var element = document.getElementById("list"),
       fastscroll = tau.widget.FastScroll(element);
   fastscroll.destroy();
</script>

Code example (jQuery API support for backward compatibility):

<div data-role="page" id="main">
   <div data-role="content">
      <ul data-role="listview" data-fastscroll="true" id="fastscroll">
         <li data-role="list-divider">A</li>
         <li>Anton</li>
         <li>Arabella</li>
         <li data-role="list-divider">B</li>
         <li>Barry</li>
         <li>Bily</li>
      </ul>
   </div>
</div>
<script>
   $("#list").fastscroll("destroy");
</script>

indexString

Gets or sets an index string.

?string indexString(string? indexAlphabet) 

Since: 2.1

This method manages the values to be used in the shortcut items.

Parameters:

Parameter	Type	Required/optional	Default value	Description
indexAlphabet	string	Optional		Values to be used in the shortcut items.

Return value:

Type	Description
?string	Primary and secondary languages.

Code example (TAU API RECOMMENDED):

<div data-role="page" id="main">
   <div data-role="content">
      <ul id="fastscroll" data-role="listview" data-fastscroll="true">
         <li data-role="list-divider">A</li>
         <li>Anton</li>
         <li>Arabella</li>
         <li data-role="list-divider">B</li>
         <li>Barry</li>
         <li>Bily</li>
      </ul>
   </div>
</div>
<script>
   /* Get index string */
   var element = document.getElementById("fastscroll"),
       fastscroll = tau.widget.FastScroll(element, {fastscroll: true});
   fastscroll.indexString();

   /* Set index string */
   fastscroll.indexString("A,D,J,P,W,Z");
</script>

Code example (jQuery API support for backward compatibility):

<div data-role="page" id="main">
   <div data-role="content">
      <ul data-role="listview" data-fastscroll="true" id="fastscroll">
         <li data-role="list-divider">A</li>
         <li>Anton</li>
         <li>Arabella</li>
         <li data-role="list-divider">B</li>
         <li>Barry</li>
         <li>Bily</li>
      </ul>
   </div>
</div>
<script>
   $("#fastscroll").fastscroll("indexString", "A,D,J,P,W,Z");
</script>

refresh

Refreshes the component.

refresh() 

Since: 2.0

The method updates and redraws the current fast scroll component.

Return value:

No return value

Code example (TAU API RECOMMENDED):

<div data-role="page" id="main">
   <div data-role="content">
      <ul id="list" data-role="listview" data-fastscroll="true">
         <li data-role="list-divider">A</li>
         <li>Anton</li>
         <li>Arabella</li>
         <li data-role="list-divider">B</li>
         <li>Barry</li>
         <li>Bily</li>
      </ul>
   </div>
</div>
<script>
   var element = document.getElementById("list"),
       fastscroll = tau.widget.FastScroll(element);

   element.insertAdjacentHTML("beforeend", "<li>Bruce</li>");
   fastscroll.refresh();
</script>

Code example (jQuery API support for backward compatibility):

<div data-role="page" id="main">
   <div data-role="content">
      <ul data-role="listview" data-fastscroll="true" id="fastscroll">
         <li data-role="list-divider">A</li>
         <li>Anton</li>
         <li>Arabella</li>
         <li data-role="list-divider">B</li>
         <li>Barry</li>
         <li>Bily</li>
      </ul>
   </div>
</div>
<script>
   $("#fastscroll").append("<li>Bruno</li>");
   $("#fastscroll").fastscroll("refresh");
</script>