|
|
|
@ -9,7 +9,14 @@ |
|
|
|
|
## Table of Contents |
|
|
|
|
|
|
|
|
|
* [Swayr](#swayr) |
|
|
|
|
* [Commands](#swayr-commands) |
|
|
|
|
* [Screenshots](#swayr-screenshots) |
|
|
|
|
* [Installation](#swayr-installation) |
|
|
|
|
* [Usage](#swayr-usage) |
|
|
|
|
* [Configuration](#swayr-configuration) |
|
|
|
|
* [Version changes](#swayr-version-changes) |
|
|
|
|
* [Swayrbar](#swayrbar) |
|
|
|
|
* [Configuration](#swayrbar-configuration) |
|
|
|
|
* [Questions and patches](#questions-and-patches) |
|
|
|
|
* [Bugs](#bugs) |
|
|
|
|
* [Build status](#build-status) |
|
|
|
@ -22,7 +29,7 @@ window/workspace creations, deletions, and focus changes using sway's JSON IPC |
|
|
|
|
interface. The client `swayr` offers subcommands, see `swayr --help`, and |
|
|
|
|
sends them to the demon which executes them. |
|
|
|
|
|
|
|
|
|
### Swayr commands |
|
|
|
|
### <a id="swayr-commands">Swayr commands</a> |
|
|
|
|
|
|
|
|
|
The `swayr` binary provides many subcommands of different categories. |
|
|
|
|
|
|
|
|
@ -163,7 +170,7 @@ These commands change the layout of the current workspace. |
|
|
|
|
one. (This is useful for accessing swayr commands which are not bound to a |
|
|
|
|
key.) |
|
|
|
|
|
|
|
|
|
### Screenshots |
|
|
|
|
### <a id="swayr-screenshots">Screenshots</a> |
|
|
|
|
|
|
|
|
|
![A screenshot of swayr switch-window](misc/switch-window.png "swayr |
|
|
|
|
switch-window") |
|
|
|
@ -172,7 +179,7 @@ switch-window") |
|
|
|
|
switch-workspace-or-window](misc/switch-workspace-or-window.png "swayr |
|
|
|
|
switch-workspace-or-window") |
|
|
|
|
|
|
|
|
|
### Installation |
|
|
|
|
### <a id="swayr-installation">Installation</a> |
|
|
|
|
|
|
|
|
|
Some distros have packaged swayr so that you can install it using your distro's |
|
|
|
|
package manager. Alternatively, it's easy to build and install it yourself |
|
|
|
@ -210,7 +217,7 @@ cargo install-update --all |
|
|
|
|
cargo install-update -- swayr |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
### Usage |
|
|
|
|
### <a id="swayr-usage">Usage</a> |
|
|
|
|
|
|
|
|
|
You need to start the swayr demon `swayrd` in your sway config |
|
|
|
|
(`~/.config/sway/config`) like so: |
|
|
|
@ -259,7 +266,7 @@ bindsym $mod+Shift+c exec env RUST_BACKTRACE=1 \ |
|
|
|
|
Of course, configure the keys to your liking. Again, enabling rust backtraces |
|
|
|
|
and logging are optional. |
|
|
|
|
|
|
|
|
|
### Configuration |
|
|
|
|
### <a id="swayr-configuration">Configuration</a> |
|
|
|
|
|
|
|
|
|
Swayr can be configured using the `~/.config/swayr/config.toml` or |
|
|
|
|
`/etc/xdg/swayr/config.toml` config file. |
|
|
|
@ -376,9 +383,10 @@ right now. |
|
|
|
|
* `fallback_icon` is a path to some PNG/SVG icon which will be used as |
|
|
|
|
`{app_icon}` if no application-specific icon can be determined. |
|
|
|
|
|
|
|
|
|
All the placeholders except `{app_icon}`, `{indent}`, `{urgency_start}`, and |
|
|
|
|
`{urgency_end}` may optionally provide a format string as specified by |
|
|
|
|
[Rust's std::fmt](https://doc.rust-lang.org/std/fmt/). The syntax is |
|
|
|
|
All the <a id="fmt-placeholders">placeholders</a> except `{app_icon}`, |
|
|
|
|
`{indent}`, `{urgency_start}`, and `{urgency_end}` may optionally provide a |
|
|
|
|
format string as specified by [Rust's |
|
|
|
|
std::fmt](https://doc.rust-lang.org/std/fmt/). The syntax is |
|
|
|
|
`{<placeholder>:<fmt_str><clipped_str>}`. For example, `{app_name:{:>10.10}}` |
|
|
|
|
would mean that the application name is printed with exactly 10 characters. If |
|
|
|
|
it's shorter, it will be right-aligned (the `>`) and padded with spaces, if |
|
|
|
@ -442,7 +450,7 @@ over IPC. Therefore, auto-tiling is triggered by new-window events, |
|
|
|
|
close-events, move-events, floating-events, and also focus-events. The latter |
|
|
|
|
are a workaround and wouldn't be required if there were resize-events. |
|
|
|
|
|
|
|
|
|
### Version Changes |
|
|
|
|
### <a id="swayr-version-changes">Version changes</a> |
|
|
|
|
|
|
|
|
|
Since version 0.8.0, I've started writing a [NEWS](swayr/NEWS.md) file listing the |
|
|
|
|
news, and changes to `swayr` commands or configuration options. If something |
|
|
|
@ -452,17 +460,134 @@ of your config. |
|
|
|
|
|
|
|
|
|
## <a id="swayrbar">Swayrbar</a> |
|
|
|
|
|
|
|
|
|
TODO: Write docs! |
|
|
|
|
`swayrbar` is a status command for sway's `swaybar` implementing the |
|
|
|
|
[`swaybar-procotol(7)`](https://man.archlinux.org/man/swaybar-protocol.7). |
|
|
|
|
This means, you would setup your `swaybar` like so in your |
|
|
|
|
`~/.config/sway/config`: |
|
|
|
|
|
|
|
|
|
```conf |
|
|
|
|
bar { |
|
|
|
|
swaybar_command swaybar |
|
|
|
|
# Use swayrbar as status command with some logging output which |
|
|
|
|
# is redirected to /tmp/swayrbar.log. Be sure to only redirect |
|
|
|
|
# stderr because the swaybar protocol requires the status_command |
|
|
|
|
# to emit JSON to stdout which swaybar reads. |
|
|
|
|
status_command env RUST_BACKTRACE=1 RUST_LOG=swayr=debug swayrbar 2> /tmp/swayrbar.log |
|
|
|
|
position top |
|
|
|
|
font pango:Iosevka 11 |
|
|
|
|
height 20 |
|
|
|
|
|
|
|
|
|
colors { |
|
|
|
|
statusline #f8c500 |
|
|
|
|
background #33333390 |
|
|
|
|
} |
|
|
|
|
} |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
`swayrbar`, like [waybar](https://github.com/Alexays/Waybar/), consists of a |
|
|
|
|
set of modules which you can enable and configure via its config file, either |
|
|
|
|
system-wide (`/etc/xdg/swayrbar/config.toml`) or per user |
|
|
|
|
(`~/.config/swayrbar/config.toml`). Modules emit information which `swaybar` |
|
|
|
|
then displays and mouse clicks on a module's space in `swaybar` are propagated |
|
|
|
|
back and trigger some action (e.g., a shell command). |
|
|
|
|
|
|
|
|
|
Right now, there are the following modules: |
|
|
|
|
|
|
|
|
|
1. The `window` module can show the title and application name of the current |
|
|
|
|
window in sway. |
|
|
|
|
2. The `sysinfo` module can show things like CPU/memory utilization or system |
|
|
|
|
load. |
|
|
|
|
3. The `battery` module can show the current [state of |
|
|
|
|
charge](https://en.wikipedia.org/wiki/State_of_charge), the state (e.g., |
|
|
|
|
charging), and the [state of |
|
|
|
|
health](https://en.wikipedia.org/wiki/State_of_health). |
|
|
|
|
4. The `date` module can show, you guess it, the current date and time! |
|
|
|
|
|
|
|
|
|
I guess there will be more modules in the future as time permits. I personally |
|
|
|
|
would enjoy a `volume` module. [Patches](#questions-and-patches) are certainly |
|
|
|
|
very welcome! |
|
|
|
|
|
|
|
|
|
### <a id="swayrbar-configuration">Configuration</a> |
|
|
|
|
|
|
|
|
|
When `swayrbar` is run for the very first time and doesn't find an existing |
|
|
|
|
configuration file at `~/.config/swayrbar/config.toml` (user-specific) or |
|
|
|
|
`/etc/xdg/swayrbar/config.toml` (system-wide), it'll create a new user-specific |
|
|
|
|
one where all modules are enabled and set up with some reasonable (according to |
|
|
|
|
the author) default values. Adapt it to your needs. |
|
|
|
|
|
|
|
|
|
The syntax of the config file is [TOML](https://toml.io/en/). Here's a short |
|
|
|
|
example with all top-level options (one!) and one module. |
|
|
|
|
|
|
|
|
|
```toml |
|
|
|
|
refresh_interval = 1000 |
|
|
|
|
|
|
|
|
|
[[modules]] |
|
|
|
|
name = 'window' |
|
|
|
|
instance = '0' |
|
|
|
|
format = '🪟 {title} — {app_name}' |
|
|
|
|
html_escape = false |
|
|
|
|
|
|
|
|
|
[modules.on_click] |
|
|
|
|
Left = ['swayr', 'switch-to-urgent-or-lru-window'] |
|
|
|
|
Right = ['kill', '{pid}'] |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
The `refresh_interval` defines the number of milliseconds between refreshes of |
|
|
|
|
`swaybar`. |
|
|
|
|
|
|
|
|
|
The remainder of the configuration defines a list of modules with their |
|
|
|
|
configuration (which is an [array of |
|
|
|
|
tables](https://toml.io/en/v1.0.0#array-of-tables) in TOML where a module's |
|
|
|
|
`on_click`). |
|
|
|
|
|
|
|
|
|
* `name` is the name or type of the module, e.g., `window`, `sysinfo`, |
|
|
|
|
`battery`, `date`,... |
|
|
|
|
* `instance` is an arbitrary string used for distinguishing two modules of the |
|
|
|
|
same `name`. For example, you might want to have two `sysinfo` modules, one |
|
|
|
|
for CPU and one for memory utilization, simply to have a separator between |
|
|
|
|
these different kinds of information. That's easily doable, just give them |
|
|
|
|
different `instance` values. |
|
|
|
|
* `format` is the string to be printed in `swaybar` where certain placeholders |
|
|
|
|
are substituted with module-specific values. Usually, such placeholders are |
|
|
|
|
written like `{title}`, i.e., inside braces. Like in `swayr`, formatting is |
|
|
|
|
available, see [here](#fmt-placeholders). |
|
|
|
|
* `html_escape` defines if `<` and `>` should be escaped as `<` and `>` |
|
|
|
|
because `format` may contain [pango |
|
|
|
|
markup](https://docs.gtk.org/Pango/pango_markup.html). Obviously, if you |
|
|
|
|
make use of this feature, you want to set `html_escape = true` for that |
|
|
|
|
module. This option is optional and may be omitted. |
|
|
|
|
* `on_click` is a table defining actions to be performed when you click on a |
|
|
|
|
module's space in `swaybar`. All placeholders available in `format` are |
|
|
|
|
available here, too. The action for each mouse button is specified as an |
|
|
|
|
array `['command', 'arg1', 'arg2',...]`. The available button names to be |
|
|
|
|
assigned to are `Left`, `Middle`, `Right`, `WheelUp`, `WheelDown`, |
|
|
|
|
`WheelLeft`, and `WheelRight`. |
|
|
|
|
|
|
|
|
|
The `on_click` table can also be written as: |
|
|
|
|
|
|
|
|
|
```toml |
|
|
|
|
on_click = { |
|
|
|
|
Left = ['swayr', 'switch-to-urgent-or-lru-window'] |
|
|
|
|
Right = ['kill', '{pid}'] |
|
|
|
|
} |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
I think this version is more readable but the version shown in the beginning of |
|
|
|
|
this section is what the [toml crate](https://crates.io/crates/toml) exports. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## <a id="questions-and-patches">Questions & Patches</a> |
|
|
|
|
|
|
|
|
|
For asking questions, sending feedback, or patches, refer to [my public inbox |
|
|
|
|
(mailinglist)](https://lists.sr.ht/~tsdh/public-inbox). Please mention the |
|
|
|
|
project you are referring to in the subject. |
|
|
|
|
project you are referring to in the subject, e.g., `swayr` or `swayrbar` (or |
|
|
|
|
other projects in different repositories). |
|
|
|
|
|
|
|
|
|
## <a id="bugs">Bugs</a> |
|
|
|
|
|
|
|
|
|
Bugs and requests can be reported [here](https://todo.sr.ht/~tsdh/swayr). |
|
|
|
|
It compiles, therefore there are no bugs. Oh well, if you still found one or |
|
|
|
|
want to request a feature, you can do so |
|
|
|
|
[here](https://todo.sr.ht/~tsdh/swayr). |
|
|
|
|
|
|
|
|
|
## <a id="build-status">Build status</a> |
|
|
|
|
|
|
|
|
|