Module: awful.prompt
Convert a wibox.widget.textbox into an input prompt.
**Keyboard navigation**:
The following readline keyboard shortcuts are implemented as expected:
| Name | Usage |
|---|---|
| CTRL+A | beginning-of-line |
| CTRL+B | backward-char |
| CTRL+C | cancel |
| CTRL+D | delete-char |
| CTRL+E | end-of-line |
| CTRL+J | accept-line |
| CTRL+M | accept-line |
| CTRL+F | move-cursor-right |
| CTRL+H | backward-delete-char |
| CTRL+K | kill-line |
| CTRL+U | unix-line-discard |
| CTRL+W | unix-word-rubout |
| CTRL+BACKSPACE | unix-word-rubout |
| SHIFT+INSERT | paste |
| HOME | beginning-of-line |
| END | end-of-line |
The following shortcuts implement additional history manipulation commands where the search term is defined as the substring of the command from first character to cursor position.
* CTRL+R: reverse history search, matches any history entry containing search term. * CTRL+S: forward history search, matches any history entry containing search term. * CTRL+UP: ZSH up line or search, matches any history entry starting with search term. * CTRL+DOWN: ZSH down line or search, matches any history entry starting with search term. * CTRL+DELETE: delete the currently visible history entry from history file. This does not delete new commands or history entries under user editing.
**Basic usage**:
By default, rc.lua will create one awful.widget.prompt per screen called
mypromptbox. It is used for both the command execution (mod4+r) and
Lua prompt (mod4+x). It can be re-used for random inputs using:
local atextbox = wibox.widget.textbox() -- Create a shortcut function local function echo_test() awful.prompt.run { prompt = "Echo: ", text = "default command", bg_cursor = "#ff0000", -- To use the default rc.lua prompt: --textbox = mouse.screen.mypromptbox.widget, textbox = atextbox, exe_callback = function(input) if not input or #input == 0 then return end naughty.notification { message = "The input was: "..input } end } end
-- Then **IN THE globalkeys TABLE** add a new shortcut awful.key({ modkey }, "e", echo_test, {description = "Echo a string", group = "custom"}),
Note that this assumes an rc.lua file based on the default one. The way to access the screen prompt may vary.
**Extra key hooks**:
The Awesome prompt also supports adding custom extensions to specific keyboard keybindings. Those keybindings have precedence over the built-in ones. Therefore, they can be used to override the default ones.
*[Example one] Adding pre-configured awful.spawn commands:*
local atextbox = wibox.widget.textbox()
-- Custom handler for the return value. This implementation does nothing,
-- but you might want be notified of the failure, so it is part of this
-- example.
local function clear(result)
atextbox.widget.text =
type(result) == "string" and result or ""
end
local hooks = {
-- Replace the "normal" Return with a custom one
{{ }, "Return", awful.spawn},
-- Spawn method to spawn in the current tag
{{"Mod1" }, "Return", function(command)
clear(awful.spawn(command,{
tag = mouse.screen.selected_tag
}))
end},
-- Spawn in the current tag as floating and on top
{{"Shift" }, "Return", function(command)
clear(awful.spawn(command,{
ontop = true,
floating = true,
tag = mouse.screen.selected_tag
}))
end},
-- Spawn in a new tag
{{"Control"}, "Return", function(command)
clear(awful.spawn(command,{
new_tag = true
}))
end},
-- Cancel
{{ }, "Escape", function(_)
clear()
end},
}
awful.prompt.run {
prompt = "Run: ",
hooks = hooks,
textbox = atextbox,
history_path = gfs.get_cache_dir() .. "/history",
done_callback = clear,
}
*[Example two] Modifying the command (+ vi like input)*:
The hook system also allows to modify the command before interpreting it in the exe_callback.
local atextbox = wibox.widget.textbox()
-- Store a list of verbs characters in a hash
local verbs = {
-- Spawn in a terminal
t = function(adjs, count, cmd) return {terminal, "-e", cmd} end, --luacheck: no unused args
-- Spawn with a shell
s = function(adjs, count, cmd) return {awful.util.shell, '-c', cmd} end, --luacheck: no unused args
}
local function vi_parse(action, command)
local req, ret = {count={}, adjectives={}}
-- Quite dumb, don't do something like *[Example three] Key listener*:
The 2 previous examples were focused on changing the prompt behavior. This
one explains how to "spy" on the prompt events. This can be used for
* Implementing more complex mutator
* Synchronising other widgets
* Showing extra tips to the user
local atextbox = wibox.widget.textbox()
local notif = nil
awful.prompt.run {
prompt = "Run: ",
keypressed_callback = function(mod, key, cmd) --luacheck: no unused args
if key == "Shift_L" then
notif = naughty.notification { message = "Shift pressed" }
end
end,
keyreleased_callback = function(mod, key, cmd) --luacheck: no unused args
if notif then
naughty.destroy(notif)
notif = nil
end
end,
textbox = atextbox,
history_path = gfs.get_cache_dir() .. "/history",
}
**highlighting**:
The prompt also support custom highlighters:
local amp = "&"..string.char(0x3B)
local quot = """..string.char(0x3B)
local atextbox = wibox.widget.textbox()
-- Create a shortcut function
local function echo_test()
awful.prompt.run {
prompt = "Echo: ",
bg_cursor = "#ff0000",
-- To use the default rc.lua prompt:
--textbox = mouse.screen.mypromptbox.widget,
textbox = atextbox,
highlighter = function(b, a)
-- Add a random marker to delimitate the cursor
local cmd = b.."ZZZCURSORZZZ"..a
-- Find shell variables
local sub = "%1"
cmd = cmd:gsub("($[A-Za-z][a-zA-Z0-9]*)", sub)
-- Highlight " && "
sub = "%1"
cmd = cmd:gsub("( "..amp..amp..")", sub)
-- Highlight double quotes
local quote_pos = cmd:find("[^\\]"..quot)
while quote_pos do
local old_pos = quote_pos
quote_pos = cmd:find("[^\\]"..quot, old_pos+2)
if quote_pos then
local content = cmd:sub(old_pos+1, quote_pos+6)
cmd = table.concat({
cmd:sub(1, old_pos),
"",
content,
"",
cmd:sub(quote_pos+7, #cmd)
}, "")
quote_pos = cmd:find("[^\\]"..quot, old_pos+38)
end
end
-- Split the string back to the original content
-- (ignore the recursive and escaped ones)
local pos = cmd:find("ZZZCURSORZZZ")
b,a = cmd:sub(1, pos-1), cmd:sub(pos+12, #cmd)
return b,a
end,
}
end
* a modified command
* An optional second return value controls if the prompt should exit or simply
update the command (from the first return value) and keep going. The default
is to execute the exe_callback and done_callback before exiting.
Info:
(Full contributors list available on
our github project)
Static module functions
awful.prompt.run (args, textbox, exe_callback, completion_callback, history_path, history_max, done_callback, changed_callback, keypressed_callback)
Run a prompt in a box.
Theme variables
beautiful.prompt_fg_cursor
color
The prompt cursor foreground color.
beautiful.prompt_bg_cursor
color
The prompt cursor background color.
beautiful.prompt_font
string
The prompt text font.
Callback functions prototype
exe_callback (command)
The callback function to call with command as argument when finished.
completion_callback (command_before_comp, cur_pos_before_comp, ncomp)
The callback function to get completions.
done_callback ()
The callback function to always call without arguments, regardless of
whether the prompt was cancelled.
changed_callback (command)
The callback function to call with command as argument when a command was
changed.
keypressed_callback (mod, key, command)
The callback function to call with mod table, key and command as arguments
when a key was pressed.
keyreleased_callback (mod, key, command)
The callback function to call with mod table, key and command as arguments
when a key was released.
highlighter (before_cursor, after_cursor)
A function to add syntax highlighting to the command.
hook (command)
A callback when a key combination is triggered.
Static module functions
Parameters:
Name
Type(s)
Description
args
Optional
table
A table with optional arguments
fg_cursor
Optional
gears.color
bg_cursor
Optional
gears.color
ul_cursor
Optional
gears.color
prompt
Optional
widget
text
Optional
string
selectall
Optional
boolean
font
Optional
string
autoexec
Optional
boolean
textbox
widget
The textbox to use for the prompt.
highlighter
Optional
function
A function to add syntax highlighting to
the command.
exe_callback
function
The callback function to call with command as argument
when finished.
completion_callback
function
The callback function to call to get completion.
history_path
Optional
string
File path where the history should be
saved, set nil to disable history
history_max
Optional
function
Set the maximum entries in history
file, 50 by default
done_callback
Optional
function
The callback function to always call
without arguments, regardless of whether the prompt was cancelled.
changed_callback
Optional
function
The callback function to call
with command as argument when a command was changed.
keypressed_callback
Optional
function
The callback function to call
with mod table, key and command as arguments when a key was pressed.
keyreleased_callback
Optional
function
The callback function to call
with mod table, key and command as arguments when a key was pressed.
hooks
Optional
table
The "hooks" argument uses a syntax similar to
awful.key. It will call a function for the matching modifiers + key.
It receives the command (widget text/input) as an argument.
If the callback returns a command, this will be passed to the
exe_callback, otherwise nothing gets executed by default, and the hook
needs to handle it.
hooks = {
-- Apply startup notification properties with Shift-Return.
{{"Shift" }, "Return", function(command)
awful.screen.focused().mypromptbox:spawn_and_handle_error(
command, {floating=true})
end},
-- Override default behavior of "Return": launch commands prefixed
-- with ":" in a terminal.
{{}, "Return", function(command)
if command:sub(1,1) == ":" then
return terminal .. ' -e ' .. command:sub(2)
end
return command
end}
}
textbox
wibox.widget.textbox
The textbox to use for the prompt. [**DEPRECATED**]
exe_callback
Optional
function or nil
The callback function to call with command as argument
when finished. [**DEPRECATED**]
completion_callback
Optional
function
The callback function to call to get completion.
[**DEPRECATED**]
history_path
Optional
string
File path where the history should be
saved, set nil to disable history [**DEPRECATED**]
history_max
Optional
number
Set the maximum entries in history
file, 50 by default [**DEPRECATED**]
done_callback
Optional
function
The callback function to always call
without arguments, regardless of whether the prompt was cancelled.
[**DEPRECATED**]
changed_callback
Optional
function
The callback function to call
with command as argument when a command was changed. [**DEPRECATED**]
keypressed_callback
Optional
function
The callback function to call
with mod table, key and command as arguments when a key was pressed.
[**DEPRECATED**]
See also:
gears.color
This module simplifies the creation of cairo pattern objects.
module
Theme variables
See also:
gears.color
This module simplifies the creation of cairo pattern objects.
module
Used by:
See also:
gears.color
This module simplifies the creation of cairo pattern objects.
module
Used by:
See also:
string
Used by:
Callback functions prototype
Parameters:
Name
Type(s)
Description
command
string
The command (as entered).
Usage:
local function my_exe_cb(command)
-- do something
end
Parameters:
Name
Type(s)
Description
command_before_comp
string
The current command.
cur_pos_before_comp
number
The current cursor position.
ncomp
number
The number of the currently completed element.
Usage:
local function my_completion_cb(command_before_comp, cur_pos_before_comp, ncomp)
return command_before_comp.."foo", cur_pos_before_comp+3, 1
end
Usage:
local function my_done_cb()
-- do something
end
Parameters:
Name
Type(s)
Description
command
string
The current command.
Usage:
local function my_changed_cb(command)
-- do something
end
Parameters:
Name
Type(s)
Description
mod
table
The current modifiers (like "Control" or "Shift").
key
string
The key name.
command
string
The current command.
Usage:
local function my_keypressed_cb(mod, key, command)
-- do something
end
Parameters:
Name
Type(s)
Description
mod
table
The current modifiers (like "Control" or "Shift").
key
string
The key name.
command
string
The current command.
Usage:
local function my_keyreleased_cb(mod, key, command)
-- do something
end
Parameters:
Name
Type(s)
Description
before_cursor
string
after_cursor
string
Usage:
local function my_highlighter(before_cursor, after_cursor)
-- do something
return before_cursor, after_cursor
end
true If the command is successful (then it won't exit)
* nothing or nil to execute the exe_callback and done_callback and exit
Parameters:
Name
Type(s)
Description
command
string
The current command.
Usage:
local function my_hook(command)
return command.."foo", false
end