1ROFI-THEME(5) ROFI-THEME(5)
2
6 rofi-theme - Rofi theme format files
7
9 The need for a new theme format was motivated by the fact that the way
10 rofi handled widgets has changed. From a very static drawing of lines
11 and text to a nice structured form of packing widgets. This change made
12 it possible to provide a more flexible theme framework. The old theme
13 format and config file are not flexible enough to expose these options
14 in a user-friendly way. Therefor, a new file format has been created,
15 replacing the old one.
16
19 The encoding of the file is utf-8. Both unix (\n) and windows (\r\n)
20 newlines format are supported. But unix is preferred.
21
23 C and C++ file comments are supported.
24 · Anything after // and before a newline is considered a comment.
26 · Everything between /* and */ is a comment.
28 Comments can be nested and the C comments can be inline.
32 The following is valid:
34 // Magic comment.
38 property: /* comment */ value;
39 However, this is not:
43 prop/*comment*/erty: value;
47
51 White space and newlines, like comments, are ignored by the parser.
52 This:
54 property: name;
58 Is identical to:
62 property :
66 name
67 ;
69
73 The preferred file extension for the new theme format is rasi. This is
74 an abbreviation for rofi advanced style information.
75
77 Each element has a section with defined properties. Global properties
78 can be defined in section * { }. Sub-section names begin with a hash
79 symbol #.
80 It is advised to define the global properties section on top of the
82 file to make inheritance of properties clearer.
83 /* Global properties section */
87 * {
88 // list of properties
89 }
90 /* Element theme section. */
92 {element path} {
93 // list of properties
94 }
95 {elements... } {
96 // list of properties
97 }
98 If there are multiple sections with the same name, they are merged.
102 Duplicate properties are overwritten and the last parsed entry kept.
103
105 A theme can have one or more global properties sections. If there is
106 more than one, they will be merged.
107 The global properties section denotes the defaults for each element.
109 Each property of this section can be referenced with @{identifier} (See
110 Properties section)
111 A global properties section is indicated with a * as element path.
113
115 A theme can have multiple element theme sections.
116 The element path can consist of multiple names separated by whitespace
118 or dots. Each element may contain any number of letters, numbers and
119 -´s. The first element in the element path should always start with a
120 #. Multiple elements can be specified by a ,.
121 This is a valid element name:
123 element normal.normal {
127 background-color: blue;
128 }
129 button {
130 background-color: blue;
131 }
132 And is identical to:
136 element normal normal, button {
140 background-color: blue;
141 }
142 Each section inherits the global properties. Properties can be explic‐
146 itly inherited from their parent with the inherit keyword. In the fol‐
147 lowing example:
148 window {
152 a: 1;
153 b: 2;
154 }
155 mainbox {
156 a: inherit;
157 b: 4;
158 c: 8;
159 }
160 The element mainbox will have the following set of properties (if main‐
164 box is a child of window):
165 a: 1;
169 b: 4;
170 c: 8;
171 If multiple sections are defined with the same name, they are merged by
175 the parser. If multiple properties with the same name are defined in
176 one section, the last encountered property is used.
177
179 The properties in a section consist of:
180 {identifier}: {value};
184 Both fields are mandatory for a property.
188 The identifier names the specified property. Identifiers can consist of
190 any combination of numbers, letters and ´-´. It must not contain any
191 whitespace. The structure of the value defines the type of the prop‐
192 erty. The current parser does not define or enforce a certain type of a
193 particular identifier. When used, values with the wrong type that can‐
194 not be converted are ignored.
195 The current theme format supports different types:
197 · a string
199 · an integer number
201 · a fractional number
203 · a boolean value
205 · a color
207 · text style
209 · line style
211 · a distance
213 · a padding
215 · a border
217 · a position
219 · a reference
221 · an orientation
223 · a list of keywords
225 · Inherit
227 Some of these types are a combination of other types.
231
233 · Format: "[:print:]+"
234 A string is always surrounded by double quotes ("). Between the quotes
238 there can be any printable character.
239 For example:
241 font: "Awasome 12";
245 The string must be valid UTF-8.
249
251 · Format: [-+]?[:digit:]+
252 An integer may contain any number.
256 For examples:
258 lines: 12;
262
266 · Format: [-+]?[:digit:]+(\.[:digit:]+)?
267 A real is an integer with an optional fraction.
271 For example:
273 real: 3.4;
277 The following is not valid: .3, 3. or scientific notation: 3.4e-3.
281
283 · Format: (true|false)
284 Boolean value is either true or false. This is case-sensitive.
288 For example:
290 dynamic: false;
294
298 rofi supports the color formats as specified in the CSS standard (1,2,3
299 and some of CSS 4)
300 · Format: #{HEX}{3} (rgb)
302 · Format: #{HEX}{4} (rgba)
304 · Format: #{HEX}{6} (rrggbb)
306 · Format: #{HEX}{8} (rrggbbaa)
308 · Format: rgb[a]({INTEGER},{INTEGER},{INTEGER}[, {PERCENTAGE}])
310 · Format: rgb[a]({INTEGER}%,{INTEGER}%,{INTEGER}%[, {PERCENTAGE}])
312 · Format: hsl[a]( {ANGLE}, {PERCENTAGE}, {PERCENTAGE} [, {PERCENT‐
314 AGE}])
315 · Format: hwb[a]( {ANGLE}, {PERCENTAGE}, {PERCENTAGE} [, {PERCENT‐
317 AGE}])
318 · Format: cmyk( {PERCENTAGE}, {PERCENTAGE}, {PERCENTAGE}, {PERCENT‐
320 AGE} [, {PERCENTAGE} ])
321 · Format: {named-color} [ / {PERCENTAGE} ]
323 The white-space format proposed in CSS4 is also supported.
327 The different values are:
329 · {HEX} is a hexadecimal number (´0-9a-f´ case insensitive).
331 · {INTEGER} value can be between 0 and 255 or 0-100 when representing
333 percentage.
334 · {ANGLE} is the angle on the color wheel, can be in deg, rad, grad
336 or turn. When no unit is specified, degrees is assumed.
337 · {PERCENTAGE} can be between 0-1.0, or 0%-100%
339 · {named-color} is one of the following colors:
341 AliceBlue, AntiqueWhite, Aqua, Aquamarine, Azure, Beige, Bisque,
343 Black, BlanchedAlmond, Blue, BlueViolet, Brown, BurlyWood, Cadet‐
344 Blue, Chartreuse, Chocolate, Coral, CornflowerBlue, Cornsilk, Crim‐
345 son, Cyan, DarkBlue, DarkCyan, DarkGoldenRod, DarkGray, DarkGrey,
346 DarkGreen, DarkKhaki, DarkMagenta, DarkOliveGreen, DarkOrange,
347 DarkOrchid, DarkRed, DarkSalmon, DarkSeaGreen, DarkSlateBlue, Dark‐
348 SlateGray, DarkSlateGrey, DarkTurquoise, DarkViolet, DeepPink,
349 DeepSkyBlue, DimGray, DimGrey, DodgerBlue, FireBrick, FloralWhite,
350 ForestGreen, Fuchsia, Gainsboro, GhostWhite, Gold, GoldenRod, Gray,
351 Grey, Green, GreenYellow, HoneyDew, HotPink, IndianRed, Indigo,
352 Ivory, Khaki, Lavender, LavenderBlush, LawnGreen, LemonChiffon,
353 LightBlue, LightCoral, LightCyan, LightGoldenRodYellow, LightGray,
354 LightGrey, LightGreen, LightPink, LightSalmon, LightSeaGreen,
355 LightSkyBlue, LightSlateGray, LightSlateGrey, LightSteelBlue,
356 LightYellow, Lime, LimeGreen, Linen, Magenta, Maroon, MediumAquaMa‐
357 rine, MediumBlue, MediumOrchid, MediumPurple, MediumSeaGreen, Medi‐
358 umSlateBlue, MediumSpringGreen, MediumTurquoise, MediumVioletRed,
359 MidnightBlue, MintCream, MistyRose, Moccasin, NavajoWhite, Navy,
360 OldLace, Olive, OliveDrab, Orange, OrangeRed, Orchid, PaleGolden‐
361 Rod, PaleGreen, PaleTurquoise, PaleVioletRed, PapayaWhip, Peach‐
362 Puff, Peru, Pink, Plum, PowderBlue, Purple, RebeccaPurple, Red,
363 RosyBrown, RoyalBlue, SaddleBrown, Salmon, SandyBrown, SeaGreen,
364 SeaShell, Sienna, Silver, SkyBlue, SlateBlue, SlateGray, SlateGrey,
365 Snow, SpringGreen, SteelBlue, Tan, Teal, Thistle, Tomato,
366 Turquoise, Violet, Wheat, White, WhiteSmoke, Yellow, Yellow‐
367 Green,transparent
368 For example:
372 background-color: #FF0000;
376 border-color: rgba(0,0,1, 0.5);
377 text-color: SeaGreen;
378 or
382 background-color: transparent;
386 text-color: Black;
387
391 · Format: (bold|italic|underline|strikethrough|none)
392 Text style indicates how the highlighted text is emphasized. None indi‐
396 cates that no emphasis should be applied.
397 · bold: make the text thicker then the surrounding text.
399 · italic: put the highlighted text in script type (slanted).
401 · underline: put a line under the highlighted text.
403 · strikethrough: put a line through the highlighted text.
405 · small caps: emphasise the text using capitalization.
407
411 · Format: (dash|solid)
412 Indicates how a line should be drawn. It currently supports: * dash: a
416 dashed line, where the gap is the same width as the dash * solid: a
417 solid line
418
420 · Format: {Integer}px
421 · Format: {Real}em
423 · Format: {Real}ch
425 · Format: {Real}%
427 A distance can be specified in 3 different units:
431 · px: Screen pixels.
433 · em: Relative to text height.
435 · ch: Relative to width of a single number.
437 · %: Percentage of the monitor size.
439 Distances used in the horizontal direction use the monitor width. Dis‐
443 tances in the vertical direction use the monitor height. For example:
444 padding: 10%;
448 On a full-HD (1920x1080) monitor, it defines a padding of 192 pixels on
452 the left and right side and 108 pixels on the top and bottom.
453
455 · Format: {Integer}
456 · Format: {Distance}
458 · Format: {Distance} {Distance}
460 · Format: {Distance} {Distance} {Distance}
462 · Format: {Distance} {Distance} {Distance} {Distance}
464 If no unit is specified, pixels are used.
468 The different number of fields in the formats are parsed like:
470 · 1 field: all
472 · 2 fields: top&bottom left&right
474 · 3 fields: top, left&right, bottom
476 · 4 fields: top, right, bottom, left
478
482 · Format: {Integer}
483 · Format: {Distance}
485 · Format: {Distance} {Distance}
487 · Format: {Distance} {Distance} {Distance}
489 · Format: {Distance} {Distance} {Distance} {Distance}
491 · Format: {Distance} {Line style}
493 · Format: {Distance} {Line style} {Distance} {Line style}
495 · Format: {Distance} {Line style} {Distance} {Line style} {Distance}
497 {Line style}
498 · Format: {Distance} {Line style} {Distance} {Line style} {Distance}
500 {Line style} {Distance} {Line style}
501 Borders are identical to padding, except that each distance field has a
505 line style property.
506
508 Indicate a place on the window/monitor.
509 · Format: (center|east|north|west|south|north east|north west|south
511 west|south east)
512 north west | north | north east
519 -------------|-------------|------------
520 west | center | east
521 -------------|-------------|------------
522 south west | south | south east
523
527 It is possible to hide widgets:
528 inputbar { enabled: false; }
530
532 · Format: @{PROPERTY NAME}
533 A reference can point to another reference. Currently, the maximum num‐
537 ber of redirects is 20. A property always refers to another property.
538 It cannot be used for a subpart of the property. For example, this is
539 not valid:
540 highlight: bold @pink;
544 But this is:
548 * {
552 myhigh: bold #FAA;
553 }
554 window {
556 highlight: @myhigh;
557 }
558
562 · Format: (horizontal|vertical)
563 Specify the orientation of the widget.
567
569 · Format: [ keyword, keyword ]
570 A list starts with a ´[´ and ends with a ´]´. The entries in the list
574 are comma-separated. The keyword in the list refers to an widget name.
575
577 · Format: inherit
578 Inherits the property from its parent widget.
582 mainbox {
586 border-color: inherit;
587 }
588
592 Element paths exists of two parts, the first part refers to the actual
593 widget by name. Some widgets have an extra state.
594 For example:
596 element selected {
600 }
601 Here element selected is the name of the widget, selected is the state
605 of the widget.
606 The difference between dots and spaces is purely cosmetic. These are
608 all the same:
609 element .selected {
613 element.selected {
615 }
616 element selected {
617 }
618
623 The current widgets available in rofi:
624 ·
626 · overlay: the overlay widget.
628 ·
630 ·
632 · box: the horizontal @box packing the widgets
634 · case-indicator: the case/sort indicator @textbox
636 · prompt: the prompt @textbox
638 · entry: the main entry @textbox
640 ·
645 · scrollbar: the listview scrollbar
647 · element: the entries in the listview
649 ·
654 · button: the buttons @textbox for each mode
656 ·
661 · textbox: the message textbox
663 Note that these path names match the default theme. Themes that provide
676 a custom layout will have different element paths.
677
679 State: State of widget
680 Optional flag(s) indicating state of the widget, used for theming.
682 These are appended after the name or class of the widget.
684 Example:
686 button selected.normal { }
687 element selected.urgent { }
689 Currently only the entrybox and scrollbar have states:
691 Entrybox:
693 {visible modifier}.{state}
694 Where visible modifier can be: * normal: no modification * selected:
696 the entry is selected/highlighted by user * alternate: the entry is at
697 an alternating row (uneven row)
698 Where state is: * normal: no modification * urgent: this entry is
700 marked urgent * active: this entry is marked active
701 These can be mixed.
703 Example:
705 nametotextbox selected.active {
709 background-color: #003642;
710 text-color: #008ed4;
711 }
712 Sets all selected textboxes marked active to the given foreground and
716 background color. Note that a state modifies the original element, it
717 therefore contains all the properties of that element.
718 Scrollbar
720 The scrollbar uses the handle state when drawing the small scrollbar
721 handle. This allows the colors used for drawing the handle to be set
722 independently.
723
725 The following properties are currently supported:
726 all widgets:
728 · padding: padding Padding on the inside of the widget
729 · margin: padding Margin on the outside of the widget
731 · border: border Border around the widget (between padding and mar‐
733 gin)/
734 · border-radius: padding Sets a radius on the corners of the borders.
736 · background: color Background color
738 · foreground: color Foreground color
740 · index: integer (This one does not inherit it value from the parent
742 widget)
743 window:
747 · font: string The font used in the window
748 · transparency: string Indicating if transparency should be used and
750 what type: real - True transparency. Only works with a compositor.
751 background - Take a screenshot of the background image and use
752 that. screenshot - Take a screenshot of the screen and use that.
753 Path to png file - Use an image.
754 · location: position The place of the anchor on the monitor
756 · anchor: anchor The anchor position on the window
758 · fullscreen: boolean Window is fullscreen.
760 · width: distance The width of the window
762 · x-offset: distance
764 · y-offset: distance The offset of the window to the anchor point,
766 allowing you to push the window left/right/up/down
767 scrollbar:
771 · background-color: color
772 · handle-width: distance
774 · handle-color: color
776 · border-color: color
778 box:
782 · orientation: orientation Set the direction the elements are packed.
783 · spacing: distance Distance between the packed elements.
785 textbox:
789 · background: color
790 · foreground: color
792 · font: the font used by this textbox (string)
794 · str: the string to display by this textbox (string)
796 · vertical-align: vertical alignment of the text (0 top, 1 bottom)
798 · horizontal-align: horizontal alignment of the text (0 left, 1
800 right)
801 · text: the text color to use (falls back to foreground if not set)
803 · highlight: text style {color} color is optional, multiple highlight
805 styles can be added like: bold underline italic #000000;
806 · width: override the desired width for the textbox
808 listview:
812 · columns: integer Number of columns to show (at least 1)
813 · fixed-height: boolean Always show lines rows, even if fewer ele‐
815 ments are available.
816 · dynamic: boolean True if the size should change when filtering the
818 list, False if it should keep the original height.
819 · scrollbar: boolean If the scrollbar should be enabled/disabled.
821 · scrollbar-width: distance Width of the scrollbar
823 · cycle: boolean When navigating, it should wrap around
825 · spacing: distance Spacing between the elements (both vertical and
827 horizontal)
828 · lines: integer Number of rows to show in the list view.
830 · layout: orientation Indicate how elements are stacked. Horizontal
832 implements the dmenu style.
833
837 The new format allows the layout of the rofi window to be tweaked
838 extensively. For each widget, the themer can specify padding, margin,
839 border, font, and more. It even allows, as an advanced feature, to pack
840 widgets in a custom structure.
841 Basic structure
843 The whole view is made out of boxes that pack other boxes or widgets.
844 The box can be vertical or horizontal. This is loosely inspired by GTK
845 http://gtk.org/.
846 The current layout of rofi is structured as follows:
848 |------------------------------------------------------------------------------------|
852 | window {BOX:vertical} |
853 | |-------------------------------------------------------------------------------| |
854 | | mainbox {BOX:vertical} | |
855 | | |---------------------------------------------------------------------------| | |
856 | | | inputbar {BOX:horizontal} | | |
857 | | | |---------| |-----------------------------------------------------| |---| | | |
858 | | | | prompt | | entry | |ci | | | |
859 | | | |---------| |-----------------------------------------------------| |---| | | |
860 | | |---------------------------------------------------------------------------| | |
861 | | | |
862 | | |---------------------------------------------------------------------------| | |
863 | | | message | | |
864 | | | |-----------------------------------------------------------------------| | | |
865 | | | | textbox | | | |
866 | | | |-----------------------------------------------------------------------| | | |
867 | | |---------------------------------------------------------------------------| | |
868 | | | |
869 | | |-----------------------------------------------------------------------------| |
870 | | | listview | |
871 | | |-----------------------------------------------------------------------------| |
872 | | | |
873 | | |---------------------------------------------------------------------------| | |
874 | | | sidebar {BOX:horizontal} | | |
875 | | | |---------------| |---------------| |--------------| |---------------| | | |
876 | | | | Button | | Button | | Button | | Button | | | |
877 | | | |---------------| |---------------| |--------------| |---------------| | | |
878 | | |---------------------------------------------------------------------------| | |
879 | |-------------------------------------------------------------------------------| |
880 |------------------------------------------------------------------------------------|
881 Advanced layout
885 The layout of rofi can be tweaked by packing the ´fixed´ widgets in a
886 custom structure.
887 The following widgets are fixed, as they provide core rofi functional‐
889 ity:
890 · prompt
892 · entry
894 · case-indicator
896 · message
898 · listview
900 · sidebar
902 The following keywords are defined and can be used to automatically
906 pack a subset of the widgets. These are used in the default theme as
907 depicted in the figure above.
908 · mainbox Packs: inputbar, message, listview, sidebar
910 · inputbar Packs: prompt,entry,case-indicator
912 Any widget name starting with textbox is a textbox widget, others are
916 box widgets and can pack other widgets. To specify children, set the
917 children property (this always happens on the box child, see example
918 below):
919 children: [prompt,entry,case-indicator];
923 The theme needs to be updated to match the hierarchy specified.
927 Below is an example of a theme emulating dmenu:
929 * {
933 background-color: Black;
934 text-color: White;
935 border-color: White;
936 font: "Times New Roman 12";
937 }
938 window {
940 anchor: north;
941 location: north;
942 width: 100%;
943 padding: 4px;
944 children: [ horibox ];
945 }
946 horibox {
948 orientation: horizontal;
949 children: [ prompt, entry, listview ];
950 }
951 listview {
953 layout: horizontal;
954 spacing: 5px;
955 lines: 10;
956 }
957 entry {
959 expand: false;
960 width: 10em;
961 }
962 element {
964 padding: 0px 2px;
965 }
966 element selected {
967 background-color: SteelBlue;
968 }
969 Padding and margin
973 Just like CSS, rofi uses the box model for each widget.
974 |-------------------------------------------------------------------|
978 | margin |
979 | |-------------------------------------------------------------| |
980 | | border | |
981 | | |---------------------------------------------------------| | |
982 | | | padding | | |
983 | | | |-----------------------------------------------------| | | |
984 | | | | content | | | |
985 | | | |-----------------------------------------------------| | | |
986 | | |---------------------------------------------------------| | |
987 | |-------------------------------------------------------------| |
988 |-------------------------------------------------------------------|
989 Explanation of the different parts:
993 · Content - The content of the widget.
995 · Padding - Clears an area around the widget. The padding shows the
997 background color of the widget.
998 · Border - A border that goes around the padding and content. The
1000 border use the foreground color of the widget.
1001 · Margin - Clears an area outside the border. The margin is transpar‐
1003 ent.
1004 The box model allows us to add a border around elements, and to define
1008 space between elements.
1009 The size of each margin, border, and padding can be set. For the bor‐
1011 der, a linestyle and radius can be set.
1012 Spacing
1014 Widgets that can pack more then one child widget (currently box and
1015 listview) have the spacing property. This property sets the distance
1016 between the packed widgets (both horizontally and vertically).
1017 |---------------------------------------|
1021 | |--------| s |--------| s |-------| |
1022 | | child | p | child | p | child | |
1023 | | | a | | a | | |
1024 | | | c | | c | | |
1025 | | | i | | i | | |
1026 | | | n | | n | | |
1027 | |--------| g |--------| g |-------| |
1028 |---------------------------------------|
1029 Advanced box packing
1033 More dynamic spacing can be achieved by adding dummy widgets, for exam‐
1034 ple to make one widget centered:
1035 |--------------------------------------------|
1039 | |-----------| |--------| |-----------| |
1040 | | dummy | | child | | dummy | |
1041 | | expand: y | | | | expand: y | |
1042 | | | | | | | |
1043 | | | | | | | |
1044 | | | | | | | |
1045 | |-----------| |--------| |-----------| |
1046 |--------------------------------------------|
1047 If both dummy widgets are set to expand, child will be centered.
1051 Depending on the expand flag of child the remaining space will be
1052 equally divided between both dummy and child widget (expand enabled),
1053 or both dummy widgets (expand disabled).
1054
1056 To get debug information from the parser, run rofi like:
1057 G_MESSAGES_DEBUG=Parser rofi -show run
1061 Syntax errors are shown in a popup and printed out to command line with
1065 the above command.
1066 To see the elements queried during running, run:
1068 G_MESSAGES_DEBUG=Theme rofi -show run
1072 To test minor changes, part of the theme can be passed on the command
1076 line, for example to set it to full-screen:
1077 rofi -theme-str ´#window { fullscreen:true;}´ -show run
1081 To print the current theme, run:
1085 rofi -dump-theme
1089
1093 Several examples are installed together with rofi. These can be found
1094 in {datadir}/rofi/themes/, where {datadir} is the install path of rofi
1095 data. When installed using a package manager, this is usually:
1096 /usr/share/.
1097
1099 rofi(1)
1100 February 2018 ROFI-THEME(5)