forked from mattbryson/TouchSwipe-Jquery-Plugin
-
Notifications
You must be signed in to change notification settings - Fork 0
/
jquery.touchSwipe.js
1961 lines (1646 loc) · 65.8 KB
/
jquery.touchSwipe.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*
* @fileOverview TouchSwipe - jQuery Plugin
* @version 1.6.3
*
* @author Matt Bryson http://www.github.com/mattbryson
* @see https://github.com/mattbryson/TouchSwipe-Jquery-Plugin
* @see http://labs.skinkers.com/touchSwipe/
* @see http://plugins.jquery.com/project/touchSwipe
*
* Copyright (c) 2010 Matt Bryson
* Dual licensed under the MIT or GPL Version 2 licenses.
*
*
* Changelog
* $Date: 2010-12-12 (Wed, 12 Dec 2010) $
* $version: 1.0.0
* $version: 1.0.1 - removed multibyte comments
*
* $Date: 2011-21-02 (Mon, 21 Feb 2011) $
* $version: 1.1.0 - added allowPageScroll property to allow swiping and scrolling of page
* - changed handler signatures so one handler can be used for multiple events
* $Date: 2011-23-02 (Wed, 23 Feb 2011) $
* $version: 1.2.0 - added click handler. This is fired if the user simply clicks and does not swipe. The event object and click target are passed to handler.
* - If you use the http://code.google.com/p/jquery-ui-for-ipad-and-iphone/ plugin, you can also assign jQuery mouse events to children of a touchSwipe object.
* $version: 1.2.1 - removed console log!
*
* $version: 1.2.2 - Fixed bug where scope was not preserved in callback methods.
*
* $Date: 2011-28-04 (Thurs, 28 April 2011) $
* $version: 1.2.4 - Changed licence terms to be MIT or GPL inline with jQuery. Added check for support of touch events to stop non compatible browsers erroring.
*
* $Date: 2011-27-09 (Tues, 27 September 2011) $
* $version: 1.2.5 - Added support for testing swipes with mouse on desktop browser (thanks to https://github.com/joelhy)
*
* $Date: 2012-14-05 (Mon, 14 May 2012) $
* $version: 1.2.6 - Added timeThreshold between start and end touch, so user can ignore slow swipes (thanks to Mark Chase). Default is null, all swipes are detected
*
* $Date: 2012-05-06 (Tues, 05 June 2012) $
* $version: 1.2.7 - Changed time threshold to have null default for backwards compatibility. Added duration param passed back in events, and refactored how time is handled.
*
* $Date: 2012-05-06 (Tues, 05 June 2012) $
* $version: 1.2.8 - Added the possibility to return a value like null or false in the trigger callback. In that way we can control when the touch start/move should take effect or not (simply by returning in some cases return null; or return false;) This effects the ontouchstart/ontouchmove event.
*
* $Date: 2012-06-06 (Wed, 06 June 2012) $
* $version: 1.3.0 - Refactored whole plugin to allow for methods to be executed, as well as exposed defaults for user override. Added 'enable', 'disable', and 'destroy' methods
*
* $Date: 2012-05-06 (Fri, 05 June 2012) $
* $version: 1.3.1 - Bug fixes - bind() with false as last argument is no longer supported in jQuery 1.6, also, if you just click, the duration is now returned correctly.
*
* $Date: 2012-29-07 (Sun, 29 July 2012) $
* $version: 1.3.2 - Added fallbackToMouseEvents option to NOT capture mouse events on non touch devices.
* - Added "all" fingers value to the fingers property, so any combinatin of fingers triggers the swipe, allowing event handlers to check the finger count
*
* $Date: 2012-09-08 (Thurs, 9 Aug 2012) $
* $version: 1.3.3 - Code tidy prep for minified version
*
* $Date: 2012-04-10 (wed, 4 Oct 2012) $
* $version: 1.4.0 - Added pinch support, pinchIn and pinchOut
*
* $Date: 2012-11-10 (Thurs, 11 Oct 2012) $
* $version: 1.5.0 - Added excludedElements, a jquery selector that specifies child elements that do NOT trigger swipes. By default, this is one select that removes all form, input select, button and anchor elements.
*
* $Date: 2012-22-10 (Mon, 22 Oct 2012) $
* $version: 1.5.1 - Fixed bug with jQuery 1.8 and trailing comma in excludedElements
* - Fixed bug with IE and eventPreventDefault()
* $Date: 2013-01-12 (Fri, 12 Jan 2013) $
* $version: 1.6.0 - Fixed bugs with pinching, mainly when both pinch and swipe enabled, as well as adding time threshold for multifinger gestures, so releasing one finger beofre the other doesnt trigger as single finger gesture.
* - made the demo site all static local HTML pages so they can be run locally by a developer
* - added jsDoc comments and added documentation for the plugin
* - code tidy
* - added triggerOnTouchLeave property that will end the event when the user swipes off the element.
* $Date: 2013-03-23 (Sat, 23 Mar 2013) $
* $version: 1.6.1 - Added support for ie8 touch events
* $version: 1.6.2 - Added support for events binding with on / off / bind in jQ for all callback names.
* - Deprecated the 'click' handler in favour of tap.
* - added cancelThreshold property
* - added option method to update init options at runtime
*
* $version 1.6.3 - added doubletap, longtap events and longTapThreshold, doubleTapThreshold property
* $Date: 2013-04-04 (Thurs, 04 April 2013) $
* $version 1.6.4 - Fixed bug with cancelThreshold introduced in 1.6.3, where swipe status no longer fired start event, and stopped once swiping back.
*/
/**
* See (http://jquery.com/).
* @name $
* @class
* See the jQuery Library (http://jquery.com/) for full details. This just
* documents the function and classes that are added to jQuery by this plug-in.
*/
/**
* See (http://jquery.com/)
* @name fn
* @class
* See the jQuery Library (http://jquery.com/) for full details. This just
* documents the function and classes that are added to jQuery by this plug-in.
* @memberOf $
*/
(function ($) {
"use strict";
//Constants
var LEFT = "left",
RIGHT = "right",
UP = "up",
DOWN = "down",
IN = "in",
OUT = "out",
NONE = "none",
AUTO = "auto",
SWIPE = "swipe",
PINCH = "pinch",
TAP = "tap",
DOUBLE_TAP = "doubletap",
LONG_TAP = "longtap",
HORIZONTAL = "horizontal",
VERTICAL = "vertical",
ALL_FINGERS = "all",
DOUBLE_TAP_THRESHOLD = 10,
PHASE_START = "start",
PHASE_MOVE = "move",
PHASE_END = "end",
PHASE_CANCEL = "cancel",
SUPPORTS_TOUCH = 'ontouchstart' in window,
PLUGIN_NS = 'TouchSwipe';
/**
* The default configuration, and available options to configure touch swipe with.
* You can set the default values by updating any of the properties prior to instantiation.
* @name $.fn.swipe.defaults
* @namespace
* @property {int} [fingers=1] The number of fingers to detect in a swipe. Any swipes that do not meet this requirement will NOT trigger swipe handlers.
* @property {int} [threshold=75] The number of pixels that the user must move their finger by before it is considered a swipe.
* @property {int} [cancelThreshold=null] The number of pixels that the user must move their finger back from the original swipe direction to cancel the gesture.
* @property {int} [pinchThreshold=20] The number of pixels that the user must pinch their finger by before it is considered a pinch.
* @property {int} [maxTimeThreshold=null] Time, in milliseconds, between touchStart and touchEnd must NOT exceed in order to be considered a swipe.
* @property {int} [fingerReleaseThreshold=250] Time in milliseconds between releasing multiple fingers. If 2 fingers are down, and are released one after the other, if they are within this threshold, it counts as a simultaneous release.
* @property {int} [longTapThreshold=500] Time in milliseconds between tap and release for a long tap
* @property {int} [doubleTapThreshold=200] Time in milliseconds between 2 taps to count as a doubletap
* @property {function} [swipe=null] A handler to catch all swipes. See {@link $.fn.swipe#event:swipe}
* @property {function} [swipeLeft=null] A handler that is triggered for "left" swipes. See {@link $.fn.swipe#event:swipeLeft}
* @property {function} [swipeRight=null] A handler that is triggered for "right" swipes. See {@link $.fn.swipe#event:swipeRight}
* @property {function} [swipeUp=null] A handler that is triggered for "up" swipes. See {@link $.fn.swipe#event:swipeUp}
* @property {function} [swipeDown=null] A handler that is triggered for "down" swipes. See {@link $.fn.swipe#event:swipeDown}
* @property {function} [swipeStatus=null] A handler triggered for every phase of the swipe. See {@link $.fn.swipe#event:swipeStatus}
* @property {function} [pinchIn=null] A handler triggered for pinch in events. See {@link $.fn.swipe#event:pinchIn}
* @property {function} [pinchOut=null] A handler triggered for pinch out events. See {@link $.fn.swipe#event:pinchOut}
* @property {function} [pinchStatus=null] A handler triggered for every phase of a pinch. See {@link $.fn.swipe#event:pinchStatus}
* @property {function} [tap=null] A handler triggered when a user just taps on the item, rather than swipes it. If they do not move, tap is triggered, if they do move, it is not.
* @property {function} [doubleTap=null] A handler triggered when a user double taps on the item. The delay between taps can be set with the doubleTapThreshold property. See {@link $.fn.swipe.defaults#doubleTapThreshold}
* @property {function} [longTap=null] A handler triggered when a user long taps on the item. The delay between start and end can be set with the longTapThreshold property. See {@link $.fn.swipe.defaults#doubleTapThreshold}
* @property {boolean} [triggerOnTouchEnd=true] If true, the swipe events are triggered when the touch end event is received (user releases finger). If false, it will be triggered on reaching the threshold, and then cancel the touch event automatically.
* @property {boolean} [triggerOnTouchLeave=false] If true, then when the user leaves the swipe object, the swipe will end and trigger appropriate handlers.
* @property {string} [allowPageScroll='auto'] How the browser handles page scrolls when the user is swiping on a touchSwipe object. See {@link $.fn.swipe.pageScroll}. <br/><br/>
<code>"auto"</code> : all undefined swipes will cause the page to scroll in that direction. <br/>
<code>"none"</code> : the page will not scroll when user swipes. <br/>
<code>"horizontal"</code> : will force page to scroll on horizontal swipes. <br/>
<code>"vertical"</code> : will force page to scroll on vertical swipes. <br/>
* @property {boolean} [fallbackToMouseEvents=true] If true mouse events are used when run on a non touch device, false will stop swipes being triggered by mouse events on non tocuh devices.
* @property {string} [excludedElements="button, input, select, textarea, a, .noSwipe"] A jquery selector that specifies child elements that do NOT trigger swipes. By default this excludes all form, input, select, button, anchor and .noSwipe elements.
*/
var defaults = {
fingers: 1,
threshold: 75,
cancelThreshold:null,
pinchThreshold:20,
maxTimeThreshold: null,
fingerReleaseThreshold:250,
longTapThreshold:500,
doubleTapThreshold:200,
swipe: null,
swipeLeft: null,
swipeRight: null,
swipeUp: null,
swipeDown: null,
swipeStatus: null,
pinchIn:null,
pinchOut:null,
pinchStatus:null,
click:null, //Deprecated since 1.6.2
tap:null,
doubleTap:null,
longTap:null,
triggerOnTouchEnd: true,
triggerOnTouchLeave:false,
allowPageScroll: "auto",
fallbackToMouseEvents: true,
excludedElements:"button, input, select, textarea, a, .noSwipe"
};
/**
* Applies TouchSwipe behaviour to one or more jQuery objects.
* The TouchSwipe plugin can be instantiated via this method, or methods within
* TouchSwipe can be executed via this method as per jQuery plugin architecture.
* @see TouchSwipe
* @class
* @param {Mixed} method If the current DOMNode is a TouchSwipe object, and <code>method</code> is a TouchSwipe method, then
* the <code>method</code> is executed, and any following arguments are passed to the TouchSwipe method.
* If <code>method</code> is an object, then the TouchSwipe class is instantiated on the current DOMNode, passing the
* configuration properties defined in the object. See TouchSwipe
*
*/
$.fn.swipe = function (method) {
var $this = $(this),
plugin = $this.data(PLUGIN_NS);
//Check if we are already instantiated and trying to execute a method
if (plugin && typeof method === 'string') {
if (plugin[method]) {
return plugin[method].apply(this, Array.prototype.slice.call(arguments, 1));
} else {
$.error('Method ' + method + ' does not exist on jQuery.swipe');
}
}
//Else not instantiated and trying to pass init object (or nothing)
else if (!plugin && (typeof method === 'object' || !method)) {
return init.apply(this, arguments);
}
return $this;
};
//Expose our defaults so a user could override the plugin defaults
$.fn.swipe.defaults = defaults;
/**
* The phases that a touch event goes through. The <code>phase</code> is passed to the event handlers.
* These properties are read only, attempting to change them will not alter the values passed to the event handlers.
* @namespace
* @readonly
* @property {string} PHASE_START Constant indicating the start phase of the touch event. Value is <code>"start"</code>.
* @property {string} PHASE_MOVE Constant indicating the move phase of the touch event. Value is <code>"move"</code>.
* @property {string} PHASE_END Constant indicating the end phase of the touch event. Value is <code>"end"</code>.
* @property {string} PHASE_CANCEL Constant indicating the cancel phase of the touch event. Value is <code>"cancel"</code>.
*/
$.fn.swipe.phases = {
PHASE_START: PHASE_START,
PHASE_MOVE: PHASE_MOVE,
PHASE_END: PHASE_END,
PHASE_CANCEL: PHASE_CANCEL
};
/**
* The direction constants that are passed to the event handlers.
* These properties are read only, attempting to change them will not alter the values passed to the event handlers.
* @namespace
* @readonly
* @property {string} LEFT Constant indicating the left direction. Value is <code>"left"</code>.
* @property {string} RIGHT Constant indicating the right direction. Value is <code>"right"</code>.
* @property {string} UP Constant indicating the up direction. Value is <code>"up"</code>.
* @property {string} DOWN Constant indicating the down direction. Value is <code>"cancel"</code>.
* @property {string} IN Constant indicating the in direction. Value is <code>"in"</code>.
* @property {string} OUT Constant indicating the out direction. Value is <code>"out"</code>.
*/
$.fn.swipe.directions = {
LEFT: LEFT,
RIGHT: RIGHT,
UP: UP,
DOWN: DOWN,
IN : IN,
OUT: OUT
};
/**
* The page scroll constants that can be used to set the value of <code>allowPageScroll</code> option
* These properties are read only
* @namespace
* @readonly
* @see $.fn.swipe.defaults#allowPageScroll
* @property {string} NONE Constant indicating no page scrolling is allowed. Value is <code>"none"</code>.
* @property {string} HORIZONTAL Constant indicating horizontal page scrolling is allowed. Value is <code>"horizontal"</code>.
* @property {string} VERTICAL Constant indicating vertical page scrolling is allowed. Value is <code>"vertical"</code>.
* @property {string} AUTO Constant indicating either horizontal or vertical will be allowed, depending on the swipe handlers registered. Value is <code>"auto"</code>.
*/
$.fn.swipe.pageScroll = {
NONE: NONE,
HORIZONTAL: HORIZONTAL,
VERTICAL: VERTICAL,
AUTO: AUTO
};
/**
* Constants representing the number of fingers used in a swipe. These are used to set both the value of <code>fingers</code> in the
* options object, as well as the value of the <code>fingers</code> event property.
* These properties are read only, attempting to change them will not alter the values passed to the event handlers.
* @namespace
* @readonly
* @see $.fn.swipe.defaults#fingers
* @property {string} ONE Constant indicating 1 finger is to be detected / was detected. Value is <code>1</code>.
* @property {string} TWO Constant indicating 2 fingers are to be detected / were detected. Value is <code>1</code>.
* @property {string} THREE Constant indicating 3 finger are to be detected / were detected. Value is <code>1</code>.
* @property {string} ALL Constant indicating any combination of finger are to be detected. Value is <code>"all"</code>.
*/
$.fn.swipe.fingers = {
ONE: 1,
TWO: 2,
THREE: 3,
ALL: ALL_FINGERS
};
/**
* Initialise the plugin for each DOM element matched
* This creates a new instance of the main TouchSwipe class for each DOM element, and then
* saves a reference to that instance in the elements data property.
* @internal
*/
function init(options) {
//Prep and extend the options
if (options && (options.allowPageScroll === undefined && (options.swipe !== undefined || options.swipeStatus !== undefined))) {
options.allowPageScroll = NONE;
}
//Check for deprecated options
//Ensure that any old click handlers are assigned to the new tap, unless we have a tap
if(options.click!==undefined && options.tap===undefined) {
options.tap = options.click;
}
if (!options) {
options = {};
}
//pass empty object so we dont modify the defaults
options = $.extend({}, $.fn.swipe.defaults, options);
//For each element instantiate the plugin
return this.each(function () {
var $this = $(this);
//Check we havent already initialised the plugin
var plugin = $this.data(PLUGIN_NS);
if (!plugin) {
plugin = new TouchSwipe(this, options);
$this.data(PLUGIN_NS, plugin);
}
});
}
/**
* Main TouchSwipe Plugin Class.
* Do not use this to construct your TouchSwipe object, use the jQuery plugin method $.fn.swipe(); {@link $.fn.swipe}
* @private
* @name TouchSwipe
* @param {DOMNode} element The HTML DOM object to apply to plugin to
* @param {Object} options The options to configure the plugin with. @link {$.fn.swipe.defaults}
* @see $.fh.swipe.defaults
* @see $.fh.swipe
* @class
*/
function TouchSwipe(element, options) {
var useTouchEvents = (SUPPORTS_TOUCH || !options.fallbackToMouseEvents),
START_EV = useTouchEvents ? 'touchstart' : 'mousedown',
MOVE_EV = useTouchEvents ? 'touchmove' : 'mousemove',
END_EV = useTouchEvents ? 'touchend' : 'mouseup',
LEAVE_EV = useTouchEvents ? null : 'mouseleave', //we manually detect leave on touch devices, so null event here
CANCEL_EV = 'touchcancel';
//touch properties
var distance = 0,
direction = null,
duration = 0,
startTouchesDistance = 0,
endTouchesDistance = 0,
pinchZoom = 1,
pinchDistance = 0,
pinchDirection = 0,
maximumsMap=null;
//jQuery wrapped element for this instance
var $element = $(element);
//Current phase of th touch cycle
var phase = "start";
// the current number of fingers being used.
var fingerCount = 0;
//track mouse points / delta
var fingerData=null;
//track times
var startTime = 0,
endTime = 0,
previousTouchEndTime=0,
previousTouchFingerCount=0,
doubleTapStartTime=0;
//Timeouts
var singleTapTimeout=null;
// Add gestures to all swipable areas if supported
try {
$element.bind(START_EV, touchStart);
$element.bind(CANCEL_EV, touchCancel);
}
catch (e) {
$.error('events not supported ' + START_EV + ',' + CANCEL_EV + ' on jQuery.swipe');
}
//
//Public methods
//
/**
* re-enables the swipe plugin with the previous configuration
* @function
* @name $.fn.swipe#enable
* @return {DOMNode} The Dom element that was registered with TouchSwipe
* @example $("#element").swipe("enable");
*/
this.enable = function () {
$element.bind(START_EV, touchStart);
$element.bind(CANCEL_EV, touchCancel);
return $element;
};
/**
* disables the swipe plugin
* @function
* @name $.fn.swipe#disable
* @return {DOMNode} The Dom element that is now registered with TouchSwipe
* @example $("#element").swipe("disable");
*/
this.disable = function () {
removeListeners();
return $element;
};
/**
* Destroy the swipe plugin completely. To use any swipe methods, you must re initialise the plugin.
* @function
* @name $.fn.swipe#destroy
* @return {DOMNode} The Dom element that was registered with TouchSwipe
* @example $("#element").swipe("destroy");
*/
this.destroy = function () {
removeListeners();
$element.data(PLUGIN_NS, null);
return $element;
};
/**
* Allows run time updating of the swipe configuration options.
* @function
* @name $.fn.swipe#option
* @param {String} property The option property to get or set
* @param {Object} [value] The value to set the property to
* @return {Object} If only a property name is passed, then that property value is returned.
* @example $("#element").swipe("option", "threshold"); // return the threshold
* @example $("#element").swipe("option", "threshold", 100); // set the threshold after init
* @see $.fn.swipe.defaults
*
*/
this.option = function (property, value) {
if(options[property]!==undefined) {
if(value===undefined) {
return options[property];
} else {
options[property] = value;
}
} else {
$.error('Option ' + property + ' does not exist on jQuery.swipe.options');
}
}
//
// Private methods
//
//
// EVENTS
//
/**
* Event handler for a touch start event.
* Stops the default click event from triggering and stores where we touched
* @inner
* @param {object} jqEvent The normalised jQuery event object.
*/
function touchStart(jqEvent) {
//If we already in a touch event (a finger already in use) then ignore subsequent ones..
if( getTouchInProgress() )
return;
//Check if this element matches any in the excluded elements selectors, or its parent is excluded, if so, DONT swipe
if( $(jqEvent.target).closest( options.excludedElements, $element ).length>0 )
return;
//As we use Jquery bind for events, we need to target the original event object
//If these events are being programatically triggered, we dont have an orignal event object, so use the Jq one.
var event = jqEvent.originalEvent ? jqEvent.originalEvent : jqEvent;
var ret,
evt = SUPPORTS_TOUCH ? event.touches[0] : event;
phase = PHASE_START;
//If we support touches, get the finger count
if (SUPPORTS_TOUCH) {
// get the total number of fingers touching the screen
fingerCount = event.touches.length;
}
//Else this is the desktop, so stop the browser from dragging the image
else {
jqEvent.preventDefault(); //call this on jq event so we are cross browser
}
//clear vars..
distance = 0;
direction = null;
pinchDirection=null;
duration = 0;
startTouchesDistance=0;
endTouchesDistance=0;
pinchZoom = 1;
pinchDistance = 0;
fingerData=createAllFingerData();
maximumsMap=createMaximumsData();
cancelMultiFingerRelease();
// check the number of fingers is what we are looking for, or we are capturing pinches
if (!SUPPORTS_TOUCH || (fingerCount === options.fingers || options.fingers === ALL_FINGERS) || hasPinches()) {
// get the coordinates of the touch
createFingerData( 0, evt );
startTime = getTimeStamp();
if(fingerCount==2) {
//Keep track of the initial pinch distance, so we can calculate the diff later
//Store second finger data as start
createFingerData( 1, event.touches[1] );
startTouchesDistance = endTouchesDistance = calculateTouchesDistance(fingerData[0].start, fingerData[1].start);
}
if (options.swipeStatus || options.pinchStatus) {
ret = triggerHandler(event, phase);
}
}
else {
//A touch with more or less than the fingers we are looking for, so cancel
ret = false;
}
//If we have a return value from the users handler, then return and cancel
if (ret === false) {
phase = PHASE_CANCEL;
triggerHandler(event, phase);
return ret;
}
else {
setTouchInProgress(true);
}
};
/**
* Event handler for a touch move event.
* If we change fingers during move, then cancel the event
* @inner
* @param {object} jqEvent The normalised jQuery event object.
*/
function touchMove(jqEvent) {
//As we use Jquery bind for events, we need to target the original event object
//If these events are being programatically triggered, we dont have an orignal event object, so use the Jq one.
var event = jqEvent.originalEvent ? jqEvent.originalEvent : jqEvent;
//If we are ending, cancelling, or within the threshold of 2 fingers being released, dont track anything..
if (phase === PHASE_END || phase === PHASE_CANCEL || inMultiFingerRelease())
return;
var ret,
evt = SUPPORTS_TOUCH ? event.touches[0] : event;
//Update the finger data
var currentFinger = updateFingerData(evt);
endTime = getTimeStamp();
if (SUPPORTS_TOUCH) {
fingerCount = event.touches.length;
}
phase = PHASE_MOVE;
//If we have 2 fingers get Touches distance as well
if(fingerCount==2) {
//Keep track of the initial pinch distance, so we can calculate the diff later
//We do this here as well as the start event, incase they start with 1 finger, and the press 2 fingers
if(startTouchesDistance==0) {
//Create second finger if this is the first time...
createFingerData( 1, event.touches[1] );
startTouchesDistance = endTouchesDistance = calculateTouchesDistance(fingerData[0].start, fingerData[1].start);
} else {
//Else just update the second finger
updateFingerData(event.touches[1]);
endTouchesDistance = calculateTouchesDistance(fingerData[0].end, fingerData[1].end);
pinchDirection = calculatePinchDirection(fingerData[0].end, fingerData[1].end);
}
pinchZoom = calculatePinchZoom(startTouchesDistance, endTouchesDistance);
pinchDistance = Math.abs(startTouchesDistance - endTouchesDistance);
}
if ( (fingerCount === options.fingers || options.fingers === ALL_FINGERS) || !SUPPORTS_TOUCH || hasPinches() ) {
direction = calculateDirection(currentFinger.start, currentFinger.end);
//Check if we need to prevent default evnet (page scroll / pinch zoom) or not
validateDefaultEvent(jqEvent, direction);
//Distance and duration are all off the main finger
distance = calculateDistance(currentFinger.start, currentFinger.end);
duration = calculateDuration();
//Cache the maximum distance we made in this direction
setMaxDistance(direction, distance);
if (options.swipeStatus || options.pinchStatus) {
ret = triggerHandler(event, phase);
}
//If we trigger end events when threshold are met, or trigger events when touch leves element
if(!options.triggerOnTouchEnd || options.triggerOnTouchLeave) {
var inBounds = true;
//If checking if we leave the element, run the bounds check (we can use touchleave as its not supported on webkit)
if(options.triggerOnTouchLeave) {
var bounds = getbounds( this );
inBounds = isInBounds( currentFinger.end, bounds );
}
//Trigger end handles as we swipe if thresholds met or if we have left the element if the user has asked to check these..
if(!options.triggerOnTouchEnd && inBounds) {
phase = getNextPhase( PHASE_MOVE );
}
//We end if out of bounds here, so set current phase to END, and check if its modified
else if(options.triggerOnTouchLeave && !inBounds ) {
phase = getNextPhase( PHASE_END );
}
if(phase==PHASE_CANCEL || phase==PHASE_END) {
triggerHandler(event, phase);
}
}
}
else {
phase = PHASE_CANCEL;
triggerHandler(event, phase);
}
if (ret === false) {
phase = PHASE_CANCEL;
triggerHandler(event, phase);
}
}
/**
* Event handler for a touch end event.
* Calculate the direction and trigger events
* @inner
* @param {object} jqEvent The normalised jQuery event object.
*/
function touchEnd(jqEvent) {
//As we use Jquery bind for events, we need to target the original event object
var event = jqEvent.originalEvent;
//If we are still in a touch with another finger return
//This allows us to wait a fraction and see if the other finger comes up, if it does within the threshold, then we treat it as a multi release, not a single release.
if (SUPPORTS_TOUCH) {
if(event.touches.length>0) {
startMultiFingerRelease();
return true;
}
}
//If a previous finger has been released, check how long ago, if within the threshold, then assume it was a multifinger release.
//This is used to allow 2 fingers to release fractionally after each other, whilst maintainig the event as containg 2 fingers, not 1
if(inMultiFingerRelease()) {
fingerCount=previousTouchFingerCount;
}
//call this on jq event so we are cross browser
jqEvent.preventDefault();
//Set end of swipe
endTime = getTimeStamp();
//Get duration incase move was never fired
duration = calculateDuration();
//If we trigger handlers at end of swipe OR, we trigger during, but they didnt trigger and we are still in the move phase
if(didSwipeBackToCancel()) {
phase = PHASE_CANCEL;
triggerHandler(event, phase);
} else if (options.triggerOnTouchEnd || (options.triggerOnTouchEnd == false && phase === PHASE_MOVE)) {
phase = PHASE_END;
triggerHandler(event, phase);
}
//Special cases - A tap should always fire on touch end regardless,
//So here we manually trigger the tap end handler by itself
//We dont run trigger handler as it will re-trigger events that may have fired already
else if (!options.triggerOnTouchEnd && hasTap()) {
//Trigger the pinch events...
phase = PHASE_END;
triggerHandlerForGesture(event, phase, TAP);
}
else if (phase === PHASE_MOVE) {
phase = PHASE_CANCEL;
triggerHandler(event, phase);
}
setTouchInProgress(false);
}
/**
* Event handler for a touch cancel event.
* Clears current vars
* @inner
*/
function touchCancel() {
// reset the variables back to default values
fingerCount = 0;
endTime = 0;
startTime = 0;
startTouchesDistance=0;
endTouchesDistance=0;
pinchZoom=1;
//If we were in progress of tracking a possible multi touch end, then re set it.
cancelMultiFingerRelease();
setTouchInProgress(false);
}
/**
* Event handler for a touch leave event.
* This is only triggered on desktops, in touch we work this out manually
* as the touchleave event is not supported in webkit
* @inner
*/
function touchLeave(jqEvent) {
var event = jqEvent.originalEvent;
//If we have the trigger on leve property set....
if(options.triggerOnTouchLeave) {
phase = getNextPhase( PHASE_END );
triggerHandler(event, phase);
}
}
/**
* Removes all listeners that were associated with the plugin
* @inner
*/
function removeListeners() {
$element.unbind(START_EV, touchStart);
$element.unbind(CANCEL_EV, touchCancel);
$element.unbind(MOVE_EV, touchMove);
$element.unbind(END_EV, touchEnd);
//we only have leave events on desktop, we manually calcuate leave on touch as its not supported in webkit
if(LEAVE_EV) {
$element.unbind(LEAVE_EV, touchLeave);
}
setTouchInProgress(false);
}
/**
* Checks if the time and distance thresholds have been met, and if so then the appropriate handlers are fired.
*/
function getNextPhase(currentPhase) {
var nextPhase = currentPhase;
// Ensure we have valid swipe (under time and over distance and check if we are out of bound...)
var validTime = validateSwipeTime();
var validDistance = validateSwipeDistance();
var didCancel = didSwipeBackToCancel();
//If we have exceeded our time, then cancel
if(!validTime || didCancel) {
nextPhase = PHASE_CANCEL;
}
//Else if we are moving, and have reached distance then end
else if (validDistance && currentPhase == PHASE_MOVE && (!options.triggerOnTouchEnd || options.triggerOnTouchLeave) ) {
nextPhase = PHASE_END;
}
//Else if we have ended by leaving and didnt reach distance, then cancel
else if (!validDistance && currentPhase==PHASE_END && options.triggerOnTouchLeave) {
nextPhase = PHASE_CANCEL;
}
return nextPhase;
}
/**
* Trigger the relevant event handler
* The handlers are passed the original event, the element that was swiped, and in the case of the catch all handler, the direction that was swiped, "left", "right", "up", or "down"
* @param {object} event the original event object
* @param {string} phase the phase of the swipe (start, end cancel etc) {@link $.fn.swipe.phases}
* @inner
*/
function triggerHandler(event, phase) {
var ret = undefined;
// SWIPE GESTURES
if(didSwipe() || hasSwipes()) { //hasSwipes as status needs to fire even if swipe is invalid
//Trigger the swipe events...
ret = triggerHandlerForGesture(event, phase, SWIPE);
}
// PINCH GESTURES (if the above didnt cancel)
else if((didPinch() || hasPinches()) && ret!==false) {
//Trigger the pinch events...
ret = triggerHandlerForGesture(event, phase, PINCH);
}
// CLICK / TAP (if the above didnt cancel)
if(didDoubleTap() && ret!==false) {
//Trigger the tap events...
ret = triggerHandlerForGesture(event, phase, DOUBLE_TAP);
}
// CLICK / TAP (if the above didnt cancel)
else if(didLongTap() && ret!==false) {
//Trigger the tap events...
ret = triggerHandlerForGesture(event, phase, LONG_TAP);
}
// CLICK / TAP (if the above didnt cancel)
else if(didTap() && ret!==false) {
//Trigger the tap event..
ret = triggerHandlerForGesture(event, phase, TAP);
}
// If we are cancelling the gesture, then manually trigger the reset handler
if (phase === PHASE_CANCEL) {
touchCancel(event);
}
// If we are ending the gesture, then manually trigger the reset handler IF all fingers are off
if(phase === PHASE_END) {
//If we support touch, then check that all fingers are off before we cancel
if (SUPPORTS_TOUCH) {
if(event.touches.length==0) {
touchCancel(event);
}
}
else {
touchCancel(event);
}
}
return ret;
}
/**
* Trigger the relevant event handler
* The handlers are passed the original event, the element that was swiped, and in the case of the catch all handler, the direction that was swiped, "left", "right", "up", or "down"
* @param {object} event the original event object
* @param {string} phase the phase of the swipe (start, end cancel etc) {@link $.fn.swipe.phases}
* @param {string} gesture the gesture to triger a handler for : PINCH or SWIPE {@link $.fn.swipe.gestures}
* @return Boolean False, to indicate that the event should stop propagation, or void.
* @inner
*/
function triggerHandlerForGesture(event, phase, gesture) {
var ret=undefined;
//SWIPES....
if(gesture==SWIPE) {
//Trigger status every time..
//Trigger the event...
$element.trigger('swipeStatus', [phase, direction || null, distance || 0, duration || 0, fingerCount]);
//Fire the callback
if (options.swipeStatus) {
ret = options.swipeStatus.call($element, event, phase, direction || null, distance || 0, duration || 0, fingerCount);
//If the status cancels, then dont run the subsequent event handlers..
if(ret===false) return false;
}
if (phase == PHASE_END && validateSwipe()) {
//Fire the catch all event
$element.trigger('swipe', [direction, distance, duration, fingerCount]);
//Fire catch all callback
if (options.swipe) {
ret = options.swipe.call($element, event, direction, distance, duration, fingerCount);
//If the status cancels, then dont run the subsequent event handlers..
if(ret===false) return false;
}
//trigger direction specific event handlers
switch (direction) {
case LEFT:
//Trigger the event
$element.trigger('swipeLeft', [direction, distance, duration, fingerCount]);
//Fire the callback
if (options.swipeLeft) {
ret = options.swipeLeft.call($element, event, direction, distance, duration, fingerCount);
}
break;
case RIGHT:
//Trigger the event
$element.trigger('swipeRight', [direction, distance, duration, fingerCount]);
//Fire the callback
if (options.swipeRight) {
ret = options.swipeRight.call($element, event, direction, distance, duration, fingerCount);
}
break;
case UP:
//Trigger the event
$element.trigger('swipeUp', [direction, distance, duration, fingerCount]);
//Fire the callback
if (options.swipeUp) {
ret = options.swipeUp.call($element, event, direction, distance, duration, fingerCount);
}
break;
case DOWN:
//Trigger the event
$element.trigger('swipeDown', [direction, distance, duration, fingerCount]);
//Fire the callback
if (options.swipeDown) {
ret = options.swipeDown.call($element, event, direction, distance, duration, fingerCount);
}
break;
}
}
}
//PINCHES....
if(gesture==PINCH) {
//Trigger the event
$element.trigger('pinchStatus', [phase, pinchDirection || null, pinchDistance || 0, duration || 0, fingerCount, pinchZoom]);
//Fire the callback
if (options.pinchStatus) {
ret = options.pinchStatus.call($element, event, phase, pinchDirection || null, pinchDistance || 0, duration || 0, fingerCount, pinchZoom);
//If the status cancels, then dont run the subsequent event handlers..
if(ret===false) return false;
}