Module: awful.prompt

Prompt module for awful.

Keyboard navigation:

The following readline keyboard shortcuts are implemented as expected:

NameUsage
CTRL+Abeginning-of-line
CTRL+Bbackward-char
CTRL+Ccancel
CTRL+Ddelete-char
CTRL+Eend-of-line
CTRL+Jaccept-line
CTRL+Maccept-line
CTRL+Fmove-cursor-right
CTRL+Hbackward-delete-char
CTRL+Kkill-line
CTRL+Uunix-line-discard
CTRL+Wunix-word-rubout
CTRL+BACKSPACEunix-word-rubout
SHIFT+INSERTpaste
HOMEbeginning-of-line
ENDend-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:

Usage example

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:*

Usage example

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.

Usage example

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

Usage example

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:

Usage example

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 <julien@danjou.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 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.


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:

  • args A table with optional arguments
    • fg_cursor gears.color (optional)
    • bg_cursor gears.color (optional)
    • ul_cursor gears.color (optional)
    • prompt widget (optional)
    • text string (optional)
    • selectall boolean (optional)
    • font string (optional)
    • autoexec boolean (optional)
    • textbox widget The textbox to use for the prompt.
    • highlighter function A function to add syntax highlighting to the command. (optional)
    • 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 string File path where the history should be saved, set nil to disable history (optional)
    • history_max function Set the maximum entries in history file, 50 by default (optional)
    • done_callback function The callback function to always call without arguments, regardless of whether the prompt was cancelled. (optional)
    • changed_callback function The callback function to call with command as argument when a command was changed. (optional)
    • keypressed_callback function The callback function to call with mod table, key and command as arguments when a key was pressed. (optional)
    • keyreleased_callback function The callback function to call with mod table, key and command as arguments when a key was pressed. (optional)
    • hooks 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}
 }
      (optional)
  • textbox The textbox to use for the prompt. [DEPRECATED]
  • exe_callback The callback function to call with command as argument when finished. [DEPRECATED]
  • completion_callback The callback function to call to get completion. [DEPRECATED]
  • history_path File path where the history should be saved, set nil to disable history [DEPRECATED] (optional)
  • history_max Set the maximum entries in history file, 50 by default [DEPRECATED] (optional)
  • done_callback The callback function to always call without arguments, regardless of whether the prompt was cancelled. [DEPRECATED] (optional)
  • changed_callback The callback function to call with command as argument when a command was changed. [DEPRECATED] (optional)
  • keypressed_callback The callback function to call with mod table, key and command as arguments when a key was pressed. [DEPRECATED] (optional)

See also:

Theme variables

beautiful.prompt_fg_cursor color
The prompt cursor foreground color.

See also:

beautiful.prompt_bg_cursor color
The prompt cursor background color.

See also:

beautiful.prompt_font string
The prompt text font.

See also:

Callback functions prototype

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

Parameters:

  • command string The command (as entered).

Usage:

    local function my_exe_cb(command)
   -- do something
end
completion_callback
The callback function to get completions.

Parameters:

  • 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
The callback function to call with command as argument when a command was changed.

Parameters:

  • command string The current command.

Usage:

    local function my_changed_cb(command)
   -- do something
end
keypressed_callback
The callback function to call with mod table, key and command as arguments when a key was pressed.

Parameters:

  • 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
The callback function to call with mod table, key and command as arguments when a key was released.

Parameters:

  • 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
A function to add syntax highlighting to the command.

Parameters:

Usage:

    local function my_highlighter(before_cursor, after_cursor)
   -- do something
   return before_cursor, after_cursor
end
hook
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:

  • command string The current command.

Usage:

    local function my_hook(command)
   return command.."foo", false
end
generated by LDoc 1.4.6 Last updated 2021-11-13 00:35:50