wayvr/wlx-overlay-s/src/gui

WayVR GUI Customization

When customizing the watch, keyboard, dashboard, etc; place custom XML files under ~/.config/wlxoverlay/theme/gui

Custom timezones, 12 vs 24-hour clock

These are not done via the GUI system, but via the regular config.

Create ~/.config/wlxoverlay/conf.d/clock.yaml as such:

timezones:
- "Europe/Oslo"
- "America/New_York"

clock_12h: false

Once this file is created, the various settings in custom UI that accept the _timezone property will use these custom alternate timezones (instead of the default set, which are selected as major ones on different continents from your current actual timezone).

The first timezone is selected with _timezone="0", the second with _timezone="1", and so on.

There is usually no need to specify your own local timezone in here; omitting _timezone from a _source="clock" Label will display local time.

Custom UI Elements

Labels

Clock label

Clock labels are driven by the current time, adhering to the user's 12/24 hour setting as well as timezone settings.

Available display values are: name (timezone name), time, date, dow

See the Custom Timezones section for more info on timezones. Skip _timezone to use local time.

<label _source="clock" _display="time" _timezone="0" [...] />

Fifo label

Fifo label creates a fifo on your system that other programs can pipe output into.

• The label will look for the last complete line to use as its text.
• If the pipe breaks due to an IO error, re-creation is attempted after 15 seconds.
• _path supports environment variables, but not ~!

<label _source="fifo" _path="$XDG_RUNTIME_DIR/my-test-label" [...] />

Example script to test with:

for i in {0..99}; do echo "i is $i" > $XDG_RUNTIME_DIR/my-test-label; sleep 1; done

Shell Exec label

This label executes a shell script using the sh shell.

• Write lines to the script's stdout to update the label text.
• The label will look for the last complete line to use as its text.
• Long-running scripts are allowed, but the label is only updated while the HMD is active.
• If the script exits successfully (code 0), it will be re-ran on the next frame. Otherwise, it will be re-ran in 15s.
• Control the pacing from inside the script itself. For example, adding a sleep 5 will make the script execute at most once per 5 seconds.
• _exec supports everything that sh supports!

<label _source="shell" _exec="$HOME/.local/bin/my-test-script.sh" [...] />

#!/usr/bin/bash
echo "This is my script's output!"

Battery label

This is a label type that's used internally to display battery states.

<label _source="battery" _device="0" [...] />

IPD

Displays IPD value in millimeters. Not parametrizable.

Format: ipd

<label _source="ipd" [...] />

Buttons

Buttons consist of a label component and one or more actions to handle press and/or release events.

Note: As of WlxOverlay 25.10, we no longer support events based on laser color, as this was bad practice accessibility-wise.

Supported events:

<button _press="..." _release="..." />

Supported button actions

::ShellExec <command> [args ..]

This button action executes a shell script using the sh shell.

• Long-running processes are allowed, but a new execution will not be triggered until the previous process has exited.
• If triggered again while the previous process is still running, SIGUSR1 will be sent to that child process.

<button _press="::ShellExec $HOME/myscript.sh test-argument" [...] />

Update the button's label from stdout

<button _press="::ShellExec $HOME/myscript.sh test-argument" _update_label="1" [...] />

• Write lines to the script's stdout to update the label text.
• The label will look for the last complete line to use as its text.
• Long-running scripts are allowed, but the label is only updated while the HMD is active.

::OscSend <path> <args ..>

Send an OSC message. The target port comes from the osc_out_port configuration setting.

<button _press="::OscSend /avatar/parameters/MyInt 1i32" [...] />

Available argument value types (case insensitive):

• Bool: true or false
• Nil: nil
• Inf: inf
• Int: -1i32, 1i32, etc
• Long: -1i64, 1i64, etc
• Float: 1f32, 1.0f32, etc
• Double: 1f64, 1.0f64, etc

::ShutDown

Gracefully shuts down WlxOverlay-S. Useful when using an auto-restart script.

::PlayspaceReset

Resets the STAGE space to (0,0,0) with identity rotation.

::PlayspaceRecenter

Recenters the STAGE space position so that the HMD is in the center. Does not modify floor level.

::PlayspaceFixFloor

Adjusts the level of floor for STAGE and LOCAL_FLOOR spaces.

The user is asked to place one controller on the floor.