Merge pull request xmonad#763 from slotThe/extending->tutorial

A Potpourri of Small Changes

CHANGES.md

@@ -74,6 +74,22 @@
     and `manyTill` functions, in order to achieve feature parity with
     `Text.ParserCombinators.ReadP`.
 
+* `XMonad.Actions.FloatKeys`
+
+  - Added `directionMoveWindow` and `directionMoveWindow` as more
+    alternatives to the existing functions.
+
+* `XMonad.Hooks.InsertPosition`
+
+  - Added `setupInsertPosition` as a combinator alternative to
+    `insertPosition`.
+
+* `XMonad.Actions.Navigation2D`
+
+  - Added `sideNavigation` as a fallback to the default tiling strategy,
+    in case `lineNavigation` can't find a window.  This benefits
+    especially users who use `XMonad.Layout.Spacing`.
+
 ### Other changes
 
 ## 0.17.1 (September 3, 2022)

XMonad/Actions/Commands.hs

@@ -57,7 +57,7 @@ import XMonad.Prelude
 -- bindings!)
 --
 -- For detailed instructions on editing your key bindings, see
--- "XMonad.Doc.Extending#Editing_key_bindings".
+-- <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.
 
 -- | Create a 'Data.Map.Map' from @String@s to xmonad actions from a
 --   list of pairs.

XMonad/Actions/CopyWindow.hs

@@ -77,7 +77,7 @@ import qualified XMonad.StackSet as W
 -- >  , ((modm .|. shiftMask, xK_v ),  killAllOtherCopies) -- @@ Toggle window state back
 --
 -- For detailed instructions on editing your key bindings, see
--- "XMonad.Doc.Extending#Editing_key_bindings".
+-- <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.
 
 -- $logHook
 --

XMonad/Actions/CycleRecentWS.hs

@@ -49,7 +49,7 @@ import Data.Function (on)
 -- >   , ((modm, xK_Tab), cycleRecentWS [xK_Alt_L] xK_Tab xK_grave)
 --
 -- For detailed instructions on editing your key bindings, see
--- "XMonad.Doc.Extending#Editing_key_bindings".
+-- <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.
 
 -- | Cycle through most recent workspaces with repeated presses of a key, while
 --   a modifier key is held down. The recency of workspaces previewed while browsing

XMonad/Actions/CycleWS.hs

@@ -122,7 +122,7 @@ import XMonad.Util.WorkspaceCompare
 -- >            windows . view $ t                                         )
 --
 -- For detailed instructions on editing your key bindings, see
--- "XMonad.Doc.Extending#Editing_key_bindings".
+-- <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.
 --
 -- When using the toggle functions, in order to ensure that the workspace
 -- to which you switch is the previously viewed workspace, use the

XMonad/Actions/CycleWindows.hs

@@ -79,7 +79,7 @@ import Control.Arrow (second)
 --
 -- Also, if you use focus follows mouse, you will want to read the section
 -- on updating the mouse pointer below.  For detailed instructions on
