Toplevel keywords

bar

The layout of the bar is specified in one of the parent structures, these are bar, popup or widget_grid. Each one is a nested structure consisting of widgets and their properties. i.e.:

bar "sfwbar" {


  button {


    value = "icon-name";


    style = "launcher";


    action[LeftClick] = Exec("firefox");


  }


  grid {


    label "mylabel" {


      value = "Some text";


    }


  }
}

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:

bar "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 using the following syntax:

bar {


  widget "MyWidget.widget"
}

The above will process the contents of configuration file MyWidget.widget and place the widget_grid object from the included file into the bar.

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.

Properties define the appearance and behaviour of widgets. These are generally defined as property = value with a few exceptions. All 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

bar objects may have the following options

PopUps and Windows

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

popup "MyPopup" {


  label { value = "test"; }
}
bar {


  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.

popup window may contain the following options

Toplevel windows can be defined using a window element and are controlled using WindowOpen and WindowClose actions. I.e.:

window "mywindow" {


  button {


    value = "close-icon";


    action = WindowClose("mywindow");


  }
}
bar {


  button {


   value = "open-icon";


   action = WindowOpen("mywindow");


  }
}

unlike popups, toplevel windows can't be placed in a specific location, compositors can place them anywhere on the desktop. They can receive focus and are useful for implementing dialogs.

Menus

User defined menus can be creating using a menu structure. The format is similar to the bar, but widgets and properties differ. For example:

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");


      }


    }


  }
}
bar {


  ...


  button {


    value = "menu-icon";


    action = Menu("menu_name");


  }
}

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 following menu items are supported:

Menu structure supports one property:

Menu items contain the following properties:

The config file consists of the following top level sections:

Placer

Placer structure controls intelligent placement of new floating windows. This functionality currently relies on side channel IPCs and is not supported for all compositors. If placer is enabled, SFWBar will first attempt to place a new floating 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 structure supports the following properties:

I.e.:

placer {


  xorigin = 5


  yorigin = 5


  xstep = 5


  ystep = 5


  children = false
}

Task Switcher

Task switcher cycles the focus across windows (i.e. Alt-Tab function). Switcher can be invoked through a SwitcherEvent action. The forward switch action is bound to SIGUSR1 signal by default, in sway, the action is additionally bound to a change in a bar hidden_state property.

In sway, you can bind alt-tab using bindsym Alt-Tab bar hidden_state toggle In other compositors, you can bind a key to killall -SIGUSR1 sfwbar (you may need to replace sfwbar with the name of the sfwbar executable if it differs from the default on your system).

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

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 and user actions.

Built-in triggers are:

Actions

SFWBar will execute actions in response to certain events. These can be user input events such as clicking or scroll a mouse over a widget or system events, such as realtime signals, data arriving via a pipe etc.

To bind an action to user input events, use widgets action property. Or for system events, you can bind an action to a trigger, using TriggerAction keyword. I.e.:

TriggerAction "mytrigger", Exec("MyCommand")

An action can be a single instruction, i.e. Exec("firefox"); or a sequence of instructions enclosed in curly brackets.

An instruction can be a function call using syntax:

[<variable> = ] my_func ( [<expression>, ... ] );

You can use variables within action { } blocks. Variables are declared using a Var keyword:

Var <identifier> [ = <expression> ];

Conditional operations can be implemented using If keyword:

If <expression>


  <instruction>
[else


  <instruction>]

Loops can be implemented using While keyword:

While <expression>


  <instruction>

Functions can be terminated early and return a value using a Return keyword:

Return [<expression>];

For more complex actions, you can define your own functions using a toplevel function keyword. I.e.:

Function my_func ( x ) {


  Var y = "This is a test " + Str(x);


  Print(y);


  Return x+1;
}
TriggerAction "sometrigger", my_func(1);

By default, all actions, functions and expressions share a single name space, so any variable is visible to all code instances. Private scopes can be defined using a Private keyword. I.e.

Private {


  Var X = 1;


  export label "mylabel" {


    value = Str(x);


  }
}

In the above example variable X can only be accessible within the scope. You can access it when addressing label "mylabel" outside of the private block as the label will inherit the scope it's defined in.

Function "SfwBarInit" is executed on startup. Use it set initial parameters for the bar, modules etc.

Expressions

As part of the configuration SFWBar can evaluate expressions. These can be part of an action or user defined function, but some properties also accept expressions. In case of the later, the expression is evaluated periodically or in response to to a trigger (see interval and trigger widget properties).

A value in an expression can have one of four types: numeric, string, array or n/a.

Expressions support the following operators: ============ ========================================================================================= Operation Description ============ ========================================================================================= + addition of numeric values or concatenation of strings, append value operator for arrays. - subtraction of numeric values. * multiplication of numeric values. / division of numeric values. % remainder of an integer division for numeric values. > greater than comparison of numeric values. >= greater than or equal comparison of numeric values. < less than comparison of numeric values. <= less than or equal comparison of numeric values. = equality comparison of two values, returns false if types differ. If conditional: If(<condition>, <expression>, <expression>) Cached get last value from a scanner variable without updating it, i.e. Cached(identifier). Ident Check if an identifier exists either as a variable or a function. ============ =========================================================================================

Expressions can include function calls, i.e.:

Var my_var = 1 + my_func(2);

Arrays can be declared and array elements can be accessed using [ ] operator:

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

Array indices start at 0.

Native functions

Actions and functions can call user definer or built-in (native) functions, the following is the list of the functions provided by SFWBar. Modules can expose their own functions which are documented separately.

SFWBar supports the following native functions:

Scanner

Bar often require polling data from system files (i.e. /sys or /proc). To this end, SFWBar provides a scanner infrastructure. Scanners allow reading system files and extract multiple data points from them in a single pass. This ensures that multiple data items are consistent and resources are not wasted reading the same file multiple times.:

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")
}
ExecClient("stdbuf -oL foo.sh BAR BAZ", "foo") {


  Foo_foo = Json(".foo")


  Foo_bar = Json(".bar")
}

Scanner declarations consist of a scanner source and one or more parsers used to populate the scanner variables.

The sources are:

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

Scanner 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 values, Sum and Product aggregators are treated as Last. Each scanner variable holds the following information:

If a suffix is omitted for a scanner variable, the .val suffix is assumed.

Intermediate scanner 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.