diff --git a/doc/rofi-theme.5 b/doc/rofi-theme.5 index 52928dcf..40e1a80a 100644 --- a/doc/rofi-theme.5 +++ b/doc/rofi-theme.5 @@ -1,7 +1,7 @@ .\" generated with Ronn/v0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3 . -.TH "ROFI\-THEME" "5" "May 2019" "" "" +.TH "ROFI\-THEME" "5" "September 2019" "" "" . .SH "NAME" \fBrofi\-theme\fR \- Rofi theme format files @@ -1167,7 +1167,25 @@ inputbar Packs: \fBprompt,entry,case\-indicator\fR .IP "" 0 . .P -Any widget name starting with \fBtextbox\fR is a textbox widget, others are box widgets and can pack other widgets\. To specify children, set the \fBchildren\fR property (this always happens on the \fBbox\fR child, see example below): +Any widget name starting with \fBtextbox\fR is a textbox widget, others are box widgets and can pack other widgets\. +. +.P +There are several special widgets that can be used by prefixing the name of the widget: +. +.TP +\fBtextbox\fR +This is a textbox widget\. The displayed string can be set with \fBstr\fR\. +. +.TP +\fBicon\fR +This is an icon widget\. The displayed icon can be set with \fBfilename\fR and size with \fBsize\fR\. +. +.TP +\fBbutton\fR +This is a textbox widget that can have a \'clickable\' action\. The \fBaction\fR can be set to: \fBok\fR accept entry\. \fBcustom\fR accept custom input\. \fBok|alternate\fR: accept entry and launch alternate action (for run launch in terminal)\. \fBcustom|alternate\fR: accept custom input and launch alternate action\. +. +.P +To specify children, set the \fBchildren\fR property (this always happens on the \fBbox\fR child, see example below): . .IP "" 4 . diff --git a/doc/rofi-theme.5.markdown b/doc/rofi-theme.5.markdown index 41825fb7..1b435fec 100644 --- a/doc/rofi-theme.5.markdown +++ b/doc/rofi-theme.5.markdown @@ -751,6 +751,21 @@ These are used in the default theme as depicted in the figure above. Packs: `prompt,entry,case-indicator` Any widget name starting with `textbox` is a textbox widget, others are box widgets and can pack other widgets. + +There are several special widgets that can be used by prefixing the name of the widget: + +* `textbox`: + This is a textbox widget. The displayed string can be set with `str`. +* `icon`: + This is an icon widget. The displayed icon can be set with `filename` and size with `size`. +* `button`: + This is a textbox widget that can have a 'clickable' action. + The `action` can be set to: + `ok` accept entry. + `custom` accept custom input. + `ok|alternate`: accept entry and launch alternate action (for run launch in terminal). + `custom|alternate`: accept custom input and launch alternate action. + To specify children, set the `children` property (this always happens on the `box` child, see example below): diff --git a/doc/rofi.1 b/doc/rofi.1 index 45d63398..e533830a 100644 --- a/doc/rofi.1 +++ b/doc/rofi.1 @@ -1,1233 +1,1664 @@ -.TH "ROFI" "" "August 2019" "" "" +.\" generated with Ronn/v0.7.3 +.\" http://github.com/rtomayko/ronn/tree/0.7.3 +. +.TH "ROFI" "1" "August 2019" "" "" +. .SH "NAME" -\fBROFI\fR -.SH NAME -.P -\fBrofi\fR \- A window switcher, application launcher, ssh dialog and dmenu replacement -.SH SYNOPSIS -.P +\fBrofi\fR \- A window switcher, application launcher, ssh dialog and dmenu replacement +. +.SH "SYNOPSIS" \fBrofi\fR [ \-show \fImode\fR ]|[ \-dmenu ]|[ \-e \fImsg\fR ] [ CONFIGURATION ] -.SH DESCRIPTION +. +.SH "DESCRIPTION" +\fBrofi\fR 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\. +. +.SH "USAGE" +\fBrofi\fR\'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 \fImodi\fR for different types of actions\. +. .P -\fBrofi\fR 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\. -.SH USAGE -.P -\fBrofi\fR\|'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 \fImodi\fR for different types of -actions\. -.P -\fBrofi\fR can also function as (drop\-in) replacement for \fBdmenu(1)\fR\|\. -.SS Running rofi -.P -To launch \fBrofi\fR directly in a certain mode, specify a mode with \fBrofi \-show \fP\|\. -To show the run dialog: -.P -.RS 2 +\fBrofi\fR can also function as (drop\-in) replacement for \fBdmenu(1)\fR\. +. +.SS "Running rofi" +To launch \fBrofi\fR directly in a certain mode, specify a mode with \fBrofi \-show \fR\. To show the run dialog: +. +.IP "" 4 +. .nf + rofi \-show run +. .fi -.RE -.SS Emulating dmenu +. +.IP "" 0 +. +.SS "Emulating dmenu" +\fBrofi\fR can emulate \fBdmenu(1)\fR (a dynamic menu for X) when launched with the \fB\-dmenu\fR flag\. +. .P -\fBrofi\fR can emulate \fBdmenu(1)\fR (a dynamic menu for X) when launched with the \fB\-dmenu\fP flag\. -.P -The website for \fBdmenu\fP can be found here \fIhttp://tools\.suckless\.org/dmenu/\fR\|\. -.P -\fBrofi\fR does not aim to be 100% compatible with dmenu\. There are simply too many different flavors of dmenu\. -The idea is that the basic usage command\-line flags are obeyed, theme\-related flags are not\. -Besides, \fBrofi\fR offers some extended features (like multi\-select, highlighting, message bar, extra key bindings)\. -.SS Display Error message +The website for \fBdmenu\fR can be found here \fIhttp://tools\.suckless\.org/dmenu/\fR\. +. .P +\fBrofi\fR does not aim to be 100% compatible with dmenu\. There are simply too many different flavors of dmenu\. The idea is that the basic usage command\-line flags are obeyed, theme\-related flags are not\. Besides, \fBrofi\fR offers some extended features (like multi\-select, highlighting, message bar, extra key bindings)\. +. +.SS "Display Error message" \fBrofi\fR error dialog can also be called from the command line\. -.P -.RS 2 +. +.IP "" 4 +. .nf + rofi \-e "my message" +. .fi -.RE +. +.IP "" 0 +. .P Markup support can be enabled, see CONFIGURATION options\. -.SH CONFIGURATION -.P +. +.SH "CONFIGURATION" There are currently three methods of setting configuration options (evaluated in order below): -.RS 0 -.IP \(bu 2 -System configuration file (for example \fB/etc/rofi\.conf\fP)\. -.IP \(bu 2 -Xresources: A method of storing key values in the Xserver\. See -here \fIhttps://en\.wikipedia\.org/wiki/X_resources\fR for more information\. -.IP \(bu 2 +. +.IP "\(bu" 4 +System configuration file (for example \fB/etc/rofi\.conf\fR)\. +. +.IP "\(bu" 4 +Xresources: A method of storing key values in the Xserver\. See here \fIhttps://en\.wikipedia\.org/wiki/X_resources\fR for more information\. +. +.IP "\(bu" 4 Rasi theme file: The new \fItheme\fR format can be used to set configuration values\. -.IP \(bu 2 -Configuration File: This uses the same format as the Xresources file\. -By default it looks in \fBXDG_USER_CONFIG_DIR\fP/rofi/config, but can be overridden on commandline\. -By default XDG_USER_CONFIG_DIR defaults to \fB$HOME/\.config\fP\|\. (See \fBrofi \-h\fP for current location)\. -This is the recommended way of configuring \fBrofi\fR\|\. -.IP \(bu 2 -Command\-line options: Arguments passed to \fBrofi\fR\|\. +. +.IP "\(bu" 4 +Configuration File: This uses the same format as the Xresources file\. By default it looks in \fBXDG_USER_CONFIG_DIR\fR/rofi/config, but can be overridden on commandline\. By default XDG_USER_CONFIG_DIR defaults to \fB$HOME/\.config\fR\. (See \fBrofi \-h\fR for current location)\. This is the recommended way of configuring \fBrofi\fR\. +. +.IP "\(bu" 4 +Command\-line options: Arguments passed to \fBrofi\fR\. +. +.IP "" 0 +. +.P +\fBTIP\fR: To get a template config file run: \fBrofi \-dump\-xresources > rofi\-example\.config\fR\. \fBNOTE\fR: In version 1\.4\.0 we support configuration in a new format, a config for this can be generated by: \fBrofi \-dump\-config > config\.rasi\fR \fBNOTE\fR: If you want to use the new configuration format, the config file should be named \fBconfig\.rasi\fR\. +. +.P +The Xresources file expects options starting with \fBrofi\.\fR followed by its name\. An example to set the number of lines: +. +.IP "" 4 +. +.nf -.RE -.P -\fBTIP\fR: To get a template config file run: \fBrofi \-dump\-xresources > rofi\-example\.config\fP\|\. -\fBNOTE\fR: In version 1\.4\.0 we support configuration in a new format, a config for this can be generated by: \fBrofi -\-dump\-config > config\.rasi\fP -\fBNOTE\fR: If you want to use the new configuration format, the config file should be named \fBconfig\.rasi\fP\|\. -.P -The Xresources file expects options starting with \fBrofi\.\fP followed by its name\. An example to set the number of lines: -.P -.RS 2 -.nf rofi\.lines: 10 +. .fi -.RE +. +.IP "" 0 +. .P -Command line options override settings from Xresources file\. The same option set as argument — prefixed with a '\-': -.P -.RS 2 +Command line options override settings from Xresources file\. The same option set as argument — prefixed with a \'\-\': +. +.IP "" 4 +. .nf + rofi \-lines 10 +. .fi -.RE +. +.IP "" 0 +. .P To get a list of available options formatted as Xresources entries, run: -.P -.RS 2 +. +.IP "" 4 +. .nf + rofi \-dump\-xresources +. .fi -.RE +. +.IP "" 0 +. .P The configuration system supports the following types: -.RS 0 -.IP \(bu 2 +. +.IP "\(bu" 4 string -.IP \(bu 2 +. +.IP "\(bu" 4 integer (signed and unsigned) -.IP \(bu 2 +. +.IP "\(bu" 4 char -.IP \(bu 2 +. +.IP "\(bu" 4 Boolean - -.RE +. +.IP "" 0 +. .P Boolean options have a non\-default command\-line syntax\. Example to enable option X: -.P -.RS 2 +. +.IP "" 4 +. .nf + \-X +. .fi -.RE +. +.IP "" 0 +. .P To disable option X: -.P -.RS 2 +. +.IP "" 4 +. .nf + \-no\-X +. .fi -.RE +. +.IP "" 0 +. .P Below is a list of the most important options: -.SS General +. +.SS "General" +\fB\-help\fR +. .P -\fB\-help\fP +The help option shows the full list of commandline options and the current set value\. These include dynamic (run\-time generated) options\. +. .P -The help option shows the full list of commandline options and the current set value\. -These include dynamic (run\-time generated) options\. +\fB\-dump\-xresources\fR +. .P -\fB\-dump\-xresources\fP +Dump the current active configuration in Xresources format to the command\-line\. This does not validate all passed values (for example, colors)\. +. .P -Dump the current active configuration in Xresources format to the command\-line\. -This does not validate all passed values (for example, colors)\. -.P -\fB\-threads\fP \fInum\fR +\fB\-threads\fR \fInum\fR +. .P Specify the number of threads \fBrofi\fR should use: -.RS 0 -.IP \(bu 2 +. +.IP "\(bu" 4 0: Autodetect the number of supported hardware threads\. -.IP \(bu 2 +. +.IP "\(bu" 4 1: Disable threading -.IP \(bu 2 +. +.IP "\(bu" 4 2\.\.N: Specify the maximum number of threads to use in the thread pool\. - -.RE +. +.IP "" 0 +. .P -\fB\-dmenu\fP +\fB\-dmenu\fR +. .P -Run \fBrofi\fR in dmenu mode\. This allows for interactive scripts\. -In \fBdmenu\fP mode, \fBrofi\fR reads from STDIN, and output to STDOUT\. -A simple example, displaying three pre\-defined options: -.P -.RS 2 +Run \fBrofi\fR in dmenu mode\. This allows for interactive scripts\. In \fBdmenu\fR mode, \fBrofi\fR reads from STDIN, and output to STDOUT\. A simple example, displaying three pre\-defined options: +. +.IP "" 4 +. .nf -echo \-e "Option #1\\nOption #2\\nOption #3" | rofi \-dmenu + +echo \-e "Option #1\enOption #2\enOption #3" | rofi \-dmenu +. .fi -.RE +. +.IP "" 0 +. .P Or get the options from a script: -.P -.RS 2 +. +.IP "" 4 +. .nf + ~/my_script\.sh | rofi \-dmenu +. .fi -.RE +. +.IP "" 0 +. .P -\fB\-show\fP \fImode\fR +\fB\-show\fR \fImode\fR +. .P -Open \fBrofi\fR in a certain mode\. Available modes are \fBwindow\fP, \fBrun\fP, \fBdrun\fP, \fBssh\fP, \fBcombi\fP\|\. -The special argument \fBkeys\fP can be used to open a searchable list of supported key bindings -(see \fIKEY BINDINGS\fR) +Open \fBrofi\fR in a certain mode\. Available modes are \fBwindow\fR, \fBrun\fR, \fBdrun\fR, \fBssh\fR, \fBcombi\fR\. The special argument \fBkeys\fR can be used to open a searchable list of supported key bindings (see \fIKEY BINDINGS\fR) +. .P To show the run\-dialog: -.P -.RS 2 +. +.IP "" 4 +. .nf + rofi \-show run +. .fi -.RE +. +.IP "" 0 +. .P -\fB\-modi\fP \fImode1,mode1\fR +\fB\-modi\fR \fImode1,mode1\fR +. .P -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 modes will be enabled\. -To only show the run and ssh launcher: -.P -.RS 2 +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 modes will be enabled\. To only show the run and ssh launcher: +. +.IP "" 4 +. .nf + rofi \-modi "run,ssh" \-show run +. .fi -.RE +. +.IP "" 0 +. .P -Custom modes can be added using the internal 'script' mode\. Each mode has two parameters: -.P -.RS 2 +Custom modes can be added using the internal \'script\' mode\. Each mode has two parameters: +. +.IP "" 4 +. .nf + :