- version 0.8.9.26 (0.9-beta23)

- finalising calculated background color
- updating docs

Author: s-n-g

Changelog

@@ -1,5 +1,7 @@
-2022-08-14 s-n-g
+2022-08-28 s-n-g
     * version 0.8.9.26 (0.9-beta23)
+    * adding calculated messages windows color
+    * adding "Calculated Color" config option
     * Windows installation will try to install 7-Zip, if not
       already installed
 

README.html

@@ -101,6 +101,11 @@ <h2 id="table-of-contents">Table of Contents <span style="padding-left: 10px;"><
 <li><a href="#pyradio-themes">PyRadio Themes</a>
 <ul>
 <li><a href="#css-color-themes-restrictions">CSS color themes restrictions</a></li>
+<li><a href="#secondary-windows-background">Secondary windows background</a>
+<ul>
+<li><a href="#theme-defined-secondary-windows-color">Theme defined secondary windows color</a></li>
+<li><a href="#calculated-secondary-windows-color">Calculated secondary windows color</a></li>
+</ul></li>
 <li><a href="#user-themes">User themes</a>
 <ul>
 <li><a href="#converting-old-themes">Converting old themes</a></li>
@@ -174,8 +179,10 @@ <h2 id="requirements">Requirements <span style="padding-left: 10px;"><sup style=
 <h2 id="changelog">Changelog <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></span></h2>
 <pre style="height: 200px;">
 
-2022-08-14 s-n-g
+2022-08-28 s-n-g
     * version 0.8.9.26 (0.9-beta23)
+    * adding calculated messages windows color
+    * adding "Calculated Color" config option
     * Windows installation will try to install 7-Zip, if not
       already installed
 
@@ -1314,7 +1321,7 @@ <h2 id="pyradio-themes">PyRadio Themes <span style="padding-left: 10px;"><sup st
 # Message window border foreground and background.
 # The background color can be left unset.
 # Please refer to the following link for more info
-# https://github.com/coderholic/pyradio#calculated-colors
+# https://github.com/coderholic/pyradio#secondary-windows-background
 #
 Messages Border     #a3b367
 
@@ -1343,6 +1350,51 @@ <h3 id="css-color-themes-restrictions">CSS color themes restrictions</h3>
 <br />
 This means that, in order for a theme change to take full effect, <strong>PyRadio</strong> will have to be restarted.</p></li>
 </ol>
