[doc] add dev documentation on widget states

fixes #651

bumblebee_status/modules/contrib/amixer.py

@@ -6,7 +6,7 @@ Parameters:
 
 contributed by `zetxx <https://github.com/zetxx>`_ - many thanks!
 
-input handling contributed by `ardadem <https://github.com/ardadem>_ - many thanks!
+input handling contributed by `ardadem <https://github.com/ardadem>`_ - many thanks!
 """
 import re
 

docs/development/module.rst

@@ -1,5 +1,5 @@
-How to write a new module
-=========================
+How to write a module
+=====================
 
 Introduction
 ------------
@@ -104,6 +104,51 @@ observations: - If you want to change the widgets a module has, you
 **have** to stick with ``update()`` - For simple modules, doing the data
 update in the widget callback is simplest (see ``kernel``, for example)
 
+Widget states
+-------------
+
+Each widget inside a module can have a list of states (for example, two
+predefined states are ``warning`` and ``critical``). States define how
+a widget is rendered (i.e. which fields in the theme file are selected to
+draw it.
+
+Somewhat paradoxically, to give a **widget** a state, a method called
+``def state(self, widget)`` has to be defined on the **module**. The
+reason for this is that the module typically contains all of the statefulness,
+so assumedly, it's easier to determine the state of a widget from the
+module, rather than from the module itself.
+
+The ``state()`` method simply returns a list of strings, which make up
+the state this particular widget has.
+
+The themeing code then iterates these states and selects the matching
+theme information from the theme file. This, it does by performing a "best match"
+search through the theme, like this:
+
+- Is there a theme definition for the **module** that in turn contains a JSON object
+  for the **state**? If so, use that (for example: ``"cpu": { "critical": { "fg": "#ff0000" } }``)
+- If not, is there a theme definition inside the ``defaults`` or ``cycle`` theme entries?
+
+For more details on that, please refer to `How to write a theme <theme.rst>`_
+
+If multiple states match on the "same level", the last state in the state list is used.
+For example, if a module returns ``[ "critical", "warning" ]`` as state, typically, the
+widget will be drawn as ``warning``.
+
+One important helper method is ``def threshold_state(value, warning, critical)``, which each
+module possesses. Using that, it is very easy to define warning and critical states when the
+widget represents a simple numeric value.
+
+Sounds confusing? An example will clarify: Let's say your widget returns a percentage (disk
+usage, or CPU usage). The widget should be marked as "warning" when the percentage is above
+50, and as "critical", if it is above 90. This, you would do like this:
+
+.. code-block:: python
+
+  def state(self, widget):
+      return self.threshold_state(self.__value, 50, 90)
+
+
 Advanced topics
 ---------------
 

docs/development/theme.rst

@@ -1,4 +1,4 @@
-How to write a new theme
+How to write a theme
 ========================
 
 Introduction

docs/modules.rst

@@ -149,18 +149,6 @@ Parameters:
 
 .. image:: ../screenshots/ping.png
 
-playerctl
-~~~~~~~~~~
-Displays information about the current song in vlc, audacious, bmp, xmms2, spotify and others
-
-Requires the following executable:
-    * playerctl
-
-contributed by `smitajit <https://github.com/smitajit>`_ - many thanks!
-
-.. image:: ../screenshots/playerctl.png
-
-
 pulseaudio
 ~~~~~~~~~~
 
@@ -301,7 +289,7 @@ Parameters:
 
 contributed by `zetxx <https://github.com/zetxx>`_ - many thanks!
 
-input handling contributed by `ardadem <https://github.com/ardadem>_ - many thanks!
+input handling contributed by `ardadem <https://github.com/ardadem>`_ - many thanks!
 
 .. image:: ../screenshots/amixer.png
 
@@ -918,6 +906,18 @@ Parameters:
 
 contributed by `bbernhard <https://github.com/bbernhard>`_ - many thanks!
 
+playerctl
+~~~~~~~~~
+
+Displays information about the current song in vlc, audacious, bmp, xmms2, spotify and others
+
+Requires the following executable:
+    * playerctl
+
+contributed by `smitajit <https://github.com/smitajit>`_ - many thanks!
+
+.. image:: ../screenshots/playerctl.png
+
 pomodoro
 ~~~~~~~~
 
@@ -1039,7 +1039,7 @@ Execute command in shell and print result
 
 Few command examples:
     'ping -c 1 1.1.1.1 | grep -Po '(?<=time=)\d+(\.\d+)? ms''
-    'echo 'BTC=$(curl -s rate.sx/1BTC | grep -Po '^\d+')USD''
+    'echo 'BTC=$(curl -s rate.sx/1BTC | grep -Po \'^\d+\')USD''
     'curl -s https://wttr.in/London?format=%l+%t+%h+%w'
     'pip3 freeze | wc -l'
     'any_custom_script.sh | grep arguments'