Mirrors/rofi
2
0
Fork 0
mirror of https://github.com/lbonn/rofi synced 2024-11-12 23:27:15 +00:00
Code Issues Projects Releases Packages Wiki Activity

[Website] Update 1.7.3 docs.

Browse source 
Issue: #2033
This commit is contained in:
Dave Davenport 2024-09-26 18:02:47 +02:00
parent 558ab34aa3
commit 35a4af12ff
5 changed files with 285 additions and 589 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

40
mkdocs/docs/1.7.3/rofi-dmenu.5.markdown
View file

@ -158,6 +158,13 @@ Force **rofi** mode to first read all data from stdin before showing the selecti
Note: the default asynchronous mode will also be automatically disabled if used with conflicting options,
such as `-dump`, `-only-match` or `-auto-select`.
`-async-pre-read` *number*
Reads the first *number* entries blocking, then switches to async mode.
This makes it feel more 'snappy'.
*default*: 25
`-window-title` *title*
Set name used for the window title. Will be shown as Rofi - *title*
@ -170,37 +177,6 @@ Position **rofi** over the window with the given X11 window ID.
Set ellipsize mode to start. So, the end of the string is visible.
`-display-columns`
A comma seperated list of columns to show.
`-display-column-separator`
The column separator. This is a regex.
*default*: '\t'
`-ballot-selected-str` *string*
When multi-select is enabled, prefix this string when element is selected.
*default*: "☑ "
`-ballot-unselected-str` *string*
When multi-select is enabled, prefix this string when element is not selected.
*default*: "☐ "
`-ellipsize-mode` (start|middle|end)
Set ellipsize mode on the listview.
*default* "end"
## PARSING ROW OPTIONS
Extra options for individual rows can be also set. See the **rofi-script(5)** manpage for details; the syntax and supported features are identical.
## RETURN VALUE
@ -211,7 +187,7 @@ Extra options for individual rows can be also set. See the **rofi-script(5)** ma
## SEE ALSO
rofi(1), rofi-sensible-terminal(1), dmenu(1), rofi-theme(5), rofi-script(5), rofi-theme-selector(1), ascii(7)
rofi(1), rofi-sensible-terminal(1), dmenu(1), rofi-theme(5), rofi-script(5), rofi-theme-selector(1)
## AUTHOR

33
mkdocs/docs/1.7.3/rofi-keys.5.markdown
View file

