eww/docs/content/main/configuration.md

+++ title = "Configuration" slug = "The basics of how to configure eww" weight = 1 +++

Configuration

For specific built in widgets <box>, <text>, <slider>, etc see Widget Documetation

Placing the configuration file

The configuration file and the scss file should lay in your $HOME/.config/eww folder. The xml file should be named eww.xml and the scss should be named eww.scss So the directory structure should look like this:

$HOME
└──.config
   └──eww
      ├──eww.xml
      └──eww.scss

Variables

If you create a <var> or a <script-var>, you can reference them in your <box> by doing {{var}}. Where var is your variable name.

The <var> tag

Allows you to repeat the same text multiple times through without retyping it multiple times.

Example: This will define a variable named banana, with the default value "I like bananas."

<variables>
    <var name="banana">I like bananas.</var>
</variables>

You can then reference it in your widgets by doing:

<box>
    {{banana}}
</box>

To change the value of the variable, and thus change the UI, you can run eww update banana "I like apples"

The <script-var> tag

Allows you to create a script that eww runs. Useful for creating volume sliders or anything similar.

Example:

<variables>
    <script-var name="date" interval="5s">
    date +%H:%M
    </script-var>
</variables>

and then reference it by doing:

<box>
    {{date}}
</box>

The interval="5s" part says how long time it should take before Eww runs the command again. Here are the available times you can set:

Shortened	Full name
ms	Miliseconds
s	Seconds
m	Minutes
h	Hours

Tail

If you don't want a set interval and instead want it to tail (run the script when it detects a change is present) you can simply remove the interval="5s" so it becomes:

<variables>
    <script-var name="date">
    date +%H:%M
    </script-var>
</variables>

The <definitions> block

In here you whole widget will be made, and you can also create your own widgets. Check Widget Documentation for pre-defined widgets.

Custom widgets

Let's get a small config and break it down.

<definitions>
    <def name="clock">
        <box>
            The time is: {{my_time}} currently.
        </box>
    </def>
    <def name="main">
        <box>
            <clock my_time="{{date}}"/>
        </box>
    </def>
</definitions>

<variables>
    <script-var name="date">
        date
    </script-var>
</variables>

That's a long config just for a custom widget. But let's break it down and try to understand it.

This part:

<def name="clock">
    <box>
	The time is: {{my_time}} currently.
    </box>
</def>

Is the custom widget. As we can see by the

<def name="clock">

the widget is called clock.Or referenced <clock> The {{my_time}} is the value we assign to be well, our time. You can actually set to be anything, it doesn't have to be a time. You can compare it to value=""

So if we look at:

<def name="main">
    <box>
	<clock my_time="{{date}}"/>
    </box>
</def>

we can see that we assign {{my_time}} to be {{date}} and if we look at

<script-var name="date">
    date
</script-var>

we can see that {{date}} is simply running the date command.

It doesn't have to be {{my_time}} either, it can be anything.

<def name="clock">
    <box>
	The time is: {{very_long_list_of_animals}} currently.
    </box>
</def>

is valid.

To use that it would look like this:

<def name="main">
    <box>
	<clock very_long_list_of_animals="{{date}}"/>
    </box>
</def>

The <windows> block

This is the part the Eww reads and loads. The <windows> config should look something like this:

<windows>
    <window name="main_window" stacking="fg">
      <size x="300" y="300" />
      <pos x="0" y="500" />
      <widget>
	<main/>
      </widget>
    </window>
</windows>

<window name="main_window"> is the part that eww runs when you start it. In this example you would run eww by doing:

./eww open main_window

but if renamed the <window> to be <window name="apple"> we would run eww by doing:

./eww open apple

The stacking="fg" says where the widget will be stacked. Possible values here are foreground, fg, background and bg. foreground or fg always stays above windows. background or bg always stays behind windows. So it will stay on your desktop.

If you were to remove the stacking="fg" it would default it to fg.

You can also have multiple windows in one document by doing:

<windows>
    <window name="main_window">
        <size x="300" y="300" />
        <pos x="0" y="500" />
        <widget>
            <main/>
        </widget>
    </window>
    <window name="main_window2">
        <size x="400" y="600"/>
        <pos x="0" y="0"/>
        <widget>
            <main2/>
        </widget>
    </window>
</windows>

---

• <size> sets x-y size of the widget.
• <pos> sets x-y position of the widget.
• <widget> is the part which you say which <def> eww should run. So if we take the example config from before:

<definitions>
    <def name="clock">
        <box>
            The time is: {{my_time}} currently.
        </box>
    </def>
    <def name="main">
        <box>
            <clock my_time="{{date}}"/>
        </box>
    </def>
</definitions>

and then look at

<widget>
    <main/>
</widget>

we will see that eww will run <def name="main"> and not <def name="clock">.