### Placer Configuration Example

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Example configuration for the 'placer' directive to define window cascade origins and steps.

```config
placer {
  xorigin = 5
  yorigin = 5
  xstep = 5
  ystep = 5
  children = false
}
```

--------------------------------

### TriggerAction Example

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Example of binding a custom trigger to an executable command.

```config
TriggerAction "mytrigger", Exec("MyCommand")
```

--------------------------------

### SFWBar startup function example

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Define a startup function to configure application mappings, icon mappings, filters, and window behavior upon launch.

```ini
# Startup function: runs once at launch
Function SfwBarInit() {
  MapAppId("firefox", ".*Mozilla Firefox");
  MapIcon("code", "visual-studio-code");
  FilterAppId("^xdg-desktop-portal.*");
  DisownMinimized(false);
}
```

--------------------------------

### Compile SFWBar from Source

Source: https://github.com/lbcrion/sfwbar/blob/main/README.md

Instructions for compiling SFWBar using Meson and Ninja. Ensure you have gtk3, gtk-layer-shell, and json-c installed.

```bash
meson setup build
ninja -C build
sudo ninja -C build install
```

--------------------------------

### Get Hyprland Clients

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Use hyprctl to get a list of clients, which can help in identifying window properties and app_ids.

```bash
hyprctl -j clients
```

--------------------------------

### Function Definition and Call

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Example of defining a custom function with parameters and calling it with a trigger.

```config
Function my_func ( x ) {
  Var y = "This is a test " + Str(x);
  Print(y);
  Return x+1;
}
TriggerAction "sometrigger", my_func(1);
```

--------------------------------

### Basic Bar Configuration Example

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Defines a bar with a launcher button and a label widget. The label displays swap usage percentage and is positioned at grid coordinates (2,1).

```config
bar "sfwbar" {
  button {
    value = "icon-name";
    style = "launcher";
    action[LeftClick] = Exec("firefox");
  }
  grid {
    label "mylabel" {
      value = "Some text";
    }
  }
}
```

--------------------------------

### Get Sway Window Tree

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Use swaymsg to get the window tree, which can help in identifying window properties and app_ids.

```bash
swaymsg -t get_tree
```

--------------------------------

### CSS Styling Example for Taskbar Buttons

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Example of how to style buttons within a taskbar widget using nested CSS conventions. Assumes the taskbar widget has been assigned the style 'mytaskbar'.

```css
grid#mytaskbar button { ... }
```

--------------------------------

### Get Interface Provider Module

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Returns the name of the module handling the specified interface.

```sfwbar
InterfaceProvider(<interface:string>)
```

--------------------------------

### SFWBar toplevel window configuration

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Define a toplevel window that can be opened and closed using specific actions. This example shows a simple about dialog.

```ini

window "aboutdialog" {
  label { value = "SFWBar v1.0beta17" }
  button {
    value = "window-close"
    action = WindowClose("aboutdialog")
  }
}
```

--------------------------------

### Define Grid Widget with CSS

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Example of defining a grid widget with custom CSS properties. The CSS applies to all elements within the grid.

```sfwbar
grid {
  css = "* { border: none }"

  label "id" {
    ...
  }
}
```

--------------------------------

### Configure Pipewire Module for Privacy Indicators

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Monitor Pipewire connection counts to display privacy indicators for audio and video. Use `PipewireCount()` to get connection counts.

```ini
#Api2

Module("pipewire");

bar {
  grid "privacy" {
    trigger = "pipewire"
    css = "* { -GtkWidget-direction: right; }"

    image {
      trigger = "pipewire"
      value   = "audio-input-microphone"
      style   = If(PipewireCount("AudioIn") > 0, "privacy_active", "hidden")
      tooltip = Str(PipewireCount("AudioIn")) + " mic connection(s)"
    }
    image {
      trigger = "pipewire"
      value   = "camera-web"
      style   = If(PipewireCount("VideoIn") > 0, "privacy_active", "hidden")
      tooltip = Str(PipewireCount("VideoIn")) + " camera connection(s)"
    }
  }
}
```

--------------------------------

### Get Entry Widget Text

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Retrieves the current text from a specified entry widget.

```sfwbar
EntryText(<id:string>)
```

--------------------------------

### Get Custom IPC Name

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Returns the name of the custom IPC currently in use, if any.

```sfwbar
CustomIPC()
```

--------------------------------

### Launch SFWBar with custom config and CSS

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Launch SFWBar specifying custom configuration and CSS files.

```sh
# Launch with a specific config file and CSS file
sfwbar -f ~/.config/sfwbar/mybar.config -c ~/.config/sfwbar/mybar.css
```

--------------------------------

### Execute Action on Widget Startup

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Specifies an action to be executed when the widget is initialized. Useful for setting initial widget configurations.

```sfwbar
action[0] = "SetInitialConfig"
```

--------------------------------

### NotificationCount

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar-ncenter.rst

Gets the count of notifications. Can be filtered by app ID.

```APIDOC
## NotificationCount([id])

### Description
Get count of the notifications. If the `id` is specified, this function returns the number of notifications for the app id of the notification referenced by the `id`, otherwise it will return the total count of notifications.

### Parameters
#### Path Parameters
- **id** (string) - Optional - The ID of a notification to filter the count by app ID.
```

