From b53aea76bd0692137e0ff904d3297c8ffe02e050 Mon Sep 17 00:00:00 2001
From: o9000 <mrovi9000@gmail.com>
Date: Tue, 4 Oct 2016 18:04:13 +0200
Subject: [PATCH] Updated changelog and doc

---
 AUTHORS         |   2 +-
 ChangeLog       |   1 +
 doc/manual.html | 126 ++++++++++++++++++++++++++++++++-
 doc/tint2.1     | 184 ++++++++++++++++++++++++++++++++++++++++++++++++
 doc/tint2.md    | 179 ++++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 490 insertions(+), 2 deletions(-)

diff --git a/AUTHORS b/AUTHORS
index cc7da4b..5965806 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -26,7 +26,7 @@ Contributors:
   Christophe D. <stophe72.d@gmail.com> : non-rectangular borders
   Benoit Averty : taskbar enhancements
   Justin Jacobs : tint2conf fixes
-  Oskari Rauta : separator plugin
+  Oskari Rauta : separator plugin, gradients
 
 Translations:
   Bosnian:
diff --git a/ChangeLog b/ChangeLog
index b42db49..9d7a1c2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -4,6 +4,7 @@
 - Enhancements:
   - Desktop files (shortcuts) used in launcher are reloaded on click, in case the file has changed
   - New config option taskbar_hide_if_empty to hide an empty taskbar in multi_desktop mode (contributed by Benoit Averty)
+  - Gradient backgrounds (contributed by Oskari Rauta)
 - New plugin: separator (contributed by Oskari Rauta)
 
 2016-08-02 0.12.12
diff --git a/doc/manual.html b/doc/manual.html
index c34797c..576d2e0 100644
--- a/doc/manual.html
+++ b/doc/manual.html
@@ -218,6 +218,7 @@ It was specifically made for Openbox but it should also work with other window m
 <ul>
 <li><p><a href="#introduction">Introduction</a></p></li>
 <li><p><a href="#backgrounds-and-borders">Backgrounds and borders</a></p></li>
+<li><p><a href="#gradients">Gradients</a></p></li>
 <li><p><a href="#panel">Panel</a></p></li>
 <li><p><a href="#launcher">Launcher</a></p></li>
 <li><p><a href="#taskbar-pager">Taskbar/Pager</a></p></li>
@@ -287,7 +288,130 @@ task_active_background_id = 2
 systray_background_id = 0
 clock_background_id = 0
 </code></pre>
