ElementQuery abstract class
A query object of a collection of Element.
abstract class ElementQuery extends DQuery<Element> {
factory ElementQuery(List<Element> elements) => new _ElementQuery(elements);
// traversing //
/** Retrieve the closest ancestor (including itself) of each element in this
* collection respectively who matches the given [selector].
*/
ElementQuery closest(String selector);
/** Retrieve the parents of each element in this collection.
* + The redundant elements in the resulting collection will be removed.
* + If [selector] is provided, parents who do not match the selector is
* filtered out.
*/
ElementQuery parent([String selector]);
/** Retrieve the union of childrens of each element in this collection.
* + If [selector] is provided, children who do not match the selector is
* filtered out.
*/
ElementQuery children([String selector]);
// DOM attribute manipulation //
/** Show all the elements in this collection by changing their CSS display
* properties.
*/
void show();
/** Hide all the elements in this collection by setting their CSS disaply
* properties value to [none].
*/
void hide();
/** Toggle the visibility of all the elements in this collection by altering
* their CSS display properties.
*/
void toggle([bool state]);
/** Get the style property value of the given [name] on the first element
* in this collection if any, or set the [value] on all the elements in
* this collection.
*
* + if [value] is provided, set the value; otherwise read the value.
*/
css(String name, [String value]);
// class manipulation //
/** Return true if any of the element contains the given [name] in its CSS
* classes.
*/
bool hasClass(String name);
/** Add the CSS class of given [name] to all the elements in this collection.
*/
void addClass(String name);
/** Remove the CSS class of given [name] from all the elements in this collection.
*/
void removeClass(String name);
/** Toggle the CSS class of given [name] in all the elements in this collection.
*/
void toggleClass(String name);
// DOM element manipulation //
/** Insert every element in this collection to the end of the [target].
* If [target] refers to multiple elements, the inserted content will be
* cloned. In such cases, the fragment inserted to the last element in target
* will be the original content.
*
* + [target] can be a selector String, an html String, an Element, or an
* [ElementQuery].
*/
void appendTo(target);
/** Insert every element in this collection to the beginning of the [target].
* If [target] refers to multiple elements, the inserted content will be
* cloned. In such cases, the fragment inserted to the last element in target
* will be the original content.
*
* + [target] can be a selector String, an html String, an Element, or an
* [ElementQuery].
*/
void prependTo(target);
/** Insert [content] to the end of each element in this collection.
* If this collection contains multiple elements, the inserted content will
* be cloned. In such cases, the fragment inserted to the last element in this
* collection will be the original content.
*
* + [content] can be an html String, an Element, or an [ElementQuery].
*/
void append(content);
/** Insert [content] to the beginning of each element in this collection.
* If this collection contains multiple elements, the inserted content will
* be cloned. In such cases, the fragment inserted to the last element in this
* collection will be the original content.
*
* + [content] can be an html String, an Element, or an [ElementQuery].
*/
void prepend(content);
/** Insert [content] before each element in this collection.
* If this collection contains multiple elements, the inserted content will
* be cloned. In such cases, the fragment inserted to the last element in this
* collection will be the original content.
*
* + [content] can be an html String, an Element, or an [ElementQuery].
*/
void before(content);
/** Insert [content] after each element in this collection.
* If this collection contains multiple elements, the inserted content will
* be cloned. In such cases, the fragment inserted to the last element in this
* collection will be the original content.
*
* + [content] can be an html String, an Element, or an [ElementQuery].
*/
void after(content);
//.replaceAll()
//.replaceWith()
//.unwrap()
//.wrap()
//.wrapAll()
//.wrapInner()
/** Create a deep copy of the elements in this collection.
*
* + If [withDataAndEvents] is true, the [data] on the elements are cloned as
* well. Default: false.
*
* + In addition to above, is [deepWithDataAndEvents] is also true, the [data]
* on the descendants of the elements are also cloned. Default: same as
* [withDataAndEvents].
*/
ElementQuery clone([bool withDataAndEvents, bool deepWithDataAndEvents]);
/** Remove the elements from the DOM.
*
* + If [data] is true, also remove associtated data under all elements and
* decendants.
*/
void detach({String selector, bool data: true});
/** Remove all child nodes of the elements in this collection from the DOM.
*/
void empty();
/** Get the combined text contents over all elements in this collection.
*/
String get text;
/** Set the text contents for all elements in this collection.
*/
void set text(String value);
/** Get the inner HTML contents of the first element.
*/
String get html;
/** Set the inner HTML contents for all elements in this collection.
*/
void set html(String value);
// offset //
/** Get the current coordinates of the first element, relative to the document.
*/
Point get offset;
/** Set the coordinates of every element in this collection, relative to the
* document.
*/
void set offset(Point offset);
/** Set the x coordinate of every element in this collection, relative to the
* document.
*/
void set offsetLeft(int left);
/** Set the y coordinate of every element in this collection, relative to the
* document.
*/
void set offsetTop(int top);
/** Get the current coordinates of the first element in the set of matched
* elements, relative to the offset parent.
*/
Point get position;
/** Get the closest ancestor element that is positioned.
*/
ElementQuery get offsetParent;
}
Extends
DQuery<Element> > ElementQuery
Constructors
factory ElementQuery(List<Element> elements) #
factory ElementQuery(List<Element> elements) => new _ElementQuery(elements);
Properties
final context #
The DOM node context originally passed to DQuery; if none was passed then context will likely be the document.
get context;
final E first #
Returns the first element.
If this is empty throws a StateError. Otherwise this method is
equivalent to this.elementAt(0)
E get first;
final T firstIfAny #
Return the first matched element, or null if empty.
T get firstIfAny;
final int height #
Retrieve the height of the first element of this collection.
int get height;
abstract String get html #
Get the inner HTML contents of the first element.
abstract void set html(String value) #
Set the inner HTML contents for all elements in this collection.
final bool isEmpty #
Returns true if there is no element in this collection.
bool get isEmpty;
final bool isNotEmpty #
Returns true if there is at least one element in this collection.
bool get isNotEmpty;
final Iterator<E> iterator #
Returns an Iterator that iterates over this Iterable object.
Iterator<E> get iterator;
final E last #
Returns the last element.
If this is empty throws a StateError.
E get last;
abstract int get length #
Returns the number of elements in the list.
The valid indices for a list are 0 through length - 1.
abstract void set length(int newLength) #
Changes the length of the list. If
newLength is greater than
the current length, entries are initialized to null.
Throws an UnsupportedError if the list is not extendable.
abstract Point get offset #
Get the current coordinates of the first element, relative to the document.
abstract void set offset(Point offset) #
Set the coordinates of every element in this collection, relative to the document.
abstract void set offsetLeft(int left) #
Set the x coordinate of every element in this collection, relative to the document.
final ElementQuery offsetParent #
Get the closest ancestor element that is positioned.
ElementQuery get offsetParent;
abstract void set offsetTop(int top) #
Set the y coordinate of every element in this collection, relative to the document.
final Point position #
Get the current coordinates of the first element in the set of matched elements, relative to the offset parent.
Point get position;
final Iterable<E> reversed #
Returns an Iterable of the elements of this List in reverse order.
Iterable<E> get reversed;
abstract int get scrollLeft #
Get the current horizontal position of the scroll bar for the first element in this collection.
abstract void set scrollLeft(int value) #
Set the current horizontal position of the scroll bar for all elements in this collection.
abstract int get scrollTop #
Get the current vertical position of the scroll bar for the first element in this collection.
abstract void set scrollTop(int value) #
Set the current vertical position of the scroll bar for all elements in this collection.
final E single #
Returns the single element in this.
If this is empty or has more than one element throws a StateError.
E get single;
abstract String get text #
Get the combined text contents over all elements in this collection.
abstract void set text(String value) #
Set the text contents for all elements in this collection.
Operators
Methods
abstract void add(E value) #
Adds value at the end of the list, extending the length by one.
Throws an UnsupportedError if the list is not extendable.
abstract void addAll(Iterable<E> iterable) #
Appends all elements of the iterable to the end of this list.
Extends the length of the list by the number of elements in
iterable.
Throws an UnsupportedError if this list is not extensible.
abstract void addClass(String name) #
Add the CSS class of given name to all the elements in this collection.
abstract void after(content) #
Insert content after each element in this collection. If this collection contains multiple elements, the inserted content will be cloned. In such cases, the fragment inserted to the last element in this collection will be the original content.
- content can be an html String, an Element, or an ElementQuery.
abstract bool any(bool test(E element)) #
Returns true if one element of this collection satisfies the predicate test. Returns false otherwise.
abstract void append(content) #
Insert content to the end of each element in this collection. If this collection contains multiple elements, the inserted content will be cloned. In such cases, the fragment inserted to the last element in this collection will be the original content.
- content can be an html String, an Element, or an ElementQuery.
abstract void appendTo(target) #
Insert every element in this collection to the end of the target. If target refers to multiple elements, the inserted content will be cloned. In such cases, the fragment inserted to the last element in target will be the original content.
-
target can be a selector String, an html String, an Element, or an ElementQuery.
abstract Map<int, E> asMap() #
Returns an unmodifiable Map view of this.
It has the indices of this list as keys, and the corresponding elements as values. The [Map.keys] [Iterable] will iterate the indices of this list in numerical order.
abstract void before(content) #
Insert content before each element in this collection. If this collection contains multiple elements, the inserted content will be cloned. In such cases, the fragment inserted to the last element in this collection will be the original content.
- content can be an html String, an Element, or an ElementQuery.
abstract ElementQuery children([String selector]) #
Retrieve the union of childrens of each element in this collection. + If selector is provided, children who do not match the selector is filtered out.
abstract void clear() #
Removes all elements in the list.
The length of the list becomes zero.
Throws an UnsupportedError, and retains all elements, if the
length of the list cannot be changed.
abstract ElementQuery clone([bool withDataAndEvents, bool deepWithDataAndEvents]) #
Create a deep copy of the elements in this collection.
-
If withDataAndEvents is true, the
dataon the elements are cloned as well. Default: false. -
In addition to above, is deepWithDataAndEvents is also true, the
dataon the descendants of the elements are also cloned. Default: same as withDataAndEvents.
abstract ElementQuery closest(String selector) #
Retrieve the closest ancestor (including itself) of each element in this collection respectively who matches the given selector.
abstract bool contains(E element) #
Check whether the collection contains an element equal to element.
abstract dynamic css(String name, [String value]) #
Get the style property value of the given name on the first element in this collection if any, or set the value on all the elements in this collection.
- if value is provided, set the value; otherwise read the value.
abstract void detach({String selector, bool data: true}) #
Remove the elements from the DOM.
-
If data is true, also remove associtated data under all elements and decendants.
abstract E elementAt(int index) #
Returns the indexth element.
If this has fewer than
index elements throws a RangeError.
Note: if this does not have a deterministic iteration order then the
function may simply return any element without any iteration if there are
at least
index elements in this.
abstract void empty() #
Remove all child nodes of the elements in this collection from the DOM.
abstract bool every(bool test(E element)) #
Returns true if every elements of this collection satisify the
predicate
test. Returns false otherwise.
abstract Iterable expand(Iterable f(E element)) #
Expand each element of this Iterable into zero or more elements.
The resulting Iterable will run through the elements returned by f for each element of this, in order.
The returned Iterable is lazy, and will call
f for each element
of this every time it's iterated.
abstract void fillRange(int start, int end, [E fillValue]) #
Sets the elements in the range start to end exclusive to the given fillValue.
It is an error if
start..
end is not a valid range pointing into the
this.
abstract ElementQuery find(String selector) #
Retrieve an ElementQuery containing descendants of this element collection which match the given selector.
abstract E firstWhere(bool test(E element), {E orElse()}) #
Returns the first element that satisfies the given predicate test.
If none matches, the result of invoking the
orElse function is
returned. By default, when
orElse is null, a StateError is
thrown.
abstract dynamic fold(initialValue, combine(previousValue, E element)) #
Reduces a collection to a single value by iteratively combining each element of the collection with an existing value using the provided function.
Use initialValue as the initial value, and the function combine to create a new value from the previous one and an element.
Example of calculating the sum of an iterable:
iterable.fold(0, (prev, element) => prev + element);
abstract void forEach(void f(E element)) #
Applies the function f to each element of this collection.
abstract Iterable<E> getRange(int start, int end) #
Returns an Iterable that iterators over the elements in the range
start to
end exclusive. The result of this function
is backed by this.
It is an error if end is before start.
It is an error if the
start and
end are not valid ranges at the time
of the call to this method. The returned Iterable behaves similar to
skip(start).take(end - start). That is, it will not throw exceptions
if this changes size.
Example:
var list = [1, 2, 3, 4, 5];
var range = list.getRange(1, 4);
print(range.join(', ')); // => 2, 3, 4
list.length = 3;
print(range.join(', ')); // => 2, 3
abstract bool hasClass(String name) #
Return true if any of the element contains the given name in its CSS classes.
abstract void hide() #
Hide all the elements in this collection by setting their CSS disaply
properties value to none.
abstract int indexOf(E element, [int start = 0]) #
Returns the first index of element in the list.
Searches the list from index
start to the length of the list.
The first time an element e is encountered so that e == element,
the index of e is returned.
Returns -1 if
element is not found.
abstract void insert(int index, E element) #
Inserts the element at position index in the list.
This increases the length of the list by one and shifts all elements at or after the index towards the end of the list.
It is an error if the index does not point inside the list or at the position after the last element.
abstract void insertAll(int index, Iterable<E> iterable) #
Inserts all elements of iterable at position index in the list.
This increases the length of the list by the length of iterable and shifts all later elements towards the end of the list.
It is an error if the index does not point inside the list or at the position after the last element.
String join([String separator = ""]) #
Converts each element to a String and concatenates the strings.
Converts each element to a String by calling Object.toString on it.
Then concatenates the strings, optionally separated by the
separator
string.
String join([String separator = ""]) {
StringBuffer buffer = new StringBuffer();
buffer.writeAll(this, separator);
return buffer.toString();
}
abstract int lastIndexOf(E element, [int start]) #
Returns the last index of element in the list.
Searches the list backwards from index start to 0.
The first time an element e is encountered so that e == element,
the index of e is returned.
If start is not provided, it defaults to this.length - 1.
Returns -1 if element is not found.
abstract E lastWhere(bool test(E element), {E orElse()}) #
Returns the last element that satisfies the given predicate test.
If none matches, the result of invoking the
orElse function is
returned. By default, when
orElse is null, a StateError is
thrown.
abstract Iterable map(f(E element)) #
Returns a lazy Iterable where each element e of this is replaced
by the result of f(e).
This method returns a view of the mapped elements. As long as the
returned Iterable is not iterated over, the supplied function
f will
not be invoked. The transformed elements will not be cached. Iterating
multiple times over the the returned Iterable will invoke the supplied
function
f multiple times on the same element.
abstract void off(String types, {String selector, DQueryEventListener handler}) #
Unregister a handler for events of given types. // TODO
abstract void on(String types, DQueryEventListener handler, {String selector}) #
Register a
handler for events of given
types on selected elements.
+ If
selector is provided, only the descendant elements matched by the
selector will trigger the event. If omitted or null, the event will always
be triggered.
+ If data is provided, you can retrieve it in event.data in the handler.
abstract void one(String types, DQueryEventListener handler, {String selector}) #
Register a one-time
handler for events of given
types. Once called,
the handler will be unregistered.
+ If
selector is provided, only the descendant elements matched by the
selector will trigger the event. If omitted or null, the event will always
be triggered.
+ If data is provided, you can retrieve it in event.data in the handler.
abstract ElementQuery parent([String selector]) #
Retrieve the parents of each element in this collection. + The redundant elements in the resulting collection will be removed. + If selector is provided, parents who do not match the selector is filtered out.
abstract void prepend(content) #
Insert content to the beginning of each element in this collection. If this collection contains multiple elements, the inserted content will be cloned. In such cases, the fragment inserted to the last element in this collection will be the original content.
- content can be an html String, an Element, or an ElementQuery.
abstract void prependTo(target) #
Insert every element in this collection to the beginning of the target. If target refers to multiple elements, the inserted content will be cloned. In such cases, the fragment inserted to the last element in target will be the original content.
-
target can be a selector String, an html String, an Element, or an ElementQuery.
abstract ElementQuery pushStack(List<Element> elems) #
Add a collection of DOM elements onto the DQuery stack.
abstract E reduce(E combine(E value, E element)) #
Reduces a collection to a single value by iteratively combining elements of the collection using the provided function.
Example of calculating the sum of an iterable:
iterable.reduce((value, element) => value + element);
abstract bool remove(Object value) #
Removes value from the list. Returns true if value was in the list. Returns false otherwise. The method has no effect if value value was not in the list.
abstract E removeAt(int index) #
Removes the element at position index from the list.
This reduces the length of this by one and moves all later elements
down by one position.
Returns the removed element.
Throws an ArgumentError if
index is not an int.
Throws an RangeError if the
index does not point inside
the list.
Throws an UnsupportedError, and doesn't remove the element,
if the length of this cannot be changed.
abstract void removeClass(String name) #
Remove the CSS class of given name from all the elements in this collection.
abstract E removeLast() #
Pops and returns the last element of the list.
Throws a UnsupportedError if the length of the
list cannot be changed.
abstract void removeRange(int start, int end) #
Removes the elements in the range start to end exclusive.
It is an error if
start..
end is not a valid range pointing into the
this.
abstract void removeWhere(bool test(E element)) #
Removes all elements of this list that satisfy test.
An elements e satisfies
test if test(e) is true.
abstract void replaceRange(int start, int end, Iterable<E> iterable) #
Removes the elements in the range start to end exclusive and replaces them with the contents of the iterable.
It is an error if
start..
end is not a valid range pointing into the
this.
Example:
var list = [1, 2, 3, 4, 5];
list.replaceRange(1, 3, [6, 7, 8, 9]);
print(list); // [1, 6, 7, 8, 9, 4, 5]
abstract void retainWhere(bool test(E element)) #
Removes all elements of this list that fail to satisfy test.
An elements e satisfies
test if test(e) is true.
abstract void setAll(int index, Iterable<E> iterable) #
Overwrites elements of this with the elemenst of
iterable starting
at position
index in the list.
This operation does not increase the length of this.
It is an error if the index does not point inside the list or at the position after the last element.
It is an error if the
iterable is longer than length -
index.
abstract void setRange(int start, int end, Iterable<E> iterable, [int skipCount = 0]) #
Copies the elements of
iterable, skipping the
skipCount first elements,
into the range
start to
end exclusive of this.
If start equals end and start.. end represents a legal range, this method has no effect.
It is an error if
start..
end is not a valid range pointing into the
this.
It is an error if the iterable does not have enough elements after skipping skipCount elements.
Example:
var list = [1, 2, 3, 4];
var list2 = [5, 6, 7, 8, 9];
list.setRange(1, 3, list2, 3);
print(list); // => [1, 8, 9, 4]
abstract void show() #
Show all the elements in this collection by changing their CSS display properties.
abstract E singleWhere(bool test(E element)) #
Returns the single element that satisfies
test. If no or more than one
element match then a StateError is thrown.
abstract Iterable<E> skip(int n) #
Returns an Iterable that skips the first
n elements.
If this has fewer than
n elements, then the resulting Iterable will
be empty.
abstract Iterable<E> skipWhile(bool test(E value)) #
Returns an Iterable that skips elements while
test is satisfied.
The filtering happens lazily. Every new Iterator of the returned
Iterable iterates over all elements of this.
As long as the iterator's elements satisfy
test they are
discarded. Once an element does not satisfy the
test the iterator stops
testing and uses every later element unconditionally. That is, the elements
of the returned Iterable are the elements of this starting from the
first element that does not satisfy
test.
abstract void sort([int compare(E a, E b)]) #
Sorts the list according to the order specified by the compare function.
The
compare function must act as a Comparator.
The default List implementations use Comparable.compare if
compare is omitted.
abstract List<E> sublist(int start, [int end]) #
Returns a new list containing the elements from start to end.
If
end is omitted, the length of this is used.
It is an error if
start or
end are not indices into this,
or if
end is before
start.
abstract Iterable<E> take(int n) #
Returns an Iterable with at most
n elements.
The returned Iterable may contain fewer than
n elements, if this
contains fewer than
n elements.
abstract Iterable<E> takeWhile(bool test(E value)) #
Returns an Iterable that stops once
test is not satisfied anymore.
The filtering happens lazily. Every new Iterator of the returned
Iterable will start iterating over the elements of this.
When the iterator encounters an element e that does not satisfy
test,
it discards e and moves into the finished state. That is, it will not
ask or provide any more elements.
abstract void toggle([bool state]) #
Toggle the visibility of all the elements in this collection by altering their CSS display properties.
abstract void toggleClass(String name) #
Toggle the CSS class of given name in all the elements in this collection.
abstract List<E> toList({bool growable: true}) #
Creates a List containing the elements of this Iterable.
The elements will be in iteration order. The list is fixed-length if growable is false.
abstract Set<E> toSet() #
Creates a Set containing the elements of this Iterable.
abstract void trigger(String type, {data}) #
Trigger an event of given type on all matched elements, with given data if provided.
abstract void triggerEvent(DQueryEvent event) #
Trigger the given
event on all matched elements, with given data if
provided.
abstract void triggerHandler(String type, {data}) #
Trigger an event of given type on the first (if any) matched element, with given data if provided. However, only the registered handlers will be called, while the default action is omitted.
abstract Iterable<E> where(bool test(E element)) #
Returns a lazy Iterable with all elements that satisfy the
predicate
test.
This method returns a view of the mapped elements. As long as the
returned Iterable is not iterated over, the supplied function
test will
not be invoked. Iterating will not cache results, and thus iterating
multiple times over the the returned Iterable will invoke the supplied
function
test multiple times on the same element.