| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285 |
- /*!
- * jQuery doTimeout: Like setTimeout, but better! - v1.0 - 3/3/2010
- * http://benalman.com/projects/jquery-dotimeout-plugin/
- *
- * Copyright (c) 2010 "Cowboy" Ben Alman
- * Dual licensed under the MIT and GPL licenses.
- * http://benalman.com/about/license/
- */
- // Script: jQuery doTimeout: Like setTimeout, but better!
- //
- // *Version: 1.0, Last updated: 3/3/2010*
- //
- // Project Home - http://benalman.com/projects/jquery-dotimeout-plugin/
- // GitHub - http://github.com/cowboy/jquery-dotimeout/
- // Source - http://github.com/cowboy/jquery-dotimeout/raw/master/jquery.ba-dotimeout.js
- // (Minified) - http://github.com/cowboy/jquery-dotimeout/raw/master/jquery.ba-dotimeout.min.js (1.0kb)
- //
- // About: License
- //
- // Copyright (c) 2010 "Cowboy" Ben Alman,
- // Dual licensed under the MIT and GPL licenses.
- // http://benalman.com/about/license/
- //
- // About: Examples
- //
- // These working examples, complete with fully commented code, illustrate a few
- // ways in which this plugin can be used.
- //
- // Debouncing - http://benalman.com/code/projects/jquery-dotimeout/examples/debouncing/
- // Delays, Polling - http://benalman.com/code/projects/jquery-dotimeout/examples/delay-poll/
- // Hover Intent - http://benalman.com/code/projects/jquery-dotimeout/examples/hoverintent/
- //
- // About: Support and Testing
- //
- // Information about what version or versions of jQuery this plugin has been
- // tested with, what browsers it has been tested in, and where the unit tests
- // reside (so you can test it yourself).
- //
- // jQuery Versions - 1.3.2, 1.4.2
- // Browsers Tested - Internet Explorer 6-8, Firefox 2-3.6, Safari 3-4, Chrome 4-5, Opera 9.6-10.1.
- // Unit Tests - http://benalman.com/code/projects/jquery-dotimeout/unit/
- //
- // About: Release History
- //
- // 1.0 - (3/3/2010) Callback can now be a string, in which case it will call
- // the appropriate $.method or $.fn.method, depending on where .doTimeout
- // was called. Callback must now return `true` (not just a truthy value)
- // to poll.
- // 0.4 - (7/15/2009) Made the "id" argument optional, some other minor tweaks
- // 0.3 - (6/25/2009) Initial release
- (function($){
- '$:nomunge'; // Used by YUI compressor.
-
- var cache = {},
-
- // Reused internal string.
- doTimeout = 'doTimeout',
-
- // A convenient shortcut.
- aps = Array.prototype.slice;
-
- // Method: jQuery.doTimeout
- //
- // Initialize, cancel, or force execution of a callback after a delay.
- //
- // If delay and callback are specified, a doTimeout is initialized. The
- // callback will execute, asynchronously, after the delay. If an id is
- // specified, this doTimeout will override and cancel any existing doTimeout
- // with the same id. Any additional arguments will be passed into callback
- // when it is executed.
- //
- // If the callback returns true, the doTimeout loop will execute again, after
- // the delay, creating a polling loop until the callback returns a non-true
- // value.
- //
- // Note that if an id is not passed as the first argument, this doTimeout will
- // NOT be able to be manually canceled or forced. (for debouncing, be sure to
- // specify an id).
- //
- // If id is specified, but delay and callback are not, the doTimeout will be
- // canceled without executing the callback. If force_mode is specified, the
- // callback will be executed, synchronously, but will only be allowed to
- // continue a polling loop if force_mode is true (provided the callback
- // returns true, of course). If force_mode is false, no polling loop will
- // continue, even if the callback returns true.
- //
- // Usage:
- //
- // > jQuery.doTimeout( [ id, ] delay, callback [, arg ... ] );
- // > jQuery.doTimeout( id [, force_mode ] );
- //
- // Arguments:
- //
- // id - (String) An optional unique identifier for this doTimeout. If id is
- // not specified, the doTimeout will NOT be able to be manually canceled or
- // forced.
- // delay - (Number) A zero-or-greater delay in milliseconds after which
- // callback will be executed.
- // callback - (Function) A function to be executed after delay milliseconds.
- // callback - (String) A jQuery method to be executed after delay
- // milliseconds. This method will only poll if it explicitly returns
- // true.
- // force_mode - (Boolean) If true, execute that id's doTimeout callback
- // immediately and synchronously, continuing any callback return-true
- // polling loop. If false, execute the callback immediately and
- // synchronously but do NOT continue a callback return-true polling loop.
- // If omitted, cancel that id's doTimeout.
- //
- // Returns:
- //
- // If force_mode is true, false or undefined and there is a
- // yet-to-be-executed callback to cancel, true is returned, but if no
- // callback remains to be executed, undefined is returned.
-
- $[doTimeout] = function() {
- return p_doTimeout.apply( window, [ 0 ].concat( aps.call( arguments ) ) );
- };
-
- // Method: jQuery.fn.doTimeout
- //
- // Initialize, cancel, or force execution of a callback after a delay.
- // Operates like <jQuery.doTimeout>, but the passed callback executes in the
- // context of the jQuery collection of elements, and the id is stored as data
- // on the first element in that collection.
- //
- // If delay and callback are specified, a doTimeout is initialized. The
- // callback will execute, asynchronously, after the delay. If an id is
- // specified, this doTimeout will override and cancel any existing doTimeout
- // with the same id. Any additional arguments will be passed into callback
- // when it is executed.
- //
- // If the callback returns true, the doTimeout loop will execute again, after
- // the delay, creating a polling loop until the callback returns a non-true
- // value.
- //
- // Note that if an id is not passed as the first argument, this doTimeout will
- // NOT be able to be manually canceled or forced (for debouncing, be sure to
- // specify an id).
- //
- // If id is specified, but delay and callback are not, the doTimeout will be
- // canceled without executing the callback. If force_mode is specified, the
- // callback will be executed, synchronously, but will only be allowed to
- // continue a polling loop if force_mode is true (provided the callback
- // returns true, of course). If force_mode is false, no polling loop will
- // continue, even if the callback returns true.
- //
- // Usage:
- //
- // > jQuery('selector').doTimeout( [ id, ] delay, callback [, arg ... ] );
- // > jQuery('selector').doTimeout( id [, force_mode ] );
- //
- // Arguments:
- //
- // id - (String) An optional unique identifier for this doTimeout, stored as
- // jQuery data on the element. If id is not specified, the doTimeout will
- // NOT be able to be manually canceled or forced.
- // delay - (Number) A zero-or-greater delay in milliseconds after which
- // callback will be executed.
- // callback - (Function) A function to be executed after delay milliseconds.
- // callback - (String) A jQuery.fn method to be executed after delay
- // milliseconds. This method will only poll if it explicitly returns
- // true (most jQuery.fn methods return a jQuery object, and not `true`,
- // which allows them to be chained and prevents polling).
- // force_mode - (Boolean) If true, execute that id's doTimeout callback
- // immediately and synchronously, continuing any callback return-true
- // polling loop. If false, execute the callback immediately and
- // synchronously but do NOT continue a callback return-true polling loop.
- // If omitted, cancel that id's doTimeout.
- //
- // Returns:
- //
- // When creating a <jQuery.fn.doTimeout>, the initial jQuery collection of
- // elements is returned. Otherwise, if force_mode is true, false or undefined
- // and there is a yet-to-be-executed callback to cancel, true is returned,
- // but if no callback remains to be executed, undefined is returned.
-
- $.fn[doTimeout] = function() {
- var args = aps.call( arguments ),
- result = p_doTimeout.apply( this, [ doTimeout + args[0] ].concat( args ) );
-
- return typeof args[0] === 'number' || typeof args[1] === 'number'
- ? this
- : result;
- };
-
- function p_doTimeout( jquery_data_key ) {
- var that = this,
- elem,
- data = {},
-
- // Allows the plugin to call a string callback method.
- method_base = jquery_data_key ? $.fn : $,
-
- // Any additional arguments will be passed to the callback.
- args = arguments,
- slice_args = 4,
-
- id = args[1],
- delay = args[2],
- callback = args[3];
-
- if ( typeof id !== 'string' ) {
- slice_args--;
-
- id = jquery_data_key = 0;
- delay = args[1];
- callback = args[2];
- }
-
- // If id is passed, store a data reference either as .data on the first
- // element in a jQuery collection, or in the internal cache.
- if ( jquery_data_key ) { // Note: key is 'doTimeout' + id
-
- // Get id-object from the first element's data, otherwise initialize it to {}.
- elem = that.eq(0);
- elem.data( jquery_data_key, data = elem.data( jquery_data_key ) || {} );
-
- } else if ( id ) {
- // Get id-object from the cache, otherwise initialize it to {}.
- data = cache[ id ] || ( cache[ id ] = {} );
- }
-
- // Clear any existing timeout for this id.
- data.id && clearTimeout( data.id );
- delete data.id;
-
- // Clean up when necessary.
- function cleanup() {
- if ( jquery_data_key ) {
- elem.removeData( jquery_data_key );
- } else if ( id ) {
- delete cache[ id ];
- }
- };
-
- // Yes, there actually is a setTimeout call in here!
- function actually_setTimeout() {
- data.id = setTimeout( function(){ data.fn(); }, delay );
- };
-
- if ( callback ) {
- // A callback (and delay) were specified. Store the callback reference for
- // possible later use, and then setTimeout.
- data.fn = function( no_polling_loop ) {
-
- // If the callback value is a string, it is assumed to be the name of a
- // method on $ or $.fn depending on where doTimeout was executed.
- if ( typeof callback === 'string' ) {
- callback = method_base[ callback ];
- }
-
- callback.apply( that, aps.call( args, slice_args ) ) === true && !no_polling_loop
-
- // Since the callback returned true, and we're not specifically
- // canceling a polling loop, do it again!
- ? actually_setTimeout()
-
- // Otherwise, clean up and quit.
- : cleanup();
- };
-
- // Set that timeout!
- actually_setTimeout();
-
- } else if ( data.fn ) {
- // No callback passed. If force_mode (delay) is true, execute the data.fn
- // callback immediately, continuing any callback return-true polling loop.
- // If force_mode is false, execute the data.fn callback immediately but do
- // NOT continue a callback return-true polling loop. If force_mode is
- // undefined, simply clean up. Since data.fn was still defined, whatever
- // was supposed to happen hadn't yet, so return true.
- delay === undefined ? cleanup() : data.fn( delay === false );
- return true;
-
- } else {
- // Since no callback was passed, and data.fn isn't defined, it looks like
- // whatever was supposed to happen already did. Clean up and quit!
- cleanup();
- }
-
- };
-
- })(jQuery);
|