--------------------------------

### GetTerm

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Gets the auto-detected terminal executable name. Returns a string.

```APIDOC
## GetTerm

### Description
Get the auto detected terminal executable name.

### Returns
- **string** - The name of the auto-detected terminal executable.
```

--------------------------------

### Configure SFWBar theme and icon theme

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Set the GTK theme and icon theme for SFWBar.

```ini
# Override GTK theme and icon theme
Theme "Adwaita-dark"
IconTheme "Papirus-Dark"
```

--------------------------------

### Get Bar Direction

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Returns the direction of the bar containing the current widget.

```sfwbar
BarDir()
```

--------------------------------

### SFWBar Window Placer Configuration

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Configures smart floating window placement behavior. Adjust origin and step values to control initial placement and cascade behavior. Set 'children' to true to also place child windows.

```ini
#Api2

placer {
  xorigin  = 5    # start X position (% of desktop width)
  yorigin  = 5    # start Y position (% of desktop height)
  xstep    = 5    # horizontal cascade step (%)
  ystep    = 5    # vertical cascade step (%)
  children = true # also place child windows (same PID)
}
```

--------------------------------

### Mid

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Extracts a substring from a string based on start and end character positions.

```APIDOC
## Mid

### Description
Extract a substring from a string, the first parameter is the string to extract the substring from, second and third parameters are the first and last characters of the substring.

### Parameters
#### Query Parameters
- **string_value** (string) - Required - The string to extract the substring from.
- **start_char** (number) - Required - The starting character index (inclusive).
- **end_char** (number) - Required - The ending character index (inclusive).
```

--------------------------------

### Configure XKB Layout Module

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Convert between xkb layout name types. Use `XkbMap()` to transform layout descriptions and `SetLayout()` to change layouts.

```ini
#Api2

Module("xkbmap");

bar {
  label "language" {
    trigger = "sway"
    # Convert from full description to brief abbreviation, e.g. "English (US)" -> "en"
    value   = Upper(XkbMap(Layout(), "description", "brief"))
    tooltip = "Layout: " + Layout() + "\n" +
              "Brief: " + XkbMap(Layout(), "description", "brief")
    action[LeftClick]  = SetLayout("next")
    action[RightClick] = SetLayout("prev")
  }
}
```

--------------------------------

### Build Dynamic Wi-Fi Network List

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Dynamically builds a Wi-Fi network list for a popup menu. Requires the 'wifi-conf' trigger to be set.

```Sfwbar Script
TriggerAction "wifi-conf", {
  Var netid = $id;
  Config("
    menu 'wifi_nets' {
      item '" + netid + "' {
        value = WifiGet('" + netid + "','SSID') + ' (' + Str(WifiGet('" + netid + "','Strength')) + '%)';
        icon = If(WifiGet('" + netid + "','Connected'),'network-wireless','network-wireless-offline');
        action = WifiConnect('" + netid + "');
      }
    }
  ");
}

TriggerAction "wifi-conf-removed", MenuItemClear($id);

bar {
  button "wifi" {
    trigger = "wifi-level"
    value   = Lookup(NetStat("signal"), -50,"network-wireless-signal-excellent",
                -65,"network-wireless-signal-good", -75,"network-wireless-signal-ok",
                "network-wireless-signal-weak")
    tooltip = "SSID: " + NetInfo("essid") + "\nSignal: " + Str(NetStat("signal")) + " dBm"
    action[LeftClick]  = Menu("wifi_nets")
    action[RightClick] = WifiScan(15)
  }
}
```

--------------------------------

### bar.button "launcher"

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Configures a launcher button with various click actions and a startup action.

```APIDOC
## bar.button "launcher"

### Description
Configures a launcher button with various click actions and a startup action.

### Method
N/A (Configuration)

### Endpoint
N/A (Configuration)

### Parameters
N/A

### Request Example
N/A

### Response
N/A

## Actions
- `action[LeftClick]`: Executes `Exec("firefox")`.
- `action[Ctrl+LeftClick]`: Executes `Exec("firefox --private-window")`.
- `action[MiddleClick]`: Executes `ExecTerm("htop")`.
- `action[RightClick]`: Opens a menu defined by `Menu("browser_menu")`.
- `action[ScrollUp]`: Controls volume with `VolumeCtl("sink-volume +2")`.
- `action[ScrollDown]`: Controls volume with `VolumeCtl("sink-volume -2")`.
- `action[0]`: Runs `SetStyle("launcher_active")` at startup.
```

--------------------------------

### Manage Bluetooth Devices

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Dynamically builds a Bluetooth device menu. Requires the 'bluez-conf' trigger and the 'bluez.so' module.

