From 7db09a31f8535385b6d781d7d4eb723cd49b7ffa Mon Sep 17 00:00:00 2001 From: Thomas Letan Date: Thu, 27 Apr 2023 13:34:23 +0200 Subject: Spatial Shell Call for Testers --- .gitignore | 3 + site/img/spatial-shell-example.png | Bin 0 -> 190003 bytes site/img/spatial-shell.png | Bin 0 -> 726132 bytes site/index.org | 2 +- site/news/CFTSpatialShell.org | 193 +++++++++++++++++++++++++++++++++++++ site/news/index.html | 15 +++ 6 files changed, 212 insertions(+), 1 deletion(-) create mode 100644 site/img/spatial-shell-example.png create mode 100644 site/img/spatial-shell.png create mode 100644 site/news/CFTSpatialShell.org diff --git a/.gitignore b/.gitignore index 1e56470..700dcba 100644 --- a/.gitignore +++ b/.gitignore @@ -15,6 +15,7 @@ _opam logs/coqffi-tutorial.stderr logs/site--index.html.stderr logs/site--news--August2022.html.stderr +logs/site--news--CFTSpatialShell.html.stderr logs/site--news--ColorlessThemes-0.2.html.stderr logs/site--news--MonthlyRetrospectives.html.stderr logs/site--news--November2022.html.stderr @@ -53,6 +54,7 @@ logs/tangling-lp.stderr logs/coqffi-tutorial.stdout logs/site--index.html.stdout logs/site--news--August2022.html.stdout +logs/site--news--CFTSpatialShell.html.stdout logs/site--news--ColorlessThemes-0.2.html.stdout logs/site--news--MonthlyRetrospectives.html.stdout logs/site--news--November2022.html.stdout @@ -96,6 +98,7 @@ rss.json site/files/coqffi-tutorial.tar.gz site/index.html site/news/August2022.html +site/news/CFTSpatialShell.html site/news/ColorlessThemes-0.2.html site/news/MonthlyRetrospectives.html site/news/November2022.html diff --git a/site/img/spatial-shell-example.png b/site/img/spatial-shell-example.png new file mode 100644 index 0000000..4e03e10 Binary files /dev/null and b/site/img/spatial-shell-example.png differ diff --git a/site/img/spatial-shell.png b/site/img/spatial-shell.png new file mode 100644 index 0000000..cb348c2 Binary files /dev/null and b/site/img/spatial-shell.png differ diff --git a/site/index.org b/site/index.org index 5df05ff..08b950d 100644 --- a/site/index.org +++ b/site/index.org @@ -31,5 +31,5 @@ let me know!]. - [[https://github.com/coq-community/coqffi][~coqffi~]] is a tool that generates the necessary boilerplate to use OCaml functions in a Coq development, and configure the Coq extraction mechanism accordingly. - - [[https://github.com/lthms/spatial-sway][Spatial Sway]] is a daemon that enables a dynamic tiling management + - [[https://github.com/lthms/spatial-shell][Spatial Shell]] is a daemon that enables a dynamic tiling management workflow a la Material Shell and PaperWM. diff --git a/site/news/CFTSpatialShell.org b/site/news/CFTSpatialShell.org new file mode 100644 index 0000000..e713671 --- /dev/null +++ b/site/news/CFTSpatialShell.org @@ -0,0 +1,193 @@ +#+TITLE: Call For Testers: Spatial Shell + +In August, 2022, I discovered [[https://material-shell.com][Material Shell]]. A +few weeks later, I had pieced together a working prototype of a dynamic tiling +management “a la Material Shell” for [[https://swaywm.org][sway]]. By October, +the project was basically fulfilling my main needs, and I had already started +to use it on my workstation[fn::I tried so you do not have to: having my +graphical session going crazy during a work meeting because of a software I had +written.]. The project sat there for a while, until I rediscovered this thing +called /holidays/. + +For a short week, I tried to address at many of the remaining issues and +missing features that I was aware of. Then, I started to write +[[https://lthms.github.io/spatial-shell/spatial.1.html][man pages]], which +turned out to be the perfect opportunity to clean-up every clunkiness I could +possibly found. + +I can’t help but finding the result rather nice, and I hope you will enjoy it +too! [[https://github.com/lthms/spatial-shell][Spatial Shell]] works on my +machine, which means it will definitely break on yours. But this is where the +fun lies, right? At this point, I definitely think the project is ready to fall +in the hands of (motivated) alpha testers. + +#+BEGIN_EXPORT html + +
site/news/CFTSpatialShell.org
+#+END_EXPORT + +It would be fair to say that Spatial Shell does not bring any novel ideas to +the table (neither from a user perspective, nor a developer one). Hopefully, it +does implement well established ideas in a nice and reliable way, so sway users +can enjoy Material Shell key ideas without having to install GNOME 3. + +Anyway, let me give a tour! + +* Spatial Model + +At its core, Spatial Shell allows you to navigate a gride of windows, wherein +each workspace is a row. Each workspace can be configured to determine how many +windows (cells) you can see at once. More precisely, Spatial Shell supports two +layouts: + +- *Maximize:* One window is displayed at a time +- *Column:* Several windows are displayed side by side, to your convenience + +The reason why *Maximize* is not a particular case of *Column*, but instead a +layout on its own, is to easily allow you to switch to and back from maximizing +the focused window. The following picture[fn::Created using +[[https://excalidraw.com/][Excalidraw]].] summarizes one particular setup with +tree workspaces, each configured differently. + +#+CAPTION: Spatial Shell allows users to configure the layout of each workspace individually. +#+NAME: fig:spatial-shell-example +[[../img/spatial-shell-example.png]] + +- Workspace 1 contains three windows, and is configured to use the *Column* + layout to display at most three windows, so every windows are visible, with + the focus being on the leftmost one. +- Workspace 2 contains four windows, and is configured to use the *Column* + layout to display at most two windows. As a consequence, two windows are not + visible. +- Workspace 3 contains two windows, and is configured to use the *Maximize* + layout so only the focused window is visible. + +To help users know which window is currently holding the focus, Spatial Shell +slightly reduces the opacity of unfocused windows (as poorly hinted by the gray +backgrounds in the figure). Finally, Spatial Shell can also set a background +for empty workspaces (using ~swaybg~ under the hood). + +And this is basically it. There is not much more to say about Spatial Shell +features. + +* Configuration + +From an implementation and user experience perspective, Spatial Shell is taking +inspiration from i3 and sway. + +More precisely, Spatial Shell comprises two executables: + +- [[https://lthms.github.io/spatial-shell/spatial.1.html][spatial(1)]], the + daemon implementing the spatial model described in the previous section, and +- [[https://lthms.github.io/spatial-shell/spatialmsg.1.html][spatialmsg(1)]], a + client used to control the current instance of spatial. + +Assuming ~$spatial~ and ~$spatialmsg~ contains the pathes to spatial and +spatialmsg binaries respectively, then the simplest sway configuration to start +using Spatial Shell is the following + +#+begin_src +exec $spatial + +# moving the focus +bindsym $mod+h exec $spatialmsg "focus left" +bindsym $mod+l exec $spatialmsg "focus right" +bindsym $mod+k exec $spatialmsg "focus up" +bindsym $mod+j exec $spatialmsg "focus down" + +# moving the focused window +bindsym $mod+Shift+h exec $spatialmsg "move left" +bindsym $mod+Shift+l exec $spatialmsg "move right" +bindsym $mod+Shift+k exec $spatialmsg "move up" +bindsym $mod+Shift+j exec $spatialmsg "move down" + +# toggle between Maximize and Column layout +bindsym $mod+space exec $spatialmsg "toggle layout" + +# modify the number of windows to display in the Column layout +bindsym $mod+i exec $spatialmsg "column count decrement" +bindsym $mod+o exec $spatialmsg "column count increment" +#+end_src + +By default, Spatial Shell sets the initial configuration of a workspace to +the Column layout with two columns at most, and sets the opacity of the +unfocused windows to 75%. This can be customized, either globally or per +workspace, by creating a configuration file in +~$XDR_RUNTIME_DIR/spatial/config~[fn::If unset, ~XDG_RUNTIME_DIR~ defaults to +~$HOME/.config~.]. + +For instance, my config file looks like that. + +#+begin_src +[workspace=3] default layout maximize +background "~/.config/spatial/wallpaper.jpg" +unfocus opacity 85 +#+end_src + +See [[https://lthms.github.io/spatial-shell/spatial.5.html][spatial(5)]] for +the list of commands supported by Spatial Shell. + +As a sidenote, readers familiar with sway will definetely pick the resemblance +with sway and swaymsg, and it actually goes pretty deep. In a nutshell, swaymsg +connects to a UNIX socket created by sway at startup time, to sends it commands +(see [[https://lthms.github.io/spatial-shell/spatial.5.html][spatial(5)]]) +using a dedicated IPC protocol inherited from i3 (see +[[https://lthms.github.io/spatial-shell/sway-ipc.7.html][sway-ipc(5)]]). Not +only spatial also relies on sway IPC protocol to interact with sway and +implement its spatial model, it creates a UNIX of its own, and supports its own +set of commands +([[https://lthms.github.io/spatial-shell/spatial-ipc.7.html][spatial-ipc.7.html]]). +spatial does exactly the same thing. + +* Waybar Integration + +It is a common practice to use a so-called “bar” with sway, to display some +useful information about the current state of the system. In the ~contrib/~ +directory of [[https://github.com/lthms/spatial-shell][Spatial Shell +repository]], interested readers will find a configuration for +[[https://github.com/Alexays/Waybar][Waybar]][fn::Readers familiar with +Material Shell design will not be surprised by the general look and feel of +this screenshot.]. This configuration is somewhat clunky at the moment, due to +the limitations of the custom widget of Waybar which does not allow to have one +widget defines several “buttons.” I am interested in investing a bit of time to +see if I could write a native widget, similarly to sway’s one. + +That being said, the user experience with this integration is already pretty +neat. As long as you don’t need more +than 6 workspaces and 8 windows per workspaces, you are good to go! + +#+CAPTION: Mandatory screenshot of Spatial Shell, with the Waybar configuration. +#+NAME: fig:spatial-shell +[[../img/spatial-shell.png]] + +* Building from Source + +As of April 2023, the only way to get Spatial Shell is to build it from source. + +You will need the following runtime dependencies: + +- sway (i3 might be supported at some point) +- gmp (for bad reasons, fortunalety this will be removed at some point) +- swaybg +- waybar (if you want the full experience) + +You will need the following build dependencies: + +- opam +- scdoc (for the man pages) + +Then, building and installing Spatial Shell is as simple as using the two +following commands. + +#+begin_src +make build-deps +make install +#+end_src + +The latter command will install Spatial Shell’s binaries in ~/usr/local/bin~, +and the man pages in ~/usr/local/man~. You can remove them with ~make +uninstall~. + +To install Waybar theme, copy ~contrib/waybar/spatialbar.py~ to +~/usr/local/bin/spatialbar~ for instance, and the Waybar style and config file +to ~$HOME/.config/waybar~. diff --git a/site/news/index.html b/site/news/index.html index 01554d2..eca97c6 100644 --- a/site/news/index.html +++ b/site/news/index.html @@ -1,5 +1,20 @@

News

+

2023

+ + +

2022