From 1ac0618543e2601771888c0979892aa546417c5d Mon Sep 17 00:00:00 2001 From: Dave Davenport Date: Sun, 25 Dec 2016 12:28:57 +0100 Subject: [PATCH] Update index page and manpage page --- index.md | 59 ++++++--- manpage.html | 346 ++++++++++++++++++++++++++++++++++++++------------- 2 files changed, 301 insertions(+), 104 deletions(-) diff --git a/index.md b/index.md index f50b8bbd..35256ace 100644 --- a/index.md +++ b/index.md @@ -8,20 +8,21 @@ subtitle: A window switcher, run dialog and dmenu replacement > This site is currently looking for a maintainer. **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/). +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. It main features are: -* Full (configurable) keyboard navigation. +* Fully configurable keyboard navigation. * Type to filter - Tokenized: Type any word in any order to filter. - (toggable) Case insensitive. - - Supports regex and glob matching. + - Supports fuzzy, regex and glob matching. * UTF-8 enabled. - UTF-8 aware string collating. - intl. keyboard support (`e -> è) @@ -42,7 +43,7 @@ It main features are: * Themeing. **Rofi** has several buildin modes implementing common use-cases and can be exteneded by scripts (either called from -**Rofi** or calling **Rofi**). +**Rofi** or calling **Rofi**). Below the different modes are listed: @@ -52,19 +53,27 @@ Below the different modes are listed: The window switcher shows the following informations in columns (can be customized): -1. Desktop number +1. Desktop name 2. Window class. 3. Window title. +Window mode features: + + - Closing applications by hitting `Shift-Delete`. + - Custom command by `Shift-Return` + + ## Run mode ![run mode](https://davedavenport.github.io/rofi/images/rofi/run-dialog.png) The run mode allows users to quickly search and launch a program. + Run mode features: - Shift-Return to run the selected program in a terminal. - Favorites list, frequently used programs are sorted on top. + - Execute command to add custom entries, like aliases. ## DRun mode @@ -74,7 +83,7 @@ Entries. These are used by most common Desktop Environments to populate launcher Drun mode features: - Favorites list, frequently used programs are sorted on top. - - Auto starting terminal applications in a terminal. + - Auto starting terminal applications in a terminal. ## SSH launcher @@ -100,7 +109,7 @@ Allowing to quickly switch to an application, either by switching to it when it Example to combine Desktop run and the window switcher: ``` -rofi -combi-modi window,drun -show combi +rofi -combi-modi window,drun -show combi -modi combi ``` ## dmenu replacement @@ -114,7 +123,7 @@ Drop in dmenu replacement. (Screenshot shows rofi used by 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`). In addition to this rofi's dmenu mode can select multiple lines and -write them to stdout. +write them to stdout. # Usage @@ -124,7 +133,7 @@ If used with `-dmenu`, rofi will use data from STDIN to let the user select an o For example to show a run dialog: - `rofi -show run` + `rofi -show run` Show a ssh dialog: @@ -153,13 +162,14 @@ Type `Shift-/Left/Right` to switch between active modi. |:----------------------------|:-------------------------------------------------------------------| |`Ctrl-v, Insert` | Paste clipboard | |`Ctrl-Shift-v, Shift-Insert` | Paste primary selection | -|`Ctrl-u` | Clear the line | -|`Ctrl-a` | Beginning of line | -|`Ctrl-e` | End of line | -|`Ctrl-f, Right` | Forward one character | -|`Alt-f` | Forward one word | -|`Ctrl-b, Left` | Back one character | -|`Alt-b` | Back one word | +|`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 | |`Ctrl-d, Delete` | Delete character | |`Ctrl-Alt-d` | Delete word | |`Ctrl-h, Backspace` | Backspace (delete previous character) | @@ -195,6 +205,8 @@ There are currently three methods of setting configuration options: [here](https://en.wikipedia.org/wiki/X_resources) for more information. * Commandline options: Arguments passed to **Rofi**. +A distribution can ship defaults in `/etc/rofi.conf`. + The Xresources options and the commandline options are aliased. To define option X set: rofi.X: value @@ -226,8 +238,23 @@ The boolean option has a non-default commandline syntax, to enable option X you 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). # Installation Please see the [installation guide](https://davedavenport.github.io/rofi/p08-INSTALL.html) for instruction on how to install **Rofi**. + +# 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. diff --git a/manpage.html b/manpage.html index 42945ac5..ac867436 100644 --- a/manpage.html +++ b/manpage.html @@ -57,7 +57,7 @@ SYNOPSIS DESCRIPTION USAGE - OPTIONS + CONFIGURATION PATTERN DMENU REPLACEMENT THEMING @@ -65,8 +65,13 @@ KEYBINDINGS Available Modi FAQ + EXAMPLES LICENSE WEBSITE + SUPPORT + DEBUGGING + ISSUE TRACKER + SEE ALSO AUTHOR @@ -92,27 +97,24 @@ [ -location position ] [ -fixed-num-lines ] [ -padding padding ] -[ -opacity opacity% ] [ -display display ] [ -bw width ] [ -dmenu [ -p prompt ] [ -sep separator ] [ -l selected line ] [ -mesg ] [ -select ] [ -input input ] ] [ -filter filter ] [ -ssh-client client ] [ -ssh-command command ] +[ -window-command command ] [ -disable-history ] [ -levenshtein-sort ] [ -case-sensitive ] +[ -cycle ] [ -show mode ] [ -modi mode1,mode2 ] [ -eh element height ] -[ -lazy-filter-limit limit ] [ -e message] [ -a row ] [ -u row ] [ -pid path ] -[ -now ] -[ -rnow ] -[ -snow ] [ -version ] [ -help ] [ -dump-xresources ] @@ -123,9 +125,9 @@ [ -combi-modi mode1,mode2 ] [ -normal-window ] [ -fake-transparency ] -[ -glob ] -[ -regex ] +[ -matching method ] [ -tokenize ] +[ -no-click-to-exit ] [ -threads num ] [ -config filename ]

