# UI properties and methods

UI elements in scripts are accessed through a Document instance
(global *document* variable) by id specified in xml.

Example: print the pos property of an element with id: "worlds-panel" to the console:
```lua
print(document["worlds-panel"].pos)
-- or
local worldsPanel = document["worlds-panel"]
print(worldsPanel.pos)
```

The IDs of the elements are global for the document, that is, *worlds-panel* can be located either in the root element,
and in a nested container.

The element id cannot be changed from a script.

The following tables will use abbreviated type descriptions, such as:
- vec2 - an array of two numbers.
- ivec2 - an array of two integers.
- rgba - an array of four integers in the range `[0..255]` denoting RGBA constituent colors.

Element methods, according to OOP features in Lua, are called using the `:` operator instead of `.`

For example:
```lua
document["worlds-panel"]:clear()
```

Access to nested elements is performed by index (starting from one).

## General properties and methods

Properties that apply to all elements:

| Name          | Type    | Read | Write | Description                                      |
| ------------- | ------- | ---- | ----- | ------------------------------------------------ |
| id            | string  | yes  | *no*  | element id                                       |
| exists        | bool    | yes  | *no*  | checks if element exists                         |
| pos           | vec2    | yes  | yes   | element position inside a container              |
| wpos          | vec2    | yes  | yes   | element position inside the window               |
| size          | vec2    | yes  | yes   | element size                                     |
| interactive   | bool    | yes  | yes   | ability to interact with the element             |
| enabled       | bool    | yes  | yes   | visually indicated version of *interactive*      |
| visible       | bool    | yes  | yes   | element visibility                               |
| focused       | bool    | yes  | yes   | focus on element                                 |
| color         | rgba    | yes  | yes   | element color                                    |
| hoverColor    | rgba    | yes  | yes   | hover color                                      |
| pressedColor  | rgba    | yes  | yes   | color when pressed                               |
| tooltip       | string  | yes  | yes   | tooltip text                                     |
| tooltipDelay  | float   | yes  | yes   | tooltip delay                                    |
| contentOffset | vec2    | yes  | *no*  | element content offset                           |
| cursor        | string  | yes  | yes   | cursor displayed on hover                        |
| parent        | Element | yes  | *no*  | parent element or nil                            |
| zIndex        | int     | yes  | *no*  | z-index value. In panel, it determines the order |

Common element methods:

| Method              | Description                                                                         |
| ------------------- | ----------------------------------------------------------------------------------- |
| moveInto(container) | moves the element to the specified container (the element is specified, not the id) |
| destruct()          | removes element                                                                     |
| reposition()        | updates the element position based on the `positionfunc`                            |

## Containers

Common properties for containers (elements: container, panel, button, pagebox):

| Name   | Type   | Read | Write | Description     |
| ------ | ------ | ---- | ----- | --------------- |
| scroll | string | yes  | yes   | scroll contents |

Common methods:

| Method                          | Description                                                                                  |
| ------------------------------- | -------------------------------------------------------------------------------------------- |
| clear()                         | clears content                                                                               |
| add(xml)                        | adds an element, creating it using xml code. Example: `container:add("<image src='test'/>")` |
| add(xml, data)                  | overload with table, which in events declared in xml will be available as DATA               |
| setInterval(interval, callback) | assigns a function to be executed repeatedly at an interval specified in milliseconds        |

## Textbox

Properties:

| Name              | Type   | Read | Write | Description                                                                          |
| ----------------- | ------ | ---- | ----- | ------------------------------------------------------------------------------------ |
| text              | string | yes  | yes   | entered text or placeholder                                                          |
| placeholder       | string | yes  | yes   | placeholder (used if nothing has been entered)                                       |
| hint              | string | yes  | yes   | text to display when nothing is entered                                              |
| caret             | int    | yes  | yes   | carriage position. `textbox.caret = -1` will set the position to the end of the text |
| editable          | bool   | yes  | yes   | text mutability                                                                      |
| edited            | bool   | yes  | yes\* | is text edited since the last set / edited status reset                              |
| multiline         | bool   | yes  | yes   | multiline support                                                                    |
| lineNumbers       | bool   | yes  | yes   | display line numbers                                                                 |
| textWrap          | bool   | yes  | yes   | automatic text wrapping (only with multiline: "true")                                |
| valid             | bool   | yes  | no    | is the entered text correct                                                          |
| textColor         | vec4   | yes  | yes   | text color                                                                           |
| syntax            | string | yes  | yes   | syntax highlighting ("lua" - Lua)                                                    |
| markup            | string | yes  | yes   | text markup language ("md" - Markdown)                                               |
| selection         | ivec2  | yes  | yes   | selection anchor and caret; see below                                                |
| externalRendering | bool   | yes  | yes   | external text rendering (default: false)                                             |
| textLayout        | table  | yes  | no    | snapshot of visible text layout; see below                                           |

