diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/accordion.gif | bin | 0 -> 71898 bytes | |||
| -rw-r--r-- | doc/plugins.org | 105 | ||||
| -rw-r--r-- | doc/quick-start.org | 16 | ||||
| -rw-r--r-- | doc/using-haskell.org | 18 |
4 files changed, 114 insertions, 25 deletions
diff --git a/doc/accordion.gif b/doc/accordion.gif Binary files differnew file mode 100644 index 0000000..c21d2b0 --- /dev/null +++ b/doc/accordion.gif diff --git a/doc/plugins.org b/doc/plugins.org index 2199659..6f474e1 100644 --- a/doc/plugins.org +++ b/doc/plugins.org @@ -16,11 +16,11 @@ to a certain monitor. All Monitors accept a common set of arguments, described below in - [[Default Monitor Arguments]]. Some monitors also accept additional + [[#default-arguments][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 + example, the following [[#batteryp-dirs-args-refreshrate][Battery]] configuration first sets the global =template= and =Low= arguments and then specifies the battery-specific =off= option. @@ -60,6 +60,9 @@ brightness value. ** Default monitor arguments + :PROPERTIES: + :CUSTOM_ID: default-arguments + :END: These are the options available for all monitors: @@ -694,18 +697,37 @@ #+begin_src haskell Run Brightness ["-t", "<bar>"] 60 #+end_src + *** =Locks= - Displays the status of Caps Lock, Num Lock and Scroll Lock. - Aliases to =locks= + - Contructors: + + - =Locks= is nullary and uses the strings =CAPS=, =NUM=, =SCROLL= to signal + that a lock is enabled (and empty strings to signal it's disabled) + + - =Locks'= allow customizing the strings for the enabled/disabled states + of the 3 locks by accepting an assoc list of type =[(String, (String, String))]=, + which is expected to contain exactly 3 elements with keys + ="CAPS"=, ="NUM"=, ="SCROLL"=. + - Example: #+begin_src haskell + -- using default labels Run Locks #+end_src + #+begin_src haskell + -- using custom labels + Run $ Locks' [("CAPS" , ("<fc=#00ff00>\xf023</fc>", "<fc=#777777>\xf09c</fc>") ) + ,("NUM" , ("<fc=#777777>\xf047</fc>", "<fc=#00ff00>\xf047</fc>" ) ) + ,("SCROLL", ("SlOCK", "" ))] + #+end_src + ** Load and Process monitors *** =Load Args RefreshRate= @@ -814,6 +836,9 @@ ** Volume monitors *** =Volume Mixer Element Args RefreshRate= + :PROPERTIES: + :CUSTOM_ID: volume + :END: - Aliases to the mixer name and element name separated by a colon. Thus, =Volume "default" "Master" [] 10= can be used as @@ -889,7 +914,7 @@ *** =Alsa Mixer Element Args= - Like [[=Volume Mixer Element Args RefreshRate=][Volume]] but with the following differences: + Like [[#volume][Volume]] but with the following differences: - Uses event-based refreshing via =alsactl monitor= instead of polling, so it will refresh instantly when there's a volume change, and won't @@ -1243,9 +1268,11 @@ - Works in the same way as =Weather=, but takes an additional argument, a list of pairs from sky conditions to their replacement (typically a unicode string or an icon specification). - - Use the variable =skyConditionS= to display the replacement of the - corresponding sky condition. All other =Weather= template variables - are available as well. + - Use the variable =skyConditionS= or =weatherS= to display the replacement of + the corresponding sky condition. =weatherS= uses the string returned by + =weather= to look up a replacement, and, if that one is not found, it + looks up the value of =skyConditionS=. All other =Weather= template + variables are available as well. For example: @@ -1296,7 +1323,7 @@ #+begin_src haskell Run UVMeter "Brisbane" ["-H", "3", "-L", "3", "--low", "green", "--high", "red"] 900 #+end_src -** Other monitors +** Other monitors and plugins *** =CatInt n filename= - Reads and displays an integer from the file whose path is =filename= @@ -1326,6 +1353,59 @@ the display of those numeric fields. - Default template: =Up: <days>d <hours>h <minutes>m= +*** =PacmanUpdates (Zero, One, Many, Error) Rate= + + - Aliases to =pacman= + - =Zero=: a =String= to use when the system is up to date. + - =One=: a =String= to use when only one update is available. + - =Many=: a =String= to use when several updates are available; it can contain + a =?= character as a placeholder for the number of updates. + - =Error=: a =String= to use when pacman fails for unkown reasons (e.g. + network error) + - Example: + #+begin_src haskell + ArchUpdates ("<fc=green>up to date</fc>", + "<fc=yellow>1 update</fc>, + "<fc=red>? updates</fc>", + "<fc=red>!Pacman Error!</fc>") + 600 + #+end_src + +*** =ArchUpdates (Zero, One, Many) Rate= + + - *This plugin is deprecated. Use =PacmanUpdates= instead.* + - Aliases to =arch= + - Same As: + #+begin_src haskell + PacmanUpdates (Zero, + One, + Many, + "pacman: Unknown cause of failure.") + Rate + #+end_src + +*** =makeAccordion Tuning [Runnable]= + + - Wraps other =Runnable= plugins and makes them all collapsible to a single string: + + [[file:accordion.gif]] + + - Aliases to =alias' tuning=, being =tuning= of type =Tuning=, so one can use multiple such "accordions" + - **Disclaimer**: This only works for Haskell =xmobar.hs= + - =Tuning=: the "settings", for which a default value is provided, + #+begin_src haskell + defaultTuning = Tuning { + alias' = "accordion" + , initial = True + , expand = "<>" + , shrink = "><" + } + #+end_src + - =expand=: =String= shown when the accordion is contracted (defaults to ="<>"=). + - =shrink=: =String= shown when the accordion is expanded (defaults to ="><"=). + - =initial=: =Bool= to tell whether the accordion is initially expanded (defaults to =True=). + - =[Runnable]=: a list of =Runnable= plugins + * Interfacing with window managers :PROPERTIES: :CUSTOM_ID: interfacing-with-window-managers @@ -1355,6 +1435,9 @@ (re)start xmobar outside xmonad. *** =UnsafeXMonadLog= + :PROPERTIES: + :CUSTOM_ID: UnsafeXMonadLog + :END: - Aliases to UnsafeXMonadLog - Displays any text received by xmobar on the =_XMONAD_LOG= atom. @@ -1385,7 +1468,7 @@ - Aliases to =PropName= - Reads the X property named by =PropName= (a string) and displays its - value. The [[../etc/xmonadpropwrite.hs][etc/xmonadpropwrite.hs script]] in xmobar's distribution can be + value. The [[https://codeberg.org/xmobar/xmobar/src/branch/master/etc/xmonadpropwrite.hs][etc/xmonadpropwrite.hs script]] in xmobar's distribution can be used to set the given property from the output of any other program or script. @@ -1421,7 +1504,7 @@ - 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 + - 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=! @@ -1480,7 +1563,7 @@ =/tmp/xmobar_status= will reveal xmonad for 1.5 seconds and temporarily overwrite the window titles. - - Take a look at [[../etc/status.sh][etc/status.sh]] + - Take a look at [[https://codeberg.org/xmobar/xmobar/src/branch/master/etc/status.sh][etc/status.sh]] - Expands environment variables for the pipe path @@ -1547,8 +1630,6 @@ xmonad configuration (=xmonad.hs=), e.g. by using a custom =~/.xmonad/build= script. - - * Executing external commands In order to execute an external command you can either write the diff --git a/doc/quick-start.org b/doc/quick-start.org index 3f381fe..fecd953 100644 --- a/doc/quick-start.org +++ b/doc/quick-start.org @@ -1,10 +1,10 @@ #+title: Quick start: using xmobar -Xmobar can either be configured using the configuration language, or [[file:using-haskell.org][used as a +Xmobar can either be configured using the configuration language, or [[https://codeberg.org/xmobar/xmobar/src/branch/master/doc/using-haskell.org][used as a Haskell library]] (similar to xmonad) and compiled with your specific configuration. For an example of a configuration file using the plain -configuration language, see [[../etc/xmobar.config][etc/xmobar.config]], and you can have a look at -[[../etc/xmobar.hs][etc/xmobar.hs]] for an example of how to write your own xmobar using Haskell. +configuration language, see [[https://codeberg.org/xmobar/xmobar/src/branch/master/etc/xmobar.config][etc/xmobar.config]], and you can have a look at +[[https://codeberg.org/xmobar/xmobar/src/branch/master/etc/xmobar.hs][etc/xmobar.hs]] for an example of how to write your own xmobar using Haskell. * Command line options @@ -314,7 +314,7 @@ configuration language, see [[../etc/xmobar.config][etc/xmobar.config]], and you *** Commands and monitors - =commands= The list of monitors and plugins to run, together with their - individual configurations. The [[./plugins.org][plugin documentation]] details all the + individual configurations. The [[https://codeberg.org/xmobar/xmobar/src/branch/master/doc/plugins.org][plugin documentation]] details all the available monitors, and you can also create new ones using Haskell. See the [[#commands-list][commands list section]] below for more. @@ -381,7 +381,7 @@ configuration language, see [[../etc/xmobar.config][etc/xmobar.config]], and you will parse the template and search for the command to be executed in the =commands= configuration option. First an =alias= will be searched (some plugins, such as =Weather= or =Network=, have default - aliases, see the [[./plugins.org][plugin documentation]]). After that, the command + aliases, see the [[https://codeberg.org/xmobar/xmobar/src/branch/master/doc/plugins.org][plugin documentation]]). After that, the command name will be tried. If a command is found, the arguments specified in the =commands= list will be used. @@ -585,7 +585,7 @@ configuration language, see [[../etc/xmobar.config][etc/xmobar.config]], and you Other options are ~Ansi~, ~Pango~, and ~Swaybar~. ** Showing xmobar output in Emacs tab or mode line Using xmobar's ANSI color text ouput, one can plug it inside Emacs, and - display your monitors in the mode line or the tab bar. The [[../etc/xmobar.el][xmobar.el + display your monitors in the mode line or the tab bar. The [[https://codeberg.org/xmobar/xmobar/src/branch/master/etc/xmobar.el][xmobar.el package]] provides a simple way of doing it. ** Using xmobar in wayland with swaybar or waybar :PROPERTIES: @@ -629,7 +629,7 @@ configuration language, see [[../etc/xmobar.config][etc/xmobar.config]], and you dynamically xmobar's size and run it alongside a system tray widget such as trayer or stalonetray (although the idea is not limited to trays, really). For your convenience, there is a version of Jonas' script in - [[../etc/padding-icon.sh][etc/padding-icon.sh]]. + [[https://codeberg.org/xmobar/xmobar/src/branch/master/etc/padding-icon.sh][etc/padding-icon.sh]]. ** Signal handling @@ -642,7 +642,7 @@ configuration language, see [[../etc/xmobar.config][etc/xmobar.config]], and you * The DBus interface When compiled with the optional =with_dbus= flag, xmobar can be controlled - over dbus. All signals defined in [[../src/Xmobar/System/Signal.hs][src/Signal.hs]] as =data SignalType= can now + over dbus. All signals defined in [[https://codeberg.org/xmobar/xmobar/src/branch/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 diff --git a/doc/using-haskell.org b/doc/using-haskell.org index 33228c7..9fd3d88 100644 --- a/doc/using-haskell.org +++ b/doc/using-haskell.org @@ -49,6 +49,14 @@ system-wide xmobar, it will notice that you have your own implementation and (re)compile and run it as needed. +* Using dynamic linking + + Setting the =with_shared= flag, which is off by default, enables (re)building + of xmobar with shared libraries. By default, =xmobar= rebuilds itself with + static linking, as is the common practice with Haskell programs, but some + distributions use dynamic linking in their packages, or you might also be so + inclined. If so, this is your flag. + * Writing a plugin :PROPERTIES: :CUSTOM_ID: writing-a-plugin @@ -75,8 +83,8 @@ =run= can be used for simpler plugins. If you define only =run= the plugin will be run every second. To overwrite this default you just need to implement =rate=, which must return the number of tenth of seconds between - every successive runs. See [[../etc/xmobar.hs][etc/xmobar.hs]] for an example of a plugin - that runs just once, and [[../src/Xmobar/Plugins/Date.hs][src/Xmobar/Plugins/Date.hs]] for one that + every successive runs. See [[https://codeberg.org/xmobar/xmobar/src/branch/master/etc/xmobar.hs][etc/xmobar.hs]] for an example of a plugin + that runs just once, and [[https://codeberg.org/xmobar/xmobar/src/branch/master/src/Xmobar/Plugins/Date.hs][src/Xmobar/Plugins/Date.hs]] for one that implements =rate=. Notice that Date could be implemented as: @@ -107,14 +115,14 @@ If your plugin only implements =alias= and =start=, then it is advisable to put it into the =Xmobar/Plugins/Monitors= directory and use one of the many - =run*= functions in [[../src/Xmobar/Plugins/Monitors/Common/Run.hs][Xmobar.Plugins.Monitors.Run]] in order to define - =start=. The =Exec= instance should then live in [[../src/Xmobar/Plugins/Monitors.hs][Xmobar.Plugins.Monitors]]. + =run*= functions in [[https://codeberg.org/xmobar/xmobar/src/branch/master/src/Xmobar/Plugins/Monitors/Common/Run.hs][Xmobar.Plugins.Monitors.Run]] in order to define + =start=. The =Exec= instance should then live in [[https://codeberg.org/xmobar/xmobar/src/branch/master/src/Xmobar/Plugins/Monitors.hs][Xmobar.Plugins.Monitors]]. * Using a plugin To use your new plugin, you just need to use a pure Haskell configuration for xmobar (as explained [[#xmobar-in-haskell][above]]) and load your definitions in your =xmobar.hs= - file. You can see an example in [[../etc/xmobar.hs][etc/xmobar.hs]] showing you how to write + file. You can see an example in [[https://codeberg.org/xmobar/xmobar/src/branch/master/etc/xmobar.hs][etc/xmobar.hs]] showing you how to write a Haskell configuration that uses a new plugin, all in one file. When xmobar runs with the full path to that Haskell file as its argument |