@@ -137,9 +139,13 @@ filter, tokenized search and more.

USAGE

-

rofi can be used in two ways, single-shot (runs a mode then exits) or emulating dmenu.

+

rofi main functionality is to assist in your workflow, allowing you to quickly (with a few keystrokes) switch +between windows, start applications or log into a remote machine via ssh. There are different modi for different type of +actions.

-

Single-shot mode

+

rofi can also function as (drop in) replacement for dmenu(1).

+ +

Running rofi

To launch rofi directly in a certain mode, specify a mode with rofi -show <mode>. To show the run dialog:

@@ -149,25 +155,28 @@ To show the run dialog:

Emulating dmenu

-

rofi can emulate dmenu (a dynamic menu for X) when launched with the -dmenu flag.

+

rofi can emulate dmenu(1) (a dynamic menu for X) when launched with the -dmenu flag.

-

The official website for dmenu can be found here.

+

The "official" website for dmenu can be found here.

-

OPTIONS

+

CONFIGURATION

There are currently three methods of setting configuration options (evaluated in order below):

+

TIP: To get a template config file run: rofi -dump-xresources > rofi-example.config.

+

The Xresources file expects options starting with rofi. followed by it's name. An Example to set the number of lines:

rofi.lines: 10
@@ -199,7 +208,7 @@ prefixed with a '-':

-X
 
-

to disable it:

+

To disable option X:

-no-X
 
@@ -211,7 +220,7 @@ prefixed with a '-':

-help

The help option shows the full list of commandline options and the current set value. -These include dynamic options.

+These include dynamic (run-time generated) options.

-dump-xresources

@@ -247,11 +256,9 @@ A simple example, displaying 3 pre-defined options:

~/my_script.sh | rofi -dmenu
 
-

Pressing the accept-custom binding (control-enter or shift-enter) sends the selected entry to STDOUT and moves to the next entry.

-

-show mode

-

Open rofi in a certain mode. Available modes are window, run, ssh +

Open rofi in a certain mode. Available modes are window, run,drun, ssh, combi To show the run-dialog:

rofi -show run
@@ -272,18 +279,19 @@ To only show the run and ssh launcher:

<name>:<script>
 
-

Example: Have a mode 'Workspaces' using the i3_switch_workspace.sh script:

+

Example: Have a mode 'Workspaces' using the i3_switch_workspaces.sh script:

rofi -modi "window,run,ssh,Workspaces:i3_switch_workspaces.sh" -show Workspaces
 

-case-sensitive

-

Start in case sensitive mode.

+

Start in case sensitive mode. +This option can be changed at run-time using the -kb-toggle-case-sensitivity key binding.

-

-fuzzy

+

-cycle

-

Enable experimental fuzzy matching.

+

Cycle through the results list. Default is 'true'.

-filter filter

@@ -299,7 +307,7 @@ To only show the run and ssh launcher:

Theming

-

All colors are either hex #rrggbb values or X11 color names.

+

All colors are either hex #rrggbb, #aarrggbb or argb:aarrggbbvalues or X11 color names.

-bw