```Sfwbar Script
#Api2

Module("bluez");

# Dynamically build bluetooth device menu
TriggerAction "bluez-conf", {
  Var devpath = $path;
  Config("
    menu 'bt_devs' {
      item '" + devpath + "' {
        value = BluezDevice('" + devpath + "','Name');
        icon  = BluezDevice('" + devpath + "','Icon');
        action = If(BluezDevice('" + devpath + "','Connected'),
          BluezDisconnect('" + devpath + "'),
          BluezConnect('" + devpath + "'));
      }
    }
  ");
}

TriggerAction "bluez-conf-removed", MenuItemClear($path);

bar {
  button "bluetooth" {
    trigger = "bluez-adapter"
    value   = If(BluezDevice("","Running"), "bluetooth-active", "bluetooth-disabled")
    tooltip = "Bluetooth: " + If(BluezAdapter("Powered"),"On","Off") + 
              "\nDevices visible: " + If(BluezAdapter("Discoverable"),"Yes","No") + 
              "\nScanning: " + If(BluezAdapter("Discovering"),"Yes","No")
    action[LeftClick]  = Menu("bt_devs")
    action[RightClick] = BluezScan(20)
  }
}
```

--------------------------------

### List available monitors in SFWBar

Source: https://context7.com/lbcrion/sfwbar/llms.txt

List all available monitors that SFWBar can target.

```sh
# List available monitors
sfwbar -m list
```

--------------------------------

### Get Widget Children

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Returns a list of child widgets. The 'id' parameter is optional and defaults to the current widget.

```sfwbar
WidgetChildren([<id:string>])
```

--------------------------------

### Configure Scanners for System Data

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Sets up various scanners to extract system information from files like /proc/stat and /proc/meminfo, command outputs (curl), and IPC streams (rfkill, Sway). Aggregates CPU stats and reads memory details.

```ini
#Api2

# Read from /proc with regex parser - aggregates CPU stats
scanner {
  File("/proc/stat", NoGlob) {
    CpuUser   = RegEx("^cpu [\t ]*([0-9]+)", Sum)
    CpuNice   = RegEx("^cpu [\t ]*[0-9]+ ([0-9]+)", Sum)
    CpuSystem = RegEx("^cpu [\t ]*[0-9]+ [0-9]+ ([0-9]+)", Sum)
    CpuIdle   = RegEx("^cpu [\t ]*[0-9]+ [0-9]+ [0-9]+ ([0-9]+)", Sum)
  }
  # Read from /proc/meminfo
  File("/proc/meminfo", NoGlob) {
    MemTotal = RegEx("^MemTotal:[\t ]*([0-9]+)")
    MemFree  = RegEx("^MemFree:[\t ]*([0-9]+)")
    MemCache = RegEx("^Cached:[\t ]*([0-9]+)")
    MemBuff  = RegEx("^Buffers:[\t ]*([0-9]+)")
  }
  # JSON from an external command
  Exec("curl -s 'https://wttr.in/?format=j1'") {
    WeatherTemp  = Json(".current_condition.0.temp_C")
    WeatherDesc  = Json(".current_condition.0.weatherDesc.0.value")
  }
  # Persistent client: reads output lines asynchronously
  ExecClient("stdbuf -oL rfkill monitor --json", "rfkill") {
    RfkillType  = Json(".type")
    RfkillSoft  = Json(".soft")
    RfkillHard  = Json(".hard")
  }
  # Sway IPC events
  SwayClient() {
    SwayLang = Json(".input.xkb_active_layout_name")
  }
}

# Intermediate variable computed from scanner vars
set CpuUtilization = 1 - CpuIdle.val / (CpuIdle.val + CpuUser.val + CpuSystem.val)

# Widget using scanner data
bar {
  label {
    interval = 1000
    value = "CPU: " + Str(CpuUtilization * 100, 1) + "% " +
            "Mem: " + Str((MemTotal-MemFree-MemCache-MemBuff)/MemTotal*100,0) + "%"
  }
}
```

--------------------------------

### Get GTK+ Event Position

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Returns the position of a GTK+ event. The 'axis' parameter can be 'x', 'y', or 'dir'. The value is a fraction of the widget's size.

```sfwbar
GtkEvent(<axis:string>)
```

--------------------------------

### Configure Application Menu Module

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Automatically build a categorized application launcher menu. Use `AppMenuFilter()`, `AppMenuItemTop()`, `AppMenuItemBottom()`, and `AppMenuSetFlat()` to customize the menu.

```ini
#Api2

Module("appmenu");

Function SfwBarInit() {
  # Exclude specific desktop entries
  AppMenuFilter "xterm.desktop"
  AppMenuFilter "xfce4-terminal.desktop"

  # Add custom items to the top of the menu
  AppMenuItemTop "%system-shutdown%Power Off", "systemctl poweroff"
  AppMenuItemTop "%system-reboot%Reboot",      "systemctl reboot"

  # Add custom items to the bottom
  AppMenuItemBottom "%preferences-system%Settings", "gnome-control-center"

  # Show all apps flat (no categories)
  AppMenuSetFlat false
}

bar {
  button "startmenu" {
    value  = "start-here"
    style  = "startmenu"
    action = Menu("app_menu_system")
  }
}
```

--------------------------------

### Get Widget State

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Returns a boolean value of a widget's state. The 'id' parameter is optional. Valid 'stateid' values are 1 or 2.

```sfwbar
WidgetState([<id:string>,] <stateid:number>)
```

--------------------------------

### Action to Open Toplevel Window

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Use the WindowOpen action on a bar widget to open a defined toplevel window. Unlike popups, toplevel windows can be placed anywhere by the compositor.

```sfwbar
bar {
    button {
     value = "open-icon";
     action = WindowOpen("mywindow");
    }
  }
```

--------------------------------

