diff options
Diffstat (limited to 'doc/rofi-theme.5')
| -rw-r--r-- | doc/rofi-theme.5 | 239 |
1 files changed, 206 insertions, 33 deletions
diff --git a/doc/rofi-theme.5 b/doc/rofi-theme.5 index 646328fb..6c0f53af 100644 --- a/doc/rofi-theme.5 +++ b/doc/rofi-theme.5 @@ -19,11 +19,15 @@ preferred. .SH Comments .PP C and C++ file comments are supported. + +.RS .IP \(bu 2 Anything after \fB\fC//\fR and before a newline is considered a comment. .IP \(bu 2 Everything between \fB\fC/*\fR and \fB\fC*/\fR is a comment. +.RE + .PP Comments can be nested and the C comments can be inline. @@ -242,6 +246,8 @@ When used, values with the wrong type that cannot be converted are ignored. .PP The current theme format supports different types: + +.RS .IP \(bu 2 a string .IP \(bu 2 @@ -279,12 +285,18 @@ an environment variable .IP \(bu 2 Inherit +.RE + .PP Some of these types are a combination of other types. -.SH String.IP \(bu 2 +.SH String +.RS +.IP \(bu 2 Format: \fB\fC"[:print:]+"\fR +.RE + .PP A string is always surrounded by double quotes (\fB\fC"\fR). Between the quotes there can be any printable character. @@ -303,9 +315,13 @@ font: "Awasome 12"; .PP The string must be valid UTF\-8. -.SH Integer.IP \(bu 2 +.SH Integer +.RS +.IP \(bu 2 Format: \fB\fC[\-+]?[:digit:]+\fR +.RE + .PP An integer may contain any number. @@ -321,9 +337,13 @@ lines: 12; .fi .RE -.SH Real.IP \(bu 2 +.SH Real +.RS +.IP \(bu 2 Format: \fB\fC[\-+]?[:digit:]+(\\.[:digit:]+)?\fR +.RE + .PP A real is an integer with an optional fraction. @@ -342,9 +362,13 @@ real: 3.4; .PP The following is not valid: \fB\fC\&.3\fR, \fB\fC3.\fR or scientific notation: \fB\fC3.4e\-3\fR\&. -.SH Boolean.IP \(bu 2 +.SH Boolean +.RS +.IP \(bu 2 Format: \fB\fC(true|false)\fR +.RE + .PP Boolean value is either \fB\fCtrue\fR or \fB\fCfalse\fR\&. This is case\-\&sensitive. @@ -362,11 +386,14 @@ dynamic: false; .SH Image .PP -\fBrofi\fP support a very limited set of image formats. +\fBrofi\fP support a limited set of background\-image formats. + +.RS .IP \(bu 2 Format: url("path to image"); .IP \(bu 2 Format: url("path to image", scale); +where scale is: none, both, width, height .IP \(bu 2 Format: linear\-gradient(stop color,stop1, color, stop2 color, ...); .IP \(bu 2 @@ -376,21 +403,16 @@ where direction is: top,left,right,bottom. Format: linear\-gradient(angle, stop color,stop1, color, stop2 color, ...); Angle in deg,rad,grad (as used in color). +.RE + .PP Where the \fB\fCpath\fR is a string, and \fB\fCstop\fR color is of type color. -The \fB\fCscale\fR property can be: -.IP \(bu 2 -none -.IP \(bu 2 -both -.IP \(bu 2 -width -.IP \(bu 2 -height .SH Color .PP \fBrofi\fP supports the color formats as specified in the CSS standard (1,2,3 and some of CSS 4) + +.RS .IP \(bu 2 Format: \fB\fC#{HEX}{3}\fR (rgb) .IP \(bu 2 @@ -412,11 +434,15 @@ Format: \fB\fCcmyk( {PERCENTAGE}, {PERCENTAGE}, {PERCENTAGE}, {PERCENTAGE} [, {P .IP \(bu 2 Format: \fB\fC{named\-color} [ / {PERCENTAGE} ]\fR +.RE + .PP The white\-space format proposed in CSS4 is also supported. .PP The different values are: + +.RS .IP \(bu 2 \fB\fC{HEX}\fR is a hexadecimal number ('0\-9a\-f' case insensitive). .IP \(bu 2 @@ -445,6 +471,8 @@ PapayaWhip, PeachPuff, Peru, Pink, Plum, PowderBlue, Purple, RebeccaPurple, Red, Salmon, SandyBrown, SeaGreen, SeaShell, Sienna, Silver, SkyBlue, SlateBlue, SlateGray, SlateGrey, Snow, SpringGreen, SteelBlue, Tan, Teal, Thistle, Tomato, Turquoise, Violet, Wheat, White, WhiteSmoke, Yellow, YellowGreen,transparent +.RE + .PP For example: @@ -472,12 +500,18 @@ text\-color: Black; .fi .RE -.SH Text style.IP \(bu 2 +.SH Text style +.RS +.IP \(bu 2 Format: \fB\fC(bold|italic|underline|strikethrough|none)\fR +.RE + .PP Text style indicates how the highlighted text is emphasized. \fB\fCNone\fR indicates that no emphasis should be applied. + +.RS .IP \(bu 2 \fB\fCbold\fR: make the text thicker then the surrounding text. .IP \(bu 2 @@ -487,16 +521,24 @@ should be applied. .IP \(bu 2 \fB\fCstrikethrough\fR: put a line through the highlighted text. -.SH Line style.IP \(bu 2 +.RE + +.SH Line style +.RS +.IP \(bu 2 Format: \fB\fC(dash|solid)\fR +.RE + .PP Indicates how a line should be drawn. It currently supports: * \fB\fCdash\fR: a dashed line, where the gap is the same width as the dash * \fB\fCsolid\fR: a solid line -.SH Distance.IP \(bu 2 +.SH Distance +.RS +.IP \(bu 2 Format: \fB\fC{Integer}px\fR .IP \(bu 2 Format: \fB\fC{Real}em\fR @@ -507,8 +549,12 @@ Format: \fB\fC{Real}%\fR .IP \(bu 2 Format: \fB\fC{Integer}mm\fR +.RE + .PP A distance can be specified in 3 different units: + +.RS .IP \(bu 2 \fB\fCpx\fR: Screen pixels. .IP \(bu 2 @@ -520,6 +566,8 @@ A distance can be specified in 3 different units: .IP \(bu 2 \fB\fC%\fR: Percentage of the \fBmonitor\fP size. +.RE + .PP Distances used in the horizontal direction use the monitor width. Distances in the vertical direction use the monitor height. @@ -553,6 +601,8 @@ width: calc( 100% \- 37px ); .PP It supports the following operations: + +.RS .IP \(bu 2 \fB\fC+\fR : Add .IP \(bu 2 @@ -568,10 +618,14 @@ It supports the following operations: .IP \(bu 2 \fB\fCmax\fR : Maximum of l or rvalue; +.RE + .PP It uses the C precedence ordering. -.SH Padding.IP \(bu 2 +.SH Padding +.RS +.IP \(bu 2 Format: \fB\fC{Integer}\fR .IP \(bu 2 Format: \fB\fC{Distance}\fR @@ -582,11 +636,15 @@ Format: \fB\fC{Distance} {Distance} {Distance}\fR .IP \(bu 2 Format: \fB\fC{Distance} {Distance} {Distance} {Distance}\fR +.RE + .PP If no unit is specified, pixels are assumed. .PP The different number of fields in the formats are parsed like: + +.RS .IP \(bu 2 1 field: \fB\fCall\fR .IP \(bu 2 @@ -596,7 +654,11 @@ The different number of fields in the formats are parsed like: .IP \(bu 2 4 fields: \fB\fCtop\fR, \fB\fCright\fR, \fB\fCbottom\fR, \fB\fCleft\fR -.SH Border.IP \(bu 2 +.RE + +.SH Border +.RS +.IP \(bu 2 Format: \fB\fC{Integer}\fR .IP \(bu 2 Format: \fB\fC{Distance}\fR @@ -615,6 +677,8 @@ Format: \fB\fC{Distance} {Line style} {Distance} {Line style} {Distance} {Line s .IP \(bu 2 Format: \fB\fC{Distance} {Line style} {Distance} {Line style} {Distance} {Line style} {Distance} {Line style}\fR +.RE + .PP Borders are identical to padding, except that each distance field has a line style property. @@ -629,23 +693,28 @@ When no unit is specified, pixels are assumed. .SH Position .PP Indicate a place on the window/monitor. + +.RS .IP \(bu 2 -Format: \fB\fC(center|east|north|west|south|north east|north west|south west|south east)\fR .PP +Format: \fB\fC(center|east|north|west|south|north east|north west|south west|south east)\fR +.PP .RS .nf north west | north | north east \-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\- - west | center | east + west | center | east \-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\- south west | south | south east .fi .RE +.RE + .SH Visibility .PP It is possible to hide widgets: @@ -655,9 +724,13 @@ inputbar { enabled: false; } -.SH Reference.IP \(bu 2 +.SH Reference +.RS +.IP \(bu 2 Format: \fB\fC@{PROPERTY NAME}\fR +.RE + .PP A reference can point to another reference. Currently, the maximum number of redirects is 20. A property always refers to another property. It cannot be used for a subpart of the property. @@ -690,28 +763,44 @@ window { .fi .RE -.SH Orientation.IP \(bu 2 +.SH Orientation +.RS +.IP \(bu 2 Format: \fB\fC(horizontal|vertical)\fR +.RE + .PP Specify the orientation of the widget. -.SH Cursor.IP \(bu 2 +.SH Cursor +.RS +.IP \(bu 2 Format: \fB\fC(default|pointer|text)\fR +.RE + .PP Specify the type of mouse cursor that is set when the mouse pointer is over the widget. -.SH List of keywords.IP \(bu 2 +.SH List of keywords +.RS +.IP \(bu 2 Format: \fB\fC[ keyword, keyword ]\fR +.RE + .PP A list starts with a '[' and ends with a ']'. The entries in the list are comma\-separated. The \fB\fCkeyword\fR in the list refers to an widget name. -.SH Environment variable.IP \(bu 2 +.SH Environment variable +.RS +.IP \(bu 2 Format: \fB\fC${:alnum:}\fR +.RE + .PP This will parse the environment variable as the property value. (that then can be any of the above types). The environment variable should be an alphanumeric string without white\-space. @@ -727,9 +816,13 @@ The environment variable should be an alphanumeric string without white\-space. .fi .RE -.SH Inherit.IP \(bu 2 +.SH Inherit +.RS +.IP \(bu 2 Format: \fB\fCinherit\fR +.RE + .PP Inherits the property from its parent widget. @@ -786,14 +879,20 @@ element selected { .SH Name .PP The current widgets available in \fBrofi\fP: + +.RS .IP \(bu 2 \fB\fCwindow\fR + +.RS .IP \(bu 2 \fB\fCoverlay\fR: the overlay widget. .IP \(bu 2 \fB\fCmainbox\fR: The mainbox box. .IP \(bu 2 \fB\fCinputbar\fR: The input bar box. + +.RS .IP \(bu 2 \fB\fCbox\fR: the horizontal @box packing the widgets .IP \(bu 2 @@ -806,27 +905,49 @@ The current widgets available in \fBrofi\fP: \fB\fCnum\-rows\fR: Shows the total number of rows. .IP \(bu 2 \fB\fCnum\-filtered\-rows\fR: Shows the total number of rows after filtering. + +.RE .IP \(bu 2 \fB\fClistview\fR: The listview. + +.RS .IP \(bu 2 \fB\fCscrollbar\fR: the listview scrollbar .IP \(bu 2 \fB\fCelement\fR: a box in the listview holding the entries + +.RS .IP \(bu 2 \fB\fCelement\-icon\fR: the widget in the listview's entry showing the (optional) icon .IP \(bu 2 \fB\fCelement\-index\fR: the widget in the listview's entry keybindable index (1,2,3..0) .IP \(bu 2 \fB\fCelement\-text\fR: the widget in the listview's entry showing the text. + +.RE + +.RE .IP \(bu 2 \fB\fCmode\-switcher\fR: the main horizontal @box packing the buttons. + +.RS .IP \(bu 2 \fB\fCbutton\fR: the buttons @textbox for each mode + +.RE .IP \(bu 2 \fB\fCmessage\fR: The container holding the textbox. + +.RS .IP \(bu 2 \fB\fCtextbox\fR: the message textbox +.RE + +.RE + +.RE + .PP Note that these path names match the default theme. Themes that provide a custom layout will have different elements, and structure. @@ -898,7 +1019,9 @@ This allows the colors used for drawing the handle to be set independently. .PP The following properties are currently supported: -.SS all widgets:.IP \(bu 2 +.SS all widgets: +.RS +.IP \(bu 2 \fBenabled\fP: enable/disable the widget .IP \(bu 2 \fBpadding\fP: padding @@ -925,7 +1048,11 @@ Color of the border \fBcursor\fP: cursor Type of mouse cursor that is set when the mouse pointer is hovered over the widget. -.SS window:.IP \(bu 2 +.RE + +.SS window: +.RS +.IP \(bu 2 .PP \fBfont\fP: string @@ -969,7 +1096,11 @@ The width of the window \fBy\-offset\fP: distance The offset of the window to the anchor point, allowing you to push the window left/right/up/down -.SS scrollbar:.IP \(bu 2 +.RE + +.SS scrollbar: +.RS +.IP \(bu 2 \fBbackground\-color\fP: color .IP \(bu 2 \fBhandle\-width\fP: distance @@ -978,14 +1109,22 @@ The offset of the window to the anchor point, allowing you to push the window le .IP \(bu 2 \fBborder\-color\fP: color -.SS box:.IP \(bu 2 +.RE + +.SS box: +.RS +.IP \(bu 2 \fBorientation\fP: orientation Set the direction the elements are packed. .IP \(bu 2 \fBspacing\fP: distance Distance between the packed elements. -.SS textbox:.IP \(bu 2 +.RE + +.SS textbox: +.RS +.IP \(bu 2 \fBbackground\-color\fP: color .IP \(bu 2 \fBborder\-color\fP: the color used for the border around the widget. @@ -1015,7 +1154,11 @@ color is optional, multiple highlight styles can be added like: bold underline i .IP \(bu 2 \fBmarkup\fP: Force markup on, beware that only valid pango markup strings are shown. -.SS listview:.IP \(bu 2 +.RE + +.SS listview: +.RS +.IP \(bu 2 \fBcolumns\fP: integer Number of columns to show (at least 1) .IP \(bu 2 @@ -1049,6 +1192,8 @@ Reverse the ordering (top down to bottom up). \fBfixed\-columns\fP: boolean Do not reduce the number of columns shown when number of visible elements is not enough to fill them all. +.RE + .PP Each element is a \fB\fCbox\fR called \fB\fCelement\fR\&. Each \fB\fCelement\fR can contain an \fB\fCelement\-icon\fR and \fB\fCelement\-text\fR\&. @@ -1175,6 +1320,8 @@ The layout of \fBrofi\fP can be tweaked by packing the 'fixed' widgets in a cust .PP The following widgets are fixed, as they provide core \fBrofi\fP functionality: + +.RS .IP \(bu 2 prompt .IP \(bu 2 @@ -1194,9 +1341,13 @@ num\-rows .IP \(bu 2 num\-filtered\-rows +.RE + .PP The following keywords are defined and can be used to automatically pack a subset of the widgets. These are used in the default theme as depicted in the figure above. + +.RS .IP \(bu 2 mainbox Packs: \fB\fCinputbar, message, listview, mode\-switcher\fR @@ -1204,11 +1355,15 @@ Packs: \fB\fCinputbar, message, listview, mode\-switcher\fR inputbar Packs: \fB\fCprompt,entry,case\-indicator\fR +.RE + .PP Any widget name starting with \fB\fCtextbox\fR is a textbox widget, others are box widgets and can pack other widgets. .PP There are several special widgets that can be used by prefixing the name of the widget: + +.RS .IP \(bu 2 \fB\fCtextbox\fR: This is a textbox widget. The displayed string can be set with \fB\fCstr\fR\&. @@ -1224,6 +1379,8 @@ The \fB\fCaction\fR can be set to: \fB\fCok|alternate\fR: accept entry and launch alternate action (for run launch in terminal). \fB\fCcustom|alternate\fR: accept custom input and launch alternate action. +.RE + .PP To specify children, set the \fB\fCchildren\fR property (this always happens on the \fB\fCbox\fR child, see example below): @@ -1314,6 +1471,8 @@ Just like CSS, \fBrofi\fP uses the box model for each widget. .PP Explanation of the different parts: + +.RS .IP \(bu 2 Content \- The content of the widget. .IP \(bu 2 @@ -1326,6 +1485,8 @@ The border use the border\-color of the widget. Margin \- Clears an area outside the border. The margin is transparent. +.RE + .PP The box model allows us to add a border around elements, and to define space between elements. @@ -1450,6 +1611,8 @@ Parts of the theme can be conditionally loaded, like the CSS \fB\fC@media\fR opt .PP It supports the following keys as constraint: + +.RS .IP \(bu 2 \fB\fCmin\-width\fR: load when width is bigger or equal then value. .IP \(bu 2 @@ -1465,6 +1628,8 @@ It supports the following keys as constraint: .IP \(bu 2 \fB\fCmonitor\-id\fR: The monitor id, see rofi \-help for id's. +.RE + .PP @media takes an integer number or a fraction, for integer number \fB\fCpx\fR can be added. @@ -1511,11 +1676,15 @@ FontAwesome 22 .PP The rasi file format offers two methods of including other files. This can be used to modify existing themes, or have multiple variations on a theme. + +.RS .IP \(bu 2 import: Import and parse a second file. .IP \(bu 2 theme: Discard theme, and load file as a fresh theme. +.RE + .PP Syntax: @@ -1534,6 +1703,8 @@ The specified file can either by \fIname\fP, \fIfilename\fP,\fIfull path\fP\&. .PP If a filename is provided, it will try to resolve it in the following order: + +.RS .IP \(bu 2 \fB\fC${XDG\_CONFIG\_HOME}/rofi/themes/\fR .IP \(bu 2 @@ -1543,6 +1714,8 @@ If a filename is provided, it will try to resolve it in the following order: .IP \(bu 2 \fB\fC${INSTALL PREFIX}/share/rofi/themes/\fR +.RE + .PP A name is resolved as a filename by appending the \fB\fC\&.rasi\fR extension. |