From 8d80b375a30d7530ce5c52554c3577f9694c240e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luk=C3=A1=C5=A1=20Mand=C3=A1k?= Date: Sat, 6 Jun 2015 14:15:48 +0200 Subject: [PATCH 1/5] Module: Added `hints` setting that allows the user to add additional i3bar protocol blocks to module's output. --- i3pystatus/core/modules.py | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/i3pystatus/core/modules.py b/i3pystatus/core/modules.py index 9a848a2..946dbae 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 (string)"), ('on_upscroll', "Callback called on scrolling up (string)"), ('on_downscroll', "Callback called on scrolling down (string)"), + ('hints', "Additional hints for module. TODO"), ) on_leftclick = None @@ -20,6 +21,12 @@ class Module(SettingsBase): on_upscroll = None on_downscroll = None + hints = None + """ + TODO + `min_width`, `align`, `separator`, `separator_block_width` + """ + def registered(self, status_handler): """Called when this module is registered with a status handler""" @@ -30,6 +37,9 @@ class Module(SettingsBase): self.output["instance"] = str(id(self)) if (self.output.get("color", "") or "").lower() == "#ffffff": del self.output["color"] + if self.hints: + h = {i: self.hints[i] for i in self.hints if i not in self.output} + self.output.update(h) json.insert(convert_position(self.position, json), self.output) def run(self): From 040b765b5d0a8912f95669d85fb106f58133d7de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luk=C3=A1=C5=A1=20Mand=C3=A1k?= Date: Sat, 6 Jun 2015 18:17:38 +0200 Subject: [PATCH 2/5] Module: Replaced list comprehension for better code readability. --- i3pystatus/core/modules.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/i3pystatus/core/modules.py b/i3pystatus/core/modules.py index 946dbae..9d55d8b 100644 --- a/i3pystatus/core/modules.py +++ b/i3pystatus/core/modules.py @@ -38,8 +38,9 @@ class Module(SettingsBase): if (self.output.get("color", "") or "").lower() == "#ffffff": del self.output["color"] if self.hints: - h = {i: self.hints[i] for i in self.hints if i not in self.output} - self.output.update(h) + for key, val in self.hints.items(): + if key not in self.output: + self.output.update({key: val}) json.insert(convert_position(self.position, json), self.output) def run(self): From 3d0142b74d9822f1f24c143c15f6fb5cd9957c3c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luk=C3=A1=C5=A1=20Mand=C3=A1k?= Date: Fri, 12 Jun 2015 17:38:34 +0200 Subject: [PATCH 3/5] Module: Added docs for hints. Module: All modules now set `"markup": "none"` by default to prevent from #181. Module: is now replacing ampersands with "&" if output is to be parsed by pango. --- i3pystatus/core/modules.py | 39 ++++++++++++++++++++++++++++++++++---- 1 file changed, 35 insertions(+), 4 deletions(-) diff --git a/i3pystatus/core/modules.py b/i3pystatus/core/modules.py index 9d55d8b..c6290ac 100644 --- a/i3pystatus/core/modules.py +++ b/i3pystatus/core/modules.py @@ -13,7 +13,7 @@ class Module(SettingsBase): ('on_rightclick', "Callback called on right click (string)"), ('on_upscroll', "Callback called on scrolling up (string)"), ('on_downscroll', "Callback called on scrolling down (string)"), - ('hints', "Additional hints for module. TODO"), + ('hints', "Additional output blocks for module output (dict)"), ) on_leftclick = None @@ -21,10 +21,26 @@ class Module(SettingsBase): on_upscroll = None on_downscroll = None - hints = None + hints = {"markup": "none"} """ - TODO - `min_width`, `align`, `separator`, `separator_block_width` + A dictionary containing additional output blocks used to customize output of + a module. + + Blocks will be applied only if `self.output` does not contain a block with + the same name already. + + All blocks are described in i3bar protocol documentation located at + http://i3wm.org/docs/i3bar-protocol.html#_blocks_in_detail. + It is recommended to use only the following blocks: + + * `min_width` and `align` blocks are used to set minimal width of output and + text aligment if text width is shorter than minimal width. + * `separator` and `separator_block_width` blocks are used to remove the + vertical bar that is separating modules. + * `markup` block can be set to `"none"` or `"pango"`. + Pango is a markup language providing additional formatting options + to advanced users. + """ def registered(self, status_handler): @@ -41,6 +57,9 @@ class Module(SettingsBase): 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): @@ -112,6 +131,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 = ( From 0267454557cb6b0d14bfd95fd1ef9a36a54fbe5d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luk=C3=A1=C5=A1=20Mand=C3=A1k?= Date: Thu, 18 Jun 2015 20:39:28 +0200 Subject: [PATCH 4/5] Module: Add hyperlinks to hints docstring. --- i3pystatus/core/modules.py | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/i3pystatus/core/modules.py b/i3pystatus/core/modules.py index c6290ac..8f7e408 100644 --- a/i3pystatus/core/modules.py +++ b/i3pystatus/core/modules.py @@ -29,17 +29,18 @@ class Module(SettingsBase): Blocks will be applied only if `self.output` does not contain a block with the same name already. - All blocks are described in i3bar protocol documentation located at - http://i3wm.org/docs/i3bar-protocol.html#_blocks_in_detail. - It is recommended to use only the following blocks: + All blocks are described in `i3bar protocol documentation + `_ + but it is recommended to use only the following blocks: * `min_width` and `align` blocks are used to set minimal width of output and text aligment if text width is shorter than minimal width. * `separator` and `separator_block_width` blocks are used to remove the vertical bar that is separating modules. * `markup` block can be set to `"none"` or `"pango"`. - Pango is a markup language providing additional formatting options - to advanced users. + `Pango markup + `_ + provides additional formatting options for advanced users. """ From b501d22ad94ec098d554db015a7d9f66949ceab2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luk=C3=A1=C5=A1=20Mand=C3=A1k?= Date: Fri, 19 Jun 2015 22:27:16 +0200 Subject: [PATCH 5/5] Moved `hints` documentation to Configuration section. Added a few basic examples. --- docs/configuration.rst | 69 ++++++++++++++++++++++++++++++++++++++ i3pystatus/core/modules.py | 23 +------------ 2 files changed, 70 insertions(+), 22 deletions(-) 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 859c7b9..4c8fa54 100644 --- a/i3pystatus/core/modules.py +++ b/i3pystatus/core/modules.py @@ -13,7 +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 (dict)"), + ('hints', "Additional output blocks for module output (see :ref:`hints`)"), ) on_leftclick = None @@ -22,27 +22,6 @@ class Module(SettingsBase): on_downscroll = None hints = {"markup": "none"} - """ - A dictionary containing additional output blocks used to customize output of - a module. - - Blocks will be applied only if `self.output` does not contain a block with - the same name already. - - All blocks are described in `i3bar protocol documentation - `_ - but it is recommended to use only the following blocks: - - * `min_width` and `align` blocks are used to set minimal width of output and - text aligment if text width is shorter than minimal width. - * `separator` and `separator_block_width` blocks are used to remove the - vertical bar that is separating modules. - * `markup` block can be set to `"none"` or `"pango"`. - `Pango markup - `_ - provides additional formatting options for advanced users. - - """ def registered(self, status_handler): """Called when this module is registered with a status handler"""