+<h3 id="secondary-windows-background">Secondary windows background</h3>
+<p>Secondary windows (such as messages, questions, the “<em>Theme Selection window</em>” the “<em>Encoding Selection window</em>”, etc.) originally use the same background color as the “<em>Main window</em>”.</p>
+<p>It is now possible to use a different background color for these windows, to get better visual result.</p>
+<p>There are two way to do that:</p>
+<ol type="1">
+<li><p>Defined in a theme</p></li>
+<li><p>Using a calculated color</p></li>
+</ol>
+<h4 id="theme-defined-secondary-windows-color">Theme defined secondary windows color</h4>
+<p>Themes have the following entry</p>
+<pre># Message window border foreground and background.
+# The background color can be left unset.
+# Please refer to the following link for more info
+# https://github.com/coderholic/pyradio#secondary-windows-background
+#
+Messages Border     #a3b367</pre>
+<p>It is possible to define a background color as well, like so</p>
+<pre>Messages Border     #a3b367 #F5DBDE</pre>
+<p>In this case, this color will be used as the Secondary Windows background color.</p>
+<p>Although one can use any color here, it is recommended to follow these guidelines for best visual result:</p>
+<ol type="1">
+<li>The color should be 1-20% lighter or darker than the “<em>Stations Background</em>” color setting of the theme.<br />
+<br />
+One can use <a target="_blank" href="http://www.workwithcolor.com/hsl-color-picker-01.htm">this page</a> (or a similar one) to insert the base color and adjust the “<em>L</em>” component as needed.<br />
+<br />
+A terminal alternative is <a target="_blank" href="https://github.com/sharkdp/pastel">pastel</a>, which can be used like so:</li>
+</ol>
+<pre>pastel color &#39;#fbf1f2&#39;              # show color info
+pastel lighten .1 &#39;#fbf1f2&#39;         # color lightened by 10%
+pastel darken .1 &#39;#fbf1f2&#39;          # color darkened by 10%</pre>
+<ol start="2" type="1">
+<li>If the “<em>Stations Background</em>” color is dark, create a lighter version of it; if it’s light, create a darker version of it.<br />
+<br />
+This is just a recomenration, though; just get a color that combines well with existing ones (border foreground, stations foreground and active station).</li>
+</ol>
+<p>This information is actually relevant to creating a new <strong>PyRadio</strong> theme, but it’s very important in order to understand how the calculated background color works.</p>
+<h4 id="calculated-secondary-windows-color">Calculated secondary windows color</h4>
+<p><strong>PyRadio</strong> will use the same background color for all windows by default, provided that the theme used does not define a “<em>Messages Border</em>” background color.</p>
+<p>In order to use a “<em>Messages Border</em>” background color different than the “<em>Stations background</em>” color, when “<em>Messages Border</em>” background color is not defined in the selected theme, a config option is available; “<strong>Calculated color</strong>”.</p>
+<p>This config option takes a value that’s between 0 and 0.2.</p>
+<p>If it is 0, no color change will occur.</p>
+<p>Otherwise, the value acts as a percentage (a <strong>factor</strong>), which indicates how much the luminance of the “<em>Stations background</em>” color will change to produce the new background color.</p>
+<p>This is how this works: <strong>PyRadio</strong> will calculate the “<em>Stations background</em>” color perceived brightness, which will indicate whether the color is dark or light. Then depending on that, will add or subtract <strong>factor</strong> percent from its luminance value.</p>
+<p>Finally, a check will be made to see if this color is close to “<em>Messages Border</em>” foreground color, and re-adjusted as possible.</p>
+<p style="margin: 1.5em 4em 0 4em; text-indent: -2.5em;"><strong>Note:</strong> When a calculated background color is used, pressing “<strong>~</strong>” (<strong>tilde</strong>) will toggle it on and off. This setting will be valid until <strong>PyRadio</strong> terminates, or a new theme is loaded.</p>
 <h3 id="user-themes">User themes</h3>
 <p>Users can easiliy create their own themes, using for example <a target="_blank" href="https://www.cssportal.com/css3-color-names/">CSS color names</a> as a resource, and</p>
 <ol type="1">

README.md