--- editing your key bindings, see "XMonad.Doc.Extending#Editing_key_bindings".
+-- editing your key bindings, see <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.
 {- $pointer
 With FocusFollowsMouse == True, the focus is updated after binding
 actions, possibly focusing a window you didn't intend to focus. Most

XMonad/Actions/DeManage.hs

@@ -48,7 +48,7 @@ import XMonad
 -- > , ((modm,               xK_d     ), withFocused demanage)
 --
 -- For detailed instructions on editing your key bindings, see
--- "XMonad.Doc.Extending#Editing_key_bindings".
+-- <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.
 
 -- | Stop managing the currently focused window.
 demanage :: Window -> X ()

XMonad/Actions/DwmPromote.hs

@@ -40,7 +40,7 @@ import qualified Data.List.NonEmpty as NE
 -- >   , ((modm,               xK_Return), dwmpromote)
 --
 -- For detailed instructions on editing your key bindings, see
--- "XMonad.Doc.Extending#Editing_key_bindings".
+-- <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.
 
 -- | Swap the focused window with the master window. If focus is in
 --   the master, swap it with the next window in the stack. Focus

XMonad/Actions/DynamicProjects.hs

@@ -113,7 +113,7 @@ import qualified XMonad.Util.ExtensibleState as XS
 -- >  , ((modm, xK_slash), shiftToProjectPrompt def)
 --
 -- For detailed instructions on editing your key bindings, see
--- "XMonad.Doc.Extending#Editing_key_bindings".
+-- <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.
 
 --------------------------------------------------------------------------------
 type ProjectName  = String

XMonad/Actions/DynamicWorkspaces.hs

@@ -75,7 +75,7 @@ import qualified XMonad.Util.ExtensibleState as XS
 -- >    zip (zip (repeat (modm .|. controlMask)) [xK_1..xK_9]) (map (setWorkspaceIndex) [1..])
 --
 -- For detailed instructions on editing your key bindings, see
--- "XMonad.Doc.Extending#Editing_key_bindings". See also the documentation for
+-- <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>. See also the documentation for
 -- "XMonad.Actions.CopyWindow", 'windows', 'shift', and 'XPConfig'.
 
 type WorkspaceTag = String

XMonad/Actions/FindEmptyWorkspace.hs

@@ -38,7 +38,7 @@ import XMonad.StackSet
 -- will tag the current window to an empty workspace and view it.
 --
 -- For detailed instructions on editing your key bindings, see
--- "XMonad.Doc.Extending#Editing_key_bindings".
+-- <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.
 
 -- | Find the first hidden empty workspace in a StackSet. Returns
 -- Nothing if all workspaces are in use. Function searches currently

XMonad/Actions/FloatKeys.hs

@@ -19,11 +19,15 @@ module XMonad.Actions.FloatKeys (
                 keysMoveWindowTo,
                 keysResizeWindow,
                 keysAbsResizeWindow,
+                directionMoveWindow,
+                directionResizeWindow,
+                Direction2D(..),
                 P, G, ChangeDim
                 ) where
 
 import XMonad
 import XMonad.Prelude (fi)
+import XMonad.Util.Types
 
 -- $usage
 -- You can use this module with the following in your @~\/.xmonad\/xmonad.hs@:
@@ -38,8 +42,36 @@ import XMonad.Prelude (fi)
 -- >  , ((modm .|. shiftMask, xK_s     ), withFocused (keysAbsResizeWindow (10,10) (1024,752)))
 -- >  , ((modm,               xK_a     ), withFocused (keysMoveWindowTo (512,384) (1%2,1%2)))
 --
+-- Using "XMonad.Util.EZConfig" syntax, we can easily build keybindings
+-- where @M-<arrow-keys>@ moves the currently focused window and
+-- @M-S-<arrow-keys>@ resizes it using 'directionMoveWindow' and
+-- 'directionResizeWindow':
+--
+-- > [ ("M-" <> m <> k, withFocused $ f i)
+-- > | (i, k) <- zip [U, D, R, L] ["<Up>", "<Down>", "<Right>", "<Left>"]
+-- > , (f, m) <- [(directionMoveWindow 10, ""), (directionResizeWindow 10, "S-")]
+-- > ]
+--
 -- For detailed instructions on editing your key bindings, see
--- "XMonad.Doc.Extending#Editing_key_bindings".
+-- <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.
+
+-- | @directionMoveWindow delta dir win@ moves the window @win@ by
+--   @delta@ pixels in direction @dir@.
+directionMoveWindow :: Int -> Direction2D -> Window -> X ()
+directionMoveWindow delta dir win = case dir of
+  U -> keysMoveWindow (0, -delta) win
+  D -> keysMoveWindow (0, delta)  win
+  R -> keysMoveWindow (delta, 0)  win
+  L -> keysMoveWindow (-delta, 0) win
+
+-- | @directionResizeWindow delta dir win@ resizes the window @win@ by
+--   @delta@ pixels in direction @dir@.
+directionResizeWindow :: Int -> Direction2D -> Window -> X ()
+directionResizeWindow delta dir win = case dir of
+  U -> keysResizeWindow (0, -delta) (0, 0) win
+  D -> keysResizeWindow (0, delta)  (0, 0) win
+  R -> keysResizeWindow (delta, 0)  (0, 0) win
+  L -> keysResizeWindow (-delta, 0) (0, 0) win
 
 -- | @keysMoveWindow (dx, dy)@ moves the window by @dx@ pixels to the
 --   right and @dy@ pixels down.

XMonad/Actions/FloatSnap.hs

@@ -53,7 +53,7 @@ import XMonad.Actions.AfterDrag
 -- >        , ((modm .|. shiftMask, xK_Down),  withFocused $ snapGrow D Nothing)
 --
 -- For detailed instructions on editing your key bindings, see
--- "XMonad.Doc.Extending#Editing_key_bindings".
+-- <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.
 --
 -- And possibly add appropriate mouse bindings, for example:
 --

XMonad/Actions/FocusNth.hs

@@ -36,7 +36,7 @@ import XMonad.StackSet
 -- >     | (i, k) <- zip [0 .. 8] [xK_1 ..]]
 --
 -- For detailed instructions on editing your key bindings, see
