X-Git-Url: http://git.asbjorn.biz/?a=blobdiff_plain;f=src%2Fjquery%2Fjquery.js;h=0c00829f6840ee6eb8919a227e7bfcb8d603dd51;hb=83b43a1e927d6b260f35f75bc2c3d177f271be93;hp=282741fd75941ea72bce48bb51688d960c7552f3;hpb=2daf49296abd4fcdf526a2c2814cd24e8f3eaff0;p=jquery.git diff --git a/src/jquery/jquery.js b/src/jquery/jquery.js index 282741f..0c00829 100644 --- a/src/jquery/jquery.js +++ b/src/jquery/jquery.js @@ -1,7 +1,7 @@ /* * jQuery @VERSION - New Wave Javascript * - * Copyright (c) 2006 John Resig (jquery.com) + * Copyright (c) 2007 John Resig (jquery.com) * Dual licensed under the MIT (MIT-LICENSE.txt) * and GPL (GPL-LICENSE.txt) licenses. * @@ -18,42 +18,45 @@ window.undefined = window.undefined; * @constructor * @private * @name jQuery + * @param String|Function|Element|Array|jQuery a selector + * @param jQuery|Element|Array c context * @cat Core */ var jQuery = function(a,c) { - // Make sure that a selection was provided - a = a || document; - - // Shortcut for document ready - // Safari reports typeof on DOM NodeLists as a function - if ( typeof a == "function" && !a.nodeType && a[0] == undefined ) - return jQuery(document)[ jQuery.fn.ready ? "ready" : "load" ]( a ); - - // Watch for when a jQuery object is passed as the selector - if ( a.jquery ) - return jQuery( jQuery.makeArray( a ) ); - - // Watch for when a jQuery object is passed at the context - if ( c && c.jquery ) - return jQuery( c ).find(a); - // If the context is global, return a new object if ( window == this ) return new jQuery(a,c); + // Make sure that a selection was provided + a = a || document; + + // HANDLE: $(function) + // Shortcut for document ready + if ( jQuery.isFunction(a) ) + return new jQuery(document)[ jQuery.fn.ready ? "ready" : "load" ]( a ); + // Handle HTML strings if ( typeof a == "string" ) { - var m = /^[^<]*(<.+>)[^>]*$/.exec(a); - if ( m ) a = jQuery.clean( [ m[1] ] ); + // HANDLE: $(html) -> $(array) + var m = /^[^<]*(<(.|\s)+>)[^>]*$/.exec(a); + if ( m ) + a = jQuery.clean( [ m[1] ] ); + + // HANDLE: $(expr) + else + return new jQuery( c ).find( a ); } + + return this.setArray( + // HANDLE: $(array) + a.constructor == Array && a || - // Watch for when an array is passed in - return this.setArray( a.constructor == Array || a.length && a != window && !a.nodeType && a[0] != undefined && a[0].nodeType ? - // Assume that it is an array of DOM Elements - jQuery.makeArray( a ) : + // HANDLE: $(arraylike) + // Watch for when an array-like object is passed as the selector + (a.jquery || a.length && a != window && !a.nodeType && a[0] != undefined && a[0].nodeType) && jQuery.makeArray( a ) || - // Find the matching elements and save them for later - jQuery.find( a, c ) ); + // HANDLE: $(*) + [ a ] ); }; // Map over the $ in case of overwrite @@ -73,11 +76,15 @@ var $ = jQuery; * (usually consisting of CSS or XPath), which then finds all matching * elements. * - * By default, $() looks for DOM elements within the context of the - * current HTML document. + * 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 [[DOM/Traversing/Selectors]] for the allowed CSS/XPath syntax for expressions. * * @example $("div > p") - * @desc This finds all p elements that are children of a div element. + * @desc Finds all p elements that are children of a div element. * @before

one

two

three

