Merge pull request #220 from richese/hints

Added hints setting to Module.

docs/configuration.rst

@@ -298,3 +298,72 @@ The settings can be of different types, namely
   elements are passed as arguments to the callable
 - again a special case of the above: just a callable, no parameters
 - a string which is run in a shell
+
+.. _hints:
+
+Hints
+-----
+
+Hints are additional parameters used to customize output of a module.
+They give you access to all attributes supported by `i3bar protocol
+<http://i3wm.org/docs/i3bar-protocol.html#_blocks_in_detail>`_.
+
+Hints are available as ``hints`` setting in all modules and its value should be
+a dictionary or ``None``.
+An attribute defined in ``hints`` will be applied only if module output does not
+contain attribute with the same name already.
+
+Some possible uses for these attributes are:
+
+*   `min_width` and `align` can be used to set minimal width of output and
+    align the text if its width is shorter than `minimal_width`.
+*   `separator` and `separator_block_width` can be used to remove the
+    vertical bar that is separating modules.
+*   `markup` can be set to `"none"` or `"pango"`.
+    `Pango markup
+    <https://developer.gnome.org/pango/stable/PangoMarkupFormat.html>`_
+    provides additional formatting options for drawing rainbows and other
+    fancy stuff.
+
+Here is an example with the :py:class:`.Network` module.
+Pango markup is used to keep the ESSID green at all times while the
+recieved/sent part is changing color depending on the amount of traffic.
+
+  .. code:: python
+
+        status.register("network",
+            interface = "wlp2s0",
+            hints = {"markup": "pango"},
+            format_up = "<span color=\"#00FF00\">{essid}</span> {bytes_recv:6.1f}KiB {bytes_sent:5.1f}KiB",
+            format_down = "",
+            dynamic_color = True,
+            start_color = "#00FF00",
+            end_color = "#FF0000",
+            color_down = "#FF0000",
+            upper_limit = 800.0,
+            )
+
+Or you can use pango to customize the color of ``status`` setting in
+:py:class:`.NowPlaying` and :py:class:`.MPD` modules.
+
+    .. code:: python
+
+        ...
+        hints = {"markup": "pango"},
+        status = {
+            "play": "▶",
+            "pause": "<span color=\"orange\">▶</span>",
+            "stop": "<span color=\"red\">◾</span>",
+        },
+        ...
+
+Or make two modules look like one.
+
+    .. code:: python
+
+        status.register("text",
+            text = "shmentarianism is a pretty long word.")
+        status.register("text",
+            hints = {"separator": False, "separator_block_width": 0},
+            text = "Antidisestabli",
+            color="#FF0000")

i3pystatus/core/modules.py

@@ -13,6 +13,7 @@ class Module(SettingsBase):
         ('on_rightclick', "Callback called on right click (see :ref:`callbacks`)"),
         ('on_upscroll', "Callback called on scrolling up (see :ref:`callbacks`)"),
         ('on_downscroll', "Callback called on scrolling down (see :ref:`callbacks`)"),
+        ('hints', "Additional output blocks for module output (see :ref:`hints`)"),
     )
 
     on_leftclick = None
@@ -20,6 +21,8 @@ class Module(SettingsBase):
     on_upscroll = None
     on_downscroll = None
 
+    hints = {"markup": "none"}
+
     def registered(self, status_handler):
         """Called when this module is registered with a status handler"""
 
@@ -30,6 +33,13 @@ class Module(SettingsBase):
             self.output["instance"] = str(id(self))
             if (self.output.get("color", "") or "").lower() == "#ffffff":
                 del self.output["color"]
+            if self.hints:
+                for key, val in self.hints.items():
+                    if key not in self.output:
+                        self.output.update({key: val})
+            if self.output.get("markup") == "pango":
+                self.__text_to_pango()
+
             json.insert(convert_position(self.position, json), self.output)
 
     def run(self):
@@ -101,6 +111,18 @@ class Module(SettingsBase):
         self.position = position
         return self
 
+    def __text_to_pango(self):
+        """
+        Replaces all ampersands in `"full_text"` and `"short_text"` blocks` in
+        `self.output` with `&`.
+        """
+        if "full_text" in self.output.keys():
+            out = self.output["full_text"].replace("&", "&")
+            self.output.update({"full_text": out})
+        if "short_text" in self.output.keys():
+            out = self.output["short_text"].replace("&", "&")
+            self.output.update({"short_text": out})
+
 
 class IntervalModule(Module):
     settings = (