@@ -319,15 +327,6 @@ To only show the run and ssh launcher:

Default: mono 12

-

-opacity

- -

Set window opacity (0-100).

- -
rofi -opacity "75"
-
- -

Default: 100

-

-eh element height

The height of a field in lines. e.g.

@@ -339,11 +338,7 @@ To only show the run and ssh launcher:

The following options are further explained in the theming section:

-

-color-enabled

- -

Enable the extended coloring options.

- -

-color-window background border color separator color /

+

-color-window background border color separator color

Set window background, border and separator color.

@@ -379,14 +374,22 @@ Max: *50*

Set the scrollbar width.

-

-glob

+

-matching method

-

Use glob style matching -Warning this option might be slow on large lists

+

Specify the matching algorithm used. +Current the following methods are supported.

-

-regex

+
    +
  • normal: Match the int string.
  • +
  • regex: Match a regex input.
  • +
  • glob: Match a glob pattern.
  • +
  • fuzzy: Do a fuzzy match.

    + +

    Default: normal

    + +

    Note:, glob matching might be slow for larger lists.

  • +
-

Use regex matching

-tokenize

@@ -467,37 +470,36 @@ To show sidebar use:

rofi -show run -sidebar-mode -lines 0
 
-

-lazy-filter-limit limit

- -

The number of entries required for rofi to go into lazy filter mode. -In lazy filter mode, it won't re-filter the list on each keypress, but only after rofi been -idle for 250ms. Experiments shows that the default (5000 lines) works well, set to 0 to always -enable.

- -

Default: 5000

-

-auto-select

When one entry is left, automatically select it.

-

-m num --monitor num

+

-m num

-

Select (Xinerama) monitor to display rofi on. -Negative numbers are handled differently:

+

-m name

+ +

-monitor num

+ +

-monitor name

+ +

