feat: module-level name and class options

BREAKING CHANGE: To allow for the `name` property, any widgets that were previously targeted by name should be targeted by class instead. This affects **all modules and all popups**, as well as several widgets inside modules. **This will break a lot of rules in your stylesheet**. To attempt to mitigate the damage, a migration script can be found [here](https://raw.githubusercontent.com/JakeStanger/ironbar/master/scripts/migrate-styles.sh) that should get you most of the way. Resolves #75.
JakeStanger · May 6, 2023 · dea6641 · dea6641
1 parent 528a8d6
commit dea6641
Show file tree

Hide file tree

Showing 30 changed files with 353 additions and 216 deletions.
diff --git a/docs/Configuration guide.md b/docs/Configuration guide.md
@@ -310,9 +310,12 @@ For information on the `Script` type, and embedding scripts in strings, see [her
 | `transition_type`     | `slide_start` or `slide_end` or `crossfade` or `none` | `slide_start` | The transition animation to use when showing/hiding the widget.                                                    |
 | `transition_duration` | `Integer`                                             | `250`         | The length of the transition animation to use when showing/hiding the widget.                                      |
 
-#### Other
+#### Appearance
 
+| Name      | Type               | Default | Description                                                                       |
+|-----------|--------------------|---------|-----------------------------------------------------------------------------------|
+| `tooltip` | `string`           | `null`  | Shows this text on hover. Supports embedding scripts between `{{double braces}}`. |
+| `name`    | `string`           | `null`  | Sets the unique widget name, allowing you to style it using `#name`.              |
+| `class`   | `string`           | `null`  | Sets one or more CSS classes, allowing you to style it using `.class`.            |
 
-| Name              | Type               | Default | Description                                                                                                        |
-|-------------------|--------------------|---------|--------------------------------------------------------------------------------------------------------------------|
-| `tooltip`         | `string`           | `null`  | Shows this text on hover. Supports embedding scripts between `{{double braces}}`.                                  |
+For more information on styling, please see the [styling guide](styling-guide).
diff --git a/docs/Styling guide.md b/docs/Styling guide.md
@@ -4,17 +4,37 @@ To style the bar, create a file at `~/.config/ironbar/style.css`.
 
 Style changes are hot-loaded so there is no need to reload the bar.
 
-A reminder: since the bar is GTK-based, it uses GTK's implementation of CSS,
+Since the bar is GTK-based, it uses [GTK's implementation of CSS](https://docs.gtk.org/gtk3/css-overview.html),
 which only includes a subset of the full web spec (plus a few non-standard properties).
 
 The below table describes the selectors provided by the bar itself.
 Information on styling individual modules can be found on their pages in the sidebar.
 
-| Selector       | Description                               |
-|----------------|-------------------------------------------|
-| `.background`  | Top-level window                          |
-| `#bar`         | Bar root box                              |
-| `#bar #start`  | Bar left or top modules container box     |
-| `#bar #center` | Bar center modules container box          |
-| `#bar #end`    | Bar right or bottom modules container box |
-| `.container`   | All of the above                          |
+| Selector       | Description                                |
+|----------------|--------------------------------------------|
+| `.background`  | Top-level window.                          |
+| `#bar`         | Bar root box.                              |
+| `#bar #start`  | Bar left or top modules container box.     |
+| `#bar #center` | Bar center modules container box.          |
+| `#bar #end`    | Bar right or bottom modules container box. |
+| `.container`   | All of the above.                          |
+| `.popup`       | Any popup box.                             |
+
+Every widget can be selected using a `kebab-case` class name matching its name. 
+You can also target popups by prefixing `popup-` to the name. For example, you can use `.clock` and `.popup-clock` respectively.
+
+Setting the `name` option on a widget allows you to target that specific instance using `#name`. 
+You can also add additional classes to re-use styles. In both cases, `popup-` is automatically prefixed to the popup (`#popup-name` or `.popup-my-class`).
+
+You can also target all GTK widgets of a certain type directly using their name. For example, `button:hover` will select the hover state on *all* buttons.
+These names are all lower case with no separator, so `MenuBar` -> `menubar`.
+
+GTK CSS does not support custom properties, but it does have its own custom `@define-color` syntax which you can use for re-using colours:
+
+```css
+@define-color color_bg #2d2d2d;
+
+box, menubar {
+    background-color: @color_bg;
+}
+```
diff --git a/docs/modules/Clipboard.md b/docs/modules/Clipboard.md
@@ -84,11 +84,13 @@ end:
 
 | Selector                             | Description                                          |
 |--------------------------------------|------------------------------------------------------|
-| `#clipboard`                         | Clipboard widget.                                    |
-| `#clipboard .btn`                    | Clipboard widget button.                             |
-| `#popup-clipboard`                   | Clipboard popup box.                                 |
-| `#popup-clipboard .item`             | Clipboard row item inside the popup.                 |
-| `#popup-clipboard .item .btn`        | Clipboard row item radio button.                     |
-| `#popup-clipboard .item .btn.text`   | Clipboard row item radio button (text values only).  |
-| `#popup-clipboard .item .btn.image`  | Clipboard row item radio button (image values only). |
-| `#popup-clipboard .item .btn-remove` | Clipboard row item remove button.                    |
+| `.clipboard`                         | Clipboard widget.                                    |
+| `.clipboard .btn`                    | Clipboard widget button.                             |
+| `.popup-clipboard`                   | Clipboard popup box.                                 |
+| `.popup-clipboard .item`             | Clipboard row item inside the popup.                 |
+| `.popup-clipboard .item .btn`        | Clipboard row item radio button.                     |
+| `.popup-clipboard .item .btn.text`   | Clipboard row item radio button (text values only).  |
+| `.popup-clipboard .item .btn.image`  | Clipboard row item radio button (image values only). |
+| `.popup-clipboard .item .btn-remove` | Clipboard row item remove button.                    |
+
+For more information on styling, please see the [styling guide](styling-guide).
diff --git a/docs/modules/Clock.md b/docs/modules/Clock.md
@@ -71,7 +71,9 @@ end:
 
 | Selector                       | Description                                                                        |
 |--------------------------------|------------------------------------------------------------------------------------|
-| `#clock`                       | Clock widget button                                                                |
-| `#popup-clock`                 | Clock popup box                                                                    |
-| `#popup-clock #calendar-clock` | Clock inside the popup                                                             |
-| `#popup-clock #calendar`       | Calendar widget inside the popup. GTK provides some OOTB styling options for this. |
+| `.clock`                       | Clock widget button                                                                |
+| `.popup-clock`                 | Clock popup box                                                                    |
+| `.popup-clock .calendar-clock` | Clock inside the popup                                                             |
+| `.popup-clock .calendar`       | Calendar widget inside the popup. GTK provides some OOTB styling options for this. |
+
+For more information on styling, please see the [styling guide](styling-guide).
diff --git a/docs/modules/Custom.md b/docs/modules/Custom.md
@@ -392,10 +392,13 @@ let {
 
 ## Styling
 
-Since the widgets are all custom, you can use the `name` and `class` attributes, then target them using `#name` and `.class`.
+Since the widgets are all custom, you can use their `name` and `class` attributes, then target them using `#name` and `.class`.
 
-The following top-level selector is always available:
+The following top-level selectors are always available:
 
-| Selector  | Description             |
-|-----------|-------------------------|
-| `#custom` | Custom widget container |
+| Selector        | Description                    |
+|-----------------|--------------------------------|
+| `.custom`       | Custom widget container.       |
+| `.popup-custom` | Custom widget popup container. |
+
+For more information on styling, please see the [styling guide](styling-guide).
diff --git a/docs/modules/Focused.md b/docs/modules/Focused.md
@@ -86,8 +86,10 @@ end:
 
 ## Styling
 
-| Selector                 | Description        |
-|--------------------------|--------------------|
-| `#focused`               | Focused widget box |
-| `#focused #icon`         | App icon           |
-| `#focused #label`        | App name           |
+| Selector          | Description        |
+|-------------------|--------------------|
+| `.focused`        | Focused widget box |
+| `.focused .icon`  | App icon           |
+| `.focused .label` | App name           |
+
+For more information on styling, please see the [styling guide](styling-guide).
diff --git a/docs/modules/Label.md b/docs/modules/Label.md
@@ -65,6 +65,8 @@ end:
 
 ## Styling
 
-| Selector                       | Description                                                                        |
-|--------------------------------|------------------------------------------------------------------------------------|
-| `#label`                       | Label widget                                                                       |
+| Selector | Description                                                                        |
+|----------|------------------------------------------------------------------------------------|
+| `.label` | Label widget                                                                       |
+
+For more information on styling, please see the [styling guide](styling-guide).
diff --git a/docs/modules/Launcher.md b/docs/modules/Launcher.md
@@ -90,10 +90,12 @@ start:
 
 | Selector                      | Description              |
 |-------------------------------|--------------------------|
-| `#launcher`                   | Launcher widget box      |
-| `#launcher .item`             | App button               |
-| `#launcher .item.open`        | App button (open app)    |
-| `#launcher .item.focused`     | App button (focused app) |
-| `#launcher .item.urgent`      | App button (urgent app)  |
-| `#launcher-popup`             | Popup container          |
-| `#launcher-popup .popup-item` | Window button in popup   |
+| `.launcher`                   | Launcher widget box      |
+| `.launcher .item`             | App button               |
+| `.launcher .item.open`        | App button (open app)    |
+| `.launcher .item.focused`     | App button (focused app) |
+| `.launcher .item.urgent`      | App button (urgent app)  |
+| `.popup-launcher`             | Popup container          |
+| `.popup-launcher .popup-item` | Window button in popup   |
+
+For more information on styling, please see the [styling guide](styling-guide).
diff --git a/docs/modules/Music.md b/docs/modules/Music.md
@@ -135,24 +135,26 @@ and will be replaced with values from the currently playing track:
 
 | Selector                            | Description                              |
 |-------------------------------------|------------------------------------------|
-| `#music`                            | Tray widget button                       |
-| `#music #contents`                  | Tray widget button contents box          |
-| `#popup-music`                      | Popup box                                |
-| `#popup-music #album-art`           | Album art image inside popup box         |
-| `#popup-music #title`               | Track title container inside popup box   |
-| `#popup-music #title .icon`         | Track title icon label inside popup box  |
-| `#popup-music #title .label`        | Track title label inside popup box       |
-| `#popup-music #album`               | Track album container inside popup box   |
-| `#popup-music #album .icon`         | Track album icon label inside popup box  |
-| `#popup-music #album .label`        | Track album label inside popup box       |
-| `#popup-music #artist`              | Track artist container inside popup box  |
-| `#popup-music #artist .icon`        | Track artist icon label inside popup box |
-| `#popup-music #artist .label`       | Track artist label inside popup box      |
-| `#popup-music #controls`            | Controls container inside popup box      |
-| `#popup-music #controls #btn-prev`  | Previous button inside popup box         |
-| `#popup-music #controls #btn-play`  | Play button inside popup box             |
-| `#popup-music #controls #btn-pause` | Pause button inside popup box            |
-| `#popup-music #controls #btn-next`  | Next button inside popup box             |
-| `#popup-music #volume`              | Volume container inside popup box        |
-| `#popup-music #volume #slider`      | Volume slider popup box                  |
-| `#popup-music #volume .icon`        | Volume icon label inside popup box       |
+| `.music`                            | Tray widget button                       |
+| `.music .contents`                  | Tray widget button contents box          |
+| `.popup-music`                      | Popup box                                |
+| `.popup-music .album-art`           | Album art image inside popup box         |
+| `.popup-music .title`               | Track title container inside popup box   |
+| `.popup-music .title .icon`         | Track title icon label inside popup box  |
+| `.popup-music .title .label`        | Track title label inside popup box       |
+| `.popup-music .album`               | Track album container inside popup box   |
+| `.popup-music .album .icon`         | Track album icon label inside popup box  |
+| `.popup-music .album .label`        | Track album label inside popup box       |
+| `.popup-music .artist`              | Track artist container inside popup box  |
+| `.popup-music .artist .icon`        | Track artist icon label inside popup box |
+| `.popup-music .artist .label`       | Track artist label inside popup box      |
+| `.popup-music .controls`            | Controls container inside popup box      |
+| `.popup-music .controls .btn-prev`  | Previous button inside popup box         |
+| `.popup-music .controls .btn-play`  | Play button inside popup box             |
+| `.popup-music .controls .btn-pause` | Pause button inside popup box            |
+| `.popup-music .controls .btn-next`  | Next button inside popup box             |
+| `.popup-music .volume`              | Volume container inside popup box        |
+| `.popup-music .volume .slider`      | Volume slider popup box                  |
+| `.popup-music .volume .icon`        | Volume icon label inside popup box       |
+
+For more information on styling, please see the [styling guide](styling-guide).
diff --git a/docs/modules/Script.md b/docs/modules/Script.md
@@ -82,6 +82,8 @@ end:
 
 ## Styling
 
-| Selector      | Description         |
-|---------------|---------------------|
-| `#script`     | Script widget label |
+| Selector  | Description         |
+|-----------|---------------------|
+| `.script` | Script widget label |
+
+For more information on styling, please see the [styling guide](styling-guide).
diff --git a/docs/modules/Sys-Info.md b/docs/modules/Sys-Info.md
@@ -172,5 +172,7 @@ The following tokens can be used in the `format` configuration option:
 
 | Selector         | Description                  |
 |------------------|------------------------------|
-| `#sysinfo`       | Sysinfo widget box           |
-| `#sysinfo #item` | Individual information label |
+| `.sysinfo`       | Sysinfo widget box           |
+| `.sysinfo .item` | Individual information label |
+
+For more information on styling, please see the [styling guide](styling-guide).
diff --git a/docs/modules/Tray.md b/docs/modules/Tray.md
@@ -60,5 +60,7 @@ end:
 
 | Selector      | Description      |
 |---------------|------------------|
-| `#tray`       | Tray widget box  |
-| `#tray .item` | Tray icon button |
+| `.tray`       | Tray widget box  |
+| `.tray .item` | Tray icon button |
+
+For more information on styling, please see the [styling guide](styling-guide).
diff --git a/docs/modules/Upower.md b/docs/modules/Upower.md
@@ -72,9 +72,11 @@ end:
 
 | Selector                        | Description                 |
 |---------------------------------|-----------------------------|
-| `#upower`                       | Upower widget container.    |
-| `#upower #icon`                 | Upower widget battery icon. |
-| `#upower #button`               | Upower widget button.       |
-| `#upower #button #label`        | Upower widget button label. |
-| `#popup-upower`                 | Upower popup box.           |
-| `#popup-upower #upower-details` | Label inside the popup.     |
+| `.upower`                       | Upower widget container.    |
+| `.upower .icon`                 | Upower widget battery icon. |
+| `.upower .button`               | Upower widget button.       |
+| `.upower .button .label`        | Upower widget button label. |
+| `.popup-upower`                 | Upower popup box.           |
+| `.popup-upower .upower-details` | Label inside the popup.     |
+
+For more information on styling, please see the [styling guide](styling-guide).
diff --git a/docs/modules/Workspaces.md b/docs/modules/Workspaces.md
@@ -91,6 +91,8 @@ end:
 
 | Selector                    | Description                          |
 |-----------------------------|--------------------------------------|
-| `#workspaces`               | Workspaces widget box                |
-| `#workspaces .item`         | Workspace button                     |
-| `#workspaces .item.focused` | Workspace button (workspace focused) |
+| `.workspaces`               | Workspaces widget box                |
+| `.workspaces .item`         | Workspace button                     |
+| `.workspaces .item.focused` | Workspace button (workspace focused) |
+
+For more information on styling, please see the [styling guide](styling-guide).