Variables

Now that you feel sufficiently greeted by your bar, you may realize that showing data like the time and date might be even more useful than having a button that greets you.

To implement dynamic content in your widgets, you make use of variables.

Nbcl variables

In Nbcl, all variables are dynamically typed bindings to values. You can define variables using let or const keyword, pass them as function parameters.

Basic variables (let and const)

let foo = "value"
const bar = "value"

This is the simplest type of variable. These variables exist only during evaluation and changes to it does not effect the rendered widgets, if you need a dynamic variable that if updated, updates the widget, you can use built in Poll and Listen components to register dynamic values which we will talk about in the following section.

Dynamic global variables

Just having nbcl variables that wont update is pretty limiting. So, ewwii has two built in components to register dynamic variables (which is also known as a signal) that can change according to the command. These variables are global, which means that it is available in all modules.

Polling variables (Poll)

Poll "var_name" {
  initial = "initial value"
  interval = "2s"
  cmd = "date +%H:%M:%S"
}

A polling variable is a variable which runs a provided shell-script repeatedly, in a given interval.

This may be the most commonly used type of variable. They are useful to access any quickly retrieved value repeatedly, and thus are the perfect choice for showing your time, date, as well as other bits of information such as pending package updates, weather, and battery level.

To externally update a polling variable, ewwii update can be used like with basic variables to assign a value. Learn more about ewwii update.

tip

When a graph widget is driven by a polling variable, set skip_unchanged to false to ensure continuous updates.

Listening variables (Listen)

Listen "foo" {
  initial = "whatever"
  cmd = "tail -F /tmp/some_file"
}

Listening variables might be the most confusing of the bunch. A listening variable runs a script once, and reads its output continously. Whenever the script outputs a new line, the value will be updated to that new line. In the example given above, the value of foo will start out as "whatever", and will change whenever a new line is appended to /tmp/some_file.

These are particularly useful when you want to apply changes instantaneously when an operation happens if you have a script that can monitor some value on its own. Volume, brightness, workspaces that get added/removed at runtime, monitoring currently focused desktop/tag, etc. are the most common usecases of this type of variable. These are particularly efficient and should be preffered if possible.

For example, the command xprop -spy -root _NET_CURRENT_DESKTOP writes the currently focused desktop whenever it changes. Another example usecase is monitoring the currently playing song with playerctl: playerctl --follow metadata --format {{title}}.

Using these variables

Since these are global variables, they can be used everywhere in the configuration using the global function. Their values can also be mutated temporarily for a property if you pair it with the mutate function.

Poll "time" {
  initial = "initial value"
  interval = "2s"
  cmd = "date +%H:%M:%S"
}

Window "1" {
  CustomWidget {}
}

component CustomWidget (any: props) {
  Box {
    Label {
      # Just use the value directly
      text = global("time")
    }
    Label {
      # {self} is how you access the value of a global variable.
      text = global("time").mutate("Time: {self}")
    }
  }
}