wayvr/wlx-overlay-s/src/gui/README.md

Custom UI Elements

Elements on custom panels may be modified at runtime using wayvrctl.

For more, refer to: wayvrctl panel-modify --help

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" [...] />

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="..." />

Laser-color-specific variants are also available

• _press_left & _release_left for blue laser
• _press_right & _release_right for orange laser
• _press_middle & _release_middle for purple laser

Release after short/long press (length controlled by config long_press_duration)

• _short_release & _long_release for any laser
• _short_release_left & _long_release_left for blue laser
• _short_release_right & _long_release_right for orange laser
• _short_release_middle & _long_release_middle for purple laser

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.

::SendKey <VirtualKey> <UP|DOWN>

Sends a key using the virtual keyboard. If WayVR is focused, the key is sent to the WayVR app.

Supported VirtualKey values are listed here.

::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.