pogmommy/eww
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Write defwindow documentation

Browse source
This commit is contained in:
elkowar 2021-08-16 16:31:46 +02:00
parent 8faedb0e89
commit e200f5ef2b
No known key found for this signature in database
GPG key ID: E321AD71B1D1F27F
1 changed files with 45 additions and 264 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

309
docs/src/configuration.md
View file

@ -1,277 +1,58 @@
# Configuration
# Writing your eww configuration
For specific built in widgets `<box>, <text>, <slider>, etc` see [Widget Documentation](widgets.md)
(For a list of all built in widgets (i.e. `box`, `text`, `slider`) see [Widget Documentation](widgets.md))
## Placing the configuration file
Eww is configured using it's own language called `yuck`. using yuck, you declare the structure and content of your widgets, the geometry, position and behavior of any windows, as well as any state and data that will be used in your widgets. Yuck is based around S-expressions, which you may know from lisp-like languages. If you're using vim, you can make use of [yuck.vim](https://github.com/elkowar/yuck.vim) for editor support. It is also recommended to use [parinfer](https://shaunlebron.github.io/parinfer/), which makes working with s-expressions delightfully easy!
Note: Example configuration files can be found in the `examples` directory of the repository and are showcased in [Examples](examples.md).
Additionally, any styles are defined in scss (which is mostly just slightly improved CSS syntax). While eww supports a significant portion of the CSS you know from the web, not everything is supported, as eww relies on GTKs own CSS engine. Notably, some animation features are unsupported, as well as most layout-related CSS properties such as flexbox, `float`, absolute position or `width`/`height`.
The configuration file and the scss file should lay in `$XDG_CONFIG_HOME/eww` (or, if unset, `$HOME/.config/eww`). 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
To get started, you'll need to create two files: `eww.yuck` and `eww.scss`. These files must be placed under `$XDG_CONFIG_HOME/eww` (this is most likely `~/.config/eww`).
Now that those files are created, you can start writing your first widget!
## Creating your first window
Firstly, you will need to create a top-level window. Here, you configure things such as the name, position, geometry and content of your window.
Let's look at an example window definition:
```lisp
(defwindow example
:monitor 0
:geometry (geometry :x 0 :y 0 :width "90%" :height "30px")
:anchor "top center"
:stacking "fg"
:reserve (struts :distance "40px" :side "top")
:windowtype "dock"
:wm-ignore false
"example content")
```
## Config structure
Here, we are defining a window named `example`, which we then set a set of properties for. Additionally, we set the content of the window to be the text `"example content"`.
Your config structure should look like this:
```xml
<eww>
<includes>
<!-- Put your <file>'s in here -->
</includes>
### `defwindow`-Properties
<definitions>
<!-- Put your <def>'s in here -->
</definitions>
| Property | Description |
| ---------: | ------------------------------------------------------------ |
| `monitor` | which monitor this window should be displayed on |
| `geometry` | Position and size of the window. Values may be provided in `px` or relative to the screen size. |
| `anchor` | What side of the screen the window should be anchored to. Either `center` or combinations of `top`, `center`, `bottom` and `left`, `center`, `right` |
<variables>
<!-- Put your <script-var> and <var>'s in here -->
</variables>
Depending on if you are using X11 or wayland, some additional properties exist:
<windows>
<!-- Put your window blocks here -->
</windows>
</eww>
```
See
[The `<includes>` block](#the-includes-block),
[The `<definitons>` block](#the-definitions-block),
[Variables](#variables) and the
[The `<windows>` block](#the-windows-block).
#### x11
## Variables
| Property | Description |
| -----------: | ------------------------------------------------------------ |
| `stacking` | Where the window should appear in the stack. Possible values: `fg`, `bg`. |
| `wm-ignore` | Whether the windowmanager should ignore this window. This is useful for dashboard-style widgets that don't need to interact with other windows at all. Note that this makes some of the other properties not have any effect. Either `true` or `false` |
| `reserve` | Specify how the window-manager should make space for your window. This is useful for bars, which should not overlap any other windows. |
| `windowtype` | Specify what type of window this is. This will be used by your window manager to determine how it should handle your window. Possible values: `normal`, `dock`, `toolbar`, `dialog`. Default: `dock` if `reserve` is specified, `normal` otherwise. |
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.
#### wayland
### 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."
```xml
<variables>
<var name="banana">I like bananas.</var>
</variables>
```
You can then reference it in your widgets by doing:
```xml
<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:
```xml
<variables>
<script-var name="date" interval="5s">
date +%H:%M
</script-var>
</variables>
```
and then reference it by doing:
```xml
<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:
```xml
<variables>
<script-var name="date">
date +%H:%M
</script-var>
</variables>
```
## The `<includes>` block
Here you can include other config files so that they are merged together at startup. Currently namespaced variables are not supported so be careful when reusing code.
```xml
<includes>
<file path="./other_config_file.xml"/>
<file path="./other_config_file2.xml"/>
</includes>
```
If you define a variable/widget/window, in a config file, when it's defined somewhere else, you can see a warning in the eww logs (`eww logs`)
## The `<definitions>` block
In here your whole widget will be made, and you can also create your own widgets. Check [Widget Documentation](widgets.md) for pre-defined widgets.
### Custom widgets
Let's get a small config and break it down.
```xml
<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:
```xml
<def name="clock">
<box>
The time is: {{my_time}} currently.
</box>
</def>
```
Is the custom widget. As we can see by the
```xml
<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:
```xml
<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
```xml
<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.
```xml
<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:
```xml
<def name="main">
<box>
<clock very_long_list_of_animals="{{date}}"/>
</box>
</def>
```
## The `<windows>` block
All different windows you might want to use are defined in the `<windows>` block.
The `<windows>` config should look something like this:
```xml
<windows>
<window name="main_window" stacking="fg" screen="1" windowtype="dock">
<geometry anchor="top left" x="300px" y="50%" width="25%" height="20px"/>
<reserve side="left" distance="50px"/>
<widget>
<main/>
</widget>
</window>
</windows>
```
For Wayland users the `<reserve/>` block is replaced by the exclusive field in `<window>`.
The previous `<window>` block would look like this.
```xml
<window name="main_window" stacking="fg" focusable="false" screen="1" exclusive="true">
<geometry anchor="top left" x="300px" y="50%" width="25%" height="20px"/>
<widget>
<main/>
</widget>
</window>
```
The window block contains multiple elements to configure the window.
- `<geometry>` is used to specify the position and size of the window.
- `<reserve>` is used to have eww reserve space at a given side of the screen the widget is on.
- `<widget>` will contain the widget that is shown in the window.
There are a couple things you can optionally configure on the window itself:
- `stacking`: stacking describes on what "layer" of the screen the window is shown.
Possible values on the X11 backend: `foreground "fg"`, `background "bg"`. Default: `"fg"`
Possible values on the Wayland backend: `foreground "fg"`, `bottom "bt"`, `background "bg"`, `overlay "ov"`. Default: `"fg"`
- `screen`: Specifies on which display to show the window in a multi-monitor setup.
This can be any number, representing the index of your monitor.
- `exclusive`: Specifies whether or not a surface can be occupied by another.
A surface can be a window, an Eww widget or any layershell surface.
The details on how it is actually implemented are left to the compositor.
This option is only valid on Wayland.
Possible values: `"true"`, `"false"`. Default: `"false"`
- `focusable`: (Wayland only) whether the window should be able to capture keyboard input.
Possible values: `"true"`, `"false"`. Default: `"false"`
- `wm-ignore`: (X11 only) wether the window should be managed by the window manager.
For a centered widget setup this is recommended to be set to true. For a bar, set the windowtype to `dock` instead.
Note that setting `wm-ignore` will make some other options not work, as those rely on the window manager.
Possible values: `"true"`, `"false"`. Default: `"true"` except if `<reserve>` is set.
- `windowtype`: (X11 only) Can be used in determining the decoration, stacking position and other behavior of the window.
Window managers tend to interpret these differently, so play around with which one works for your usecase!
Possible values:
- `"normal"`: indicates that this is a normal, top-level window
- `"dock"`: indicates a bar, dock, or panel window
- `"utility"`: indicates a pinned utility window
- `"toolbar"`: toolbars "torn off" from the main application
- `"dialog"`: indicates that this is a dialog window
- Default: `"dock"`
- `sticky`: (X11 only) If the window should show up on all workspaces. Note that this may not have any effect, depending on your window manager and the window type.
Possible values: `"true"`, `"false"`. Default: `"true"`
- `resizable`: (X11 only) If the window should be resizable. Note that this may not have any effect, depending on your window manager and the window type.
Possible values: `"true"`, `"false"`. Default: `"true"`
### Recommendations for different use-cases on X
Window positioning is... weird on X11. Different window-managers handle things differently, and some things are just not compatible.
Thus, the following setups are recommendations that will _probably_ work. If they don't try to play around with different settings for any of the X11 only properties.
- For a bar:
- Set `windowtype` to `dock`, and provide a `reserve` configuration to match your window geometry to make the WM reserve space.
- Set `wm-ignore` to `false`.
- For a centered, full-screen widget setup:
- Set `wm-ignore` to `true`.
| Property | Description |
| ----------: | ------------------------------------------------------------ |
| `stacking` | Where the window should appear in the stack. Possible values: `fg`, `bg`, `overlay`, `bottom`. |
| `exclusive` | Whether the compositor should reserve space for the window automatically. |
| `focusable` | Whether the window should be able to be focused. This is necessary for any widgets that use the keyboard to work. |