docs: document gradients

(v2: small fixes)

diff --git a/docs/labwc-theme.5.scd b/docs/labwc-theme.5.scd
index 5b267f35c71b9dc978b4529f5a1f6441ab25597b..b9eb30d53e2baf8e3af50ea6b200e20a7ff7bd16 100644 (file)
--- a/docs/labwc-theme.5.scd
+++ b/docs/labwc-theme.5.scd
@@ -41,6 +41,8 @@ labwc-config(5).
        - #rrggbb (hexadecimal RGB values)
        - #rrggbb aaa (same but with decimal alpha value percentage)
        - #rrggbbaa (same but with inline alpha value in hex encoding)
+       - #rgb (hexadecimal RGB values where #fff is shorthand for #f0f0f0)
+         (since 0.9.0)
 
        Note: the #rrggbb aaa notation is deprecated starting from
        labwc 0.7.2 and may be removed in future releases.
@@ -49,6 +51,52 @@ labwc-config(5).
        Justification determines the horizontal alignment of text.
        Valid options are Left, Center and Right.
 
+*textures*
+       Textures determine the visual look of an element. They are specified
+       through a text string with a number of fields. Capitalization is not
+       significant. The format is as follows:
+
+```
+(Solid | Gradient <type>)
+```
+
+       ... where *|* stands for "or".
+
+       - *Solid* means that the background of the texture is filled with a
+         single color. The texture must be accompanied by a single color field.
+         For example:
+
+```
+window.*.title.bg: Solid
+window.*.title.bg.color: #f8f5f2
+```
+
+       - *Gradient* means that the background of the texture is filled with a
+         gradient from one color to another. When Gradient is specified, it
+         must be followed by the gradient's type. It must also be accompanied
+         by the fields *color* and *colorTo*. Valid gradient types are:
+         (1) *Vertical* where the gradient goes from the top edge to the bottom
+         (2) *SplitVertical* where the gradient is split in the middle and goes
+         out toward the top and bottom edges. SplitVertical gradients have two
+         extra, optional color fields: *color.splitTo* and *colorTo.splitTo*.
+         These colors are the light colors used on the far top and bottom of
+         the SplitVertical gradient. When these are omitted, the default values
+         for these are *color x 5/4* and *colorTo x 17/16*. Examples:
+
+```
+# Vertical gradient
+window.*.title.bg: Gradient Vertical
+window.*.title.bg.color: #658fb5
+window.*.title.bg.colorTo: #4d6982
+
+# SplitVertical gradient
+window.*.title.bg: Gradient SplitVertical
+window.*.title.bg.color: #658fb5
+window.*.title.bg.color.splitTo: #7595b9
+window.*.title.bg.colorTo: #4d6982
+window.*.title.bg.colorTo.splitTo: #557485
+```
+
 # THEME ELEMENTS
 
 *border.width*
@@ -75,12 +123,22 @@ labwc-config(5).
        value as set for window.active.border.color to disable the status
        indicator. Default is #ff0000.
 
+*window.active.title.bg*
+       Texture for the focused window's titlebar. See texture section above.
+       Default is *Solid*
+
 *window.active.title.bg.color*
-       Background color for the focused window's titlebar.
+       Background color for the focused window's titlebar. See texture section
+       for additional color fields associated with gradients.
        Default is #e1dedb.
 
+*window.inactive.title.bg*
+       Texture for non-focused windows' titlebars. See texture section above.
+       Default is *Solid*
+
 *window.inactive.title.bg.color*
-       Background color for non-focused windows' titlebars.
+       Background color for non-focused windows' titlebars. See texture section
+       for additional color fields associated with gradients.
        Default is #f6f5f4.
 
 *window.active.label.text.color*

diff --git a/docs/themerc b/docs/themerc
index 7ac293f706d5b46ade6f8c4bd91d60647cad5293..045c102124022f4497a4422d40c024dbb6cd6bcd 100644 (file)
--- a/docs/themerc
+++ b/docs/themerc
@@ -25,6 +25,14 @@ window.active.indicator.toggled-keybind.color: #ff0000
 # window titlebar background
 window.active.title.bg.color: #e1dedb
 window.inactive.title.bg.color: #f6f5f4
+window.*.title.bg: Solid
+
+# Vertical and SplitVertical gradients are supported for window.*.title.bg
+# with the following additional color fields. See labwc-theme(5) for examples.
+#
+#     window.*.title.bg.colorTo:
+#     window.*.title.bg.color.splitTo:
+#     window.*.title.bg.colorTo.splitTo:
 
 # window titlebar text
 window.active.label.text.color: #000000