Provided by: sfwbar_1.0~beta13-1build2_amd64 
NAME
SFWBar - S* Floating Window taskBar
SYNOPSIS
sfwbar [options]
DESCRIPTION
SFWBar is a taskbar for wayland compositors. Originally written for Sway, it should work with any
compositor supporting layer-shell protocol. SFWBar assists in handling of floating windows on a wayland
desktop. It provides a taskbar, a pager, a task switcher, a system tray, a floating window placement
engine, a simple widget set for display data extracted from various system files. SFWBar can work with
any wayland compositor supporting layer shell protocol. Taskbar and switcher require either sway or
wlr-foreign-toplevel protocol support. Placer and pager require sway.
OPTIONS
SFWBar executable can be invoked with the following options:
-f | --config
Specify a filename of a configuration file
-c | --css
Specify a filename of a css file
-s | --socket
Specify a location of sway ipc socket
-m | --monitor
Specify a monitor to display the bar on ("-m list" to list available monitors)
-b | --bar_id
Specify a sway bar_id on which sfwbar will listen for status changes
CONFIGURATION
SFWBar reads configuration from a config file (sfwbar.config by default). The program checks users XDG
config directory (usually ~/.config/sfwbar/) for this file, followed by system xdg data directories.
Additionally, user can specify a location and a name of the config file using -f command line option.
Appearance of the program can be specified using CSS properties, these are sourced either from the css
section of the main configuration file or from a file with a .css extension with the same base name as
the config file located in the same directory as the config file. The name of the css file can be also
specified using -c option.
The config file consists of the following top level sections:
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:
interval
an timeout after the last task switch event after which the selected window is activated
labels [true|false]
display window titles in the task list
icons [true|false]
display window icons in the task list
cols a number of columns in the task list
css css code applicable to the switcher grid. You can specify more detailed css code in the main CSS
file. Using style name #switcher for the task switcher window and the main grid and names
#switcher_normal and #switcher_active for inactive and active window representations respectively.
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:
taskbar
a special widget displaying a list of all floating windows. (requires a compositor supporting
wlr-foreign-toplevel protocol or i3 ipc)
pager a special widget displaying a list of all workspaces. (requires a compositor supporting
wlr-foreign-toplevel protocol or i3 ipc)
tray a special widget displaying a list of tray icons received via status notifier item interface
grid a layout grid capable of containing other widgets. You can use these to further subdivide each
cell of the main grid and arrange items within it.
label a label displaying text sourced from an expression. Labels accept pango markup to further theme
text within them.
scale a progress bar with a progress value specified by an expression
chart a chart plotting the value of the expression over time
image display an icon or an image from a file. The name of an icon or a file is specified by an
expression and can change dynamically.
button add a clickable button with an icon/image.
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:
value an expression specifying the value to display. This can be a static value (i.e. "string" or 1) or
an expression (i.e. "Value is:" + $MyString or 2 * MyNumber.val). See expressions section for
more detail. For Label widgets value tells text to display. For Scale widgets it specifies a
fraction to display. For Chart widgets it specifies a fraction of the next datapoint. For Image
widgets and buttons it provides an icon or an image file name.
style a style name for the widget. Styles can be used in CSS to theme widgets. Multiple widgets can
have the same style. A style name can be used in css using gtk+ named widget convention, i.e.
label#mystyle. Style property can be set to an expression to change styles in response to changes
in system parameters.
tooltip
sets a tooltip for a widget. A tooltip can be a static value or an expression. In case of the
latter, the tooltip will be dynamically updated every time it pops up.
interval
widget update frequency in milliseconds..
trigger
trigger on which event updates. Triggers are emitted by Client sources a widget should not have
both an interval and a trigger specified. (if both are specified, interval is ignored and trigger
is used).
css additional css properties for the widget. These properties will only apply to the widget in
question.
action an action to execute upon interaction with a widget. Actions can be attached to any widget.
Multiple actions can be attached to various pointer events. The notation is action[<event>] =
<action>. Event values are 1,2,3 or LeftClick, MiddleClick or RightClick respectively. For mouse
scroll events, use values 4,5,6,7 or ScrollUp, ScrollDown, ScrollLeft and ScrollRight
respectively. If no index is specified the action is attached to a left mouse button click.
Additionallly, modifiers can be specified using the notation of [Modifier+]Index. I.e.
action[Ctrl+LeftClick]. The following modifiers supported: Shift, Ctrl, Mod1, Mod2, Mod3, Mod4,
Mod5i, Super, Hyper and Meta. Multiple modifiers can be added, i.e. action[Ctrl+Shift+ScrollUp].
action[0] will be executed on startup. You can use this action to set initial configuration for a
widget. See Actions section for more details on how actions are specified.
Taskbar widget may contain the following options
labels [true|false]
an indicator whether to display an application title within the taskbar
icons [true|false]
an indicator whether to display application icons within the taskbar
filter_output [true|false]
This property is deprecated, please use filter instead. specifies whether taskbar should only
list windows present on the same output as the taskbar
filter [output|workspace]
Specifies whether taskbar should only list windows present on the same output or workspace as the
taskbar itself.
title_width
set maximum width of an application title in characters
sort [true|false]
setting of whether taskbar items should be sorted. If the items are not sorted, user can sort them
manually via drag-and-drop mechanism. Items are sorted by default, set this to false to enable
drag-and-drop.
rows a number of rows in a taskbar.
cols a number of columns in a taskbar. If both rows and cols are specified, rows will be used. If
neither is specified, the default is rows=1
group [true|false]
if set to true, the taskbar items will be grouped by app_id, the main taskbar will contain one
item per app_id with an icon and a label set to app_id. On over, it will popup a "group taskbar"
containing items for individual windows. You can specify taskbar parameters for the group
taskbars using group prefix, i.e. group cols = 1. The properties supported for groups are cols,
rows, style, css, title_width, labels, icons.
Pager widget may contain the following options
preview [true|false]
specifies whether workspace previews are displayed on mouse hover over pager buttons
sort [true|false]
setting of whether pager items should be sorted. If the items are not sorted, user can sort them
manually via drag-and-drop mechanism. Items are sorted by default, set this to false to enable
drag-and-drop.
numeric [true|false]
if true, the workspaces will be sorted as numbers, otherwise they will be sorted as strings
(defaults to true).
pins a list of "pinned" workspaces. These will show up in the pager even if the workspace is empty.
rows a number of rows in a pager.
cols a number of columns in a pager. If both rows and cols are specified, rows will be used. If
neither is specified, the default is rows=1
tray widget may contain the following options
rows a number of rows in a pager.
cols a number of columns in a pager. If both rows and cols are specified, rows will be used. If
neither is specified, the default is rows=1
sort [true|false]
setting of whether tray items should be sorted. If the items are not sorted, user can sort them
manually via drag-and-drop mechanism. Items are sorted by default, set this to false to enable
drag-and-drop.
popup window may contain the following options
AutoClose [true|false]
specify whether the popup window should close if user clicks anywhere outside of the window.
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:
item an actionable menu item. This item has two parameters, the first one is a label, the second is an
action to execute when the item is activated. See Actions section for more details on supported
actions.
separator
a menu separator. This item has no parameters
submenu
attach a submenu. The first parameter parameter is a label to display in the parent menu, the
second optional parameter is a menu name, if a menu name is assigned, further items can be added
to a submenu as to any other menu.
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:
─────────────────────────────────────────────────────────────────
SIGRTMIN+X RT signal SIGRTMIN+X has been
received (X is a number)
─────────────────────────────────────────────────────────────────
sway Data has been received on SwayClient
scanner source
─────────────────────────────────────────────────────────────────
mpd Data has been received on MpdClient
scanner source
─────────────────────────────────────────────────────────────────
<output>-connected an output has been connected (i.e.
eDP-1-connected)
─────────────────────────────────────────────────────────────────
<output>-disconnected an output has been disconnected
┌───────────────────────┬───────────────────────────────────────┐
│ │ │
Actions │ │ │
--
MISCELLANEOUS
If the icon is missing for a specific program in the taskbar or switcher, it is likely due to an missing
icon or application not setting app_id correctly. You can check app_id's of running programs by running
sfwbar -d -g app_id. if app_id is present, you need to add an icon with the appropriate name to your
icon theme. If it's blank, you can try mapping it from the program's title (please note that the title
may change during runtime, so matching it can be tricky). Mapping is supported via top-level MapAppId
keyword. I.e.
MapAppId app_id, pattern
where app_id is the desired app_id and pattern is a regular expression to match the title against.
If you are using an XWayland app, they usually do not have an app_id set. If an icon is not showing, you
can add your icon to the following locations: 1. $HOME/.icons 2. One of the directories listed in
$XDG_DATA_DIRS/icons 3. /usr/share/pixmaps 4. Location of the main config file currently in use 5.
$XDG_CONFIG_HOME/sfwbar/
If an app_id is not set, and sway is being used, sfwbar will fallback to using the instance in the
window-properties.
You can find the app_id that is being used with sfwbar by using the sfwbar -d -g app_id command, which
will show a list of running applications if your compositor supports the wlr-foreign-toplevel protocol
(i.e. labwc, wayfire, sway): ` 14:49:25.41 app_id: 'jetbrains-clion', title 'sfwbar – pager.c' `
Alternatively your desktop environment might have a command to display a list: - Sway: swaymsg -t
get_tree - Hyperland: hyprctl -j clients
When using swaymsg -t get_tree, with CLion this will show the following:
"window_properties": {
"class": "jetbrains-clion",
"instance": "jetbrains-clion",
"title": "sfwbar – trayitem.c",
"transient_for": null,
"window_type": "normal"
}
So we can put an icon called jetbrains-clion.svg (or other formats, see the [Arch wiki](‐
https://wiki.archlinux.org/title/desktop_entries#Icons)) for information about file formats.
CSS STYLE
SFWBar uses gtk+ widgets and can accept all css properties supported by gtk+. SFWBar widgets correspond
to gtk+ widgets as following:
┌───────────────┬────────────────┬──────────────────────────────┐
│ SFWBar widget │ gtk+ widget │ css class │
├───────────────┼────────────────┼──────────────────────────────┤
│ label │ GtkLabel │ label │
├───────────────┼────────────────┼──────────────────────────────┤
│ image │ GtkImage │ image │
├───────────────┼────────────────┼──────────────────────────────┤
│ button │ GtkButton │ button │
├───────────────┼────────────────┼──────────────────────────────┤
│ scale │ GtkProgressBar │ progressbar, trough, │
│ │ │ progress │
└───────────────┴────────────────┴──────────────────────────────┘
Taskbar, Pager, Tray and Switcher use combinations of these widgets and can be themed using gtk+ nested
css convention, i.e. grid#taskbar button { ... } (this example assumes you assigned style = taskbar to
your taskbar widget).
In addition to standard gtk+ css properties SFWBar implements several additional properties. These are:
┌───────────────────────┬───────────────────────────────────────┐
│ property │ description │
├───────────────────────┼───────────────────────────────────────┤
│ -GtkWidget-align │ specify text alignment for a label, │
│ │ defined as a fraction. (0 = left │
│ │ aligned, 1 = right aligned, 0.5 = │
│ │ centered) │
├───────────────────────┼───────────────────────────────────────┤
│ -GtkWidget-ellipsize │ specify whether a text in a label │
│ │ should be ellipsized if it's too long │
│ │ to fit in allocated space │
├───────────────────────┼───────────────────────────────────────┤
│ -GtkWidget-direction │ specify a direction for a widget. │
│ │ For scale, it's a direction towards │
│ │ which scale grows. For a grid, it's │
│ │ a direction in which a new widget is │
│ │ position relative to the last placed │
│ │ widget. For a window it's an edge │
│ │ along which the bar is positioned. │
│ │ Possible values │
│ │ [top|bottom|left|right] │
├───────────────────────┼───────────────────────────────────────┤
│ -GtkWidget-max-width │ Limit maximum width of a widget (in │
│ │ pixels) │
├───────────────────────┼───────────────────────────────────────┤
│ -GtkWidget-max-height │ Limit maximum height of a widget (in │
│ │ pixels) │
├───────────────────────┼───────────────────────────────────────┤
│ -GtkWidget-hexpand │ specify if a widget should expand │
│ │ horizontally to occupy available │
│ │ space. [true|false] │
├───────────────────────┼───────────────────────────────────────┤
│ -GtkWidget-vexpand │ as above, for vertical expansion. │
├───────────────────────┼───────────────────────────────────────┤
│ -GtkWidget-halign │ Horizontally align widget within any │
│ │ free space allocated to it, values │
│ │ supported are: fill, start, end, │
│ │ center and baseline. The last │
│ │ vertically aligns widgets to align │
│ │ text within. │
├───────────────────────┼───────────────────────────────────────┤
│ -GtkWidget-valign │ Vertically align widget. │
├───────────────────────┼───────────────────────────────────────┤
│ -GtkWidget-visible │ Control visibility of a widget. If │
│ │ set to false, widget will be hidden. │
├───────────────────────┼───────────────────────────────────────┤
│ -ScaleImage-color │ Specify a color to repaint an image │
│ │ with. The image will be painted with │
│ │ this color using image's alpha │
│ │ channel as a mask. The color's own │
│ │ alpha value can be used to tint an │
│ │ image. │
├───────────────────────┼───────────────────────────────────────┤
│ -ScaleImage-symbolic │ Render an image as a symbolic icon. │
│ │ If set to true, the image will be │
│ │ re-colored to the gtk theme │
│ │ foreground color, preserving the │
│ │ image alpha channel. This property is │
│ │ ignored if -ScaleImage-color is │
│ │ specified. │
└───────────────────────┴───────────────────────────────────────┘
Taskbar and pager buttons are assigned the following styles
───────────────────────────────────────────────────────────
style name description
───────────────────────────────────────────────────────────
sfwbar toplevel bar window
───────────────────────────────────────────────────────────
layout top level layout grid
───────────────────────────────────────────────────────────
taskbar_normal taskbar button for a window
───────────────────────────────────────────────────────────
taskbar_active taskbar button for currently focused
window
───────────────────────────────────────────────────────────
pager_normal pager button for a workspace
───────────────────────────────────────────────────────────
pager_visible pager button for a visible workspace
───────────────────────────────────────────────────────────
pager_focused pager button for a currently focused
workspace
───────────────────────────────────────────────────────────
switcher switcher window and top level grid
───────────────────────────────────────────────────────────
switcher_active switcher active window representation
───────────────────────────────────────────────────────────
switcher_normal switcher inactive window
representation
───────────────────────────────────────────────────────────
tray tray menus and menu items
───────────────────────────────────────────────────────────
tray_active active tray icon
───────────────────────────────────────────────────────────
tray_attention tray icon requiring user attention
───────────────────────────────────────────────────────────
tray_passive passive tray icon
───────────────────────────────────────────────────────────
menu_item menu items (each contains an image
and a label)
┌─────────────────┬───────────────────────────────────────┐
│ │ │
--
COPYRIGHT │ │ │
GPLv3+ │ │ │
│ │ │
│ │ │
│ │ │ SFWBAR(1)
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │
│ │ │