-----------------------------------------------------------------------------
-- |
-- Module : XMonad.Actions.TopicSpace
-- Copyright : (c) Nicolas Pouillard
-- License : BSD-style (see LICENSE)
--
-- Maintainer : Nicolas Pouillard <nicolas.pouillard@gmail.com>
-- Stability : unstable
-- Portability : unportable
--
-- Turns your workspaces into a more topic oriented system.
-----------------------------------------------------------------------------
module XMonad.Actions.TopicSpace
(
-- * Overview
-- $overview
-- * Usage
-- $usage
Topic
, Dir
, TopicConfig(..)
, getLastFocusedTopics
, setLastFocusedTopic
, pprWindowSet
, topicActionWithPrompt
, topicAction
, currentTopicAction
, switchTopic
, switchNthLastFocused
, shiftNthLastFocused
, currentTopicDir
, checkTopicConfig
, (>*>)
)
where
import XMonad
import Data.List
import Data.Maybe (fromMaybe, isNothing, listToMaybe)
import Data.Ord
import qualified Data.Map as M
import Control.Monad ((=<<),liftM2,when,unless,replicateM_)
import System.IO
import XMonad.Operations
import qualified XMonad.StackSet as W
import XMonad.Prompt
import XMonad.Prompt.Workspace
import XMonad.Hooks.UrgencyHook
import XMonad.Hooks.DynamicLog (PP(..))
import qualified XMonad.Hooks.DynamicLog as DL
import XMonad.Util.Run (spawnPipe)
import XMonad.Util.StringProp(getStringListProp,setStringListProp)
-- $overview
-- 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.
-- $usage
-- Here is an example of configuration using TopicSpace:
--
-- @
-- -- The list of all topics/workspaces of your xmonad configuration.
-- -- The order is important, new topics must be inserted
-- -- at the end of the list if you want hot-restarting
-- -- to work.
-- myTopics :: [Topic]
-- myTopics =
-- [ \"dashboard\" -- the first one
-- , \"admin\", \"build\", \"cleaning\", \"conf\", \"darcs\", \"haskell\", \"irc\"
-- , \"mail\", \"movie\", \"music\", \"talk\", \"text\", \"tools\", \"web\", \"xmonad\"
-- , \"yi\", \"documents\", \"twitter\", \"pdf\"
-- ]
-- @
--
-- @
-- myTopicConfig :: TopicConfig
-- myTopicConfig = TopicConfig
-- { topicDirs = M.fromList $
-- [ (\"conf\", \"w\/conf\")
-- , (\"dashboard\", \"Desktop\")
-- , (\"yi\", \"w\/dev-haskell\/yi\")
-- , (\"darcs\", \"w\/dev-haskell\/darcs\")
-- , (\"haskell\", \"w\/dev-haskell\")
-- , (\"xmonad\", \"w\/dev-haskell\/xmonad\")
-- , (\"tools\", \"w\/tools\")
-- , (\"movie\", \"Movies\")
-- , (\"talk\", \"w\/talks\")
-- , (\"music\", \"Music\")
-- , (\"documents\", \"w\/documents\")
-- , (\"pdf\", \"w\/documents\")
-- ]
-- , defaultTopicAction = const $ spawnShell >*> 3
-- , defaultTopic = \"dashboard\"
-- , maxTopicHistory = 10
-- , topicActions = M.fromList $
-- [ (\"conf\", spawnShell >> spawnShellIn \"wd\/ertai\/private\")
-- , (\"darcs\", spawnShell >*> 3)
-- , (\"yi\", spawnShell >*> 3)
-- , (\"haskell\", spawnShell >*> 2 >>
-- spawnShellIn \"wd\/dev-haskell\/ghc\")
-- , (\"xmonad\", spawnShellIn \"wd\/x11-wm\/xmonad\" >>
-- spawnShellIn \"wd\/x11-wm\/xmonad\/contrib\" >>
-- spawnShellIn \"wd\/x11-wm\/xmonad\/utils\" >>
-- spawnShellIn \".xmonad\" >>
-- spawnShellIn \".xmonad\")
-- , (\"mail\", mailAction)
-- , (\"irc\", ssh somewhere)
-- , (\"admin\", ssh somewhere >>
-- ssh nowhere)
-- , (\"dashboard\", spawnShell)
-- , (\"twitter\", spawnShell)
-- , (\"web\", spawn browserCmd)
-- , (\"movie\", spawnShell)
-- , (\"documents\", spawnShell >*> 2 >>
-- spawnShellIn \"Documents\" >*> 2)
-- , (\"pdf\", spawn pdfViewerCmd)
-- ]
-- }
-- @
--
-- @
-- -- extend your keybindings
-- myKeys conf\@XConfig{modMask=modm} =
-- [ ((modm , xK_n ), spawnShell) -- %! Launch terminal
-- , ((modm , xK_a ), currentTopicAction myTopicConfig)
-- , ((modm , xK_g ), promptedGoto)
-- , ((modm .|. shiftMask, xK_g ), promptedShift)
-- ...
-- ]
-- ++
-- [ ((modm, k), switchNthLastFocused myTopicConfig i)
-- | (i, k) <- zip [1..] workspaceKeys]
-- @
--
-- @
-- spawnShell :: X ()
-- spawnShell = currentTopicDir myTopicConfig >>= spawnShellIn
-- @
--
-- @
-- spawnShellIn :: Dir -> X ()
-- spawnShellIn dir = spawn $ \"urxvt '(cd ''\" ++ dir ++ \"'' && \" ++ myShell ++ \" )'\"
-- @
--
-- @
-- goto :: Topic -> X ()
-- goto = switchTopic myTopicConfig
-- @
--
-- @
-- promptedGoto :: X ()
-- promptedGoto = workspacePrompt myXPConfig goto
-- @
--
-- @
-- promptedShift :: X ()
-- promptedShift = workspacePrompt myXPConfig $ windows . W.shift
-- @
--
-- @
-- myConfig = do
-- checkTopicConfig myTopics myTopicConfig
-- myLogHook <- makeMyLogHook
-- return $ defaultConfig
-- { borderWidth = 1 -- Width of the window border in pixels.
-- , workspaces = myTopics
-- , layoutHook = myModifiers myLayout
-- , manageHook = myManageHook
-- , logHook = myLogHook
-- , handleEventHook = myHandleEventHook
-- , terminal = myTerminal -- The preferred terminal program.
-- , normalBorderColor = \"#3f3c6d\"
-- , focusedBorderColor = \"#4f66ff\"
-- , XMonad.modMask = mod1Mask
-- , keys = myKeys
-- , mouseBindings = myMouseBindings
-- }
-- @
--
-- @
-- main :: IO ()
-- main = xmonad =<< myConfig
-- @
-- | An alias for @flip replicateM_@
(>*>) :: Monad m => m a -> Int -> m ()
(>*>) = flip replicateM_
infix >*>
-- | 'Topic' is just an alias for 'WorkspaceId'
type Topic = WorkspaceId
-- | 'Dir' is just an alias for 'FilePath' but should points to a directory.
type Dir = FilePath
-- | Here is the topic space configuration area.
data TopicConfig = TopicConfig { topicDirs :: M.Map Topic Dir
-- ^ This mapping associate a directory to each topic.
, topicActions :: M.Map Topic (X ())
-- ^ This mapping associate an action to trigger when
-- switching to a given topic which workspace is empty.
, defaultTopicAction :: Topic -> X ()
-- ^ This is the default topic action.
, defaultTopic :: Topic
-- ^ This is the default topic.
, maxTopicHistory :: Int
-- ^ This setups the maximum depth of topic history, usually
-- 10 is a good default since we can bind all of them using
-- numeric keypad.
}
-- | Returns the list of last focused workspaces the empty list otherwise.
-- This function rely on a reserved property namely _XMONAD_LAST_FOCUSED_WORKSPACES.
getLastFocusedTopics :: X [String]
getLastFocusedTopics = asks display >>= flip getStringListProp "_XMONAD_LAST_FOCUSED_WORKSPACES"
-- | Given a 'TopicConfig', the last focused topic, and a predicate that will
-- select topics that one want to keep, this function will set the property
-- of last focused topics.
setLastFocusedTopic :: TopicConfig -> Topic -> (Topic -> Bool) -> X ()
setLastFocusedTopic tg w predicate = do
disp <- asks display
setStringListProp disp "_XMONAD_LAST_FOCUSED_WORKSPACES"
. take (maxTopicHistory tg) . nub . (w:) . filter predicate =<< getLastFocusedTopics
-- | This function is a variant of 'DL.pprWindowSet' which takes a topic configuration
-- and a pretty-printing record 'PP'. It will show the list of topics sorted historically
-- and highlighting topics with urgent windows.
pprWindowSet :: TopicConfig -> PP -> X String
pprWindowSet tg pp = do
winset <- gets windowset
urgents <- readUrgents
let empty_workspaces = map W.tag $ filter (isNothing . W.stack) $ W.workspaces winset
maxDepth = maxTopicHistory tg
setLastFocusedTopic tg (W.tag . W.workspace . W.current $ winset)
(`notElem` empty_workspaces)
lastWs <- getLastFocusedTopics
let depth topic = elemIndex topic lastWs
add_depth proj topic = proj pp $ maybe topic (((topic++":")++) . show) $ depth topic
pp' = pp { ppHidden = add_depth ppHidden, ppVisible = add_depth ppVisible }
sortWindows = take (maxDepth - 1) . sortBy (comparing $ fromMaybe maxDepth . depth . W.tag)
return $ DL.pprWindowSet sortWindows urgents pp' winset
-- | Given a prompt configuration and a topic configuration, triggers the action associated with
-- the topic given in prompt.
topicActionWithPrompt :: XPConfig -> TopicConfig -> X ()
topicActionWithPrompt xp tg = workspacePrompt xp (liftM2 (>>) (switchTopic tg) (topicAction tg))
-- | Given a configuration and a topic, triggers the action associated with the given topic.
topicAction :: TopicConfig -> Topic -> X ()
topicAction tg topic = fromMaybe (defaultTopicAction tg topic) $ M.lookup topic $ topicActions tg
-- | Trigger the action associated with the current topic.
currentTopicAction :: TopicConfig -> X ()
currentTopicAction tg = topicAction tg =<< gets (W.tag . W.workspace . W.current . windowset)
-- | Switch to the given topic.
switchTopic :: TopicConfig -> Topic -> X ()
switchTopic tg topic = do
windows $ W.greedyView topic
wins <- gets (W.integrate' . W.stack . W.workspace . W.current . windowset)
when (null wins) $ topicAction tg topic
-- | Switch to the Nth last focused topic or failback to the 'defaultTopic'.
switchNthLastFocused ::TopicConfig -> Int -> X ()
switchNthLastFocused tg depth = do
lastWs <- getLastFocusedTopics
switchTopic tg $ (lastWs ++ repeat (defaultTopic tg)) !! depth
-- | Shift the focused window to the Nth last focused topic, or fallback to doing nothing.
shiftNthLastFocused :: Int -> X ()
shiftNthLastFocused n = do
ws <- fmap (listToMaybe . drop n) getLastFocusedTopics
whenJust ws $ windows . W.shift
-- | Returns the directory associated with current topic returns the empty string otherwise.
currentTopicDir :: TopicConfig -> X String
currentTopicDir tg = do
topic <- gets (W.tag . W.workspace . W.current . windowset)
return . fromMaybe "" . M.lookup topic $ topicDirs tg
-- | Check the given topic configuration for duplicates topics or undefined topics.
checkTopicConfig :: [Topic] -> TopicConfig -> IO ()
checkTopicConfig tags tg = do
-- tags <- gets $ map W.tag . workspaces . windowset
let
seenTopics = nub $ sort $ M.keys (topicDirs tg) ++ M.keys (topicActions tg)
dups = tags \\ nub tags
diffTopic = seenTopics \\ sort tags
check lst msg = unless (null lst) $ xmessage $ msg ++ " (tags): " ++ show lst
check diffTopic "Seen but missing topics/workspaces"
check dups "Duplicate topics/workspaces"
-- | Display the given message using the @xmessage@ program.
xmessage :: String -> IO ()
xmessage s = do
h <- spawnPipe "xmessage -file -"
hPutStr h s
hClose h
