# gui.find

Textadept's Find & Replace pane.

- - -

## Fields

- - -

<a id="_G.events.FIND_WRAPPED"></a>
### `_G.events.FIND_WRAPPED` (string)

Emitted when a search for text wraps, either from bottom to top when
  searching for a next occurrence, or from top to bottom when searching for a
  previous occurrence.
  This is useful for implementing a more visual or audible notice when a
  search wraps in addition to the statusbar message.

- - -

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

The text in the find entry.

- - -

<a id="find_label_text"></a>
### `find_label_text` (string, Write-only)

The text of the "Find" label.
  This is primarily used for localization.

- - -

<a id="find_next_button_text"></a>
### `find_next_button_text` (string, Write-only)

The text of the "Find Next" button.
  This is primarily used for localization.

- - -

<a id="find_prev_button_text"></a>
### `find_prev_button_text` (string, Write-only)

The text of the "Find Prev" button.
  This is primarily used for localization.

- - -

<a id="in_files"></a>
### `in_files` (bool)

Search for the text in a list of files.
  The default value is `false`.

- - -

<a id="in_files_label_text"></a>
### `in_files_label_text` (string, Write-only)

The text of the "In files" label.
  This is primarily used for localization.

- - -

<a id="lua"></a>
### `lua` (bool)

Interpret search text as a Lua pattern.
  The default value is `false`.

- - -

<a id="lua_pattern_label_text"></a>
### `lua_pattern_label_text` (string, Write-only)

The text of the "Lua pattern" label.
  This is primarily used for localization.

- - -

<a id="match_case"></a>
### `match_case` (bool)

Searches are case-sensitive.
  The default value is `false`.

- - -

<a id="match_case_label_text"></a>
### `match_case_label_text` (string, Write-only)

The text of the "Match case" label.
  This is primarily used for localization.

- - -

<a id="replace_all_button_text"></a>
### `replace_all_button_text` (string, Write-only)

The text of the "Replace All" button.
  This is primarily used for localization.

- - -

<a id="replace_button_text"></a>
### `replace_button_text` (string, Write-only)

The text of the "Replace" button.
  This is primarily used for localization.

- - -

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

The text in the replace entry.

- - -

<a id="replace_label_text"></a>
### `replace_label_text` (string, Write-only)

The text of the "Replace" label.
  This is primarily used for localization.

- - -

<a id="whole_word"></a>
### `whole_word` (bool)

Match only whole-words in searches.
  The default value is `false`.

- - -

<a id="whole_word_label_text"></a>
### `whole_word_label_text` (string, Write-only)

The text of the "Whole word" label.
  This is primarily used for localization.

- - -


## Functions

- - -

<a id="find_in_files"></a>
### `find_in_files`(*utf8\_dir*)

Searches the *utf8_dir* or user-specified directory for files that match
search text and options and prints the results to a buffer.
Use the `find_text`, `match_case`, `whole_word`, and `lua` fields to set the
search text and option flags, respectively. Use `FILTER` to set the search
filter.

Parameters:

* *`utf8_dir`*: Optional UTF-8-encoded directory path to search. If `nil`,
  the user is prompted for one.

See also:

* [`FILTER`](#FILTER)

- - -

<a id="find_incremental"></a>
### `find_incremental`(*text, next, anchor*)

Begins an incremental search using the command entry if *text* is `nil`;
otherwise continues an incremental search by searching for the next or
previous instance of string *text* depending on boolean *next*.
If *anchor* is `true`, searches for *text* starting from the current position
instead of the position where incremental search began at.
Only the `match_case` find option is recognized. Normal command entry
functionality is unavailable until the search is finished by pressing `Esc`
(`⎋` on Mac OSX | `Esc` in curses).

Parameters:

* *`text`*: The text to incrementally search for, or `nil` to begin an
  incremental search.
* *`next`*: Flag indicating whether or not the search direction is forward.
* *`anchor`*: Optional flag indicating whether or not to start searching from
  the current position. The default value is `false`.

- - -

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

Mimics pressing the "Find Next" button.

- - -

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

Mimics pressing the "Find Prev" button.

- - -

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

Displays and focuses the Find & Replace pane.

- - -

<a id="goto_file_found"></a>
### `goto_file_found`(*line, next*)

Goes to the source of the find in files search result on line number *line*
in the files found buffer, or if `nil`, the next or previous search result
depending on boolean *next*.

Parameters:

* *`line`*: The line number in the files found buffer that contains the
  search result to go to.
* *`next`*: Optional flag indicating whether to go to the next search result
  or the previous one. Only applicable when *line* is `nil` or `false`.

- - -

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

Mimics pressing the "Replace" button.

- - -

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

Mimics pressing the "Replace All" button.

- - -


## Tables

- - -

<a id="FILTER"></a>
### `FILTER`

Table of Lua patterns matching files and folders to exclude when finding in
files.
Each filter string is a pattern that matches filenames to exclude, with
patterns matching folders to exclude listed in a `folders` sub-table.
Patterns starting with '!' exclude files and folders that do not match the
pattern that follows. Use a table of raw file extensions assigned to an
`extensions` key for fast filtering by extension. All strings must be encoded
in `_G._CHARSET`, not UTF-8.
The default value is `lfs.FILTER`, a filter for common binary file extensions
and version control folders.

See also:

* [`find_in_files`](#find_in_files)

- - -

