This repo contains code implementing Spatial Groups for StumpWM.

======================================================================

Installation:

Please see https://github.com/stumpwm/stumpwm/wiki/Modules for how to
install the stumpwm-contrib collection.

Otherwise, manually:

 mkdir ~/.stumpwm.d/modules  (if needed)

 git clone https://github.com/stumpwm/stumpwm-contrib ~/.stumpwm.d/modules

 In your .stumpwmrc, add the following:

   (in-package :stumpwm)
   (load-module "spatial-groups")
   (spatial-groups:install-default-keybinds) ; optional

 Restart stumpwm.

======================================================================

From the original post:

http://demosthenes.org/tmp/StumpWMSpatialGroups.mp4

Please pardon the rough edges. I'm not starting a Youtube channel,
just trying to have a conversation about how to manage windows and
groups in Stump.

Spatial grouping abuses Stump's ability to dynamically create groups
to create a sparse 3d array of groups, visualized as multiple desktops
of a 2d grid of screens. Hotkeys use arrows to navigate the grid and
swap desktops in a way which emulates a larger physical screen
surface.

Using this method allows me to group windows by project, adjacent to
each other. This allows absolute navigation to each window, as opposed
to relative navigation (ie: alt-tab).

I'm not grouping related application windows on the same screen, but
rather organizing patterns of groups to keep related application
windows cognitively near each other. I still may use splits and tile
windows within a screen, but not as often.

Concepts:
 Spatial groups use a 3d coordinate system: “x,y,z”
 Valid groups are “0,0,0”, “-1,2,0”, etc.
 Z is used as the desktop index

Keys:
 Control-Shift-{Left,Right}: Change desktop (Z axis)
 Control-Arrows: Navigate virtual screens on current desktop
 Control-Shift-Up: Return to 0,0 on current desktop (Z)
 Shift-Arrows: Navigate splits on current screen group

======================================================================

This idea of spatial groupings I have been using since Enlightenment
in the early 2000's. E later dropped their virtual desktops with
expandable numbers of screens in a grid.

I've implemented this concept on xmonad, awesome WM, i3, and now
StumpWM (my fav).

My work style is to start a central task, and then supplemental tasks
should be organized radially from that central task. To do this, I use
a 2d plane of workspaces where I can easily layout my windows
geometrically and navigate them spatially in lieu of a desktop or tab
analogy. Multiple projects or key tasks are separated on separate
planes.

In this configuration, each workspace is a tag organized into a 3d
cube of workspaces described by a simple coordinate system. To
navigate between these workspaces, simple keybindings have been
created.

Example Workspace Plane:

The example plane below puts Emacs into the central window, surrounded
by supplimental windows that help support the central task.

At any time from the central window, any supplemental window is only
one key chord away (Control+Arrows). Habit and simple organization
gives way to always knowing where to go to find an item in relation to
the central workspace.

+-----------------------------------------------+----------------------+
|                       |                       |                      |
|                       |  Supplement           |                      |
|                       |                       |                      |
|                       |  Firefox              |                      |
|                       |                       |                      |
+----------------------------------------------------------------------+
|                       |                       |                      |
|  Supplement           |    Central Task       |  Supplement          |
|                       |                       |                      |
|  SQL Window           |    EMACS              |  Documentation       |
|                       |                       |                      |
+----------------------------------------------------------------------+
|                       |                       |                      |
|                       |  Supplement           |                      |
|                       |                       |                      |
|                       |  Two shell prompts    |                      |
|                       |                       |                      |
+-----------------------------------------------+----------------------+


There is no Alt-tab style confusion of trying to find the right window
in a dynamic stack. This organization also lends itself to full screen
windows, or relatively few tiles.

Second level supplementary windows can be created in the corners,
where they are at most two key chords from center. These are less
frequently used and may provide scratch space for additional windows.

The third dimension comes in when managing multiple core tasks in
parallel, where the advantage of easy radial addressing becomes a
concern for another project. The third dimension allows us to stack
workspaces, and toggle between them when it is time to change
projects.

+-----------------------------------------------+----------------------+
| 1,1,1                 |                       |                      |
|                       |  Supplement           |                      |
|                       |                       |                      |
|                       |  Firefox              |                      |---------+
|                       |                       |                      |         |
+----------------------------------------------------------------------+         |
|                       |                       |                      |         |
|  Supplement           |    Central Task       |  Supplement          |         |
|                       |                       |                      |         |----------+
|  SQL Window           |    EMACS              |  Documentation       |---------+          |
|                       |                       |                      |         |          |
+----------------------------------------------------------------------+         |          |
|                       |                       |                      |         |          |
|                       |  Supplement           |                      |on       |          |
|                       |                       |                      |         |----------+
|                       |  Two shell prompts    |                      |---------+          |
| 1,3,1                 |                       |                      |         |          |
+-----------------------------------------------+----------------------+         |          |
          |                       |                       |                      |ion       |
          |                       |  Two shell prompts    |                      |          |
          | 1,3,2                 |                       |                      |----------+
          +-----------------------------------------------+----------------------+          |
                     |                       |                       |                      |
                     |                       |  Two shell prompts    |                      |
                     | 1,3,3                 |                       |                      |
                     +-----------------------------------------------+----------------------+

======================================================================

TODO:

 - Multiple monitor support?
 - Cleanup code
