Skip to content

Customize UI

Jump to bottom
galister edited this page Apr 14, 2024 · 16 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 the same pattern that fc-match uses. Do not include font size.

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.

Example:

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

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

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]
    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%" ]

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