diff --git a/docs/configuration.rst b/docs/configuration.rst index fb47b96..fe02994 100644 --- a/docs/configuration.rst +++ b/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 +`_. + +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 + `_ + 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 = "{essid} {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": "", + "stop": "", + }, + ... + +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") diff --git a/i3pystatus/core/modules.py b/i3pystatus/core/modules.py index 7e355b0..4c8fa54 100644 --- a/i3pystatus/core/modules.py +++ b/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 = (