### Array Lookup for Dynamic Icons

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Initializes SFWBar by defining thresholds and corresponding icons for battery levels. It uses `ArrayLookup` to determine the appropriate icon based on the current battery level.

```ini
#Api2

# Array operations
Function SfwBarInit() {
  Var thresholds = [80, 60, 40, 20];
  Var icons = ["battery-full","battery-good","battery-low","battery-caution","battery-empty"];
  Var icon = ArrayLookup(BatteryLevel, thresholds, icons, "battery-empty");
  Print("Battery icon: " + icon);
}
```

--------------------------------

### WiFi Module Initialization

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Initializes the WiFi module, allowing interaction with NetworkManager or IWD for scanning and connecting to networks.

```ini
#Api2

Module("wifi-nm");   # or Module("wifi-iwd")
```

--------------------------------

### Include External Widget Configuration

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Use this syntax to include the contents of another configuration file into the current bar definition. The specified widget will be processed and placed into the bar.

```sfwbar
bar {
  widget "MyWidget.widget"
}
```

--------------------------------

### SFWBar bar layout configuration

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Configure the main panel, including its edge, size, layer, alignment, and monitor binding. Widgets like buttons, labels, taskbars, pagers, trays, and clocks can be placed within the bar.

```ini
#Api2

bar "sfwbar" {
  edge = "bottom"          # top | bottom | left | right
  layer = "top"            # top | bottom | overlay | background
  size = "auto"            # pixels, "80%", or "auto"
  halign = "center"        # start | center | end
  mirror = "*"             # mirror to all monitors
  exclusive_zone = "auto"
  sensor = 300             # autohide: hide after 300ms
  sensor_delay = 200       # reappear after 200ms hover
  transition = 500         # animation duration (ms)
  monitor = "eDP-1"        # bind to specific monitor

  # A launcher button
  button {
    value = "firefox"
    style = "launcher"
    action[LeftClick] = Exec("firefox");
    tooltip = "Open Firefox"
  }

  # Expanding spacer
  label {
    css = "* { -GtkWidget-hexpand: true; }"
  }

  # Taskbar
  taskbar {
    style = "taskbar"
    rows = 1
    icons = true
    labels = true
    title_width = 30
    sort = false
    filter = workspace        # only show windows from current workspace
    group = popup             # group by app_id with popup on hover
    action[RightClick] = Menu("winops");
    action[Drag] = Focus();
  }

  # Pager with workspace preview
  pager {
    style = "pager"
    rows = 1
    pins = "1","2","3","4"
    preview = true
    primary_axis = rows
    action[Drag] = WorkspaceActivate();
  }

  # System tray
  tray {
    rows = 1
    sort = false
    primary_axis = rows
  }

  # Clock
  widget "clock.widget" {
    time_format = "%H:%M"
    tooltip_format = "%H:%M\n%x"
  }
}
```

--------------------------------

### SFWBar Task Switcher Configuration

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Configures the Alt-Tab window switcher popup. Options control activation delay, icon/label display, layout columns, filtering, and sorting. The 'css' property allows custom styling.

```ini
#Api2

switcher {
  disable       = false
  interval      = 700       # ms after last switch before activating focus
  icons         = true
  labels        = false
  cols          = 6
  filter        = workspace # floating | minimized | output | workspace
  sort          = true
  primary_axis  = cols
  css           = "window#switcher { border: 1px solid @borders; border-radius: 8px; padding: 40px; }"
}
```

```shell
# In sway: bind Alt-Tab
# bindsym Alt+Tab bar hidden_state toggle

# For other compositors, bind a key to:
# killall -SIGUSR1 sfwbar
```

--------------------------------

### SFWBar Native Function: Exec

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Executes a shell command. Returns n/a.

```sfwbar
Exec("<string>")
```

--------------------------------

### Configure DBus Module for Watching and Subscribing

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Integrate with DBus services to watch for name changes and subscribe to signals. Use `DBusWatch()` and `DBusSubscribe()` for these operations.

```ini
#Api2

Module("dbus");

Function SfwBarInit() {
  # Watch for NetworkManager on the system bus
  DBusWatch("system", "org.freedesktop.NetworkManager", "nm-watch");

  # Subscribe to UPower's DeviceChanged signal
  DBusSubscribe(
    ["system","org.freedesktop.UPower","/org/freedesktop/UPower","org.freedesktop.UPower"],
    "DeviceChanged", "upower-changed");
}

TriggerAction "nm-watch", {
  If $DBusStatus = "appeared"
    Exec("notify-send 'NetworkManager' 'Service started'")
  Else
    Exec("notify-send 'NetworkManager' 'Service stopped'")
}

TriggerAction "upower-changed", {
  # DBusSignal contains signal parameters as an sfwbar array
  Print("UPower device changed: " + $DBusSignal[0]);
}

# Call a DBus method directly
Function GetHostname() {
  Var addr = ["system","org.freedesktop.hostname1",
              "/org/freedesktop/hostname1","org.freedesktop.DBus.Properties"];
  Var result = DBusCall(addr, "Get", "(ss)", ["org.freedesktop.hostname1","Hostname"]);
  Return result[0];
}
```

--------------------------------

### SwayWinCmd

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Sends a command over Sway IPC that is applicable to the current window.

