From a10543e6c58851dd80e39712e7fb62cbceab9f55 Mon Sep 17 00:00:00 2001 From: Dave Davenport Date: Mon, 4 Jul 2016 17:29:58 +0200 Subject: [PATCH] Update README. --- README.md | 88 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 56 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 98ced278..b4fbb1e2 100644 --- a/README.md +++ b/README.md @@ -7,45 +7,54 @@ # A window switcher, run dialog and dmenu replacement -A popup window switcher roughly based on [superswitcher](http://code.google.com/p/superswitcher/). -This version started off as a clone of simpleswitcher, the version from [Sean -Pringle](http://github.com/seanpringle/simpleswitcher). All credit for this great tool should go to him. -Rofi developed extra features, like a run-dialog, ssh-launcher and can act as a drop-in dmenu -replacement, making it a very versatile tool. +**Rofi** started as clone of simpleswitcher, written by [Sean Pringle](http://github.com/seanpringle/simpleswitcher) a +popup window switcher roughly based on [superswitcher](http://code.google.com/p/superswitcher/). +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. -Using Rofi is a lot like dmenu, but extended for an improved work flow. It main features are: * Full (configurable) keyboard navigation. * Type to filter - Tokenized: Type any word in any order to filter. - - Case insensitive + - (toggable) Case insensitive. + - Supports regex and glob matching. * UTF-8 enabled. - UTF-8 aware string collating. - intl. keyboard support (`e -> รจ) -* Pango font rendering. * RTL language support. -* Window Switcher. - - I3 support. - - EWMH compatible WM. -* Run dialog. -* Desktop File Run dialog. -* SSH launcher. +* Cairo drawing and Pango font rendering. +* Build in modes: + - Window switcher mode. + - EWMH compatible WM. + - Workaround for older I3 installations. + - Run mode. + - Desktop File Run mode. + - SSH launcher mode. + - Combi mode, allow several modes to be merged into one list. * History based ordering last 25 choices are ordered on top based on use. (optional) * Levenshtein distance ordering of matches. (optional) * Drop in dmenu replacement. - With many added improvements. * Can be easily extended using scripts. +* Themeing. -The 4 Main functions of rofi are: +**Rofi** has several buildin modes implementing common use-cases and can be exteneded by scripts (either called from +**Rofi** or calling **Rofi**). + +Below the different modes are listed: ## Window Switcher ![Window List](https://davedavenport.github.io/rofi/images/rofi/window-list.png) -The window switcher shows the following informations in columns: +The window switcher shows the following informations in columns (can be customized): -1. Desktop number (optional, not shown in I3 mode) +1. Desktop number 2. Window class. 3. Window title. @@ -53,20 +62,23 @@ If compiled with I3 support, it should autodetect if I3 window manager is runnin I3 compatibility mode. This will disable Desktop numbers and hide the i3-bar, also it sends an IPC message to I3 to change focus. -## Run dialog +> Note: With the latest I3 this is no longer needed as I3 obeys EWHM hints. +> The 'dedicated' support of I3 will be removed from future releases. -![run dialog](https://davedavenport.github.io/rofi/images/rofi/run-dialog.png) +## Run mode -The run dialog allows the user to quickly search and launch a program. +![run mode](https://davedavenport.github.io/rofi/images/rofi/run-dialog.png) + +The run mode allows the user to quickly search and launch a program. It offers the following features: - Shift-Return to run the selected program in a terminal. - Favorites list, frequently used programs are sorted on top. -## DRun dialog +## DRun mode -The desktop run dialog allows the user to quickly search and launch an application from the *freedesktop.org* Desktop +The desktop run mode allows the user to quickly search and launch an application from the *freedesktop.org* Desktop Entries. E.g. what is used by Desktop Environment to fill their launcher. It offers the following features: - Favorites list, frequently used programs are sorted on top. @@ -80,6 +92,14 @@ Quickly ssh into remote machines - Parses ~/.ssh/config to find hosts. +## Script mode + +Loads external scripts to add modes to **Rofi**, for example a file-browser. + +## 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. ## dmenu replacement @@ -88,7 +108,7 @@ Quickly ssh into remote machines Drop in dmenu replacement. (Screenshot shows rofi used by [teiler](https://github.com/carnager/teiler) ). -**rofi** features several improvements over dmenu to improve usability. There is the option to add +**Rofi** features several improvements over dmenu to improve usability. There is the option to add 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 provided option (`-only-match`). @@ -99,11 +119,9 @@ 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. -## Single-shot +For example to show a run dialog: -Show a run dialog with some font / color options: - - `rofi -show run -font "snap 10" -fg "#505050" -bg "#000000" -hlfg "#ffb964" -hlbg "#000000" -o 85` + `rofi -show run` Show a ssh dialog: @@ -163,20 +181,21 @@ Type `Shift-Right` to switch from Window list mode to Run mode and back. |`Alt-grave` | Toggle levenshtein sort. | |`Alt-Shift-S` | Take a screenshot and store this in the Pictures directory. | +For the full list of keybindings see: `rofi -show keys` or `rofi -help`. # Configuration There are currently three methods of setting configuration options: - * Compile time: edit config.c. This method is strongly discouraged. + * Local configuration. Normally, depending on XDG, in `~/.local/rofi/config`. This uses the Xresources format. * Xresources: A method of storing key values in the Xserver. See [here](https://en.wikipedia.org/wiki/X_resources) for more information. - This is the recommended way of configuring **rofi**. Remember to load your changes with `xrdb -load ~/.Xresources` - * Commandline options: Arguments passed to **rofi**. + This is the recommended way of configuring **Rofi**. Remember to load your changes with `xrdb -load ~/.Xresources` + * Commandline options: Arguments passed to **Rofi**. The Xresources options and the commandline options are aliased. So to set option X you would set: -`rofi.X: value` + rofi.X: value In the Xresources file, and to (override) this via the commandline you would pass the same key prefixed with a '-': @@ -187,6 +206,10 @@ To get a list of available options, formatted as Xresources entries run: rofi -dump-Xresources +or in a more readable format + + rofi -help + The configuration system supports the following types: * String @@ -204,4 +227,5 @@ to disable it: # Installation -Please see the [installation guide](https://davedavenport.github.io/rofi/p08-INSTALL.html) for instruction on how to install *rofi*. +Please see the [installation guide](https://davedavenport.github.io/rofi/p08-INSTALL.html) for instruction on how to +install **Rofi**.