summaryrefslogtreecommitdiffhomepage
path: root/doc/plugins.org
diff options
context:
space:
mode:
authorjao <jao@gnu.org>2022-02-19 04:15:53 +0000
committerjao <jao@gnu.org>2022-02-19 04:17:02 +0000
commit679eb24da94b4c908a7e562a4587bab428f817ce (patch)
tree5d9d6547b93888e1bffed932d82b3e16c5aae081 /doc/plugins.org
parent2cf3f4d4dc08339aadc511b96a7627ddeb7a0836 (diff)
downloadxmobar-679eb24da94b4c908a7e562a4587bab428f817ce.tar.gz
xmobar-679eb24da94b4c908a7e562a4587bab428f817ce.tar.bz2
Interfacing with window managers: new doc file
Diffstat (limited to 'doc/plugins.org')
-rw-r--r--doc/plugins.org229
1 files changed, 4 insertions, 225 deletions
diff --git a/doc/plugins.org b/doc/plugins.org
index 0d61b5f..052ff6f 100644
--- a/doc/plugins.org
+++ b/doc/plugins.org
@@ -35,6 +35,10 @@
100
#+end_src
+ See also [[./window-managers.org][Interfacing with window managers]] for a collection of
+ plugins that let you interact and control xmobar from window
+ managers.
+
*** Icon Patterns
Some monitors allow usage of strings that depend on some integer
@@ -1274,231 +1278,6 @@
Run UVMeter "Brisbane" ["-H", "3", "-L", "3", "--low", "green", "--high", "red"] 900
#+end_src
-* 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 =<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!
-
- #+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:
-
- #+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 = "<icon=" ++ path ++ "/>"
-
- xpm :: String -> String
- xpm = icon . (++ ".xpm")
- #+end_src
-
* Executing External Commands
In order to execute an external command you can either write the