Query
query
¶
A DOMQuery is a set of DOM nodes associated with a given CSS selector.
This set of nodes may be further filtered with the filter method. Additional methods apply actions to the nodes in the query.
If this sounds like JQuery, a (once) popular JS library, it is no coincidence.
DOMQuery objects are typically created by Widget.query method.
Queries are lazy. Results will be calculated at the point you iterate over the query, or call a method which evaluates the query, such as first() and last().
DOMQuery
¶
Bases: Generic[QueryType]
nodes: list[QueryType]
property
¶
Lazily evaluate nodes.
add_class(*class_names)
¶
Add the given class name(s) to nodes.
exclude(selector)
¶
filter(selector)
¶
first(expect_type=None)
¶
Get the first matching node.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
expect_type |
type[ExpectType] | None
|
Require matched node is of this type, or None for any type. Defaults to None. |
None
|
Raises:
Type | Description |
---|---|
WrongType
|
If the wrong type was found. |
NoMatches
|
If there are no matching nodes in the query. |
Returns:
Type | Description |
---|---|
QueryType | ExpectType
|
The matching Widget. |
last(expect_type=None)
¶
Get the last matching node.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
expect_type |
type[ExpectType] | None
|
Require matched node is of this type, or None for any type. Defaults to None. |
None
|
Raises:
Type | Description |
---|---|
WrongType
|
If the wrong type was found. |
NoMatches
|
If there are no matching nodes in the query. |
Returns:
Type | Description |
---|---|
QueryType | ExpectType
|
The matching Widget. |
only_one(expect_type=None)
¶
Get the only matching node.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
expect_type |
type[ExpectType] | None
|
Require matched node is of this type, or None for any type. Defaults to None. |
None
|
Raises:
Type | Description |
---|---|
WrongType
|
If the wrong type was found. |
NoMatches
|
If no node matches the query. |
TooManyMatches
|
If there is more than one matching node in the query. |
Returns:
Type | Description |
---|---|
Widget | ExpectType
|
The matching Widget. |
refresh(*, repaint=True, layout=False)
¶
remove()
¶
Remove matched nodes from the DOM.
Returns:
Type | Description |
---|---|
AwaitRemove
|
An awaitable object that waits for the widgets to be removed. |
remove_class(*class_names)
¶
Remove the given class names from the nodes.
results(filter_type=None)
¶
Get query results, optionally filtered by a given type.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
filter_type |
type[ExpectType] | None
|
A Widget class to filter results, or None for no filter. Defaults to None. |
None
|
Yields:
Type | Description |
---|---|
Iterator[Widget | ExpectType]
|
Iterator[Widget | ExpectType]: An iterator of Widget instances. |
set_class(add, *class_names)
¶
set_styles(css=None, **update_styles)
¶
Set styles on matched nodes.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
css |
str | None
|
CSS declarations to parser, or None. Defaults to None. |
None
|
toggle_class(*class_names)
¶
Toggle the given class names from matched nodes.
InvalidQueryFormat
¶
Bases: QueryError
Query did not parse correctly.
NoMatches
¶
Bases: QueryError
No nodes matched the query.
TooManyMatches
¶
Bases: QueryError
Too many nodes matched the query.
WrongType
¶
Bases: QueryError
Query result was not of the correct type.