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:

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

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,{
            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        = '<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.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:

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
Author: Julien Danjou <[email protected]>

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

run ([args={}[, textbox[, exe_callback[, completion_callback[, history_path[, history_max[, done_callback[, changed_callback[, keypressed_callback]]]]]]]]])

Run a prompt in a box.

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)

Theme variables

beautiful.prompt_fg_cursor

The prompt cursor foreground color.

Type:

color

Type:

color

Type:

string

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:

before_cursor string
after_cursor string

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

awesome

Contents

Libraries

Sample files

Classes

Documentation

Module `awful.prompt`

Info:

Functions

Theme variables

Callback functions prototype

Functions

See also:

Theme variables

Type:

See also:

Type:

See also:

Type:

See also:

Callback functions prototype

Parameters:

Usage:

Parameters:

Usage:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

awesome

Contents

Libraries

Sample files

Classes

Documentation

Module awful.prompt

Info:

Functions

Theme variables

Callback functions prototype

Functions

See also:

Theme variables

Type:

See also:

Type:

See also:

Type:

See also:

Callback functions prototype

Parameters:

Usage:

Parameters:

Usage:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Module `awful.prompt`