```APIDOC
## SwayWinCmd

### Description
Send a command over Sway IPC applicable to a current window.

### Parameters
#### Query Parameters
- **command** (string) - Required - The command to send over Sway IPC applicable to the current window.
```

--------------------------------

### SFWBar button actions for popups and toplevel windows

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Configure buttons within a bar to trigger popup windows on left-click and toplevel windows on right-click.

```ini

bar {
  button {
    value = "network-wireless"
    action[LeftClick] = PopUp("myinfo");
    action[RightClick] = WindowOpen("aboutdialog");
  }
}
```

--------------------------------

### Execute Client and Parse JSON

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Executes a client command, waits for its output, and parses it as JSON. The 'trigger' parameter identifies the source.

```sfwbar
ExecClient("stdbuf -oL foo.sh BAR BAZ", "foo") {
    Foo_foo = Json(".foo")
    Foo_bar = Json(".bar")
  }
```

--------------------------------

### Menu

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Opens a menu attached to the widget executing the action. Returns n/a.

```APIDOC
## Menu

### Description
Open a menu with a specified name. The menu will be attached to the widget executing the action.

### Parameters
#### Path Parameters
- **string** (string) - Required - The name of the menu to open.
```

--------------------------------

### Reload SFWBar configuration

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Reload SFWBar's configuration by sending the SIGHUP signal to the process.

```sh
# Reload configuration by sending SIGHUP
killall -SIGHUP sfwbar
```

--------------------------------

### Format Network Information with String Manipulation

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Displays the uppercased first 12 characters of the network's ESSID and shows network details like IP, CIDR, and Gateway in the tooltip. Utilizes `Upper`, `Mid`, and `NetInfo` functions.

```ini
#Api2

# String manipulation
bar {
  label {
    interval = 60000
    value = Upper(Mid(NetInfo("essid"), 1, 12))
    tooltip = "IP: " + NetInfo("ip") + "/" + NetInfo("cidr") + 
              "\nGW: " + NetInfo("gateway")
  }
}
```

--------------------------------

### Configure BSD Sysctl Module

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Query BSD sysctl values directly from widget expressions. Use `BSDCtl()` to retrieve system control values.

```ini
#Api2

Module("bsdctl");

bar {
  label {
    interval = 2000
    value = "CPU: " + Str(Val(BSDCtl("hw.sensors.cpu0.temp0")) - 273.15, 1) + "°C"
    tooltip = "Load: " + BSDCtl("vm.loadavg") +
              "\nMem: "  + BSDCtl("hw.physmem")
  }
}
```

--------------------------------

### bar.taskbar

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Defines actions for window management within the taskbar context.

```APIDOC
## bar.taskbar

### Description
Defines actions for window management within the taskbar context.

### Method
N/A (Configuration)

### Endpoint
N/A (Configuration)

### Parameters
N/A

### Request Example
N/A

### Response
N/A

## Actions
- `action[LeftClick]`: Activates focus with `Focus()`.
- `action[MiddleClick]`: Closes the window with `Close()`.
- `action[RightClick]`: Opens a menu defined by `Menu("winops")`.
- `action[Shift+LeftClick]`: Minimizes the window with `Minimize()`.
- `action[Drag]`: Activates focus with `Focus()`.
```

--------------------------------

### Simple Memory Usage Widget

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar-widgets.rst

This widget reads /proc/meminfo, extracts memory statistics, calculates the percentage of memory in use, and displays it as a label. The scanner processes the file when variables are accessed, and the label updates at a specified interval.

```sfwbar
scanner {
  file("/proc/meminfo") {
    MemTotal = RegEx("^MemTotal:[\t ]*([0-9]+)[\t ]")
    MemFree = RegEx("^MemFree:[\t ]*([0-9]+)[\t ]")
    MemCache = RegEx( "^Cached:[\t ]*([0-9]+)[\t ]")
    MemBuff = Regex("^Buffers:[\t ]*([0-9]+)[\t ]")
  }
}

layout {
  label {
    interval = 500
    value = Str((MemTotal-MemFree-MemCache-MemBuff)/MemTotal*100) + "%"
  }
}
```

--------------------------------

### Define a Menu with Items and Submenu

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Define a menu named 'menu_name' with a basic item, a separator, and a submenu. Menu items can execute commands or open other menus.

```sfwbar
menu "menu_name" {
    item {
      value = "item1";
      tooltip = "the first item";
      action = Exec("command");
    }
    separator;
    item {
      value = "sub";
      menu "mysubmenu" {
        item {
          value = "item2";
          action = SwayCmd("focus next");
        }
      }
    }
  }
```

--------------------------------

### System Information Functions

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Functions for retrieving disk usage, active window information, and widget details.

