diff options
| -rw-r--r-- | doc/plugins.org | 236 |
1 files changed, 128 insertions, 108 deletions
diff --git a/doc/plugins.org b/doc/plugins.org index 99a850b..0516b67 100644 --- a/doc/plugins.org +++ b/doc/plugins.org @@ -1264,158 +1264,178 @@ and not new individual messages. Listed below are ways to interface xmobar with your window manager of choice. -** =XMonadLog= +** Property-based Logging +*** =XMonadLog= -- Aliases to 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. + - 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 + #+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. + 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= +*** =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 =<raw=…>=) or - remove tags from dynamic text that you pipe through to xmobar in this - way. + - 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 =<raw=…>=) 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! + - 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 - <action=`xdotool key alt+1`>ws1</action> <action=`xdotool key alt+1`>ws2</action> - #+end_src + #+begin_src shell + <action=`xdotool key alt+1`>ws1</action> <action=`xdotool key alt+1`>ws2</action> + #+end_src -- If you use xmonad, It is advised that you still use =xmobarStrip= for - the =ppTitle= in your logHook: + - 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 + #+begin_src haskell + myPP = defaultPP { ppTitle = xmobarStrip } + main = xmonad $ def + { logHook = dynamicLogString myPP >>= xmonadPropLog + } + #+end_src -** =StdinReader= +*** =XPropertyLog PropName= -- 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. + - 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. -** =UnsafeStdinReader= +*** =UnsafeXPropertyLog PropName= -- 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=! + - 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. -** =CommandReader "/path/to/program" Alias= +*** =UnsafeStdinReader= -- Runs the given program, and displays its standard output. + - 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=! -** =PipeReader "default text:/path/to/pipe" Alias= +** 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= + - 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= +*** =MarqueePipeReader "default text:/path/to/pipe" (length, rate, sep) Alias= -- Generally equivalent to PipeReader + - Generally equivalent to PipeReader -- Text is displayed as marquee with the specified length, rate in 10th - seconds and separator when it wraps around + - 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 + #+begin_src haskell + Run MarqueePipeReader "/tmp/testpipe" (10, 7, "+") "mpipe" + #+end_src -- Expands environment variables in the first argument + - Expands environment variables in the first argument -** =BufferedPipeReader Alias [(Timeout, Bool, "/path/to/pipe1"), ..]= +*** =BufferedPipeReader Alias [(Timeout, Bool, "/path/to/pipe1"), ..]= -- Display data from multiple pipes. + - 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. + - 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= + - 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. + - 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: + - 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 + #+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. + 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]] + - Take a look at [[http://github.com/jaor/xmobar/raw/master/examples/status.sh][examples/status.sh]] -- Expands environment variables for the pipe path + - Expands environment variables for the pipe path -** =HandleReader Handle Alias= +** Handle-based Logging +*** =HandleReader Handle Alias= -- Display data from a Haskell =Handle= + - Display data from a Haskell =Handle= -- This plugin is only useful if you are running xmobar from another - Haskell program like XMonad. + - 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: + - 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 + #+begin_src haskell + (readHandle, writeHandle) <- createPipe + xmobarProcess <- forkProcess $ xmobar myConfig + { commands = + Run (HandleReader readHandle "handle") : commands myConfig + } + hPutStr writeHandle "Hello World" + #+end_src * Executing External Commands |