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
|
||||
|
||||
`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
|
||||
|
||||
### `div`
|
||||
## div widget
|
||||
|
||||
The most simple element
|
||||
`<div>`
|
||||
|
||||
### The most simple element
|
||||
|
||||
#### Parameters
|
||||
|
||||
None
|
||||
_None_
|
||||
|
||||
---
|
||||
|
||||
### `label`
|
||||
## label widget
|
||||
|
||||
Text element
|
||||
`<label>`
|
||||
|
||||
### A simple text element
|
||||
|
||||
#### Parameters
|
||||
|
||||
`text`: abc
|
||||
`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
|
||||
`align`: "left" | "right" | "center" | "justified" | "end"
|
||||
|
||||
`weight`: normal | bold
|
||||
|
||||
`size`: _float_
|
||||
`weight`: "normal" | "bold"
|
||||
|
||||
---
|
||||
|
||||
### `rectangle`
|
||||
## rectangle widget
|
||||
|
||||
A styled rectangle
|
||||
`<rectangle>`
|
||||
|
||||
### A styled rectangle
|
||||
|
||||
#### Parameters
|
||||
|
||||
`text`: abc
|
||||
|
||||
`color`: #FFAABB | #FFAABBCC
|
||||
|
||||
_1st gradient color_
|
||||
@@ -82,24 +118,212 @@ _1st 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
|
||||
|
||||
---
|
||||
|
||||
### `sprite`
|
||||
## sprite widget
|
||||
|
||||
Image widget, supports raster and svg vector
|
||||
`<sprite>`
|
||||
|
||||
### Image widget, supports raster and svg vector
|
||||
|
||||
#### 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