1# ROFI-THEME 5 rofi-theme 2 3## NAME 4 5**rofi-theme** - Rofi theme format files 6 7## DESCRIPTION 8 9The need for a new theme format was motivated by the fact that the way rofi handled widgets has changed. From a very 10static drawing of lines and text to a nice structured form of packing widgets. This change made it possible to provide a 11more flexible theme framework. The old theme format and config file are not flexible enough to expose these options in a 12user-friendly way. Therefore, a new file format has been created, replacing the old one. 13 14## FORMAT SPECIFICATION 15 16## Encoding 17 18The encoding of the file is utf-8. Both unix (`\n`) and windows (`\r\n`) newlines format are supported. But unix is 19preferred. 20 21## Comments 22 23C and C++ file comments are supported. 24 25* Anything after `// ` and before a newline is considered a comment. 26* Everything between `/*` and `*/` is a comment. 27 28Comments can be nested and the C comments can be inline. 29 30The following is valid: 31 32``` 33// Magic comment. 34property: /* comment */ value; 35``` 36 37However, this is not: 38 39``` 40prop/*comment*/erty: value; 41``` 42 43## White space 44 45White space and newlines, like comments, are ignored by the parser. 46 47This: 48 49``` 50property: name; 51``` 52 53Is identical to: 54 55``` 56 property : 57name 58 59; 60``` 61 62## File extension 63 64The preferred file extension for the new theme format is **rasi**. This is an 65abbreviation for **r**ofi **a**dvanced **s**tyle **i**nformation. 66 67## Basic Structure 68 69Each element has a section with defined properties. Global properties can be defined in section `* { }`. 70Sub-section names begin with a hash symbol `#`. 71 72It is advised to define the *global properties section* on top of the file to 73make inheritance of properties clearer. 74 75``` 76/* Global properties section */ 77* { 78 // list of properties 79} 80 81/* Element theme section. */ 82{element path} { 83 // list of properties 84} 85{elements... } { 86 // list of properties 87} 88``` 89 90If there are multiple sections with the same name, they are merged. Duplicate properties are overwritten and the last 91parsed entry kept. 92 93## Global properties section 94 95A theme can have one or more global properties sections. If there is more than one, 96they will be merged. 97 98The global properties section denotes the defaults for each element. 99Each property of this section can be referenced with `@{identifier}` 100(See Properties section) 101 102A global properties section is indicated with a `*` as element path. 103 104## Element theme section 105 106A theme can have multiple element theme sections. 107 108The element path can consist of multiple names separated by whitespace or dots. 109Each element may contain any number of letters, numbers and `-`'s. 110The first element in the element path should always start with a `#`. 111Multiple elements can be specified by a `,`. 112 113This is a valid element name: 114 115``` 116element normal.normal { 117 background-color: blue; 118} 119button { 120 background-color: blue; 121} 122``` 123 124And is identical to: 125 126``` 127element normal normal, button { 128 background-color: blue; 129} 130``` 131 132Each section inherits the global properties. Properties can be explicitly inherited from their parent with the 133`inherit` keyword. 134In the following example: 135 136``` 137window { 138 a: 1; 139 b: 2; 140 children: [ mainbox ]; 141} 142mainbox { 143 a: inherit; 144 b: 4; 145 c: 8; 146} 147``` 148 149The element `mainbox` will have the following set of properties (if `mainbox` is a child of `window`): 150 151``` 152a: 1; 153b: 4; 154c: 8; 155``` 156 157If multiple sections are defined with the same name, they are merged by the 158parser. If multiple properties with the same name are defined in one section, 159the last encountered property is used. 160 161## Properties Format 162 163The properties in a section consist of: 164 165``` 166{identifier}: {value}; 167``` 168 169Both fields are mandatory for a property. 170 171The `identifier` names the specified property. Identifiers can consist of any 172combination of numbers, letters and '-'. It must not contain any whitespace. 173The structure of the `value` defines the type of the property. The current 174parser does not define or enforce a certain type of a particular `identifier`. 175When used, values with the wrong type that cannot be converted are ignored. 176 177The current theme format supports different types: 178 179 * a string 180 * an integer number 181 * a fractional number 182 * a boolean value 183 * a color 184 * text style 185 * line style 186 * a distance 187 * a padding 188 * a border 189 * a position 190 * a reference 191 * an orientation 192 * a list of keywords 193 * an environment variable 194 * Inherit 195 196Some of these types are a combination of other types. 197 198## String 199 200* Format: `"[:print:]+"` 201 202A string is always surrounded by double quotes (`"`). Between the quotes there can be any printable character. 203 204For example: 205 206``` 207font: "Awasome 12"; 208``` 209 210The string must be valid UTF-8. 211 212## Integer 213 214* Format: `[-+]?[:digit:]+` 215 216An integer may contain any number. 217 218For examples: 219 220``` 221lines: 12; 222``` 223 224## Real 225 226* Format: `[-+]?[:digit:]+(\.[:digit:]+)?` 227 228A real is an integer with an optional fraction. 229 230For example: 231 232``` 233real: 3.4; 234``` 235 236The following is not valid: `.3`, `3.` or scientific notation: `3.4e-3`. 237 238## Boolean 239 240* Format: `(true|false)` 241 242Boolean value is either `true` or `false`. This is case-sensitive. 243 244 245For example: 246 247``` 248dynamic: false; 249``` 250 251## Color 252 253**rofi** supports the color formats as specified in the CSS standard (1,2,3 and some of CSS 4) 254 255* Format: `#{HEX}{3}` (rgb) 256* Format: `#{HEX}{4}` (rgba) 257* Format: `#{HEX}{6}` (rrggbb) 258* Format: `#{HEX}{8}` (rrggbbaa) 259* Format: `rgb[a]({INTEGER},{INTEGER},{INTEGER}[, {PERCENTAGE}])` 260* Format: `rgb[a]({INTEGER}%,{INTEGER}%,{INTEGER}%[, {PERCENTAGE}])` 261* Format: `hsl[a]( {ANGLE}, {PERCENTAGE}, {PERCENTAGE} [, {PERCENTAGE}])` 262* Format: `hwb[a]( {ANGLE}, {PERCENTAGE}, {PERCENTAGE} [, {PERCENTAGE}])` 263* Format: `cmyk( {PERCENTAGE}, {PERCENTAGE}, {PERCENTAGE}, {PERCENTAGE} [, {PERCENTAGE} ])` 264* Format: `{named-color} [ / {PERCENTAGE} ]` 265 266The white-space format proposed in CSS4 is also supported. 267 268The different values are: 269 270 * `{HEX}` is a hexadecimal number ('0-9a-f' case insensitive). 271 * `{INTEGER}` value can be between 0 and 255 or 0-100 when representing percentage. 272 * `{ANGLE}` is the angle on the color wheel, can be in `deg`, `rad`, `grad` or `turn`. When no unit is specified, degrees is assumed. 273 * `{PERCENTAGE}` can be between 0-1.0, or 0%-100% 274 * `{named-color}` is one of the following colors: 275 276 AliceBlue, AntiqueWhite, Aqua, Aquamarine, Azure, Beige, Bisque, Black, BlanchedAlmond, Blue, BlueViolet, Brown, 277 BurlyWood, CadetBlue, Chartreuse, Chocolate, Coral, CornflowerBlue, Cornsilk, Crimson, Cyan, DarkBlue, DarkCyan, 278 DarkGoldenRod, DarkGray, DarkGrey, DarkGreen, DarkKhaki, DarkMagenta, DarkOliveGreen, DarkOrange, DarkOrchid, DarkRed, 279 DarkSalmon, DarkSeaGreen, DarkSlateBlue, DarkSlateGray, DarkSlateGrey, DarkTurquoise, DarkViolet, DeepPink, DeepSkyBlue, 280 DimGray, DimGrey, DodgerBlue, FireBrick, FloralWhite, ForestGreen, Fuchsia, Gainsboro, GhostWhite, Gold, GoldenRod, 281 Gray, Grey, Green, GreenYellow, HoneyDew, HotPink, IndianRed, Indigo, Ivory, Khaki, Lavender, LavenderBlush, LawnGreen, 282 LemonChiffon, LightBlue, LightCoral, LightCyan, LightGoldenRodYellow, LightGray, LightGrey, LightGreen, LightPink, 283 LightSalmon, LightSeaGreen, LightSkyBlue, LightSlateGray, LightSlateGrey, LightSteelBlue, LightYellow, Lime, LimeGreen, 284 Linen, Magenta, Maroon, MediumAquaMarine, MediumBlue, MediumOrchid, MediumPurple, MediumSeaGreen, MediumSlateBlue, 285 MediumSpringGreen, MediumTurquoise, MediumVioletRed, MidnightBlue, MintCream, MistyRose, Moccasin, NavajoWhite, Navy, 286 OldLace, Olive, OliveDrab, Orange, OrangeRed, Orchid, PaleGoldenRod, PaleGreen, PaleTurquoise, PaleVioletRed, 287 PapayaWhip, PeachPuff, Peru, Pink, Plum, PowderBlue, Purple, RebeccaPurple, Red, RosyBrown, RoyalBlue, SaddleBrown, 288 Salmon, SandyBrown, SeaGreen, SeaShell, Sienna, Silver, SkyBlue, SlateBlue, SlateGray, SlateGrey, Snow, SpringGreen, 289 SteelBlue, Tan, Teal, Thistle, Tomato, Turquoise, Violet, Wheat, White, WhiteSmoke, Yellow, YellowGreen,transparent 290 291 292 293For example: 294 295``` 296background-color: #FF0000; 297border-color: rgba(0,0,1, 0.5); 298text-color: SeaGreen; 299``` 300or 301 302``` 303background-color: transparent; 304text-color: Black; 305``` 306 307## Text style 308 309* Format: `(bold|italic|underline|strikethrough|none)` 310 311Text style indicates how the highlighted text is emphasized. `None` indicates that no emphasis 312should be applied. 313 314 * `bold`: make the text thicker then the surrounding text. 315 * `italic`: put the highlighted text in script type (slanted). 316 * `underline`: put a line under the highlighted text. 317 * `strikethrough`: put a line through the highlighted text. 318 * `small caps`: emphasise the text using capitalization. 319 320> For some reason `small caps` does not work on some systems. 321 322## Line style 323 324* Format: `(dash|solid)` 325 326Indicates how a line should be drawn. 327It currently supports: 328 * `dash`: a dashed line, where the gap is the same width as the dash 329 * `solid`: a solid line 330 331## Distance 332 333* Format: `{Integer}px` 334* Format: `{Real}em` 335* Format: `{Real}ch` 336* Format: `{Real}%` 337* Format: `{Integer}mm` 338 339A distance can be specified in 3 different units: 340 341* `px`: Screen pixels. 342* `em`: Relative to text height. 343* `ch`: Relative to width of a single number. 344* `mm`: Actual size in millimeters (based on dpi). 345* `%`: Percentage of the **monitor** size. 346 347Distances used in the horizontal direction use the monitor width. Distances in 348the vertical direction use the monitor height. 349For example: 350 351``` 352 padding: 10%; 353``` 354On a full-HD (1920x1080) monitor, it defines a padding of 192 pixels on the left 355and right side and 108 pixels on the top and bottom. 356 357### Calculating sizes 358 359Rofi supports some maths in calculating sizes. For this it uses the CSS syntax: 360 361``` 362width: calc( 100% - 37px ); 363``` 364 365It supports the following operations: 366 367* `+` : Add 368* `-` : Subtract 369* `/` : Divide 370* `*` : Multiply 371* `%` : Multiply 372* `min` : Minimum of l or rvalue; 373* `max` : Maximum of l or rvalue; 374 375It uses the C precedence ordering. 376 377## Padding 378 379* Format: `{Integer}` 380* Format: `{Distance}` 381* Format: `{Distance} {Distance}` 382* Format: `{Distance} {Distance} {Distance}` 383* Format: `{Distance} {Distance} {Distance} {Distance}` 384 385If no unit is specified, pixels are assumed. 386 387The different number of fields in the formats are parsed like: 388 389* 1 field: `all` 390* 2 fields: `top&bottom` `left&right` 391* 3 fields: `top`, `left&right`, `bottom` 392* 4 fields: `top`, `right`, `bottom`, `left` 393 394 395## Border 396 397* Format: `{Integer}` 398* Format: `{Distance}` 399* Format: `{Distance} {Distance}` 400* Format: `{Distance} {Distance} {Distance}` 401* Format: `{Distance} {Distance} {Distance} {Distance}` 402* Format: `{Distance} {Line style}` 403* Format: `{Distance} {Line style} {Distance} {Line style}` 404* Format: `{Distance} {Line style} {Distance} {Line style} {Distance} {Line style}` 405* Format: `{Distance} {Line style} {Distance} {Line style} {Distance} {Line style} {Distance} {Line style}` 406 407Borders are identical to padding, except that each distance field has a line 408style property. 409 410> When no unit is specified, pixels are assumed. 411 412## Position 413 414Indicate a place on the window/monitor. 415 416* Format: `(center|east|north|west|south|north east|north west|south west|south east)` 417 418``` 419 420north west | north | north east 421-------------|-------------|------------ 422 west | center | east 423-------------|-------------|------------ 424south west | south | south east 425``` 426 427## Visibility 428 429It is possible to hide widgets: 430 431inputbar { 432 enabled: false; 433} 434 435## Reference 436 437* Format: `@{PROPERTY NAME}` 438 439A reference can point to another reference. Currently, the maximum number of redirects is 20. 440A property always refers to another property. It cannot be used for a subpart of the property. 441For example, this is not valid: 442 443``` 444highlight: bold @pink; 445``` 446 447But this is: 448 449``` 450* { 451 myhigh: bold #FAA; 452} 453 454window { 455 highlight: @myhigh; 456} 457``` 458 459## Orientation 460 461 * Format: `(horizontal|vertical)` 462 463Specify the orientation of the widget. 464 465## List of keywords 466 467* Format: `[ keyword, keyword ]` 468 469A list starts with a '[' and ends with a ']'. The entries in the list are comma-separated. 470The `keyword` in the list refers to an widget name. 471 472## Environment variable 473 474* Format: `${:alnum:}` 475 476This will parse the environment variable as the property value. (that then can be any of the above types). 477The environment variable should be an alphanumeric string without white-space. 478 479``` 480* { 481 background-color: ${BG}; 482} 483``` 484 485## Inherit 486 487 * Format: `inherit` 488 489Inherits the property from its parent widget. 490 491``` 492mainbox { 493 border-color: inherit; 494} 495``` 496 497 498## ELEMENTS PATHS 499 500Element paths exists of two parts, the first part refers to the actual widget by name. 501Some widgets have an extra state. 502 503For example: 504 505``` 506element selected { 507} 508``` 509 510Here `element selected` is the name of the widget, `selected` is the state of the widget. 511 512The difference between dots and spaces is purely cosmetic. These are all the same: 513 514``` 515element .selected { 516 517element.selected { 518} 519element selected { 520} 521``` 522 523## SUPPORTED ELEMENT PATH 524 525## Name 526 527The current widgets available in **rofi**: 528 529* `window` 530 * `overlay`: the overlay widget. 531 * `mainbox`: The mainbox box. 532 * `inputbar`: The input bar box. 533 * `box`: the horizontal @box packing the widgets 534 * `case-indicator`: the case/sort indicator @textbox 535 * `prompt`: the prompt @textbox 536 * `entry`: the main entry @textbox 537 * `num-rows`: Shows the total number of rows. 538 * `num-filtered-rows`: Shows the total number of rows after filtering. 539 * `listview`: The listview. 540 * `scrollbar`: the listview scrollbar 541 * `element`: a box in the listview holding the entries 542 * `element-icon`: the widget in the listview's entry showing the (optional) icon 543 * `element-index`: the widget in the listview's entry keybindable index (1,2,3..0) 544 * `element-text`: the widget in the listview's entry showing the text. 545 * `mode-switcher`: the main horizontal @box packing the buttons. 546 * `button`: the buttons @textbox for each mode 547 * `message`: The container holding the textbox. 548 * `textbox`: the message textbox 549 550Note that these path names match the default theme. Themes that provide a custom layout will have different 551elements, and structure. 552 553 554## State 555 556State: State of widget 557 558Optional flag(s) indicating state of the widget, used for theming. 559 560These are appended after the name or class of the widget. 561 562### Example: 563 564`button selected.normal { }` 565 566`element selected.urgent { }` 567 568Currently only the entrybox and scrollbar have states: 569 570### Entrybox: 571 572`{visible modifier}.{state}` 573 574Where `visible modifier` can be: 575 * normal: no modification 576 * selected: the entry is selected/highlighted by user 577 * alternate: the entry is at an alternating row (uneven row) 578 579Where `state` is: 580 * normal: no modification 581 * urgent: this entry is marked urgent 582 * active: this entry is marked active 583 584These can be mixed. 585 586Example: 587 588``` 589nametotextbox selected.active { 590 background-color: #003642; 591 text-color: #008ed4; 592} 593``` 594 595Sets all selected textboxes marked active to the given text and background color. 596Note that a state modifies the original element, it therefore contains all the properties of that element. 597 598### Scrollbar 599 600The scrollbar uses the `handle` state when drawing the small scrollbar handle. 601This allows the colors used for drawing the handle to be set independently. 602 603 604## SUPPORTED PROPERTIES 605 606The following properties are currently supported: 607 608### all widgets: 609 610* **enabled**: enable/disable the widget 611* **padding**: padding 612 Padding on the inside of the widget 613* **margin**: padding 614 Margin on the outside of the widget 615* **border**: border 616 Border around the widget (between padding and margin)/ 617* **border-radius**: padding 618 Sets a radius on the corners of the borders. 619* **background-color**: color 620 Background color 621* **border-color**: color 622 Color of the border 623 624### window: 625 626* **font**: string 627 The font used in the window 628 629* **transparency**: string 630 Indicating if transparency should be used and what type: 631 **real** - True transparency. Only works with a compositor. 632 **background** - Take a screenshot of the background image and use that. 633 **screenshot** - Take a screenshot of the screen and use that. 634 **Path** to png file - Use an image. 635 636* **location**: position 637 The place of the anchor on the monitor 638* **anchor**: anchor 639 The anchor position on the window 640* **fullscreen**: boolean 641 Window is fullscreen. 642* **width**: distance 643 The width of the window 644* **x-offset**: distance 645* **y-offset**: distance 646 The offset of the window to the anchor point, allowing you to push the window left/right/up/down 647 648 649### scrollbar: 650 651* **background-color**: color 652* **handle-width**: distance 653* **handle-color**: color 654* **border-color**: color 655 656### box: 657 658* **orientation**: orientation 659 Set the direction the elements are packed. 660* **spacing**: distance 661 Distance between the packed elements. 662 663### textbox: 664 665* **background-color**: color 666* **border-color**: the color used for the border around the widget. 667* **font**: the font used by this textbox (string). 668* **str**: the string to display by this textbox (string). 669* **vertical-align**: vertical alignment of the text (`0` top, `1` bottom). 670* **horizontal-align**: horizontal alignment of the text (`0` left, `1` right). 671* **text-color**: the text color to use. 672* **highlight**: text style {color}. 673 color is optional, multiple highlight styles can be added like: bold underline italic #000000; 674* **width**: override the desired width for the textbox. 675* **content**: Set the displayed text (String). 676* **placeholder**: Set the displayed text (String) when nothing is entered. 677* **placeholder-color**: Color of the placeholder text. 678* **blink**: Enable/Disable blinking on an input textbox (Boolean). 679 680### listview: 681* **columns**: integer 682 Number of columns to show (at least 1) 683* **fixed-height**: boolean 684 Always show `lines` rows, even if fewer elements are available. 685* **dynamic**: boolean 686 `True` if the size should change when filtering the list, `False` if it should keep the original height. 687* **scrollbar**: boolean 688 If the scrollbar should be enabled/disabled. 689* **scrollbar-width**: distance 690 Width of the scrollbar 691* **cycle**: boolean 692 When navigating, it should wrap around 693* **spacing**: distance 694 Spacing between the elements (both vertical and horizontal) 695* **lines**: integer 696 Number of rows to show in the list view. 697* **layout**: orientation 698 Indicate how elements are stacked. Horizontal implements the dmenu style. 699* **reverse**: boolean 700 Reverse the ordering (top down to bottom up). 701* **fixed-columns**: boolean 702 Do not reduce the number of columns shown when number of visible elements is not enough to fill them all. 703 704Each element is a `box` called `element`. Each `element` can contain an `element-icon` and `element-text`. 705 706### listview text highlight: 707 708The `element-text` widget in the `listview` is the one used to show the text. 709On this widget set the `highlight` property (only place this property is used) to change 710the style of highlighting. 711The `highlight` property consist of the `text-style` property and a color. 712 713To disable highlighting: 714 715```css 716 element-text { 717 highlight: None; 718 } 719``` 720 721To set to red underlined: 722 723```css 724 element-text { 725 highlight: underline red; 726 } 727``` 728 729## Layout 730 731The new format allows the layout of the **rofi** window to be tweaked extensively. 732For each widget, the themer can specify padding, margin, border, font, and more. 733It even allows, as an advanced feature, to pack widgets in a custom structure. 734 735### Basic structure 736 737The whole view is made out of boxes that pack other boxes or widgets. 738The box can be vertical or horizontal. This is loosely inspired by [GTK](http://gtk.org/). 739 740The current layout of **rofi** is structured as follows: 741 742``` 743|------------------------------------------------------------------------------------| 744| window {BOX:vertical} | 745| |-------------------------------------------------------------------------------| | 746| | mainbox {BOX:vertical} | | 747| | |---------------------------------------------------------------------------| | | 748| | | inputbar {BOX:horizontal} | | | 749| | | |---------| |-----------------------------------------------------| |---| | | | 750| | | | prompt | | entry | |ci | | | | 751| | | |---------| |-----------------------------------------------------| |---| | | | 752| | |---------------------------------------------------------------------------| | | 753| | | | 754| | |---------------------------------------------------------------------------| | | 755| | | message | | | 756| | | |-----------------------------------------------------------------------| | | | 757| | | | textbox | | | | 758| | | |-----------------------------------------------------------------------| | | | 759| | |---------------------------------------------------------------------------| | | 760| | | | 761| | |-----------------------------------------------------------------------------| | 762| | | listview | | 763| | |-----------------------------------------------------------------------------| | 764| | | | 765| | |---------------------------------------------------------------------------| | | 766| | | mode-switcher {BOX:horizontal} | | | 767| | | |---------------| |---------------| |--------------| |---------------| | | | 768| | | | Button | | Button | | Button | | Button | | | | 769| | | |---------------| |---------------| |--------------| |---------------| | | | 770| | |---------------------------------------------------------------------------| | | 771| |-------------------------------------------------------------------------------| | 772|------------------------------------------------------------------------------------| 773 774 775``` 776> ci is the case-indicator 777 778### Error message structure 779 780``` 781|-----------------------------------------------------------------------------------| 782| window {BOX:vertical} | 783| |------------------------------------------------------------------------------| | 784| | error-message {BOX:vertical} | | 785| | |-------------------------------------------------------------------------| | | 786| | | textbox | | | 787| | |-------------------------------------------------------------------------| | | 788| |------------------------------------------------------------------------------| | 789|-----------------------------------------------------------------------------------| 790 791 792``` 793 794### Advanced layout 795 796The layout of **rofi** can be tweaked by packing the 'fixed' widgets in a custom structure. 797 798The following widgets are fixed, as they provide core **rofi** functionality: 799 800 * prompt 801 * entry 802 * overlay 803 * case-indicator 804 * message 805 * listview 806 * mode-switcher 807 * num-rows 808 * num-filtered-rows 809 810The following keywords are defined and can be used to automatically pack a subset of the widgets. 811These are used in the default theme as depicted in the figure above. 812 813 * mainbox 814 Packs: `inputbar, message, listview, mode-switcher` 815 * inputbar 816 Packs: `prompt,entry,case-indicator` 817 818Any widget name starting with `textbox` is a textbox widget, others are box widgets and can pack other widgets. 819 820There are several special widgets that can be used by prefixing the name of the widget: 821 822* `textbox`: 823 This is a textbox widget. The displayed string can be set with `str`. 824* `icon`: 825 This is an icon widget. The displayed icon can be set with `filename` and size with `size`. 826* `button`: 827 This is a textbox widget that can have a 'clickable' action. 828 The `action` can be set to: 829 `ok` accept entry. 830 `custom` accept custom input. 831 `ok|alternate`: accept entry and launch alternate action (for run launch in terminal). 832 `custom|alternate`: accept custom input and launch alternate action. 833 834To specify children, set the `children` 835property (this always happens on the `box` child, see example below): 836 837``` 838children: [prompt,entry,overlay,case-indicator]; 839``` 840 841The theme needs to be updated to match the hierarchy specified. 842 843Below is an example of a theme emulating dmenu: 844 845```css 846* { 847 background-color: Black; 848 text-color: White; 849 border-color: White; 850 font: "Times New Roman 12"; 851} 852 853window { 854 anchor: north; 855 location: north; 856 width: 100%; 857 padding: 4px; 858 children: [ horibox ]; 859} 860 861horibox { 862 orientation: horizontal; 863 children: [ prompt, entry, listview ]; 864} 865 866listview { 867 layout: horizontal; 868 spacing: 5px; 869 lines: 10; 870} 871 872entry { 873 expand: false; 874 width: 10em; 875} 876 877element { 878 padding: 0px 2px; 879} 880element selected { 881 background-color: SteelBlue; 882} 883``` 884 885 886### Padding and margin 887 888Just like CSS, **rofi** uses the box model for each widget. 889 890``` 891|-------------------------------------------------------------------| 892| margin | 893| |-------------------------------------------------------------| | 894| | border | | 895| | |---------------------------------------------------------| | | 896| | | padding | | | 897| | | |-----------------------------------------------------| | | | 898| | | | content | | | | 899| | | |-----------------------------------------------------| | | | 900| | |---------------------------------------------------------| | | 901| |-------------------------------------------------------------| | 902|-------------------------------------------------------------------| 903``` 904 905Explanation of the different parts: 906 907 * Content - The content of the widget. 908 * Padding - Clears an area around the widget. 909 The padding shows the background color of the widget. 910 * Border - A border that goes around the padding and content. 911 The border use the border-color of the widget. 912 * Margin - Clears an area outside the border. 913 The margin is transparent. 914 915The box model allows us to add a border around elements, and to define space between elements. 916 917The size of each margin, border, and padding can be set. 918For the border, a linestyle and radius can be set. 919 920### Spacing 921 922Widgets that can pack more then one child widget (currently box and listview) have the `spacing` property. 923This property sets the distance between the packed widgets (both horizontally and vertically). 924 925``` 926|---------------------------------------| 927| |--------| s |--------| s |-------| | 928| | child | p | child | p | child | | 929| | | a | | a | | | 930| | | c | | c | | | 931| | | i | | i | | | 932| | | n | | n | | | 933| |--------| g |--------| g |-------| | 934|---------------------------------------| 935``` 936 937### Advanced box packing 938 939More dynamic spacing can be achieved by adding dummy widgets, for example to make one widget centered: 940 941``` 942|--------------------------------------------| 943| |-----------| |--------| |-----------| | 944| | dummy | | child | | dummy | | 945| | expand: y | | | | expand: y | | 946| | | | | | | | 947| | | | | | | | 948| | | | | | | | 949| |-----------| |--------| |-----------| | 950|--------------------------------------------| 951``` 952 953If both dummy widgets are set to expand, `child` will be centered. Depending on the `expand` flag of child the 954remaining space will be equally divided between both dummy and child widget (expand enabled), or both dummy widgets 955(expand disabled). 956 957## DEBUGGING 958 959To get debug information from the parser, run rofi like: 960 961``` 962G_MESSAGES_DEBUG=Parser rofi -show run 963``` 964 965Syntax errors are shown in a popup and printed out to command line with the above command. 966 967To see the elements queried during running, run: 968 969``` 970G_MESSAGES_DEBUG=Theme rofi -show run 971``` 972 973To test minor changes, part of the theme can be passed on the command line, for example to set it to full-screen: 974 975``` 976rofi -theme-str '#window { fullscreen:true;}' -show run 977``` 978 979To print the current theme, run: 980 981``` 982rofi -dump-theme 983``` 984 985## Media support 986 987Parts of the theme can be conditionally loaded, like the CSS `@media` option. 988 989``` 990@media ( min-width: 120 ) { 991 992} 993``` 994 995It supports the following keys as constraint: 996 997 * `min-width`: load when width is bigger or equal then value. 998 * `max-width`: load when width is smaller then value. 999 * `min-height`: load when height is bigger or equal then value. 1000 * `max-height`: load when height is smaller then value. 1001 * `min-aspect-ratio` load when aspect ratio is over value. 1002 * `max-aspect-ratio`: load when aspect ratio is under value. 1003 * `monitor-id`: The monitor id, see rofi -help for id's. 1004 1005@media takes an integer number or a fraction, for integer number `px` can be added. 1006 1007 1008``` 1009@media ( min-width: 120 px ) { 1010 1011} 1012``` 1013 1014## Multiple file handling 1015 1016The rasi file format offers two methods of including other files. 1017This can be used to modify existing themes, or have multiple variations on a theme. 1018 1019 * import: Import and parse a second file. 1020 * theme: Discard theme, and load file as a fresh theme. 1021 1022Syntax: 1023 1024``` 1025@import "myfile" 1026@theme "mytheme" 1027``` 1028 1029The specified file can either by *name*, *filename*,*full path*. 1030 1031If a filename is provided, it will try to resolve it in the following order: 1032 1033 * `${XDG_CONFIG_HOME}/rofi/themes/` 1034 * `${XDG_CONFIG_HOME}/rofi/` 1035 * `${XDG_DATA_HOME}/rofi/themes/` 1036 * `${INSTALL PREFIX}/share/rofi/themes/` 1037 1038A name is resolved as a filename by appending the `.rasi` extension. 1039 1040 1041 1042## EXAMPLES 1043 1044Several examples are installed together with **rofi**. These can be found in `{datadir}/rofi/themes/`, where 1045`{datadir}` is the install path of **rofi** data. When installed using a package manager, this is usually: `/usr/share/`. 1046 1047## SEE ALSO 1048 1049rofi(1), rofi-script(5), rofi-theme-selector(1) 1050