summaryrefslogtreecommitdiffhomepage
path: root/doc/plugins.org
diff options
context:
space:
mode:
Diffstat (limited to 'doc/plugins.org')
-rw-r--r--doc/plugins.org236
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