From 1ebbfbae14d78eacba0da8caf30f167f24843041 Mon Sep 17 00:00:00 2001 From: tobi-wan-kenobi Date: Tue, 9 Jun 2020 20:45:54 +0200 Subject: [PATCH] [doc] add dev documentation on widget states fixes #651 --- bumblebee_status/modules/contrib/amixer.py | 2 +- docs/development/module.rst | 49 +++++++++++++++++++++- docs/development/theme.rst | 2 +- docs/modules.rst | 28 ++++++------- 4 files changed, 63 insertions(+), 18 deletions(-) diff --git a/bumblebee_status/modules/contrib/amixer.py b/bumblebee_status/modules/contrib/amixer.py index 9e3bb3d..4ab30f9 100644 --- a/bumblebee_status/modules/contrib/amixer.py +++ b/bumblebee_status/modules/contrib/amixer.py @@ -6,7 +6,7 @@ Parameters: contributed by `zetxx `_ - many thanks! -input handling contributed by `ardadem _ - many thanks! +input handling contributed by `ardadem `_ - many thanks! """ import re diff --git a/docs/development/module.rst b/docs/development/module.rst index 4a3f483..58b1156 100644 --- a/docs/development/module.rst +++ b/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 `_ + +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 --------------- diff --git a/docs/development/theme.rst b/docs/development/theme.rst index 1336a87..b42bb90 100644 --- a/docs/development/theme.rst +++ b/docs/development/theme.rst @@ -1,4 +1,4 @@ -How to write a new theme +How to write a theme ======================== Introduction diff --git a/docs/modules.rst b/docs/modules.rst index 3afc95d..ed99936 100644 --- a/docs/modules.rst +++ b/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 `_ - many thanks! - -.. image:: ../screenshots/playerctl.png - - pulseaudio ~~~~~~~~~~ @@ -301,7 +289,7 @@ Parameters: contributed by `zetxx `_ - many thanks! -input handling contributed by `ardadem _ - many thanks! +input handling contributed by `ardadem `_ - many thanks! .. image:: ../screenshots/amixer.png @@ -918,6 +906,18 @@ Parameters: contributed by `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 `_ - 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'