# 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 +++ 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 = 'Run: ', 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 = "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

### 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 (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**]

  ### See also:

  gears.color | This module simplifies the creation of cairo pattern objects. | module

## Theme variables

🔗 beautiful.prompt_fg_cursor color
  The prompt cursor foreground color.

  ### See also:

  gears.color | This module simplifies the creation of cairo pattern objects. | module

  Click to display more

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

  ### See also:

  gears.color | This module simplifies the creation of cairo pattern objects. | module

  Click to display more

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

  ### See also:

  string |  |

  Click to display more

  ### 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

generated by LDoc 1.5.0