# Quick jump

## [Widgets](#widgets)

[div](#div-widget), [label](#label-widget), [rectangle](#rectangle-widget), [sprite](#sprite-widget)

## [Built-in components](#components)

[Button](#button-component), [Slider](#slider-component), [CheckBox](#checkbox-component)

## [Examples](#examples)

[Simple layout](#simple-layout)

[Value substitution (themes)](#value-substitution-themes)

[File inclusion](#file-inclusion)

[Macros](#macros)

[Templates](#templates)

# Universal widget attributes

### They can be used in any widget/component

`display`: "flex" | "block" | "grid"

`position`: "absolute" | "relative"

`flex_grow`: **float**

`flex_shrink`: **float**

`gap`: **float** | **percent**

`flex_basis`: **float** | **percent**

`justify_self`: "center" | "end" | "flex_end" | "flex_start" | "start" | "stretch"

`justify_content`: "center" | "end" | "flex_start" | "flex_end" | "space_around" | "space_between" | "space_evenly" | "start" | "stretch"

`flex_wrap`: "wrap" | "no_wrap" | "wrap_reverse"

`flex_direction`: "row" | "column" | "column_reverse" | "row_reverse"

`align_items`, `align_self`: "baseline" | "center" | "end" | "flex_start" | "flex_end" | "start" | "stretch"

`box_sizing`: "border_box" | "content_box"

`margin`, `margin_left`, `margin_right`, `margin_top`, `margin_bottom`: **float** | **percent**

`padding`, `padding_left`, `padding_right`, `padding_top`, `padding_bottom`: **float** | **percent**

`overflow`, `overflow_x`, `overflow_y`: "hidden" | "visible" | "clip" | "scroll"

`min_width`, `min_height`: **float** | **percent**

`max_width`, `max_height`: **float** | **percent**

`width`, `height`: **float** | **percent**

# Widgets

## div widget

### `<div>`

### The most simple element

#### Parameters

_None_

---

## label widget

### `<label>`

### A simple text element

#### Parameters

`text`: **string**

_Simple text_

`translation`: **string**

_Translated by key_

`size`: **float** (default: 14)

_Text size in pixel units_

`color`: #FFAABB | #FFAABBCC

`align`: "left" | "right" | "center" | "justified" | "end"

`weight`: "normal" | "bold"

---

## rectangle widget

### `<rectangle>`

### A styled rectangle

#### Parameters

`color`: #FFAABB | #FFAABBCC

_1st gradient color_

`color2`: #FFAABB | #FFAABBCC

_2nd gradient color_

`gradient`: "horizontal" | "vertical" | "radial" | "none"

`round`: **float** (default: 0) | **percent** (0-100%)

`border`: **float**

`border_color`: #FFAABB | #FFAABBCC

---

## sprite widget

### `<sprite>`

### Image widget, supports raster and svg vector

#### Parameters

`src`: **string**

_Internal (assets) image path_

`src_ext`: **string**

_External image path_

---

# Components

## Button component

### `<Button>`

### A clickable, decorated button

#### Parameters

`text`: **string**

_Simple text_

`translation`: **string**

_Translated by key_

`round`: **float** (default: 4) | **percent** (0-100%)

`color`: #FFAABB | #FFAABBCC

`border_color`: #FFAABB | #FFAABBCC

`hover_color`: #FFAABB | #FFAABBCC

`hover_border_color`: #FFAABB | #FFAABBCC

#### Info

Child widgets are supported and can be added directly in XML.

---

## Slider component

### `<Slider>`

### A simple slider.

#### Parameters

`min_value`: **float**

`max_value`: **float**

_Needs to be bigger than `min_value`_

`value`: **float**

_Initial slider value_

---

## Checkbox component

### `<CheckBox>`

### A check-box with label.

#### Parameters

`text`: **string**

_Simple text_

`translation`: **string**

_Translated by key_

`box_size`: **float** (default: 24)

`checked`: **int** (default: 0)

---

# Examples

## Simple layout

```xml
<layout>
  <elements>
    <label text="Hello, world!"/>
    <label translation="WELCOME.HELLO_WORLD" size="20" color="#FF0000"/>
    <div gap="16" flex_direction="row">
      <rectangle width="16" height="16" color="#FF0000"/>
      <rectangle width="16" height="16" color="#00FF00"/>
      <rectangle width="16" height="16" color="#0000FF"/>
    </div>
  </elements>
</layout>
```

## Value substitution (themes)

```xml
<layout>
  <theme>
    <var key="hello" value="Hello, world!" />
    <var key="text_color" value="#FF0000" />
  </theme>

  <elements>
    <!-- "~hello" will be replaced to "Hello, world!" -->
    <label text="~hello"/>
    <!-- "~text_color" will be replaced to "#FF0000" -->
    <label text="This text will be red" color="~text_color"/>
  </elements>
</layout>
```

## Macros

```xml
<layout>
  <macro name="my_macro"
    margin="4" min_width="100" min_height="100" flex_direction="row" gap="8"
    align_items="center" justify_content="center"/>

  <elements>
    <!-- This div will have all attributes specified in "my_macro" -->
    <div macro="my_macro">
      <label text="hello, world!"/>
    </div>
  </elements>
</layout>

```

## File inclusion

theme.xml:

```xml
<layout>
  <theme>
    <var key="my_red" value="#FF0000" />
    <var key="my_green" value="#00FF00" />
    <var key="my_blue" value="#0000FF" />
  </theme>
</layout>
```

bar.xml:

```xml
<layout>
  <elements>
    <!-- utilize theme variables included in theme.xml -->
    <rectangle width="16" height="16" color="~my_red"/>
    <rectangle width="16" height="16" color="~my_green"/>
    <rectangle width="16" height="16" color="~my_blue"/>
  </elements>
</layout>
```

main.xml:

```xml
<layout>
  <!-- Include theme -->
  <include src="theme.xml"/>

  <elements>
    <!-- Include as additional elements here -->
    <include src="bar.xml"/>
  </elements>
</layout>
```

## Templates

```xml
<layout>
  <!-- "title" attrib will be passed to every matching ${title} -->
  <template name="DecoratedTitle">
    <rectangle color="#FFFF00" padding="8" round="4" gap="4">
      <label text="${title}"/>
    </rectangle>
  </template>

  <elements>
    <!-- "title" used here -->
    <DecoratedTitle title="This is a title.">
  </elements>
</layout>

```