488 lines
9.2 KiB
Markdown
488 lines
9.2 KiB
Markdown
# 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**
|
|
|
|
### Advanced attributes
|
|
|
|
`interactable`: "1" | "0"
|
|
|
|
_Set to 0 if you want to exclude this widget from altering the event state_
|
|
|
|
`consume_mouse_events`: "1" | "0"
|
|
|
|
_Used in case of overlapping pop-ups or windows, most notably applied to various backgrounds_
|
|
|
|
`new_pass`: "1" | "0"
|
|
|
|
_Set to 1 if you want to render overlapping pop-ups to properly render your widgets in order. Wgui renders with as few Vulkan drawcalls as possible, so this is your responsibility._
|
|
|
|
# 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_
|
|
|
|
`wrap`: "1" | "0" (default: "0")
|
|
|
|
_Enable text wrapping?_
|
|
|
|
`color`: #FFAABB | #FFAABBCC
|
|
|
|
`align`: "left" | "right" | "center" | "justified" | "end"
|
|
|
|
`weight`: "normal" | "bold"
|
|
|
|
`shadow`: #112233 | #112233CC (default: None)
|
|
|
|
`shadow_x`: **float** (default: 1.5)
|
|
|
|
_Horizontal offset of the shadow from the original text. Positive is right._
|
|
|
|
`shadow_y`: **float** (default: 1.5)
|
|
|
|
_Vertical offset of the shadow from the original text. Positive is down._
|
|
|
|
---
|
|
|
|
## 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 for small images
|
|
|
|
Always set the `width` & `height` of a `<sprite>`!
|
|
|
|
Supported formats: svg, png, jpeg, gif, webp
|
|
|
|
Maximum image size: 256x256 pixels
|
|
|
|
For large or frequently changing images (e.g. album art), or if borders/rounding is desired, consider the `<image>` tag instead.
|
|
|
|
Sprite images are atlassed, making them very efficient to render.
|
|
|
|
Adding large sprites permanently increases the atlas size (and thus VRAM usage) for the session. (Atlas space can be re-used, but the atlas won't shrink back.)
|
|
|
|
#### Parameters
|
|
|
|
`src`: **string**
|
|
|
|
_External (filesystem) image path. Falls back to Internal (assets) if not found._
|
|
|
|
`src_ext`: **string**
|
|
|
|
_External (filesystem) image path_
|
|
|
|
`src_builtin`: **string**
|
|
|
|
_Internal (assets) image path_
|
|
|
|
`src_internal`: **string**
|
|
|
|
_wgui internal image path. Do not use directly unless it's related to the core wgui assets._
|
|
|
|
## image widget
|
|
|
|
### `<image>`
|
|
|
|
### Image widget for large images
|
|
|
|
Always set the `width` & `height` of an `<image>`!
|
|
|
|
Supported formats: svg, png, jpeg, gif, webp
|
|
|
|
Maximum image size: Max texture size for the GPU (usually 8K+)
|
|
|
|
For small images such as icons, consider using the `<sprite>` tag instead.
|
|
|
|
`<image>` requires a single draw call per widget, while `<sprite>` widgets all share a single draw call per panel.
|
|
|
|
#### Parameters
|
|
|
|
`src`: **string**
|
|
|
|
_External (filesystem) image path. Falls back to Internal (assets) if not found._
|
|
|
|
`src_ext`: **string**
|
|
|
|
_External (filesystem) image path_
|
|
|
|
`src_builtin`: **string**
|
|
|
|
_Internal (assets) image path_
|
|
|
|
`src_internal`: **string**
|
|
|
|
_wgui internal image path. Do not use directly unless it's related to the core wgui assets._
|
|
|
|
`round`: **float** (default: 0) | **percent** (0-100%)
|
|
|
|
`border`: **float**
|
|
|
|
`border_color`: #FFAABB | #FFAABBCC
|
|
|
|
---
|
|
|
|
# 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%)
|
|
|
|
`border`: **float** (default: 2)
|
|
|
|
`color`: #FFAABB | #FFAABBCC
|
|
|
|
`border_color`: #FFAABB | #FFAABBCC
|
|
|
|
`hover_color`: #FFAABB | #FFAABBCC
|
|
|
|
`hover_border_color`: #FFAABB | #FFAABBCC
|
|
|
|
`tooltip`: **string**
|
|
|
|
_Tooltip text on hover, translated by key_
|
|
|
|
`tooltip_str`: **string**
|
|
|
|
_Tooltip text on hover, raw text (not translated)_
|
|
|
|
`tooltip_side`: "top" | "bottom" | "left" | "right" (default: top)
|
|
|
|
`sticky`: "1" | "0" (default: "0")
|
|
|
|
_make button act as a toggle (visual only)_
|
|
|
|
`sprite_src` | `sprite_src_ext` | `sprite_src_builtin` | `sprite_src_internal`
|
|
|
|
_Image path (see [sprite](#sprite-widget)) for src descriptions_
|
|
|
|
#### 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_
|
|
|
|
`show_value`: "1" | "0"
|
|
|
|
_Set to 0 if you don't want to display value text in the slider handle_
|
|
|
|
---
|
|
|
|
## Checkbox component
|
|
|
|
### `<CheckBox>`
|
|
|
|
### A check-box with label.
|
|
|
|
#### Parameters
|
|
|
|
`text`: **string**
|
|
|
|
_Simple text_
|
|
|
|
`translation`: **string**
|
|
|
|
_Translated by key_
|
|
|
|
`box_size`: **float** (default: 24)
|
|
|
|
`value`: **string**
|
|
|
|
_optional value that will be sent with internal events_
|
|
|
|
`checked`: **int** (default: 0)
|
|
|
|
---
|
|
|
|
## Radiobox component
|
|
|
|
### `<RadioBox>`
|
|
|
|
### A radio-box with label.
|
|
|
|
#### Parameters
|
|
|
|
`text`: **string**
|
|
|
|
_Simple text_
|
|
|
|
`translation`: **string**
|
|
|
|
_Translated by key_
|
|
|
|
`box_size`: **float** (default: 24)
|
|
|
|
`value`: **string**
|
|
|
|
_optional value that will be set as the RadioGroup's value_
|
|
|
|
`checked`: **int** (default: 0)
|
|
|
|
---
|
|
|
|
## RadioGroup component
|
|
|
|
### `<RadioGroup>`
|
|
|
|
### A radio group. Place `<RadioBox>` components inside this.
|
|
|
|
---
|
|
|
|
# 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>
|
|
|
|
```
|