9.2 KiB
Quick jump
Widgets
Built-in components
Examples
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) 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
<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)
<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
<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:
<layout>
<theme>
<var key="my_red" value="#FF0000" />
<var key="my_green" value="#00FF00" />
<var key="my_blue" value="#0000FF" />
</theme>
</layout>
bar.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:
<layout>
<!-- Include theme -->
<include src="theme.xml"/>
<elements>
<!-- Include as additional elements here -->
<include src="bar.xml"/>
</elements>
</layout>
Templates
<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>