jquery tips

   1 /* Doc definitions for JQuery support in NetBeans, 
   2  * automatically generated from the JQuery documentation
   3  * using the generator in misc/javascript.generatestubs/jquery-sdoc
   4  * Version: 1.0
   5  */
   6 
   7 /**
   8  * @id jQuery
   9  * @global jQuery
  10  * @type jQuery
  11  */
  12 
  13 /**
  14  * @id $
  15  * @global $
  16  * @type jQuery
  17  */
  18 
  19 /**
  20  * This function accepts a string containing a CSS selector which is then used to match a set of elements.
  21  * The core functionality of jQuery centers around this function. Everything in jQuery is based upon this, or uses this in some way. The most basic use of this function is to pass in an expression (usually consisting of CSS), which then finds all matching elements. By default, if no context is specified, $() looks for DOM elements within the context of the current HTML document. If you do specify a context, such as a DOM element or jQuery object, the expression will be matched against the contents of that context. See<a href='Selectors'>Selectors</a> for the allowed CSS syntax for expressions.
  22  * @code
  23  * $("div", xml.responseXML);
  24  * @id jQuery.jQuery
  25  * @param {String} expression An expression to search with.
  26  * @param {Element, jQuery} context A DOM Element, Document or jQuery to use as context
  27  * @type jQuery
  28  * @since 1.0
  29  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
  30  */
  31 
  32 /**
  33  * Create DOM elements on-the-fly from the provided String of raw HTML.
  34  * You can pass in plain HTML Strings written by hand, create them using some template engine or plugin, or load them via AJAX. There are limitations when creating input elements, see the second example. Also when passing strings that may include slashes (such as an image path), escape the slashes. When creating single elements use the closing tag or XHTML format. For example, to create a span use $("<span/>") or $("<span></span>") instead of without the closing slash/tag.
  35  * @code
  36  * // Does NOT work in IE:
  37  * $("<input/>").attr("type", "checkbox");
  38  * // Does work in IE:
  39  * $("<input type='checkbox'/>");
  40  * @id jQuery.jQuery
  41  * @param {String} html A string of HTML to create on the fly.
  42  * @param {document} ownerDocument A document in which the new elements will be created
  43  * @type jQuery
  44  * @since 1.0
  45  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
  46  */
  47 
  48 /**
  49  * Wrap jQuery functionality around a single or multiple DOM Element(s).
  50  * This function also accepts XML Documents and Window objects as valid arguments (even though they are not DOM Elements).
  51  * @code
  52  * $(myForm.elements).hide()
  53  * @id jQuery.jQuery
  54  * @param {Element, Array<Element>} elements DOM element(s) to be encapsulated by a jQuery object.
  55  * @type jQuery
  56  * @since 1.0
  57  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
  58  */
  59 
  60 /**
  61  * A shorthand for $(document).ready().
  62  * Allows you to bind a function to be executed when the DOM document has finished loading. This function behaves just like $(document).ready(), in that it should be used to wrap other $() operations on your page that depend on the DOM being ready to be operated on. While this function is, technically, chainable - there really isn't much use for chaining against it. You can have as many $(document).ready events on your page as you like. See ready(Function) for details about the ready event.
  63  * @code
  64  * jQuery(function($) {
  65  *   // Your code using failsafe $ alias here
  66  * });
  67  * @id jQuery.jQuery
  68  * @param {Function} callback The function to execute when the DOM is ready.
  69  * @type jQuery
  70  * @since 1.0
  71  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
  72  */
  73 
  74 /**
  75  * Execute a function within the context of every matched element.
  76  * This means that every time the passed-in function is executed (which is once for every element matched) the 'this' keyword points to the specific DOM element. Additionally, the function, when executed, is passed a single argument representing the position of the element in the matched set (integer, zero-index). Returning 'false' from within the each function completely stops the loop through all of the elements (this is like using a 'break' with a normal loop). Returning 'true' from within the loop skips to the next iteration (this is like using a 'continue' with a normal loop).
  77  * @code
  78  * $("button").click(function () {
  79  *       $("div").each(function (index, domEle) {
  80  *         // domEle == this
  81  *         $(domEle).css("backgroundColor", "yellow"); 
  82  *         if ($(this).is("#stop")) {
  83  *           $("span").text("Stopped at div index #" + index);
  84  *           return false;
  85  *         }
  86  *       });
  87  *     });
  88  * @id jQuery.each
  89  * @param {Function} callback The callback to execute for each matched element.
  90  * <pre>function callback(index, domElement) {
  91  *   this; // this == domElement
  92  * }
  93  * </pre>
  94  * @type jQuery
  95  * @since 1.0
  96  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
  97  */
  98 
  99 /**
 100  * The number of elements in the jQuery object.
 101  * The number of elements currently matched. The<a href='Core/size'>size</a> function will return the same value.
 102  * @code
 103  * $(document.body).click(function () {
 104  *       $(document.body).append($("<div>"));
 105  *       var n = $("div").length;
 106  *       $("span").text("There are " + n + " divs." +
 107  *                      "Click to add more.");
 108  *     }).trigger('click'); // trigger the click to start
 109  * @id jQuery.length
 110  * @type Number
 111  * @property
 112  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 113  */
 114 
 115 /**
 116  * Reduce the set of matched elements to a single element.
 117  * The position of the element in the set of matched elements starts at 0 and goes to length - 1.
 118  * @code
 119  * $("p").eq(1).css("color", "red")
 120  * @id jQuery.eq
 121  * @param {Number} position The index of the element to select.
 122  * @type jQuery
 123  * @since 1.0
 124  * @removed 1.2
 125  * @deprecated <a href='Traversing/slice'>slice</a>
 126  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 127  */
 128 
 129 /**
 130  * Access all matched DOM elements.
 131  * This serves as a backwards-compatible way of accessing all matched elements (other than the jQuery object itself, which is, in fact, an array of elements). It is useful if you need to operate on the DOM elements themselves instead of using built-in jQuery functions.
 132  * @code
 133  * function disp(divs) {
 134  *       var a = [];
 135  *       for (var i = 0; i < divs.length; i++) {
 136  *         a.push(divs[i].innerHTML);
 137  *       }
 138  *       $("span").text(a.join(" "));
 139  *     }
 140  *     
 141  *     disp( $("div").get().reverse() );
 142  * @id jQuery.get
 143  * @type Array<Element>
 144  * @since 1.0
 145  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 146  */
 147 
 148 /**
 149  * Access a single matched DOM element at a specified index in the matched set.
 150  * This allows you to extract the actual DOM element and operate on it directly without necessarily using jQuery functionality on it. This function called as $(this).get(0) is the equivalent of using square bracket notation on the jQuery object itself like $(this)[0].
 151  * @code
 152  * $("*", document.body).click(function (e) {
 153  *       e.stopPropagation();
 154  *       var domEl = $(this).get(0);
 155  *       $("span:first").text("Clicked on - " + domEl.tagName);
 156  *     });
 157  * @id jQuery.get
 158  * @param {Number} index Access the element in the Nth position.
 159  * @type Element
 160  * @since 1.0
 161  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 162  */
 163 
 164 /**
 165  * Searches every matched element for the object and returns the index of the element, if found, starting with zero.
 166  * Returns -1 if the object wasn't found.
 167  * @code
 168  * $("*").index( $('#bar')[0] )
 169  * @id jQuery.index
 170  * @param {Element } subject Object to search for.
 171  * @type Number
 172  * @since 1.0
 173  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 174  */
 175 
 176 /**
 177  * Returns value at named data store for the element, as set by data(name, value).
 178  * <p>If the jQuery collection references multiple elements, the value returned refers to the first element.</p><p>This function is used to get stored data on an element without the risk of a circular reference. It uses jQuery.data and is new to version 1.2.3. It can be used for many reasons and jQuery UI uses it heavily. </p>
 179  * @code
 180  * $("button").click(function(e) {
 181  *       var value;
 182  * 
 183  *       switch ($("button").index(this)) {
 184  *         case 0 :
 185  *           value = $("div").data("blah");
 186  *           break;
 187  *         case 1 :
 188  *           $("div").data("blah", "hello");
 189  *           value = "Stored!";
 190  *           break;
 191  *         case 2 :
 192  *           $("div").data("blah", 86);
 193  *           value = "Stored!";
 194  *           break;
 195  *         case 3 :
 196  *           $("div").removeData("blah");
 197  *           value = "Removed!";
 198  *           break;
 199  *       }
 200  * 
 201  *       $("span").text("" + value);
 202  *     });
 203  * @id jQuery.data
 204  * @param {String} name Name of the data stored.
 205  * @type Any
 206  * @since 1.2.3
 207  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 208  */
 209 
 210 /**
 211  * Stores the value in the named spot and also returns the value.
 212  * <p>If the jQuery collection references multiple elements, the data element is set on all of them.</p><p>This function can be useful for attaching data to elements without having to create a new expando. It also isn't limited to a string. The value can be any format.</p>
 213  * @code
 214  * $("div").data("test", { first: 16, last: "pizza!" });
 215  *     $("span:first").text($("div").data("test").first);
 216  *     $("span:last").text($("div").data("test").last);
 217  * @id jQuery.data
 218  * @param {String} name Name of the data to store.
 219  * @param {Any} value Value to be stored.
 220  * @type Any
 221  * @since 1.2.3
 222  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 223  */
 224 
 225 /**
 226  * Removes named data store from an element.
 227  * This is the complement function to $().data(name, value).
 228  * @code
 229  * $("span:eq(0)").text("" + $("div").data("test1"));
 230  *     $("div").data("test1", "VALUE-1");
 231  *     $("div").data("test2", "VALUE-2");
 232  *     $("span:eq(1)").text("" + $("div").data("test1"));
 233  *     $("div").removeData("test1");
 234  *     $("span:eq(2)").text("" + $("div").data("test1"));
 235  *     $("span:eq(3)").text("" + $("div").data("test2"));
 236  * @id jQuery.removeData
 237  * @param {String} name The name of the data store property to remove.
 238  * @type jQuery
 239  * @since 1.2.3
 240  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 241  */
 242 
 243 /**
 244  * Extends the jQuery element set to provide new methods (used to make a typical jQuery plugin).
 245  * Can be used to add functions into the to add<a href='Plugins/Authoring'>plugin methods (plugins)</a> .
 246  * @code
 247  * jQuery.fn.extend({
 248  *   check: function() {
 249  *     return this.each(function() { this.checked = true; });
 250  *   },
 251  *   uncheck: function() {
 252  *     return this.each(function() { this.checked = false; });
 253  *   }
 254  * });
 255  * @id jQuery.fn.extend
 256  * @param {Object} object The object that will be merged into the jQuery object.
 257  * @type jQuery
 258  * @since 1.0
 259  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 260  */
 261 
 262 /**
 263  * Extends the jQuery object itself.
 264  * Can be used to add functions into the jQuery namespace. See<a href='Core/jQuery.fn.extend'>jQuery.fn.extend</a> for more information on using this method to add<a href='Plugins/Authoring'>Plugins</a> .
 265  * @code
 266  * jQuery.extend({
 267  *   min: function(a, b) { return a < b ? a : b; },
 268  *   max: function(a, b) { return a > b ? a : b; }
 269  * });
 270  * @id jQuery.extend
 271  * @param {Object} object The object that will be merged into the jQuery object.
 272  * @type jQuery
 273  * @since 1.0
 274  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 275  */
 276 
 277 /**
 278  * Run this function to give control of the $ variable back to whichever library first implemented it.
 279  * This helps to make sure that jQuery doesn't conflict with the $ object of other libraries. By using this function, you will only be able to access jQuery using the 'jQuery' variable. For example, where you used to do $("div p"), you now must do jQuery("div p"). '''NOTE:''' This function must be called after including the jQuery javascript file, but '''before''' including any other conflicting library, and also before actually that other conflicting library gets used, in case jQuery is included last. noConflict can be called at the end of the jQuery.js file to globally disable the $() jQuery alias. jQuery.noConflict returns a reference to jQuery, so it can be used to override the $() alias of the jQuery object.
 280  * @code
 281  * var j = jQuery.noConflict();
 282  * // Do something with jQuery
 283  * j("div p").hide();
 284  * // Do something with another library's $()
 285  * $("content").style.display = 'none';
 286  * @id jQuery.noConflict
 287  * @type jQuery
 288  * @since 1.0
 289  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 290  */
 291 
 292 /**
 293  * Revert control of both the $ and jQuery variables to their original owners. '''Use with discretion.'''
 294  * This is a more-extreme version of the simple<a href='Core/jQuery.noConflict'>noConflict</a> method, as this one will completely undo what jQuery has introduced. This is to be used in an extreme case where you'd like to embed jQuery into a high-conflict environment. '''NOTE:''' It's very likely that plugins won't work after this particular method has been called.
 295  * @code
 296  * var dom = {};
 297  * dom.query = jQuery.noConflict(true);
 298  * @id jQuery.noConflict
 299  * @param {Boolean} extreme Set to true to enable the extreme rollback of jQuery and its variables.
 300  * @type jQuery
 301  * @since 1.1.4
 302  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 303  */
 304 
 305 /**
 306  * Access a property on the first matched element. This method makes it easy to retrieve a property value from the first matched element. If the element does not have an attribute with such a name, undefined is returned. Attributes include title, alt, src, href, width, style, etc.
 307  * 
 308  * @code
 309  * var title = $("em").attr("title");
 310  *     $("div").text(title);
 311  * @id jQuery.attr
 312  * @param {String} name The name of the property to access.
 313  * @type Object
 314  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 315  */
 316 
 317 /**
 318  * Set a key/value object as properties to all matched elements.
 319  * This serves as the best way to set a large number of properties on all matched elements. Note that you must use 'className' as key if you want to set the class-Attribute. Or use .addClass( class ) or .removeClass( class ). Keep in mind this recursively calls attr( key, value ) or attr ( key, fn ), so if one of the properties you are passing is a function, the function will be evaluated and not stored as the attribute itself.
 320  * @code
 321  * $("img").attr({ 
 322  *           src: "/images/hat.gif",
 323  *           title: "jQuery",
 324  *           alt: "jQuery Logo"
 325  *         });
 326  *     $("div").text($("img").attr("alt"));
 327  * @id jQuery.attr
 328  * @param {Map} properties Key/value pairs to set as object properties.
 329  * @type jQuery
 330  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 331  */
 332 
 333 /**
 334  * Set a single property to a value, on all matched elements.
 335  * 
 336  * @code
 337  * $("button:gt(1)").attr("disabled","disabled");
 338  * @id jQuery.attr
 339  * @param {String} key The name of the property to set.
 340  * @param {Object} value The value to set the property to.
 341  * @type jQuery
 342  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 343  */
 344 
 345 /**
 346  * Set a single property to a computed value, on all matched elements.
 347  * Instead of supplying a string value as described<a href='#keyvalue'>above</a> , a function is provided that computes the value.
 348  * @code
 349  * $("img").attr("src", function() { 
 350  *           return "/images/" + this.title; 
 351  *         });
 352  * @id jQuery.attr
 353  * @param {String} key The name of the property to set.
 354  * @param {Function} fn A function returning the value to set. Scope: Current element, argument: Index of current element
 355  * <pre>function callback(indexArray) {
 356  *   // indexArray == position in the jQuery object
 357  *   this; // dom element
 358  * }
 359  * </pre>
 360  * @type jQuery
 361  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 362  */
 363 
 364 /**
 365  * Remove an attribute from each of the matched elements.
 366  * 
 367  * @code
 368  * $("button").click(function () {
 369  *       $(this).next().removeAttr("disabled")
 370  *              .focus()
 371  *              .val("editable now");
 372  *     });
 373  * @id jQuery.removeAttr
 374  * @param {String} name The name of the property to remove.
 375  * @type jQuery
 376  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 377  */
 378 
 379 /**
 380  * Adds the specified class(es) to each of the set of matched elements.
 381  * 
 382  * @code
 383  * $("p:last").addClass("selected highlight");
 384  * @id jQuery.addClass
 385  * @param {String} class One or more classes to add to the elements, these are separated by spaces.
 386  * @type jQuery
 387  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 388  */
 389 
 390 /**
 391  * Returns true if the specified class is present on at least one of the set of matched elements.
 392  * 
 393  * @code
 394  * $("div#result1").append($("p:first").hasClass("selected").toString());
 395  * $("div#result2").append($("p:last").hasClass("selected").toString());
 396  * $("div#result3").append($("p").hasClass("selected").toString());
 397  * @id jQuery.hasClass
 398  * @param {String} class One CSS class name to be checked for.
 399  * @type Boolean
 400  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 401  */
 402 
 403 /**
 404  * Removes all or the specified class(es) from the set of matched elements.
 405  * 
 406  * @code
 407  * $("p:eq(1)").removeClass();
 408  * @id jQuery.removeClass
 409  * @param {String} class One or more CSS classes to remove from the elements, these are separated by spaces.
 410  * @type jQuery
 411  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 412  */
 413 
 414 /**
 415  * Adds the specified class if it is not present, removes the specified class if it is present.
 416  * 
 417  * @code
 418  * $("p").click(function () {
 419  *       $(this).toggleClass("highlight");
 420  *     });
 421  * @id jQuery.toggleClass
 422  * @param {String} class A CSS class to toggle on the elements.
 423  * @type jQuery
 424  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 425  */
 426 
 427 /**
 428  * Get the html contents (innerHTML) of the first matched element. This property is not available on XML documents (although it will work for XHTML documents).
 429  * 
 430  * @code
 431  * $("p").click(function () {
 432  *       var htmlStr = $(this).html();
 433  *       $(this).text(htmlStr);
 434  *     });
 435  * @id jQuery.html
 436  * @type String
 437  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 438  */
 439 
 440 /**
 441  * Set the html contents of every matched element. This property is not available on XML documents (although it will work for XHTML documents).
 442  * 
 443  * @code
 444  * $("div").html("<b>Wow!</b> Such excitement");
 445  *     $("div b").append(document.createTextNode("!!!"))
 446  *               .css("color", "red");
 447  * @id jQuery.html
 448  * @param {String} val Set the html contents to the specified value.
 449  * @type jQuery
 450  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 451  */
 452 
 453 /**
 454  * Get the combined text contents of all matched elements.
 455  * The result is a string that contains the combined text contents of all matched elements. This method works on both HTML and XML documents. Cannot be used on input elements. For input field text use the<a href='Attributes/val#val'>val attribute</a> .
 456  * @code
 457  * var str = $("p:first").text();
 458  *     $("p:last").html(str);
 459  * @id jQuery.text
 460  * @type String
 461  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 462  */
 463 
 464 /**
 465  * Set the text contents of all matched elements.
 466  * Similar to html(), but escapes HTML (replace "<" and ">" with their HTML entities). Cannot be used on input elements. For input field text use the<a href='Attributes/val#val'>val attribute</a> .
 467  * @code
 468  * $("p").text("<b>Some</b> new text.");
 469  * @id jQuery.text
 470  * @param {String} val The text value to set the contents of the element to.
 471  * @type jQuery
 472  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 473  */
 474 
 475 /**
 476  * Get the content of the value attribute of the first matched element.
 477  * In jQuery 1.2, a value is now returned for all elements, including selects. For multiple selects an array of values is returned. For older versions of jQuery use the [http://www.malsup.com/jquery/form/#fields fieldValue function of the Form Plugin]. For selects and checkboxes, see the<a href='Selectors/selected'>:selected</a> and<a href='Selectors/checked'>:checked</a> selectors.
 478  * @code
 479  * $("input").keyup(function () {
 480  *       var value = $(this).val();
 481  *       $("p").text(value);
 482  *     }).keyup();
 483  * @id jQuery.val
 484  * @type String|Array
 485  * @since 1.0
 486  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 487  */
 488 
 489 /**
 490  * Set the value attribute of every matched element.
 491  * In jQuery 1.2, this is also able to set the value of select elements, but selecting the appropriate options.
 492  * @code
 493  * $("button").click(function () {
 494  *       var text = $(this).text();
 495  *       $("input").val(text);
 496  *     });
 497  * @id jQuery.val
 498  * @param {String} val The value to set on the matched element.
 499  * @type jQuery
 500  * @since 1.0
 501  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 502  */
 503 
 504 /**
 505  * Checks, or selects, all the radio buttons, checkboxes, and select options that match the set of values.
 506  * 
 507  * @code
 508  * $("#single").val("Single2");
 509  *     $("#multiple").val(["Multiple2", "Multiple3"]);
 510  *     $("input").val(["check1","check2", "radio1" ]);
 511  * @id jQuery.val
 512  * @param {Array<String>} val The set of values to check/select.
 513  * @type jQuery
 514  * @since 1.2
 515  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 516  */
 517 
 518 /**
 519  * Reduce the set of matched elements to a single element.
 520  * Argument is the position of the element in the set of matched elements, starting at 0 and going to length - 1. Since the query filters out all elements that do not match the given index, providing an invalid index returns an empty set of elements rather than null.
 521  * @code
 522  * $("div").eq(2).addClass("blue");
 523  * @id jQuery.eq
 524  * @param {Integer} index The index of the element in the jQuery object.
 525  * @type jQuery
 526  * @since 1.1.2
 527  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 528  */
 529 
 530 /**
 531  * Checks the current selection against a class and returns true, if at least one element of the selection has the given class.
 532  * This is an alternative to is("." + class).
 533  * @code
 534  * $("div").click(function(){
 535  *       if ( $(this).hasClass("protected") )
 536  *         $(this).animate({ left: -10 }, 75)
 537  *                .animate({ left: 10 }, 75)
 538  *                .animate({ left: -10 }, 75)
 539  *                .animate({ left: 10 }, 75)
 540  *                .animate({ left: 0 }, 75);
 541  *     });
 542  * @id jQuery.hasClass
 543  * @param {String} class The class to match.
 544  * @type Boolean
 545  * @since 1.2
 546  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 547  */
 548 
 549 /**
 550  * Removes all elements from the set of matched elements that do not match the specified expression(s).
 551  * This method is used to narrow down the results of a search. Provide a comma-separated list of expressions to apply multiple filters at once.
 552  * @code
 553  * $("p").filter(".selected, :first")
 554  * @id jQuery.filter
 555  * @param {Expression} expr An expression to pass into the filter
 556  * @type jQuery
 557  * @since 1.0
 558  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 559  */
 560 
 561 /**
 562  * Removes all elements from the set of matched elements that do not match the specified function.
 563  * The function is called with a context equal to the current element (just like<a href='Core/each'>$.each</a> ). If the function returns false, then the element is removed - anything else and the element is kept.
 564  * @code
 565  * $("p").filter(function(index) {
 566  *    return $("ol", this).length == 0;
 567  *  });
 568  * @id jQuery.filter
 569  * @param {Function} fn A function to pass into the filter
 570  * <pre>function callback(indexInJQueryObject) {
 571  *   var keepItBoolean = true;
 572  * 
 573  *   this; // dom element
 574  * 
 575  *   return keepItBoolean;
 576  * }
 577  * </pre>
 578  * @type jQuery
 579  * @since 1.0
 580  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 581  */
 582 
 583 /**
 584  * Checks the current selection against an expression and returns true, if at least one element of the selection fits the given expression.
 585  * If no element fits, or the expression is not valid, then the response will be 'false'. '''Note''': Only ''simple'' expressions are supported. Complex expressions, such as those containing hierarchy selectors (such as +, ~, and >) will always return 'true'.<a href='Traversing/filter'>filter</a> is used internally, therefore all rules that apply there apply here, as well.
 586  * @code
 587  * var isFormParent = $("input[@type='checkbox']").parent().is("form")
 588  *     $("div").text("isFormParent = " + isFormParent);
 589  * @id jQuery.is
 590  * @param {String} expr The expression with which to filter
 591  * @type Boolean
 592  * @since 1.0
 593  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 594  */
 595 
 596 /**
 597  * Translate a set of elements in the jQuery object into another set of values in an array (which may, or may not, be elements).
 598  * You could use this to build lists of values, attributes, css values - or even perform special, custom, selector transformations. This is provided as a convenience method for using<a href='Utilities/jQuery.map'>$.map()</a> .
 599  * @code
 600  * var mappedItems = $("li").map(function (index) {
 601  *       var replacement = $("<li>").text($(this).text()).get(0);
 602  *       if (index == 0) {
 603  *         // make the first item all caps
 604  *         $(replacement).text($(replacement).text().toUpperCase());
 605  *       } else if (index == 1 || index == 3) {
 606  *         // delete the second and fourth items
 607  *         replacement = null;
 608  *       } else if (index == 2) {
 609  *         // make two of the third item and add some text
 610  *         replacement = [replacement,$("<li>").get(0)];
 611  *         $(replacement[0]).append("<b> - A</b>");
 612  *         $(replacement[1]).append("Extra <b> - B</b>");
 613  *       }
 614  * 
 615  *       // replacment will be an dom element, null, 
 616  *       // or an array of dom elements
 617  *       return replacement;
 618  *     });
 619  *     $("#results").append(mappedItems);
 620  * @id jQuery.map
 621  * @param {Function} callback The function to execute on each element in the set.
 622  * <pre>function callback(index, domElement) {
 623  *   var replacement;
 624  * 
 625  *   this; // also dom element
 626  * 
 627  *   // replacement == null : delete spot
 628  *   // replacement == array : insert the elements of the array
 629  *   // else replace the spot with replacement
 630  *   return replacement;
 631  * }
 632  * </pre>
 633  * @type jQuery
 634  * @since 1.2
 635  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 636  */
 637 
 638 /**
 639  * Removes elements matching the specified expression from the set of matched elements.
 640  * 
 641  * @code
 642  * $("p").not($("div p.selected"))
 643  * @id jQuery.not
 644  * @param {String, DOMElement, Array<DOMElement>} expr An expression with which to remove matching elements, an element to remove from the set or a set of elements to remove from the jQuery set of matched elements.
 645  * @type jQuery
 646  * @since 1.0
 647  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 648  */
 649 
 650 /**
 651  * Selects a subset of the matched elements.
 652  * Behaves exactly like the built-in Array slice method.
 653  * @code
 654  * $("p").slice(-1).wrapInner("<b></b>");
 655  * @id jQuery.slice
 656  * @param {Integer} start Where to start the subset. The first element is at zero. Can be negative to start from the end of the selection.
 657  * @param {Integer} end Where to end the subset (does not include the end element itself). If unspecified, ends at the end of the selection.
 658  * @type jQuery
 659  * @since 1.1.4
 660  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 661  */
 662 
 663 /**
 664  * Adds more elements, matched by the given expression, to the set of matched elements.
 665  * 
 666  * @code
 667  * $("p").add(document.getElementById("a")).css("background", "yellow");
 668  * @id jQuery.add
 669  * @param {String, DOMElement, Array<DOMElement>} expr An expression whose matched elements are added for String, a string of HTML to create on the fly for DOMElement or one or more Elements to add if an Array.
 670  * @type jQuery
 671  * @since 1.0
 672  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 673  */
 674 
 675 /**
 676  * Get a set of elements containing all of the unique immediate children of each of the matched set of elements.
 677  * This set can be filtered with an optional expression that will cause only elements matching the selector to be collected. Also note: while parents() will look at all ancestors, children() will only consider immediate child elements.
 678  * @code
 679  * $("div").children(".selected").css("color", "blue");
 680  * @id jQuery.children
 681  * @param {String} expr An expression to filter the child Elements with.
 682  * @type jQuery
 683  * @since 1.0
 684  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 685  */
 686 
 687 /**
 688  * Find all the child nodes inside the matched elements (including text nodes), or the content document, if the element is an iframe.
 689  * 
 690  * @code
 691  * $("iframe").contents().find("body").append("I'm in an iframe!");
 692  * @id jQuery.contents
 693  * @type jQuery
 694  * @since 1.2
 695  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 696  */
 697 
 698 /**
 699  * Searches for all elements that match the specified<a href='Selectors'>expression</a> . This method is a good way to find additional descendant elements with which to process.
 700  * All searching is done using a<a href='Selectors'>jQuery expression</a> . The expression can be written using CSS 1-3 Selector syntax.
 701  * @code
 702  * var newText = $("p").text().split(" ").join("</span> <span>");
 703  *     newText = "<span>" + newText + "</span>";
 704  * 
 705  *     $("p").html(newText)
 706  *           .find("span")
 707  *             .hover(function () { $(this).addClass("hilite"); },
 708  *                    function () { $(this).removeClass("hilite"); })
 709  *           .end()
 710  *           .find(":contains('t')")
 711  *             .css({"font-style":"italic", "font-weight":"bolder"});
 712  * @id jQuery.find
 713  * @param {String} expr An expression to search with.
 714  * @type jQuery
 715  * @since 1.0
 716  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 717  */
 718 
 719 /**
 720  * Get a set of elements containing the unique next siblings of each of the given set of elements.
 721  * next only returns the very next sibling for each element, not all next siblings (see nextAll). You may provide an optional expression to filter the returned set.
 722  * @code
 723  * $("p").next(".selected").css("background", "yellow");
 724  * @id jQuery.next
 725  * @param {String} expr An expression with which to filter the returned set.
 726  * @type jQuery
 727  * @since 1.0
 728  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 729  */
 730 
 731 /**
 732  * Find all sibling elements after the current element.
 733  * Use an optional expression to filter the matched set.
 734  * @code
 735  * $(":nth-child(1)").nextAll("p").addClass("after");
 736  * @id jQuery.nextAll
 737  * @param {String} expr An expression to filter the next Elements with.
 738  * @type jQuery
 739  * @since 1.2
 740  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 741  */
 742 
 743 /**
 744  * Returns a jQuery collection with the positioned parent of the first matched element.
 745  * This is the first parent of the element that has position (as in relative or absolute). This method only works with visible elements.
 746  * @id jQuery.offsetParent
 747  * @type jQuery
 748  * @since 1.26
 749  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 750  */
 751 
 752 /**
 753  * Get a set of elements containing the unique parents of the matched set of elements.
 754  * You may use an optional expression to filter the set of parent elements that will match.
 755  * @code
 756  * $("p").parent(".selected").css("background", "yellow");
 757  * @id jQuery.parent
 758  * @param {String} expr An expression to filter the parents with.
 759  * @type jQuery
 760  * @since 1.0
 761  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 762  */
 763 
 764 /**
 765  * Get a set of elements containing the unique ancestors of the matched set of elements (except for the root element). The matched elements can be filtered with an optional expression.
 766  * 
 767  * @code
 768  * function showParents() {
 769  *       $("div").css("border-color", "white");
 770  *       var len = $("span.selected")
 771  *                        .parents("div")
 772  *                        .css("border", "2px red solid")
 773  *                        .length;
 774  *       $("b").text("Unique div parents: " + len);
 775  *     }
 776  *     $("span").click(function () {
 777  *       $(this).toggleClass("selected");
 778  *       showParents();
 779  *     });
 780  * @id jQuery.parents
 781  * @param {String} expr An expression to filter the ancestors with
 782  * @type jQuery
 783  * @since 1.0
 784  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 785  */
 786 
 787 /**
 788  * Get a set of elements containing the unique previous siblings of each of the matched set of elements.
 789  * Use an optional expression to filter the matched set. Only the immediately previous sibling is returned, not all previous siblings.
 790  * @code
 791  * $("p").prev(".selected").css("background", "yellow");
 792  * @id jQuery.prev
 793  * @param {String} expr An expression to filter the previous Elements with.
 794  * @type jQuery
 795  * @since 1.0
 796  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 797  */
 798 
 799 /**
 800  * Find all sibling elements in front of the current element.
 801  * Use an optional expression to filter the matched set.
 802  * @code
 803  * $("div:last").prevAll().addClass("before");
 804  * @id jQuery.prevAll
 805  * @param {String} expr An expression to filter the previous elements with.
 806  * @type jQuery
 807  * @since 1.2
 808  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 809  */
 810 
 811 /**
 812  * Get a set of elements containing all of the unique siblings of each of the matched set of elements. Can be filtered with an optional expressions.
 813  * 
 814  * @code
 815  * $("p").siblings(".selected").css("background", "yellow");
 816  * @id jQuery.siblings
 817  * @param {String} expr An expression to filter the sibling Elements with
 818  * @type jQuery
 819  * @since 1.0
 820  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 821  */
 822 
 823 /**
 824  * Add the previous selection to the current selection.
 825  * Useful for traversing elements, and then adding something that was matched before the last traversal.
 826  * @code
 827  * $("div").find("p").andSelf().addClass("border");
 828  *     $("div").find("p").addClass("background");
 829  * @id jQuery.andSelf
 830  * @type jQuery
 831  * @since 1.2
 832  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 833  */
 834 
 835 /**
 836  * Revert the most recent 'destructive' operation, changing the set of matched elements to its previous state (right before the destructive operation).
 837  * If there was no destructive operation before, an empty set is returned. A 'destructive' operation is any operation that changes the set of matched jQuery elements, which means any Traversing function that returns a jQuery object - including<a href='Traversing/add'>add</a> ,<a href='Traversing/andSelf'>andSelf</a> ,<a href='Traversing/children'>children</a> ,<a href='Traversing/filter'>filter</a> ,<a href='Traversing/find'>find</a> ,<a href='Traversing/map'>map</a> ,<a href='Traversing/next'>next</a> ,<a href='Traversing/nextAll'>nextAll</a> ,<a href='Traversing/not'>not</a> ,<a href='Traversing/parent'>parent</a> ,<a href='Traversing/parents'>parents</a> ,<a href='Traversing/prev'>prev</a> ,<a href='Traversing/prevAll'>prevAll</a> ,<a href='Traversing/siblings'>siblings</a> and<a href='Traversing/slice'>slice</a> - plus the<a href='Manipulation/clone'>clone</a> function (from Manipulation).
 838  * @code
 839  * $("p").find("span").end().css("border", "2px red solid");
 840  * @id jQuery.end
 841  * @type jQuery
 842  * @since 1.0
 843  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 844  */
 845 
 846 /**
 847  * Get the html contents (innerHTML) of the first matched element. This property is not available on XML documents (although it will work for XHTML documents).
 848  * 
 849  * @code
 850  * $("p").click(function () {
 851  *       var htmlStr = $(this).html();
 852  *       $(this).text(htmlStr);
 853  *     });
 854  * @id jQuery.html
 855  * @type String
 856  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 857  */
 858 
 859 /**
 860  * Set the html contents of every matched element. This property is not available on XML documents (although it will work for XHTML documents).
 861  * 
 862  * @code
 863  * $("div").html("<b>Wow!</b> Such excitement");
 864  *     $("div b").append(document.createTextNode("!!!"))
 865  *               .css("color", "red");
 866  * @id jQuery.html
 867  * @param {String} val Set the html contents to the specified value.
 868  * @type jQuery
 869  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 870  */
 871 
 872 /**
 873  * Get the combined text contents of all matched elements.
 874  * The result is a string that contains the combined text contents of all matched elements. This method works on both HTML and XML documents. Cannot be used on input elements. For input field text use the<a href='Attributes/val#val'>val attribute</a> .
 875  * @code
 876  * var str = $("p:first").text();
 877  *     $("p:last").html(str);
 878  * @id jQuery.text
 879  * @type String
 880  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 881  */
 882 
 883 /**
 884  * Set the text contents of all matched elements.
 885  * Similar to html(), but escapes HTML (replace "<" and ">" with their HTML entities). Cannot be used on input elements. For input field text use the<a href='Attributes/val#val'>val attribute</a> .
 886  * @code
 887  * $("p").text("<b>Some</b> new text.");
 888  * @id jQuery.text
 889  * @param {String} val The text value to set the contents of the element to.
 890  * @type jQuery
 891  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 892  */
 893 
 894 /**
 895  * Append content to the inside of every matched element.
 896  * This operation is similar to doing an appendChild to all the specified elements, adding them into the document.
 897  * @code
 898  * $("p").append( $("b") );
 899  * @id jQuery.append
 900  * @param {String, Element, jQuery} content Content to append to the target.
 901  * @type jQuery
 902  * @since 1.0
 903  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 904  */
 905 
 906 /**
 907  * Append all of the matched elements to another, specified, set of elements.
 908  * This operation is, essentially, the reverse of doing a regular $(A).append(B), in that instead of appending B to A, you're appending A to B.
 909  * @code
 910  * $("span").appendTo("#foo"); // check append() examples
 911  * @id jQuery.appendTo
 912  * @param {String} content target to which the content will be appended.
 913  * @type jQuery
 914  * @since 1.0
 915  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 916  */
 917 
 918 /**
 919  * Prepend content to the inside of every matched element.
 920  * This operation is the best way to insert elements inside, at the beginning, of all matched elements.
 921  * @code
 922  * $("p").prepend( $("b") );
 923  * @id jQuery.prepend
 924  * @param {String, Element, jQuery} content Content to prepend to the target.
 925  * @type jQuery
 926  * @since 1.0
 927  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 928  */
 929 
 930 /**
 931  * Prepend all of the matched elements to another, specified, set of elements.
 932  * This operation is, essentially, the reverse of doing a regular $(A).prepend(B), in that instead of prepending B to A, you're prepending A to B.
 933  * @code
 934  * $("span").prependTo("#foo"); // check prepend() examples
 935  * @id jQuery.prependTo
 936  * @param {String} content target to which the content will be prepended.
 937  * @type jQuery
 938  * @since 1.0
 939  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 940  */
 941 
 942 /**
 943  * Insert content after each of the matched elements.
 944  * 
 945  * @code
 946  * $("p").after( $("b") );
 947  * @id jQuery.after
 948  * @param {String, Element, jQuery} content Content to insert after each target.
 949  * @type jQuery
 950  * @since 1.0
 951  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 952  */
 953 
 954 /**
 955  * Insert content before each of the matched elements.
 956  * 
 957  * @code
 958  * $("p").before( $("b") );
 959  * @id jQuery.before
 960  * @param {String, Element, jQuery} content Content to insert before each target.
 961  * @type jQuery
 962  * @since 1.0
 963  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 964  */
 965 
 966 /**
 967  * Insert all of the matched elements after another, specified, set of elements.
 968  * This operation is, essentially, the reverse of doing a regular $(A).after(B), in that instead of inserting B after A, you're inserting A after B.
 969  * @code
 970  * $("p").insertAfter("#foo"); // check after() examples
 971  * @id jQuery.insertAfter
 972  * @param {String} content Content after which the selected element(s) is inserted.
 973  * @type jQuery
 974  * @since 1.0
 975  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 976  */
 977 
 978 /**
 979  * Insert all of the matched elements before another, specified, set of elements.
 980  * This operation is, essentially, the reverse of doing a regular $(A).before(B), in that instead of inserting B before A, you're inserting A before B.
 981  * @code
 982  * $("p").insertBefore("#foo"); // check before() examples
 983  * @id jQuery.insertBefore
 984  * @param {String} content Content after which the selected element(s) is inserted.
 985  * @type jQuery
 986  * @since 1.0
 987  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 988  */
 989 
 990 /**
 991  * Wrap each matched element with the specified HTML content.
 992  * This wrapping process is most useful for injecting additional structure into a document, without ruining the original semantic qualities of a document. This works by going through the first element provided (which is generated, on the fly, from the provided HTML) and finds the deepest descendant element within its structure -- it is that element that will enwrap everything else.
 993  * @code
 994  * $("span").wrap("<div><div><p><em><b></b></em></p></div></div>");
 995  * @id jQuery.wrap
 996  * @param {String} html A string of HTML that will be created on the fly and wrapped around each target.
 997  * @type jQuery
 998  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
 999  */
