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       = "<b>Echo: </b>",
        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        = "<b>Run: </b>",
    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 <num>+<adj>+<num>+<verb>
    for char in action:gmatch('(.)') do
        if     tonumber(char)  then table.insert(req.count, char)
        elseif verbs[char]     then req.verb = char
        else   table.insert(ret.adjectives, char) end
        if req.verb then
            req.count = tonumber(table.concat(req.count)) or 1
            ret = ret or verbs[req.verb](req.adjectives, req.count, command)
            req = {count={}, adjectives={}}
        end
    end
    return ret
end
awful.prompt.run {
    prompt       = '<b>Run: </b>',
    hooks        = {
        {{},'Return', function(cmd)
            if (not cmd) or cmd:sub(1,1) ~= ':' then return cmd end
            local act, cmd2 = cmd:gmatch(':([a-zA-Z1-9]+)[ ]+(.*)')()
            if not act then return cmd end
            return vi_parse(act, cmd2)
        end},
    },
    textbox      = atextbox,
    history_path = gfs.get_cache_dir() .. '/history',
    exe_callback = function(cmd) awful.spawn(cmd) end
}

[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               = "<b>Run: </b>",
    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 = "&amp"..string.char(0x3B)
local quot = "&quot"..string.char(0x3B)
local atextbox = wibox.widget.textbox()
-- Create a shortcut function
local function echo_test()
    awful.prompt.run {
        prompt       = "<b>Echo: </b>",
        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 = "<span foreground='#CFBA5D'>%1</span>"
            cmd = cmd:gsub("($[A-Za-z][a-zA-Z0-9]*)", sub)
            -- Highlight " && "
            sub = "<span foreground='#159040'>%1</span>"
            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),
                            "<span foreground='#2977CF'>",
                            content,
                            "</span>",
                            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

Info:

Copyright: 2008 Julien Danjou
Originally authored by: Julien Danjou <[email protected]>
(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

🔗 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.

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]

Theme variables

🔗 beautiful.prompt_fg_cursor color

The prompt cursor foreground color.

Used by:

awful.widget.prompt Create a prompt widget which will launch a command.
awful.widget.prompt Create a prompt widget which will launch a command.

🔗 beautiful.prompt_bg_cursor color

The prompt cursor background color.

Used by:

awful.widget.prompt Create a prompt widget which will launch a command.
awful.widget.prompt Create a prompt widget which will launch a command.

🔗 beautiful.prompt_font string

The prompt text font.

Used by:

awful.widget.prompt Create a prompt widget which will launch a command.
awful.widget.prompt Create a prompt widget which will launch a command.

Callback functions prototype

🔗 exe_callback (command)

The callback function to call with command as argument when finished.

Parameters:

Name		Type(s)	Description
command		string	The command (as entered).

Usage:

local function my_exe_cb(command)
   -- do something
end

🔗 completion_callback (command_before_comp, cur_pos_before_comp, ncomp)

The callback function to get completions.

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

🔗 done_callback ()

The callback function to always call without arguments, regardless of whether the prompt was cancelled.

Usage:

local function my_done_cb()
   -- do something
end

🔗 changed_callback (command)

The callback function to call with command as argument when a command was changed.

Parameters:

Name		Type(s)	Description
command		string	The current command.

Usage:

local function my_changed_cb(command)
   -- do something
end

🔗 keypressed_callback (mod, key, command)

The callback function to call with mod table, key and command as arguments when a key was pressed.

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

🔗 keyreleased_callback (mod, key, command)

The callback function to call with mod table, key and command as arguments when a key was released.

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

🔗 highlighter (before_cursor, after_cursor)

A function to add syntax highlighting to the command.

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

🔗 hook (command)

A callback when a key combination is triggered. This callback can return many things:

a modified command
true If the command is successful (then it won't exit)
nothing or nil to execute the exe_callback and done_callback and exit

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.

Parameters:

Name		Type(s)	Description
command		string	The current command.

Usage:

local function my_hook(command)
   return command.."foo", false
end

awesome

Contents

Libraries

Core components

Input handling

Declarative rules

Widgets

Widget containers

Widget layouts

Popups and bars

Utility libraries

Theme related libraries

Sample files

Classes

Documentation

Module: awful.prompt

Info:

Static module functions

Theme variables

Callback functions prototype

Static module functions

Parameters:

See also:

Theme variables

See also:

Used by:

See also:

Used by:

See also:

Used by:

Callback functions prototype

Parameters:

Usage:

Parameters:

Usage:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Module: `awful.prompt`