1# Styling guide
2
3## Text style and color
4
5All UI elements in Visp can be styled with custom colors and text attributes.
6Assign styles with the `style` command; please see the [commands documentation](commands.md#setting-styles) for details.
7
8Colors are either literal names, such as `red`, `yellow`, or `green`, or hexadecimal color values such as `@ff0077`
9(the hash sign `#` cannot be used as it is reserved for comments; the `@` character is used instead).
10
11The 16 base colors found in most terminals have the following names, from 0 to 15:
12
13|        | 00      | 01      | 02      | 03      | 04      | 05      | 06      | 07      |
14|--------|---------|---------|---------|---------|---------|---------|---------|---------|
15| dim    | black   | maroon  | green   | olive   | navy    | purple  | teal    | silver  |
16| bright | gray    | red     | lime    | yellow  | blue    | fuchsia | aqua    | white   |
17
18More colors can be used, but they are not included here. A full list of supported
19color names can be found in the [tcell documentation](https://github.com/gdamore/tcell/blob/v2.2.0/color.go#L842).
20
21
22### Tags
23
24Any _tag_, such as `artist`, `album`, `date`, `time`, etc. can be styled.
25These tags are not included in this list.
26Their styles apply both to the tracklist and in the top bar.
27All tag names are in lowercase.
28
29### Tracklist
30
31* `header`
32
33  Column headers showing tag names.
34
35* `currentSong`
36
37  Color of the entire line in the tracklist, highlighting the currently playing song.
38
39* `selection`
40
41  Line color of selected songs.
42
43* `cursor`
44
45  Color of the entire line in the tracklist, highlighting the cursor position.
46
47### Log console
48
49* `logLevel`
50
51  Log level, such as DEBUG, INFO, or ERROR.
52
53* `logMessage`
54
55  Log messages.
56
57* `timestamp`
58
59  Log timestamps
60
61### Key bindings
62
63* `context`
64
65  Window context of keybinding.
66
67* `keyBinding`
68
69  Keybinding sequence that triggers the command.
70
71* `command`
72
73  Actual command run when completing the keybinding.
74
75### Top bar
76
77See [below](#top-bar-variables) for corresponding variables.
78
79* `deviceName`
80
81  Corresponds to `${device}` or `${device|name}`.
82
83* `deviceType`
84
85  Corresponds to `${device|type}`.
86
87* `elapsedPercentage`
88
89  Corresponds to `${elapsed|percentage}`.
90
91* `elapsedTime`
92
93  Corresponds to `${elapsed}`.
94
95* `liked`
96
97  Corresponds to `${liked}`.
98
99* `listIndex`
100
101  Corresponds to `${list|index}`.
102
103* `listTitle`
104
105  Corresponds to `${list|title}`.
106
107* `listTotal`
108
109  Corresponds to `${list|total}`.
110
111* `mute`
112
113  The color of the `${volume}` widget when the volume is zero.
114
115* `shortName`
116
117  Corresponds to `${shortname}`.
118
119* `state`
120
121  Corresponds to `${state}` and `${state|unicode}`.
122
123* `switches`
124
125  Corresponds to `${mode}`.
126
127* `syncStatus`
128
129  Corresponds to `${syncStatus}`.
130
131* `tagMissing`
132
133  The color used for tag styling when the tag is missing.
134
135* `topbar`
136
137  The default color of the top bar text and whitespace.
138
139* `version`
140
141  Corresponds to `${version}`.
142
143* `volume`
144
145  Corresponds to `${volume}`.
146
147### Statusbar
148
149* `commandText`
150
151  Text color when writing text in command input mode.
152
153* `errorText`
154
155  Text color of error messages in the status bar.
156
157* `readout`
158
159  Position readout at the bottom right.
160
161* `searchText`
162
163  Text color when searching.
164
165* `sequenceText`
166
167  Text color of uncompleted keyboard bindings.
168
169* `statusbar`
170
171  Normal text in the status bar.
172
173* `visualText`
174
175  Text color of the `-- VISUAL --` text when selecting songs in visual mode.
176
177
178## Top bar
179
180The top bar is an informational area where information about the current state of both MPD and PMS is shown.
181The height and contents are very flexible, and can be made to look exactly as you want them to.
182
183### Examples
184
185Borders are added for emphasis, and are not part of the rendered text.
186
187* One line, showing player state, artist, track title, and time elapsed.
188
189  ```
190  set topbar="${state|unicode} ${tag|artist} - ${tag|title} (${elapsed})"
191  ```
192  →
193  ```
194  .---------------------------------------------------------------------------.
195  |▶ Madrugada - Black Mambo (02:41)                                          |
196  '---------------------------------------------------------------------------'
197  ```
198
199* One line, with left- and right-justified text.
200
201  ```
202  set topbar="this text is to the left|this text is to the right"
203  ```
204  →
205  ```
206  .---------------------------------------------------------------------------.
207  |this text is to the left                          this text is to the right|
208  '---------------------------------------------------------------------------'
209  ```
210
211* Three lines containing center-justified text on the middle line.
212
213  ```
214  set topbar=";|the ${tag|artist} is in the center||;;"
215  ```
216  →
217  ```
218  .---------------------------------------------------------------------------.
219  |                                                                           |
220  |                       the Spoonbill is in the center                      |
221  |                                                                           |
222  '---------------------------------------------------------------------------'
223  ```
224
225### Top bar variables
226
227#### Playback state
228
229* `${syncStatus}`
230
231  Shows a `[+]` sign if the visible tracklist represents a real Spotify playlist, and the local copy differs.
232
233* `${state}`
234
235  The current player state, represented as a two-character ASCII art.
236
237* `${state|unicode}`
238
239  The current player state, represented with unicode symbols.
240
241* `${elapsed}`
242
243  The time elapsed in the current track.
244
245* `${elapsed|percentage}`
246
247  The time elapsed in the current track as a percentage of its total length.
248
249* `${time}`
250
251  The total length of the current track.
252
253* `${mode}`
254
255  The status of the player switches `random`, `single`, and `repeat`, printed as three characters (`zsr`).
256
257* `${liked}`
258
259  Shows a ASCII art heart if the current song is in the library of _liked songs_.
260
261* `${liked|unicode}`
262
263  Green heart symbol if the current song is in the library of _liked songs_.
264
265* `${volume}`
266
267  The current volume, or `MUTE` if the volume is zero.
268
269* `${device}` or `${device|name}`
270
271  Name of the Spotify device where music is being played.
272
273* `${device|type}`
274
275  Type of device currently playing.
276
277* `${tag|<tag>}`
278
279  A specific tag of the currently playing song, such as `${tag|artist}`.
280
281#### Information about the current list
282
283* `${list|index}`
284
285  The numeric index of the current tracklist.
286
287* `${list|title}`
288
289  The title of the current tracklist.
290
291* `${list|total}`
292
293  The total number of tracklists.
294
295#### Miscellaneous
296
297* `${shortname}`
298
299  The short name of this program.
300
301* `${version}`
302
303  The git version this program was compiled from.
304
305### Special characters
306
307* `|` divides the line into one more piece.
308* `;` starts a new line.
309* `$` selects a variable. You can use either `${variable|parameter}` or `$variable`.
310* `\` escapes the special meaning of the next character, so it will be printed literally.
311