From 1d25be20599f33aeae548165041536c2017dae96 Mon Sep 17 00:00:00 2001 From: tobi-wan-kenobi Date: Sat, 9 May 2020 15:31:25 +0200 Subject: [PATCH] [doc] update module documentation --- core/decorators.py | 4 +-- docs/development/module.rst | 64 +++++++++++++++++++++++++++++------ tests/core/test_decorators.py | 8 ++--- 3 files changed, 58 insertions(+), 18 deletions(-) diff --git a/core/decorators.py b/core/decorators.py index 76cb9c8..8c87308 100644 --- a/core/decorators.py +++ b/core/decorators.py @@ -33,9 +33,7 @@ def scrollable(func): widget.set("scrolling.direction", "right") widget.set("__content__", text) - width = widget.get( - "theme.width", util.format.asint(module.parameter("width", 30)) - ) + width = util.format.asint(module.parameter("scrolling.width", 30)) if util.format.asbool(module.parameter("scrolling.makewide", True)): widget.set("theme.minwidth", "A" * width) if width < 0 or len(text) <= width: diff --git a/docs/development/module.rst b/docs/development/module.rst index 6c1a6b5..e14cc83 100644 --- a/docs/development/module.rst +++ b/docs/development/module.rst @@ -33,6 +33,8 @@ to this): - Please favour single quotes for strings (except for docstrings, which are always """) - For private methods/variables, please use a leading ``__`` (e.g. ``__output`` rather than ``_output``) +For anything else, please run your code through `black `_. + Hello world ----------- @@ -88,8 +90,8 @@ If you want to add widgets during runtime, please use the TODO: expand on this -Periodic updates ----------------- +Periodic updates (update() vs. full_text) +----------------------------------------- ``bumblebee-status`` modules have two different ways to update their data: 1. Each interval, the callback registered when the widget was @@ -153,13 +155,53 @@ what the user configures via ``-i ``! It is still possible to override the module’s interval using ``-p .interval=``, however. -TODOs ------ +Redraw outside the update interval +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sometimes, it is desirable to redraw a widget dynamically, even outside its update +interva. This can be useful if the value to be displayed is calculated in a separate +thread. In such a scenario, the ``update()`` method would simply trigger of a thread +and the actual value would be available later (but presumably before the next +update call). + +If that is the case, it is possible to fire off an event in the thread to cause the +affected widget to be redrawn, like this: + +.. code:: python + + import core.event + + # later + core.event.trigger("update", [], redraw_only=True) + +A concrete example of this can be found in the module ``redshift``, and a couple of others. + +Scrolling content +~~~~~~~~~~~~~~~~~ + +If a widgets produces a large amount of content, it might be desirable to limit the amount +of space the widget can occupy and scroll the content, if necessary. + +This behaviour can be achieved using the ``scrollable`` decorator like this: + +.. code:: python + + import core.module + import core.widget + import core.decorators + + class Module(core.module.Module): + def __init__(self, config, theme): + super().__init__(config, theme, core.widget.Widget(self.description)) + + @core.decorators.scrollable + def description(self, widget): + pass # TODO: implement + +There are a couple of parameters that can be set on the affected module, either in the +module using ``self.set()`` or via the CLI using the ``--parameter`` flag: + +- ``scrolling.width``: Integer, defaults to 30, determines the minimum width of the widgets, if ``makewide`` is specified +- ``scrolling.makewide``: Boolean, defaults to true, determines whether the widgets should be expanded to their minwidth + ``scrolling.bounce``: Boolean, defaults to true, determines whether the content should change directions when a scroll is completed, or just marquee through -- default update interval -- scrolling -- theme.minwidth -- scrolling decorator -- theme.exclude -- per module update interval -> nice string format -- update via events diff --git a/tests/core/test_decorators.py b/tests/core/test_decorators.py index fb2878d..9ad7986 100644 --- a/tests/core/test_decorators.py +++ b/tests/core/test_decorators.py @@ -22,7 +22,7 @@ class config(unittest.TestCase): self.module = TestModule() self.widget = self.module.widget() self.width = 10 - self.module.set("width", self.width) + self.module.set("scrolling.width", self.width) def test_no_text(self): self.assertEqual("", self.module.text) @@ -40,7 +40,7 @@ class config(unittest.TestCase): def test_bounce(self): self.module.text = "abcd" - self.module.set("width", 2) + self.module.set("scrolling.width", 2) self.assertEqual("ab", self.module.get(self.widget)) self.assertEqual("bc", self.module.get(self.widget)) self.assertEqual("cd", self.module.get(self.widget)) @@ -54,7 +54,7 @@ class config(unittest.TestCase): def test_nobounce(self): self.module.set("scrolling.bounce", False) self.module.text = "abcd" - self.module.set("width", 2) + self.module.set("scrolling.width", 2) self.assertEqual("ab", self.module.get(self.widget)) self.assertEqual("bc", self.module.get(self.widget)) self.assertEqual("cd", self.module.get(self.widget)) @@ -64,7 +64,7 @@ class config(unittest.TestCase): def test_changed_data(self): self.module.text = "abcd" - self.module.set("width", 2) + self.module.set("scrolling.width", 2) self.assertEqual("ab", self.module.get(self.widget)) self.assertEqual("bc", self.module.get(self.widget)) self.module.text = "wxyz"