```APIDOC
## Disk

### Description
Queries disk information for a disk. `fs` specifies a mount point to query. `info` specifies desired information.

### Parameters
- **fs** (string) - The mount point of the disk.
- **info** (string) - The desired information (e.g., `total`, `avail`, `free`, `%avail`, `%used`).

### Returns
<number>

## ActiveWin

### Description
Returns a tile of the currently focused window.

### Returns
<string>

## WindowInfo

### Description
Queries information about a window. Optional parameter `id` specifies the the widget id of a taskbar item corresponding to a window to query. If omitted the widget calling the function is used. `query` parameter specifies the data to query.

### Parameters
- **id** (string) - Optional. The widget id of a taskbar item.
- **query** (string) - The data to query (e.g., `appid`, `title`, `minimized`, `maximized`, `fullscreen`, `focused`).

### Returns
<string> or <number> depending on the query.

## WidgetId

### Description
Returns an ID of a widget invoking the action.

### Returns
<string>

## WidgetSetData

### Description
Sets data for a widget.

### Parameters
- **id** (string) - Optional. The widget ID.
- **name** (string) - The name of the data field.
- **value** (any) - The value to set.

### Returns
None.
```

--------------------------------

### Configure Taskbar Labels

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Determines whether application titles are shown in the Taskbar widget.

```sfwbar
labels = true
```

--------------------------------

### Set Widget Value Property

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Demonstrates setting the 'value' property for a widget. This can be a static string, number, or a dynamic expression.

```sfwbar
value = "Value is:" + $MyString
```

--------------------------------

### Target a specific monitor with SFWBar

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Specify the monitor to which SFWBar should bind.

```sh
# Target a specific monitor
sfwbar -m eDP-1
```

--------------------------------

### Print

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Prints a string to standard output, useful for debugging user functions. Returns n/a.

```APIDOC
## Print

### Description
Print a string to standard output. Useful for debugging user functions.

### Parameters
#### Path Parameters
- **string** (string) - Required - The string to print.
```

--------------------------------

### FileTrigger

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Sets up a file monitor. Upon changes to the file, a trigger is emitted. An optional timeout can be specified to emit the trigger periodically. Returns n/a.

```APIDOC
## FileTrigger

### Description
Setup a file monitor. Upon any changes to the file, a trigger will be emitted. If the timeout is specified, the trigger will be emitted at an interval specified by timeout value (in microseconds) until the first file monitor event is detected (this is useful for /sys files where monitoring may not be effective.

### Parameters
#### Path Parameters
- **file:string** (string) - Required - The path to the file to monitor.
- **trigger:string** (string) - Required - The name of the trigger to emit upon file change.
- **timeout:numeric** (numeric) - Optional - The interval in microseconds to emit the trigger if no file change is detected.
```

--------------------------------

### Button Actions Configuration

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Defines various actions for a button, including launching applications, opening terminals, and displaying menus, with support for modifier keys like Ctrl.

```ini
#Api2

bar {
  button "launcher" {
    value = "firefox"
    # Modifier+event combinations
    action[LeftClick]       = Exec("firefox")
    action[Ctrl+LeftClick]  = Exec("firefox --private-window")
    action[MiddleClick]     = ExecTerm("htop")
    action[RightClick]      = Menu("browser_menu")
    action[ScrollUp]        = VolumeCtl("sink-volume +2")
    action[ScrollDown]      = VolumeCtl("sink-volume -2")
    # action[0] runs at startup
    action[0]               = SetStyle("launcher_active")
  }

  # Window management actions (only valid inside taskbar context)
  taskbar {
    action[LeftClick]       = Focus()
    action[MiddleClick]     = Close()
    action[RightClick]      = Menu("winops")
    action[Shift+LeftClick] = Minimize()
    action[Drag]            = Focus()
  }
}

# Trigger-bound action
TriggerAction "network", {
  Var ip = NetInfo("ip");
  If ip = ""
    SetStyle("net_button", "disconnected")
  Else
    SetStyle("net_button", "connected")
}
```

--------------------------------

### MpdServer

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar-mpd.rst

Initializes the connection to an MPD server. If not called, it falls back to environment variables or default socket/host.

```APIDOC
## MpdServer

### Description
Specify an address for an MPD server to use. The address is specified using the MPD_HOST convention ([password@]host[:port], where a host can be a local socket or an abstract socket prefixed by @).

### Parameters
#### Path Parameters
- **address** (string) - Required - The address of the MPD server.
```

--------------------------------

### SFWBar Native Function: Config

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Processes a snippet of the configuration file to change the bar configuration on the fly. Returns n/a.

```sfwbar
Config("<string>")
```

--------------------------------

### TriggerAction "volume-conf"

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Sets the default audio sink to 'Headphones' if the device description matches.

```APIDOC
## TriggerAction "volume-conf"

### Description
Sets the default audio sink to 'Headphones' if the device description matches.

### Method
N/A (Configuration)

### Endpoint
N/A (Configuration)

### Parameters
N/A

### Request Example
N/A

### Response
N/A

## Logic
- If `VolumeInfo("sink-description", $device_id)` equals "Headphones", then `VolumeCtl($device_id, "sink-set-default")` is executed.
```

--------------------------------

### Config

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Processes a snippet of configuration file, allowing for on-the-fly changes to the bar's configuration. Returns n/a.

```APIDOC
## Config

### Description
Processes a snippet of configuration file. This action permits changing the bar configuration on the fly.

### Parameters
#### Path Parameters
- **string** (string) - Required - The configuration snippet to process.
```

--------------------------------

### SFWBar Native Function: Print

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Prints a string to standard output, useful for debugging user functions. Returns n/a.

```sfwbar
Print("<string>")
```

--------------------------------

