rofi/README.md

264 lines
10 KiB
Markdown
Raw Normal View History

2015-12-31 20:33:20 +00:00
[![Build Status](https://travis-ci.org/DaveDavenport/rofi.svg?branch=master)](https://travis-ci.org/DaveDavenport/rofi)
[![codecov.io](https://codecov.io/github/DaveDavenport/rofi/coverage.svg?branch=master)](https://codecov.io/github/DaveDavenport/rofi?branch=master)
2016-05-30 19:15:50 +00:00
[![Issues](https://img.shields.io/github/issues/DaveDavenport/rofi.svg)](https://github.com/DaveDavenport/rofi/issues)
[![Forks](https://img.shields.io/github/forks/DaveDavenport/rofi.svg)](https://github.com/DaveDavenport/rofi/network)
[![Stars](https://img.shields.io/github/stars/DaveDavenport/rofi.svg)](https://github.com/DaveDavenport/rofi/stargazers)
2016-05-30 19:24:12 +00:00
[![Downloads](https://img.shields.io/github/downloads/DaveDavenport/rofi/total.svg)](https://github.com/DaveDavenport/rofi/releases)
2016-10-17 18:58:50 +00:00
[![Coverity](https://scan.coverity.com/projects/3850/badge.svg)](https://scan.coverity.com/projects/davedavenport-rofi)
2016-11-12 13:51:23 +00:00
[![Forum](https://img.shields.io/badge/forum-online-green.svg)](https://forum.qtools.org)
2015-12-31 20:33:20 +00:00
2015-05-05 09:33:54 +00:00
# A window switcher, run dialog and dmenu replacement
2014-08-28 19:36:53 +00:00
2016-07-04 15:29:58 +00:00
**Rofi** started as clone of simpleswitcher, written by [Sean Pringle](http://github.com/seanpringle/simpleswitcher) a
2016-12-07 17:20:05 +00:00
popup window switcher roughly based on [superswitcher](http://code.google.com/p/superswitcher/).
2016-07-04 15:29:58 +00:00
Simpleswitcher laid the foundations and therefor Sean Pringle deserves most of the credit for this tool. **Rofi**,
renamed as it lost the *simple* property, has been extended with extra features, like a run-dialog, ssh-launcher and
can act as a drop-in dmenu replacement, making it a very versatile tool.
**Rofi**, like dmenu, will provide the user with a textual list of options where one or more can be selected.
This can either be, running an application, selecting a window or options provided by an external script.
2015-01-20 22:34:53 +00:00
2015-05-04 13:37:54 +00:00
It main features are:
2016-12-07 17:20:05 +00:00
* Fully configurable keyboard navigation.
2015-05-04 13:37:54 +00:00
* Type to filter
- Tokenized: Type any word in any order to filter.
2016-07-04 15:29:58 +00:00
- (toggable) Case insensitive.
2016-12-07 17:20:05 +00:00
- Supports fuzzy, regex and glob matching.
2015-05-04 13:37:54 +00:00
* UTF-8 enabled.
- UTF-8 aware string collating.
- intl. keyboard support (`e -> è)
* RTL language support.
2016-07-04 15:29:58 +00:00
* Cairo drawing and Pango font rendering.
* Build in modes:
- Window switcher mode.
- EWMH compatible WM.
- Run mode.
- Desktop File Run mode.
- SSH launcher mode.
- Combi mode, allow several modes to be merged into one list.
2015-05-04 13:37:54 +00:00
* History based ordering last 25 choices are ordered on top based on use. (optional)
* Levenshtein distance ordering of matches. (optional)
* Drop in dmenu replacement.
2015-05-26 14:50:41 +00:00
- With many added improvements.
2015-05-04 13:37:54 +00:00
* Can be easily extended using scripts.
2016-07-04 15:29:58 +00:00
* Themeing.
**Rofi** has several buildin modes implementing common use-cases and can be exteneded by scripts (either called from
2016-12-07 17:20:05 +00:00
**Rofi** or calling **Rofi**).
2015-05-04 13:37:54 +00:00
2016-07-04 15:29:58 +00:00
Below the different modes are listed:
2015-05-04 13:37:54 +00:00
## Window Switcher
![Window List](https://davedavenport.github.io/rofi/images/rofi/window-list.png)
2016-07-04 15:29:58 +00:00
The window switcher shows the following informations in columns (can be customized):
2015-05-04 13:37:54 +00:00
2016-12-07 17:20:05 +00:00
1. Desktop name
2015-05-04 13:37:54 +00:00
2. Window class.
3. Window title.
2016-12-07 17:20:05 +00:00
Window mode features:
- Closing applications by hitting `Shift-Delete`.
- Custom command by `Shift-Return`
2016-07-04 15:29:58 +00:00
## Run mode
2015-05-04 13:37:54 +00:00
2016-07-04 15:29:58 +00:00
![run mode](https://davedavenport.github.io/rofi/images/rofi/run-dialog.png)
2015-05-04 13:37:54 +00:00
2016-07-18 14:03:16 +00:00
The run mode allows users to quickly search and launch a program.
2016-12-07 17:20:05 +00:00
2016-07-18 14:03:16 +00:00
Run mode features:
2015-05-04 13:37:54 +00:00
- Shift-Return to run the selected program in a terminal.
- Favorites list, frequently used programs are sorted on top.
2016-12-07 17:20:05 +00:00
- Execute command to add custom entries, like aliases.
2015-05-04 13:37:54 +00:00
2016-07-04 07:29:43 +00:00
2016-07-04 15:29:58 +00:00
## DRun mode
2016-07-04 07:29:43 +00:00
2016-07-18 14:03:16 +00:00
The desktop run mode allows users to quickly search and launch an application from the *freedesktop.org* Desktop
Entries. These are used by most common Desktop Environments to populate launchers and menus.
Drun mode features:
2016-07-04 07:29:43 +00:00
- Favorites list, frequently used programs are sorted on top.
2016-12-07 17:20:05 +00:00
- Auto starting terminal applications in a terminal.
2015-12-07 07:56:47 +00:00
2015-05-04 13:37:54 +00:00
## SSH launcher
![SSH Launcher](https://davedavenport.github.io/rofi/images/rofi/ssh-dialog.png)
Quickly ssh into remote machines
- Parses ~/.ssh/config to find hosts.
2016-07-04 15:29:58 +00:00
## Script mode
Loads external scripts to add modes to **Rofi**, for example a file-browser.
2016-07-28 06:11:23 +00:00
```
rofi -show fb -modi fb:../Examples/rofi-file-browser.sh
```
2016-07-04 15:29:58 +00:00
## COMBI mode
Combine multiple modes in one view. This is especially usefull when merging the window and run mode into one view.
Allowing to quickly switch to an application, either by switching to it when it is already running or starting it.
2015-05-04 13:37:54 +00:00
2016-07-28 06:11:23 +00:00
Example to combine Desktop run and the window switcher:
```
2016-12-07 17:20:05 +00:00
rofi -combi-modi window,drun -show combi -modi combi
2016-07-28 06:11:23 +00:00
```
2015-05-04 13:37:54 +00:00
## dmenu replacement
![DMENU replacement (running teiler)](https://davedavenport.github.io/rofi/images/rofi/dmenu-replacement.png)
Drop in dmenu replacement. (Screenshot shows rofi used by
[teiler](https://github.com/carnager/teiler) ).
2016-07-04 15:29:58 +00:00
**Rofi** features several improvements over dmenu to improve usability. There is the option to add
2015-05-26 14:50:41 +00:00
an extra message bar (`-mesg`), pre-entering of text (`-filter`) or selecting entries based on a
pattern (`-select`). Also highlighting (`-u` and `-a`) options and modi to force user to select one
2016-07-18 14:03:16 +00:00
provided option (`-only-match`). In addition to this rofi's dmenu mode can select multiple lines and
2016-12-07 17:20:05 +00:00
write them to stdout.
2015-05-26 14:50:41 +00:00
2015-05-04 13:37:54 +00:00
# Usage
If used with `-show [mode]`, rofi will immediately open in the specified [mode]
If used with `-dmenu`, rofi will use data from STDIN to let the user select an option.
2016-07-04 15:29:58 +00:00
For example to show a run dialog:
2015-05-04 13:37:54 +00:00
2016-12-07 17:20:05 +00:00
`rofi -show run`
2015-05-04 13:37:54 +00:00
Show a ssh dialog:
`rofi -show ssh`
## dmenu
If passed the `-dmenu` option, or ran as `dmenu` (ie, /usr/bin/dmenu is symlinked to /usr/bin/rofi),
rofi will use the data passed from STDIN.
```
~/scripts/my_script.sh | rofi -dmenu
echo -e "Option #1\nOption #2\nOption #3" | rofi -dmenu
```
2015-05-04 13:37:54 +00:00
In both cases, rofi will output the user's selection to STDOUT.
## Switching Between Modi
2016-07-18 14:03:16 +00:00
Type `Shift-/Left/Right` to switch between active modi.
2015-05-04 13:37:54 +00:00
## Keybindings
| Key | Action |
|:----------------------------|:-------------------------------------------------------------------|
|`Ctrl-v, Insert` | Paste clipboard |
|`Ctrl-Shift-v, Shift-Insert` | Paste primary selection |
2016-12-07 17:20:05 +00:00
|`Ctrl-w` | Clear the line |
|`Ctrl-u` | Delete till the start of line |
|`Ctrl-a` | Move to beginning of line |
|`Ctrl-e` | Move to end of line |
|`Ctrl-f, Right` | Move forward one character |
|`Alt-f` | Move forward one word |
|`Ctrl-b, Left` | Move back one character |
|`Alt-b` | Move back one word |
2015-05-04 13:37:54 +00:00
|`Ctrl-d, Delete` | Delete character |
|`Ctrl-Alt-d` | Delete word |
|`Ctrl-h, Backspace` | Backspace (delete previous character) |
|`Ctrl-Alt-h` | Delete previous word |
|`Ctrl-j,Ctrl-m,Enter` | Accept entry |
|`Ctrl-n,Down` | Select next entry |
|`Ctrl-p,Up` | Select previous entry |
|`Page Up` | Go to the previous page |
|`Page Down` | Go to the next page |
|`Ctrl-Page Up` | Go to the previous column |
|`Ctrl-Page Down` | Go to the next column |
|`Ctrl-Enter` | Use entered text as command (in ssh/run modi) |
|`Shift-Enter` | Launch the application in a 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 modi. The list can be customized with the -modi option. |
|`Shift-Left` | Switch to the previous modi. The list can be customized with the -modi option. |
|`Ctrl-Tab` | Switch to the next modi. The list can be customized with the -modi option. |
|`Ctrl-Shift-Tab` | Switch to the previous modi. The list can be customized with the -modi option. |
2015-05-04 13:37:54 +00:00
|`Ctrl-space` | Set selected item as input text. |
|`Shift-Del` | Delete entry from history. |
2015-12-07 07:56:47 +00:00
|`grave` | Toggle case sensitivity. |
2015-12-13 10:50:59 +00:00
|`Alt-grave` | Toggle levenshtein sort. |
2015-12-09 07:29:18 +00:00
|`Alt-Shift-S` | Take a screenshot and store this in the Pictures directory. |
2015-05-04 13:37:54 +00:00
2016-07-04 15:29:58 +00:00
For the full list of keybindings see: `rofi -show keys` or `rofi -help`.
2015-05-04 13:37:54 +00:00
# Configuration
There are currently three methods of setting configuration options:
2016-07-04 15:29:58 +00:00
* Local configuration. Normally, depending on XDG, in `~/.local/rofi/config`. This uses the Xresources format.
2015-05-04 13:37:54 +00:00
* Xresources: A method of storing key values in the Xserver. See
[here](https://en.wikipedia.org/wiki/X_resources) for more information.
2016-07-04 15:29:58 +00:00
* Commandline options: Arguments passed to **Rofi**.
2015-05-04 13:37:54 +00:00
2016-12-07 17:20:05 +00:00
A distribution can ship defaults in `/etc/rofi.conf`.
2016-07-18 14:03:16 +00:00
The Xresources options and the commandline options are aliased. To define option X set:
2015-05-04 13:37:54 +00:00
2016-07-04 15:29:58 +00:00
rofi.X: value
2015-05-04 13:37:54 +00:00
2016-07-18 14:03:16 +00:00
In the Xresources file. To set/override this from commandline pass the same key
prefixed with '-':
2015-05-04 13:37:54 +00:00
rofi -X value
To get a list of available options, formatted as Xresources entries run:
rofi -dump-Xresources
2016-07-04 15:29:58 +00:00
or in a more readable format
rofi -help
2015-05-04 13:37:54 +00:00
The configuration system supports the following types:
* String
* Integer (signed and unsigned)
* Char
* Boolean
The boolean option has a non-default commandline syntax, to enable option X you do:
rofi -X
to disable it:
rofi -no-X
# Manpage
For more detailed information, please see the [manpage](doc/rofi-manpage.markdown), the [wiki](https://github.com/DaveDavenport/rofi/wiki) or the [forum](https://forum.qtools.org).
2015-05-04 13:37:54 +00:00
# Installation
2016-07-04 15:29:58 +00:00
Please see the [installation guide](https://davedavenport.github.io/rofi/p08-INSTALL.html) for instruction on how to
install **Rofi**.
2016-12-22 14:59:13 +00:00
# What is rofi not?
Rofi is not:
* A preview application. In other words, it will not show a (small) preview of image, movie or other files.
* A UI toolkit.
* A library to be used in other applications.
* An application that can support every possible use-case. It tries to generic enough to be usable by everybody.
Specific functionality can be added using scripts.
* Just a dmenu replacement. The dmenu functionality is a nice 'extra' to **rofi** not it main purpose.