# gui.command_entry

Textadept's Command Entry.

## Modes

The command entry supports multiple [modes][] that have their own sets of key
bindings stored in a separate table in `_G.keys` under a mode prefix key.
Mode names are arbitrary, but cannot conflict with lexer names or key
sequence strings (e.g. `'lua'` or `'send'`) due to the method used for
looking up key bindings. An example mode is "lua_command" mode for executing
Lua commands:

    local gui_ce = gui.command_entry
    keys['ce'] = {gui_ce.enter_mode, 'lua_command'}
    keys.lua_command = {
      ['\t'] = gui_ce.complete_lua,
      ['\n'] = {gui_ce.finish_mode, gui_ce.execute_lua}
    }

In this case, `Ctrl+E` opens the command entry and enters "lua_command" key
mode where the `Tab` and `Enter` keys have special, defined functionality.
(By default, `Esc` is pre-defined to exit any command entry mode.) `Tab`
shows a list of Lua completions for the entry text and `Enter` exits
"lua_command" key mode and executes the entered code. All other keys are
handled normally by the command entry.

It is important to note that while in any command entry key mode, all editor
key bindings are ignored -- even if the editor, not the command entry, has
focus. You must first exit the key mode by pressing `Esc` (or `Enter` in the
case of the above "lua_command" key mode).

[modes]: keys.html#Modes

- - -

## Fields

- - -

<a id="entry_text"></a>
### `entry_text` (string)

The text in the entry.

- - -


## Functions

- - -

<a id="complete_lua"></a>
### `complete_lua`(*code*)

Shows a set of Lua code completions for string *code* or `entry_text`.
Completions are subject to an "abbreviated" environment where the `buffer`,
`view`, and `gui` tables are also considered as globals.

Parameters:

* *`code`*: The Lua code to complete. The default value is the value of
  `entry_text`.

- - -

<a id="enter_mode"></a>
### `enter_mode`(*mode*)

Opens the command entry in key mode *mode*.
Key bindings will be looked up in `keys[mode]` instead of `keys`. The `Esc`
(`⎋` on Mac OSX | `Esc` in curses) key exits the current mode, closes the
command entry, and restores normal key lookup.
This function is useful for binding keys to enter a command entry mode.

Parameters:

* *`mode`*: The key mode to enter into, or `nil` to exit the current mode.

Usage:

* `keys['ce'] = {gui.command_entry.enter_mode, 'command_entry'}`

See also:

* [`keys.MODE`](keys.html#MODE)

- - -

<a id="execute_lua"></a>
### `execute_lua`(*code*)

Executes string *code* as Lua code.
Code is subject to an "abbreviated" environment where the `buffer`, `view`,
and `gui` tables are also considered as globals.
Print the results of '=' expressions like in the Lua prompt.

Parameters:

* *`code`*: The Lua code to execute.

- - -

<a id="finish_mode"></a>
### `finish_mode`(*f*)

Exits the current key mode, closes the command entry, and calls function *f*
(if given) with the command entry text as an argument.
This is useful for binding keys to exit a command entry mode and perform an
action with the entered text.

Parameters:

* *`f`*: Optional function to call. It should accept the command entry text
  as an argument.

Usage:

* `keys['\n'] = {gui.command_entry.finish_mode, gui.print}`

- - -

<a id="focus"></a>
### `focus`()

Focuses the command entry.

- - -

<a id="show_completions"></a>
### `show_completions`(*completions*)

Shows the completion list *completions* for the current word prefix.
Word prefix characters are alphanumerics and underscores. On selection, the
word prefix is replaced with the completion.

Parameters:

* *`completions`*: The table of completions to show. Non-string values are
  ignored.

- - -


