[doc] update module documentation

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:

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 <https://github.com/psf/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 <interval>``! It is still possible to
 override the module’s interval using ``-p <module>.interval=<value>``,
 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", [<list of module IDs>], 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

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"