Updated changelog and doc

2016-10-04 18:04:13 +02:00
parent a5434a362b
commit b53aea76bd
5 changed files with 490 additions and 2 deletions
--- 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: