1AERC-STYLESETS(7) Miscellaneous Information Manual AERC-STYLESETS(7)
2
6 aerc-stylesets - styleset file specification for aerc(1)
7
9 aerc uses a simple configuration syntax to configure the styleset for
10 its ui.
11
13 The styleset is described as <object>.<attribute> = <value> pairs.
14 For example, in the line below, the foreground color of the style ob‐
16 ject msglist_unread is set to cornflowerblue
17 msglist_unread.fg = cornflowerblue
19 The configuration also allows wildcard matching of the keys to config‐
21 ure multiple style objects at a time.
22
24 The following options are available to be modified for each of the
25 style objects.
26 <object>.fg = <color>
28 The foreground color of the style object is set.
29 <object>.bg = <color>
31 The background color of the style object is set.
32 <object>.bold = true|false|toggle
34 The bold attribute of the style object is set/unset.
35 <object>.blink = true|false|toggle
37 The blink attribute of the style object is set/unset. The terminal
38 needs to support blinking text.
39 <object>.underline = true|false|toggle
41 The underline attribute of the style object is set/unset. The ter‐
42 minal needs to support underline text.
43 <object>.italic = true|false|toggle
45 The italic attribute of the style object is set/unset. The terminal
46 needs to support italic text.
47 <object>.dim = true|false|toggle
49 The dim attribute of the style object is set/unset. The terminal
50 needs to support half-bright text.
51 <object>.reverse = true|false|toggle
53 Reverses the color of the style object. Exchanges the foreground
54 and background colors.
55 If the value is false, it doesn't change anything.
57 <object>.normal = true
59 All the attributes of the style object are unset.
60 The value doesn't matter.
62 <object>.default = true
64 Set the style object to the default style of the context. Usually
65 based on the terminal.
66 The value doesn't matter.
68
70 The style objects represent the various ui elements or ui instances for
71 styling.
72 ┌───────────────────┬────────────────────────────┐
74 │Style Object │ Description │
75 ├───────────────────┼────────────────────────────┤
76 │default │ The default style object │
77 │ │ used for normal ui ele‐ │
78 │ │ ments while not using spe‐ │
79 │ │ cialized configuration. │
80 ├───────────────────┼────────────────────────────┤
81 │error │ The style used to show er‐ │
82 │ │ rors. │
83 ├───────────────────┼────────────────────────────┤
84 │warning │ The style used when show‐ │
85 │ │ ing warnings. │
86 ├───────────────────┼────────────────────────────┤
87 │success │ The style used for success │
88 │ │ messages. │
89 ├───────────────────┼────────────────────────────┤
90 │title │ The style object used to │
91 │ │ style titles in ui ele‐ │
92 │ │ ments. │
93 ├───────────────────┼────────────────────────────┤
94 │header │ The style object used to │
95 │ │ style headers in ui ele‐ │
96 │ │ ments. │
97 ├───────────────────┼────────────────────────────┤
98 │statusline_default │ The default style applied │
99 │ │ to the statusline. │
100 ├───────────────────┼────────────────────────────┤
101 │statusline_error │ The style used for error │
102 │ │ messages in statusline. │
103 ├───────────────────┼────────────────────────────┤
104 │statusline_success │ The style used for success │
105 │ │ messages in statusline. │
106 ├───────────────────┼────────────────────────────┤
107 │msglist_default │ The default style for mes‐ │
108 │ │ sages in a message list. │
109 ├───────────────────┼────────────────────────────┤
110 │msglist_unread │ Unread messages in a mes‐ │
111 │ │ sage list. │
112 ├───────────────────┼────────────────────────────┤
113 │msglist_read │ Read messages in a message │
114 │ │ list. │
115 ├───────────────────┼────────────────────────────┤
116 │msglist_flagged │ The messages with the │
117 │ │ flagged flag. │
118 ├───────────────────┼────────────────────────────┤
119 │msglist_deleted │ The messages marked as │
120 │ │ deleted. │
121 ├───────────────────┼────────────────────────────┤
122 │msglist_marked │ The messages with the │
123 │ │ marked flag. │
124 ├───────────────────┼────────────────────────────┤
125 │msglist_result │ The messages which match │
126 │ │ the current search. │
127 ├───────────────────┼────────────────────────────┤
128 │msglist_answered │ The messages marked as an‐ │
129 │ │ swered. │
130 ├───────────────────┼────────────────────────────┤
131 │dirlist_default │ The default style for di‐ │
132 │ │ rectories in the directory │
133 │ │ list. │
134 ├───────────────────┼────────────────────────────┤
135 │dirlist_unread │ The style used for direc‐ │
136 │ │ tories with unread mes‐ │
137 │ │ sages │
138 ├───────────────────┼────────────────────────────┤
139 │dirlist_recent │ The style used for direc‐ │
140 │ │ tories with recent mes‐ │
141 │ │ sages │
142 ├───────────────────┼────────────────────────────┤
143 │completion_default │ The default style for the │
144 │ │ completion engine. │
145 ├───────────────────┼────────────────────────────┤
146 │completion_gutter │ The completion gutter. │
147 ├───────────────────┼────────────────────────────┤
148 │completion_pill │ The completion pill. │
149 ├───────────────────┼────────────────────────────┤
150 │tab │ The style for the tab bar. │
151 ├───────────────────┼────────────────────────────┤
152 │stack │ The style for ui stack el‐ │
153 │ │ ement. │
154 ├───────────────────┼────────────────────────────┤
155 │spinner │ The style for the loading │
156 │ │ spinner. │
157 ├───────────────────┼────────────────────────────┤
158 │border │ The style used to draw │
159 │ │ borders (only the bg color │
160 │ │ is used unless you custom‐ │
161 │ │ ize border-char-vertical │
162 │ │ and/or border-char-hori‐ │
163 │ │ zontal in aerc.conf). │
164 ├───────────────────┼────────────────────────────┤
165 │selector_default │ The default style for the │
166 │ │ selector ui element. │
167 ├───────────────────┼────────────────────────────┤
168 │selector_focused │ The focused item in a se‐ │
169 │ │ lector ui element. │
170 ├───────────────────┼────────────────────────────┤
171 │selector_chooser │ The item chooser in a se‐ │
172 │ │ lector ui element. │
173 └───────────────────┴────────────────────────────┘
174 These next style objects only affect the built-in colorize filter and
175 must be declared under a [viewer] section of the styleset file.
176 ┌─────────────┬────────────────────────────┐
178 │Style Object │ Description │
179 ├─────────────┼────────────────────────────┤
180 │url │ URLs. │
181 ├─────────────┼────────────────────────────┤
182 │header │ RFC-822-like header names. │
183 ├─────────────┼────────────────────────────┤
184 │signature │ Email signatures. │
185 ├─────────────┼────────────────────────────┤
186 │diff_meta │ Patch diff meta lines. │
187 ├─────────────┼────────────────────────────┤
188 │diff_chunk │ Patch diff chunks. │
189 ├─────────────┼────────────────────────────┤
190 │diff_add │ Patch diff added lines. │
191 ├─────────────┼────────────────────────────┤
192 │diff_del │ Patch diff deleted lines. │
193 ├─────────────┼────────────────────────────┤
194 │quote_1 │ First level quoted text. │
195 ├─────────────┼────────────────────────────┤
196 │quote_2 │ Second level quoted text. │
197 ├─────────────┼────────────────────────────┤
198 │quote_3 │ Third level quoted text. │
199 ├─────────────┼────────────────────────────┤
200 │quote_4 │ Fourth level quoted text. │
201 ├─────────────┼────────────────────────────┤
202 │quote_x │ Above fourth level quoted │
203 │ │ text. │
204 └─────────────┴────────────────────────────┘
205 User defined styles can be used to style arbitrary strings in go-tem‐
206 plates (see .Style in aerc-templates(7)). User styles must be defined
207 in the [user] ini section. Styles can be referenced by their name (e.g.
208 red.fg is named "red").
209 Example:
211 [user]
213 red.fg=red
214 User styles are layered with other styles applied to the context in
216 which they are rendered. The user style colors (fg and/or bg) will only
217 be effective if the context style does not define any. Other boolean
218 attributes will be merged with the underlying style boolean attributes.
219 For example, if the context style is:
221 fg=red bold
223 And the inline style is:
225 fg=yellow italic underline
227 The effective style will be:
229 fg=red bold italic underline
231
233 The styleset configuration can be made simpler by using the fnmatch
234 style wildcard matching for the style object.
235 The special characters used in the fnmatch wildcards are:
237 ┌────────┬────────────────────────────┐
239 │Pattern │ Meaning │
240 ├────────┼────────────────────────────┤
241 │* │ Matches everything │
242 ├────────┼────────────────────────────┤
243 │? │ Matches any single charac‐ │
244 │ │ ter │
245 └────────┴────────────────────────────┘
246 For example, the following wildcards can be made using this syntax.
247 ┌───────────────────┬───────────────────────────┐
249 │Example │ Description │
250 ├───────────────────┼───────────────────────────┤
251 │*.fg = blue │ Set the foreground color │
252 │ │ of all style objects to │
253 │ │ blue. │
254 ├───────────────────┼───────────────────────────┤
255 │*list.bg = hotpink │ Set the background color │
256 │ │ of all style objects that │
257 │ │ end in list to hotpink. │
258 └───────────────────┴───────────────────────────┘
259 Note that the statements in a given styleset are parsed in the order in
260 which they are written. That means that with the following styleset:
261 msglist_marked.fg = pink
263 msglist_*.fg = white
264 The msglist_marked.fg attribute will be set to white.
266
268 The selected modifier can be applied to any style object. The style
269 provided for the selected modifier is applied on top of the style ob‐
270 ject it corresponds to.
271 If you would like to make sure message that are flagged as read in the
273 msglist appear in yellow foreground and black background. You can spec‐
274 ify that with this:
275 msglist_default.selected.fg = yellow
277 msglist_default.selected.bg = black
279 If we specify the global style selected modifier using fnmatch as be‐
281 low:
282 *.selected.reverse = toggle
284 This toggles the reverse switch for selected version of all the style
286 objects.
287 selected objects inherit from all attributes of their non-selected
289 counterparts. selected statements are parsed after non-selected ones
290 and effectively override the attributes of the non-selected style ob‐
291 ject.
292
294 Some styles, (currently the msglist_* and dirlist_* ones) are applied
295 in layers. If a style differs from the base (in this case *list_de‐
296 fault) then that style applies, unless overridden by a higher layer. If
297 fg and bg colors are not defined explicitly (or defined to the default
298 color) they will be considered as "transparent" and the colors from the
299 lower layer will be used instead.
300 The order that msglist_* styles are applied in is, from first to last:
302 1. msglist_default
304 2. msglist_unread
305 3. msglist_read
306 4. msglist_answered
307 5. msglist_flagged
308 6. msglist_deleted
309 7. msglist_result
310 8. msglist_marked
311 So, the marked style will override all other msglist styles.
314 The order for dirlist_* styles is:
316 1. dirlist_default
318 2. dirlist_unread
319 3. dirlist_recent
320
323 All msglist_* styles can be defined for specific email header values.
324 The syntax is as follows:
325 msglist_<name>.<header>,<header_value>.<attribute> = <attr_value>
327 If <header_value> starts with a tilde character ~, it will be inter‐
329 preted as a regular expression.
330 Examples:
332 msglist*.X-Sourcehut-Patchset-Update,APPROVED.fg = green
334 msglist*.X-Sourcehut-Patchset-Update,NEEDS_REVISION.fg = yellow
335 msglist*.X-Sourcehut-Patchset-Update,REJECTED.fg = red
336 "msglist_*.Subject,~^([[w-]+]s*)?[(RFC )?PATCH.fg" = #ffffaf
337 "msglist_*.Subject,~^([[w-]+]s*)?[(RFC )?PATCH.selected.fg" = #ffffaf
338 When a dynamic style is matched to an email header, it will be used in
340 priority compared to its non-dynamic counterpart. Provided the follow‐
341 ing styleset:
342 msglist_marked.fg = blue
344 msglist_*.Subject,~foobar.fg = red
345 An email with foobar it its subject will be colored in red all the
347 time, since msglist_* also applies to msglist_marked.
348
350 The color values are set using the values accepted by the tcell li‐
351 brary. The values can be one of the following.
352 default
354 The color is set as per the system or terminal default.
355 <Color name>
357 Any w3c approved color name is used to set colors for the style.
358 <Hex code>
360 Hexcode for a color can be used. The format must be #XXXXXX.
361 <Dec number>
363 Color based on the terminal palette index. Valid numbers are be‐
364 tween 0 and 255.
365
367 aerc(1) aerc-config(5)
368
370 Originally created by Drew DeVault <sir@cmpwn.com> and maintained by
371 Robin Jarry <robin@jarry.cc> who is assisted by other open source con‐
372 tributors. For more information about aerc development, see
373 https://sr.ht/~rjarry/aerc/.
374 2023-07-16 AERC-STYLESETS(7)