ElementList

#include <Ultralight/dom/ElementList.h>

Overview

A fixed list of DOM elements returned by a query or an Element::children() call.

Calls like dom::Document::querySelectorAll() and Element::children() return an ElementList to hold matching elements from a page. You use it in native code to inspect and update groups of elements, such as rows in a table or controls in a form.

Querying a table for rows and iterating over the results looks like this:

dom::ElementList scores = document.querySelectorAll("#scores tr");
if (scores.empty())
  Log("no scores yet");
 
for (dom::Element score_row : scores)
  score_row.classList.add("visible");

Snapshot Behavior

An ElementList is a snapshot of elements at the time of the query, unlike live collections on the web. Later changes to the page never add, remove, or reorder entries in the list. Call dom::Document::querySelectorAll() again when you need the current elements.

Removing an element from the page leaves it in the list, and its handle stays valid. Collections like Element::children(), HTMLSelectElement::selectedOptions(), and HTMLFormElement::elements() are live on the web, but return snapshots in the library.

Usage and Lifetime

• Check for no results with empty() or length(). An ElementList has no boolean operator, so writing if (list) doesn't compile.
• An ElementList can't be copied. Transfer ownership with std::move when storing a list in a member variable.
• An ElementList doesn't keep its page alive. When the page navigates away, the list keeps its length, but operations on its Elements fail safely (see dom::Element).

See also

dom::Document::querySelectorAll(), dom::Element::querySelectorAll(), dom::Element::children(), dom::NodeList

Classes
class	iterator
	A forward iterator over the list's elements, so range-for works (for (dom::Element el : list)). More...

Static Public Member Functions
static ElementList	Adopt (ULDOMElementList handle)
	Wrap a C handle you own, taking ownership of it.

Public Member Functions
	ElementList ()=default
	Create an empty ElementList (length() is 0).
	ElementList (const ElementList &)=delete
ElementList &	operator= (const ElementList &)=delete
	ElementList (ElementList &&other) noexcept
	Move constructor (other becomes empty).
ElementList &	operator= (ElementList &&other) noexcept
	Move assignment (destroys the current list and other becomes empty).
	~ElementList ()
	Destroy the list (elements you got from it aren't affected).
size_t	length () const
	Get the number of elements in the list (length).
size_t	size () const
	Get the number of elements in the list (the same as length()).
bool	empty () const
	Whether or not the list has no elements (length() is 0).
Element	item (size_t index) const
	Get the element at an index (item).
Element	operator[] (size_t index) const
	Get the element at an index (the same as item()).
iterator	begin () const
iterator	end () const
ULDOMElementList	raw () const
	Get the C handle, for passing to the <Ultralight/CAPI/CAPI_DOMElement.h> functions.
ULDOMElementList	LeakRef ()
	Give up ownership of the C handle and return it.

Protected Member Functions
	ElementList (ULDOMElementList handle)

Constructor & Destructor Documentation

ElementList() [1/4]

ElementList ( )

default

Create an empty ElementList (length() is 0).

ElementList() [2/4]

ElementList ( const ElementList & )

delete

ElementList() [3/4]

ElementList ( ElementList && other )

inlinenoexcept

Move constructor (other becomes empty).

Parameters

other

The ElementList to move from.

~ElementList()

~ElementList ( )

inline

Destroy the list (elements you got from it aren't affected).

ElementList() [4/4]

ElementList ( ULDOMElementList handle )

inlineexplicitprotected

Member Function Documentation

Adopt()

ElementList Adopt ( ULDOMElementList handle )

inlinestatic

Wrap a C handle you own, taking ownership of it.

Parameters

handle

A handle from the C API that you would otherwise destroy with ulDestroyDOMElementList() (NULL gives an empty ElementList).

Returns

Returns an ElementList that destroys handle when it's done.

begin()

iterator begin ( ) const

inline

empty()

bool empty ( ) const

inline

Whether or not the list has no elements (length() is 0).

end()

iterator end ( ) const

inline

item()

Element item ( size_t index ) const

inline

Get the element at an index (item).

Parameters

index

The zero-based index.

Returns

Returns the element (empty if index is out of range).

LeakRef()

ULDOMElementList LeakRef ( )

inline

Give up ownership of the C handle and return it.

This ElementList becomes empty.

Returns

Returns the handle. You must call ulDestroyDOMElementList() when finished.

length()

size_t length ( ) const

inline

Get the number of elements in the list (length).

Returns

Returns the number of elements (0 for an empty ElementList).

operator=() [1/2]

ElementList & operator= ( const ElementList & )

delete

operator=() [2/2]

ElementList & operator= ( ElementList && other )

inlinenoexcept

Move assignment (destroys the current list and other becomes empty).

Parameters

other

The ElementList to move from.

Returns

Returns this ElementList.

operator[]()

Element operator[] ( size_t index ) const

inline

Get the element at an index (the same as item()).

Parameters

index

The zero-based index.

Returns

Returns the element (empty if index is out of range).

raw()

ULDOMElementList raw ( ) const

inline

Get the C handle, for passing to the <Ultralight/CAPI/CAPI_DOMElement.h> functions.

Returns

Returns the handle (NULL for an empty ElementList). This ElementList still owns it, so don't destroy it.

size()

size_t size ( ) const

inline

Get the number of elements in the list (the same as length()).

Returns

Returns the number of elements (0 for an empty ElementList).

---

The documentation for this class was generated from the following file:

• Ultralight/dom/ElementList.h