theme: use max_toggled_hover.xbm

...and treat max_hover_toggled.xbm as an alternative name supported for
compatibility reasons.

Use the following button filename schema: "BUTTON [TOGGLED] [STATE]"
with the words separted by underscore and with the following meaning:
  - BUTTON can be one of 'max', 'iconify', 'close', 'menu'
  - TOGGLED is either 'toggled' or nothing
  - STATE is 'hover' or nothing.

This is consistent with the openbox.org wiki and it is believed that this
is how the vast majority of extant openbox themes out there are written.

But please be aware that it is actually different to vanilla Openbox which
uses: "BUTTON [STATE] [TOGGLED]" following a commit in 2014 which broke
themes and led to some distros patching Openbox:
https://github.com/danakj/openbox/commit/35e92e4c2a45b28d5c2c9b44b64aeb4222098c94

Arch Linux and Debian patch Openbox to keep the old syntax (the one that
this commit aligns us with).
https://gitlab.archlinux.org/archlinux/packaging/packages/openbox/-/blob/main/debian-887908.patch?ref_type=heads

diff --git a/docs/labwc-theme.5.scd b/docs/labwc-theme.5.scd
index efd0725911119d0fbae04b3e59a41c8e43c0f464..8a092c0c26035dbc0650cdd73a6088c439bff774 100644 (file)
--- a/docs/labwc-theme.5.scd
+++ b/docs/labwc-theme.5.scd
@@ -206,12 +206,16 @@ over the button in question:
 - iconify_hover.xbm
 - close_hover.xbm
 - menu_hover.xbm
-- max_hover_toggled.xbm
+- max_toggled_hover.xbm
 
 One advantage of xbm buttons over other formats is that they change color based
 on the theme. Other formats use the suffices "-active" and "-inactive" to align
 with the respective titlebar colors. For example: "close-active.png"
 
+For compatibility reasons, the following alternative names are supported:
+
+- max_hover_toggled.xbm for max_toggled_hover.xbm
+
 # DEFINITIONS
 
 The handle is the window edge decoration at the bottom of the window.

diff --git a/src/theme.c b/src/theme.c
index 2ee359133d0a5c08825cf78f3fe322cf799a38f8..1712ee9392df5f441b9ec036460cfbb6ad036a1f 100644 (file)
--- a/src/theme.c
+++ b/src/theme.c
@@ -56,6 +56,36 @@ drop(struct lab_data_buffer **buffer)
        }
 }
 
+/*
+ * We use the following button filename schema: "BUTTON [TOGGLED] [STATE]"
+ * with the words separted by underscore, and the following meaning:
+ *   - BUTTON can be one of 'max', 'iconify', 'close', 'menu'
+ *   - TOGGLED is either 'toggled' or nothing
+ *   - STATE is 'hover' or nothing. In future, 'pressed' may be supported too.
+ *
+ * We believe that this is how the vast majority of extant openbox themes out
+ * there are constructed and it is consistent with the openbox.org wiki. But
+ * please be aware that it is actually different to vanilla Openbox which uses:
+ * "BUTTON [STATE] [TOGGLED]" following an unfortunate commit in 2014 which
+ * broke themes and led to some distros patching Openbox:
+ * https://github.com/danakj/openbox/commit/35e92e4c2a45b28d5c2c9b44b64aeb4222098c94
+ *
+ * Arch Linux and Debian patch Openbox to keep the old syntax (the one we use).
+ * https://gitlab.archlinux.org/archlinux/packaging/packages/openbox/-/blob/main/debian-887908.patch?ref_type=heads
+ * This patch does the following:
+ *   - reads "%s_toggled_pressed.xbm" and "%s_toggled_hover.xbm" instead of the
+ *     'hover_toggled' equivalents.
+ *   - parses 'toggled.unpressed', toggled.pressed' and 'toggled.hover' instead
+ *     of the other way around ('*.toggled') when processing themerc.
+ *
+ * For compatibility with distros which do not apply similar patches, we support
+ * the hover-before-toggle too, for example:
+ *
+ *     .name = "max_toggled_hover",
+ *     .alt_name = "max_hover_toggled",
+ *
+ * ...in the button array definition below.
+ */
 static void
 load_buttons(struct theme *theme)
 {
@@ -116,8 +146,8 @@ load_buttons(struct theme *theme)
                .inactive.buffer = &theme->button_maximize_inactive_hover,
                .inactive.rgba = theme->window_inactive_button_max_unpressed_image_color,
        }, {
-               .name = "max_hover_toggled",
-               .alt_name = "max_toggled_hover",
+               .name = "max_toggled_hover",
+               .alt_name = "max_hover_toggled",
                .fallback_button = { 0x3e, 0x22, 0x2f, 0x29, 0x39, 0x0f },
                .active.buffer = &theme->button_restore_active_hover,
                .active.rgba = theme->window_active_button_max_unpressed_image_color,