* @result [

two

] * @@ -89,7 +96,7 @@ var $ = jQuery; * * @name $ * @param String expr An expression to search with - * @param Element context (optional) A DOM Element, or Document, representing the base context. + * @param Element|jQuery context (optional) A DOM Element, Document or jQuery to use as context * @cat Core * @type jQuery * @see $(Element) @@ -97,50 +104,35 @@ var $ = jQuery; */ /** - * This function accepts a string of raw HTML. + * Create DOM elements on-the-fly from the provided String of raw HTML. * - * The HTML string is different from the traditional selectors in that - * it creates the DOM elements representing that HTML string, on the fly, - * to be (assumedly) inserted into the document later. - * - * @example $("

Hello

").appendTo("#body") + * @example $("

Hello

").appendTo("body") * @desc Creates a div element (and all of its contents) dynamically, - * and appends it to the element with the ID of body. Internally, an - * element is created and it's innerHTML property set to the given markup. + * and appends it to the body element. Internally, an + * element is created and its innerHTML property set to the given markup. * It is therefore both quite flexible and limited. * * @name $ * @param String html A string of HTML to create on the fly. * @cat Core * @type jQuery + * @see appendTo(String) */ /** - * Wrap jQuery functionality around a specific DOM Element. + * Wrap jQuery functionality around a single or multiple DOM Element(s). + * * This function also accepts XML Documents and Window objects * as valid arguments (even though they are not DOM Elements). * - * @example $(document).find("div > p") - * @before

one

two

three

- * @result [

two

] - * - * @example $(document.body).background( "black" ); + * @example $(document.body).css( "background", "black" ); * @desc Sets the background color of the page to black. * - * @name $ - * @param Element elem A DOM element to be encapsulated by a jQuery object. - * @cat Core - * @type jQuery - */ - -/** - * Wrap jQuery functionality around a set of DOM Elements. - * * @example $( myForm.elements ).hide() * @desc Hides all the input elements within a form * * @name $ - * @param Array elems An array of DOM elements to be encapsulated by a jQuery object. + * @param Element|Array elems DOM element(s) to be encapsulated by a jQuery object. * @cat Core * @type jQuery */ @@ -149,8 +141,10 @@ var $ = jQuery; * A shorthand for $(document).ready(), allowing 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 - * all of the other $() operations on your page. While this function is, - * technically, chainable - there really isn't much use for chaining against it. + * 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. @@ -160,25 +154,18 @@ var $ = jQuery; * }); * @desc Executes the function when the DOM is ready to be used. * - * @name $ - * @param Function fn The function to execute when the DOM is ready. - * @cat Core - * @type jQuery - */ - -/** - * A means of creating a cloned copy of a jQuery object. This function - * copies the set of matched elements from one jQuery object and creates - * another, new, jQuery object containing the same elements. - * - * @example var div = $("div"); - * $( div ).find("p"); - * @desc Locates all p elements with all div elements, without disrupting the original jQuery object contained in 'div' (as would normally be the case if a simple div.find("p") was done). + * @example jQuery(function($) { + * // Your code using failsafe $ alias here... + * }); + * @desc Uses both the shortcut for $(document).ready() and the argument + * to write failsafe jQuery code using the $ alias, without relying on the + * global alias. * * @name $ - * @param jQuery obj The jQuery object to be cloned. + * @param Function fn The function to execute when the DOM is ready. * @cat Core * @type jQuery + * @see ready(Function) */ jQuery.fn = jQuery.prototype = { @@ -194,7 +181,7 @@ jQuery.fn = jQuery.prototype = { jquery: "@VERSION", /** - * The number of elements currently matched. + * The number of elements currently matched. The size function will return the same value. * * @example $("img").length; * @before @@ -207,7 +194,8 @@ jQuery.fn = jQuery.prototype = { */ /** - * The number of elements currently matched. + * Get the number of elements currently matched. This returns the same + * number as the 'length' property of the jQuery object. * * @example $("img").size(); * @before @@ -224,13 +212,16 @@ jQuery.fn = jQuery.prototype = { length: 0, /** - * Access all matched elements. This serves as a backwards-compatible + * Access all matched DOM elements. 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. + * * @example $("img").get(); * @before * @result [ ] + * @desc Selects all images in the document and returns the DOM Elements as an Array * * @name get * @type Array @@ -238,12 +229,14 @@ jQuery.fn = jQuery.prototype = { */ /** - * Access a single matched element. num is used to access the - * Nth element matched. + * Access a single matched DOM element at a specified index in the matched set. + * This allows you to extract the actual DOM element and operate on it + * directly without necessarily using jQuery functionality on it. * - * @example $("img").get(1); + * @example $("img").get(0); * @before - * @result [ ] + * @result + * @desc Selects all images in the document and returns the first one * * @name get * @type Element @@ -264,24 +257,24 @@ jQuery.fn = jQuery.prototype = { * Set the jQuery object to an array of elements, while maintaining * the stack. * - * @example $("img").set([ document.body ]); - * @result $("img").set() == [ document.body ] + * @example $("img").pushStack([ document.body ]); + * @result $("img").pushStack() == [ document.body ] * * @private - * @name set + * @name pushStack * @type jQuery * @param Elements elems An array of elements * @cat Core */ - set: function( a ) { - var ret = jQuery(this); + pushStack: function( a ) { + var ret = jQuery(a); ret.prevObject = this; - return ret.setArray( a ); + return ret; }, /** * Set the jQuery object to an array of elements. This operation is - * completely destructive - be sure to use .set() if you wish to maintain + * completely destructive - be sure to use .pushStack() if you wish to maintain * the jQuery stack. * * @example $("img").setArray([ document.body ]); @@ -303,11 +296,11 @@ jQuery.fn = jQuery.prototype = { * Execute a function within the context of every matched element. * 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 element. + * 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. + * set (integer, zero-index). * * @example $("img").each(function(i){ * this.src = "test" + i + ".jpg"; @@ -330,21 +323,24 @@ jQuery.fn = jQuery.prototype = { * the index of the element, if found, starting with zero. * Returns -1 if the object wasn't found. * - * @example $("*").index(document.getElementById('foobar')) - * @before
+ * @example $("*").index( $('#foobar')[0] ) + * @before
* @result 0 + * @desc Returns the index for the element with ID foobar * - * @example $("*").index(document.getElementById('foo')) - * @before
+ * @example $("*").index( $('#foo')[0] ) + * @before
* @result 2 + * @desc Returns the index for the element with ID foo within another element * - * @example $("*").index(document.getElementById('bar')) - * @before
+ * @example $("*").index( $('#bar')[0] ) + * @before
* @result -1 + * @desc Returns -1, as there is no element with ID bar * * @name index * @type Number - * @param Object obj Object to search for + * @param Element subject Object to search for * @cat Core */ index: function( obj ) { @@ -360,14 +356,18 @@ jQuery.fn = jQuery.prototype = { * 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. + * * @example $("img").attr("src"); * @before * @result test.jpg + * @desc Returns the src attribute from the first image in the document. * * @name attr * @type Object * @param String name The name of the property to access. - * @cat DOM + * @cat DOM/Attributes */ /** @@ -379,11 +379,12 @@ jQuery.fn = jQuery.prototype = { * @example $("img").attr({ src: "test.jpg", alt: "Test Image" }); * @before * @result Test Image + * @desc Sets src and alt attributes to all images. * * @name attr * @type jQuery * @param Map properties Key/value pairs to set as object properties. - * @cat DOM + * @cat DOM/Attributes */ /** @@ -396,36 +397,60 @@ jQuery.fn = jQuery.prototype = { * @example $("img").attr("src","test.jpg"); * @before * @result + * @desc Sets src attribute to all images. * * @name attr * @type jQuery * @param String key The name of the property to set. * @param Object value The value to set the property to. - * @cat DOM + * @cat DOM/Attributes + */ + + /** + * Set a single property to a computed value, on all matched elements. + * + * Instead of supplying a string value as described + * [[DOM/Attributes#attr.28_key.2C_value_.29|above]], + * a function is provided that computes the value. + * + * @example $("img").attr("title", function() { return this.src }); + * @before + * @result + * @desc Sets title attribute from src attribute. + * + * @example $("img").attr("title", function(index) { return this.title + (i + 1); }); + * @before + * @result + * @desc Enumerate title attribute. + * + * @name attr + * @type jQuery + * @param String key The name of the property to set. + * @param Function value A function returning the value to set. + * Scope: Current element, argument: Index of current element + * @cat DOM/Attributes */ attr: function( key, value, type ) { + var obj = key; + + // Look for the case where we're accessing a style value + if ( key.constructor == String ) + if ( value == undefined ) + return this.length && jQuery[ type || "attr" ]( this[0], key ) || undefined; + else { + obj = {}; + obj[ key ] = value; + } + // Check to see if we're setting style values - return typeof key != "string" || value != undefined ? - this.each(function(){ - // See if we're setting a hash of styles - if ( value == undefined ) - // Set all the styles - for ( var prop in key ) - jQuery.attr( - type ? this.style : this, - prop, key[prop] - ); - - // See if we're setting a single key/value style - else - jQuery.attr( - type ? this.style : this, - key, value - ); - }) : - - // Look for the case where we're accessing a style value - jQuery[ type || "attr" ]( this[0], key ); + return this.each(function(index){ + // Set all the styles + for ( var prop in obj ) + jQuery.attr( + type ? this.style : this, + prop, jQuery.prop(this, obj[prop], type, index, prop) + ); + }); }, /** @@ -435,21 +460,16 @@ jQuery.fn = jQuery.prototype = { * * @example $("p").css("color"); * @before

Test Paragraph.

- * @result red + * @result "red" * @desc Retrieves the color style of the first paragraph * - * @example $("p").css("fontWeight"); + * @example $("p").css("font-weight"); * @before

Test Paragraph.

- * @result bold + * @result "bold" * @desc Retrieves the font-weight style of the first paragraph. - * Note that for all style properties with a dash (like 'font-weight'), you have to - * write it in camelCase. In other words: Every time you have a '-' in a - * property, remove it and replace the next character with an uppercase - * representation of itself. Eg. fontWeight, fontSize, fontFamily, borderWidth, - * borderStyle, borderBottomWidth etc. * * @name css - * @type Object + * @type String * @param String name The name of the property to access. * @cat CSS */ @@ -463,6 +483,7 @@ jQuery.fn = jQuery.prototype = { * @example $("p").css({ color: "red", background: "blue" }); * @before

Test Paragraph.

* @result

Test Paragraph.

+ * @desc Sets color and background styles to all p elements. * * @name css * @type jQuery @@ -472,16 +493,22 @@ jQuery.fn = jQuery.prototype = { /** * Set a single style property to a value, on all matched elements. + * If a number is provided, it is automatically converted into a pixel value. * * @example $("p").css("color","red"); * @before

Test Paragraph.

* @result

Test Paragraph.

* @desc Changes the color of all paragraphs to red * + * @example $("p").css("left",30); + * @before

Test Paragraph.

+ * @result

Test Paragraph.

+ * @desc Changes the left of all paragraphs to "30px" + * * @name css * @type jQuery * @param String key The name of the property to set. - * @param Object value The value to set the property to. + * @param String|Number value The value to set the property to. * @cat CSS */ css: function( key, value ) { @@ -489,48 +516,53 @@ jQuery.fn = jQuery.prototype = { }, /** - * Retrieve the text contents of all matched elements. The result is + * Get the text contents of all matched elements. The result is * a string that contains the combined text contents of all matched * elements. This method works on both HTML and XML documents. * * @example $("p").text(); - * @before

Test Paragraph.

- * @result Test Paragraph. + * @before

Test Paragraph.

Paraparagraph

+ * @result Test Paragraph.Paraparagraph + * @desc Gets the concatenated text of all paragraphs * * @name text * @type String - * @cat DOM + * @cat DOM/Attributes */ /** - * Set the text contents of all matched elements. This has the same - * effect as calling .html() with your specified string. + * Set the text contents of all matched elements. * - * @example $("p").text("Some new text."); + * Similar to html(), but escapes HTML (replace "<" and ">" with their + * HTML entities). + * + * @example $("p").text("Some new text."); * @before

Test Paragraph.

- * @result

Some new text.

+ * @result

<b>Some</b> new text.

+ * @desc Sets the text of all paragraphs. * - * @param String val The text value to set the contents of the element to. + * @example $("p").text("Some new text.", true); + * @before

Test Paragraph.

+ * @result

Some new text.

+ * @desc Sets the text of all paragraphs. * * @name text * @type String - * @cat DOM + * @param String val The text value to set the contents of the element to. + * @cat DOM/Attributes */ text: function(e) { - // A surprisingly high number of people expect the - // .text() method to do this, so lets do it! if ( typeof e == "string" ) - return this.html( e ); + return this.empty().append( document.createTextNode( e ) ); - e = e || this; var t = ""; - for ( var j = 0, el = e.length; j < el; j++ ) { - var r = e[j].childNodes; - for ( var i = 0, rl = r.length; i < rl; i++ ) - if ( r[i].nodeType != 8 ) - t += r[i].nodeType != 1 ? - r[i].nodeValue : jQuery.fn.text([ r[i] ]); - } + jQuery.each( e || this, function(){ + jQuery.each( this.childNodes, function(){ + if ( this.nodeType != 8 ) + t += this.nodeType != 1 ? + this.nodeValue : jQuery.fn.text([ this ]); + }); + }); return t; }, @@ -577,7 +609,7 @@ jQuery.fn = jQuery.prototype = { * * @name wrap * @type jQuery - * @param Element elem A DOM element that will be wrapped. + * @param Element elem A DOM element that will be wrapped around the target. * @cat DOM/Manipulation */ wrap: function() { @@ -610,14 +642,17 @@ jQuery.fn = jQuery.prototype = { * @example $("p").append("Hello"); * @before

I would like to say:

* @result

I would like to say: Hello

+ * @desc Appends some HTML to all paragraphs. * * @example $("p").append( $("#foo")[0] ); * @before

I would like to say:

Hello * @result

I would like to say: Hello

+ * @desc Appends an Element to all paragraphs. * * @example $("p").append( $("b") ); * @before

I would like to say:

Hello * @result

I would like to say: Hello

+ * @desc Appends a jQuery object (similar to an Array of DOM Elements) to all paragraphs. * * @name append * @type jQuery @@ -642,14 +677,17 @@ jQuery.fn = jQuery.prototype = { * @example $("p").prepend("Hello"); * @before

I would like to say:

* @result

HelloI would like to say:

+ * @desc Prepends some HTML to all paragraphs. * * @example $("p").prepend( $("#foo")[0] ); * @before

I would like to say:

Hello * @result

HelloI would like to say:

+ * @desc Prepends an Element to all paragraphs. * * @example $("p").prepend( $("b") ); * @before

I would like to say:

Hello * @result

HelloI would like to say:

+ * @desc Prepends a jQuery object (similar to an Array of DOM Elements) to all paragraphs. * * @name prepend * @type jQuery @@ -671,14 +709,17 @@ jQuery.fn = jQuery.prototype = { * @example $("p").before("Hello"); * @before

I would like to say:

* @result Hello

I would like to say:

+ * @desc Inserts some HTML before all paragraphs. * * @example $("p").before( $("#foo")[0] ); * @before

I would like to say:

Hello * @result Hello

I would like to say:

+ * @desc Inserts an Element before all paragraphs. * * @example $("p").before( $("b") ); * @before

I would like to say:

Hello * @result Hello

I would like to say:

+ * @desc Inserts a jQuery object (similar to an Array of DOM Elements) before all paragraphs. * * @name before * @type jQuery @@ -700,14 +741,17 @@ jQuery.fn = jQuery.prototype = { * @example $("p").after("Hello"); * @before

I would like to say:

* @result

I would like to say:

Hello + * @desc Inserts some HTML after all paragraphs. * * @example $("p").after( $("#foo")[0] ); * @before Hello

I would like to say:

* @result

I would like to say:

Hello + * @desc Inserts an Element after all paragraphs. * * @example $("p").after( $("b") ); * @before Hello

I would like to say:

* @result

I would like to say:

Hello + * @desc Inserts a jQuery object (similar to an Array of DOM Elements) after all paragraphs. * * @name after * @type jQuery @@ -724,15 +768,22 @@ jQuery.fn = jQuery.prototype = { }, /** - * End the most recent 'destructive' operation, reverting the list of matched elements - * back to its previous state. After an end operation, the list of matched elements will - * revert to the last state of matched elements. + * Revert the most recent 'destructive' operation, changing the set of matched elements + * to its previous state (right before the destructive operation). * * 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. These functions are: add, + * children, clone, filter, + * find, not, next, + * parent, parents, prev and siblings. + * * @example $("p").find("span").end(); * @before

Hello, how are you?

- * @result $("p").find("span").end() == [

...

] + * @result [

...

] + * @desc Selects all paragraphs, finds span elements inside these, and reverts the + * selection back to the paragraphs. * * @name end * @type jQuery @@ -744,7 +795,8 @@ jQuery.fn = jQuery.prototype = { /** * Searches for all elements that match the specified expression. - * This method is the optimal way of finding additional descendant + + * This method is a good way to find additional descendant * elements with which to process. * * All searching is done using a jQuery expression. The expression can be @@ -752,7 +804,9 @@ jQuery.fn = jQuery.prototype = { * * @example $("p").find("span"); * @before

Hello, how are you?

- * @result $("p").find("span") == [ Hello ] + * @result [ Hello ] + * @desc Starts with all paragraphs and searches for descendant span + * elements, same as $("p span") * * @name find * @type jQuery @@ -760,47 +814,55 @@ jQuery.fn = jQuery.prototype = { * @cat DOM/Traversing */ find: function(t) { - return this.set( jQuery.map( this, function(a){ + return this.pushStack( jQuery.map( this, function(a){ return jQuery.find(t,a); - }) ); + }), t ); }, /** - * Create cloned copies of all matched DOM Elements. This does - * not create a cloned copy of this particular jQuery object, - * instead it creates duplicate copies of all DOM Elements. + * Clone matched DOM Elements and select the clones. + * * This is useful for moving copies of the elements to another * location in the DOM. * * @example $("b").clone().prependTo("p"); * @before Hello

, how are you?

* @result Hello

Hello, how are you?

+ * @desc Clones all b elements (and selects the clones) and prepends them to all paragraphs. * * @name clone * @type jQuery + * @param Boolean deep (Optional) Set to false if you don't want to clone all descendant nodes, in addition to the element itself. * @cat DOM/Manipulation */ clone: function(deep) { - return this.set( jQuery.map( this, function(a){ - return a.cloneNode( deep != undefined ? deep : true ); + return this.pushStack( jQuery.map( this, function(a){ + var a = a.cloneNode( deep != undefined ? deep : true ); + a.$events = null; // drop $events expando to avoid firing incorrect events + return a; }) ); }, /** * Removes all elements from the set of matched elements that do not - * match the specified expression. This method is used to narrow down + * match the specified expression(s). This method is used to narrow down * the results of a search. * - * All searching is done using a jQuery expression. The expression - * can be written using CSS 1-3 Selector syntax, or basic XPath. + * Provide a comma-separated list of expressions to apply multiple filters at once. * * @example $("p").filter(".selected") * @before

Hello

How are you?

* @result [

Hello

] + * @desc Selects all paragraphs and removes those without a class "selected". + * + * @example $("p").filter(".selected, :first") + * @before

Hello

Hello Again

And Again

+ * @result [

Hello

,

And Again

] + * @desc Selects all paragraphs and removes those without class "selected" and being the first one. * * @name filter * @type jQuery - * @param String expr An expression to search with. + * @param String expression Expression(s) to search with. * @cat DOM/Traversing */ @@ -809,11 +871,8 @@ jQuery.fn = jQuery.prototype = { * pass the specified filter. This method is used to narrow down * the results of a search. * - * The elements to filter are passed as the first argument, their - * index inside the set as the second. - * - * @example $("p").filter(function(element, index) { - * return $("ol", element).length == 0; + * @example $("p").filter(function(index) { + * return $("ol", this).length == 0; * }) * @before

  1. Hello

How are you?

* @result [

How are you?

] @@ -824,51 +883,24 @@ jQuery.fn = jQuery.prototype = { * @param Function filter A function to use for filtering * @cat DOM/Traversing */ - - /** - * Removes all elements from the set of matched elements that do not - * match at least one of the expressions passed to the function. This - * method is used when you want to filter the set of matched elements - * through more than one expression. - * - * Elements will be retained in the jQuery object if they match at - * least one of the expressions passed. - * - * @example $("p").filter([".selected", ":first"]) - * @before

Hello

Hello Again

And Again

- * @result [

Hello

,

And Again

] - * - * @name filter - * @type jQuery - * @param Array exprs A set of expressions to evaluate against - * @cat DOM/Traversing - */ filter: function(t) { - return this.set( - t.constructor == Array && - jQuery.map(this,function(a){ - for ( var i = 0, tl = t.length; i < tl; i++ ) - if ( jQuery.filter(t[i],[a]).r.length ) - return a; - return null; + return this.pushStack( + jQuery.isFunction( t ) && + jQuery.grep(this, function(el, index){ + return t.apply(el, [index]) }) || - t.constructor == Boolean && - ( t ? this.get() : [] ) || - - typeof t == "function" && - jQuery.grep( this, t ) || - - jQuery.filter(t,this).r ); + jQuery.multiFilter(t,this) ); }, /** * Removes the specified Element from the set of matched elements. This * method is used to remove a single Element from a jQuery object. * - * @example $("p").not( document.getElementById("selected") ) + * @example $("p").not( $("#selected")[0] ) * @before

Hello

Hello Again

* @result [

Hello

] + * @desc Removes the element with the ID "selected" from the set of all paragraphs. * * @name not * @type jQuery @@ -884,71 +916,112 @@ jQuery.fn = jQuery.prototype = { * @example $("p").not("#selected") * @before

Hello

Hello Again

* @result [

Hello

] + * @desc Removes the element with the ID "selected" from the set of all paragraphs. * * @name not * @type jQuery * @param String expr An expression with which to remove matching elements * @cat DOM/Traversing */ + + /** + * Removes any elements inside the array of elements from the set + * of matched elements. This method is used to remove one or more + * elements from a jQuery object. + * + * Please note: the expression cannot use a reference to the + * element name. See the two examples below. + * + * @example $("p").not( $("div p.selected") ) + * @before

Hello

Hello Again

+ * @result [

Hello

] + * @desc Removes all elements that match "div p.selected" from the total set of all paragraphs. + * + * @name not + * @type jQuery + * @param jQuery elems A set of elements to remove from the jQuery set of matched elements. + * @cat DOM/Traversing + */ not: function(t) { - return this.set( typeof t == "string" ? - jQuery.filter(t,this,true).r : - jQuery.grep(this,function(a){ return a != t; }) ); + return this.pushStack( + t.constructor == String && + jQuery.multiFilter(t, this, true) || + + jQuery.grep(this, function(a) { + return ( t.constructor == Array || t.jquery ) + ? jQuery.inArray( a, t ) < 0 + : a != t; + }) + ); }, /** - * Adds the elements matched by the expression to the jQuery object. This - * can be used to concatenate the result sets of two expressions. + * Adds more elements, matched by the given expression, + * to the set of matched elements. * * @example $("p").add("span") - * @before

Hello

Hello Again

- * @result [

Hello

, Hello Again ] + * @before (HTML)

Hello

Hello Again + * @result (jQuery object matching 2 elements) [

Hello

, Hello Again ] + * @desc Compare the above result to the result of $('p'), + * which would just result in [

Hello

]
. + * Using add(), matched elements of $('span') are simply + * added to the returned jQuery-object. * * @name add * @type jQuery * @param String expr An expression whose matched elements are added * @cat DOM/Traversing */ - + /** - * Adds each of the Elements in the array to the set of matched elements. - * This is used to add a set of Elements to a jQuery object. + * Adds more elements, created on the fly, to the set of + * matched elements. * - * @example $("p").add([document.getElementById("a"), document.getElementById("b")]) - * @before

Hello

Hello AgainAnd Again

- * @result [

Hello

, Hello Again, And Again ] + * @example $("p").add("Again") + * @before

Hello

+ * @result [

Hello

, Again ] * * @name add * @type jQuery - * @param Array els An array of Elements to add + * @param String html A string of HTML to create on the fly. * @cat DOM/Traversing */ /** - * Adds a single Element to the set of matched elements. This is used to - * add a single Element to a jQuery object. + * Adds one or more Elements to the set of matched elements. * * @example $("p").add( document.getElementById("a") ) * @before

Hello

Hello Again

* @result [

Hello

, Hello Again ] * + * @example $("p").add( document.forms[0].elements ) + * @before

Hello