1000 
1001 /**
1002  * Wrap each matched element with the specified element.
1003  * 
1004  * @code
1005  * $("p").wrap($(".doublediv"));
1006  * @id jQuery.wrap
1007  * @param {Element} elem A DOM element that will be wrapped around each target.
1008  * @type jQuery
1009  * @since 1.0
1010  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1011  */
1012 
1013 /**
1014  * Wrap all the elements in the matched set into a single wrapper element.
1015  * This is different from<a href='Manipulation/wrap'>.wrap()</a> where each element in the matched set would get wrapped with an element. This wrapping process is most useful for injecting additional structure into a document, without ruining the original semantic qualities of a document. This works by going through the first element provided (which is generated, on the fly, from the provided HTML) and finds the deepest descendant element within its structure -- it is that element that will enwrap everything else.
1016  * @code
1017  * $("span").wrapAll("<div><div><p><em><b></b></em></p></div></div>");
1018  * @id jQuery.wrapAll
1019  * @param {String} html A string of HTML that will be created on the fly and wrapped around the target.
1020  * @type jQuery
1021  * @since 1.2
1022  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1023  */
1024 
1025 /**
1026  * Wrap all the elements in the matched set into a single wrapper element.
1027  * This is different from<a href='Manipulation/wrap'>.wrap()</a> where each element in the matched set would get wrapped with an element.
1028  * @code
1029  * $("p").wrapAll($(".doublediv"));
1030  * @id jQuery.wrapAll
1031  * @param {Element} elem A DOM element that will be wrapped around the target.
1032  * @type jQuery
1033  * @since 1.2
1034  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1035  */
1036 
1037 /**
1038  * Wrap the inner child contents of each matched element (including text nodes) with an HTML structure.
1039  * This wrapping process is most useful for injecting additional structure into a document, without ruining the original semantic qualities of a document. This works by going through the first element provided (which is generated, on the fly, from the provided HTML) and finds the deepest ancestor element within its structure -- it is that element that will enwrap everything else.
1040  * @code
1041  * $("body").wrapInner("<div><div><p><em><b></b></em></p></div></div>");
1042  * @id jQuery.wrapInner
1043  * @param {String} html A string of HTML that will be created on the fly and wrapped around the target.
1044  * @type jQuery
1045  * @since 1.2
1046  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1047  */
1048 
1049 /**
1050  * Wrap the inner child contents of each matched element (including text nodes) with a DOM element.
1051  * 
1052  * @code
1053  * $("p").wrapInner($("<span class='red'></span>"));
1054  * @id jQuery.wrapInner
1055  * @param {Element} elem A DOM element that will be wrapped around the target.
1056  * @type jQuery
1057  * @since 1.2
1058  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1059  */
1060 
1061 /**
1062  * Replaces all matched elements with the specified HTML or DOM elements. This returns the JQuery element that was just replaced, which has been removed from the DOM.
1063  * 
1064  * @code
1065  * $("p").click(function () {
1066  *       $(this).replaceWith($("div"));
1067  *     });
1068  * @id jQuery.replaceWith
1069  * @param {String, Element, jQuery} content Content to replace the matched elements with.
1070  * @type jQuery
1071  * @since 1.2
1072  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1073  */
1074 
1075 /**
1076  * Replaces the elements matched by the specified selector with the matched elements.
1077  * This function is the complement to replaceWith() which does the same task with the parameters reversed.
1078  * @code
1079  * $("<b>Paragraph. </b>").replaceAll("p"); // check replaceWith() examples
1080  * @id jQuery.replaceAll
1081  * @param {Selector} selector The elements to find and replace the matched elements with.
1082  * @type jQuery
1083  * @since 1.2
1084  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1085  */
1086 
1087 /**
1088  * Remove all child nodes from the set of matched elements.
1089  * Note that this function starting with 1.2.2 will also remove all event handlers and internally cached data.
1090  * @code
1091  * $("button").click(function () {
1092  *       $("p").empty();
1093  *     });
1094  * @id jQuery.empty
1095  * @type jQuery
1096  * @since 1.0
1097  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1098  */
1099 
1100 /**
1101  * Removes all matched elements from the DOM.
1102  * This does NOT remove them from the jQuery object, allowing you to use the matched elements further. Note that this function starting with 1.2.2 will also remove all event handlers and internally cached data. So: <code> $("#foo").remove().appendTo("#bar"); </code> should be written as <code> $("#foo").appendTo("#bar"); </code> to avoid losing the event handlers. Can be filtered with an optional expression.
1103  * @code
1104  * $("button").click(function () {
1105  *       $("p").remove(":contains('Hello')");
1106  *     });
1107  * @id jQuery.remove
1108  * @param {String} expr A jQuery expression to filter the set of elements to be removed.
1109  * @type jQuery
1110  * @since 1.0
1111  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1112  */
1113 
1114 /**
1115  * Clone matched DOM Elements and select the clones.
1116  * This is useful for moving copies of the elements to another location in the DOM.
1117  * @code
1118  * $("b").clone().prependTo("p");
1119  * @id jQuery.clone
1120  * @type jQuery
1121  * @since 1.0
1122  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1123  */
1124 
1125 /**
1126  * Clone matched DOM Elements, and all their event handlers, and select the clones.
1127  * This is useful for moving copies of the elements, and their events, to another location in the DOM.
1128  * @code
1129  * $("button").click(function(){
1130  *       $(this).clone(true).insertAfter(this);
1131  *     });
1132  * @id jQuery.clone
1133  * @param {Boolean} true Set to true to enable cloning of event handlers.
1134  * @type jQuery
1135  * @since 1.0
1136  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1137  */
1138 
1139 /**
1140  * Return a style property on the first matched element.
1141  * 
1142  * @code
1143  * $("div").click(function () {
1144  *       var color = $(this).css("background-color");
1145  *       $("#result").html("That div is <span style='color:" +
1146  *                          color + ";'>" + color + "</span>.");
1147  *     });
1148  * @id jQuery.css
1149  * @param {String} name The name of the property to access.
1150  * @type String
1151  * @since 1.0
1152  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1153  */
1154 
1155 /**
1156  * Set a key/value object as style properties to all matched elements.
1157  * This is the best way to set several style properties on all matched elements.
1158  * @code
1159  * $("p").hover(function () {
1160  *       $(this).css({ "background-color":"yellow", "font-weight":"bolder" });
1161  *     }, function () {
1162  *       var cssObj = {
1163  *         "background-color": "#ddd",
1164  *         "font-weight": "",
1165  *         color: "#0028f4"
1166  *       }
1167  *       $(this).css(cssObj);
1168  *     });
1169  * @id jQuery.css
1170  * @param {Map} properties Key/value pairs to set as style properties.
1171  * @type jQuery
1172  * @since 1.0
1173  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1174  */
1175 
1176 /**
1177  * Set a single style property to a value on all matched elements.
1178  * If a number is provided, it is automatically converted into a pixel value.
1179  * @code
1180  * var words = $("p:first").text().split(" ");
1181  *     var text = words.join("</span> <span>");
1182  *     $("p:first").html("<span>" + text + "</span>");
1183  *     $("span").click(function () {
1184  *       $(this).css("background-color","yellow");
1185  *     });
1186  * @id jQuery.css
1187  * @param {String} name The name of the property to set.
1188  * @param {String, Number} value The value to set the property to.
1189  * @type jQuery
1190  * @since 1.0
1191  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1192  */
1193 
1194 /**
1195  * Get the current offset of the first matched element relative to the viewport.
1196  * The returned object contains two<a href='Types#Integer'>Integer</a> properties, top and left. The method works only with visible elements.
1197  * @code
1198  * $("*", document.body).click(function (e) {
1199  *       var offset = $(this).offset();
1200  *       e.stopPropagation();
1201  *       $("#result").text(this.tagName + " coords ( " + offset.left + ", " +
1202  *                                       offset.top + " )");
1203  *     });
1204  * @id jQuery.offset
1205  * @type Object{top|left}
1206  * @since 1.2
1207  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1208  */
1209 
1210 /**
1211  * Gets the top and left position of an element relative to its offset parent.
1212  * The returned object contains two<a href='Types#Integer'>Integer</a> properties, top and left. For accurate calculations make sure to use pixel values for margins, borders and padding. This method only works with visible elements.
1213  * @code
1214  * var p = $("p:first");
1215  * var position = p.position();
1216  * $("p:last").text( "left: " + position.left + ", top: " + position.top );
1217  * @id jQuery.position
1218  * @type Object{top|left}
1219  * @since 1.2
1220  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1221  */
1222 
1223 /**
1224  * Gets the scroll top offset of the first matched element.
1225  * This method works for both visible and hidden elements.
1226  * @code
1227  * var p = $("p:first");
1228  * $("p:last").text( "scrollTop:" + p.scrollTop() );
1229  * @id jQuery.scrollTop
1230  * @type Integer
1231  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1232  */
1233 
1234 /**
1235  * When a value is passed in, the scroll top offset is set to that value on all matched elements.
1236  * This method works for both visible and hidden elements.
1237  * @code
1238  * $("div.demo").scrollTop(300);
1239  * @id jQuery.scrollTop
1240  * @param {Number} val A positive number representing the desired scroll top offset.
1241  * @type jQuery
1242  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1243  */
1244 
1245 /**
1246  * Gets the scroll left offset of the first matched element.
1247  * This method works for both visible and hidden elements.
1248  * @code
1249  * var p = $("p:first");
1250  * $("p:last").text( "scrollLeft:" + p.scrollLeft() );
1251  * @id jQuery.scrollLeft
1252  * @type Integer
1253  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1254  */
1255 
1256 /**
1257  * When a value is passed in, the scroll left offset is set to that value on all matched elements.
1258  * This method works for both visible and hidden elements.
1259  * @code
1260  * $("div.demo").scrollLeft(300);
1261  * @id jQuery.scrollLeft
1262  * @param {Number} val A positive number representing the desired scroll left offset.
1263  * @type jQuery
1264  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1265  */
1266 
1267 /**
1268  * Get the current computed, pixel, height of the first matched element.
1269  * In jQuery 1.2, this method is able to find the height of the window and document.
1270  * @code
1271  * function showHeight(ele, h) {
1272  *       $("div").text("The height for the " + ele + 
1273  *                     " is " + h + "px.");
1274  *     }
1275  *     $("#getp").click(function () { 
1276  *       showHeight("paragraph", $("p").height()); 
1277  *     });
1278  *     $("#getd").click(function () { 
1279  *       showHeight("document", $(document).height()); 
1280  *     });
1281  *     $("#getw").click(function () { 
1282  *       showHeight("window", $(window).height()); 
1283  *     });
1284  * @id jQuery.height
1285  * @type Integer
1286  * @since 1.0
1287  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1288  */
1289 
1290 /**
1291  * Set the CSS height of every matched element.
1292  * If no explicit unit was specified (like 'em' or '%') then "px" is concatenated to the value.
1293  * @code
1294  * $("div").one('click', function () {
1295  *       $(this).height(30)
1296  *              .css({cursor:"auto", backgroundColor:"green"});
1297  *     });
1298  * @id jQuery.height
1299  * @param {String, Number} val Set the CSS 'height' property to the specified value.
1300  * @type jQuery
1301  * @since 1.0
1302  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1303  */
1304 
1305 /**
1306  * Get the current computed, pixel, width of the first matched element.
1307  * In jQuery 1.2, this method is able to find the width of the window and document.
1308  * @code
1309  * function showWidth(ele, w) {
1310  *       $("div").text("The width for the " + ele + 
1311  *                     " is " + w + "px.");
1312  *     }
1313  *     $("#getp").click(function () { 
1314  *       showWidth("paragraph", $("p").width()); 
1315  *     });
1316  *     $("#getd").click(function () { 
1317  *       showWidth("document", $(document).width()); 
1318  *     });
1319  *     $("#getw").click(function () { 
1320  *       showWidth("window", $(window).width()); 
1321  *     });
1322  * @id jQuery.width
1323  * @type Integer
1324  * @since 1.0
1325  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1326  */
1327 
1328 /**
1329  * Set the CSS width of every matched element.
1330  * If no explicit unit was specified (like 'em' or '%') then "px" is concatenated to the value.
1331  * @code
1332  * $("div").one('click', function () {
1333  *       $(this).width(30)
1334  *              .css({cursor:"auto", "background-color":"blue"});
1335  *     });
1336  * @id jQuery.width
1337  * @param {String, Number} val Set the CSS 'width' property to the specified value.
1338  * @type jQuery
1339  * @since 1.0
1340  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1341  */
1342 
1343 /**
1344  * Gets the inner height (excludes the border and includes the padding) for the first matched element.
1345  * This method works for both visible and hidden elements.
1346  * @code
1347  * var p = $("p:first");
1348  * $("p:last").text( "innerHeight:" + p.innerHeight() );
1349  * @id jQuery.innerHeight
1350  * @type Integer
1351  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1352  */
1353 
1354 /**
1355  * Gets the inner width (excludes the border and includes the padding) for the first matched element.
1356  * This method works for both visible and hidden elements.
1357  * @code
1358  * var p = $("p:first");
1359  * $("p:last").text( "innerWidth:" + p.innerWidth() );
1360  * @id jQuery.innerWidth
1361  * @type Integer
1362  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1363  */
1364 
1365 /**
1366  * Gets the offsetHeight (includes the border and padding by default) for the first matched element.
1367  * This method works for both visible and hidden elements.
1368  * @code
1369  * var p = $("p:first");
1370  * $("p:last").text( "outerHeight:" + p.outerHeight() + " , outerHeight(true):" + p.outerHeight(true) );
1371  * @id jQuery.outerHeight
1372  * @param {Options} options A set of key/value pairs that configure the outerHeight method. All options are optional.
1373  * @type Integer
1374  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1375  */
1376 
1377 /**
1378  * Get the outer width (includes the border and padding by default) for the first matched element.
1379  * This method works for both visible and hidden elements. The margin can be included by passing an options map with margin set to true.
1380  * @code
1381  * var p = $("p:first");
1382  * $("p:last").text( "outerWidth:" + p.outerWidth()+ " , outerWidth(true):" + p.outerWidth(true) );
1383  * @id jQuery.outerWidth
1384  * @param {Options} options A set of key/value pairs that configure the outerWidth method. All options are optional.
1385  * @type Integer
1386  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1387  */
1388 
1389 /**
1390  * Binds a function to be executed whenever the DOM is ready to be traversed and manipulated.
1391  * <p>This is probably the most important function included in the event module, as it can greatly improve the response times of your web applications.</p><p>In a nutshell, this is a solid replacement for using window.onload, and attaching a function to that. By using this method, your bound function will be called the instant the DOM is ready to be read and manipulated, which is when what 99.99% of all JavaScript code needs to run.</p><p>There is one argument passed to the ready event handler: A reference to the jQuery function. You can name that argument whatever you like, and can therefore stick with the $ alias without risk of naming collisions.</p><p>Please ensure you have no code in your <body> onload event handler, otherwise $(document).ready() may not fire.</p><p>You can have as many $(document).ready events on your page as you like. The functions are then executed in the order they were added.</p>
1392  * @code
1393  * $(function() {
1394  *   // Your code here
1395  * });
1396  * @id jQuery.ready
1397  * @param {Function} fn The function to be executed when the DOM is ready.
1398  * <pre>function callback(jQueryReference) {
1399  *   this; // document
1400  * }
1401  * </pre>
1402  * @type jQuery
1403  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1404  */
1405 
1406 /**
1407  * Binds a handler to one or more events (like click) for each matched element. Can also bind custom events.
1408  * '''Possible event values:''' <code>blur</code>, <code>focus</code>, <code>load</code>, <code>resize</code>, <code>scroll</code>, <code>unload</code>, <code>click</code>, <code>dblclick</code>, <code> mousedown</code>, <code>mouseup</code>, <code>mousemove</code>, <code>mouseover</code>, <code>mouseout</code>, <code>mouseenter</code>, <code>mouseleave</code>, <code>change</code>, <code>select</code>, <code> submit</code>, <code>keydown</code>, <code>keypress</code>, <code>keyup</code>, <code>error</code> The event handler is passed an event object that you can use to prevent default behaviour. To stop both default action and event bubbling, your handler has to return false. Note that this will prevent handlers on parent elements from running but not other jQuery handlers on the same element. In most cases, you can define your event handlers as anonymous functions (see first example). In cases where that is not possible, you can pass additional data as the second parameter (and the handler function as the third), see second example.
1409  * @code
1410  * $("p").bind("myCustomEvent", function(e, myName, myValue){
1411  *       $(this).text(myName + ", hi there!");
1412  *       $("span").stop().css("opacity", 1)
1413  *                .text("myName = " + myName)
1414  *                .fadeIn(30).fadeOut(1000);
1415  *     });
1416  *     $("button").click(function () {
1417  *       $("p").trigger("myCustomEvent", [ "John" ]);
1418  *     });
1419  * @id jQuery.bind
1420  * @param {String} type One or more event types separated by a space
1421  * @param {Object} data Additional data passed to the event handler as event.data
1422  * @param {Function} fn A function to bind to the event on each of the set of matched elements
1423  * <pre>function callback(eventObject) {
1424  *   this; // dom element
1425  * }
1426  * </pre>
1427  * @type jQuery
1428  * @since 1.0
1429  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1430  */
1431 
1432 /**
1433  * Binds a handler to one or more events to be executed <i>once</i> for each matched element.
1434  * <p>The handler is executed only once for each element. Otherwise, the same rules as described in<a href='Events/bind'>bind</a> () apply. The event handler is passed an event object that you can use to prevent default behaviour. To stop both default action and event bubbling, your handler should return false.</p><p>In most cases, you can define your event handlers as anonymous functions (see first example). In cases where that is not possible, you can pass additional data as the second paramter (and the handler function as the third), see second example.</p>
1435  * @code
1436  * $("p").one("click", function(){
1437  *   alert( $(this).text() );
1438  * });
1439  * @id jQuery.one
1440  * @param {String} type An event type
1441  * @param {Object} data Additional data passed to the event handler as event.data
1442  * @param {Function} fn A function to bind to the specified event on each of the matched elements.
1443  * <pre>function callback(eventObject) {
1444  *   this; // dom element
1445  * }
1446  * </pre>
1447  * @type jQuery
1448  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1449  */
1450 
1451 /**
1452  * Trigger a type of event on every matched element.
1453  * <p>This will also cause the default action of the browser with the same name (if one exists) to be executed. For example, passing 'submit' to the trigger() function will also cause the browser to submit the form. This default action can be prevented by returning false from one of the functions bound to the event.</p><p>If a native event is triggered and a suitable event object is not passed as the first element of 'data', then a fake event object is added before all supplied 'data' arguments. This element contains appropriate 'type' and 'target' fields and null-op 'preventDefault' and 'stopPropagation' methods, but none of the clientXY/pageXY/keyCode fields specific to mouse and keyboard events. A "suitable" event object is judged by the presence of the 'preventDefault' field.</p><p>You can also trigger custom events registered with bind.</p><p>You can add a '''!''' in event type to trigger events without namespace.</p>
1454  * @code
1455  * $("p").bind("myEvent", function (event, message1, message2) {
1456  *   alert(message1 + ' ' + message2);
1457  * });
1458  * $("p").trigger("myEvent", ["Hello","World!"]);
1459  * @id jQuery.trigger
1460  * @param {String} type  An event type to trigger.
1461  * @param {Array} data  Additional data to pass as arguments (after the event object) to the event handler.
1462  * @type jQuery
1463  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1464  */
1465 
1466 /**
1467  * This particular method triggers all bound event handlers on an element (for a specific event type) WITHOUT executing the browsers default actions.
1468  * The event is only triggered on the first element within the JQuery collection. This method returns the return value of the triggered handler instead of a chainable JQuery object. Also, if the JQuery collection is empty, this method returns 'undefined' instead of an empty JQuery collection.
1469  * @code
1470  * $("#old").click(function(){
1471  *       $("input").trigger("focus");
1472  *     });
1473  *     $("#new").click(function(){
1474  *       $("input").triggerHandler("focus");
1475  *     });
1476  *     $("input").focus(function(){
1477  *       $("<span>Focused!</span>").appendTo("body").fadeOut(1000);
1478  *     });
1479  * @id jQuery.triggerHandler
1480  * @param {String} type  An event type to trigger.
1481  * @param {Array} data  Additional data to pass as arguments (after the event object) to the event handler.
1482  * @type jQuery
1483  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1484  */
1485 
1486 /**
1487  * This does the opposite of bind, it removes bound events from each of the matched elements.
1488  * <p>Without any arguments, all bound events are removed.</p><p>You can also unbind custom events registered with bind.</p><p>If the type is provided, all bound events of that type are removed.</p><p>If the function that was passed to bind is provided as the second argument, only that specific event handler is removed.</p>
1489  * @code
1490  * var foo = function () {
1491  *   // code to handle some kind of event
1492  * };
1493  * 
1494  * $("p").bind("click", foo); //  now foo will be called when paragraphs are clicked 
1495  * 
1496  * $("p").unbind("click", foo); //  foo will no longer be called.
1497  * @id jQuery.unbind
1498  * @param {String} type  An event type to unbind.
1499  * @param {Function} fn  A function to unbind from the event on each of the set of matched elements.
1500  * @type jQuery
1501  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1502  */
1503 
1504 /**
1505  * Simulates hovering (moving the mouse on, and off, an object). This is a custom method which provides an 'in' to a frequent task.
1506  * Whenever the mouse cursor is moved over a matched element, the first specified function is fired. Whenever the mouse moves off of the element, the second specified function fires. Additionally, checks are in place to see if the mouse is still within the specified element itself (for example, an image inside of a div), and if it is, it will continue to 'hover', and not move out (a common error in using a mouseout event handler).
1507  * @code
1508  * $("td").unbind('mouseenter mouseleave');
1509  * @id jQuery.hover
1510  * @param {Function} over The function to fire when the mouse is moved over a matched element.
1511  * <pre>function callback(eventObject) {
1512  *   this; // dom element
1513  * }
1514  * </pre>
1515  * @param {Function} out The function to fire when the mouse is moved off of a matched element.
1516  * <pre>function callback(eventObject) {
1517  *   this; // dom element
1518  * }
1519  * </pre>
1520  * @type jQuery
1521  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1522  */
1523 
1524 /**
1525  * Toggle among two or more function calls every other click.
1526  * <p>Whenever a matched element is clicked, the first specified function is fired, when clicked again, the second is fired, and so on. All subsequent clicks continue to rotate through the functions.</p><p>Use unbind("click") to remove the toggle event.</p>
1527  * @code
1528  * $("td").toggle(
1529  *   function () {
1530  *     $(this).addClass("selected");
1531  *   },
1532  *   function () {
1533  *     $(this).removeClass("selected");
1534  *   }
1535  * );
1536  * @id jQuery.toggle
1537  * @param {Function} fn The function to execute.
1538  * <pre>function callback(eventObject) {
1539  *   this; // dom element
1540  * }
1541  * </pre>
1542  * @param {Function} fn2 The function to execute.
1543  * <pre>function callback(eventObject) {
1544  *   this; // dom element
1545  * }
1546  * </pre>
1547  * @param {Function} fn3,fn4, The function to execute.
1548  * <pre>function callback(eventObject) {
1549  *   this; // dom element
1550  * }
1551  * </pre>
1552  * @type jQuery
1553  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1554  */
1555 
1556 /**
1557  * Triggers the blur event of each matched element.
1558  * This causes all of the functions that have been bound to that blur event to be executed, and calls the browser's default blur action on the matching element(s). This default action can be prevented by returning false from one of the functions bound to the blur event. The blur event usually fires when an element loses focus either via the pointing device or by tabbing navigation
1559  * @code
1560  * $("p").blur();
1561  * @id jQuery.blur
1562  * @type jQuery
1563  * @since 1.0
1564  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1565  */
1566 
1567 /**
1568  * Bind a function to the blur event of each matched element.
1569  * The blur event fires when an element loses focus either via the pointing device or by tabbing navigation.
1570  * @code
1571  * $("p").blur( function () { alert("Hello World!"); } );
1572  * @id jQuery.blur
1573  * @param {Function} fn A function to bind to the blur event on each of the matched elements.
1574  * <pre>function callback(eventObject) {
1575  *   this; // dom element
1576  * }
1577  * </pre>
1578  * @type jQuery
1579  * @since 1.0
1580  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1581  */
1582 
1583 /**
1584  * Triggers the change event of each matched element.
1585  * This causes all of the functions that have been bound to that change event to be executed, and calls the browser's default change action on the matching element(s). This default action can be prevented by returning false from one of the functions bound to the change event. The change event usually fires when a control loses the input focus and its value has been modified since gaining focus.
1586  * @id jQuery.change
1587  * @type jQuery
1588  * @since 1.0
1589  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1590  */
1591 
1592 /**
1593  * Binds a function to the change event of each matched element.
1594  * The change event fires when a control loses the input focus and its value has been modified since gaining focus.
1595  * @code
1596  * $("input[@type='text']").change( function() {
1597  *   // check input ($(this).val()) for validity here
1598  * });
1599  * @id jQuery.change
1600  * @param {Function} fn A function to bind to the change event on each of the matched elements.
1601  * <pre>function callback(eventObject) {
1602  *   this; // dom element
1603  * }
1604  * </pre>
1605  * @type jQuery
1606  * @since 1.0
1607  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1608  */
1609 
1610 /**
1611  * Triggers the click event of each matched element.
1612  * Causes all of the functions that have been bound to that click event to be executed.
1613  * @code
1614  * $("p").click();
1615  * @id jQuery.click
1616  * @type jQuery
1617  * @since 1.0
1618  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1619  */
1620 
1621 /**
1622  * Binds a function to the click event of each matched element.
1623  * The click event fires when the pointing device button is clicked over an element. A click is defined as a mousedown and mouseup over the same screen location. The sequence of these events is:<ul><li>mousedown</li><li>mouseup</li><li>click</li></ul>
1624  * @code
1625  * $("p").click(function () { 
1626  *       $(this).slideUp(); 
1627  *     });
1628  *     $("p").hover(function () {
1629  *       $(this).addClass("hilite");
1630  *     }, function () {
1631  *       $(this).removeClass("hilite");
1632  *     });
1633  * @id jQuery.click
1634  * @param {Function} fn A function to bind to the click event on each of the matched elements.
1635  * <pre>function callback(eventObject) {
1636  *   this; // dom element
1637  * }
1638  * </pre>
1639  * @type jQuery
1640  * @since 1.0
1641  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1642  */
1643 
1644 /**
1645  * Triggers the dblclick event of each matched element.
1646  * This causes all of the functions that have been bound to that dblclick event to be executed, and calls the browser's default dblclick action on the matching element(s). This default action can be prevented by returning false from one of the functions bound to the dblclick event. The dblclick event usually fires when the pointing device button is double clicked over an element.
1647  * @id jQuery.dblclick
1648  * @type jQuery
1649  * @since 1.0
1650  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1651  */
1652 
1653 /**
1654  * Binds a function to the dblclick event of each matched element.
1655  * The dblclick event fires when the pointing device button is double clicked over an element
1656  * @code
1657  * var divdbl = $("div:first");
1658  *     divdbl.dblclick(function () { 
1659  *       divdbl.toggleClass('dbl'); 
1660  *     });
1661  * @id jQuery.dblclick
1662  * @param {Function} fn The function to bind to the dblclick event on each of the matched elements.
1663  * <pre>function callback(eventObject) {
1664  *   this; // dom element
1665  * }
1666  * </pre>
1667  * @type jQuery
1668  * @since 1.0
1669  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1670  */
1671 
1672 /**
1673  * Triggers the error event of each matched element.
1674  * This causes all of the functions that have been bound to that error event to be executed, and calls the browser's default error action on the matching element(s). This default action can be prevented by returning false from one of the functions bound to the error event. The error event usually fires when an element loses focus either via the pointing device or by tabbing navigation.
1675  * @id jQuery.error
1676  * @type jQuery
1677  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1678  */
1679 
1680 /**
1681  * Binds a function to the error event of each matched element.
1682  * <p>There is no public standard for the error event. In most browsers, the window object's error event is triggered when a JavaScript error occurs on the page. An image object's error event is triggered when it is set an invalid src attribute - either a non-existent file, or one with corrupt image data.</p><p>If the event is thrown by the window object, the event handler will be passed three parameters: <ol><li>A message describing the event ("varName is not defined", "missing operator in expression", etc.),</li><li>the full URL of the document containing the error, and</li><li>the line number on which the error occured.</li></ol></p> <p>If the event handler returns true, it signifies that the event was handled, and the browser raises no errors.</p><p>For more information, see: <ul><li>[http://msdn2.microsoft.com/en-us/library/ms536930.aspx msdn - onerror Event]</li><li>[http://developer.mozilla.org/en/docs/DOM:window.onerror Gecko DOM Reference - onerror Event]</li><li>[http://developer.mozilla.org/en/docs/DOM:event Gecko DOM Reference - Event object]</li><li>[http://en.wikipedia.org/wiki/DOM_Events Wikipedia: DOM Events]</ul></p>
1683  * @code
1684  * $("img").error(function(){
1685  *   $(this).hide();
1686  * });
1687  * @id jQuery.error
1688  * @param {Function} fn An event handler function to bind to the error event.
1689  * <pre>function callback(eventObject) {
1690  *   this; // dom element
1691  * }
1692  * </pre>
1693  * @type jQuery
1694  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1695  */
1696 
1697 /**
1698  * Triggers the focus event of each matched element.
1699  * This causes all of the functions that have been bound to the focus event to be executed. Note that this does not execute the focus method of the underlying elements.
1700  * @code
1701  * $(document).ready(function(){
1702  *   $("#login").focus();
1703  * });
1704  * @id jQuery.focus
1705  * @type jQuery
1706  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1707  */
1708 
1709 /**
1710  * Binds a function to the focus event of each matched element.
1711  * The focus event fires when an element receives focus either via the pointing device or by tab navigation.
1712  * @code
1713  * $("input[@type=text]").focus(function(){
1714  *   $(this).blur();
1715  * });
1716  * @id jQuery.focus
1717  * @param {Function} fn A function to bind to the focus event on each of the matched elements.
1718  * <pre>function callback(eventObject) {  
1719  * this; // dom element
1720  * }
1721  * </pre>
1722  * @type jQuery
1723  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1724  */
1725 
1726 /**
1727  * Triggers the keydown event of each matched element.
1728  * This causes all of the functions that have been bound to the keydown event to be executed, and calls the browser's default keydown action on the matching element(s). This default action can be prevented by returning false from one of the functions bound to the keydown event. The keydown event usually fires when a key on the keyboard is pressed.
1729  * @id jQuery.keydown
1730  * @type jQuery
1731  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1732  */
1733 
1734 /**
1735  * Bind a function to the keydown event of each matched element.
1736  * The keydown event fires when a key on the keyboard is pressed.
1737  * @code
1738  * $(window).keydown(function(event){
1739  *   switch (event.keyCode) {
1740  *     // 
1741  *     // different keys do different things
1742  *     // Different browsers provide different codes
1743  *     // see here for details: http://unixpapa.com/js/key.html    
1744  *     // 
1745  *   }
1746  * });
1747  * @id jQuery.keydown
1748  * @param {Function} fn A function to bind to the keydown event on each of the matched elements.
1749  * <pre>function callback(eventObject) {
1750  *   this; // dom element
1751  * }
1752  * </pre>
1753  * @type jQuery
1754  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1755  */
1756 
1757 /**
1758  * Triggers the keypress event of each matched element.
1759  * This causes all of the functions that have been bound to the keypress event to be executed, and calls the browser's default keypress action on the matching element(s). This default action can be prevented by returning false from one of the functions bound to the keypress event. The keypress event usually fires when a key on the keyboard is pressed.
1760  * @id jQuery.keypress
1761  * @type jQuery
1762  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1763  */
1764 
1765 /**
1766  * Binds a function to the keypress event of each matched element.
1767  * The keypress event fires when a key on the keyboard is "clicked". A keypress is defined as a keydown and keyup on the same key. The sequence of these events is: <ul><li>keydown</li><li>keypress</li><li>keyup</li></ul>
1768  * @code
1769  * $("input").keypress(function (e) {
1770  *       if (e.which == 32 || (65 <= e.which && e.which <= 65 + 25)
1771  *                         || (97 <= e.which && e.which <= 97 + 25)) {
1772  *         var c = String.fromCharCode(e.which);
1773  *         $("p").append($("<span/>"))
1774  *               .children(":last")
1775  *               .append(document.createTextNode(c));
1776  *       } else if (e.which == 8) {
1777  *         // backspace in IE only be on keydown
1778  *         $("p").children(":last").remove();
1779  *       }
1780  *       $("div").text(e.which);
1781  *     });
1782  * @id jQuery.keypress
1783  * @param {Function} fn A function to bind to the keypress event on each of the matched elements.
1784  * <pre>function callback(eventObject) {
1785  *   this; // dom element
1786  * }
1787  * </pre>
1788  * @type jQuery
1789  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1790  */
1791 
1792 /**
1793  * Triggers the keyup event of each matched element.
1794  * This causes all of the functions that have been bound to the keyup event to be executed, and calls the browser's default keyup action on the matching element(s). This default action can be prevented by returning false from one of the functions bound to the keyup event. The keyup event usually fires when a key on the keyboard is released.
1795  * @id jQuery.keyup
1796  * @type jQuery
1797  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1798  */
1799 
1800 /**
1801  * Bind a function to the keyup event of each matched element.
1802  * The keyup event fires when a key on the keyboard is released.
1803  * @code
1804  * $(document).keyup(function(event){
1805  *     if (event.keyCode == 27) {
1806  *         alert('escaped!');
1807  *     }
1808  * });
1809  * @id jQuery.keyup
1810  * @param {Function} fn A function to bind to the keyup event on each of the matched elements.
1811  * <pre>function callback(eventObject) {
1812  *   this; // dom element
1813  * }
1814  * </pre>
1815  * @type jQuery
1816  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1817  */
1818 
1819 /**
1820  * Binds a function to the load event of each matched element.
1821  * When bound to the window element, the event fires when the user agent finishes loading all content within a document, including window, frames, objects and images. For elements, it fires when the target element and all of its content has finished loading. Note: load will work only if you set it before the element has completely loaded, if you set it after that nothing will happen. This doesn't happen in $(document).ready(), which jQuery handles it to work as expected, also when setting it after the DOM has loaded.
1822  * @code
1823  * $(window).load(function () {
1824  *       // run code
1825  *     });
1826  * @id jQuery.load 
1827  * @param {Function} fn A function to bind to the load event on each of the matched elements.
1828  * <pre>function callback(eventObject) {
1829  *   this; // dom element
1830  * }
1831  * </pre>
1832  * @type jQuery
1833  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1834  */
1835 
1836 /**
1837  * Binds a function to the mousedown event of each matched element.
1838  * The mousedown event fires when the pointing device button is pressed over an element.
1839  * @code
1840  * $("p").mouseup(function(){
1841  *       $(this).append('<span style="color:#F00;">Mouse up.</span>');
1842  *     }).mousedown(function(){
1843  *       $(this).append('<span style="color:#00F;">Mouse down.</span>');
1844  *     });
1845  * @id jQuery.mousedown 
1846  * @param {Function} fn A function to bind to the mousedown event on each of the matched elements.
1847  * <pre>function callback(eventObject) {
1848  *   this; // dom element
1849  * }
1850  * </pre>
1851  * @type jQuery
1852  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1853  */
1854 
1855 /**
1856  * Bind a function to the mousemove event of each matched element.
1857  * The mousemove event fires when the pointing device is moved while it is over an element. The event handler is passed one variable - the event object. Its .clientX and .clientY properties represent the coordinates of the mouse.
1858  * @code
1859  * $("div").mousemove(function(e){
1860  *       var pageCoords = "( " + e.pageX + ", " + e.pageY + " )";
1861  *       var clientCoords = "( " + e.clientX + ", " + e.clientY + " )";
1862  *       $("span:first").text("( e.pageX, e.pageY ) - " + pageCoords);
1863  *       $("span:last").text("( e.clientX, e.clientY ) - " + clientCoords);
1864  *     });
1865  * @id jQuery.mousemove
1866  * @param {Function} fn A function to bind to the mousmove event on each of the matched elements.
1867  * <pre>function callback(eventObject) {
1868  *   this; // dom element
1869  * }
1870  * </pre>
1871  * @type jQuery
1872  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1873  */
1874 
1875 /**
1876  * Bind a function to the mouseout event of each matched element.
1877  * The mouseout event fires when the pointing device is moved away from an element.
1878  * @code
1879  * var i = 0;
1880  *     $("div.overout").mouseout(function(){
1881  *       $("p:first",this).text("mouse out");
1882  *       $("p:last",this).text(++i);
1883  *     }).mouseover(function(){
1884  *       $("p:first",this).text("mouse over");
1885  *     });
1886  * 
1887  *     var n = 0;
1888  *     $("div.enterleave").bind("mouseenter",function(){
1889  *       $("p:first",this).text("mouse enter");
1890  *     }).bind("mouseleave",function(){
1891  *       $("p:first",this).text("mouse leave");
1892  *       $("p:last",this).text(++n);
1893  *     });
1894  * @id jQuery.mouseout
1895  * @param {Function} fn A function to bind to the mouseout event on each of the matched elements.
1896  * <pre>function callback(eventObject) {
1897  *   this; // dom element
1898  * }
1899  * </pre>
1900  * @type jQuery
1901  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1902  */
1903 
1904 /**
1905  * Bind a function to the mouseover event of each matched element.
1906  * The mouseover event fires when the pointing device is moved onto an element.
1907  * @code
1908  * var i = 0;
1909  *     $("div.overout").mouseover(function(){
1910  *       $("p:first",this).text("mouse over");
1911  *       $("p:last",this).text(++i);
1912  *     }).mouseout(function(){
1913  *       $("p:first",this).text("mouse out");
1914  *     });
1915  * 
1916  *     var n = 0;
1917  *     $("div.enterleave").bind("mouseenter",function(){
1918  *       $("p:first",this).text("mouse enter");
1919  *       $("p:last",this).text(++n);
1920  *     }).bind("mouseleave",function(){
1921  *       $("p:first",this).text("mouse leave");
1922  *     });
1923  * @id jQuery.mouseover
1924  * @param {Function} fn A function to bind to the mouseover event on each of the matched elements.
1925  * <pre>function callback(eventObject) {
1926  *   this; // dom element
1927  * }
1928  * </pre>
1929  * @type jQuery
1930  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1931  */
1932 
1933 /**
1934  * Bind a function to the mouseup event of each matched element.
1935  * The mouseup event fires when the pointing device button is released over an element.
1936  * @code
1937  * $("p").mouseup(function(){
1938  *       $(this).append('<span style="color:#F00;">Mouse up.</span>');
1939  *     }).mousedown(function(){
1940  *       $(this).append('<span style="color:#00F;">Mouse down.</span>');
1941  *     });
1942  * @id jQuery.mouseup
1943  * @param {Function} fn A function to bind to the mouseup event on each of the matched elements.
1944  * <pre>function callback(eventObject) {
1945  *   this; // dom element
1946  * }
1947  * </pre>
1948  * @type jQuery
1949  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1950  */
1951 
1952 /**
1953  * Bind a function to the resize event of each matched element.
1954  * The resize event fires when a document view is resized
1955  * @code
1956  * $(window).resize(function(){
1957  *   alert("Stop it!");
1958  * });
1959  * @id jQuery.resize
1960  * @param {Function} fn A function to bind to the resize event on each of the matched elements.
1961  * <pre>function callback(eventObject) {
1962  *   this; // dom element
1963  * }
1964  * </pre>
1965  * @type jQuery
1966  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1967  */
1968 
1969 /**
1970  * Bind a function to the scroll event of each matched element.
1971  * The scroll event fires when a document view is scrolled.
1972  * @code
1973  * $("p").clone().appendTo(document.body);
1974  *     $("p").clone().appendTo(document.body);
1975  *     $("p").clone().appendTo(document.body);
1976  *     $(window).scroll(function () { 
1977  *       $("span").css("display", "inline").fadeOut("slow"); 
1978  *     });
1979  * @id jQuery.scroll
1980  * @param {Function} fn A function to bind to the scroll event on each of the matched elements.
1981  * <pre>function callback(eventObject) {
1982  *   this; // dom element
1983  * }
1984  * </pre>
1985  * @type jQuery
1986  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1987  */
1988 
1989 /**
1990  * Trigger the select event of each matched element.
1991  * This causes all of the functions that have been bound to that select event to be executed, and calls the browser's default select action on the matching element(s). This default action can be prevented by returning false from one of the functions bound to the select event. Note: Do not confuse the "select" event with the "<a href='Events/change'>change</a> " event, which is the one triggered when an html "select" element is having its selected option modified by the user.
1992  * @code
1993  * $("input").select();
1994  * @id jQuery.select
1995  * @type jQuery
1996  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
1997  */
1998 
1999 /**
2000  * Bind a function to the select event of each matched element.
2001  * The select event fires when a user selects some text in a text field, including input and textarea.
2002  * @code
2003  * $(document).select( function () { 
2004  *       $("div").text("Something was selected").show().fadeOut(1000); 
2005  *     });
2006  * @id jQuery.select
2007  * @param {Function} fn A function to bind to the select event on each of the matched elements.
2008  * <pre>function callback(eventObject) {
2009  *   this; // dom element
2010  * }
2011  * </pre>
2012  * @type jQuery
2013  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2014  */
2015 
2016 /**
2017  * Trigger the submit event of each matched element.
2018  * This causes all of the functions that have been bound to that submit event to be executed, and calls the browser's default submit action on the matching element(s). This default action can be prevented by returning false from one of the functions bound to the submit event.
2019  * @code
2020  * $("form:first").submit();
2021  * @id jQuery.submit
2022  * @type jQuery
2023  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2024  */
2025 
2026 /**
2027  * Bind a function to the submit event of each matched element.
2028  * The select event fires when a form is submitted
2029  * @code
2030  * $("form").submit( function () {
2031  *   return this.some_flag_variable;
2032  * } );
2033  * @id jQuery.submit
2034  * @param {Function} fn A function to bind to the submit event on each of the matched elements.
2035  * <pre>function callback(eventObject) {
2036  *   this; // dom element
2037  * }
2038  * </pre>
2039  * @type jQuery
2040  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2041  */
2042 
2043 /**
2044  * Binds a function to the unload event of each matched element.
2045  * 
2046  * @code
2047  * $(window).unload( function () { alert("Bye now!"); } );
2048  * @id jQuery.unload
2049  * @param {Function} fn function to bind to the unload event on each of the matched elements.
2050  * <pre>function callback(eventObject) {
2051  *   this; // dom element
2052  * }
2053  * </pre>
2054  * @type jQuery
2055  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2056  */
2057 
2058 /**
2059  * Displays each of the set of matched elements if they are hidden.
2060  * Same as<a href='Effects/show#speedcallback'>show( speed, [callback] )</a> without animations. Doesn't change anything if the selected elements are all visible. It doesn't matter if the element is hidden via a hide() call, or via a display:none in a stylesheet.
2061  * @code
2062  * $("p").show()
2063  * @id jQuery.show
2064  * @type jQuery
2065  * @since 1.0
2066  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2067  */
2068 
2069 /**
2070  * Show all matched elements using a graceful animation and firing an optional callback after completion.
2071  * The height, width, and opacity of each of the matched elements are changed dynamically according to the specified speed.
2072  * @code
2073  * function doIt() {
2074  *       $("span,div").show("normal");
2075  *     }
2076  *     $("button").click(doIt); // can pass in function name
2077  *     $("form").submit(function () {
2078  *       if ($("input").val() == "yes") {
2079  *         $("p").show(4000, function () {
2080  *           $(this).text("Ok, DONE! (now showing)");
2081  *         });
2082  *       }
2083  *       $("span,div").hide("normal");
2084  *       return false; // to stop the submit
2085  *     });
2086  * @id jQuery.show
2087  * @param {String, Number } speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).
2088  * @param {Function} callback A function to be executed whenever the animation completes, executes once for each element animated against.
2089  * <pre>function callback() {
2090  *   this; // dom element
2091  * }
2092  * </pre>
2093  * @type jQuery
2094  * @since 1.0
2095  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2096  */
2097 
2098 /**
2099  * Hides each of the set of matched elements if they are shown.
2100  * Same as<a href='Effects/hide#speedcallback'>hide( speed, [callback] )</a> without animations. Doesn't change anything if the selected elements are all hidden.
2101  * @code
2102  * $("p").hide();
2103  *     $("a").click(function () {
2104  *       $(this).hide();
2105  *       return false;
2106  *     });
2107  * @id jQuery.hide
2108  * @type jQuery
2109  * @since 1.0
2110  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2111  */
2112 
2113 /**
2114  * Hide all matched elements using a graceful animation and firing an optional callback after completion.
2115  * The height, width, and opacity of each of the matched elements are changed dynamically according to the specified speed.
2116  * @code
2117  * for (var i = 0; i < 5; i++) {
2118  *       $("<div>").appendTo(document.body);
2119  *     }
2120  *     $("div").click(function () {
2121  *       $(this).hide(2000, function () {
2122  *         $(this).remove();
2123  *       });
2124  *     });
2125  * @id jQuery.hide
2126  * @param {String, Number } speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).
2127  * @param {Function} callback A function to be executed whenever the animation completes, executes once for each element animated against.
2128  * <pre>function callback() {
2129  *   this; // dom element
2130  * }
2131  * </pre>
2132  * @type jQuery
2133  * @since 1.0
2134  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2135  */
2136 
2137 /**
2138  * Toggles displaying each of the set of matched elements.
2139  * If they are shown, toggle makes them hidden. If they are hidden, toggle makes them shown.
2140  * @code
2141  * $("button").click(function () {
2142  *       $("p").toggle();
2143  *     });
2144  * @id jQuery.toggle
2145  * @type jQuery
2146  * @since 1.0
2147  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2148  */
2149 
2150 /**
2151  * Reveal all matched elements by adjusting their height and firing an optional callback after completion.
2152  * Only the height is adjusted for this animation, causing all matched elements to be revealed in a "sliding" manner.
2153  * @code
2154  * $("div").click(function () {
2155  *       $(this).css({ borderStyle:"inset", cursor:"wait" });
2156  *       $("input").slideDown(1000,function(){
2157  *         $(this).css("border", "2px red inset")
2158  *                .filter(".middle")
2159  *                  .css("background", "yellow")
2160  *                  .focus();
2161  *         $("div").css("visibility", "hidden");
2162  *       });
2163  *     });
2164  * @id jQuery.slideDown
2165  * @param {String, Number } speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).
2166  * @param {Function} callback A function to be executed whenever the animation completes, executes once for each element animated against.
2167  * <pre>function callback() {
2168  *   this; // dom element
2169  * }
2170  * </pre>
2171  * @type jQuery
2172  * @since 1.0
2173  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2174  */
2175 
2176 /**
2177  * Hide all matched elements by adjusting their height and firing an optional callback after completion.
2178  * Only the height is adjusted for this animation, causing all matched elements to be hidden in a "sliding" manner.
2179  * @code
2180  * $("button").click(function () {
2181  *       $(this).parent().slideUp("slow", function () {
2182  *         $("#msg").text($("button", this).text() + " has completed.");
2183  *       });
2184  *     });
2185  * @id jQuery.slideUp
2186  * @param {String, Number } speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).
2187  * @param {Function} callback A function to be executed whenever the animation completes, executes once for each element animated against.
2188  * <pre>function callback() {
2189  *   this; // dom element
2190  * }
2191  * </pre>
2192  * @type jQuery
2193  * @since 1.0
2194  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2195  */
2196 
2197 /**
2198  * Toggle the visibility of all matched elements by adjusting their height and firing an optional callback after completion.
2199  * Only the height is adjusted for this animation, causing all matched elements to be hidden or shown in a "sliding" manner.
2200  * @code
2201  * $("#aa").click(function () {
2202  *       $("div:not(.still)").slideToggle("slow", function () {
2203  *         var n = parseInt($("span").text(), 10);
2204  *         $("span").text(n + 1);
2205  *       });
2206  *     });
2207  * @id jQuery.slideToggle
2208  * @param {String, Number } speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).
2209  * @param {Function} callback A function to be executed whenever the animation completes, executes once for each element animated against.
2210  * <pre>function callback() {
2211  *   this; // dom element
2212  * }
2213  * </pre>
2214  * @type jQuery
2215  * @since 1.0
2216  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2217  */
2218 
2219 /**
2220  * Fade in all matched elements by adjusting their opacity and firing an optional callback after completion.
2221  * Only the opacity is adjusted for this animation, meaning that all of the matched elements should already have some form of height and width associated with them.
2222  * @code
2223  * $("a").click(function () {
2224  *       $("div").fadeIn(3000, function () {
2225  *         $("span").fadeIn(100);
2226  *       });
2227  *       return false;
2228  *     });
2229  * @id jQuery.fadeIn
2230  * @param {String, Number } speed A string representing one of the three predefined speeds ("slow", "def", or "fast") or the number of milliseconds to run the animation (e.g. 1000).  As of jQuery 1.2.6, "normal" or any other string works the same as "def" (400ms).
2231  * @param {Function} callback A function to be executed whenever the animation completes, executes once for each element animated against.
2232  * <pre>function callback() {
2233  *   this; // dom element
2234  * }
2235  * </pre>
2236  * @type jQuery
2237  * @since 1.0
2238  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2239  */
2240 
2241 /**
2242  * Fade out all matched elements by adjusting their opacity and firing an optional callback after completion.
2243  * Only the opacity is adjusted for this animation, meaning that all of the matched elements should already have some form of height and width associated with them.
2244  * @code
2245  * $("span").click(function () {
2246  *       $(this).fadeOut(1000, function () {
2247  *         $("div").text("'" + $(this).text() + "' has faded!");
2248  *         $(this).remove();
2249  *       });
2250  *     });
2251  *     $("span").hover(function () {
2252  *       $(this).addClass("hilite");
2253  *     }, function () {
2254  *       $(this).removeClass("hilite");
2255  *     });
2256  * @id jQuery.fadeOut
2257  * @param {String, Number } speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).
2258  * @param {Function} callback A function to be executed whenever the animation completes, executes once for each element animated against.
2259  * <pre>function callback() {
2260  *   this; // dom element
2261  * }
2262  * </pre>
2263  * @type jQuery
2264  * @since 1.0
2265  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2266  */
2267 
2268 /**
2269  * Fade the opacity of all matched elements to a specified opacity and firing an optional callback after completion.
2270  * Only the opacity is adjusted for this animation, meaning that all of the matched elements should already have some form of height and width associated with them.
2271  * @code
2272  * var getPos = function (n) {
2273  *       return (Math.floor(n) * 90) + "px";
2274  *     };
2275  *     $("p").each(function (n) {
2276  *       var r = Math.floor(Math.random() * 3);
2277  *       var tmp = $(this).text();
2278  *       $(this).text($("p:eq(" + r + ")").text());
2279  *       $("p:eq(" + r + ")").text(tmp);
2280  *       $(this).css("left", getPos(n));
2281  *     });
2282  *     $("div").each(function (n) {
2283  *                   $(this).css("left", getPos(n));
2284  *                 })
2285  *             .css("cursor", "pointer")
2286  *             .click(function () {
2287  *                   $(this).fadeTo(250, 0.25, function () {
2288  *                         $(this).css("cursor", "")
2289  *                                .prev().css({"font-weight": "bolder",
2290  *                                             "font-style": "italic"});
2291  *                       });
2292  *                 });
2293  * @id jQuery.fadeTo
2294  * @param {String, Number } speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).
2295  * @param {Number } opacity The opacity to fade to (a number from 0 to 1).
2296  * @param {Function} callback A function to be executed whenever the animation completes, executed once for each element animated against.
2297  * <pre>function callback() {
2298  *   this; // dom element
2299  * }
2300  * </pre>
2301  * @type jQuery
2302  * @since 1.0
2303  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2304  */
2305 
2306 /**
2307  * A function for making custom animations.
2308  * The key aspect of this function is the object of style properties that will be animated, and to what end. Each key within the object represents a style property that will also be animated (for example: "height", "top", or "opacity"). Note that properties should be specified using camel case, e.g. "marginLeft" instead of "margin-left." The value associated with the key represents to what end the property will be animated. If a number is provided as the value, then the style property will be transitioned from its current state to that new number. Otherwise if the string "hide", "show", or "toggle" is provided, a default animation will be constructed for that property. Only properties that take numeric values are supported (e.g. backgroundColor is not supported). As of jQuery 1.2 you can now animate properties by em and % (where applicable). Additionally, in jQuery 1.2, you can now do relative animations - specifying a "''+=''" or "''-=''" in front of the property value moves the element positively or negatively, relative to its current position.
2309  * @code
2310  * $("p").animate({
2311  *       "opacity": "show"
2312  *     }, "slow", "easein");
2313  * @id jQuery.animate
2314  * @param {Options} params A set of style attributes that you wish to animate, and to what end.
2315  * @param {String, Number } duration A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).
2316  * @param {String } easing The name of the easing effect that you want to use (plugin required). There are two built-in values, "linear" and "swing".
2317  * @param {Function} callback A function to be executed whenever the animation completes, executes once for each element animated against.
2318  * @type jQuery
2319  * @since 1.0
2320  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2321  */
2322 
2323 /**
2324  * A function for making custom animations.
2325  * The key aspect of this function is the object of style properties that will be animated, and to what end. Each key within the object represents a style property that will also be animated (e.g. "height", "top", or "opacity"). Note that properties should be specified using camel case, e.g. "marginLeft" instead of "margin-left." The value associated with the key represents to what end the property will be animated. If a number is provided as the value, then the style property will be transitioned from its current state to that new number. Otherwise if the string "hide", "show", or "toggle" is provided, a default animation will be constructed for that property.
2326  * @code
2327  * $("p").animate({
2328  *        height:200, width:400, opacity: .5
2329  *     }, 1000, "linear", function(){alert("all done");} );
2330  * @id jQuery.animate
2331  * @param {Options} params A set of style attributes that you wish to animate, and to what end.
2332  * @param {Options } options A set of options with which to configure the animation.
2333  * @type jQuery
2334  * @since 1.0
2335  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2336  */
2337 
2338 /**
2339  * Stops all the currently running animations on all the specified elements.
2340  * If any animations are queued to run, then they will begin immediately.
2341  * @code
2342  * // Start animation
2343  *     $("#go").click(function(){
2344  *       $(".block").animate({left: '+=100px'}, 2000);
2345  *     });
2346  * 
2347  *     // Stop animation when button is clicked
2348  *     $("#stop").click(function(){
2349  *       $(".block").stop();
2350  *     });
2351  * 
2352  *     // Start animation in the opposite direction
2353  *     $("#back").click(function(){
2354  *       $(".block").animate({left: '-=100px'}, 2000);
2355  *     });
2356  * @id jQuery.stop
2357  * @type jQuery
2358  * @since 1.2
2359  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2360  */
2361 
2362 /**
2363  * Returns a reference to the first element's queue (which is an array of functions).
2364  * 
2365  * @code
2366  * $("#show").click(function () {
2367  *       var n = $("div").queue("fx");
2368  *       $("span").text("Queue length is: " + n.length);
2369  *     });
2370  *     function runIt() {
2371  *       $("div").show("slow");
2372  *       $("div").animate({left:'+=200'},2000);
2373  *       $("div").slideToggle(1000);
2374  *       $("div").slideToggle("fast");
2375  *       $("div").animate({left:'-=200'},1500);
2376  *       $("div").hide("slow");
2377  *       $("div").show(1200);
2378  *       $("div").slideUp("normal", runIt);
2379  *     }
2380  *     runIt();
2381  * @id jQuery.queue
2382  * @type Array<Function>
2383  * @since 1.2
2384  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2385  */
2386 
2387 /**
2388  * Adds a new function, to be executed, onto the end of the queue of all matched elements.
2389  * 
2390  * @code
2391  * $(document.body).click(function () {
2392  *       $("div").show("slow");
2393  *       $("div").animate({left:'+=200'},2000);
2394  *       $("div").queue(function () {
2395  *         $(this).addClass("newcolor");
2396  *         $(this).dequeue();
2397  *       });
2398  *       $("div").animate({left:'-=200'},500);
2399  *       $("div").queue(function () {
2400  *         $(this).removeClass("newcolor");
2401  *         $(this).dequeue();
2402  *       });
2403  *       $("div").slideUp();
2404  *     });
2405  * @id jQuery.queue
2406  * @param {Function} callback The function to add to the queue.
2407  * <pre>function callback() {
2408  *   this; // dom element
2409  *   // to continue the queue you must call
2410  *   jQuery(this).dequeue();
2411  * }
2412  * </pre>
2413  * @type jQuery
2414  * @since 1.2
2415  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2416  */
2417 
2418 /**
2419  * Replaces the queue of all matched element with this new queue (the array of functions).
2420  * 
2421  * @code
2422  * $("#start").click(function () {
2423  *       $("div").show("slow");
2424  *       $("div").animate({left:'+=200'},5000);
2425  *       $("div").queue(function () {
2426  *         $(this).addClass("newcolor");
2427  *         $(this).dequeue();
2428  *       });
2429  *       $("div").animate({left:'-=200'},1500);
2430  *       $("div").queue(function () {
2431  *         $(this).removeClass("newcolor");
2432  *         $(this).dequeue();
2433  *       });
2434  *       $("div").slideUp();
2435  *     });
2436  *     $("#stop").click(function () {
2437  *       $("div").queue("fx", []);
2438  *       $("div").stop();
2439  *     });
2440  * @id jQuery.queue
2441  * @param {Array<Function>} queue The queue to replace all the queues with.  The functions have the same parameters and this value as queue(callback).
2442  * @type jQuery
2443  * @since 1.2
2444  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2445  */
2446 
2447 /**
2448  * Removes a queued function from the front of the queue and executes it.
2449  * 
2450  * @code
2451  * $("button").click(function () {
2452  *       $("div").animate({left:'+=200px'}, 2000);
2453  *       $("div").animate({top:'0px'}, 600);
2454  *       $("div").queue(function () {
2455  *         $(this).toggleClass("red");
2456  *         $(this).dequeue();
2457  *       });
2458  *       $("div").animate({left:'10px', top:'30px'}, 700);
2459  *     });
2460  * @id jQuery.dequeue
2461  * @type jQuery
2462  * @since 1.2
2463  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2464  */
2465 
2466 /**
2467  * Load a remote page using an HTTP request.
2468  * This is jQuery's low-level AJAX implementation. See $.get, $.post etc. for higher-level abstractions that are often easier to understand and use, but don't offer as much functionality (such as error callbacks). $.ajax() returns the XMLHttpRequest that it creates. In most cases you won't need that object to manipulate directly, but it is available if you need to abort the request manually. $.ajax() takes one argument, an object of key/value pairs, that are used to initialize and handle the request. See below for a full list of the key/values that can be used. '''Note:''' If you specify the dataType option described below, make sure the server sends the correct MIME type in the response (eg. xml as "text/xml"). Sending the wrong MIME type can lead to unexpected problems in your script. See<a href='Specifying_the_Data_Type_for_AJAX_Requests'>Specifying the Data Type for AJAX Requests</a> for more information. '''Note:''' All remote (not on the same domain) POST requests are converted to GET when 'script' is the dataType (because it loads script using a DOM script tag). As of jQuery 1.2, you can load JSON data located on another domain if you specify a [http://bob.pythonmac.org/archives/2005/12/05/remote-json-jsonp/ JSONP] callback, which can be done like so: "myurl?callback=?". jQuery automatically replaces the ? with the correct method name to call, calling your specified callback. Or, if you set the dataType to "jsonp" a callback will be automatically added to your Ajax request.
2469  * @code
2470  * var xmlDocument = [create xml document];
2471  *  $.ajax({
2472  *    url: "page.php",
2473  *    processData: false,
2474  *    data: xmlDocument,
2475  *    success: handleResponse
2476  *  });
2477  * @id jQuery.ajax
2478  * @param {Options} options A set of key/value pairs that configure the Ajax request. All options are optional. A default can be set for any option with <a href='Ajax/jQuery.ajaxSetup'>$.ajaxSetup</a>().
2479  * @type XMLHttpRequest
2480  * @since 1.0
2481  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2482  */
2483 
2484 /**
2485  * Load HTML from a remote file and inject it into the DOM.
2486  * A GET request will be performed by default - but if you pass in any extra parameters then a POST will occur. In jQuery 1.2 you can now specify a jQuery selector in the URL. Doing so will filter the incoming HTML document, only injecting the elements that match the selector. The syntax looks something like "url #some > selector". See the examples for more information.
2487  * @code
2488  * $("#feeds").load("feeds.php", {limit: 25}, function(){
2489  *    alert("The last 25 entries in the feed have been loaded");
2490  *  });
2491  * @id jQuery.load
2492  * @param {String} url The URL of the HTML page to load.
2493  * @param {Map} data Key/value pairs that will be sent to the server.
2494  * @param {Callback} callback The function called when the ajax request is complete (not necessarily success).
2495  * <pre>function (responseText, textStatus, XMLHttpRequest) {
2496  *   this; // dom element
2497  * }
2498  * </pre>
2499  * @type jQuery
2500  * @since 1.0
2501  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2502  */
2503 
2504 /**
2505  * Load a remote page using an HTTP GET request.
2506  * This is an easy way to send a simple GET request to a server without having to use the more complex $.ajax function. It allows a single callback function to be specified that will be executed when the request is complete (and only if the response has a successful response code). If you need to have both error and success callbacks, you may want to use $.ajax.
2507  * @code
2508  * $.get("test.cgi", { name: "John", time: "2pm" },
2509  *    function(data){
2510  *      alert("Data Loaded: " + data);
2511  *    });
2512  * @id jQuery.get
2513  * @param {String} url The URL of the page to load.
2514  * @param {Map} data Key/value pairs that will be sent to the server.
2515  * @param {Function} callback A function to be executed whenever the data is loaded successfully.
2516  * <pre>function (data, textStatus) {
2517  *   // data could be xmlDoc, jsonObj, html, text, etc
2518  *   this; // the options for this ajax request
2519  * }
2520  * </pre>
2521  * @param {String} type Type of data to be returned to callback function:  "xml", "html", "script", "json", "jsonp", or "text".
2522  * @type XMLHttpRequest
2523  * @since 1.0
2524  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2525  */
2526 
2527 /**
2528  * Load JSON data using an HTTP GET request.
2529  * As of jQuery 1.2, you can load JSON data located on another domain if you specify a [http://bob.pythonmac.org/archives/2005/12/05/remote-json-jsonp/ JSONP] callback, which can be done like so: "myurl?callback=?". jQuery automatically replaces the ? with the correct method name to call, calling your specified callback. Note: Keep in mind, that lines after this function will be executed before callback.
2530  * @code
2531  * var id=$("#id").attr("value");
2532  *   $.getJSON("pages.php",{id:id},dates);
2533  * function dates(datos)
2534  * {
2535  *     
2536  *  $("#list").html("Name:"+datos[1].name+"<br>"+"Last Name:"+datos[1].lastname+"<br>"+"Address:"+datos[1].address);
2537  * }
2538  * @id jQuery.getJSON
2539  * @param {String} url The URL of the page to load.
2540  * @param {Map} data Key/value pairs that will be sent to the server.
2541  * @param {Function} callback A function to be executed whenever the data is loaded successfully.
2542  * <pre>function (data, textStatus) {
2543  *   // data will be a jsonObj
2544  *   this; // the options for this ajax request
2545  * }
2546  * </pre>
2547  * @type XMLHttpRequest
2548  * @since 1.0
2549  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2550  */
2551 
2552 /**
2553  * Loads, and executes, a local JavaScript file using an HTTP GET request.
2554  * Before jQuery 1.2, getScript was only able to load scripts from the same domain as the original page. As of 1.2, you can now load JavaScript files from any domain. Warning: Safari 2 and older is unable to evaluate scripts in a global context synchronously. If you load functions via getScript, make sure to call them after a delay.
2555  * @code
2556  * $.getScript("test.js", function(){
2557  *    alert("Script loaded and executed.");
2558  *  });
2559  * @id jQuery.getScript
2560  * @param {String} url The URL of the page to load.
2561  * @param {Function} callback A function to be executed whenever the data is loaded successfully.
2562  * <pre>function (data, textStatus) {
2563  *   // data should be javascript
2564  *   this; // the options for this ajax request
2565  * }
2566  * </pre>
2567  * @type XMLHttpRequest
2568  * @since 1.0
2569  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2570  */
2571 
2572 /**
2573  * Load a remote page using an HTTP POST request.
2574  * This is an easy way to send a simple POST request to a server without having to use the more complex $.ajax function. It allows a single callback function to be specified that will be executed when the request is complete (and only if the response has a successful response code). The returned data format can be specified by the fourth parameter. If you need to have both error and success callbacks, you may want to use $.ajax. $.post is a (simplified) wrapper function for $.ajax.
2575  * @code
2576  * $.post("test.php", { func: "getNameAndTime" },
2577  *    function(data){
2578  *      alert(data.name); // John
2579  *      console.log(data.time); //  2pm
2580  *    }, "json");
2581  * @id jQuery.post
2582  * @param {String} url The URL of the page to load.
2583  * @param {Map} data Key/value pairs that will be sent to the server.
2584  * @param {Function} callback A function to be executed whenever the data is loaded successfully.
2585  * <pre>function (data, textStatus) {
2586  *   // data could be xmlDoc, jsonObj, html, text, etc
2587  *   this; // the options for this ajax request
2588  *   // textStatus can be one of:
2589  *   //   "timeout"
2590  *   //   "error"
2591  *   //   "notmodified"
2592  *   //   "success"
2593  *   //   "parsererror" 
2594  * }
2595  * </pre>
2596  * @param {String} type Type of data to be returned to callback function:  "xml", "html", "script", "json", "jsonp", or "text".
2597  * <pre>$.postJSON = function(url, data, callback) {
2598  *     $.post(url, data, callback, "json");
2599  * };
2600  * </pre>
2601  * @type XMLHttpRequest
2602  * @since 1.0
2603  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2604  */
2605 
2606 /**
2607  * Attach a function to be executed whenever an AJAX request completes. This is an<a href='Ajax_Events'>Ajax Event</a> .
2608  * The XMLHttpRequest and settings used for that request are passed as arguments to the callback.
2609  * @code
2610  * $("#msg").ajaxComplete(function(request, settings){
2611  *    $(this).append("<li>Request Complete.</li>");
2612  *  });
2613  * @id jQuery.ajaxComplete
2614  * @param {Function} callback The function to execute.
2615  * <pre>function (event, XMLHttpRequest, ajaxOptions) {
2616  *   this; // dom element listening
2617  * }
2618  * </pre>
2619  * @type jQuery
2620  * @since 1.0
2621  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2622  */
2623 
2624 /**
2625  * Attach a function to be executed whenever an AJAX request fails. This is an<a href='Ajax_Events'>Ajax Event</a> .
2626  * The XMLHttpRequest and settings used for that request are passed as arguments to the callback. A third argument, an exception object, is passed if an exception occured while processing the request.
2627  * @code
2628  * $("#msg").ajaxError(function(event, request, settings){
2629  *    $(this).append("<li>Error requesting page " + settings.url + "</li>");
2630  *  });
2631  * @id jQuery.ajaxError
2632  * @param {Function} callback The function to execute.
2633  * <pre>function (event, XMLHttpRequest, ajaxOptions, thrownError) {
2634  *   // thrownError only passed if an error was caught
2635  *   this; // dom element listening
2636  * }
2637  * </pre>
2638  * @type jQuery
2639  * @since 1.0
2640  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2641  */
2642 
2643 /**
2644  * Attach a function to be executed before an AJAX request is sent. This is an<a href='Ajax_Events'>Ajax Event</a> .
2645  * The XMLHttpRequest and settings used for that request are passed as arguments to the callback.
2646  * @code
2647  * $("#msg").ajaxSend(function(evt, request, settings){
2648  *    $(this).append("<li>Starting request at " + settings.url + "</li>");
2649  *  });
2650  * @id jQuery.ajaxSend
2651  * @param {Function} callback The function to execute.
2652  * <pre>function (event, XMLHttpRequest, ajaxOptions) {
2653  *   this; // dom element listening
2654  * }
2655  * </pre>
2656  * @type jQuery
2657  * @since 1.0
2658  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2659  */
2660 
2661 /**
2662  * Attach a function to be executed whenever an AJAX request begins and there is none already active. This is an<a href='Ajax_Events'>Ajax Event</a> .
2663  * 
2664  * @code
2665  * $("#loading").ajaxStart(function(){
2666  *    $(this).show();
2667  *  });
2668  * @id jQuery.ajaxStart
2669  * @param {Function} callback The function to execute.
2670  * <pre>function () {
2671  *   this; // dom element listening
2672  * }
2673  * </pre>
2674  * @type jQuery
2675  * @since 1.0
2676  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2677  */
2678 
2679 /**
2680  * Attach a function to be executed whenever all AJAX requests have ended. This is an<a href='Ajax_Events'>Ajax Event</a> .
2681  * 
2682  * @code
2683  * $("#loading").ajaxStop(function(){
2684  *    $(this).hide();
2685  *  });
2686  * @id jQuery.ajaxStop
2687  * @param {Function} callback The function to execute.
2688  * <pre>function () {
2689  *   this; // dom element listening
2690  * }
2691  * </pre>
2692  * @type jQuery
2693  * @since 1.0
2694  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2695  */
2696 
2697 /**
2698  * Attach a function to be executed whenever an AJAX request completes successfully. This is an<a href='Ajax_Events'>Ajax Event</a> .
2699  * The event object, XMLHttpRequest, and settings used for that request are passed as arguments to the callback.
2700  * @code
2701  * $("#msg").ajaxSuccess(function(evt, request, settings){
2702  *    $(this).append("<li>Successful Request!</li>");
2703  *  });
2704  * @id jQuery.ajaxSuccess
2705  * @param {Function} callback The function to execute.
2706  * <pre>function (event, XMLHttpRequest, ajaxOptions) {
2707  *   this; // dom element listening
2708  * }
2709  * </pre>
2710  * @type jQuery
2711  * @since 1.0
2712  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2713  */
2714 
2715 /**
2716  * Setup global settings for AJAX requests.
2717  * See<a href='Ajax/jQuery.ajax'>$.ajax</a> for a description of all available options.
2718  * @code
2719  * $.ajaxSetup({
2720  *    url: "/xmlhttp/",
2721  *    global: false,
2722  *    type: "POST"
2723  *  });
2724  *  $.ajax({ data: myData });
2725  * @id jQuery.ajaxSetup
2726  * @param {Options} options A set of key/value pairs that configure the default Ajax request. All options are optional.
2727  * @type 
2728  * @since 1.1
2729  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2730  */
2731 
2732 /**
2733  * Serializes a set of input elements into a string of data.
2734  * Serialize is typically used to prepare user input data to be posted to a server. The serialized data is in a standard format that is compatible with almost all server side programming languages and frameworks. In order to work properly '''serialize requires that form fields have a name''' attribute. Having only an id will not work. Note the name attribute in this field: <input id="email" name="email" type="text" /> '''Versions''' As of jQuery 1.2 the serialize method correctly serializes forms. For older versions of jQuery, the [http://www.malsup.com/jquery/form/ Form Plugin's] fieldSerialize method should be used.
2735  * @code
2736  * function showValues() {
2737  *       var str = $("form").serialize();
2738  *       $("#results").text(str);
2739  *     }
2740  * 
2741  *     $(":checkbox, :radio").click(showValues);
2742  *     $("select").change(showValues);
2743  *     showValues();
2744  * @id jQuery.serialize
2745  * @type jQuery
2746  * @since 1.0
2747  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2748  */
2749 
2750 /**
2751  * Serializes all forms and form elements (like the<a href='Ajax/serialize'>.serialize()</a> method) but returns a JSON data structure for you to work with.
2752  * 
2753  * @code
2754  * function showValues() {
2755  *       var fields = $(":input").serializeArray();
2756  *       $("#results").empty();
2757  *       jQuery.each(fields, function(i, field){
2758  *         $("#results").append(field.value + " ");
2759  *       });
2760  *     }
2761  * 
2762  *     $(":checkbox, :radio").click(showValues);
2763  *     $("select").change(showValues);
2764  *     showValues();
2765  * @id jQuery.serializeArray
2766  * @type jQuery
2767  * @since 1.2
2768  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2769  */
2770 
2771 /**
2772  * Contains flags for the useragent, read from navigator.userAgent.
2773  * Available flags are: * safari * opera * msie * mozilla This property is available before the DOM is ready, therefore you can use it to add ready events only for certain browsers. There are situations where object detection is not reliable enough, in such cases it makes sense to use browser detection. A combination of browser and object detection yields quite reliable results.
2774  * @code
2775  * jQuery.each(jQuery.browser, function(i) {
2776  *    if($.browser.msie){
2777  *       $("#div ul li").css("display","inline");
2778  *    }else{
2779  *       $("#div ul li").css("display","inline-table");
2780  *    }
2781  *  });
2782  * @id jQuery.browser
2783  * @type Map
2784  * @property
2785  * @since 1.0
2786  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2787  */
2788 
2789 /**
2790  * The version number of the rendering engine for the user's browser.
2791  * Here are some typical results: * Internet Explorer: 6.0, 7.0 * Mozilla/Firefox/Flock/Camino: 1.7.12, 1.8.1.3, 1.9 * Opera: 9.20 * Safari/Webkit: 312.8, 418.9
2792  * @code
2793  * if (jQuery.browser.msie) {
2794  *   alert(parseInt(jQuery.browser.version));
2795  * }
2796  * @id jQuery.browser.version
2797  * @type String
2798  * @property
2799  * @since 1.1.3
2800  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2801  */
2802 
2803 /**
2804  * States if the current page, in the user's browser, is being rendered using the [http://www.w3.org/TR/REC-CSS2/box.html W3C CSS Box Model].
2805  * 
2806  * @code
2807  * $.boxModel
2808  * @id jQuery.boxModel
2809  * @type Boolean
2810  * @property
2811  * @since 1.0
2812  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2813  */
2814 
2815 /**
2816  * A generic iterator function, which can be used to seamlessly iterate over both objects and arrays.
2817  * This function is not the same as<a href='Core/each'>$().each()</a> - which is used to iterate, exclusively, over a jQuery object. This function can be used to iterate over anything. The callback has two arguments:the key (objects) or index (arrays) as the first, and the value as the second. If you wish to break the each() loop at a particular iteration you can do so by making your function return false. Returning non-false is the same as a <code>continue</code> statement in a for loop, it will skip immediately to the next iteration.
2818  * @code
2819  * $.each( { name: "John", lang: "JS" }, function(i, n){
2820  *    alert( "Name: " + i + ", Value: " + n );
2821  *  });
2822  * @id jQuery.each
2823  * @param {Object} object The object or array to iterate over.
2824  * @param {Function} callback The function that will be executed on every object.
2825  * <pre>function callback(indexInArray, valueOfElement) {
2826  *   var booleanKeepGoing;
2827  * 
2828  *   this; // == valueOfElement (casted to Object)
2829  * 
2830  *   return booleanKeepGoing; // optional, unless false 
2831  *                            // and want to stop looping
2832  * }
2833  * </pre>
2834  * @type Object
2835  * @since 1.0
2836  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2837  */
2838 
2839 /**
2840  * Extend one object with one or more others, returning the original, modified, object.
2841  * If no target is specified, the JQuery namespace itself is extended. This can be useful for plugin authors wishing to add new methods to JQuery. If a boolean true is specified as the first argument, JQuery performs a deep copy, recursively copying any objects it finds. Otherwise, the copy will share structure with the original object(s). Undefined properties are not copied. However, properties inherited from the object's prototype ''will'' be copied over.
2842  * @code
2843  * var empty = {}
2844  * var defaults = { validate: false, limit: 5, name: "foo" };
2845  * var options = { validate: true, name: "bar" };
2846  * var settings = $.extend(empty, defaults, options);
2847  * @id jQuery.extend
2848  * @param {Object} target The object to extend.
2849  * @param {Object} object1 The object that will be merged into the first.
2850  * @param {Object} objectN More objects to merge into the first.
2851  * @type Object
2852  * @since 1.0
2853  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2854  */
2855 
2856 /**
2857  * Filter items out of an array, by using a filter function.
2858  * The filter function will be passed two arguments: The current array item and its index. The filter function must return 'true' to keep the item in the array.
2859  * @code
2860  * $.grep( [0,1,2], function(n,i){
2861  *    return n > 0;
2862  *  });
2863  * @id jQuery.grep
2864  * @param {Array} array The Array to find items in.
2865  * @param {Function} callback The function to process each item against.  The first argument to the function is the list item, and the second argument is the list index.  The function should return a Boolean value.  The "lambda-form" function feature was removed in jQuery 1.2.3 to help compatibility with other frameworks.
2866  * <pre>function callback(elementOfArray, indexInArray) {
2867  *   var shouldKeepIt;
2868  * 
2869  *   this; // == window
2870  * 
2871  *   return shouldKeepIt;
2872  * }
2873  * </pre>
2874  * @param {Boolean} invert If "invert" is false, or not provided, then the function returns an array consisting of all elements for which "callback" returns true.  If "invert" is true, then the function returns an array consisting of all elements for which "callback" returns false.
2875  * @type Array
2876  * @since 1.0
2877  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2878  */
2879 
2880 /**
2881  * Turns anything into a true array.
2882  * Typically it will be unnecessary to use this function if you are using jQuery which uses this function internally.
2883  * @code
2884  * var arr = jQuery.makeArray(document.getElementsByTagName("div"));
2885  *     arr.reverse(); // use an Array method on list of dom elements
2886  *     $(arr).appendTo(document.body);
2887  * @id jQuery.makeArray
2888  * @param {Object} obj Anything to turn in to an actual Array.
2889  * @type Array
2890  * @since 1.2
2891  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2892  */
2893 
2894 /**
2895  * Translate all items in an array to another array of items.
2896  * The translation function that is provided to this method is called for each item in the array and is passed two arguments: The item to be translated, and its index within the array. The function can then return the translated value, 'null' (to remove the item), or an array of values - which will be flattened into the full array.
2897  * @code
2898  * $.map( [0,1,2,3], function (a) { return a * a; } );
2899  * @id jQuery.map
2900  * @param {Array} array The Array to translate.
2901  * @param {Function} callback The function to process each item against.  The argument to the function is the list item. The function can return any value.  The "lambda-form" function represented as a string no longer works.  It was removed in version 1.2.3 to increase compatibility with Adobe AIR.   
2902  * <pre>function callback(elementOfArray, indexInArray) {
2903  *   var replacementValue;
2904  * 
2905  *   this; // unmapped
2906  * 
2907  *   return replacementValue;
2908  * }
2909  * </pre>
2910  * @type Array
2911  * @since 1.0
2912  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2913  */
2914 
2915 /**
2916  * Determine the index of the first parameter in the Array (-1 if not found).
2917  * 
2918  * @code
2919  * var arr = [ 4, "Pete", 8, "John" ];
2920  * 
2921  *     $("span:eq(0)").text(jQuery.inArray("John", arr));
2922  *     $("span:eq(1)").text(jQuery.inArray(4, arr));
2923  *     $("span:eq(2)").text(jQuery.inArray("David", arr));
2924  * @id jQuery.inArray
2925  * @param {Any} value Value to see if it exists in the array.
2926  * @param {Array} array Array to look through for the value.
2927  * @type Number
2928  * @since 1.2
2929  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2930  */
2931 
2932 /**
2933  * Merge two arrays together. Removing all duplicates is removed in jQuery 1.1.3
2934  * The result is the altered first argument with the elements from the second array added. To remove duplicate elements from the resulting array, use $.unique().
2935  * @code
2936  * $.merge( [3,2,1], [4,3,2] )
2937  * @id jQuery.merge
2938  * @param {Array} first The first array to merge, the elements of second added.
2939  * @param {Array} second The second array to merge into the first, unaltered.
2940  * @type Array
2941  * @since 1.0
2942  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2943  */
2944 
2945 /**
2946  * Remove all duplicate elements from an array of elements.
2947  * 
2948  * @code
2949  * $.unique(document.getElementsByTagName("div"));
2950  * @id jQuery.unique
2951  * @param {Array} array The Array to translate.
2952  * @type Array
2953  * @since 1.1.3
2954  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2955  */
2956 
2957 /**
2958  * Determine if the parameter passed is a function.
2959  * 
2960  * @code
2961  * $.isFunction(function(){});
2962  * @id jQuery.isFunction
2963  * @param {Object} obj Object to test whether or not it is a function.
2964  * @type boolean
2965  * @since 1.2
2966  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2967  */
2968 
2969 /**
2970  * Remove the whitespace from the beginning and end of a string.
2971  * Uses a regular expression to remove whitespace from the given string.
2972  * @code
2973  * $.trim("  hello, how are you?  ");
2974  * @id jQuery.trim
2975  * @param {String} str The string to trim.
2976  * @type String
2977  * @since 1.0
2978  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2979  */
2980 
2981 /**
2982  * Returns a unique ID for the element.
2983  * Typically this function will only be used internally. It is called automatically when necessary when using the other data() functionality.
2984  * @code
2985  * $(document.body).click(function(e) {
2986  *       var id = jQuery.data(e.target);
2987  *       $("span").text(id);
2988  *     });
2989  * @id jQuery.data
2990  * @param {Element} elem DOM element of interest.
2991  * @type Number
2992  * @since 1.2
2993  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
2994  */
2995 
2996 /**
2997  * Returns value at named data store for the element.
2998  * 
2999  * @code
3000  * $("button").click(function(e) {
3001  *       var adiv = $("div").get(0);
3002  *       var value;
3003  * 
3004  *       switch ($("button").index(this)) {
3005  *         case 0 :
3006  *           value = jQuery.data(adiv, "blah");
3007  *           break;
3008  *         case 1 :
3009  *           jQuery.data(adiv, "blah", "hello");
3010  *           value = "Stored!";
3011  *           break;
3012  *         case 2 :
3013  *           jQuery.data(adiv, "blah", 86);
3014  *           value = "Stored!";
3015  *           break;
3016  *         case 3 :
3017  *           jQuery.removeData(adiv);
3018  *           value = "Removed!";
3019  *           break;
3020  *       }
3021  * 
3022  *       $("span").text("" + value);
3023  *     });
3024  * @id jQuery.data
3025  * @param {Element} elem DOM element of interest.
3026  * @param {String} name Name of the data stored.
3027  * @type Any
3028  * @since 1.2
3029  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
3030  */
3031 
3032 /**
3033  * Stores the value in the named spot and also returns the value.
3034  * This function can be useful for attaching data to elements without having to create a new expando. It also isn't limited to a string. The value can be any format. To avoid conflicts in plugins, it is usually effective to store one object using the plugin name and put all the necessary information in that object. <code> var obj = jQuery.data($("#target").get(0), "pluginname", {}); obj[] =  </code>
3035  * @code
3036  * var adiv = $("div").get(0);
3037  *     jQuery.data(adiv, "test", { first: 16, last: "pizza!" });
3038  *     $("span:first").text(jQuery.data(adiv, "test").first);
3039  *     $("span:last").text(jQuery.data(adiv, "test").last);
3040  * @id jQuery.data
3041  * @param {Element} elem DOM element of interest.
3042  * @param {String} name Name of the data to store.
3043  * @param {Any} value Value to be stored.
3044  * @type Any
3045  * @since 1.2
3046  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
3047  */
3048 
3049 /**
3050  * Remove the expando attribute that allows data storage on an element.
3051  * This is the complement function to jQuery.data(elem) which is called as necessary by jQuery.data(elem, name, value).
3052  * @code
3053  * var adiv = $("div").get(0);
3054  * 
3055  *     $("span:eq(0)").text("" + jQuery.data(adiv, "test1"));
3056  *     jQuery.data(adiv, "test1", "VALUE-1");
3057  *     jQuery.data(adiv, "test2", "VALUE-2");
3058  *     $("span:eq(1)").text("" + jQuery.data(adiv, "test1"));
3059  *     jQuery.removeData(adiv);
3060  *     $("span:eq(2)").text("" + jQuery.data(adiv, "test1"));
3061  *     $("span:eq(3)").text("" + jQuery.data(adiv, "test2"));
3062  * @id jQuery.removeData
3063  * @param {Element} elem Element to delete the data store from.
3064  * @type 
3065  * @since 1.2
3066  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
3067  */
3068 
3069 /**
3070  * Removes just this one named data store.
3071  * This is the complement function to jQuery.data(elem, name, value).
3072  * @code
3073  * var adiv = $("div").get(0);
3074  * 
3075  *     $("span:eq(0)").text("" + jQuery.data(adiv, "test1"));
3076  *     jQuery.data(adiv, "test1", "VALUE-1");
3077  *     jQuery.data(adiv, "test2", "VALUE-2");
3078  *     $("span:eq(1)").text("" + jQuery.data(adiv, "test1"));
3079  *     jQuery.removeData(adiv, "test1");
3080  *     $("span:eq(2)").text("" + jQuery.data(adiv, "test1"));
3081  *     $("span:eq(3)").text("" + jQuery.data(adiv, "test2"));
3082  * @id jQuery.removeData
3083  * @param {Element} elem Element to delete the named data store property from.
3084  * @param {String} name The name of the data store property to remove.
3085  * @type 
3086  * @since 1.2
3087  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
3088  */
3089 
3090 /**
3091  * Serializes an array of form elements or an object (core of<a href='Ajax/serialize'>.serialize()</a> method).
3092  * 
3093  * @code
3094  * var params = { width:1680, height:1050 };
3095  *     var str = jQuery.param(params);
3096  *     $("#results").text(str);
3097  * @id jQuery.param
3098  * @param {Array<Elements>, jQuery, Object} obj An Array or jQuery object is serialized by name/value pairs.  An object by key/value pairs.
3099  * @type String
3100  * @since 1.2
3101  * @compat=IE6|IE7|FF1|FF2|FF3|OPERA|SAFARI2|SAFARI3|KONQ
3102  */
3103 
3104