### Debug Application IDs

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Run sfwbar with the -d -g app_id flags to debug and identify application IDs of running programs.

```bash
sfwbar -d -g app_id
```

--------------------------------

### SFWBar popup window configuration

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Define a popup window that can be triggered by widget actions. It supports auto-closing and can contain various widgets like labels and buttons.

```ini
#Api2

popup "myinfo" {
  AutoClose = true
  label {
    value = "IP: " + NetInfo("ip") + "\nGateway: " + NetInfo("gateway")
    trigger = "network"
  }
  button {
    value = "close-symbolic"
    action = PopUp("myinfo")
  }
}
```

--------------------------------

### Specify Sway IPC socket and bar ID

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Configure SFWBar to use a specific Sway IPC socket and listen on a particular bar ID.

```sh
# Specify a sway IPC socket and listen on a specific bar ID
sfwbar -s /run/user/1000/sway-ipc.sock -b bar-0
```

--------------------------------

### Bind Task Switcher in Other Compositors

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

How to bind a key to trigger the sfwbar task switcher using SIGUSR1 in compositors other than Sway.

```bash
killall -SIGUSR1 sfwbar
```

--------------------------------

### Action to Display a Menu

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Use the Menu action on a bar widget to display a user-defined menu. The menu is identified by its name.

```sfwbar
bar {
    ...
    button {
      value = "menu-icon";
      action = Menu("menu_name");
    }
  }
```

--------------------------------

### ExecTerm

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Executes a shell command in a terminal. Returns n/a.

```APIDOC
## ExecTerm

### Description
Execute a shell command in a terminal.

### Parameters
#### Path Parameters
- **string** (string) - Required - The shell command to execute in a terminal.
```

--------------------------------

### BluezDevice Properties

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar-bluez.rst

Fetches a property for a Bluez device specified by its path.

```APIDOC
## BluezDevice(<path>, <property>)

### Description
Fetches a property for a bluez device specified by `path`.

### Parameters
*   **path** (string) - The path of the Bluez device.
*   **property** (string) - The property to retrieve. Supported properties include:
    *   "Name"
    *   "Address"
    *   "Icon"
    *   "MajorClass"
    *   "MinorClass"
    *   "Paired"
    *   "Trusted"
    *   "Connected"
    *   "Connecting"
    *   "Running"

### Returns
*   (string | boolean | numeric) - The value of the requested property.
```

--------------------------------

### Define SFWBar expression macros

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Define reusable expression macros for common values or expressions.

```ini
# Define a reusable expression macro
Define ThicknessHint = "28px"
Set ImagePath = "icons/misc"
```

--------------------------------

### SFWBar Native Function: ExecRead

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Executes a shell command and returns its output as a string.

```sfwbar
ExecRead("<string>")
```

--------------------------------

### Display Disk Space Usage

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Shows the percentage of used space on the root partition and displays free space in GB for root and home partitions in the tooltip. Uses `Disk` and `Str` functions for formatting.

```ini
#Api2

# File and disk queries
bar {
  label {
    interval = 30000
    tooltip = "Root: " + Str(Disk("/","avail")/1073741824,1) + " GB free\n" +
              "Home: " + Str(Disk("/home","avail")/1073741824,1) + " GB free"
    value = Str(Disk("/","%used")*100,0) + "%"
  }
}
```

--------------------------------

### SwayCmd

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Sends a command over Sway IPC.

```APIDOC
## SwayCmd

### Description
Send a command over Sway IPC.

### Parameters
#### Query Parameters
- **command** (string) - Required - The command to send over Sway IPC.
```

--------------------------------

### InterfaceProvider

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Returns a name of a module currently handling the specified interface.

```APIDOC
## InterfaceProvider

### Description
Returns a name of a module currently handling the specified interface.

### Method
GET

### Endpoint
/interface/provider

### Parameters
#### Query Parameters
- **interface** (string) - Required - The name of the interface to query.
```

--------------------------------

### SFWBar Native Function: ExecTerm

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Executes a shell command within a terminal. Returns n/a.

```sfwbar
ExecTerm("<string>")
```

--------------------------------

### Set Widget Tooltip

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Configures a tooltip for a widget. The tooltip can be static text or an expression that updates dynamically.

```sfwbar
tooltip = "$MyDynamicTooltip"
```

--------------------------------

### Apply Background Effect to Widget

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Requests the compositor to apply a background effect, such as blur, underneath the widget.

```sfwbar
background_effect = "blur"
```

--------------------------------

### Exit

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Terminates SFWBar.

```APIDOC
## Exit

### Description
Terminate SFWBar.
```

--------------------------------

### Keyboard Layout

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Retrieves the current keyboard layout.

```APIDOC
## Layout

### Description
Returns the current keyboard layout.

### Returns
<string>
```

--------------------------------

### SetLayout

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Switches the current keyboard layout to the next or previous one.

```APIDOC
## SetLayout

### Description
Switches current keyboard layout. The string parameter can have values "next" or "prev" for next or previous layout respectively.

### Parameters
#### Query Parameters
- **layout_direction** (string) - Required - Can be either "next" or "prev".
```

--------------------------------

### SFWBar Expression Syntax

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

SFWBar supports expressions for dynamic values in configurations. These expressions can include arithmetic operations, comparisons, conditional logic, and function calls.