Select monitor to display rofi on. +As input it accepts: primary (if primary output is set), the xrandr output name or integer number (in order of +detection). Negative numbers are handled differently:

  • -1: the currently focused monitor.
  • -2: the currently focused window (i.e. rofi will be displayed on top of the focused window).
  • -
  • -3: Position at mouse (still follows the location setting, use -location 1 to get normal context menu +
  • -3: Position at mouse (overrides the location setting to get normal context menu behaviour.)
  • -4: the monitor with the focused window.
  • -5: the monitor that shows the mouse pointer.

    -

    Default: -1

  • +

    Default: -5

+

See rofi -h output for the detected monitors, their position and size.

+

PATTERN setting

-terminal

@@ -524,7 +526,8 @@ Default: ssh

Set the command to execute when starting a ssh session. The pattern {host} is replaced by the selected ssh entry.

-

Default: {terminal} -e {ssh-client} {host}

+

Pattern: {ssh-client} +Default: {terminal} -e {ssh-client} {host}

-parse-hosts

@@ -561,6 +564,13 @@ See PATTERN.

Default: ""

+

-window-command cmd

+ +

Set command to execute on selected window for custom action. +See PATTERN.

+ +

Default: "xkill -id {window}"

+

Combi settings

-combi-modi mode1,mode2

@@ -569,7 +579,7 @@ See PATTERN.

For syntax to see -modi. To get one merge view, of window,run,ssh:

-
rofi -show combi -combi-modi "window,run,ssh"
+
rofi -show combi -combi-modi "window,run,ssh" -modi combi
 

History and Sorting

@@ -582,7 +592,8 @@ To get one merge view, of window,run,ssh:

-levenshtein-sort to enable -no-levenshtein-sort to disable

-

When searching sort the result based on levenshtein distance.

+

When searching sort the result based on levenshtein distance. +This setting can be changed at runtime, see -kb-toggle-sort.

Dmenu specific

@@ -674,7 +685,7 @@ For more information on supported markup see here for details about pango markup.

+ +

-multi-select

+ +

Allow multiple lines to be selected. Adds a small selection indicator to the left of each entry.

+ +

-sync

+ +

Force rofi mode to first read all data from stdin before showing selection window. This is how original dmenu behaviour.

+ +

Window Mode

+ +

-window-format format

+ +

Format what is being displayed for windows.

+ +

format: {field[:len]}

+ +

field:

+ +
    +
  • w: Desktop name
  • +
  • t: Title of window
  • +
  • n: Name
  • +
  • r: Role
  • +
  • c: Class
  • +
+ + +

len: maximum field length (0 for auto-size). If length negative and window width is negative field length is width - len. +if length is positive, the entry will be truncated or padded to fill that length.

+ +

default: {w} {c} {t}

+

Message dialog

-e message

@@ -699,14 +747,30 @@ Message can be multi-line.

Other

-

'-pid' path

+

-pid path

Make rofi create a pid file and check this on startup. Avoiding multiple copies running simultaneously. This is useful when running rofi from a keybinding daemon.

-fake-transparency

-

Enable fake transparency. This only works with transparent background color in the theme, not the opacity setting.

+

Enable fake transparency. This only works with transparent background color in the theme.

+ +

-fake-background

+ +

Select what to use as background for fake transparency. This can be 'background', 'screenshot' or a path to an image +file (currently only supports png).

+ +

-display-{mode} string

+ +

Set the name to use for mode. This is used as prompt and in combi-browser.

+ +

-click-to-exit +-no-click-to-exit

+ +

Click the mouse outside of the rofi window to exit.

+ +

Default: enabled

Debug

@@ -714,6 +778,8 @@ simultaneously. This is useful when running rofi from a keybind

Disable parsing of configuration. This runs rofi in stock mode.

+

For more information on debugging see the wiki

+

PATTERN

To launch commands (e.g. when using the ssh launcher) the user can enter the used command-line, @@ -724,6 +790,7 @@ the following keys can be used that will be replaced at runtime:

  • {terminal}: The configured terminal (See -terminal-emulator)
  • {ssh-client}: The configured ssh client (See -ssh-client)
  • {cmd}: The command to execute.
  • +
  • {window}: The window id of the selected window. (In window-command)
  • @@ -737,9 +804,8 @@ This way it can be used as a drop-in replacement for dmenu. just copy or symlink

    THEMING

    -

    With rofi 0.15.4 we have a new way of specifying colors, the old settings still apply (for now). -To enable the new setup, set rofi.color-enabled to true. The new setup allows you to specify -colors per state, similar to i3 +

    With rofi 0.15.4 we have a new way of specifying theme colors. +The new setup allows you to specify colors per state, similar to i3 Currently 3 states exists:

      @@ -761,7 +827,7 @@ Currently 3 states exists:

      The window background and border color should be specified separate. The key color-window contains -a pair background,border. +a pair background,border,separator. An example for Xresources file:

      ! State:           'bg',     'fg',     'bgalt',  'hlbg',   'hlfg'
      @@ -769,8 +835,8 @@ rofi.color-normal: #fdf6e3,  #002b36,  #eee8d5,  #586e75,  #eee8d5
       rofi.color-urgent: #fdf6e3,  #dc322f,  #eee8d5,  #dc322f,  #fdf6e3
       rofi.color-active: #fdf6e3,  #268bd2,  #eee8d5,  #268bd2,  #fdf6e3
       
      -!                  'background', 'border'
      -rofi.color-window: #fdf6e3,      #002b36
      +!                  'background', 'border', 'separator'
      +rofi.color-window: #fdf6e3,      #002b36,  #002b36
       

      Same settings can also be specified on command-line:

      @@ -780,17 +846,34 @@ rofi.color-window: #fdf6e3, #002b36

      COLORS

      -

      Rofi has an experimental mode for a 'nicer' transparency. The idea is to make the -background of the window transparent, leaving the text opaque. -There are 2 requirements for this feature: 1. Your Xserver supports TrueColor, 2. You are running a -composite manager. If this is satisfied you can use the following format for colors:

      +

      RGB colors can be specified by either its X11 name, or hexadecimal notation. +For example:

      + +
      white
      +
      + +

      Or

      + +
      #FFFFFF
      +
      + +

      ARGB colors are also support, these can be used to create a transparent window if: 1. Your Xserver supports TrueColor, 2. +You are running a composite manager.

      argb:FF444444
       
      +

      Or

      + +
      #FF444444
      +
      +

      The first two fields specify the alpha level. This determines the amount of transparency. (00 everything, FF nothing). The other fields represent the actual color, in hex.

      +

      Within rofi transparency can be used, e.g. if the selected background color is 50% transparent, the background color +of the window will be visible through it.

      +

      KEYBINDINGS

      rofi has the following key-bindings:

      @@ -831,49 +914,64 @@ composite manager. If this is satisfied you can use the following format for col
    -

    To get a full list of keybindings, see rofi -dump-xresources | grep kb-. -Keybindings can be modified using the configuration systems.

    +

    To get a full list of keybindings on the commandline, see rofi -dump-xresources | grep kb-. +Keybindings can be modified using the configuration systems. +To get searchable list of keybindings, run rofi -show keys.

    + +

    A keybinding starting with ! will act when all keys have been released.

    Available Modi

    Window

    -

    Show a list of all the windows and allow switching between them.

    +

    Show a list of all the windows and allow switching between them. +Pressing the delete-entry binding (shift-delete) will close the window. +Pressing the accept-custom binding (control-enter or shift-enter) will run a command on the window. +(See option window-command );

    WindowCD

    -

    Shows a list of the windows on the current desktop and allows switching between them.

    +

    Shows a list of the windows on the current desktop and allows switching between them. +Pressing the delete-entry binding (shift-delete) will kill the window. +Pressing the accept-custom binding (control-enter or shift-enter) will run a command on the window. +(See option window-command );

    Run

    Shows a list of executables in $PATH and can launch them (optional in a terminal). +Pressing the delete-entry binding (shift-delete) will remove this entry from the run history. Pressing the accept-custom binding (control-enter or shift-enter) will run the command in a terminal.

    DRun

    Same as the run launches, but the list is created from the installed desktop files. It automatically launches them in a terminal if specified in the Desktop File. +Pressing the delete-entry binding (shift-delete) will remove this entry from the run history. Pressing the accept-custom binding (control-enter or shift-enter) with custom input (no entry matching) will run the command in a terminal.

    SSH

    Shows a list of SSH targets based on your ssh config file, and allows to quickly ssh into them.

    +

    Keys

    + +

    Shows a searchable list of key bindings.

    +

    Script

    Allows custom scripted Modi to be added.

    FAQ

    -

    Text in window switcher is not nicely lined out

    +

    The text in the window switcher is not nicely lined out.

    Try using a mono-space font.

    -

    rofi is completely black.

    +

    The window is completely black.

    Check quotes used on the commandline: e.g. used “ instead of ".

    -

    rofi what does the icon in the top right show?

    +

    What does the icon in the top right show?

    The indicator shows:

    @@ -883,6 +981,60 @@ Pressing the accept-custom binding (control-enter or < `±` Sorting and Case sensitivity enabled"
    +

    EXAMPLES

    + +

    Some basic usage examples of rofi:

    + +

    Show the run dialog:

    + +
    rofi -modi run -show run
    +
    + +

    Show the the run dialog and allow switching to Desktop File run dialog (drun):

    + +
    rofi -modi run,drun -show run
    +
    + +

    Combine the run and Desktop File run dialog (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 -modi combi,window -show combi -combi-modi run,drun
    +
    + +

    Run rofi full monitor width at the top of the monitor like a dropdown menu:

    + +
    rofi -show run -width 100 -location 1 -lines 5 -bw 2 -yoffset -2
    +
    + +

    Get a colored list of available wifi networks:

    + +
    tty-pipe nmcli device wifi | out2html -p | rofi -dmenu -markup-rows
    +
    + +

    Popup a text message claiming that this is the end:

    + +
    rofi -e "This is the end"
    +
    + +

    Popup a text message in red, bold font claiming that this is still the end:

    + +
    rofi -e "<span color='red'><b>This is still the end</b></span>>" -markup
    +
    + +

    Show all keybindings:

    + +
    rofi -show keys
    +
    + +

    Use qalc to get a simple calculator in rofi:

    + +
     rofi -show calc -modi "calc:qalc +u8 -nocurrencies"
    +
    +

    LICENSE

    MIT/X11
    @@ -911,24 +1063,42 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
     
     

    rofi website can be found at here

    -

    rofi bugtracker can be found here

    +

    SUPPORT

    + +

    rofi support can be obtained here (#rofi on irc.freenode.net), or via the +forum

    + +

    DEBUGGING

    + +

    Please see this wiki entry.

    + +

    ISSUE TRACKER

    + +

    rofi issue tracker can be found here

    + +

    When creating an issue, please read this +first.

    + +

    SEE ALSO

    + +

    rofi-sensible-terminal(1), dmenu(1)

    AUTHOR

    -

    Qball Cow qball@gmpclient.org

    +

    Qball Cow qball@gmpclient.org

    -

    Rasmus Steinke rasi@xssn.at

    +

    Rasmus Steinke rasi@xssn.at

    -

    Quentin Glidic sardemff7+rofi@sardemff7.net

    +

    Quentin Glidic sardemff7+rofi@sardemff7.net

    -

    Original code based on work by: Sean Pringle sean.pringle@gmail.com

    +

    Original code based on work by: Sean Pringle sean.pringle@gmail.com

    For a full list of authors, check the AUTHORS file.

    1. -
    2. 2016-05-02
    3. +
    4. December 2016
    5. rofi-manpage