Standard Library
class DomNode
A handle to one node in the browser page.
since 0.1.0-alpha.1wasm
Overview
A DomNode holds only an integer that the host uses to find the real node, so copying one copies the handle, not the node. Methods map directly onto browser operations. Methods that change the node return the node itself so calls can be chained. A node found by id that does not exist is a DomNode whose exists() is false; it is not an error to hold one, but operating on it is.
Examples
Building and changing a node
DomNode item = Dom::create("li");
item.setText("first").setAttr("class", "task");
Dom::byId("list").append(item);
console.writeln(item.attr("class"));
Constructors
new
new(int handle)Wrap a host handle as a DomNode.
Programs get nodes from Dom::create, Dom::byId and the other Dom functions; calling this directly is only useful with a handle obtained from the host.
Parameters
- handle
- The host handle of the node, or
0for no node.
Fields
h
int hThe host handle of the node; 0 means no node.
Methods
append
Add a node as the last child of this one.
Parameters
- child
- The node to add.
Returns
This node, so calls can be chained.
Examples
Nesting nodes
DomNode list = Dom::create("ul");
list.append(Dom::create("li")).append(Dom::create("li"));
Dom::body().append(list);
attr
@extern("getAttribute", "Str")
attr(string name) -> stringRead an attribute of the element.
Parameters
- name
- The attribute name.
Returns
The attribute value, or "" if the attribute is not set.
click
click() -> voidFire a "click" event at this node, as if the user had clicked it.
The handlers run after the current code finishes. Equivalent to dispatch("click").
Examples
Simulating a click
DomNode button = Dom::create("button");
button.on("click", (e) => {
console.writeln("clicked");
});
button.click();
console.writeln("click fired");
See also: dispatch
dispatch
@extern("dispatchEvent", "Act")
dispatch(string type) -> voidFire an event of the given type at this node.
This is the same mechanism the browser uses for real events. The handlers run in their own turn, after the current code finishes, not during this call.
Parameters
- type
- The event type to fire, for example
"click".
events
Listen for an event as a stream.
Each call attaches one listener to the node, and every matching event is pushed into the returned stream as a DomEvent. Closing the stream (directly or with using) detaches the listener and releases the handler, so Dom::listenerCount() returns to its earlier value.
Parameters
- type
- The event type to listen for, for example
"click".
Returns
A stream of the events as they occur.
Examples
Consuming events from a stream
DomNode button = Dom::create("button");
InStream<DomEvent> clicks = button.events("click");
clicks.subscribe((DomEvent e) => {
console.writeln("clicked");
});
button.click();
clicks.close();
See also: on
exists
exists() -> boolWhether this handle refers to a real node.
A lookup with Dom::byId that finds nothing yields a node whose handle is 0; this reports false for it.
Returns
true if the handle is not 0.
Examples
Checking a lookup
if (!Dom::byId("missing").exists()) {
console.writeln("no element with that id");
}
handle
handle() -> intThe raw host handle of the node.
Returns
The integer handle that identifies the node on the host side.
off
off(string type, int listener) -> voidRemove a handler registered with on.
Parameters
- type
- The event type the handler was registered for.
- listener
- The token returned by
on.
on
on(string type, (DomEvent) => void cb) -> intRegister a handler for an event on this node.
The handler runs once for each event of that type, in its own turn of the event loop, and may use await. The returned token identifies this registration so it can be removed with off.
Parameters
- type
- The event type to listen for, for example
"click". - cb
- The handler, called with the event.
Returns
A token for use with off.
Examples
Adding and removing a handler
DomNode button = Dom::create("button");
int token = button.on("click", (e) => {
console.writeln("clicked");
});
button.off("click", token);
See also: off
release
@extern("release", "Act")
release() -> voidRelease the host's handle for this node.
Use it when a program is finished with a node it created, so the host can free its slot. The node must not be used afterwards.
setAttr
@extern("setAttribute", "Fluent")
setAttr(string name, string value) -> DomNodeSet an attribute on the element.
Parameters
- name
- The attribute name, for example
"id"or"class". - value
- The new attribute value.
Returns
This node, so calls can be chained.
Examples
Chaining attribute changes
DomNode link = Dom::create("a");
link.setAttr("href", "/docs").setAttr("class", "nav");
setText
@extern("setText", "Fluent")
setText(string t) -> DomNodeReplace the text content of the node.
Parameters
- t
- The new text.
Returns
This node, so calls can be chained.
text
@extern("getText", "Str")
text() -> stringRead the text content of the node.
Returns
The node's text, or "" if it has none.
See also
- Dom — The browser document surface: entry points for reaching and creating DOM nodes.