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
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.
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.