DOCSEARCHbyAlgolia
Submit Docs

ironbar

repository·master·Indexed 23 days ago

https://github.com/jakestanger/ironbar

A customizable, feature-rich GTK4 bar for Wayland compositors (Sway, Hyprland, and Niri) written in Rust. It supports high customization via CSS and various modules, including pre-configured 'Desktop' and 'Minimal' profiles. Version 0.19.0.

Tokens
58.8K
Snippets
109
Records
215
Agent score
79%

What's inside ironbar

  1. Use Ironvars for runtime configuration

    master

    Ironvars are runtime variables that can be referenced within your configuration files using the #variable_name syntax. They allow for dynamic configuration that updates automatically when the variable's value changes.

    Key constraints:

    • Keys: Must consist only of alphanumeric characters, -, and _.
    • Values: Any valid UTF-8 string.

    Setting values:

    • Use the IPC server (via the CLI) with the set command to update values at runtime.
    • Define default values in your top-level configuration using the ironvar_defaults key.
    #my_variable

  2. Target specific widgets and popups with CSS

    master

    You can target individual Ironbar widgets using several methods:

    1. By Name: Use a kebab-case class name matching the widget's name (e.g., .clock).
    2. By Popup: Prefix the widget name with popup- to target its popup (e.g., .popup-clock).
    3. By Instance Name: If you set the name option on a widget, you can target that specific instance using an ID (e.g., #my-custom-clock). For popups, use #popup-my-custom-clock.
    4. By Custom Class: You can add additional classes to a widget for reusable styling. For popups, use .popup-my-class.
    5. By GTK Type: Target all GTK widgets of a certain type using their lowercase name (e.g., label or button:hover).

    If a selector has no effect, try a more specific selector (e.g., instead of .popup-clipboard .item, use .popup-clipboard .item label).

    Use the command ironbar inspect to help identify how to address specific elements.

  3. Use the Music module to display playback info

    master

    The Music module displays the currently playing song from your music player. It supports two modes of operation:

    1. MPRIS mode: The widget listens to all MPRIS-compatible players and automatically detects and displays the active one.
    2. MPD mode: The widget connects to an MPD (Music Player Daemon) server.

    Clicking on the widget opens a popout that displays information about the current song, album art, and playback controls. You can control how long song titles are shown on the bar and in the popup using the truncate or marquee options.

  4. Use compound state in profiles

    master

    Some modules support 'compound' state, allowing a profile to match on multiple state values simultaneously (e.g., battery percentage AND charging status).

    When multiple profiles match, the most specific value for the state matchers takes precedence. For example, a profile matching both percent = 20 and charging = true will take precedence over a profile that only matches percent = 20.

    let {
  $battery = {
    type = "battery"
    format = "HIGH {percentage}%"
    profiles = {
      low.when = { percent = 20 }
      low.format = "LOW {percentage}%"
    
      // applies over `low` when charging.
      low-charging.when = { percent = 20 charging = true }
      low-charging.format = "LOW (CHARGING) {percentage}%"

      // applies over `medium-charging` when NOT charging.
      medium.when = { percent = 50 charging = false }
      medium.format = "MEDIUM {percentage}%"

      medium-charging.when = { percent = 50 }
      medium-charging.format = "MEDIUM (CHARGING) {percentage}%"

      good.when = { percent = 75 charging = false }
      good.format = "GOOD {percentage}%"

      good-charging.when = { percent = 75 charging = true }
      good-charging.format = "GOOD (CHARGING) {percentage}%"

      empty.when = { percent = 1 charging = true }
    }
  }
} in {
  end = [ $battery ]
}

  5. Understand PulseAudio terminology in the Volume module

    master

    The Volume module uses PulseAudio terminology to define audio sources and destinations. Understanding these terms is necessary for configuring sinks and sources:

    • Sink: A sound device producing audio coming out of your machine (e.g., speakers).
    • Source: A sound device receiving audio going into your machine (e.g., microphone).
    • SinkInput: An application or program sending sound to an existing sink (e.g., an app playing audio through speakers).
    • SourceOutput: An application or program receiving audio from a source (e.g., an app using a microphone).

  6. Choose between poll and watch modes for scripts

    master

    The mode setting determines how the script is executed and how the output is handled:

    • poll: Runs the script and waits for it to exit. Once the script exits, the label is updated with the full stdout content.
    • watch: Starts a long-running script. The label is updated to show the latest line every time the script writes to stdout.

    Note: watch mode may not work with all programs if they use block-buffering instead of line-buffering when output is piped.

  7. Execute commands in Ironbar

    master

    Buttons and sliders can execute commands.

    Shell Commands

    Prefix shell commands with an ! to execute them. Example: on_click = "!~/.local/bin/my-script.sh".

    Command Arguments

    Some widgets (like slider) pass their current value as an argument to the command. This can be accessed using $0.

    Built-in Bar Commands

    • popup:toggle
    • popup:open
    • popup:close

  9. Filter network devices by type or interface

    master

    To control which network devices appear in the bar, use types_blacklist, types_whitelist, interface_blacklist, or interface_whitelist.

    Device types are the same as those used by NetworkManager. You can identify the types on your system by running nmcli device status in a terminal.

    Supported Device Types: unknown, ethernet, wifi, bt, olpc_mesh, wimax, modem, infiniband, bond, vlan, adsl, bridge, generic, team, tun, ip_tunnel, macvlan, vxlan, veth, macsec, dummy, ppp, ovs_interface, ovs_port, ovs_bridge, wpan, six_lowpan, wireguard, wifi_p2p, vrf, loopback, hsr, and ipvlan.

  10. Use dynamic booleans for conditional visibility

    master

    You can control whether a module or property is active using dynamic booleans in fields like show_if. These accept either a script or a variable.

    • Scripts: Write the command directly without any special notation. Ironbar uses the script's exit code: 0 is true, and any other exit code is false. Only polling scripts are supported for booleans.
    • Variables: Use the #name syntax. The value is treated as false if it is an empty string, 0, or false. All other values are treated as true.

    This is useful for showing/hiding modules based on hardware presence or state variables.

  11. Embed dynamic scripts in labels

    master

    Any widget with a label attribute supports embedded scripts using the {{double braces}} shorthand syntax. This allows you to interpolate text from scripts dynamically.

    Both polling and watching modes are supported. For example, to show system uptime updated every 30 seconds:

    Uptime: {{30000:uptime -p | cut -d ' ' -f2-}}

  12. Use dynamic strings in configuration

    master

    Ironbar allows you to inject dynamic content into configuration fields using a mixture of static text, scripts, and variables.

    • Scripts: Wrap scripts in {{double braces}}. Ironbar supports both polling and watching scripts.
    • Variables: Use the #name syntax. Note that variables cannot be placed inside script braces.
    • Literal Hashes: To use a literal # character outside of a script, use ##.

    Use scripts for quick-to-fetch information (like uptime) and ironvars for complex or expensive data (like weather fetched via a module).