# UI properties and methods

UI elements in scripts are accessed through a Document instance
(*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                       |

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)                                               |

\* - 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 |

## 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     |
| 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 |
