Update documentation
This commit is contained in:
Aleksander
@@ -1,79 +1,115 @@
|
|||||||
|
# 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
|
# Universal widget attributes
|
||||||
|
|
||||||
`display`: flex | block | grid
|
### They can be used in any widget/component
|
||||||
|
|
||||||
`position`: absolute | relative
|
`display`: "flex" | "block" | "grid"
|
||||||
|
|
||||||
`flex_grow`: units (3)
|
`position`: "absolute" | "relative"
|
||||||
|
|
||||||
`flex_shrink`: units (3)
|
`flex_grow`: **float**
|
||||||
|
|
||||||
`gap`: units (42) or percent (42%)
|
`flex_shrink`: **float**
|
||||||
|
|
||||||
`flex_basis`: units (42) or percent (42%)
|
`gap`: **float** | **percent**
|
||||||
|
|
||||||
`justify_self`: center | end | flex_end | flex_start | start | stretch
|
`flex_basis`: **float** | **percent**
|
||||||
|
|
||||||
`justify_content`: center | end | flex_start | flex_end | space_around | space_between | space_evenly | start | stretch
|
`justify_self`: "center" | "end" | "flex_end" | "flex_start" | "start" | "stretch"
|
||||||
|
|
||||||
`flex_wrap`: wrap | no_wrap | wrap_reverse
|
`justify_content`: "center" | "end" | "flex_start" | "flex_end" | "space_around" | "space_between" | "space_evenly" | "start" | "stretch"
|
||||||
|
|
||||||
`flex_direction`: row | column | column_reverse | row_reverse,
|
`flex_wrap`: "wrap" | "no_wrap" | "wrap_reverse"
|
||||||
|
|
||||||
`align_items`, `align_self`: baseline | center | end | flex_start | flex_end | start | stretch
|
`flex_direction`: "row" | "column" | "column_reverse" | "row_reverse"
|
||||||
|
|
||||||
`box_sizing`: border_box | content_box
|
`align_items`, `align_self`: "baseline" | "center" | "end" | "flex_start" | "flex_end" | "start" | "stretch"
|
||||||
|
|
||||||
`margin`, `margin_left`, `margin_right`, `margin_top`, `margin_bottom`: units (42) or percent (42%)
|
`box_sizing`: "border_box" | "content_box"
|
||||||
|
|
||||||
`padding`, `padding_left`, `padding_right`, `padding_top`, `padding_bottom`: units (42) or percent (42%)
|
`margin`, `margin_left`, `margin_right`, `margin_top`, `margin_bottom`: **float** | **percent**
|
||||||
|
|
||||||
`overflow`, `overflow_x`, `overflow_y`: hidden | visible | clip | scroll
|
`padding`, `padding_left`, `padding_right`, `padding_top`, `padding_bottom`: **float** | **percent**
|
||||||
|
|
||||||
`min_width`, `min_height`: units (42) or percent (42%)
|
`overflow`, `overflow_x`, `overflow_y`: "hidden" | "visible" | "clip" | "scroll"
|
||||||
|
|
||||||
`max_width`, `max_height`: units (42) or percent (42%)
|
`min_width`, `min_height`: **float** | **percent**
|
||||||
|
|
||||||
`width`, `height`: units (42) or percent (42%)
|
`max_width`, `max_height`: **float** | **percent**
|
||||||
|
|
||||||
|
`width`, `height`: **float** | **percent**
|
||||||
|
|
||||||
# Widgets
|
# Widgets
|
||||||
|
|
||||||
### `div`
|
## div widget
|
||||||
|
|
||||||
The most simple element
|
`<div>`
|
||||||
|
|
||||||
|
### The most simple element
|
||||||
|
|
||||||
#### Parameters
|
#### Parameters
|
||||||
|
|
||||||
None
|
_None_
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### `label`
|
## label widget
|
||||||
|
|
||||||
Text element
|
`<label>`
|
||||||
|
|
||||||
|
### A simple text element
|
||||||
|
|
||||||
#### Parameters
|
#### Parameters
|
||||||
|
|
||||||
`text`: abc
|
`text`: **string**
|
||||||
|
|
||||||
|
_Simple text_
|
||||||
|
|
||||||
|
`translation`: **string**
|
||||||
|
|
||||||
|
_Translated by key_
|
||||||
|
|
||||||
|
`size`: **float** (default: 14)
|
||||||
|
|
||||||
|
_Text size in pixel units_
|
||||||
|
|
||||||
`color`: #FFAABB | #FFAABBCC
|
`color`: #FFAABB | #FFAABBCC
|
||||||
|
|
||||||
`align`: left | right | center | justified | end
|
`align`: "left" | "right" | "center" | "justified" | "end"
|
||||||
|
|
||||||
`weight`: normal | bold
|
`weight`: "normal" | "bold"
|
||||||
|
|
||||||
`size`: _float_
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### `rectangle`
|
## rectangle widget
|
||||||
|
|
||||||
A styled rectangle
|
`<rectangle>`
|
||||||
|
|
||||||
|
### A styled rectangle
|
||||||
|
|
||||||
#### Parameters
|
#### Parameters
|
||||||
|
|
||||||
`text`: abc
|
|
||||||
|
|
||||||
`color`: #FFAABB | #FFAABBCC
|
`color`: #FFAABB | #FFAABBCC
|
||||||
|
|
||||||
_1st gradient color_
|
_1st gradient color_
|
||||||
@@ -82,24 +118,212 @@ _1st gradient color_
|
|||||||
|
|
||||||
_2nd gradient color_
|
_2nd gradient color_
|
||||||
|
|
||||||
`gradient`: horizontal | vertical | radial | none
|
`gradient`: "horizontal" | "vertical" | "radial" | "none"
|
||||||
|
|
||||||
`round`: _float (0.0 - 1.0)_
|
`round`: **float** (default: 0) | **percent** (0-100%)
|
||||||
|
|
||||||
`border`: _float_
|
`border`: **float**
|
||||||
|
|
||||||
`border_color`: #FFAABB | #FFAABBCC
|
`border_color`: #FFAABB | #FFAABBCC
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### `sprite`
|
## sprite widget
|
||||||
|
|
||||||
Image widget, supports raster and svg vector
|
`<sprite>`
|
||||||
|
|
||||||
|
### Image widget, supports raster and svg vector
|
||||||
|
|
||||||
#### Parameters
|
#### Parameters
|
||||||
|
|
||||||
`src`: Internal (assets) image path
|
`src`: **string**
|
||||||
|
|
||||||
`src_ext`: External image path
|
_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
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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>
|
||||||
|
|
||||||
|
```
|
||||||
|
|||||||
Reference in New Issue
Block a user