Placer

Placer section enables intelligent placement of new floating windows. If enabled the program will first attempt to place the window in a location, where it won't overlap with other windows. If such location doesn't exist, the window will be placed in a cascading pattern from top-left to bottom-right. The Placer declaration accepts parameters "xstep" and "ystep" that specify the steps in the window cascade. These are specified in percentage of the desktop dimensions. The cascade placement will start at a location specified by "xorigin" "yorigin" parameters. I.e.:

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

"children" parameter specifies if new windows opened by a program with other windows already opened should be placed. These are usually dialog windows and SFWBar won't place them by default. If the placer section is not present in the file, SFWBar will let the compositor determine the locations for new windows.

Task Switcher

Task switcher implements a keyboard shortcut to cycle focus across windows (i.e. Alt-Tab). The action is triggered upon receiving a change in a bar hidden_state property or signal SIGUSR1. This can be configured in Sway, via one of the following bindings:

bindsym Alt-Tab bar hidden_state toggle
or
bindsym Alt-Tab exec killall -SIGUSR1 sfwbar

(for non-sway compositors, use SIGUSR1 trigger)

NixOS + Hyprland (probably other non-sway compositors) use:

bind = ALT, Tab, exec, killall -SIGUSR1 .sfwbar-wrapped

Task switcher is configured in the "switcher" section of the configuration file. The following parameters are accepted:

Layout

Defines the layout of the taskbar. The layout holds a set of widgets. Widgets can be nested in case of a grid widget, which acts as a container.

The following widget types are supported:

Each widget is placed within the parent grid. By default, widgets are placed next to the previous widget along the "direction" of the grid (left to right by default). You can specify widget's positions within a grid by using a property "loc(x,y[,w,h])" with the first two parameters specifying the location of the widget within the parent grid and the last two parameters specifying the widget dimensions in grid cells:

layout "id" {
  label {
  style = "mystyle"
  value = SwapUsed / SwapTotal + "%"
  loc(2,1,1,1)
  }
}

The optional "id" string of the layout, specifies the bar to populate and can control positioning of the grid within a bar using syntax of "name:position", valid positions are start, center and end. This allows placement of some widgets in the center of the bar. In case of a single bar, the name of a bar can be omitted, i.e. ":center". External widgets can be included in layout using the following syntax:

layout {
  include("MyWidget.widget")
}

The above will include all scanner variables data and widget sub-layout from file MyWidget.widget

Grid widgets can contain other widgets, these are declared within the grid definition i.e.

grid {
  css = "* { border: none }"
  label "id" {
    ...
  }
}

Widgets can optionally have unique id's assigned to them in order to allow manipulating them in the future. Widgets can have the following properties:

Taskbar widget may contain the following options

Pager widget may contain the following options

tray widget may contain the following options

popup window may contain the following options

PopUp

Popup windows can be defined the same way as layouts. The only difference is that popup's are not part of a bar and will not be displayed by default. Instead they are displayed when a PopUp action is invoked on a widget. i.e.:

PopUp "MyPopup" {
  label { value = "test" }
}
Layout {
  label {
    value = "click me"
    action = PopUp "MyPopup"
  }
}

The PopUp action toggles visibility of the popup window. I.e. the first time it's invoked, the window will pop up and on the second invocation it will pop down. As a result it should be safe to bind the PopUp to multiple widgets.

Menus

User defined menus can be attached to any widget (see action widget property). Menus are defined using a Menu section in the config file. The example syntax is as following:

menuclear("menu_name")
menu ("menu_name") {
  item("item1", Exec "command")
  separator
  submenu("sub","mysubmenu") {
    item("item2", SwayCmd "focus next")
  }
}

Command MenuClear deletes any existing items from a menu. Each menu has a name used to link the menu to the widget action and a list of menu items. If a menu with the same name is defined more than once, the items from subsequence declarations will be appended to the original menu. If you want to re-define the menu, use MenuClear action to clear the original menu.

The following menu items are supported:

Triggers

Triggers are emitted in response to various events, such as compositor state changes, real time signals or notifications from modules. Some triggers can be defined as part of the configuration (i.e. SocketClient or ExecClient scanner sources), others are built in, or defined in modules.

Built-in triggers are:

Actions

Actions can be attached to click and scroll events for any widget or to items within a menu. Actions can be conditional on a state of a window or a widget they refer to and some actions may require a parameter. Conditions are specified in square brackets prior to the action i.e. [Minimized] and can be inverted using ! or joined using | i.e. [!Minimized | Focused]. All conditions on the list must be satisfied. Supported conditions are: Minimized, Maximized, Focused, FullScreen and UserState

Actions can be activated upon receipt of a trigger from one of the client type sources, using TriggerAction top-level keyword. I.e.

TriggerAction "mytrigger", Exec "MyCommand"

Parameters are specified as strings immediately following the relevant action. I.e. Menu "WindowOps". Some actions apply to a window, if the action is attached to taskbar button, the action will be applied to a window referenced by the button, otherwise, it will apply to the currently focused window. The following action types are supported:

Functions

Functions are sequences of actions. They are used when multiple actions need to be execute on a single triggeer. A good example of this functionality is dynamically constructed menus generated by an external script:

function("fancy_menu") {
  MenuClear "dynamic_menu"
  PipeRead "$HOME/bin/buildmenu.sh"
  Menu "dynamic_menu"
}

The above example clears a menu, executes a script that builds a menu again and opens the resulting menu.

Function "SfwBarInit" executed on startup. You can use this functions to set initial parameters for the bar, such as default monitor and layer.

Scanner

SFWBar widgets display data obtained from various sources. These can be files or output of commands.

Each source section contains one or more variables that SFWBar will poll periodically and populate with the data parsed from the source. The sources and variables linked to them as configured in the section scanner

scanner {
  file("/proc/swaps",NoGlob) {
    SwapTotal = RegEx("[\t ]([0-9]+)")
    SwapUsed = RegEx("[\t ][0-9]+[\t ]([0-9]+)")
  }
  exec("getweather.sh") {
    $WeatherTemp = Json(".forecast.today.degrees")
  }
}

Each declaration within the scanner section specifies a source. This can be one of the following:

The file source also accepts further optional arguments specifying how scanner should handle the source, these can be:

Variables are extracted from sources using parsers, currently the following parsers are supported:

Optional aggregators specify how multiple occurrences of numeric data are treated. The following aggregators are supported:

For string variables, Sum and Product aggregators are treated as Last.

Global Options

EXPRESSIONS

Values in widgets can contain basic arithmetic and string manipulation expressions. These allow transformation of data obtained by the scanner before it is displayed by the widgets.

The numeric operations are:

The string operations are:

In addition the following query functions are supported

Each numeric variable contains four values

By default, the value of the variable is the value of .val. String variables are prefixed with $, i.e. $StringVar The following string operation are supported. For example:

$MyString + Str((MyValue - MyValue.pval)/MyValue.time),2)

User defined expression macros are supported via top-level define keyword. I.e.

define MyExpr = VarA + VarB * VarC + Val($Complex)
...
value = Str(MyExpr,2)

The above will expand the expression into:

value = Str(VarA + VarB * VarC + Val($Complex),2)

Macro's don't have types, as they perform substitution before the expression is evaluated.

Intermediate variables can be declared using a toplevel set keyword I.e.

set MyExpr = VarA + VarB * VarC + Val($Complex
...
value = Str(MyExpr,2)

In the above example, value of the MyExpr variable will be calculated and the result will be used in computing the value expression. Intermediate variables have type and have all of the fields of a scan variable (i.e. val, pval, time etc). They can be used the same way as scan variables.