# Module `awful.prompt`

Prompt module for awful.

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:

    -- Create a shortcut function
    local function echo_test()
        awful.prompt.run {
            prompt       = "Echo: ",
            textbox      = mouse.screen.mypromptbox.widget,
            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.

### Info:

- Copyright: 2008 Julien Danjou
- Author: Julien Danjou <julien@danjou.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.

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

  The following readline keyboard shortcuts are implemented as expected: `CTRL+A`, `CTRL+B`, `CTRL+C`, `CTRL+D`, `CTRL+E`, `CTRL+J`, `CTRL+M`, `CTRL+F`, `CTRL+H`, `CTRL+K`, `CTRL+U`, `CTRL+W`, `CTRL+BACKSPACE`, `SHIFT+INSERT`, `HOME`, `END` and arrow keys.

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

  gears.color

generated by LDoc 1.4.6 Last updated 2017-01-20 01:17:18