PolytreeDE/rofi
1
0
Fork 0
mirror of https://github.com/davatorium/rofi.git synced 2024-10-27 05:23:18 -04:00
Code Releases Activity

[DOC] Update rofi-theme with a small getting started.

Browse source
This commit is contained in:
Dave Davenport 2022-04-06 20:23:07 +02:00
parent 62ebde525f
commit 2cc21909f5
2 changed files with 336 additions and 26 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

215
doc/rofi-theme.5
View file

@ -4,10 +4,190 @@
.PP .PP
\fBrofi-theme\fP - Rofi theme format files \fBrofi-theme\fP - Rofi theme format files
.SH GETTING STARTED
.PP
The easiest way to get started theming rofi is by modifying your existing theme.
Themes can be modified/tweaked by adding theming elements to the end of your
config file. The default location of this file is \fB\fC~/.config/rofi/config.ras\fR,
if the file does not exists, you can create it.
.PP
For example if we want to change the \fB\fCType to filter\fR text in the entry box:
.PP
.RS
.nf
entry {
placeholder: "Type here";
}
.fi
.RE
.PP
In the above statement, \fB\fCentry\fR indicates the widget, \fB\fCplaceholder\fR is the
property we want to modify and we set it to the string \fB\fC"Type here"\fR\&.
To find the commonly available widgets in rofi, see the 'Basic structure' section.
.PP
To change the mouse over cursor to a pointer, add:
.PP
.RS
.nf
entry {
placeholder: "Type here";
cursor: pointer;
}
.fi
.RE
.PP
For the next modification, we want to add the icon after each text element and
increase the size. First we start by modifying the \fB\fCelement\fR widget:
.PP
.RS
.nf
element {
orientation: horizontal;
children: [ element-text, element-icon ];
spacing: 5px;
}
.fi
.RE
.PP
Resulting in the following packing:
.PP
.RS
.nf
┌─────────────────────────────────────────────────────────────────────┐
│ element │
│ ┌─────────────────────────────────────────────┐ ┌─────────────────┐ │
│ │element─text │ │ element─icon │ │
│ └─────────────────────────────────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
.fi
.RE
.PP
The \fB\fCelement\fR (container) widget hold each entry in the \fB\fClistview\fR, we add the two
pre-defined children in the order we want to show them.
We also specify the packing direction (\fB\fCorientation\fR) and the spacing between the children (\fB\fCspacing\fR).
We specify the space between the two children in absolute pixels (\fB\fCpx\fR).
.PP
To increase the icon-size, we need to modify the \fB\fCelement-icon\fR widget.
.PP
.RS
.nf
element-icon {
size: 2.5em;
}
.fi
.RE
.PP
.RS
.nf
┌─────────────────────────────────────────────────────────────────────┐
│ element │
│ ┌─────────────────────────────────────────────┐ ┌─────────────────┐ │
│ │element─text │ │ element │ │
│ │ │ │ ─ │ │
│ │ │ │ icon │ │
│ └─────────────────────────────────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
.fi
.RE
.PP
In this example we specify the size in the em
\[la]https://www.w3.org/Style/LieBos3e/em\[ra] unit.
.PP
Now lets change the text color of both the \fB\fCentry\fR and the \fB\fCelement-text\fR widget to red and background to blue.
.PP
.RS
.nf
entry, element-text {
text-color: red;
background-color: rgb(0,0,255);
}
.fi
.RE
.PP
Here we use two different methods of writing down the color, for \fB\fCtext-color\fR
we used a named color, for \fB\fCbackground-color\fR we specify it in \fB\fCrgb\fR\&.
We also specify the property for multiple widgets by passing a comma separated
list of widget names.
.PP
If you want to center the text relative to the icon, we can set this:
.PP
.RS
.nf
element-icon {
vertical-align: 0.5;
}
.fi
.RE
.PP
.RS
.nf
┌─────────────────────────────────────────────────────────────────────┐
│ element │
│ ┌─────────────────────────────────────────────┐ ┌─────────────────┐ │
│ │ │ │ element │ │
│ │element-text │ │ ─ │ │
│ │ │ │ icon │ │
│ └─────────────────────────────────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
.fi
.RE
.PP
If you want to see the complete theme, including the modification you can run:
.PP
.RS
.nf
rofi -dump-theme
.fi
.RE
.SH DEFAULT THEME LOADING .SH DEFAULT THEME LOADING
.PP .PP
By default, rofi loads the default theme. This theme is \fBalways\fP loaded. By default, rofi loads the default theme. This theme is \fBalways\fP loaded.
In the default (always loaded) configuration it does: The default configuration contains:
.PP .PP
.RS .RS
@ -19,11 +199,11 @@ In the default (always loaded) configuration it does:
.RE .RE
.PP .PP
To unload the default theme, and load another theme, add \fB\fC@theme\fR to your To unload the default theme, and load another theme, add the \fB\fC@theme\fR statement
\fB\fCconfig.rasi\fR file. to your \fB\fCconfig.rasi\fR file.
.PP .PP
If you have a theme loaded by \fB\fC@theme\fR or use the default theme, you can tweak If you have a theme loaded via \fB\fC@theme\fR or use the default theme, you can tweak
it by adding overriding elements at the end of your \fB\fCconfig.rasi\fR file. it by adding overriding elements at the end of your \fB\fCconfig.rasi\fR file.
.PP .PP
@ -52,7 +232,7 @@ user-friendly way. Therefore, a new file format has been created, replacing the
.SH FORMAT SPECIFICATION .SH FORMAT SPECIFICATION
.SH Encoding .SH Encoding
.PP .PP
The encoding of the file is utf-8. Both unix (\fB\fC\\n\fR) and windows (\fB\fC\\r\\n\fR) newlines format are supported. But unix is The encoding of the file is UTF-8. Both unix (\fB\fC\\n\fR) and windows (\fB\fC\\r\\n\fR) newlines format are supported. But unix is
preferred. preferred.
.SH Comments .SH Comments
@ -651,28 +831,37 @@ width: calc( 100% - 37px );
.fi .fi
.RE .RE
.PP
.RS
.nf
width: calc( 20% min 512 );
.fi
.RE
.PP .PP
It supports the following operations: It supports the following operations:
.RS .RS
.IP \(bu 2 .IP \(bu 2
\fB\fC+\fR : Add \fB\fC+\fR : Add
.IP \(bu 2 .IP \(bu 2
\fB\fC-\fR : Subtract \fB\fC-\fR : Subtract
.IP \(bu 2 .IP \(bu 2
\fB\fC/\fR : Divide \fB\fC/\fR : Divide
.IP \(bu 2 .IP \(bu 2
\fB\fC*\fR : Multiply \fB\fC*\fR : Multiply
.IP \(bu 2 .IP \(bu 2
\fB\fC%\fR : Modulo \fB\fC%\fR : Modulo
.IP \(bu 2 .IP \(bu 2
\fB\fCmin\fR : Minimum of lvalue or rvalue; \fB\fCmin\fR : Minimum of lvalue or rvalue;
.IP \(bu 2 .IP \(bu 2
\fB\fCmax\fR : Maximum of lvalue or rvalue; \fB\fCmax\fR : Maximum of lvalue or rvalue;
.IP \(bu 2 .IP \(bu 2
\fB\fCfloor\fR : Round down lvalue to the next multiple of rvalue \fB\fCfloor\fR : Round down lvalue to the next multiple of rvalue
.IP \(bu 2 .IP \(bu 2
\fB\fCceil\fR : Round up lvalue to the next multiple of rvalue \fB\fCceil\fR : Round up lvalue to the next multiple of rvalue
.IP \(bu 2 .IP \(bu 2
\fB\fCround\fR : Round lvalue to the next multiple of rvalue \fB\fCround\fR : Round lvalue to the next multiple of rvalue

147
doc/rofi-theme.5.markdown
View file

@ -4,19 +4,136 @@
**rofi-theme** - Rofi theme format files **rofi-theme** - Rofi theme format files
## GETTING STARTED
The easiest way to get started theming rofi is by modifying your existing theme.
Themes can be modified/tweaked by adding theming elements to the end of your
config file. The default location of this file is `~/.config/rofi/config.ras`,
if the file does not exists, you can create it.
For example if we want to change the `Type to filter` text in the entry box:
```css
entry {
placeholder: "Type here";
}
```
In the above statement, `entry` indicates the widget, `placeholder` is the
property we want to modify and we set it to the string `"Type here"`.
To find the commonly available widgets in rofi, see the 'Basic structure' section.
To change the mouse over cursor to a pointer, add:
```css
entry {
placeholder: "Type here";
cursor: pointer;
}
```
For the next modification, we want to add the icon after each text element and
increase the size. First we start by modifying the `element` widget:
```css
element {
orientation: horizontal;
children: [ element-text, element-icon ];
spacing: 5px;
}
```
Resulting in the following packing:
```
┌─────────────────────────────────────────────────────────────────────┐
│ element │
│ ┌─────────────────────────────────────────────┐ ┌─────────────────┐ │
│ │element─text │ │ element─icon │ │
│ └─────────────────────────────────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
```
The `element` (container) widget hold each entry in the `listview`, we add the two
pre-defined children in the order we want to show them.
We also specify the packing direction (`orientation`) and the spacing between the children (`spacing`).
We specify the space between the two children in absolute pixels (`px`).
To increase the icon-size, we need to modify the `element-icon` widget.
```css
element-icon {
size: 2.5em;
}
```
```
┌─────────────────────────────────────────────────────────────────────┐
│ element │
│ ┌─────────────────────────────────────────────┐ ┌─────────────────┐ │
│ │element─text │ │ element │ │
│ │ │ │ ─ │ │
│ │ │ │ icon │ │
│ └─────────────────────────────────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
```
In this example we specify the size in the [em](https://www.w3.org/Style/LieBos3e/em) unit.
Now lets change the text color of both the `entry` and the `element-text` widget to red and background to blue.
```css
entry, element-text {
text-color: red;
background-color: rgb(0,0,255);
}
```
Here we use two different methods of writing down the color, for `text-color`
we used a named color, for `background-color` we specify it in `rgb`.
We also specify the property for multiple widgets by passing a comma separated
list of widget names.
If you want to center the text relative to the icon, we can set this:
```css
element-icon {
vertical-align: 0.5;
}
```
```
┌─────────────────────────────────────────────────────────────────────┐
│ element │
│ ┌─────────────────────────────────────────────┐ ┌─────────────────┐ │
│ │ │ │ element │ │
│ │element-text │ │ ─ │ │
│ │ │ │ icon │ │
│ └─────────────────────────────────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
```
If you want to see the complete theme, including the modification you can run:
```bash
rofi -dump-theme
```
## DEFAULT THEME LOADING ## DEFAULT THEME LOADING
By default, rofi loads the default theme. This theme is **always** loaded. By default, rofi loads the default theme. This theme is **always** loaded.
In the default (always loaded) configuration it does: The default configuration contains:
```css ```css
@theme "default" @theme "default"
``` ```
To unload the default theme, and load another theme, add `@theme` to your To unload the default theme, and load another theme, add the `@theme` statement
`config.rasi` file. to your `config.rasi` file.
If you have a theme loaded by `@theme` or use the default theme, you can tweak If you have a theme loaded via `@theme` or use the default theme, you can tweak
it by adding overriding elements at the end of your `config.rasi` file. it by adding overriding elements at the end of your `config.rasi` file.
For the difference between `@import` and `@theme` see the `Multiple file For the difference between `@import` and `@theme` see the `Multiple file
@ -39,7 +156,7 @@ user-friendly way. Therefore, a new file format has been created, replacing the
## Encoding ## Encoding
The encoding of the file is utf-8. Both unix (`\n`) and windows (`\r\n`) newlines format are supported. But unix is The encoding of the file is UTF-8. Both unix (`\n`) and windows (`\r\n`) newlines format are supported. But unix is
preferred. preferred.
## Comments ## Comments
@ -410,17 +527,21 @@ Rofi supports some maths in calculating sizes. For this it uses the CSS syntax:
width: calc( 100% - 37px ); width: calc( 100% - 37px );
``` ```
```css
width: calc( 20% min 512 );
```
It supports the following operations: It supports the following operations:
* `+` : Add * `+` : Add
* `-` : Subtract * `-` : Subtract
* `/` : Divide * `/` : Divide
* `*` : Multiply * `*` : Multiply
* `%` : Modulo * `%` : Modulo
* `min` : Minimum of lvalue or rvalue; * `min` : Minimum of lvalue or rvalue;
* `max` : Maximum of lvalue or rvalue; * `max` : Maximum of lvalue or rvalue;
* `floor` : Round down lvalue to the next multiple of rvalue * `floor` : Round down lvalue to the next multiple of rvalue
* `ceil` : Round up lvalue to the next multiple of rvalue * `ceil` : Round up lvalue to the next multiple of rvalue
* `round` : Round lvalue to the next multiple of rvalue * `round` : Round lvalue to the next multiple of rvalue
It uses the C precedence ordering. It uses the C precedence ordering.