-<p>Identifier 0 refers to a special background which is fully transparent, identifier 1 applies the first background defined in the config file etc.</p><h3 id="panel">Panel<a name="panel" href="#panel" class="md2man-permalink" title="permalink"></a></h3>
+<p>Identifier 0 refers to a special background which is fully transparent, identifier 1 applies the first background defined in the config file etc.</p><h3 id="gradients">Gradients<a name="gradients" href="#gradients" class="md2man-permalink" title="permalink"></a></h3><p>(Available since 0.13.0)</p><p>Most of the panel elements that accept backgrounds also allow specifying
+one or more gradient layers that are drawn on top of the solid color
+background.</p><p>First the user must define one or more gradients in the config file,
+each starting with <code>gradient = TYPE</code>. These should be added
+ideally after backgrounds but before all the other options.</p><p>Then gradients can be added by index to elements, using <code>*_gradient_id = INDEX</code>,
+where <code>*</code> is an element name, for example <code>panel</code>, and <code>INDEX</code> is
+the gradient index, starting from 1. The <code>*_gradient_id</code> option can be repeated
+for the same element, which results in multiple gradients
+being drawn on top of each other in the given order.</p><h1 id="simple-gradients">Simple gradients<a name="simple-gradients" href="#simple-gradients" class="md2man-permalink" title="permalink"></a></h1><p>These are gradients that vary from fixed control points (top-to-bottom, left-to-right
+or center-to-corners). The user must specify the start and end colors,
+and can optionally add extra color stops in between.</p><h2 id="vertical-gradient-with-color-varying-from-the-top-edge-to-the-bottom-edge-two-colors">Vertical gradient, with color varying from the top edge to the bottom edge, two colors<a name="vertical-gradient-with-color-varying-from-the-top-edge-to-the-bottom-edge-two-colors" href="#vertical-gradient-with-color-varying-from-the-top-edge-to-the-bottom-edge-two-colors" class="md2man-permalink" title="permalink"></a></h2><pre class="highlight plaintext"><code>gradient = vertical
+start_color = #rrggbb opacity
+end_color = #rrggbb opacity
+</code></pre>
+<h2 id="horizontal-gradient-with-color-varying-from-the-left-edge-to-the-right-edge-two-colors">Horizontal gradient, with color varying from the left edge to the right edge, two colors<a name="horizontal-gradient-with-color-varying-from-the-left-edge-to-the-right-edge-two-colors" href="#horizontal-gradient-with-color-varying-from-the-left-edge-to-the-right-edge-two-colors" class="md2man-permalink" title="permalink"></a></h2><pre class="highlight plaintext"><code>gradient = horizontal
+start_color = #rrggbb opacity
+end_color = #rrggbb opacity
+</code></pre>
+<h2 id="centered-radial-gradient-with-color-varying-from-the-center-to-the-corner-two-colors">Centered radial gradient, with color varying from the center to the corner, two colors:<a name="centered-radial-gradient-with-color-varying-from-the-center-to-the-corner-two-colors" href="#centered-radial-gradient-with-color-varying-from-the-center-to-the-corner-two-colors" class="md2man-permalink" title="permalink"></a></h2><pre class="highlight plaintext"><code>gradient = centered
+start_color = #rrggbb opacity
+end_color = #rrggbb opacity
+</code></pre>
+<h2 id="adding-extra-color-stops-0-and-100-remain-fixed-more-colors-at-x-between-the-start-and-end-control-points">Adding extra color stops (0% and 100% remain fixed, more colors at x% between the start and end control points)<a name="adding-extra-color-stops-0-and-100-remain-fixed-more-colors-at-x-between-the-start-and-end-control-points" href="#adding-extra-color-stops-0-and-100-remain-fixed-more-colors-at-x-between-the-start-and-end-control-points" class="md2man-permalink" title="permalink"></a></h2><pre class="highlight plaintext"><code>color_stop = percentage #rrggbb opacity
+</code></pre>
+<h1 id="advanced-gradients">Advanced gradients<a name="advanced-gradients" href="#advanced-gradients" class="md2man-permalink" title="permalink"></a></h1><p>These gradient types allow specifying the control points. This permits, for example,
+adding off-center radial glow effects, linear gradients with arbitrary angles,
+or using another element&#39;s edge as a control point.</p><p>Note: updates are currently a little buggy for task buttons.</p><h2 id="linear-or-radial-gradients-with-arbitrary-control-points-and-orientation">Linear or radial gradients, with arbitrary control points (and orientation)<a name="linear-or-radial-gradients-with-arbitrary-control-points-and-orientation" href="#linear-or-radial-gradients-with-arbitrary-control-points-and-orientation" class="md2man-permalink" title="permalink"></a></h2><pre class="highlight plaintext"><code>gradient = linear | radial
+# Geometry
+from_offset_x = SIZE_EXPRESSION
+from_offset_y = SIZE_EXPRESSION
+# from_offset_r for radial only
+from_offset_r = SIZE_EXPRESSION
+to_offset_x = SIZE_EXPRESSION
+to_offset_y = SIZE_EXPRESSION
+# to_offset_r for radial only
+to_offset_r = SIZE_EXPRESSION
+# Colors
+start_color = #rrggbb opacity
+end_color = #rrggbb opacity
+# Optional: more color stops
+color_stop = percentage #rrggbb opacity
+color_stop = percentage #rrggbb opacity
+</code></pre>
+<p><code>SIZE_EXPRESSION</code> is an expression that encodes an offset,
+following the grammar:</p><pre class="highlight plaintext"><code>SIZE_EXPRESSION = number |
+                  SIZE |
+                  SIZE * number |
+                  SIZE * number%
+SIZE = width | height | radius | left | right | top | bottom | centerx | centery |
+       ELEMENT width | ELEMENT height | ELEMENT radius | ELEMENT left | ELEMENT right | ELEMENT top | ELEMENT bottom | ELEMENT centerx | ELEMENT centery
+ELEMENT = self | parent | panel
+</code></pre>
+<p>All coordinates are computed in the drawn element&#39;s coordinate system,
+with origin in the top-left corner and the vertical axis growing down.</p><p>Numbers are any real numbers. Negative numbers must not have spaces between
+the minus sign and the first digit, for example <code>-1.234</code> is correct,
+while <code>- 1.234</code> is not.</p><p>Multiple <code>*_offset_*</code> can be given, in which case they are added together.</p><h1 id="gradient-examples">Gradient examples<a name="gradient-examples" href="#gradient-examples" class="md2man-permalink" title="permalink"></a></h1><pre class="highlight plaintext"><code># Gradient 1: thin film effect
+gradient = horizontal
+start_color = #111122 30
+end_color = #112211 30
+color_stop = 60 #221111 30
+
+# Gradient 2: center glow
+gradient = centered
+start_color = #ffffff 20
+end_color = #ffffff 0
+
+# Gradient 3: glow
+gradient = radial
+start_color = #ffffff 20
+end_color = #ffffff 0
+from_offset_x = width * 0.28
+from_offset_y = height * 0.28
+from_offset_r = 0
+to_offset_x = width * 0.28
+to_offset_y = height * 0.28
+to_offset_r = radius * 2
+
+# Gradient 4: aurora
+gradient = linear
+start_color = #ffffff 0
+end_color = #ffffff 0
+from_offset_x = panel left
+from_offset_y = panel top
+to_offset_x = panel width * 3
+to_offset_x = panel height * 3
+to_offset_y = panel width
+to_offset_y = panel height
+color_stop = 0.1 #ffffff 30
+color_stop = 0.8 #ffffff 30
+color_stop = 2.1 #7777aa 30
+color_stop = 3.1 #7777aa 30
+color_stop = 4.0 #ffffaa 30
+color_stop = 4.8 #aa7733 30
+color_stop = 5.1 #ff7733 30
+color_stop = 6.5 #337788 30
+color_stop = 9.2 #ffffaa 30
+color_stop = 10.1 #777777 30
+color_stop = 12.1 #aaaaff 30
+color_stop = 14.0 #77ff77 30
+color_stop = 18.0 #ffff77 30
+color_stop = 19.8 #77ffaa 30
+color_stop = 21.1 #ffffaa 20
+color_stop = 23.5 #337733 30
+color_stop = 25.5 #337733 30
+color_stop = 29.2 #77ffff 30
+color_stop = 30.1 #77ffaa 30
+color_stop = 31.0 #ffffaa 30
+color_stop = 34.8 #aa7733 30
+
+# Gradient 5: elegant black
+gradient = vertical
+start_color = #444444 100
+end_color = #222222 100
+
+# Gradient 6: elegant black
+gradient = horizontal
+start_color = #111111 100
+end_color = #222222 100
+
+[....]
+
+panel_gradient_id = 5
+</code></pre>
+<h3 id="panel">Panel<a name="panel" href="#panel" class="md2man-permalink" title="permalink"></a></h3>
 <ul>
 <li><p><code>panel_items = LTSBC</code> defines the items tint2 will show and the order of those items. Each letter refers to an item, defined as:</p>
 <ul>
