Skip to content

Customize UI

Jump to bottom
galister edited this page Sep 26, 2024 · 13 revisions

UI definitions are stored in yaml files under ~/.config/wlxoverlay.

First, let's grab some files that we can edit.

Customize Watch

cd ~/.config/wlxoverlay
wget https://github.com/galister/wlx-overlay-s/raw/main/src/res/watch.yaml

Customize Settings Panel

cd ~/.config/wlxoverlay
wget https://github.com/galister/wlx-overlay-s/raw/main/src/res/settings.yaml

Add a custom UI window of your own

Simply create any Yaml file in ~/.config/wlxoverlay with the correct format. You will be able to spawn it using the ShowUi type Button placed on an existing UI panel, such as the watch or settings.

Change the Primary Font

WlxOverlay-S uses one primary font for optimal resource usage. This font can be changed via conf.d.

echo 'primary_font: "JetBrains Mono:style=Bold"' > ~/.config/wlxoverlay/conf.d/font.yaml

The setting takes a fontconfig pattern. For help, see man fonts-conf, sections FONT PROPERTIES and FONT NAMES.

Do not include font size. Font size is instead set on the UI element.

Before you begin - Performance considerations

UI panels can be expensive.

  • Pick the smallest render resolution (size) that still looks OK. Increasing resolution will severely increase VRAM usage.
  • Pick 2-3 font sizes and use those same sizes across your panels. Loading additional font sizes will increase VRAM usage.
  • Compositing is not a simple task. It often makes sense to create one larger panel instead of many smaller ones (sacrifice VRAM in exchange for lighter CPU load).

Desktop Preview

There is a preview window that can be used for UI development.

To edit ~/.config/wlxoverlay/watch.yaml:

cargo run --features=uidev -- --uidev=watch

Once launched, the preview will refresh automatically when changes are made to the file.

The preview is currently non-interactive and won't react to mouse or keyboard input.

Basic UI Settings

  • size - render resolution of the panel. after changing this, you would need to to re-adjust the placement and sizes of elements.

  • width - size of the panel in 3D space, in meters. height will be calculated from the aspect ratio.

  • elements - the UI elements that will be drawn and may be interacted with

Elements are drawn in order of appearance, so make sure that your background Panel comes before your Label or Button.

Element Types

Panel

A colored rectangle, with optional rounded corners.

Example:

  - type: Panel
    rect: [0, 0, 400, 200]
    corner_radius: 5
    bg_color: "#353535"

Sprite

Displays an image / sprite from a sprite sheet.

Properties:

  • sprite: The path to the DDS texture file. Absolute, or relative to ~/.config/wlxoverlay.
  • sprite_st: List of 4 floats. First 2 elements are UV scale, last 2 elements are UV translation (offset).

Example:

  - type: Sprite
    rect: [0, 0, 64, 64]
    sprite: icons.dds # relative to ~/.config/wlxoverlay
    sprite_st: [1, 1, 0, 0] # to display entire image

Label

Displays some kind of text.

Static Label

Displays static text.

  - type: Label
    rect: [15, 35, 600, 70]
    font_size: 12
    fg_color: "#ffffff"
    source: Static
    text: Settings

Clock label

The clock label displays date, time or both with the provided format. See available formats here.

    source: Clock
    format: "%x"

Exec Label

Executes a command every interval seconds

    source: Exec
    command: ["echo", "hello world" ]
    interval: 0.5

By default, commands are not executed in a shell. You may explicitly call a shell as such:

    source: Exec
    command: [ "bash", "-c", "echo \"hello this is $USER\"" ]
    interval: 0.5

Ipd Label

Displays the current IPD in millimeters with 1 decimal precision

    source: Ipd

Internal Use

There are some types that are meant to be used internally, but feel free to use them, too. See: LabelContent

Button

Rectangular push-button with a background rectangle, a highlight layer and foreground text.

Buttons provide these events:

  • click_down
  • click_up
  • long_click_up
  • right_down
  • right_up
  • long_right_up
  • middle_down
  • middle_up
  • long_middle_up
  • scroll_down
  • scroll_up

Any number of actions can be attached to events. Actions are enumerated in order of appearance.

Example:

  - type: Button
    rect: [327, 52, 46, 32]
    corner_radius: 3
    font_size: 14
    fg_color: "#FFFFFF"
    bg_color: "#505050"
    text: "+"
    click_down:
      - type: Exec
        command: [ "pactl", "set-sink-volume", "@DEFAULT_SINK@", "+5%" ]
      - type: Toast
        message: Volume was raised!

Button actions

Exec

Executes a command.

      - type: Exec
        command: [ "pactl", "set-sink-volume", "@DEFAULT_SINK@", "+5%" ]

By default, commands are not executed in a shell. You may explicitly call a shell as such:

      - type: Exec
        command: [ "bash", "-c", "echo \"hello this is $USER\"" ]

VirtualKey

Send a keyboard press or release event.

      - type: VirtualKey
        keycode: XF86Launch3
        action: Press

Available key codes are listed here. Action can be Press or Release.

Toast

      - type: Toast
        message: Hello world!

Window

Create a window from mypanel.yaml:

      - type: Window
        target: mypanel
        action: ShowUi

Create a mirror (PipeWire window/region/screen):

      - type: Window
        target: M1
        action: ShowMirror

Destroy a window: Closes the window, stopping all captures and releasing resources such as swapchains. This can be used with windows spawned by ShowUi and ShowWindow.

      - type: Window
        target: M1
        action: Destroy

Overlay

These work on windows created with ShowUi / ShowMirror, as well as built-in overlays.

A showcase of this can be found on the kbd button in watch.yaml.

Internal Use

There are some types that are meant to be used internally, but feel free to use them, too. See: ButtonData, ButtonAction

Clone this wiki locally