@ -52,15 +52,6 @@ configuration {
}
```
## Unsetting a binding
To unset a binding, pass an empty string.
```css
configuration {
kb-clear-line: "";
}
```
## Keyboard Bindings
@ -74,12 +65,6 @@ Paste clipboard
**Default**: Control+v,Insert
### **kb-secondary-copy**
Copy current selection to clipboard
**Default**: Control+c
### **kb-clear-line**
Clear input line
@ -151,12 +136,12 @@ Accept entry
**Default**: Control+j,Control+m,Return,KP_Enter
### **kb-accept-custom**
Use entered text as command (in ssh/run modes)
Use entered text as command (in ssh/run modi)
**Default**: Control+Return
### **kb-accept-custom-alt**
Use entered text as command (in ssh/run modes)
Use entered text as command (in ssh/run modi)
**Default**: Control+Shift+Return
@ -198,7 +183,7 @@ Go to the next column
### **kb-row-up**
Select previous entry
**Default**: Up,Control+p
**Default**: Up,Control+p,ISO_Left_Tab
### **kb-row-down**
Select next entry
@ -208,17 +193,7 @@ Select next entry
### **kb-row-tab**
Go to next row, if one left, accept it, if no left next mode.
**Default**:
### **kb-element-next**
Go to next row.
**Default**: Tab
### **kb-element-prev**
Go to previous row.
**Default**: ISO_Left_Tab
**Default**: Tab
### **kb-page-prev**
Go to the previous page

26
mkdocs/docs/1.7.3/rofi-script.5.markdown
View file

@ -2,14 +2,13 @@
## NAME
**rofi script mode** - Rofi format for scriptable mode.
**rofi script mode** - Rofi format for scriptable modi.
## DESCRIPTION
**rofi** supports modes that use simple scripts in the background to generate a
list and process the result from user actions. This provide a simple interface
to make simple extensions to rofi.
**rofi** supports modes that use simple scripts in the background to generate a list and process the result from user
actions. This provide a simple interface to make simple extensions to rofi.
## USAGE
@ -19,18 +18,17 @@ To specify a script mode, set a mode with the following syntax: "{name}:{executa
For example:
```
rofi -show fb -modes "fb:file_browser.sh"
rofi -show fb -modi "fb:file_browser.sh"
```
The name should be unique.
## API
Rofi calls the executable without arguments on startup. This should generate a
list of options, separated by a newline (`\n`) (This can be changed by the
script). If the user selects an option, rofi calls the executable with the text
of that option as the first argument. If the script returns no entries, rofi
quits.
Rofi calls the executable without arguments on startup. This should generate a list of options, separated by a newline
(`\n`) (This can be changed by the script).
If the user selects an option, rofi calls the executable with the text of that option as the first argument.
If the script returns no entries, rofi quits.
A simple script would be:
@ -65,10 +63,6 @@ An integer number with the current state:
Environment get set when selected entry get set with the property value of the 'info' row option, if set.
### `ROFI_DATA`
Environment get set when script sets `data` option in header.
## Passing mode options
Extra options, like setting the prompt, can be set by the script.
@ -90,10 +84,6 @@ The following extra options exists:
* **delim**: Set the delimiter for for next rows. Default is '\n' and this option should finish with this. Only call this on first call of script, it is remembered for consecutive calls.
* **no-custom**: If set to 'true'; only accept listed entries, ignore custom input.
* **use-hot-keys**: If set to true, it enabled the Custom keybindings for script. Warning this breaks the normal rofi flow.
* **keep-selection**: If set, the selection is not moved to the first entry, but the current position is maintained. The filter is cleared.
* **new-selection**: If `keep-selection` is set, this allows you to override the selected entry (absolute position).
* **data**: Passed data to the next execution of the script via **ROFI_DATA**.
* **theme**: Small theme snippet to f.e. change the background color of a widget.
## Parsing row options

462
mkdocs/docs/1.7.3/rofi-theme.5.markdown
View file

@ -4,165 +4,19 @@
**rofi-theme** - Rofi theme format files
## GETTING STARTED WITH THEMING
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 the
config file. The default location of this file is `~/.config/rofi/config.rasi`,
if the file does not exists, you can create it.
A basic config:
```css
configuration {
modes: [ combi ];
combi-modes: [ window, drun, run ];
}
@theme "gruvbox-light"
/* Insert theme modifications after this */
```
For example if we want to change the `Type to filter` text in the entry box we
append the following:
```css
entry {
placeholder: "Type here";
}
```
In the above section, `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. 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-text {
vertical-align: 0.5;
}
```
```
┌─────────────────────────────────────────────────────────────────────┐
│ element │
│ ┌─────────────────────────────────────────────┐ ┌─────────────────┐ │
│ │ │ │ element │ │
│ │element-text │ │ ─ │ │
│ │ │ │ icon │ │
│ └─────────────────────────────────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
```
We can also specify the color and width of the cursor. You could, for example,
create a crimson block cursor like this:
```css
entry {
cursor-color: rgb(220,20,60);
cursor-width: 8px;
}
```
By default, the `cursor-color` will be the same as the `text-color`. The `cursor-width` will always default to 2 pixels.
If you want to see the complete theme, including the modification you can run:
```bash
rofi -dump-theme
```
## DEFAULT THEME LOADING
By default, rofi loads the default theme. This theme is **always** loaded.
The default configuration contains:
In the default (always loaded) configuration it does:
```css
@theme "default"
```
To unload the default theme, and load another theme, add the `@theme` statement
to your `config.rasi` file.
To unload the default theme, and load another theme, add `@theme` to your
`config.rasi` file.
If you have a theme loaded via `@theme` or use the default theme, you can tweak
If you have a theme loaded by `@theme` or use the default theme, you can tweak
it by adding overriding elements at the end of your `config.rasi` file.
For the difference between `@import` and `@theme` see the `Multiple file
@ -185,7 +39,7 @@ user-friendly way. Therefore, a new file format has been created, replacing the
## 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.
## Comments
@ -193,7 +47,7 @@ preferred.
C and C++ file comments are supported.
* Anything after `// ` and before a newline is considered a comment.
* Everything between `/*` and `*/` is a comment, this comment can span multiple lines.
* Everything between `/*` and `*/` is a comment.
Comments can be nested and the C comments can be inline.
@ -237,7 +91,7 @@ abbreviation for **r**ofi **a**dvanced **s**tyle **i**nformation.
## Basic Structure
Each element has a section with defined properties. Global properties can be defined in section `* { }`.
Sub-section names begin with an optional hash symbol `#`.
Sub-section names begin with a hash symbol `#`.
It is advised to define the *global properties section* on top of the file to
make inheritance of properties clearer.
@ -277,8 +131,8 @@ A theme can have multiple element theme sections.
The element path can consist of multiple names separated by whitespace or dots.
Each element may contain any number of letters, numbers and `-`'s.
The first element in the element path can optionally start with a `#` (for
historic reasons). Multiple elements can be specified by a `,`.
The first element in the element path should always start with a `#`.
Multiple elements can be specified by a `,`.
This is a valid element name:
@ -299,8 +153,8 @@ element normal normal, button {
}
```
Each section inherits the global properties. Properties can be explicitly
inherited from their parent with the `inherit` keyword.
Each section inherits the global properties. Properties can be explicitly inherited from their parent with the
`inherit` keyword.
In the following example:
```css
@ -316,8 +170,7 @@ mainbox {
}
```
The element `mainbox` will have the following set of properties (if `mainbox`
is a child of `window`):
The element `mainbox` will have the following set of properties (if `mainbox` is a child of `window`):
```css
a: 1;
@ -381,15 +234,7 @@ For example:
font: "Awasome 12";
```
The string must be valid UTF-8, special characters can be escaped:
```css
text {
content: "Line one\n\tIndented line two";
}
```
The following special characters can be escaped: `\b`, `\f`, `\n`, `\r`, `\t`, `\v`, `\` and `"`.
The string must be valid UTF-8.
## Integer
@ -510,18 +355,8 @@ should be applied.
* `bold`: make the text thicker then the surrounding text.
* `italic`: put the highlighted text in script type (slanted).
* `underline`: put a line under the text.
* `strikethrough`: put a line through the text.
The following options are available on pango 1.50.0 and up:
* `uppercase`: Uppercase the text.
* `lowercase`: Lowercase the text.
The following option is disabled as pango crashes on this if there is eel
upsizing or wrapping. This will be re-enabled once fixed:
* `capitalize`: Capitalize the text.
* `underline`: put a line under the highlighted text.
* `strikethrough`: put a line through the highlighted text.
## Line style
@ -566,21 +401,17 @@ Rofi supports some maths in calculating sizes. For this it uses the CSS syntax:
width: calc( 100% - 37px );
```
```css
width: calc( 20% min 512 );
```
It supports the following operations:
* `+` : Add
* `-` : Subtract
* `/` : Divide
* `*` : Multiply
* `%` : Modulo
* `min` : Minimum of lvalue or rvalue;
* `max` : Maximum of lvalue or rvalue;
* `+` : Add
* `-` : Subtract
* `/` : Divide
* `*` : Multiply
* `%` : Multiply
* `min` : Minimum of l or rvalue;
* `max` : Maximum of l or 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
It uses the C precedence ordering.
@ -625,28 +456,24 @@ style property.
Indicate a place on the window/monitor.
```
┌─────────────┬─────────────┬─────────────┐
│ north west │ north │ north east │
├─────────────┼─────────────┼─────────────┤
│ west │ center │ east │
├─────────────┼─────────────┼─────────────┤
│ south west │ south │ south east │
└─────────────┴─────────────┴─────────────┘
* Format: `(center|east|north|west|south|north east|north west|south west|south east)`
```
* Format: `(center|east|north|west|south|north east|north west|south west|south east)`
north west | north | north east
-------------|-------------|------------
west | center | east
-------------|-------------|------------
south west | south | south east
```
## Visibility
It is possible to hide widgets:
```css
inputbar {
enabled: false;
}
```
## Reference
@ -795,8 +622,6 @@ The current widgets available in **rofi**:
* `entry`: the main entry @textbox
* `num-rows`: Shows the total number of rows.
* `num-filtered-rows`: Shows the total number of rows after filtering.
* `textbox-current-entry`: Shows the text of the currently selected entry.
* `icon-current-entry`: Shows the icon of the currently selected entry.
* `listview`: The listview.
* `scrollbar`: the listview scrollbar
* `element`: a box in the listview holding the entries
@ -868,22 +693,22 @@ The following properties are currently supported:
### all widgets:
* **enabled**: enable/disable rendering of the widget
* **padding**: padding
* **enabled**: enable/disable the widget
* **padding**: padding
Padding on the inside of the widget
* **margin**: padding
* **margin**: padding
Margin on the outside of the widget
* **border**: border
* **border**: border
Border around the widget (between padding and margin)/
* **border-radius**: padding
* **border-radius**: padding
Sets a radius on the corners of the borders.
* **background-color**: color
* **background-color**: color
Background color
* **background-image**: image
* **background-image**: image
Background image
* **border-color**: color
Color of the border
* **cursor**: cursor
* **cursor**: cursor
Type of mouse cursor that is set when the mouse pointer is hovered over the widget.
### window:
@ -906,8 +731,8 @@ The following properties are currently supported:
Window is fullscreen.
* **width**: distance
The width of the window
* **x-offset**: distance
* **y-offset**: distance
* **x-offset**: distance
* **y-offset**: distance
The offset of the window to the anchor point, allowing you to push the window left/right/up/down
@ -922,7 +747,7 @@ The following properties are currently supported:
* **orientation**: orientation
Set the direction the elements are packed.
* **spacing**: distance
* **spacing**: distance
Distance between the packed elements.
### textbox:
@ -930,18 +755,16 @@ The following properties are currently supported:
* **background-color**: color
* **border-color**: the color used for the border around the widget.
* **font**: the font used by this textbox (string).
* **str**/**content**: the string to display by this textbox (string).
* **str**: the string to display by this textbox (string).
* **vertical-align**: Vertical alignment of the text. A number between 0 (top) and 1 (bottom).
* **horizontal-align**: Horizontal alignment of the text. A number between 0 (left) and 1 (right).
* **text-color**: the text color to use.
* **text-transform**: text style {color} for the whole text.
* **highlight**: text style {color}.
color is optional, multiple highlight styles can be added like: bold underline italic #000000;
This option is only available on the `element-text` widget.
* **width**: override the desired width for the textbox.
* **content**: Set the displayed text (String).
* **placeholder**: Set the displayed text (String) when nothing is entered.
* **placeholder-markup**: If true, placeholder text supports pango markup for stylizing.
* **placeholder-color**: Color of the placeholder text.
* **blink**: Enable/Disable blinking on an input textbox (Boolean).
* **markup**: Force markup on, beware that only valid pango markup strings are shown.
@ -949,14 +772,6 @@ The following properties are currently supported:
Set the location of tab stops by their distance from the beginning of the line.
Each distance should be greater than the previous one.
The text appears to the right of the tab stop position (other alignments are not supported yet).
* **cursor-width**: The width of the cursor.
* **cursor-color**: The color used to draw the cursor.
* **cursor-outline**: Enable a border (outline) around the cursor. (Boolean)
* **cursor-outline-width**: The width of the border around the cursor. (Double)
* **cursor-outline-color**: The color to use for the cursor outline. (Color)
* **text-outline**: Enable a border (outline) around the text. (Boolean)
* **text-outline-width**: The width of the border around the text. (Double)
* **text-outline-color**: The color to use for the text outline. (Color)
### listview:
* **columns**: integer
@ -979,13 +794,8 @@ The following properties are currently supported:
Indicate how elements are stacked. Horizontal implements the dmenu style.
* **reverse**: boolean
Reverse the ordering (top down to bottom up).
* **flow**: orientation
The order the elements are layed out. Vertical is the original 'column' view.
* **fixed-columns**: boolean
Do not reduce the number of columns shown when number of visible elements is not enough to fill them all.
* **require-input**: boolean
Listview requires user input to be unhidden. The list is still present and
hitting accept will activate the first entry.
Each element is a `box` called `element`. Each `element` can contain an `element-icon` and `element-text`.
@ -1026,42 +836,42 @@ The box can be vertical or horizontal. This is loosely inspired by [GTK](http://
The current layout of **rofi** is structured as follows:
```
┌────────────────────────────────────────────────────────────────────────────────────┐
│ window {BOX:vertical} │
│ ┌───────────────────────────────────────────────────────────────────────────────┐ │
│ │ mainbox {BOX:vertical} │ │
│ │ ┌───────────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ inputbar {BOX:horizontal} │ │ │
│ │ │ ┌─────────┐ ┌─┐ ┌───────────────────────────────┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐ │ │ │
│ │ │ │ prompt │ │:│ │ entry │ │#fr│ │ / │ │#ns│ │ci │ │ │ │
│ │ │ └─────────┘ └─┘ └───────────────────────────────┘ └───┘ └───┘ └───┘ └───┘ │ │ │
│ │ └───────────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌───────────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ message │ │ │
│ │ │ ┌───────────────────────────────────────────────────────────────────────┐ │ │ │
│ │ │ │ textbox │ │ │ │
│ │ │ └───────────────────────────────────────────────────────────────────────┘ │ │ │
│ │ └───────────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌───────────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ listview │ │ │
│ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │
│ │ │ │ element │ │ │ │
│ │ │ │ ┌─────────────────┐ ┌─────────────────────────────────────────────┐ │ │ │ │
│ │ │ │ │element─icon │ │element─text │ │ │ │ │
│ │ │ │ └─────────────────┘ └─────────────────────────────────────────────┘ │ │ │ │
│ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │
│ │ └───────────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌───────────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ mode─switcher {BOX:horizontal} │ │ │
│ │ │ ┌───────────────┐ ┌───────────────┐ ┌──────────────┐ ┌───────────────┐ │ │ │
│ │ │ │ Button │ │ Button │ │ Button │ │ Button │ │ │ │
│ │ │ └───────────────┘ └───────────────┘ └──────────────┘ └───────────────┘ │ │ │
│ │ └───────────────────────────────────────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────────────────┘
|------------------------------------------------------------------------------------|
| window {BOX:vertical} |
| |-------------------------------------------------------------------------------| |
| | mainbox {BOX:vertical} | |
| | |---------------------------------------------------------------------------| | |
| | | inputbar {BOX:horizontal} | | |
| | | |---------| |-| |---------------------------------|---| |---| |---| |---| | | |
| | | | prompt | |:| | entry |#fr| | / | |#ns| |ci | | | |
| | | |---------| |_| |---------------------------------|---| |---| |---| |---| | | |
| | |---------------------------------------------------------------------------| | |
| | | |
| | |---------------------------------------------------------------------------| | |
| | | message | | |
| | | |-----------------------------------------------------------------------| | | |
| | | | textbox | | | |
| | | |-----------------------------------------------------------------------| | | |
| | |---------------------------------------------------------------------------| | |
| | | |
| | |-----------------------------------------------------------------------------| |
| | | listview | |
| | | |------------------------------------------------------------------------] | |
| | | | element | | |
| | | | |-----------------| |------------------------------------------------] | | |
| | | | |element-icon | |element-text | | | |
| | | | |-----------------| |------------------------------------------------| | | |
| | | |------------------------------------------------------------------------] | |
| | |-----------------------------------------------------------------------------| |
| | | |
| | |---------------------------------------------------------------------------| | |
| | | mode-switcher {BOX:horizontal} | | |
| | | |---------------| |---------------| |--------------| |---------------| | | |
| | | | Button | | Button | | Button | | Button | | | |
| | | |---------------| |---------------| |--------------| |---------------| | | |
| | |---------------------------------------------------------------------------| | |
| |-------------------------------------------------------------------------------| |
|------------------------------------------------------------------------------------|
```
@ -1072,15 +882,16 @@ The current layout of **rofi** is structured as follows:
### Error message structure
```
┌──────────────────────────────────────────────────────────────────────────────────┐
│ window {BOX:vertical} │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ error─message {BOX:vertical} │ │
│ │ ┌────────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ textbox │ │ │
│ │ └────────────────────────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────────────┘
|-----------------------------------------------------------------------------------|
| window {BOX:vertical} |
| |------------------------------------------------------------------------------| |
| | error-message {BOX:vertical} | |
| | |-------------------------------------------------------------------------| | |
| | | textbox | | |
| | |-------------------------------------------------------------------------| | |
| |------------------------------------------------------------------------------| |
|-----------------------------------------------------------------------------------|
```
@ -1224,18 +1035,18 @@ element selected {
Just like CSS, **rofi** uses the box model for each widget.
```
┌──────────────────────────────────────────────────────────────────┐
│ margin │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ border │ │
│ │ ┌────────────────────────────────────────────────────────┐ │ │
│ │ │ padding │ │ │
│ │ │ ┌────────────────────────────────────────────────────┐ │ │ │
│ │ │ │ content │ │ │ │
│ │ │ └────────────────────────────────────────────────────┘ │ │ │
│ │ └────────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
|-------------------------------------------------------------------|
| margin |
| |-------------------------------------------------------------| |
| | border | |
| | |---------------------------------------------------------| | |
| | | padding | | |
| | | |-----------------------------------------------------| | | |
| | | | content | | | |
| | | |-----------------------------------------------------| | | |
| | |---------------------------------------------------------| | |
| |-------------------------------------------------------------| |
|-------------------------------------------------------------------|
```
Explanation of the different parts:
@ -1259,15 +1070,15 @@ Widgets that can pack more then one child widget (currently box and listview) ha
This property sets the distance between the packed widgets (both horizontally and vertically).
```
┌───────────────────────────────────────┐
│ ┌────────┐ s ┌────────┐ s ┌────────┐ │
│ │ child │ p │ child │ p │ child │ │
│ │ │ a │ │ a │ │ │
│ │ │ c │ │ c │ │ │
│ │ │ i │ │ i │ │ │
│ │ │ n │ │ n │ │ │
│ └────────┘ g └────────┘ g └────────┘ │
└───────────────────────────────────────┘
|---------------------------------------|
| |--------| s |--------| s |-------| |
| | child | p | child | p | child | |
| | | a | | a | | |
| | | c | | c | | |
| | | i | | i | | |
| | | n | | n | | |
| |--------| g |--------| g |-------| |
|---------------------------------------|
```
### Advanced box packing
@ -1275,15 +1086,15 @@ This property sets the distance between the packed widgets (both horizontally an
More dynamic spacing can be achieved by adding dummy widgets, for example to make one widget centered:
```
┌────────────────────────────────────────────────────┐
│ ┌───────────────┐ ┌────────┐ ┌───────────────┐ │
│ │ dummy │ │ child │ │ dummy │ │
│ │ expand: true; │ │ │ │ expand: true; │ │
│ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │
│ └───────────────┘ └────────┘ └───────────────┘ │
└────────────────────────────────────────────────────┘
|----------------------------------------------------|
| |---------------| |--------| |---------------| |
| | dummy | | child | | dummy | |
| | expand: true; | | | | expand: true; | |
| | | | | | | |
| | | | | | | |
| | | | | | | |
| |---------------| |--------| |---------------| |
|----------------------------------------------------|
```
If both dummy widgets are set to expand, `child` will be centered. Depending on the `expand` flag of child the
@ -1343,7 +1154,6 @@ It supports the following keys as constraint:
* `min-aspect-ratio` load when aspect ratio is over value.
* `max-aspect-ratio`: load when aspect ratio is under value.
* `monitor-id`: The monitor id, see rofi -help for id's.
* `enabled`: Boolean option to enable. Supports environment variable.
@media takes an integer number or a fraction, for integer number `px` can be added.
@ -1354,12 +1164,6 @@ It supports the following keys as constraint:
}
```
```
@media ( enabled: env(DO_LIGHT, false ) {
}
```
## Font Parsing
@ -1377,34 +1181,6 @@ Or
FontAwesome 22
```
## Icon Handling
Rofi supports 3 ways of specifying an icon:
* Filename
* icon-name, this is looked up via the icon-theme.
* Markup String. It renders a string as an icon.
For the first two options, GdkPixbuf is used to open and render the icons.
This in general gives support for most required image formats.
For the string option it uses Pango to render the string. The string needs to
start with a `<span` tag, that allows you to set color and font.
Markup string:
```bash
echo -en "testing\0icon\x1f<span color='red'>⏻</span>" | ./rofi -dmenu
```
Getting supported icon formats:
```bash
G_MESSAGES_DEBUG=Helpers.IconFetcher rofi
```
This uses the debug framework and prints out a list of supported image file
extensions.
## Multiple file handling
The rasi file format offers two methods of including other files.

313
mkdocs/docs/1.7.3/rofi.1.markdown
View file

@ -11,45 +11,30 @@
## DESCRIPTION
**rofi** is an X11 pop-up window switcher, run dialog, dmenu replacement, and
more. It focuses on being fast to use and have minimal distraction. It supports
keyboard and mouse navigation, type to filter, tokenized search and more.
**rofi** is an X11 pop-up window switcher, run dialog, dmenu replacement, and more. It focuses on
being fast to use and have minimal distraction. It supports keyboard and mouse navigation, type to
filter, tokenized search and more.
## USAGE
**rofi**'s main functionality is to assist in your workflow, allowing you to
quickly switch between windows, start applications or log into a remote machine
via `ssh`. There are different *modes* for different types of actions. **rofi**
is a standalone application and should not be integrated into scripts. For
integration into scripts it has a special mode that functions as a (drop-in)
replacement for **dmenu(1)**. See emulating dmenu below.
**rofi**'s main functionality is to assist in your workflow, allowing you to quickly switch
between windows, start applications or log into a remote machine via `ssh`.
There are different *modi* for different types of actions.
**rofi** is a standalone application and should not be integrated into scripts.
For integration into scripts it has a special mode that functions as a
(drop-in) replacement for **dmenu(1)**. See emulating dmenu below.
### Running rofi
To launch **rofi** directly in a certain mode, specify a mode with `rofi -show <mode>`.
To show the `drun` dialog:
```bash
rofi -show drun
```
A very useful setup in minimalistic window managers is to combine `drun`, `run`
with `window` mode:
```bash
rofi -show combi -modes combi -combi-modes "window,drun,run"
```
In this setup it first list all open applications, then all installed
applications. So if you type firefox and hit return, it will switch to the
running firefox, or launch it when it is not running.
To show the `run` dialog:
rofi -show run
### Emulating dmenu
**rofi** can emulate **dmenu(1)** (a dynamic menu for X11) when launched with
the `-dmenu` flag.
**rofi** can emulate **dmenu(1)** (a dynamic menu for X11) when launched with the `-dmenu` flag.
For more information see **rofi-dmenu(5)**.
@ -75,29 +60,6 @@ To get a template config file, run: `rofi -dump-config > config.rasi`
This will contain (commented) all current configuration options, modified options are uncommented.
To get a template config file that sets the icon-theme run: `rofi -icon-theme hicolor -dump-config`.
It is **strongly** recommended to use this as a starting point for your configuration.
An empty configuration section in the config file looks like:
```css
configuration {
// set config options here
}
```
Most of the configuration options mentioned below (beside options like `-show`,
`-dump-config` that apply to a single run) can be set here.
For example to set the dpi value to 72:
```css
configuration {
dpi: 72;
}
```
The configuration system supports the following types:
* string
@ -123,8 +85,8 @@ Below is a list of the most important options:
`-help`
The help option shows the full list of command-line options and the current set
values. These include dynamic (run-time generated) options.
The help option shows the full list of command-line options and the current set values.
These include dynamic (run-time generated) options.
`-version`
@ -143,11 +105,6 @@ Dump the current active theme, in rasi format, to stdout and exit.
Try to parse the file and return 0 when successful, non-zero when failed.
`-list-keybindings`
List all known keybindings without trying to parse them. This can be used to
look for duplicate bindings.
`-threads` *num*
Specify the number of threads **rofi** should use:
@ -174,45 +131,41 @@ Or get the options from a script:
~/my_script.sh | rofi -dmenu
See the **rofi-dmenu(5)** manpage for more information.
`-show` *mode*
Open **rofi** in a certain mode. Available modes are `window`, `run`, `drun`,
`ssh`, `combi`. The special argument `keys` can be used to open a searchable
list of supported key bindings
(see the **rofi-keys(5)** manpage)
Open **rofi** in a certain mode. Available modes are `window`, `run`, `drun`, `ssh`, `combi`.
The special argument `keys` can be used to open a searchable list of supported key bindings
(see *KEY BINDINGS*)
To show the run-dialog:
rofi -show run
If `-show` is the last option passed to rofi, the first enabled modes is shown.
If `-show` is the last option passed to rofi, the first enabled modi is shown.
`-modes` *mode1,mode2*
`-modi` *mode1,mode2*
Specify an ordered, comma-separated list of modes to enable.
Enabled modes can be changed at runtime. Default key is `Ctrl+Tab`.
If no modes are specified, all configured modes will be enabled.
To only show the `run` and `ssh` launcher:
rofi -modes "run,ssh" -show run
rofi -modi "run,ssh" -show run
Custom modes can be added using the internal `script` mode. Each such mode has
two parameters:
Custom modes can be added using the internal `script` mode. Each such mode has two parameters:
<name>:<script>
Example: Have a mode called 'Workspaces' using the `i3_switch_workspaces.sh` script:
rofi -modes "window,run,ssh,Workspaces:i3_switch_workspaces.sh" -show Workspaces
rofi -modi "window,run,ssh,Workspaces:i3_switch_workspaces.sh" -show Workspaces
Notes: The i3 window manager dislikes commas in the command when specifying an
exec command. For that case, `#` can be used as a separator.
Notes: The i3 window manager dislikes commas in the command when specifying an exec command.
For that case, `#` can be used as a separator.
**TIP**: The name is allowed to contain spaces:
rofi -modes "My File Browser:fb.sh" -show "My File Browser"
rofi -modi "My File Browser:fb.sh" -show "My File Browser"
`-case-sensitive`
@ -266,6 +219,10 @@ Specify icon theme to be used.
If not specified default theme from DE is used, *Adwaita* and *gnome* themes act as
fallback themes.
`-application-fallback-icon`
Specify an icon to be used when the application icon in run/drun are not yet loaded or is not available.
`-markup`
Use Pango markup to format output wherever possible.
@ -278,33 +235,6 @@ Make **rofi** react like a normal application window. Useful for scripts like Cl
Make rofi steal focus on launch and restore close to window that held it when launched.
`-refilter-timeout-limit`
The time (in ms) boundary filter may take before switch from instant to delayed filter mode.
Default: 300
A fallback icon can be specified for each mode:
```css
configuration {
<mode>{
fallback-icon: "<icon name>";
}
}
```
Example
```css
configuration {
run,drun {
fallback-icon: "application-x-addon";
}
}
```
### Matching
`-matching` *method*
@ -417,7 +347,7 @@ Keep a fixed number of visible lines.
`-sidebar-mode`
Open in sidebar-mode. In this mode, a list of all enabled modes is shown at the bottom.
(See `-modes` option)
(See `-modi` option)
To show sidebar, use:
rofi -show run -sidebar-mode
@ -543,12 +473,6 @@ See *PATTERN*.
Default: *{cmd}*
Example to run applications in a dedicated cgroup with systemd. Requires a shell to escape and interpolate the unit name correctly.
```
"bash -c 'systemd-run --user --unit=app-rofi-\$(systemd-escape {cmd})-\$RANDOM {cmd}'"
```
`-run-shell-command` *cmd*
Set command to execute when running an application in a shell.
@ -578,7 +502,7 @@ Format what is being displayed for windows.
* **r**: role
* **c**: class
*len*: maximum field length (0 for auto-size). If length is negative, the entry will be unchanged.
*len*: maximum field length (0 for auto-size). If length and window *width* are negative, field length is *width - len*.
If length is positive, the entry will be truncated or padded to fill that length.
@ -606,39 +530,16 @@ configuration {
}
}
```
You can hide the currently active window with the 'hide-active-window' setting:
```css
configuration {
window {
hide-active-window: true;
}
}
```
or pass `-window-hide-active-window true` on command line.
You can prefer the icon theme above the window set icon with the 'prefer-icon-theme' setting:
```css
configuration {
window {
prefer-icon-theme: true;
}
}
```
or pass `-window-prefer-icon-theme true` on command line.
### Combi settings
`-combi-modes ` *mode1*,*mode2*
`-combi-modi` *mode1*,*mode2*
The modes to combine in combi mode.
For syntax to `-combi-modes`, see `-modes`.
The modi to combine in combi mode.
For syntax to `-combi-modi`, see `-modi`.
To get one merge view, of `window`,`run`, and `ssh`:
rofi -show combi -combi-modes "window,run,ssh" -modes combi
rofi -show combi -combi-modi "window,run,ssh" -modi combi
**NOTE**: The i3 window manager dislikes commas in the command when specifying an exec command.
For that case, `#` can be used as a separator.
@ -654,7 +555,7 @@ Pango markup can be used to formatting the output.
Default: {mode} {text}
Note: This setting is ignored if `combi-hide-mode-prefix` is enabled.
Note: This setting is ignored if `combi-hide-mode-prefix` is eanbled.
### History and Sorting
@ -708,14 +609,10 @@ configuration {
sorting-method: "name";
/** Group directories before files. */
directories-first: true;
/** Show hidden files. */
show-hidden: false;
}
}
```
The `show-hidden` can also be triggered with the `kb-delete-entry` keybinding.
### Other
`-drun-use-desktop-cache`
@ -760,12 +657,6 @@ Click the mouse outside the **rofi** window to exit.
Default: *enabled*
`-xserver-i300-workaround`
Workaround for bug in Xserver. See issue #611 and #1642 on the rofi issue tracker.
Default: *disabled*
## PATTERN
To launch commands (for example, when using the ssh launcher), the user can enter the used command-line. The following keys can be used that will be replaced at runtime:
@ -783,10 +674,54 @@ Please see **rofi-theme(5)** manpage for more information on theming.
## KEY BINDINGS
Please see the **rofi-keys(5)** manpage for the keybindings and how to set them up.
**rofi** has the following key bindings:
The keybinding can also be used for actions, when the action is executed the
mentioned keystroke is inserted:
* `Control-v, Insert`: Paste from clipboard
* `Control-Shift-v, Shift-Insert`: Paste primary selection
* `Control-u`: Clear the line
* `Control-a`: Beginning of line
* `Control-e`: End of line
* `Control-f, Right`: Forward one character
* `Alt-f, Control-Right`: Forward one word
* `Control-b, Left`: Back one character
* `Alt-b, Control-Left`: Back one word
* `Control-d, Delete`: Delete character
* `Control-Alt-d`: Delete word
* `Control-h, Backspace, Shift-Backspace`: Backspace (delete previous character)
* `Control-Alt-h`: Delete previous word
* `Control-j,Control-m,Enter`: Accept entry
* `Control-n,Down`: Select next entry
* `Control-p,Up`: Select previous entry
* `Page Up`: Go to previous page
* `Page Down`: Go to next page
* `Control-Page Up`: Go to previous column
* `Control-Page Down`: Go to next column
* `Control-Enter`: Use entered text as a command (in `ssh/run modi`)
* `Shift-Enter`: Launch the application in a terminal (in run mode)
* `Control-Shift-Enter`: As Control-Enter and run the command in terminal (in run mode)
* `Shift-Enter`: Return the selected entry and move to the next item while keeping **rofi** open. (in dmenu)
* `Shift-Right`: Switch to the next mode. The list can be customized with the `-modi` argument.
* `Shift-Left`: Switch to the previous mode. The list can be customized with the `-modi` argument.
* `Control-Tab`: Switch to the next mode. The list can be customized with the `-modi` argument.
* `Control-Shift-Tab`: Switch to the previous mode. The list can be customized with the `-modi` argument.
* `Control-space`: Set selected item as input text.
* `Shift-Del`: Delete entry from history.
* `grave`: Toggle case sensitivity.
* `Alt-grave`: Toggle sorting.
* `Alt-Shift-S`: Take a screenshot and store it in the Pictures directory.
* `Control-l`: File complete for run dialog.
This list might not be complete, to get a full list of all key bindings
supported in your rofi, see `rofi -h`. The options starting with `-kb` are keybindings.
Key bindings can be modified using the configuration systems. Multiple keys can be bound
to one action by comma separating them. For example `-kb-primary-paste "Conctrol+v,Insert"`
To get a searchable list of key bindings, run `rofi -show keys`.
A key binding starting with `!` will act when all keys have been released.
You can bind certain events to key-actions:
### Timeout
@ -815,7 +750,9 @@ configuration {
}
```
## Available Modes
For a full list of bindings, see the **rofi-keys(5)** manpage.
## Available Modi
### window
@ -888,25 +825,25 @@ Shows a searchable list of key bindings.
### script
Allows custom scripted Modes to be added, see the **rofi-script(5)** manpage for more information.
Allows custom scripted Modi to be added, see the **rofi-script(5)** manpage for more information.
### combi
Combines multiple modes in one list. Specify which modes are included with the `-combi-modes` option.
Combines multiple modi in one list. Specify which modi are included with the `-combi-modi` option.
When using the combi mode, a *!bang* can be used to filter the results by modes.
All modes that match the bang as a prefix are included.
For example, say you have specified `-combi-modes run,window,windowcd`. If your
When using the combi mode, a *!bang* can be used to filter the results by modi.
All modi that match the bang as a prefix are included.
For example, say you have specified `-combi-modi run,window,windowcd`. If your
query begins with the bang `!w`, only results from the `window` and `windowcd`
modes are shown, even if the rest of the input text would match results from `run`.
modi are shown, even if the rest of the input text would match results from `run`.
If no match, the input is handled by the first combined modes.
If no match, the input is handled by the first combined modi.
## FAQ
### The text in the window switcher is not nicely aligned.
Try using a mono-space font or tabs + the tab-stops setting..
Try using a mono-space font.
### The window is completely black.
@ -936,19 +873,19 @@ Some basic usage examples of **rofi**:
Show the run dialog:
rofi -modes run -show run
rofi -modi run -show run
Show the run dialog, and allow switching to Desktop File run dialog (`drun`):
rofi -modes run,drun -show run
rofi -modi run,drun -show run
Combine the run and Desktop File run dialog (`drun`):
rofi -modes combi -show combi -combi-modes run,drun
rofi -modi combi -show combi -combi-modi run,drun
Combine the run and Desktop File run dialog (`drun`), and allow switching to window switcher:
rofi -modes combi,window -show combi -combi-modes run,drun
rofi -modi combi,window -show combi -combi-modi run,drun
Pop up a text message claiming that this is the end:
@ -962,6 +899,10 @@ Show all key bindings:
rofi -show keys
Use `qalc` to get a simple calculator in **rofi**:
rofi -show calc -modi "calc:qalc +u8 -nocurrencies"
## i3
In [i3](http://i3wm.org/) you want to bind **rofi** to be launched on key release. Otherwise, it cannot grab the keyboard.
@ -996,28 +937,66 @@ been released.
## WEBSITE
**rofi** website can be found [here](https://github.com/davatorium/rofi/)
**rofi** website can be found [here](https://davedavenport.github.io/rofi/)
## SUPPORT
**rofi** support can be obtained:
* [GitHub Discussions](https://github.com/davatorium/rofi/discussions)
* [Forum (Reddit)](https://reddit.com/r/qtools//)
* [IRC](irc://irc.libera.chat:6697/#rofi) (#rofi on irc.libera.chat),
## DEBUGGING
For more information see **rofi-debugging(5)** manpage.
To debug, it is smart to first try disabling your custom configuration:
`-no-config`
Disable parsing of configuration. This runs rofi in *stock* mode.
If you run custom C plugins, you can disable them using:
`-no-plugins`
Disables the loading of plugins.
To further debug the plugin, you can get a trace with (lots of) debug information. This debug output can be enabled for
multiple parts in rofi using the glib debug framework. Debug domains can be enabled by setting the G_MESSAGES_DEBUG
environment variable. At the time of creation of this page, the following debug domains exist:
* all: Show debug information from all domains.
* X11Helper: The X11 Helper functions.
* View: The main window view functions.
* Widgets.Box: The Box widget.
* Dialogs.DMenu: The dmenu mode.
* Dialogs.Run: The run mode.
* Dialogs.DRun: The desktop file run mode.
* Dialogs.Window: The window mode.
* Dialogs.Script: The script mode.
* Dialogs.Combi: The script mode.
* Dialogs.Ssh: The ssh mode.
* Rofi: The main application.
* Timings: Get timing output.
* Theme: Theme engine debug output. (warning lots of output).
* Widgets.Icon: The Icon widget.
* Widgets.Box: The box widget.
* Widgets.Container: The container widget.
* Widgets.Window: The window widget.
* Helpers.IconFetcher: Information about icon lookup.
The output of this can provide useful information when writing an issue.
More information (possibly outdated) see [this](https://github.com/DaveDavenport/rofi/wiki/Debugging%20Rofi) wiki entry.
## ISSUE TRACKER
The **rofi** issue tracker can be found [here](https://github.com/davatorium/rofi/issues)
Before creating an issue, consider posting a question on the [discussion forum](https://github.com/davatorium/rofi/discussions) first.
When creating an issue, please read [this](https://github.com/davatorium/rofi/blob/master/.github/CONTRIBUTING.md)
The **rofi** issue tracker can be found [here](https://github.com/DaveDavenport/rofi/issues)
When creating an issue, please read [this](https://github.com/DaveDavenport/rofi/blob/master/.github/CONTRIBUTING.md)
first.
## SEE ALSO
**rofi-sensible-terminal(1)**, **dmenu(1)**, **rofi-debugging(5)**, **rofi-theme(5)**, **rofi-script(5)**, **rofi-keys(5)**,**rofi-theme-selector(1)**,**rofi-dmenu(5)**
**rofi-sensible-terminal(1)**, **dmenu(1)**, **rofi-theme(5)**, **rofi-script(5)**, **rofi-keys(5)**,**rofi-theme-selector(1)**
## AUTHOR