summaryrefslogtreecommitdiffhomepage
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/plugins.org301
1 files changed, 152 insertions, 149 deletions
diff --git a/doc/plugins.org b/doc/plugins.org
index a1fa4df..907d59f 100644
--- a/doc/plugins.org
+++ b/doc/plugins.org
@@ -1,35 +1,37 @@
* System Monitor Plugins
-This is the description of the system monitor plugins available in
-xmobar. Some of them are only installed when an optional build option is
-set: we mention that fact, when needed, in their description.
-
-Each monitor has an =alias= to be used in the output template. Monitors
-may have default aliases, see the documentation of the monitor in
-question.
-
-There are two types of arguments: ones that all monitors share (the so
-called /default monitor arguments/) and arguments that are specific to a
-certain monitor.
-
-All Monitors accept a common set of arguments, described below in
-[[Default Monitor Arguments]]. Some monitors also accept additional options
-that are specific to them. When specifying the list of arguments in your
-configuration, the common options come first, followed by =--=, followed
-by any monitor-specific options. For example, the following [[=Battery Args RefreshRate=][Battery]]
-configuration first sets the global =template= and =Low= arguments and
-then specifies the battery-specific =off= option.
-
-#+begin_src haskell
- Run Battery
- [ "--template", "<acstatus>"
- , "--Low" , "15"
- -- battery specific options start here.
- , "--"
- , "--off" , "<left> (<timeleft>)"
- ]
- 100
-#+end_src
+ This is the description of the system monitor plugins available in
+ xmobar. Some of them are only installed when an optional build
+ option is set: we mention that fact, when needed, in their
+ description.
+
+ Each monitor has an =alias= to be used in the output
+ template. Monitors may have default aliases, see the documentation
+ of the monitor in question.
+
+ There are two types of arguments: ones that all monitors share (the
+ so called /default monitor arguments/) and arguments that are specific
+ to a certain monitor.
+
+ All Monitors accept a common set of arguments, described below in
+ [[Default Monitor Arguments]]. Some monitors also accept additional
+ options that are specific to them. When specifying the list of
+ arguments in your configuration, the common options come first,
+ followed by =--=, followed by any monitor-specific options. For
+ example, the following [[=Battery Args RefreshRate=][Battery]] configuration first sets the global
+ =template= and =Low= arguments and then specifies the battery-specific
+ =off= option.
+
+ #+begin_src haskell
+ Run Battery
+ [ "--template", "<acstatus>"
+ , "--Low" , "15"
+ -- battery specific options start here.
+ , "--"
+ , "--off" , "<left> (<timeleft>)"
+ ]
+ 100
+ #+end_src
** Icon Patterns
@@ -1260,8 +1262,8 @@ something like:
* Interfacing with Window Managers
-Listed below are ways to interface xmobar with your window manager of
-choice.
+ Listed below are ways to interface xmobar with your window manager
+ of choice.
** Property-based Logging
*** =XMonadLog=
@@ -1438,9 +1440,9 @@ choice.
** 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.
+ 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=
@@ -1482,69 +1484,70 @@ more performant to use shared memory. The following plugins leverage
* Executing External Commands
-In order to execute an external command you can either write the command
-name in the template, in this case it will be executed without
-arguments, or you can configure it in the "commands" configuration
-option list with the Com template command:
+ In order to execute an external command you can either write the
+ command name in the template, in this case it will be executed
+ without arguments, or you can configure it in the "commands"
+ configuration option list with the Com template command:
-=Com ProgramName Args Alias RefreshRate=
+ =Com ProgramName Args Alias RefreshRate=
-- ProgramName: the name of the program
-- Args: the arguments to be passed to the program at execution time
-- RefreshRate: number of tenths of second between re-runs of the
- command. A zero or negative rate means that the command will be
- executed only once.
-- Alias: a name to be used in the template. If the alias is en empty
- string the program name can be used in the template.
+ - ProgramName: the name of the program
+ - Args: the arguments to be passed to the program at execution time
+ - RefreshRate: number of tenths of second between re-runs of the
+ command. A zero or negative rate means that the command will be
+ executed only once.
+ - Alias: a name to be used in the template. If the alias is en empty
+ string the program name can be used in the template.
-E.g.:
+ E.g.:
-#+begin_src haskell
- Run Com "uname" ["-s","-r"] "" 0
-#+end_src
+ #+begin_src haskell
+ Run Com "uname" ["-s","-r"] "" 0
+ #+end_src
-can be used in the output template as =%uname%= (and xmobar will call
-/uname/ only once), while
+ can be used in the output template as =%uname%= (and xmobar will call
+ /uname/ only once), while
-#+begin_src haskell
- Run Com "date" ["+\"%a %b %_d %H:%M\""] "mydate" 600
-#+end_src
+ #+begin_src haskell
+ Run Com "date" ["+\"%a %b %_d %H:%M\""] "mydate" 600
+ #+end_src
-can be used in the output template as =%mydate%=.
+ can be used in the output template as =%mydate%=.
-Sometimes, you don't mind if the command executed exits with an error,
-or you might want to display a custom message in that case. To that end,
-you can use the =ComX= variant:
+ Sometimes, you don't mind if the command executed exits with an
+ error, or you might want to display a custom message in that
+ case. To that end, you can use the =ComX= variant:
-=ComX ProgramName Args ExitMessage Alias RefreshRate=
+ =ComX ProgramName Args ExitMessage Alias RefreshRate=
-Works like =Com=, but displaying =ExitMessage= (a string) if the
-execution fails. For instance:
+ Works like =Com=, but displaying =ExitMessage= (a string) if the
+ execution fails. For instance:
-#+begin_src haskell
- Run ComX "date" ["+\"%a %b %_d %H:%M\""] "N/A" "mydate" 600
-#+end_src
+ #+begin_src haskell
+ Run ComX "date" ["+\"%a %b %_d %H:%M\""] "N/A" "mydate" 600
+ #+end_src
-will display "N/A" if for some reason the =date= invocation fails.
+ will display "N/A" if for some reason the =date= invocation fails.
* The DBus Interface
-When compiled with the optional =with_dbus= flag, xmobar can be
-controlled over dbus. All signals defined in [[https://github.com/jaor/xmobar/blob/master/src/Xmobar/System/Signal.hs][src/Signal.hs]] as =data
-SignalType= can now be sent over dbus to xmobar. Due to current
-limitations of the implementation only one process of xmobar can acquire
-the dbus. This is handled on a first-come-first-served basis, meaning
-that the first process will get the dbus interface. Other processes will
-run without further problems, yet have no dbus interface.
+ When compiled with the optional =with_dbus= flag, xmobar can be
+ controlled over dbus. All signals defined in [[https://github.com/jaor/xmobar/blob/master/src/Xmobar/System/Signal.hs][src/Signal.hs]] as =data
+ SignalType= can now be sent over dbus to xmobar. Due to current
+ limitations of the implementation only one process of xmobar can
+ acquire the dbus. This is handled on a first-come-first-served
+ basis, meaning that the first process will get the dbus
+ interface. Other processes will run without further problems, yet
+ have no dbus interface.
-- Bus Name: =org.Xmobar.Control=
-- Object Path: =/org/Xmobar/Control=
-- Member Name: Any of SignalType, e.g. =string:Reveal=
-- Interface Name: =org.Xmobar.Control=
+ - Bus Name: =org.Xmobar.Control=
+ - Object Path: =/org/Xmobar/Control=
+ - Member Name: Any of SignalType, e.g. =string:Reveal=
+ - Interface Name: =org.Xmobar.Control=
-An example using the =dbus-send= command line utility:
+ An example using the =dbus-send= command line utility:
-#+begin_src shell
+ #+begin_src shell
dbus-send \
--session \
--dest=org.Xmobar.Control \
@@ -1553,82 +1556,82 @@ An example using the =dbus-send= command line utility:
'/org/Xmobar/Control' \
org.Xmobar.Control.SendSignal \
"string:Toggle 0"
-#+end_src
+ #+end_src
-It is also possible to send multiple signals at once:
+ It is also possible to send multiple signals at once:
-#+begin_src shell
- # send to another screen, reveal and toggle the persistent flag
- dbus-send [..] \
- "string:ChangeScreen 0" "string:Reveal 0" "string:TogglePersistent"
-#+end_src
+ #+begin_src shell
+ # send to another screen, reveal and toggle the persistent flag
+ dbus-send [..] \
+ "string:ChangeScreen 0" "string:Reveal 0" "string:TogglePersistent"
+ #+end_src
-The =Toggle=, =Reveal=, and =Hide= signals take an additional integer
-argument that denotes an initial delay, in tenths of a second, before
-the command takes effect.
+ The =Toggle=, =Reveal=, and =Hide= signals take an additional integer
+ argument that denotes an initial delay, in tenths of a second,
+ before the command takes effect.
** Example for using the DBus IPC interface with XMonad
-Bind the key which should {,un}map xmobar to a dummy value. This is
-necessary for {,un}grabKey in xmonad.
+ Bind the key which should {,un}map xmobar to a dummy value. This is
+ necessary for {,un}grabKey in xmonad.
-#+begin_src haskell
- ((0, xK_Alt_L), pure ())
-#+end_src
+ #+begin_src haskell
+ ((0, xK_Alt_L), pure ())
+ #+end_src
-Also, install =avoidStruts= layout modifier from
-=XMonad.Hooks.ManageDocks=
+ Also, install =avoidStruts= layout modifier from
+ =XMonad.Hooks.ManageDocks=
-Finally, install these two event hooks (=handleEventHook= in =XConfig=)
-=myDocksEventHook= is a replacement for =docksEventHook= which reacts on
-unmap events as well (which =docksEventHook= doesn't).
+ Finally, install these two event hooks (=handleEventHook= in =XConfig=)
+ =myDocksEventHook= is a replacement for =docksEventHook= which reacts
+ on unmap events as well (which =docksEventHook= doesn't).
-#+begin_src haskell
- import qualified XMonad.Util.ExtensibleState as XS
-
- data DockToggleTime = DTT { lastTime :: Time } deriving (Eq, Show, Typeable)
-
- instance ExtensionClass DockToggleTime where
- initialValue = DTT 0
-
- toggleDocksHook :: Int -> KeySym -> Event -> X All
- toggleDocksHook to ks ( KeyEvent { ev_event_display = d
- , ev_event_type = et
- , ev_keycode = ekc
- , ev_time = etime
- } ) =
- io (keysymToKeycode d ks) >>= toggleDocks >> return (All True)
- where
- toggleDocks kc
- | ekc == kc && et == keyPress = do
- safeSendSignal ["Reveal 0", "TogglePersistent"]
- XS.put ( DTT etime )
- | ekc == kc && et == keyRelease = do
- gap <- XS.gets ( (-) etime . lastTime )
- safeSendSignal [ "TogglePersistent"
- , "Hide " ++ show (if gap < 400 then to else 0)
- ]
- | otherwise = return ()
-
- safeSendSignal s = catchX (io $ sendSignal s) (return ())
- sendSignal = withSession . callSignal
- withSession mc = connectSession >>= \c -> callNoReply c mc >> disconnect c
- callSignal :: [String] -> MethodCall
- callSignal s = ( methodCall
- ( objectPath_ "/org/Xmobar/Control" )
- ( interfaceName_ "org.Xmobar.Control" )
- ( memberName_ "SendSignal" )
- ) { methodCallDestination = Just $ busName_ "org.Xmobar.Control"
- , methodCallBody = map toVariant s
- }
-
- toggleDocksHook _ _ _ = return (All True)
-
- myDocksEventHook :: Event -> X All
- myDocksEventHook e = do
- when (et == mapNotify || et == unmapNotify) $
- whenX ((not `fmap` (isClient w)) <&&> runQuery checkDock w) refresh
- return (All True)
- where w = ev_window e
- et = ev_event_type e
-#+end_src
+ #+begin_src haskell
+ import qualified XMonad.Util.ExtensibleState as XS
+
+ data DockToggleTime = DTT { lastTime :: Time } deriving (Eq, Show, Typeable)
+
+ instance ExtensionClass DockToggleTime where
+ initialValue = DTT 0
+
+ toggleDocksHook :: Int -> KeySym -> Event -> X All
+ toggleDocksHook to ks ( KeyEvent { ev_event_display = d
+ , ev_event_type = et
+ , ev_keycode = ekc
+ , ev_time = etime
+ } ) =
+ io (keysymToKeycode d ks) >>= toggleDocks >> return (All True)
+ where
+ toggleDocks kc
+ | ekc == kc && et == keyPress = do
+ safeSendSignal ["Reveal 0", "TogglePersistent"]
+ XS.put ( DTT etime )
+ | ekc == kc && et == keyRelease = do
+ gap <- XS.gets ( (-) etime . lastTime )
+ safeSendSignal [ "TogglePersistent"
+ , "Hide " ++ show (if gap < 400 then to else 0)
+ ]
+ | otherwise = return ()
+
+ safeSendSignal s = catchX (io $ sendSignal s) (return ())
+ sendSignal = withSession . callSignal
+ withSession mc = connectSession >>= \c -> callNoReply c mc >> disconnect c
+ callSignal :: [String] -> MethodCall
+ callSignal s = ( methodCall
+ ( objectPath_ "/org/Xmobar/Control" )
+ ( interfaceName_ "org.Xmobar.Control" )
+ ( memberName_ "SendSignal" )
+ ) { methodCallDestination = Just $ busName_ "org.Xmobar.Control"
+ , methodCallBody = map toVariant s
+ }
+
+ toggleDocksHook _ _ _ = return (All True)
+
+ myDocksEventHook :: Event -> X All
+ myDocksEventHook e = do
+ when (et == mapNotify || et == unmapNotify) $
+ whenX ((not `fmap` (isClient w)) <&&> runQuery checkDock w) refresh
+ return (All True)
+ where w = ev_window e
+ et = ev_event_type e
+ #+end_src