@@ -48,6 +48,9 @@ Ben Dowling - [https://github.com/coderholic](https://github.com/coderholic)
 * [Copying and pasting - Registers](#copying-and-pasting---registers)
 * [PyRadio Themes](#pyradio-themes)
     * [CSS color themes restrictions](#css-color-themes-restrictions)
+    * [Secondary windows background](#secondary-windows-background)
+        * [Theme defined secondary windows color](#theme-defined-secondary-windows-color)
+        * [Calculated secondary windows color](#calculated-secondary-windows-color)
     * [User themes](#user-themes)
         * [Converting old themes](#converting-old-themes)
     * [Using transparency](#using-transparency)
@@ -794,7 +797,7 @@ PyRadio URL         #a3b367
 # Message window border foreground and background.
 # The background color can be left unset.
 # Please refer to the following link for more info
-# https://github.com/coderholic/pyradio#calculated-colors
+# https://github.com/coderholic/pyradio#secondary-windows-background
 #
 Messages Border     #a3b367
 
@@ -832,6 +835,79 @@ These terminal will default to the old "**dark**" theme, displaying whatever col
 \
 This means that, in order for a theme change to take full effect, **PyRadio** will have to be restarted.
 
+### Secondary windows background
+
+Secondary windows (such as messages, questions, the "*Theme Selection window*" the "*Encoding Selection window*", etc.) originally use the same background color as the "*Main window*".
+
+It is now possible to use a different background color for these windows, to get better visual result.
+
+There are two way to do that:
+
+1. Defined in a theme
+
+2. Using a calculated color
+
+#### Theme defined secondary windows color
+
+Themes have the following entry
+
+```
+# Message window border foreground and background.
+# The background color can be left unset.
+# Please refer to the following link for more info
+# https://github.com/coderholic/pyradio#secondary-windows-background
+#
+Messages Border     #a3b367
+```
+
+It is possible to define a background color as well, like so
+
+
+```
+Messages Border     #a3b367 #F5DBDE
+```
+
+In this case, this color will be used as the Secondary Windows background color.
+
+Although one can use any color here, it is recommended to follow these guidelines for best visual result:
+
+1. The color should be 1-20% lighter or darker than the "*Stations Background*" color setting of the theme. \
+\
+One can use [this page](http://www.workwithcolor.com/hsl-color-picker-01.htm) (or a similar one) to insert the base color and adjust the "*L*" component as needed. \
+\
+A terminal alternative is [pastel](https://github.com/sharkdp/pastel), which can be used like so:
+
+```
+pastel color '#fbf1f2'              # show color info
+pastel lighten .1 '#fbf1f2'         # color lightened by 10%
+pastel darken .1 '#fbf1f2'          # color darkened by 10%
+```
+
+
+2. If the "*Stations Background*" color is dark, create a lighter version of it; if it's light, create a darker version of it. \
+\
+This is just a recomenration, though; just get a color that combines well with existing ones (border foreground, stations foreground and active station).
+
+This information is actually relevant to creating a new **PyRadio** theme, but it's very important in order to understand how the calculated background color works.
+
+#### Calculated secondary windows color
+
+**PyRadio** will use the same background color for all windows by default, provided that the theme used does not define a "*Messages Border*" background color.
+
+In order to use a "*Messages Border*" background color different than the "*Stations background*" color, when "*Messages Border*" background color is not defined in the selected theme, a config option is available; "**Calculated color**".
+
+This config option takes a value that's between 0 and 0.2.
+
+If it is 0, no color change will occur.
+
+Otherwise, the value acts as a percentage (a **factor**), which indicates how much the luminance of the "*Stations background*" color will change to produce the new background color.
+
+This is how this works: **PyRadio** will calculate the "*Stations background*" color perceived brightness, which will indicate whether the color is dark or light. Then depending on that, will add or subtract **factor** percent from its luminance value.
+
+Finally, a check will be made to see if this color is close to "*Messages Border*" foreground color, and re-adjusted as possible.
+
+**Note:** When a calculated background color is used, pressing "**~**" (**tilde**) will toggle it on and off. This setting will be valid until **PyRadio** terminates, or a new theme is loaded.
+
 ### User themes
 
 Users can easiliy create their own themes, using for example [CSS color names](https://www.cssportal.com/css3-color-names/) as a resource, and

pyradio.1

@@ -879,6 +879,104 @@ There are a couple of terminals (that I know of) which will permit changing thei
 
 This means that, in order for a theme change to take full effect, \fBpyradio\fR will have to be restarted.
 
+.RE
+.PP
+\fBSecondary windows background\fR
+
+Secondary windows (such as messages, questions, the \fITheme Selection window\fR the \fIEncoding Selection window\fR, etc.) originally use the same background color as the \fIMain window\fR.
+
+It is now possible to use a different background color for these windows, to get better visual result.
+
+There are two way to do that:
+
+.RS 3
+.IP 1. 3
+Defined in a theme
+
+.IP 2. 3
+Using a calculated color
+
+.PP
+\fBTheme defined secondary windows color \fR
+
+.RS 3
+Themes have the following entry
+
+.RS 3
+\fI# Message window border foreground and background.
+.br
+# The background color can be left unset.
+.br
+# Please refer to the following link for more info
+.br
+# https://github.com/coderholic/pyradio#secondary-windows-background
+.br
+#
+.br
+Messages Border     #a3b367\fR
+.RE
+
+It is possible to define a background color as well, like so
+
+.RS 3
+\fIMessages Border     #a3b367 #F5DBDE\fR
+.RE
+
+In this case, this color will be used as the \fISecondary Windows\fR background color.
+
+Although one can use any color here, it is recommended to follow these guidelines for best visual result:
+
+.RS 3
+.IP 1. 3
+The color should be 1-20% lighter or darker than the "*Stations Background*" color setting of the theme.
+
+One can use this page \fIhttp://www.workwithcolor.com/hsl-color-picker-01.htm\fR (or a similar one) to insert the base color and adjust the \fBL\fR component as needed.
+
+A terminal alternative is \fBpastel\fR (\fIhttps://github.com/sharkdp/pastel\fR), which can be used like so:
+
+
+.RS 6
+\fIpastel color '#fbf1f2'\fR         # show color info
+.br
+\fIpastel lighten .1 '#fbf1f2'\fR    # color lightened by 10%
+.br
+\fIpastel darken .1 '#fbf1f2'\fR     # color darkened by 10%\fR
+.RE
+
+.IP 2. 3
+If the \fIStations Background\fR color is dark, create a lighter version of it; if it's light, create a darker version of it.
+
+This is just a recomenration, though; just get a color that combines well with existing ones (border foreground, stations foreground and active station).
+
+This information is actually relevant to creating a new \fBpyradio\fR theme, but it's very important in order to understand how the calculated background color works.
+
+
+.RE
+.RE
+\fBCalculated secondary windows color\fR
+.RS 3
+
+
+\fBpyradio\fR will use the same background color for all windows by default, provided that the theme used does not define a \fIMessages Border\fR background color.
+
+In order to use a \fIMessages Border\fR background color different than the \fIStations background\fR color, when \fIMessages Border\fR background color is not defined in the selected theme, a config option is available; \fBCalculated color\fR".
+
+This config option takes a value that's between 0 and 0.2.
+
+If it is 0, no color change will occur.
+
+Otherwise, the value acts as a percentage (a \fBfactor\fR), which indicates how much the luminance of the \fIStations background\fR color will change to produce the new background color.
+
+This is how this works: \fBpyradio\fR will calculate the \fIStations background\fR color perceived brightness, which will indicate whether the color is dark or light. Then depending on that, will add or subtract \fBfactor\fR percent from its luminance value.
+
+Finally, a check will be made to see if this color is close to \fIMessages Border\fR foreground color, and re-adjusted as possible.
+
+
+.IP \fBNote\fR
+When a calculated background color is used, pressing \fI~\fR (\fItilde\fR) will toggle it on and off. This setting will be valid until \fBPyRadio\fR terminates, or a new theme is loaded.
+
+.RE
+
 .RE
 .PP
 \fBUser themes\fR
@@ -891,11 +989,15 @@ Copy (and rename) one of the \fISystem Themes\fR to the user's \fBthemes\fR fold
 
 To gain access to the \fISystem Themes\fR, execute the following commands
 
+.RS 6
 \fIcd `python -c 'import site; print(site.getusersitepackages())'`\fR
-.BR
+.br
 \fIcd pyradio/themes\fR
+.RE
 
+.RS 3
 (you may have to use \fIpython2\fR or \fIpython3\fR instead of plain \fIpython\fR, depending on your OS and distribution).
+.RE
 
 .IP 2. 3
 Customize it as desired

pyradio/__init__.py

@@ -1,6 +1,6 @@
 " pyradio -- Console radio player. "
 
-version_info = (0, 8, 9, 25)
+version_info = (0, 8, 9, 26)
 
 # Set it to True if new stations have been
 # added to the package's stations.csv

pyradio/config.py

@@ -2852,7 +2852,7 @@ def download(self, a_theme=None, a_path=None, print_errors=None):
 # Message window border foreground and background.
 # The background color can be left unset.
 # Please refer to the following link for more info
-# https://github.com/coderholic/pyradio#calculated-colors
+# https://github.com/coderholic/pyradio#secondary-windows-background
 #
 Messages Border     {color4}
 
@@ -2895,7 +2895,7 @@ def download(self, a_theme=None, a_path=None, print_errors=None):
 # Message window border foreground and background.
 # The background color can be left unset.
 # Please refer to the following link for more info
-# https://github.com/coderholic/pyradio#calculated-colors
+# https://github.com/coderholic/pyradio#secondary-windows-background
 #
 Messages Border     {color2}
 
@@ -3041,7 +3041,7 @@ def download(self, a_theme=None, a_path=None, print_errors=None):
 # Message window border foreground and background.
 # The background color can be left unset.
 # Please refer to the following link for more info
-# https://github.com/coderholic/pyradio#calculated-colors
+# https://github.com/coderholic/pyradio#secondary-windows-background
 #
 Messages Border     {color8}
 
@@ -3084,7 +3084,7 @@ def download(self, a_theme=None, a_path=None, print_errors=None):
 # Message window border foreground and background.
 # The background color can be left unset.
 # Please refer to the following link for more info
-# https://github.com/coderholic/pyradio#calculated-colors
+# https://github.com/coderholic/pyradio#secondary-windows-background
 #
 Messages Border     {color8}
 
@@ -3127,7 +3127,7 @@ def download(self, a_theme=None, a_path=None, print_errors=None):
 # Message window border foreground and background.
 # The background color can be left unset.
 # Please refer to the following link for more info
-# https://github.com/coderholic/pyradio#calculated-colors
+# https://github.com/coderholic/pyradio#secondary-windows-background
 #
 Messages Border     {color8}
 
@@ -3170,7 +3170,7 @@ def download(self, a_theme=None, a_path=None, print_errors=None):
 # Message window border foreground and background.
 # The background color can be left unset.
 # Please refer to the following link for more info
-# https://github.com/coderholic/pyradio#calculated-colors
+# https://github.com/coderholic/pyradio#secondary-windows-background
 #
 Messages Border     {color8}
 

pyradio/config_window.py

@@ -79,7 +79,7 @@ class PyRadioConfigWindow(object):
     '|', 'Default value = dark'])
     _help_text.append(['If False, theme colors will be used.', '|',
     "If True and a compositor is running, the stations' window background will be transparent.", '|', "If True and a compositor is not running, the terminal's background color will be used.", '|', 'Default value: False'])
-    _help_text.append(['Pyradio can calculate and use an alternative color for secondary windows.', '|', 'This option will determine if this color will be used (value > 0) or not (value = 0), provided that the theme used does not already provide it.', '|', 'The value of this option is actually the factor to darken or lighten the main (stations) background color.', '|', 'You can get more info on this at https://github.com/coderholic/pyradio#calculated-colors' , '|', 'Valid Values: 0-0.2', 'Default value: 0'])
+    _help_text.append(['Pyradio can calculate and use an alternative color for secondary windows.', '|', 'This option will determine if this color will be used (value > 0) or not (value = 0), provided that the theme used does not already provide it.', '|', 'The value of this option is actually the factor to darken or lighten the main (stations) background color.', '|', 'You can get more info on this at https://github.com/coderholic/pyradio#secondary-windows-background', '|', 'Valid Values: 0-0.2', 'Default value: 0'])
     _help_text.append(None)
     _help_text.append(['Specify whether you will be asked to confirm every station deletion action.',
     '|', 'Default value: True'])
@@ -350,6 +350,8 @@ def _check_if_config_is_dirty(self):
     def _apply_a_theme(self, a_theme, use_transparency=None):
         theme = PyRadioTheme(self._cnf)
         theme.readAndApplyTheme(a_theme, use_transparency=use_transparency)
+        self._cnf.use_calculated_colors = False if self._cnf.opts['calculated_color_factor'][1] == '0' else True
+        self._cnf.update_calculated_colors()
         theme = None
         curses.doupdate()