```sfwbar
Var my_var = 1 + my_func(2);
```

```sfwbar
Var my_array = [1,2,3];
Var my_var = my_array[2];
```

--------------------------------

### Notification Center Widget

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Receives and manages desktop notifications. Requires the 'ncenter.so' module and the 'notification-updated' trigger.

```Sfwbar Script
#Api2

Module("ncenter");

# Dynamically add/remove notification widgets
TriggerAction "notification-updated", {
  Var nid = $id;
  Config("
    grid '" + nid + "' {
      trigger = 'notification-updated'
      css = '* { -GtkWidget-direction: right; }'
      image  { value = '" + $icon + "'; style = 'notif_icon' }
      grid {
        css = '* { -GtkWidget-direction: bottom; }'
        label { value = '<b>" + Markup($summary) + "</b>'; style = 'notif_title' }
        label { value = '"  + Markup($body)    + "'; style = 'notif_body' }
      }
      button {
        value  = 'window-close'
        action = NotificationClose(" + nid + ")
      }
    }
  ");
}

TriggerAction "notification-removed", ClearWidget($id);

bar {
  button "ncenter" {
    trigger = "notification-updated"
    value   = "notification-symbolic"
    tooltip = Str(NotificationCount()) + " notifications"
    action  = PopUp("notification_popup")
  }
}
```

--------------------------------

### BluezAdapter Properties

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar-bluez.rst

Queries the state of the default Bluetooth adapter.

```APIDOC
## BluezAdapter(<property>)

### Description
Queries the state of the default adapter.

### Parameters
*   **property** (string) - The property to query. Supported properties include:
    *   "Count"
    *   "Discovering"
    *   "Discoverable"
    *   "Powered"

### Returns
*   (numeric | boolean) - The value of the requested property.
```

--------------------------------

### PipeRead

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Processes a snippet of configuration sourced from the output of a shell command, enabling configuration updates from scripts. Returns n/a.

```APIDOC
## PipeRead

### Description
Processes a snippet of configuration sourced from an output of a shell command. This function can be used to update SFWBar configuration from a script.

### Parameters
#### Path Parameters
- **string** (string) - Required - The configuration snippet sourced from a shell command output.
```

--------------------------------

### SFWBar Native Function: Menu

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Opens a menu with the specified name, attached to the widget executing the action. Returns n/a.

```sfwbar
Menu(<string>)
```

--------------------------------

### BluezPair

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar-bluez.rst

Attempts to pair and connect to a Bluetooth device.

```APIDOC
## BluezPair(<path>)

### Description
Attempt to pair and connect to the bluetooth device specified by `path`.

### Parameters
*   **path** (string) - The path of the Bluetooth device to pair and connect to.
```

--------------------------------

### File System Functions

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Functions for reading file contents, listing directories, and checking file existence.

```APIDOC
## Read

### Description
Reads the contents of a file and returns them as a string.

### Parameters
- **string** (string) - The path to the file to read.

### Returns
<string>

## ls

### Description
Retrieves a list of files in a directory specified by the parameter.

### Parameters
- **string** (string) - The path to the directory.

### Returns
<array>

## TestFile

### Description
Check if the file exists and is readable by the SFWBar process.

### Parameters
- **string** (string) - The path to the file.

### Returns
<number>
```

--------------------------------

### MPD Music Player Widget

Source: https://context7.com/lbcrion/sfwbar/llms.txt

Controls Music Player Daemon (MPD) playback and displays song metadata. Requires the 'mpd.so' module and an MPD server connection.

```Sfwbar Script
#Api2

Module("mpd");

# Optional: override default server address
Function SfwBarInit() {
  MpdServer("localhost:6600");
}

# Compute song progress including live elapsed time
set MpdProgress = (Val(MpdInfo("elapsed")) +
  If(MpdInfo("state")="play", Val(MpdInfo("age"))/1000000, 0)) /
  Val(MpdInfo("duration"));

bar {
  grid "mpdwidget" {
    trigger = "mpd"
    css = "* { -GtkWidget-direction: right; }"

    image {
      value   = MpdInfo("cover")
      trigger = "mpd"
      style   = If(MpdInfo("cover")="","hidden","mpd_cover")
    }
    label {
      trigger = "mpd"
      value   = MpdInfo("Artist") + " – " + MpdInfo("Title")
      tooltip = "Album: " + MpdInfo("Album") + "\nFile: " + MpdInfo("file")
    }
    scale {
      value    = MpdProgress
      interval = 1000
      action   = MpdCmd("seekcur " + Str(GtkEvent("x") * Val(MpdInfo("Duration"))))
    }
    image {
      value  = "media-skip-backward"
      action = MpdCmd("previous")
    }
    image {
      value  = If(MpdInfo("state")="play","media-playback-pause","media-playback-start")
      trigger = "mpd"
      action = MpdCmd(If(MpdInfo("state")="play","pause","play"))
    }
    image {
      value  = "media-skip-forward"
      action = MpdCmd("next")
    }
  }
}
```

--------------------------------

### SFWBar Native Function: Exit

Source: https://github.com/lbcrion/sfwbar/blob/main/doc/sfwbar.rst

Terminates the SFWBar application.

```sfwbar
Exit()
```