Module awful.prompt
Prompt module for awful.
**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.notify{ text = '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. Therefor, 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,{
intrusive = true,
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.notify { text = '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:
Functions
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
The prompt cursor foreground color.
beautiful.prompt_bg_cursor
The prompt cursor background color.
beautiful.prompt_font
The prompt text font.
Callback functions prototype
exe_callback
The callback function to call with command as argument when finished.
completion_callback
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
The callback function to call with command as argument when a command was
changed.
keypressed_callback
The callback function to call with mod table, key and command as arguments
when a key was pressed.
keyreleased_callback
The callback function to call with mod table, key and command as arguments
when a key was released.
highlighter
A function to add syntax highlighting to the command.
hook
A callback when a key combination is triggered.
Functions
Methods
See also:
Theme variables
Type:
See also:
Type:
See also:
Type:
See also:
Callback functions prototype
Parameters:
Usage:
local function my_exe_cb(command)
-- do something
end
Parameters:
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:
Usage:
local function my_changed_cb(command)
-- do something
end
Parameters:
Usage:
local function my_keypressed_cb(mod, key, command)
-- do something
end
Parameters:
Usage:
local function my_keyreleased_cb(mod, key, command)
-- do something
end
Parameters:
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:
Usage:
local function my_hook(command)
return command.."foo", false
end