diff --git a/docs/config-docs.md b/docs/config-docs.md new file mode 100644 index 0000000..1868f93 --- /dev/null +++ b/docs/config-docs.md @@ -0,0 +1,363 @@ + +# Eww - Widgets for everyone! + + +Eww (ElKowar's Wacky Widgets, pronounced with sufficient amounts of disgust) Is a widgeting system made in [rust](https://www.rust-lang.org/), which let's you create your own widgets simmilarly to how you can in AwesomeWM. The key difference: It is independent of your window manager! + +Configured in XML and themed using CSS, it is easy to customize and provides all the flexibility you need! + + +## Contents + +- [How to install Eww](#how-to-install-eww) + - [Prerequisites](#prerequisites) + - [Building](#building) + - [Starting Eww](#starting-eww) +- [Configuration](#configuration) + - [Placing the configuration file](#placing-the-configuration-file) + - [Variables](#variables) + - [The var tag](#the-var-tag) + - [The script-var tag](#the-script-var-tag) + - [Tail](#tail) + - [The Definitions block](#the-definitions-block) + - [Custom Widgets](#custom-widgets) + - [The Windows block](#the-windows-block) + - [Widgets made in Eww](#widgets-made-in-eww) +- [GTK](#gtk) + - [GTK-Temeing / Eww Themeing](#gtk-themeing) + - [GTK-Debugger](#gtk-debugger) +- [Troubleshooting](#troubleshooting) + - [My scss isn't being loaded](#my-scss-isnt-being-loaded) + - [Eww can't find my configuration file](#eww-cant-find-my-configuration-file) + - [Something isn't styled correctly!](#something-isnt-styled-correctly) + + +## How to install Eww + +### Prerequisites + +* rustc +* cargo (nightly toolchain) + +Rather than with your system package manager, I recommend installing it using [rustup](https://rustup.rs/), as this makes it easy to use the nightly toolchain, which is necessary to build eww. + +### Building + +Once you have the Prerequisites ready, you're ready to install and build eww. + +First clone the repo: +```bash +git clone https://github.com/elkowar/eww +``` +then enter it. +```bash +cd eww +``` +and then to build: +```bash +cargo build --release +``` + +### Running eww +Once you've built it you can now run it by entering: +```bash +cd target/release +``` +and then make the Eww binary executable +```bash +chmod +x ./eww +``` +and then to run it do +``` +./eww open +``` +`` is the name of the window, see [The windows block](#the-windows-block). + +## Configuration + +For specific built in widgets `, , , 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 `` or a ``, you can reference them in your `` by doing `{{var}}`. Where `var` is your variable name. + +#### The `` 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 + + I like bananas. + +``` +You can then reference it in your widgets by doing: + +```xml + + {{banana}} + +``` + +To change the value of the variable, and thus change the UI, you can run `eww update banana "I like apples"` + +#### The `` tag + +Allows you to create a script that eww runs. +Useful for creating volume sliders or anything similar. + +Example: +```xml + + + date +%H:%M + + +``` + +and then reference it by doing: +```xml + + {{date}} + +``` + +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 + + + date +%H:%M + + +``` + +### The `` 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. + +```xml + + + + The time is: {{my_time}} currently. + + + + + + + + + + + + date + + +``` +That's a long config just for a custom widget. But let's break it down and try to understand it. + +This part: +```xml + + + The time is: {{my_time}} currently. + + +``` +Is the custom widget. As we can see by the +```xml + +``` +the widget is called `clock.`Or referenced `` +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 + + + + + +``` +we can see that we assign `{{my_time}}` to be `{{date}}` and if we look at +```xml + + date + +``` +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 + + + The time is: {{very_long_list_of_animals}} currently. + + +``` +is valid. + +To use that it would look like this: +```xml + + + + + +``` +### The `` block + +This is the part the Eww reads and loads. The `` config should look something like this: + +```xml + + + + + +
+ + + +``` +`` is the part that eww runs when you start it. In this example you would run eww by doing: +```bash +./eww open main_window +``` +but if renamed the `` to be `` we would run eww by doing: +```bash +./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: + +```xml + + + + + +
+ + + + + + + + + + +``` +--- + +- `` sets x-y size of the widget. +- `` sets x-y position of the widget. +- `` is the part which you say which `` eww should run. So if we take the example config from before: +```xml + + + + The time is: {{my_time}} currently. + + + + + + + + +``` +and then look at +```xml + +
+ +``` +we will see that eww will run `` and not ``. + +### Widgets made in Eww + +![two](two.png) ![one](one.png) + + +## GTK + +### Gtk-Themeing + +Eww is styled in GTK CSS. To make theming even easier, it makes use of `scss` and then compiles that into CSS for you. If you don't know any way to style something check out the [GTK CSS Overview wiki](https://developer.gnome.org/gtk3/stable/chap-css-overview.html), the [GTK CSS Properties Overview wiki ](https://developer.gnome.org/gtk3/stable/chap-css-properties.html). Or check the [GTK-Debugger](#gtk-debugger) + +If you have **NO** clue about how to do CSS, check out some online guides or tutorials. + +SCSS is *very* close to CSS so if you know CSS you'll have no problem learning SCSS. + +### GTK-Debugger + +The debugger can be used for **a lot** of things. Especially if something doesn't work or isn't styled right. to enable it do +```bash +GTK_DEBUG=interactive ./eww open main_window +``` +or in fish +```bash +env GTK_DEBUG=interactive ./eww open main_window +``` + +If a style or something similar doesn't work you can click on the icon in the top left icon to select the thing that isn't being styled or isn't being styled correctly. + +Then you can click on the drop down menu in the top right corner and select CSS Nodes, here you will see everything about styling it, CSS Properties and how it's structured. + +## Troubleshooting + +Here you will find help if something doesn't work, if the issue isn't listed here please [open an issue on the github repo.](https://github.com/elkowar/eww/issues) + +### My scss isn't being loaded! + +1. You have not created a scss file +2. The scss file isn't called correctly. (it should be called `eww.scss` in the `$HOME/.config/eww` folder) +3. The scss file isn't placed in the correct location (check above) +4. You have used two (or more) semi-colons (;;) insted of one (;) at the end of a line. + +If none of these fixed your problem [open an issue on the github repo.](https://github.com/elkowar/eww/issues) Or check the [GTK-Debugger](#gtk-debugger). + +### Eww can't find my configuration file! + +1. It's incorrectly named or it's in the wrong place (it should be called `eww.xml` in the `$HOME/.config/eww` folder) +2. You haven't started eww correctly or you started it wrong. (See [Starting Eww](starting-eww)) + +### Something isn't styled correctly! + +1. You have misstyped the CSS class. +2. Check the [GTK-Debugger](#gtk-debugger) + +Remeber if your issue isn't listed here, [open an issue on the github repo](https://github.com/elkowar/eww/issues). diff --git a/docs/one.png b/docs/one.png new file mode 100644 index 0000000..d808192 Binary files /dev/null and b/docs/one.png differ diff --git a/docs/two.png b/docs/two.png new file mode 100644 index 0000000..6b695cb Binary files /dev/null and b/docs/two.png differ diff --git a/two.png b/two.png new file mode 100644 index 0000000..6b695cb Binary files /dev/null and b/two.png differ