rofi/CONFIG.md

203 lines
4.5 KiB
Markdown
Raw Normal View History

2023-03-26 22:09:25 +00:00
> This page does not describe all of **ROFI**'s configuration options, just the
> most common usecase. For the full configuration options, check the manpages.
<br />
2023-03-26 22:09:25 +00:00
## Where does the configuration live
2023-03-26 22:09:25 +00:00
Rofi's configurations, custom themes live in `${XDG_CONFIG_HOME}/rofi/`, on
most systems this is `~/.config/rofi/`.
The name of the main configuration file is `config.rasi`. (`~/.config/rofi/config.rasi`).
2023-03-26 22:09:25 +00:00
## Create an empty configuration file
2023-03-26 22:09:25 +00:00
Open `~/.config/rofi/config.rasi` in your favorite text editor and add the
following block:
```css
configuration {
}
```
You can now set the options in the `configuration` block.
2023-03-26 22:09:25 +00:00
## Create a configuration file from current setup
2023-03-26 22:09:25 +00:00
If you do not want to start from scratch, or want to migrate from older
configuration format, you can get tell rofi to dumps it configuration:
```bash
rofi -dump-config > ~/.config/rofi/config.rasi
```
This will have all the possible settings and their current value.
If a value is the default value, the entry will be commented.
For example:
```css
configuration {
2022-02-23 21:42:56 +00:00
/* modes: "window,run,ssh,drun";*/
/* font: "mono 12";*/
/* location: 0;*/
/* yoffset: 0;*/
/* xoffset: 0;*/
/* fixed-num-lines: true;*/
... cut ...
/* ml-row-down: "ScrollDown";*/
/* me-select-entry: "MousePrimary";*/
/* me-accept-entry: "MouseDPrimary";*/
/* me-accept-custom: "Control+MouseDPrimary";*/
}
```
To create a copy of the current theme, you can run:
```bash
rofi -dump-theme > ~/.config/rofi/current.rasi
```
2023-03-26 22:09:25 +00:00
## Configuration file format
2023-03-26 22:09:25 +00:00
### Encoding
2023-03-26 22:09:25 +00:00
The encoding of the file is utf-8. Both Unix (`\n`) and windows (`\r\n`)
newlines format are supported. But Unix is preferred.
2023-03-26 22:09:25 +00:00
### Comments
C and C++ file comments are supported.
2023-03-26 22:09:25 +00:00
- Anything after `// ` and before a newline is considered a comment.
- Everything between `/*` and `*/` is a comment.
Comments can be nested and the C comments can be inline.
The following is valid:
2023-03-26 22:09:25 +00:00
```css
// Magic comment.
property: /* comment */ value;
```
However, this is not:
2023-03-26 22:09:25 +00:00
```css
prop/*comment*/erty: value;
```
2023-03-26 22:09:25 +00:00
### White space
White space and newlines, like comments, are ignored by the parser.
This:
2023-03-26 22:09:25 +00:00
```css
property: name;
```
Is identical to:
2023-03-26 22:09:25 +00:00
```css
property :
name
;
```
2023-03-26 22:09:25 +00:00
### Data types
**ROFI**'s configuration supports several data formats:
2023-03-26 22:09:25 +00:00
#### String
2023-03-26 22:09:25 +00:00
A string is always surrounded by double quotes (`"`). Between the quotes there
can be any printable character.
For example:
```css
ml-row-down: "ScrollDown";
```
2023-03-26 22:09:25 +00:00
#### Number
An integer may contain any full number.
For example:
2023-03-26 22:09:25 +00:00
```css
eh: 2;
```
2023-03-26 22:09:25 +00:00
#### Boolean
Boolean value is either `true` or `false`. This is case-sensitive.
For example:
```css
show-icons: true;
```
2023-03-26 22:09:25 +00:00
This is equal to the `-show-icons` option on the commandline, and `show-icons:
false;` is equal to `-no-show-icons`.
2023-03-26 22:09:25 +00:00
#### Character
2023-03-26 22:09:25 +00:00
Character value is always surrounded by single quotes (') and should contain a
single character. It supports escaping.
```css
matching-negate-char: '-';
```
2023-03-26 22:09:25 +00:00
#### List
2023-03-26 22:09:25 +00:00
This is not supported by the old configuration system, but can be used in the
**rasi** format.
2023-03-26 22:09:25 +00:00
A list starts with a '[' and ends with a ']'. The entries in the list are
comma-separated. The entry in the list single ASCII words.
```css
2022-02-23 21:42:56 +00:00
combi-modes: [window,drun];
```
For older versions you have :
```css
2022-02-23 21:42:56 +00:00
combi-modes: "window,drun";
```
2023-03-26 22:09:25 +00:00
## Get a list of all possible options
There are 2 ways to get a list of all options:
1. Dump the configuration file explained above. (`rofi -dump-config`)
2023-03-26 22:09:25 +00:00
1. Look at output of `rofi -h`.
2023-03-26 22:09:25 +00:00
To see what values an option support check the manpage, it describes most of
them.
2023-03-26 22:09:25 +00:00
NOTE: not all options might be in the manpage, as options can be added at
run-time. (f.e. by plugins).
2023-03-26 22:09:25 +00:00
## Splitting configuration over multiple files
2023-03-26 22:09:25 +00:00
It is possible to split configuration over multiple files using imports. For
example in `~/.config/rofi/config.rasi`
```css
configuration {
}
@import "myConfig"
@theme "MyTheme"
```
Rofi will first parse the config block in `~/.config/rofi/config.rasi`, then
parse `~/.config/rofi/myConfig.rasi` and then load the theme `myTheme`. More
information can be obtained from the **rofi-theme(5)** manpage. Imports can be
nested.