3 * jQuery Mobile Widget @VERSION
5 * This software is licensed under the MIT licence (as defined by the OSI at
6 * http://www.opensource.org/licenses/mit-license.php)
8 * ***************************************************************************
9 * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd.
10 * Copyright (c) 2011 by Intel Corporation Ltd.
12 * Permission is hereby granted, free of charge, to any person obtaining a
13 * copy of this software and associated documentation files (the "Software"),
14 * to deal in the Software without restriction, including without limitation
15 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
16 * and/or sell copies of the Software, and to permit persons to whom the
17 * Software is furnished to do so, subject to the following conditions:
19 * The above copyright notice and this permission notice shall be included in
20 * all copies or substantial portions of the Software.
22 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
23 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
24 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
25 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
26 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
27 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
28 * DEALINGS IN THE SOFTWARE.
29 * ***************************************************************************
31 * Authors: Elliot Smith <elliot.smith@intel.com>
32 * Yonghwi Park <yonghwi0324.park@samsung.com>
35 // fastscroll is a scrollview controller, which binds
36 // a scrollview to a a list of short cuts; the shortcuts are built
37 // from the text on dividers in the list. Clicking on a shortcut
38 // instantaneously jumps the scrollview to the selected list divider;
39 // mouse movements on the shortcut column move the scrollview to the
40 // list divider matching the text currently under the touch; a popup
41 // with the text currently under the touch is also displayed.
43 // To apply, add the attribute data-fastscroll="true" to a listview
44 // (a <ul> or <ol> element inside a page). Alternatively, call
45 // fastscroll() on an element.
47 // The closest element with class ui-scrollview-clip is used as the
48 // scrollview to be controlled.
50 // If a listview has no dividers or a single divider, the widget won't
55 The shortcut scroll widget shows a shortcut list that is bound to its parent scroll bar and respective list view. This widget is displayed as a text pop-up representing shortcuts to different list dividers in the list view. If you select a shortcut text from the shortcut scroll, the parent list view is moved to the location representing the selected shortcut.
57 To add a shortcut scroll widget to the application, use the following code:
59 <div class="content" data-role="content" data-scroll="y">
60 <ul id="contacts" data-role="listview" data-fastscroll="true">
65 For the shortcut scroll widget to be visible, the parent list view must have multiple list dividers.
69 @property {Boolean} data-fastscroll
70 When set to true, creates a shortcut scroll using the HTML unordered list (<ul>) element.
74 The shortcut scroll is created for the closest list view with the ui-scrollview-clip class.
78 The indexString method is used to get (if no value is defined) or set the string to present the index.
80 <div class="content" data-role="content" data-scroll="y">
81 ul id="contacts" data-role="listview" data-fastscroll="true">
82 <li data-role="list-divider">A</li>
87 $(".selector").fastscroll( "indexString" [, indexAlphabet] );
89 (function ( $, undefined ) {
91 $.widget( "tizen.fastscroll", $.mobile.widget, {
93 initSelector: ":jqmData(fastscroll)"
96 _primaryLanguage: null,
97 _secondLanguage: null,
100 _defaultDuration: 500,
104 _create: function () {
105 var $el = this.element,
108 page = $el.closest( ':jqmData(role="page")' ),
111 this.scrollview = $el.addClass( 'ui-fastscroll-target' ).closest( '.ui-scrollview-clip' );
112 this.shortcutsContainer = $( '<div class="ui-fastscroll" aria-label="Fast scroll bar, double tap to fast scroll mode" tabindex="0"/>' );
113 this.shortcutsList = $( '<ul aria-hidden="true"></ul>' );
115 // popup for the hovering character
116 this.scrollview.append($( '<div class="ui-fastscroll-popup"></div>' ) );
117 $popup = this.scrollview.find( '.ui-fastscroll-popup' );
119 this.shortcutsContainer.append( this.shortcutsList );
120 this.scrollview.append( this.shortcutsContainer );
122 // find the bottom of the last item in the listview
123 this.lastListItem = $el.children().last();
125 // remove scrollbars from scrollview
126 this.scrollview.find( '.ui-scrollbar' ).hide();
128 this.jumpToDivider = function ( divider ) {
129 // get the vertical position of the divider (so we can scroll to it)
130 var dividerY = $( divider ).position().top,
131 // find the bottom of the last list item
132 bottomOffset = self.lastListItem.outerHeight( true ) + self.lastListItem.position().top,
133 scrollviewHeight = self.scrollview.height(),
135 // check that after the candidate scroll, the bottom of the
136 // last item will still be at the bottom of the scroll view
137 // and not some way up the page
138 maxScroll = bottomOffset - scrollviewHeight,
141 dividerY = ( dividerY > maxScroll ? maxScroll : dividerY );
143 // don't apply a negative scroll, as this means the
144 // divider should already be visible
145 dividerY = Math.max( dividerY, 0 );
148 self.scrollview.scrollview( 'scrollTo', 0, -dividerY );
150 dstOffset = self.scrollview.offset();
154 // bind mouse over so it moves the scroller to the divider
155 .bind( 'touchstart mousedown vmousedown touchmove vmousemove vmouseover', function ( e ) {
156 // Get coords relative to the element
157 var coords = $.mobile.tizen.targetRelativeCoordsFromEvent( e ),
158 shortcutsListOffset = self.shortcutsList.offset();
160 if ( self._isFadeOut === true ) {
164 // If the element is a list item, get coordinates relative to the shortcuts list
165 if ( e.target.tagName.toLowerCase() === "li" ) {
166 coords.x += $( e.target ).offset().left - shortcutsListOffset.left;
167 coords.y += $( e.target ).offset().top - shortcutsListOffset.top;
170 if ( e.target.tagName.toLowerCase() === "span" ) {
171 coords.x += $( e.target ).parent().offset().left - shortcutsListOffset.left;
172 coords.y += $( e.target ).parent().offset().top - shortcutsListOffset.top;
175 self.shortcutsList.find( 'li' ).each( function () {
176 var listItem = $( this );
178 .removeClass( "ui-fastscroll-hover" )
179 .removeClass( "ui-fastscroll-hover-down" );
181 // Hit test each list item
182 self.shortcutsList.find( 'li' ).each( function () {
183 var listItem = $( this ),
184 l = listItem.offset().left - shortcutsListOffset.left,
185 t = listItem.offset().top - shortcutsListOffset.top,
186 r = l + Math.abs(listItem.outerWidth( true ) ),
187 b = t + Math.abs(listItem.outerHeight( true ) ),
194 if ( coords.x >= l && coords.x <= r && coords.y >= t && coords.y <= b ) {
195 if ( listItem.text() !== "." ) {
196 self._hitItem( listItem );
198 omitSet = listItem.data( "omitSet" );
199 unit = ( b - t ) / omitSet.length;
200 for ( i = 0; i < omitSet.length; i++ ) {
201 baseTop = t + ( i * unit );
202 baseBottom = baseTop + unit;
203 if ( coords.y >= baseTop && coords.y <= baseBottom ) {
204 self._hitOmitItem( listItem, omitSet.charAt( i ) );
213 self._setTimer( false );
218 // bind mouseout of the fastscroll container to remove popup
219 .bind( 'touchend mouseup vmouseup vmouseout', function () {
221 $( ".ui-fastscroll-hover" ).removeClass( "ui-fastscroll-hover" );
222 $( ".ui-fastscroll-hover-first-item" ).removeClass( "ui-fastscroll-hover-first-item" );
223 $( ".ui-fastscroll-hover-down" ).removeClass( "ui-fastscroll-hover-down" );
224 self._setTimer( true );
227 if ( page && !( page.is( ':visible' ) ) ) {
228 page.bind( 'pageshow', function () { self.refresh(); } );
233 // refresh the list when dividers are filtered out
234 $el.bind( 'updatelayout', function () {
238 self.scrollview.bind( "scrollstart", function ( e ) {
239 self._setTimer( false );
240 }).bind( "scrollstop", function ( e ) {
241 self._setTimer( true );
245 _hitOmitItem: function ( listItem, text ) {
247 $popup = self.scrollview.find( '.ui-fastscroll-popup' ),
248 divider = self._dividerMap[ text ];
250 if ( typeof divider !== "undefined" ) {
251 self.jumpToDivider( $( divider ) );
255 .css( { marginLeft: -( $popup.outerWidth() / 2 ),
256 marginTop: -( $popup.outerHeight() / 2 ),
257 padding: $popup.css( "paddingTop" ) } )
258 .width( $popup.height() )
261 $( listItem ).addClass( "ui-fastscroll-hover" );
262 if ( listItem.index() === 0 ) {
263 $( listItem ).addClass( "ui-fastscroll-hover-first-item" );
265 $( listItem ).siblings().eq( listItem.index() ).addClass( "ui-fastscroll-hover-down" );
268 _hitItem: function ( listItem ) {
270 $popup = self.scrollview.find( '.ui-fastscroll-popup' ),
271 text = listItem.text(),
274 if ( text === "#" ) {
275 divider = self._dividerMap.number;
277 divider = self._dividerMap[ text ];
280 if ( typeof divider !== "undefined" ) {
281 self.jumpToDivider( $( divider ) );
285 .css( { marginLeft: -( $popup.outerWidth() / 2 ),
286 marginTop: -( $popup.outerHeight() / 2 ),
287 padding: $popup.css( "paddingTop" ) } )
288 .width( $popup.height() )
291 $( listItem ).addClass( "ui-fastscroll-hover" );
292 if ( listItem.index() === 0 ) {
293 $( listItem ).addClass( "ui-fastscroll-hover-first-item" );
295 $( listItem ).siblings().eq( listItem.index() ).addClass( "ui-fastscroll-hover-down" );
298 _focusItem: function ( listItem ) {
300 $popup = self.scrollview.find( '.ui-fastscroll-popup' );
302 listItem.focusin( function ( e ) {
303 self.shortcutsList.attr( "aria-hidden", false );
304 self._hitItem( listItem );
305 self._setTimer( false );
306 }).focusout( function ( e ) {
307 self.shortcutsList.attr( "aria-hidden", true );
309 $( ".ui-fastscroll-hover" ).removeClass( "ui-fastscroll-hover" );
310 $( ".ui-fastscroll-hover-first-item" ).removeClass( "ui-fastscroll-hover-first-item" );
311 $( ".ui-fastscroll-hover-down" ).removeClass( "ui-fastscroll-hover-down" );
312 self._setTimer( true );
316 _contentHeight: function () {
318 $content = $( '.ui-scrollview-clip' ),
322 clipSize = $( window ).height();
324 if ( $content.hasClass( "ui-content" ) ) {
325 paddingValue = parseInt( $content.css( "padding-top" ), 10 );
326 clipSize = clipSize - ( paddingValue || 0 );
327 paddingValue = parseInt( $content.css( "padding-bottom" ), 10 );
328 clipSize = clipSize - ( paddingValue || 0 );
329 header = $content.siblings( ".ui-header:visible" );
330 footer = $content.siblings( ".ui-footer:visible" );
333 if ( header.outerHeight( true ) === null ) {
334 clipSize = clipSize - ( $( ".ui-header" ).outerHeight() || 0 );
336 clipSize = clipSize - header.outerHeight( true );
340 clipSize = clipSize - footer.outerHeight( true );
343 clipSize = $content.height();
348 _omit: function ( numOfItems, maxNumOfItems ) {
349 var maxGroupNum = parseInt( ( maxNumOfItems - 1 ) / 2, 10 ),
350 numOfExtraItems = numOfItems - maxNumOfItems,
358 if ( ( maxNumOfItems < 3 ) || ( numOfItems <= maxNumOfItems ) ) {
362 if ( numOfExtraItems >= maxGroupNum ) {
365 groupPosLength = maxGroupNum;
367 size = maxNumOfItems / ( numOfExtraItems + 1 );
369 groupPosLength = numOfExtraItems;
372 for ( i = 0; i < groupPosLength; i++ ) {
373 groupPos.push( parseInt( group, 10 ) );
377 for ( i = 0; i < maxNumOfItems; i++ ) {
381 for ( i = 0; i < numOfExtraItems; i++ ) {
382 omitInfo[ groupPos[ i % maxGroupNum ] ]++;
388 _createDividerMap: function () {
390 primaryCharacterSet = self._primaryLanguage ? self._primaryLanguage.replace( /,/g, "" ) : null,
391 secondCharacterSet = self._secondLanguage ? self._secondLanguage.replace( /,/g, "" ) : null,
392 numberSet = "0123456789",
393 dividers = self.element.find( '.ui-li-divider' ),
400 matchToDivider = function ( index, divider ) {
401 if ( $( divider ).text() === indexChar ) {
402 map[ indexChar ] = divider;
406 makeCharacterSet = function ( index, divider ) {
407 primaryCharacterSet += $( divider ).text();
410 if ( primaryCharacterSet === null ) {
411 primaryCharacterSet = "";
412 dividers.each( makeCharacterSet );
415 for ( i = 0; i < primaryCharacterSet.length; i++ ) {
416 indexChar = primaryCharacterSet.charAt( i );
417 dividers.each( matchToDivider );
420 if ( secondCharacterSet !== null ) {
421 for ( i = 0; i < secondCharacterSet.length; i++ ) {
422 indexChar = secondCharacterSet.charAt( i );
423 dividers.each( matchToDivider );
427 dividers.each( function ( index, divider ) {
428 if ( numberSet.search( $( divider ).text() ) !== -1 ) {
429 map.number = divider;
434 self._dividerMap = map;
437 _setTimer: function ( start ) {
440 if ( start === true ) {
441 self._timer = setTimeout( function () {
442 self._isFadeOut = true;
443 self.shortcutsContainer.fadeOut( self._defaultDuration, function () {
444 self._isFadeOut = false;
446 }, self._defaultTime );
448 if ( self._timer !== null ) {
449 clearTimeout( self._timer );
451 self.shortcutsContainer.show();
455 indexString: function ( indexAlphabet ) {
459 if ( typeof indexAlphabet === "undefined" ) {
460 return self._primaryLanguage + ":" + self._secondLanguage;
463 characterSet = indexAlphabet.split( ":" );
464 self._primaryLanguage = characterSet[ 0 ];
465 if ( characterSet.length === 2 ) {
466 self._secondLanguage = characterSet[ 1 ];
470 refresh: function () {
472 primaryCharacterSet = self._primaryLanguage ? self._primaryLanguage.replace( /,/g, "" ) : null,
473 secondCharacterSet = self._secondLanguage ? self._secondLanguage.replace( /,/g, "" ) : null,
474 contentHeight = self._contentHeight(),
475 shapItem = $( '<li tabindex="0" aria-label="double to move Number list"><span aria-hidden="true">#</span><span aria-label="Number"/></li>' ),
501 makeCharacterSet = function ( index, divider ) {
502 primaryCharacterSet += $( divider ).text();
505 makeOmitSet = function ( index, length ) {
509 for ( count = 0; count < length; count++ ) {
510 omitSet += primaryCharacterSet[ index + count ];
516 itemHandler = function ( e ) {
517 var text = $( this ).text(),
518 matchDivider = self._dividerMap[ text ];
520 if ( typeof matchDivider !== "undefined" ) {
521 $( matchDivider ).next().focus();
525 self._createDividerMap();
527 self.shortcutsList.find( 'li' ).remove();
529 // get all the dividers from the list and turn them into shortcuts
530 dividers = self.element.find( '.ui-li-divider' );
532 // get all the list items
533 listItems = self.element.find('li').not('.ui-li-divider');
535 // only use visible dividers
536 dividers = dividers.filter( ':visible' );
537 listItems = listItems.filter( ':visible' );
539 if ( dividers.length < 2 ) {
540 self.shortcutsList.hide();
544 self.shortcutsList.show();
545 self.lastListItem = listItems.last();
546 self.shortcutsList.append( shapItem );
547 self._focusItem( shapItem );
549 if ( primaryCharacterSet === null ) {
550 primaryCharacterSet = "";
551 dividers.each( makeCharacterSet );
554 padding = parseInt( shapItem.css( "padding" ), 10 );
555 minHeight = shapItem.height() + ( padding * 2 );
556 maxNumOfItems = parseInt( ( contentHeight / minHeight ) - 1, 10 );
557 numOfItems = primaryCharacterSet.length;
559 maxNumOfItems = secondCharacterSet ? maxNumOfItems - 2 : maxNumOfItems;
561 if ( maxNumOfItems < 3 ) {
566 omitInfo = self._omit( numOfItems, maxNumOfItems );
568 for ( i = 0; i < primaryCharacterSet.length; i++ ) {
569 indexChar = primaryCharacterSet.charAt( i );
570 shortcutItem = $( '<li tabindex="0" aria-label="double to move ' + indexChar + ' list">' + indexChar + '</li>' );
572 self._focusItem( shortcutItem );
574 if ( typeof omitInfo !== "undefined" && omitInfo[ omitIndex ] > 1 ) {
575 shortcutItem = $( '<li>.</li>' );
576 shortcutItem.data( "omitSet", makeOmitSet( i, omitInfo[ omitIndex ] ) );
577 i += omitInfo[ omitIndex ] - 1;
579 shortcutItem.bind( 'vclick', itemHandler );
582 shapItem.before( shortcutItem );
586 if ( secondCharacterSet !== null ) {
587 lastIndex = secondCharacterSet.length - 1;
590 seconds.push( secondCharacterSet.charAt( 0 ) );
591 seconds.push( secondCharacterSet.charAt( lastIndex ) );
593 for ( i = 0; i < seconds.length; i++ ) {
594 indexChar = seconds[ i ];
595 shortcutItem = $( '<li tabindex="0" aria-label="double to move ' + indexChar + ' list">' + indexChar + '</li>' );
597 self._focusItem( shortcutItem );
598 shortcutItem.bind( 'vclick', itemHandler );
599 shapItem.before( shortcutItem );
603 containerHeight = self.shortcutsContainer.outerHeight();
604 emptySize = contentHeight - containerHeight;
605 shortcutsItems = self.shortcutsList.children();
606 size = parseInt( emptySize / shortcutsItems.length, 10 );
607 correction = emptySize - ( shortcutsItems.length * size );
609 if ( emptySize > 0 ) {
610 shortcutsItems.each( function ( index, item ) {
611 height = $( item ).height() + size;
612 if ( correction !== 0 ) {
618 lineHeight: height + "px"
623 // position the shortcut flush with the top of the first list divider
624 shortcutsTop = dividers.first().position().top;
625 self.shortcutsContainer.css( 'top', shortcutsTop );
627 // make the scrollview clip tall enough to show the whole of the shortcutslist
628 minClipHeight = shortcutsTop + self.shortcutsContainer.outerHeight() + 'px';
629 self.scrollview.css( 'min-height', minClipHeight );
631 self._setTimer( false );
632 self._setTimer( true );
636 $( document ).bind( "pagecreate create", function ( e ) {
637 $( $.tizen.fastscroll.prototype.options.initSelector, e.target )
638 .not( ":jqmData(role='none'), :jqmData(role='nojs')" )
642 $( window ).bind( "resize orientationchange", function ( e ) {
643 $( ".ui-page-active .ui-fastscroll-target" ).fastscroll( "refresh" );