\* - false only

Methods:

| Method                    | Description                                                      |
| ------------------------- | ---------------------------------------------------------------- |
| paste(text: str)          | inserts the specified text at the caret position                 |
| lineAt(pos: int) -> int   | determines the line number by position in the text               |
| linePos(line: int) -> int | determines the position of the beginning of the line in the text |

### Selection and external rendering

- `selection` (read/write): `{anchor, caret}`, preserving direction. Indices
  are zero-based native caret character units, not UTF-8 byte offsets. Setters
  require finite integers, clamp to the text length and reveal the caret,
  including immediately after replacing text. Setting selection does not
  edit text or reset undo history.
- `externalRendering` (read/write boolean, default `false`): hides native text,
  caret, selection and current-line highlight. Input, hit testing, layout,
  scrolling, background, line numbers and scrollbar remain native. Setting it
  back to `false` restores native rendering without replacing the textbox.
  Markup and external rendering cannot be combined: either setter rejects it.
- `textLayout` (read-only table): a snapshot of the current visible layout.
  `ready=false` means the font is unavailable or markup is active. Otherwise:
  - `text`: the value of `textbox.text`, including `placeholder` when input is empty;
    `font`: font name.
  - `lineHeight`: row pitch; `textHeight`: height to use for a label displaying a row.
  - `caretRect`: `{x,y,cellWidth,rowHeight}` at the moving selection endpoint;
    at end-of-line the cell width is the space advance. This is geometry,
    independent of focus, editability and blink phase.
  - `selectionRects`: `{x, y, width, height}` rectangles for visible selected rows,
    including selected newline cells.
  - `lines`: visible rows `{start, text, pos={x,y}, advances={...}}`;
    `start` is a native caret index, text excludes the trailing newline,
    `advances` contains the native width of each character. Empty input may
    expose the hint as display rows; it does not replace `text` in the snapshot.

Coordinates are relative to the textbox, include scrolling and alignment,
and may extend outside its bounds. External painters must clip to the field.
Snapshots are independent Lua tables; modifying them does not modify the box.
Read them again after input, resizing or scrolling. Syntax colors are not
exported; the external painter supplies its own colors. Indexing and text input
follow the existing textbox behavior.

```lua
local field = document.input
field.text = "abcdef"
field.selection = {5, 2}
local anchor, caret = unpack(field.selection)

field.externalRendering = true
local layout = field.textLayout
if layout.ready then
    for _, line in ipairs(layout.lines) do
        print(line.start, line.text, line.pos[1], line.pos[2])
    end
end
```

In this example the caret is at position 2 and the selection anchor is at
position 5. A negative selection index is clamped to zero; unlike `caret`,
it does not address characters from the end of the text.

## Slider (trackbar)

Properties:

| Name       | Type  | Read | Write | Description           |
| ---------- | ----- | ---- | ----- | --------------------- |
| value      | float | yes  | yes   | current value         |
| min        | float | yes  | yes   | minimum value         |
| max        | float | yes  | yes   | maximum value         |
| step       | float | yes  | yes   | division step         |
| trackWidth | float | yes  | yes   | control element width |
| trackColor | rgba  | yes  | yes   | control element color |

## Menu (pagebox)

Properties:

| Name  | Type   | Read | Write | Description  |
| ----- | ------ | ---- | ----- | ------------ |
| page  | string | yes  | yes   | current page |

Methods:

