Skip to content

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: boolean Whether the element still exists. Read-only.
  • tag: string The tag (div, body), or empty for a dead element. Read-only.
  • id: string The element's id (the id attribute; ids are unique in a document).
  • class_name: string The classes, separated by spaces: what the style rules (.card) match.
  • inner_rml: string The RML of what is inside the element; setting it replaces the children.
  • text: string The text of a text node (made with CreateText); empty for any other element.
  • is_visible: boolean Whether 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: number The 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.