Turns your workspaces into a more topic oriented system.

This module allows to organize your workspaces on a precise topic basis. So instead of having a workspace called work you can setup one workspace per task. Here we call these workspaces, topics. The great thing with topics is that one can attach a directory that makes sense to each particular topic. One can also attach an action which will be triggered when switching to a topic that does not have any windows in it. So you can attach your mail client to the mail topic, some terminals in the right directory to the xmonad topic... This package also provides a nice way to display your topics in an historical way using a custom pprWindowSet function. You can also easily switch to recent topics using this history of last focused topics.

A blog post highlighting some features of this module can be found here.

You can use this module with the following in your xmonad.hs:

import qualified Data.Map.Strict as M
import qualified XMonad.StackSet as W

import XMonad.Actions.TopicSpace
import XMonad.Util.EZConfig    -- for the keybindings
import XMonad.Prompt.Workspace -- if you want to use the prompt

You will then have to

• Define a new TopicConfig via TopicItems
• Add the appropriate keybindings
• Replace the workspaces field in your XConfig with a list of your topics names
• Optionally, if you want to use the history features, add workspaceHistoryHook from XMonad.Hooks.WorkspaceHistory (re-exported by this module) or an equivalent function to your logHook. See the documentation of XMonad.Hooks.WorkspaceHistory for further details

Let us go through a full example together.

A TopicItem consists of three things: the name of the topic, its root directory, and the action associated to it—to be executed if the topic is empty or the action is forced via a keybinding.

We start by specifying our chosen topics as a list of such TopicItems:

topicItems :: [TopicItem]
topicItems =
  [ inHome   "1:WEB"              (spawn "firefox")
  , noAction "2"      "."
  , noAction "3:VID"  "videos"
  , TI       "4:VPN"  "openvpn"   (spawn "urxvt -e randomVPN.sh")
  , inHome   "5:IM"               (spawn "signal" *> spawn "telegram")
  , inHome   "6:IRC"              (spawn "urxvt -e weechat")
  , TI       "dts"    ".dotfiles" spawnShell
  , TI       "xm-con" "hs/xm-con" (spawnShell *> spawnShellIn "hs/xm")
  ]

Then we just need to put together our topic config:

myTopicConfig :: TopicConfig
myTopicConfig = def
  { topicDirs          = tiDirs    topicItems
  , topicActions       = tiActions topicItems
  , defaultTopicAction = const (pure ()) -- by default, do nothing
  , defaultTopic       = "1:WEB"         -- fallback
  }

Above, we have used the spawnShell and spawnShellIn helper functions; here they are:

spawnShell :: X ()
spawnShell = currentTopicDir myTopicConfig >>= spawnShellIn

spawnShellIn :: Dir -> X ()
spawnShellIn dir = spawn $ "alacritty --working-directory " ++ dir

Next, we define some other other useful helper functions. It is rather common to have a lot of topics—much more than available keys! In a situation like that, it's very convenient to switch topics with a prompt; the following use of workspacePrompt does exactly that.

goto :: Topic -> X ()
goto = switchTopic myTopicConfig

promptedGoto :: X ()
promptedGoto = workspacePrompt def goto

promptedShift :: X ()
promptedShift = workspacePrompt def $ windows . W.shift

-- Toggle between the two most recently used topics, but keep
-- screens separate.  This needs @workspaceHistoryHook@.
toggleTopic :: X ()
toggleTopic = switchNthLastFocusedByScreen myTopicConfig 1

Hopefully you've gotten a general feeling of how to define these kind of small helper functions using what's provided in this module.

Adding the appropriate keybindings works as it normally would. Here, we'll use XMonad.Util.EZConfig syntax:

myKeys :: [(String, X ())]
myKeys =
  [ ("M-n"        , spawnShell)
  , ("M-a"        , currentTopicAction myTopicConfig)
  , ("M-g"        , promptedGoto)
  , ("M-S-g"      , promptedShift)
  , ("M-S-<Space>", toggleTopic)
  ]
  ++
  -- The following does two things:
  --   1. Switch topics (no modifier)
  --   2. Move focused window to topic N (shift modifier)
  [ ("M-" ++ m ++ k, f i)
  | (i, k) <- zip (topicNames topicItems) (map show [1 .. 9 :: Int])
  , (f, m) <- [(goto, ""), (windows . W.shift, "S-")]
  ]

This makes M-1 to M-9 switch to the first nine topics that we have specified in topicItems.

You can also switch to the nine last-used topics instead:

  [ ("M-" ++ show i, switchNthLastFocused myTopicConfig i)
  | i <- [1 .. 9]
  ]

We can now put the whole configuration together with the following:

main :: IO ()
main = xmonad $ def
  { workspaces = topicNames topicItems
  }
 `additionalKeysP` myKeys