| Method  | Description                       |
| ------- | --------------------------------- |
| back()  | switches to previous page         |
| reset() | resets page and switching history |

## Checkbox

Properties:

| Name    | Type | Read | Write | Description |
| ------- | ---- | ---- | ----- | ----------- |
| checked | bool | yes  | yes   | mark status |

## Button

Properties:

| Name  | Type   | Read | Write | Description  |
| ----- | ------ | ---- | ----- | ------------ |
| text  | string | yes  | yes   | button text  |

## Label

Properties:

| Name   | Type   | Read | Write | Description                            |
| ------ | ------ | ---- | ----- | -------------------------------------- |
| text   | string | yes  | yes   | label text                             |
| markup | string | yes  | yes   | text markup language ("md" - Markdown) |

## Image

Properties:

| Name     | Type   | Read | Write | Description      |
| -------- | ------ | ---- | ----- | ---------------- |
| src      | string | yes  | yes   | texture name     |
| fallback | string | yes  | yes   | fallback texture |
| region   | vec4   | yes  | yes   | image sub-region |

## Canvas

Properties:

| Title | Type   | Read | Write | Description |
|-------|--------| ---- |-------|-------------|
| data  | Canvas | yes  | no    | canvas data |

Methods:

Here, *color* can be specified in the following ways:
- rgba: int
- r: int, g: int, b: int
- r: int, g: int, b: int, a: int

| Method                                                   | Description                                             |
|----------------------------------------------------------|---------------------------------------------------------|
| data:at(x: int, y: int)                                  | returns an RGBA pixel at the given coordinates          |
| data:set(x: int, y: int, *color*)                        | updates an RGBA pixel at the given coordinates          |
| data:line(x1: int, y1: int, x2: int, y2: int, *color*)   | draws a line with the specified RGBA color              |
| data:blit(src: Canvas, dst_x: int, dst_y: int)           | draws the src canvas at the specified coordinates       |
| data:clear()                                             | clears the canvas                                       |
| data:clear(*color*)                                      | fills the canvas with the specified RGBA color          |
| data:rect(x: int, y: int, w: int, h: int, *color*)       | fills the rectangle with the specified RGBA color       |
| data:update()                                            | applies changes to the canvas and uploads it to the GPU |
| data:set_data(data: Bytearray | table<int>)              | replaces pixel data (width * height * 4 numbers)        |
| data:get_data()                                          | creates a Bytearray object with the image's pixel data  |
| data:create_texture(name: str)                           | creates and shares texture to renderer                  |
| data:unbind_texture()                                    | unbinds the texture from the canvas                     |
| data:mul(*color* or Canvas)                              | multiplies a color by the specified color or canvas     |
| data:add(*color* or Canvas)                              | adds a color or another canvas to a color               |
| data:sub(*color* or Canvas)                              | subtracts a color or another canvas to a color          |
| data:encode(format: str)                                 | encodes image to specified format and returns bytearray |

To decode a byte array into a Canvas, use the static method:
```lua
Canvas.decode(data: Bytearray, format: str) -> Canvas
```

Currently, only png is supported.

## Inline frame (iframe)

| Name     | Type   | Read | Write | Description                 |
|----------|--------|------|-------|-----------------------------|
| src      | string | yes  | yes   | id of the embedded document |

## Select

Derived from button with access to properties such as the text to display.

Properties:

| Name    | Type   | Read | Write | Description                                      |
|---------|--------|------|-------|--------------------------------------------------|
| value   | string | yes  | yes   | Selected value                                   |
| options | table  | yes  | yes   | List of options (tables `{value=..., text=...}`) |

## Inventory

Properties:

| Name      | Type | Read | Write | Description                                       |
| --------- | ---- | ---- | ----- | ------------------------------------------------- |
| inventory | int  | yes  | yes   | id of the inventory to which the element is bound |

## Slot

Properties:

| Name      | Type | Read | Write | Description                                        |
| --------- | ---- | ---- | ----- | -------------------------------------------------- |
| inventory | int  | yes  | no    | id of the inventory to which the element is bound  |
| slotIndex | int  | yes  | no    | index of the slot to which the element is attached |