1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
|
# rofi-script(5)
## NAME
**rofi script mode** - Rofi format for scriptable mode.
## 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.
## USAGE
To specify a script mode, set a mode with the following syntax:
"{name}:{executable}"
For example:
```bash
rofi -show fb -modes "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.
A simple script would be:
```bash
#!/usr/bin/env bash
if [ x"$@" = x"quit" ]
then
exit 0
fi
echo "reload"
echo "quit"
```
This shows two entries, reload and quit. When the quit entry is selected, rofi
closes.
## Environment
Rofi sets the following environment variable when executing the script:
### `ROFI_RETV`
An integer number with the current state:
- **0**: Initial call of script.
- **1**: Selected an entry.
- **2**: Selected a custom entry.
- **10-28**: Custom keybinding 1-19 ( need to be explicitly enabled by script ).
### `ROFI_INFO`
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. Extra options
are lines that start with a NULL character (`\0`) followed by a key, separator
(`\x1f`) and value.
For example to set the prompt:
```bash
echo -en "\0prompt\x1fChange prompt\n"
```
The following extra options exists:
- **prompt**: Update the prompt text.
- **message**: Update the message text.
- **markup-rows**: If 'true' renders markup in the row.
- **urgent**: Mark rows as urgent. (for syntax see the urgent option in
dmenu mode)
- **active**: Mark rows as active. (for syntax see the active option in
dmenu mode)
- **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.
The **theme** property cannot change the interface while running, it is only
usable for small changes in, for example background color, of widgets that get
updated during display like the row color of the listview.
## Parsing row options
Extra options for individual rows can be set. The extra option can be specified
following the same syntax as mode option, but following the entry.
For example:
```bash
echo -en "aap\0icon\x1ffolder\n"
```
The following options are supported:
- **icon**: Set the icon for that row.
- **display**: Replace the displayed string. (Original string will still be used for filtering)
- **meta**: Specify invisible search terms used for filtering.
- **nonselectable**: If true the row cannot activated.
- **permanent**: If true the row always shows, independent of filter.
- **info**: Info that, on selection, gets placed in the `ROFI_INFO`
environment variable. This entry does not get searched for filtering.
- **urgent**: Set urgent flag on entry (true/false)
- **active**: Set active flag on entry (true/false)
multiple entries can be passed using the `\x1f` separator.
```bash
echo -en "aap\0icon\x1ffolder\x1finfo\x1ftest\n"
```
## Executing external program
If you want to launch an external program from the script, you need to make
sure it is launched in the background. If not rofi will wait for its output (to
display).
In bash the best way to do this is using `coproc`.
```bash
coproc ( myApp > /dev/null 2>&1 )
```
## DASH shell
If you use the `dash` shell for your script, take special care with how dash
handles escaped values for the separators. See issue #1201 on github.
## Script locations
To specify a script there are the following options:
- Specify an absolute path to the script.
- The script is executable and located in your $PATH
Scripts located in the following location are loaded on startup:
- The script is in `$XDG_CONFIG_PATH/rofi/scripts/`, this is usually
`~/.config/rofi/scripts/`.
## SEE ALSO
rofi(1), rofi-sensible-terminal(1), dmenu(1), rofi-theme(5),
rofi-theme-selector(1)
## AUTHOR
Qball Cow <qball@gmpclient.org>
Rasmus Steinke <rasi@xssn.at>
Morgane Glidic <sardemff7+rofi@sardemff7.net>
Original code based on work by: Sean Pringle <sean.pringle@gmail.com>
For a full list of authors, check the AUTHORS file.
|
