Fast Scroll
===========

+----------+---------------------------------+
| Author   | Renato Araujo Oliveira Filho    |
+----------+-------------+-------------------+
| License  | BSD License                     |
+----------+---------------------------------+
| Contact  | renato.filho@canonical.com      |
+----------+---------------------------------+
| Framework| ubuntu-sdk-14.10                |
+----------+---------------------------------+

This widget provides a quick way to navigate long list views by providing
a fast scroll. Example use cases are scrolling through an address book with
a long list of contacts. It shows all the characters from A-Z but only the
ones shown in the listview are differentiated with a bold font. The currently
selected section is highlighted with a black rectangle. As the user scrolls
the listview, the selected section rectangle also scrolls automatically with
an animation.

.. note:: At the moment, fast scroll only accepts listviews to be ordered alphabets and does not work well with special characters.

Example:

.. code-block:: qml

    Page {
        id: fastscrollpage
    
        ListModel {
            id: testModel
            ListElement { title: "Alan Pope" }
            ListElement { title: "Aditya Urs" }
            ListElement { title: "Akiva Shammai Avraham" }
            ListElement { title: "Andrew Hayzen" }
            ListElement { title: "Carla Sella" }
            ListElement { title: "Daniel Holm" }
            ListElement { title: "Daniel Holbhach" }
            ListElement { title: "David Planella" }
            ListElement { title: "Lento Manickathan" }
            ListElement { title: "Leo Arias" }
            ListElement { title: "Michael Hall" }
            ListElement { title: "Michael Zanetti" }
            ListElement { title: "Mihir Soni" }
            ListElement { title: "Michael Spencer" }
            ListElement { title: "Nicholas Skaggs" }
            ListElement { title: "Nekhelesh Ramanthan" }
            ListElement { title: "Oliver Gravert" }
            ListElement { title: "Jenkins" }
            ListElement { title: "Kunal Parmar" }
            ListElement { title: "Riccardo Padovani" }
            ListElement { title: "Robert Schroll" }
            ListElement { title: "Victor Thompson" }
        }

        ListView {
            id: nameListView
            anchors.fill: parent
            anchors.rightMargin: fastScroll.showing ? fastScroll.width - units.gu(1)
                                                    : 0
            clip: true
            currentIndex: -1
            model: testModel

            function getSectionText(index) {
                return testModel.get(index).title.substring(0,1)
            }

            delegate: ListItem.Standard {
                text: title
            }
        }

        FastScroll {
            id: fastScroll
            listView: nameListView
            anchors {
                top: nameListView.top
                bottom: nameListView.bottom
                right: parent.right
            }
        }
    }
    
.. image:: ../_images/fastscroll.png
   :align: center

Properties
----------

- :ref:`listview`: listview
- :ref:`showing`: bool
- :ref:`enabled`: bool

Methods
-------

- :ref:`getSectionText(index)`

Property Documentation
----------------------

.. _listview:

listview
^^^^^^^^

The listview which requires the fastscroll component

.. _showing:

showing (readonly)
^^^^^^^^^^^^^^^^^^

Readonly property to return the visiblity status of the fast scroll component. The 
fast scroll is automatically hidden after few seconds. This property will help with
defining behaviour based on the visiblity of the component.

.. _enabled:

enabled
^^^^^^^

This property can be used to enable/disable the fastscroll. For instance when the listview
has too few elements, it might be better to disable the fastscroll.

Here is a code sample that disables the fastscroll when the listview has too few elements, ::

    enabled: (listview.contentHeight > (listview.height * 2)) && (listview.height >= minimumHeight)
    
Method Documentation
--------------------

.. _getSectionText(index):

function getSectionText(index)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This function returns the available section headers of a listview to the fast scroll and is required
for the fastscroll to know which indexes to highlight. See the example above to get a better idea of
how to use this.