UiElement¶
Extends EngineObject.
An element of a document (a div, a text node, a whole document) as scripts hold it. The object is a handle: it names the element without keeping it alive, so one whose element has been destroyed (its document was closed, an ancestor was destroyed) is IsAlive false and every call on it does nothing or answers "none". An element made with CreateElement or CreateText belongs to the object that holds it until it is put in a tree with Append or InsertBefore; an element nobody ever put in a tree is destroyed when the script lets go of it, and one in a tree lives as long as the tree does. Elements are made, moved and changed here.
Properties¶
is_alive: booleanWhether the element still exists. Read-only.tag: stringThe tag (div, body), or empty for a dead element. Read-only.id: stringThe element's id (the id attribute; ids are unique in a document).class_name: stringThe classes, separated by spaces: what the style rules (.card) match.inner_rml: stringThe RML of what is inside the element; setting it replaces the children.text: stringThe text of a text node (made with CreateText); empty for any other element.is_visible: booleanWhether it can be seen: not display: none or visibility: hidden, itself or any element above it. Read-only.parent: UiElement?The element it is in, or nothing for a document or an element in no tree. Read-only.child_count: numberThe number of elements and text nodes directly inside. Read-only.document: UiElement?The document the element is in (a document is its own). Read-only.
Methods¶
show¶
function show(self): ()
Makes the document visible (and it starts to be drawn and to take input).
hide¶
function hide(self): ()
close¶
function close(self): ()
Unloads the document: everything in it is destroyed. Call it on the document.
add_style¶
function add_style(self, rcss: string): boolean
Adds style rules (RCSS) to the document this element is in, on top of its own.
create_element¶
function create_element(self, tag: string): UiElement?
A new element with the tag (div, span, input...) in this element's document, in no tree yet.
create_text¶
function create_text(self, text: string): UiElement?
A new text node in this element's document, in no tree yet.
append¶
function append(self, child: UiElement): boolean
Puts child, made by CreateElement or taken out by Remove, last in this element, which owns it from then on. False if it is already in a tree.
insert_before¶
function insert_before(self, child: UiElement, before: UiElement?): boolean
The same, before before, a child of this element (or last, when it is nothing).
remove¶
function remove(self, child: UiElement): boolean
Takes a child out of this element. It is the script's again: put it somewhere else, or let go of it to destroy it.
destroy_element¶
function destroy_element(self): ()
Destroys the element with everything inside it, out of its tree. Every object that names it is dead afterwards.
child¶
function child(self, index: number): UiElement?
by_id¶
function by_id(self, id: string): UiElement?
The element with this id in or below this one.
closest¶
function closest(self, selector: string): UiElement?
The nearest element, this one included and going up, that a selector (.card, #menu, div.row) matches.
contains¶
function contains(self, other: UiElement): boolean
Whether other is this element or inside it.
get_attribute¶
function get_attribute(self, name: string): string?
has_attribute¶
function has_attribute(self, name: string): boolean
set_attribute¶
function set_attribute(self, name: string, value: string): ()
remove_attribute¶
function remove_attribute(self, name: string): ()
set_property¶
function set_property(self, name: string, value: string): boolean
Sets an inline style (set_property("width", "120px")); false when the name or the value is not valid RCSS.
remove_property¶
function remove_property(self, name: string): ()
set_pseudo_class¶
function set_pseudo_class(self, name: string, on: boolean): ()
has_pseudo_class¶
function has_pseudo_class(self, name: string): boolean
focus¶
function focus(self): boolean
blur¶
function blur(self): ()
click¶
function click(self): ()
Clicks the element as if the pointer had.
scroll_into_view¶
function scroll_into_view(self, alignWithTop: boolean?): ()
rect¶
function rect(self): (number, number, number, number)
The element's border box on the screen in pixels, as the last update laid it out: x, y, width, height.
listen¶
function listen(self, type_: string, handler: (...any) -> ...any, capture: boolean?): number
Calls handler with a UiEvent whenever an event of this type (click, mousedown, keydown, change, focus...) reaches the element on its way up from what was hit, or, with capture, on its way down. Returns a number for UiSystem.Unlisten. The listener goes when the element does.
unlisten¶
function unlisten(self, token: number): boolean
Takes back a listener of this element (the number Listen returned); the same as UiSystem.Unlisten.