--- "XMonad.Doc.Extending#Editing_key_bindings".
+-- <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.
 
 -- | Give focus to the nth window of the current workspace.
 focusNth :: Int -> X ()

XMonad/Actions/LinkWorkspaces.hs

@@ -58,7 +58,7 @@ import qualified Data.Map as M
 -- >       , (i, k) <- zip (XMonad.workspaces conf) [xK_1 .. xK_9]]
 --
 -- For detailed instructions on editing your key bindings, see
--- "XMonad.Doc.Extending#Editing_key_bindings".
+-- <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.
 
 data MessageConfig = MessageConfig {  messageFunction :: ScreenId -> [Char] -> [Char] -> [Char] -> X()
                     , foreground :: [Char]

XMonad/Actions/MouseResize.hs

@@ -50,9 +50,9 @@ import XMonad.Util.XUtils
 --
 -- > main = xmonad def { layoutHook = myLayout }
 --
--- For more detailed instructions on editing the layoutHook see:
---
--- "XMonad.Doc.Extending#Editing_the_layout_hook"
+-- For more detailed instructions on editing the layoutHook see
+-- <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial> and
+-- "XMonad.Doc.Extending#Editing_the_layout_hook".
 
 mouseResize :: l a -> ModifiedLayout MouseResize l a
 mouseResize = ModifiedLayout (MR [])

XMonad/Actions/Navigation2D.hs

@@ -97,7 +97,15 @@ import XMonad.Util.Types
 -- >                              False
 -- >               $ def
 --
--- Alternatively, you can use navigation2DP:
+-- /NOTE/: the @def@ argument to 'navigation2D' contains the strategy
+-- that decides which windows actually get selected.  While the default
+-- behaviour tries to keep them into account, if you use modules that
+-- influence tiling in some way, like "XMonad.Layout.Spacing" or
+-- "XMonad.Layout.Gaps", you should think about using a different
+-- strategy, if you find the default behaviour to be unnatural.  Check
+-- out the [finer points](#g:Finer_Points) below for more information.
+--
+-- Alternatively to 'navigation2D', you can use 'navigation2DP':
 --
 -- > main = xmonad $ navigation2DP def
 -- >                               ("<Up>", "<Left>", "<Down>", "<Right>")
@@ -107,7 +115,7 @@ import XMonad.Util.Types
 -- >               $ def
 --
 -- That's it. If instead you'd like more control, you can combine
--- withNavigation2DConfig and additionalNav2DKeys or additionalNav2DKeysP:
+-- 'withNavigation2DConfig' and 'additionalNav2DKeys' or 'additionalNav2DKeysP':
 --
 -- > main = xmonad $ withNavigation2DConfig def
 -- >               $ additionalNav2DKeys (xK_Up, xK_Left, xK_Down, xK_Right)
@@ -161,7 +169,7 @@ import XMonad.Util.Types
 --
 -- For detailed instruction on editing the key binding see:
 --
--- "XMonad.Doc.Extending#Editing_key_bindings".
+-- <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.
 
 -- $finer_points
 -- #Finer_Points#
@@ -178,9 +186,19 @@ import XMonad.Util.Types
 -- values in the above example to 'True'.  You could also decide you want
 -- wrapping only for a subset of the operations and no wrapping for others.
 --
--- By default, all layouts use the 'defaultTiledNavigation' strategy specified
--- in the 'Navigation2DConfig' (by default, line navigation is used).  To
--- override this behaviour for some layouts, add a pair (\"layout name\",
+-- By default, all layouts use the 'defaultTiledNavigation' strategy
+-- specified in the 'Navigation2DConfig' (by default, line navigation is
+-- used).  Many more navigation strategies are available; some may feel
+-- more natural, depending on the layout and user:
+--
+--   * 'lineNavigation'
+--   * 'centerNavigation'
+--   * 'sideNavigation'
+--   * 'sideNavigationWithBias'
+--
+-- There is also the ability to combine two strategies with 'hybridOf'.
+--
+-- To override the default behaviour for some layouts, add a pair (\"layout name\",
 -- navigation strategy) to the 'layoutNavigation' list in the
 -- 'Navigation2DConfig', where \"layout name\" is the string reported by the
 -- layout's description method (normally what is shown as the layout name in
@@ -326,7 +344,7 @@ centerNavigation = N 2 doCenterNavigation
 -- and push it to the right until it intersects with at least one other window.
 -- Of those windows, one with a point that is the closest to the centre of the
 -- line (+1) is selected. This is probably the most intuitive strategy for the
--- tiled layer when using XMonad.Layout.Spacing.
+-- tiled layer when using "XMonad.Layout.Spacing".
 sideNavigation :: Navigation2D
 sideNavigation = N 1 (doSideNavigationWithBias 1)
 
@@ -446,7 +464,7 @@ withNavigation2DConfig conf2d xconf = xconf { startupHook  = startupHook xconf
                                             }
 
 instance Default Navigation2DConfig where
-    def                   = Navigation2DConfig { defaultTiledNavigation = lineNavigation
+    def                   = Navigation2DConfig { defaultTiledNavigation = hybridOf lineNavigation sideNavigation
                                                , floatNavigation        = centerNavigation
                                                , screenNavigation       = lineNavigation
                                                , layoutNavigation       = []

XMonad/Actions/OnScreen.hs

@@ -183,4 +183,4 @@ toggleOrView' f i st = fromMaybe (f i st) $ do
 -- where 0 is the first screen and \"1\" the workspace with the tag \"1\".
 --
 -- For detailed instructions on editing your key bindings, see
--- "XMonad.Doc.Extending#Editing_key_bindings".
+-- <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.

XMonad/Actions/PerLayoutKeys.hs

@@ -32,7 +32,7 @@ import XMonad.StackSet as S
 -- >   ,((0, xK_F2), bindByLayout [("Tall", spawn "rxvt"), ("Mirror Tall", spawn "xeyes"), ("", spawn "xmessage hello")])
 --
 -- For detailed instructions on editing your key bindings, see
--- "XMonad.Doc.Extending#Editing_key_bindings".
+-- <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.
 
 -- | Uses supplied function to decide which action to run depending on current layout name.
 chooseActionByLayout :: (String->X()) -> X()

XMonad/Actions/PerWindowKeys.hs

@@ -41,7 +41,7 @@ import XMonad
 -- doThisIfTheOthersFail)]@.
 --
 -- For detailed instructions on editing your key bindings, see
--- "XMonad.Doc.Extending#Editing_key_bindings".
+-- <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.
 
 -- | Run an action if a Query holds true. Doesn't stop at the first one that
 -- does, however, and could potentially run all actions.

XMonad/Actions/PerWorkspaceKeys.hs

@@ -32,7 +32,7 @@ import XMonad.StackSet as S
 -- >   ,((0, xK_F2), bindOn [("1", spawn "rxvt"), ("2", spawn "xeyes"), ("", spawn "xmessage hello")])
 --
 -- For detailed instructions on editing your key bindings, see
--- "XMonad.Doc.Extending#Editing_key_bindings".
+-- <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.
 
 -- | Uses supplied function to decide which action to run depending on current workspace name.
 chooseAction :: (String->X()) -> X()

XMonad/Actions/PhysicalScreens.hs

@@ -65,7 +65,7 @@ Example usage in your @~\/.xmonad\/xmonad.hs@ file:
 >     , (f, mask) <- [(viewScreen def, 0), (sendToScreen def, shiftMask)]]
 
 For detailed instructions on editing your key bindings, see
-"XMonad.Doc.Extending#Editing_key_bindings".
+<https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.
  -}
 
 -- | The type of the index of a screen by location

XMonad/Actions/Plane.hs

@@ -59,7 +59,7 @@ import XMonad.Util.Run
 -- > myNewKeys (XConfig {modMask = modm}) = planeKeys modm (Lines 3) Finite
 --
 -- For detailed instructions on editing your key bindings, see
--- "XMonad.Doc.Extending#Editing_key_bindings".
+-- <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.
 
 -- | Direction to go in the plane.
 data Direction =  ToLeft | ToUp | ToRight | ToDown deriving Enum

XMonad/Actions/Promote.hs

@@ -37,7 +37,7 @@ import XMonad.StackSet
 -- >   , ((modm,               xK_Return), promote)
 --
 -- For detailed instructions on editing your key bindings, see
--- "XMonad.Doc.Extending#Editing_key_bindings".
+-- <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.
 
 -- | Move the focused window to the master pane. All other windows
 --   retain their order. If focus is in the master, swap it with the

XMonad/Actions/RotSlaves.hs

@@ -39,7 +39,7 @@ import XMonad.Prelude
 -- TwoPane layout (see "XMonad.Layout.TwoPane").
 --
 -- For detailed instructions on editing your key bindings, see
--- "XMonad.Doc.Extending#Editing_key_bindings".
+-- <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.
 
 -- | Rotate the windows in the current stack, excluding the first one
 --   (master).

XMonad/Actions/SimpleDate.hs

@@ -35,7 +35,7 @@ import XMonad.Util.Run
 -- In this example, a popup date menu will now be bound to @mod-d@.
 --
 -- For detailed instructions on editing your key bindings, see
--- "XMonad.Doc.Extending#Editing_key_bindings".
+-- <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.
 
 date :: X ()
 date = unsafeSpawn "(date; sleep 10) | dzen2"

XMonad/Actions/SinkAll.hs

@@ -32,4 +32,4 @@ import XMonad.Actions.WithAll (sinkAll)
 -- >   , ((modm .|. shiftMask, xK_t), sinkAll)
 --
 -- For detailed instructions on editing your key bindings, see
--- "XMonad.Doc.Extending#Editing_key_bindings".
+-- <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.

XMonad/Actions/SpawnOn.hs

@@ -63,7 +63,7 @@ import XMonad.Util.Process (getPPIDChain)
 -- the spawned application(e.g. float or resize it).
 --
 -- For detailed instructions on editing your key bindings, see
--- "XMonad.Doc.Extending#Editing_key_bindings".
+-- <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.
 
 newtype Spawner = Spawner {pidsRef :: [(ProcessID, ManageHook)]}
 

XMonad/Actions/Submap.hs

@@ -56,7 +56,7 @@ because that is a special value passed to XGrabKey() and not an actual
 modifier.
 
 For detailed instructions on editing your key bindings, see
-"XMonad.Doc.Extending#Editing_key_bindings".
+<https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.
 
 -}
 

XMonad/Actions/SwapWorkspaces.hs

@@ -44,7 +44,7 @@ import XMonad.Util.WorkspaceCompare
 -- will swap workspaces 1 and 5.
 --
 -- For detailed instructions on editing your key bindings, see
--- "XMonad.Doc.Extending#Editing_key_bindings".
+-- <https://xmonad.org/TUTORIAL.html#customizing-xmonad the tutorial>.
 
 -- | Swaps the currently focused workspace with the given workspace tag, via
 --   @swapWorkspaces@.