diff --git a/doc/tint2.1 b/doc/tint2.1
index 4d2fa76..5e14c13 100644
--- a/doc/tint2.1
+++ b/doc/tint2.1
@@ -45,6 +45,8 @@ Introduction \[la]#introduction\[ra]
 .IP \(bu 2
 Backgrounds and borders \[la]#backgrounds-and-borders\[ra]
 .IP \(bu 2
+Gradients \[la]#gradients\[ra]
+.IP \(bu 2
 Panel \[la]#panel\[ra]
 .IP \(bu 2
 Launcher \[la]#launcher\[ra]
@@ -173,6 +175,188 @@ clock_background_id = 0
 .RE
 .PP
 Identifier 0 refers to a special background which is fully transparent, identifier 1 applies the first background defined in the config file etc.
+.SS Gradients
+.PP
+(Available since 0.13.0)
+.PP
+Most of the panel elements that accept backgrounds also allow specifying
+one or more gradient layers that are drawn on top of the solid color
+background.
+.PP
+First the user must define one or more gradients in the config file,
+each starting with \fB\fCgradient = TYPE\fR\&. These should be added
+ideally after backgrounds but before all the other options.
+.PP
+Then gradients can be added by index to elements, using \fB\fC*_gradient_id = INDEX\fR,
+where \fB\fC*\fR is an element name, for example \fB\fCpanel\fR, and \fB\fCINDEX\fR is
+the gradient index, starting from 1. The \fB\fC*_gradient_id\fR option can be repeated
+for the same element, which results in multiple gradients
+being drawn on top of each other in the given order.
+.SH Simple gradients
+.PP
+These are gradients that vary from fixed control points (top\-to\-bottom, left\-to\-right
+or center\-to\-corners). The user must specify the start and end colors,
+and can optionally add extra color stops in between.
+.SH Vertical gradient, with color varying from the top edge to the bottom edge, two colors
+.PP
+.RS
+.nf
+gradient = vertical
+start_color = #rrggbb opacity
+end_color = #rrggbb opacity
+.fi
+.RE
+.SH Horizontal gradient, with color varying from the left edge to the right edge, two colors
+.PP
+.RS
+.nf
+gradient = horizontal
+start_color = #rrggbb opacity
+end_color = #rrggbb opacity
+.fi
+.RE
+.SH Centered radial gradient, with color varying from the center to the corner, two colors:
+.PP
+.RS
+.nf
+gradient = centered
+start_color = #rrggbb opacity
+end_color = #rrggbb opacity
+.fi
+.RE
+.SH Adding extra color stops (0% and 100% remain fixed, more colors at x% between the start and end control points)
+.PP
+.RS
+.nf
+color_stop = percentage #rrggbb opacity
+.fi
+.RE
+.SH Advanced gradients
+.PP
+These gradient types allow specifying the control points. This permits, for example,
+adding off\-center radial glow effects, linear gradients with arbitrary angles,
+or using another element's edge as a control point.
+.PP
+Note: updates are currently a little buggy for task buttons.
+.SH Linear or radial gradients, with arbitrary control points (and orientation)
+.PP
+.RS
+.nf
+gradient = linear | radial
+# Geometry
+from_offset_x = SIZE_EXPRESSION
+from_offset_y = SIZE_EXPRESSION
+# from_offset_r for radial only
+from_offset_r = SIZE_EXPRESSION
+to_offset_x = SIZE_EXPRESSION
+to_offset_y = SIZE_EXPRESSION
+# to_offset_r for radial only
+to_offset_r = SIZE_EXPRESSION
+# Colors
+start_color = #rrggbb opacity
+end_color = #rrggbb opacity
+# Optional: more color stops
+color_stop = percentage #rrggbb opacity
+color_stop = percentage #rrggbb opacity
+.fi
+.RE
+.PP
+\fB\fCSIZE_EXPRESSION\fR is an expression that encodes an offset,
+following the grammar:
+.PP
+.RS
+.nf
+SIZE_EXPRESSION = number |
+                  SIZE |
+                  SIZE * number |
+                  SIZE * number%
+SIZE = width | height | radius | left | right | top | bottom | centerx | centery |
+       ELEMENT width | ELEMENT height | ELEMENT radius | ELEMENT left | ELEMENT right | ELEMENT top | ELEMENT bottom | ELEMENT centerx | ELEMENT centery
+ELEMENT = self | parent | panel
+.fi
+.RE
+.PP
+All coordinates are computed in the drawn element's coordinate system,
+with origin in the top\-left corner and the vertical axis growing down.
+.PP
+Numbers are any real numbers. Negative numbers must not have spaces between
+the minus sign and the first digit, for example \fB\fC\-1.234\fR is correct,
+while \fB\fC\- 1.234\fR is not.
+.PP
+Multiple \fB\fC*_offset_*\fR can be given, in which case they are added together.
+.SH Gradient examples
+.PP
+.RS
+.nf
+# Gradient 1: thin film effect
+gradient = horizontal
+start_color = #111122 30
+end_color = #112211 30
+color_stop = 60 #221111 30
+
+# Gradient 2: center glow
+gradient = centered
+start_color = #ffffff 20
+end_color = #ffffff 0
+
+# Gradient 3: glow
+gradient = radial
+start_color = #ffffff 20
+end_color = #ffffff 0
+from_offset_x = width * 0.28
+from_offset_y = height * 0.28
+from_offset_r = 0
+to_offset_x = width * 0.28
+to_offset_y = height * 0.28
+to_offset_r = radius * 2
+
+# Gradient 4: aurora
+gradient = linear
+start_color = #ffffff 0
+end_color = #ffffff 0
+from_offset_x = panel left
+from_offset_y = panel top
+to_offset_x = panel width * 3
+to_offset_x = panel height * 3
+to_offset_y = panel width
+to_offset_y = panel height
+color_stop = 0.1 #ffffff 30
+color_stop = 0.8 #ffffff 30
+color_stop = 2.1 #7777aa 30
+color_stop = 3.1 #7777aa 30
+color_stop = 4.0 #ffffaa 30
+color_stop = 4.8 #aa7733 30
+color_stop = 5.1 #ff7733 30
+color_stop = 6.5 #337788 30
+color_stop = 9.2 #ffffaa 30
+color_stop = 10.1 #777777 30
+color_stop = 12.1 #aaaaff 30
+color_stop = 14.0 #77ff77 30
+color_stop = 18.0 #ffff77 30
+color_stop = 19.8 #77ffaa 30
+color_stop = 21.1 #ffffaa 20
+color_stop = 23.5 #337733 30
+color_stop = 25.5 #337733 30
+color_stop = 29.2 #77ffff 30
+color_stop = 30.1 #77ffaa 30
+color_stop = 31.0 #ffffaa 30
+color_stop = 34.8 #aa7733 30
+
+# Gradient 5: elegant black
+gradient = vertical
+start_color = #444444 100
+end_color = #222222 100
+
+# Gradient 6: elegant black
+gradient = horizontal
+start_color = #111111 100
+end_color = #222222 100
+
+[....]
+
+panel_gradient_id = 5
+.fi
+.RE
 .SS Panel
 .RS
 .IP \(bu 2
diff --git a/doc/tint2.md b/doc/tint2.md
index c3b0574..d9f853c 100644
--- a/doc/tint2.md
+++ b/doc/tint2.md
@@ -36,6 +36,8 @@ Goals:
 
   * [Backgrounds and borders](#backgrounds-and-borders)
 
+  * [Gradients](#gradients)
+
   * [Panel](#panel)
 
   * [Launcher](#launcher)
@@ -136,6 +138,183 @@ clock_background_id = 0
 
 Identifier 0 refers to a special background which is fully transparent, identifier 1 applies the first background defined in the config file etc.
 
+### Gradients
+
+(Available since 0.13.0)
+
+Most of the panel elements that accept backgrounds also allow specifying
+one or more gradient layers that are drawn on top of the solid color
+background.
+
+First the user must define one or more gradients in the config file,
+each starting with `gradient = TYPE`. These should be added
+ideally after backgrounds but before all the other options.
+
+Then gradients can be added by index to elements, using `*_gradient_id = INDEX`,
+where `*` is an element name, for example `panel`, and `INDEX` is
+the gradient index, starting from 1. The `*_gradient_id` option can be repeated
+for the same element, which results in multiple gradients
+being drawn on top of each other in the given order.
+
+# Simple gradients
+
+These are gradients that vary from fixed control points (top-to-bottom, left-to-right
+or center-to-corners). The user must specify the start and end colors,
+and can optionally add extra color stops in between.
+
+## Vertical gradient, with color varying from the top edge to the bottom edge, two colors
+
+```
+gradient = vertical
+start_color = #rrggbb opacity
+end_color = #rrggbb opacity
+```
+
+## Horizontal gradient, with color varying from the left edge to the right edge, two colors
+
+```
+gradient = horizontal
+start_color = #rrggbb opacity
+end_color = #rrggbb opacity
+```
+
+## Centered radial gradient, with color varying from the center to the corner, two colors:
+
+```
+gradient = centered
+start_color = #rrggbb opacity
+end_color = #rrggbb opacity
+```
+
+## Adding extra color stops (0% and 100% remain fixed, more colors at x% between the start and end control points)
+
+```
+color_stop = percentage #rrggbb opacity
+```
+
+# Advanced gradients
+
+These gradient types allow specifying the control points. This permits, for example,
+adding off-center radial glow effects, linear gradients with arbitrary angles,
+or using another element's edge as a control point.
+
+Note: updates are currently a little buggy for task buttons.
+
+## Linear or radial gradients, with arbitrary control points (and orientation)
+
+```
+gradient = linear | radial
+# Geometry
+from_offset_x = SIZE_EXPRESSION
+from_offset_y = SIZE_EXPRESSION
+# from_offset_r for radial only
+from_offset_r = SIZE_EXPRESSION
+to_offset_x = SIZE_EXPRESSION
+to_offset_y = SIZE_EXPRESSION
+# to_offset_r for radial only
+to_offset_r = SIZE_EXPRESSION
+# Colors
+start_color = #rrggbb opacity
+end_color = #rrggbb opacity
+# Optional: more color stops
+color_stop = percentage #rrggbb opacity
+color_stop = percentage #rrggbb opacity
+```
+
+`SIZE_EXPRESSION` is an expression that encodes an offset,
+following the grammar:
+
+```
+SIZE_EXPRESSION = number |
+                  SIZE |
+                  SIZE * number |
+                  SIZE * number%
+SIZE = width | height | radius | left | right | top | bottom | centerx | centery |
+       ELEMENT width | ELEMENT height | ELEMENT radius | ELEMENT left | ELEMENT right | ELEMENT top | ELEMENT bottom | ELEMENT centerx | ELEMENT centery
+ELEMENT = self | parent | panel
+```
+
+All coordinates are computed in the drawn element's coordinate system,
+with origin in the top-left corner and the vertical axis growing down.
+
+Numbers are any real numbers. Negative numbers must not have spaces between
+the minus sign and the first digit, for example `-1.234` is correct,
+while `- 1.234` is not.
+
+Multiple `*_offset_*` can be given, in which case they are added together.
+
+# Gradient examples
+
+```
+# Gradient 1: thin film effect
+gradient = horizontal
+start_color = #111122 30
+end_color = #112211 30
+color_stop = 60 #221111 30
+
+# Gradient 2: center glow
+gradient = centered
+start_color = #ffffff 20
+end_color = #ffffff 0
+
+# Gradient 3: glow
+gradient = radial
+start_color = #ffffff 20
+end_color = #ffffff 0
+from_offset_x = width * 0.28
+from_offset_y = height * 0.28
+from_offset_r = 0
+to_offset_x = width * 0.28
+to_offset_y = height * 0.28
+to_offset_r = radius * 2
+
+# Gradient 4: aurora
+gradient = linear
+start_color = #ffffff 0
+end_color = #ffffff 0
+from_offset_x = panel left
+from_offset_y = panel top
+to_offset_x = panel width * 3
+to_offset_x = panel height * 3
+to_offset_y = panel width
+to_offset_y = panel height
+color_stop = 0.1 #ffffff 30
+color_stop = 0.8 #ffffff 30
+color_stop = 2.1 #7777aa 30
+color_stop = 3.1 #7777aa 30
+color_stop = 4.0 #ffffaa 30
+color_stop = 4.8 #aa7733 30
+color_stop = 5.1 #ff7733 30
+color_stop = 6.5 #337788 30
+color_stop = 9.2 #ffffaa 30
+color_stop = 10.1 #777777 30
+color_stop = 12.1 #aaaaff 30
+color_stop = 14.0 #77ff77 30
+color_stop = 18.0 #ffff77 30
+color_stop = 19.8 #77ffaa 30
+color_stop = 21.1 #ffffaa 20
+color_stop = 23.5 #337733 30
+color_stop = 25.5 #337733 30
+color_stop = 29.2 #77ffff 30
+color_stop = 30.1 #77ffaa 30
+color_stop = 31.0 #ffffaa 30
+color_stop = 34.8 #aa7733 30
+
+# Gradient 5: elegant black
+gradient = vertical
+start_color = #444444 100
+end_color = #222222 100
+
+# Gradient 6: elegant black
+gradient = horizontal
+start_color = #111111 100
+end_color = #222222 100
+
+[....]
+
+panel_gradient_id = 5
+```
+
 ### Panel
 
   * `panel_items = LTSBC` defines the items tint2 will show and the order of those items. Each letter refers to an item, defined as: