From 679eb24da94b4c908a7e562a4587bab428f817ce Mon Sep 17 00:00:00 2001 From: jao Date: Sat, 19 Feb 2022 04:15:53 +0000 Subject: Interfacing with window managers: new doc file --- doc/window-managers.org | 224 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 224 insertions(+) create mode 100644 doc/window-managers.org (limited to 'doc/window-managers.org') diff --git a/doc/window-managers.org b/doc/window-managers.org new file mode 100644 index 0000000..3a194c8 --- /dev/null +++ b/doc/window-managers.org @@ -0,0 +1,224 @@ +#+title: Interfacing with window managers + +Listed below are ways to interface xmobar with your window manager of +choice. + +*** Property-based Logging +***** =XMonadLog= + + - Aliases to XMonadLog + + - Displays information from xmonad's =_XMONAD_LOG=. You can use + this by using functions from the [[https://hackage.haskell.org/package/xmonad-contrib-0.16/docs/XMonad-Hooks-DynamicLog.html][XMonad.Hooks.DynamicLog]] + module. By using the =xmonadPropLog= function in your logHook, + you can write the the above property. The following shows a + minimal xmonad configuration that spawns xmobar and then + writes to the =_XMONAD_LOG= property. + + #+begin_src haskell + main = do + spawn "xmobar" + xmonad $ def + { logHook = dynamicLogString defaultPP >>= xmonadPropLog + } + #+end_src + + This plugin can be used as a sometimes more convenient + alternative to =StdinReader=. For instance, it allows you to + (re)start xmobar outside xmonad. + +***** =UnsafeXMonadLog= + + - Aliases to UnsafeXMonadLog + - Displays any text received by xmobar on the =_XMONAD_LOG= atom. + - Will not do anything to the text received. This means you can pass + xmobar dynamic actions. Be careful to escape (using ==) or + remove tags from dynamic text that you pipe through to xmobar in this + way. + + - Sample usage: Send the list of your workspaces, enclosed by actions + tags, to xmobar. This enables you to switch to a workspace when you + click on it in xmobar! + + #+begin_src shell + ws1 ws2 + #+end_src + + - If you use xmonad, It is advised that you still use =xmobarStrip= for + the =ppTitle= in your logHook: + + #+begin_src haskell + myPP = defaultPP { ppTitle = xmobarStrip } + main = xmonad $ def + { logHook = dynamicLogString myPP >>= xmonadPropLog + } + #+end_src + +***** =XPropertyLog PropName= + + - Aliases to =PropName= + - Reads the X property named by =PropName= (a string) and displays its + value. The [[https://github.com/jaor/xmobar/raw/master/examples/xmonadpropwrite.hs][examples/xmonadpropwrite.hs script]] in xmobar's distribution + can be used to set the given property from the output of any other + program or script. + +***** =UnsafeXPropertyLog PropName= + + - Aliases to =PropName= + - Same as =XPropertyLog= but the input is not filtered to avoid + injection of actions (cf. =UnsafeXMonadLog=). The program writing the + value of the read property is responsible of performing any needed + cleanups. + +***** =NamedXPropertyLog PropName Alias= + + - Aliases to =Alias= + - Same as =XPropertyLog= but a custom alias can be specified. + +***** =UnsafeNamedXPropertyLog PropName Alias= + + - Aliases to =Alias= + - Same as =UnsafeXPropertyLog=, but a custom alias can be specified. + +*** Logging via Stdin +***** =StdinReader= + + - Aliases to StdinReader + - Displays any text received by xmobar on its standard input. + - Strips actions from the text received. This means you can't pass + dynamic actions via stdin. This is safer than =UnsafeStdinReader= + because there is no need to escape the content before passing it to + xmobar's standard input. + +***** =UnsafeStdinReader= + + - Aliases to UnsafeStdinReader + - Displays any text received by xmobar on its standard input. + - Similar to [[=UnsafeXMonadLog=][UnsafeXMonadLog]], in the sense that it does not strip any + actions from the received text, only using =stdin= and not a property + atom of the root window. Please be equally carefully when using this + as when using =UnsafeXMonadLog=! + +*** Pipe-based Logging +***** =PipeReader "default text:/path/to/pipe" Alias= + + - Reads its displayed output from the given pipe. + - Prefix an optional default text separated by a colon + - Expands environment variables in the first argument of syntax =${VAR}= + or =$VAR= + +***** =MarqueePipeReader "default text:/path/to/pipe" (length, rate, sep) Alias= + + - Generally equivalent to PipeReader + + - Text is displayed as marquee with the specified length, rate in 10th + seconds and separator when it wraps around + + #+begin_src haskell + Run MarqueePipeReader "/tmp/testpipe" (10, 7, "+") "mpipe" + #+end_src + + - Expands environment variables in the first argument + +***** =BufferedPipeReader Alias [(Timeout, Bool, "/path/to/pipe1"), ..]= + + - Display data from multiple pipes. + + - Timeout (in tenth of seconds) is the value after which the + previous content is restored i.e. if there was already + something from a previous pipe it will be put on display + again, overwriting the current status. + + - A pipe with Timeout of 0 will be displayed permanently, just + like =PipeReader= + + - The boolean option indicates whether new data for this pipe + should make xmobar appear (unhide, reveal). In this case, the + Timeout additionally specifies when the window should be + hidden again. The output is restored in any case. + + - Use it for OSD-like status bars e.g. for setting the volume or + brightness: + + #+begin_src haskell + Run BufferedPipeReader "bpr" + [ ( 0, False, "/tmp/xmobar_window" ) + , ( 15, True, "/tmp/xmobar_status" ) + ] + #+end_src + + Have your window manager send window titles to + =/tmp/xmobar_window=. They will always be shown and not reveal + your xmobar. Sending some status information to + =/tmp/xmobar_status= will reveal xmonad for 1.5 seconds and + temporarily overwrite the window titles. + + - Take a look at [[http://github.com/jaor/xmobar/raw/master/examples/status.sh][examples/status.sh]] + + - Expands environment variables for the pipe path + +*** Handle-based Logging +***** =HandleReader Handle Alias= + + - Display data from a Haskell =Handle= + + - This plugin is only useful if you are running xmobar from another + Haskell program like XMonad. + + - You can use =System.Process.createPipe= to create a pair of =read= & + =write= Handles. Pass the =read= Handle to HandleReader and write your + output to the =write= Handle: + + #+begin_src haskell + (readHandle, writeHandle) <- createPipe + xmobarProcess <- forkProcess $ xmobar myConfig + { commands = + Run (HandleReader readHandle "handle") : commands myConfig + } + hPutStr writeHandle "Hello World" + #+end_src + +*** Software Transactional Memory + + When invoking xmobar from other Haskell code it can be easier and + more performant to use shared memory. The following plugins + leverage =Control.Concurrent.STM= to realize these gains for xmobar. + +***** =QueueReader (TQueue a) (a -> String) String= + + - Display data from a Haskell =TQueue a=. + + - This plugin is only useful if you are running xmobar from another + haskell program like xmonad. + + - You should make an =IO= safe =TQueue a= with + =Control.Concurrent.STM.newTQueueIO=. Write to it from the user + code with =writeTQueue=, and read with =readTQueue=. A common use + is to overwite =ppOutput= from =XMonad.Hooks.DynamicLog= as shown + below. + + #+begin_src haskell + main :: IO () + main = do + q <- STM.newTQueueIO @String + bar <- forkIO $ xmobar myConf + { commands = Run (QueueReader q id "XMonadLog") : commands myConf } + xmonad $ def { logHook = logWorkspacesToQueue q } + + logWorkspacesToQueue :: STM.TQueue String -> X () + logWorkspacesToQueue q = + dynamicLogWithPP def { ppOutput = STM.atomically . STM.writeTQueue q } + where + -- Manage the PrettyPrinting configuration here. + ppLayout' :: String -> String + ppLayout' "Spacing Tall" = xpm "layout-spacing-tall" + ppLayout' "Spacing Mirror Tall" = xpm "layout-spacing-mirror" + ppLayout' "Spacing Full" = xpm "layout-full" + ppLayout' x = x + + icon :: String -> String + icon path = "" + + xpm :: String -> String + xpm = icon . (++ ".xpm") + #+end_src -- cgit v1.2.3