will not style correctly.
#### Troubleshooting
Errors in lexers can be tricky to debug. Lexers print Lua errors to
`io.stderr` and `_G.print()` statements to `io.stdout`. Running your editor
from a terminal is the easiest way to see errors as they occur.
#### Risks
Poorly written lexers have the ability to crash Scintilla (and thus its
containing application), so unsaved data might be lost. However, I have only
observed these crashes in early lexer development, when syntax errors or
pattern errors are present. Once the lexer actually starts styling text
(either correctly or incorrectly, it does not matter), I have not observed
any crashes.
#### Acknowledgements
Thanks to Peter Odding for his [lexer post][] on the Lua mailing list
that provided inspiration, and thanks to Roberto Ierusalimschy for LPeg.
[lexer post]: http://lua-users.org/lists/lua-l/2007-04/msg00116.html
### Fields defined by `lexer`
#### `lexer.CLASS` (string)
The token name for class tokens.
#### `lexer.COMMENT` (string)
The token name for comment tokens.
#### `lexer.CONSTANT` (string)
The token name for constant tokens.
#### `lexer.DEFAULT` (string)
The token name for default tokens.
#### `lexer.ERROR` (string)
The token name for error tokens.
#### `lexer.FOLD_BASE` (number)
The initial (root) fold level.
#### `lexer.FOLD_BLANK` (number)
Flag indicating that the line is blank.
#### `lexer.FOLD_HEADER` (number)
Flag indicating the line is fold point.
#### `lexer.FUNCTION` (string)
The token name for function tokens.
#### `lexer.IDENTIFIER` (string)
The token name for identifier tokens.
#### `lexer.KEYWORD` (string)
The token name for keyword tokens.
#### `lexer.LABEL` (string)
The token name for label tokens.
#### `lexer.NUMBER` (string)
The token name for number tokens.
#### `lexer.OPERATOR` (string)
The token name for operator tokens.
#### `lexer.PREPROCESSOR` (string)
The token name for preprocessor tokens.
#### `lexer.REGEX` (string)
The token name for regex tokens.
#### `lexer.STRING` (string)
The token name for string tokens.
#### `lexer.TYPE` (string)
The token name for type tokens.
#### `lexer.VARIABLE` (string)
The token name for variable tokens.
#### `lexer.WHITESPACE` (string)
The token name for whitespace tokens.
#### `lexer.alnum` (pattern)
A pattern that matches any alphanumeric character ('A'-'Z', 'a'-'z',
'0'-'9').
#### `lexer.alpha` (pattern)
A pattern that matches any alphabetic character ('A'-'Z', 'a'-'z').
#### `lexer.any` (pattern)
A pattern that matches any single character.
#### `lexer.ascii` (pattern)
A pattern that matches any ASCII character (codes 0 to 127).
#### `lexer.cntrl` (pattern)
A pattern that matches any control character (ASCII codes 0 to 31).
#### `lexer.dec_num` (pattern)
A pattern that matches a decimal number.
#### `lexer.digit` (pattern)
A pattern that matches any digit ('0'-'9').
#### `lexer.extend` (pattern)
A pattern that matches any ASCII extended character (codes 0 to 255).
#### `lexer.float` (pattern)
A pattern that matches a floating point number.
#### `lexer.fold_by_indentation` (boolean)
Whether or not to fold based on indentation level if a lexer does not have
a folder.
Some lexers automatically enable this option. It is disabled by default.
This is an alias for `lexer.property['fold.by.indentation'] = '1|0'`.
#### `lexer.fold_compact` (boolean)
Whether or not blank lines after an ending fold point are included in that
fold.
This option is disabled by default.
This is an alias for `lexer.property['fold.compact'] = '1|0'`.
#### `lexer.fold_level` (table, Read-only)
Table of fold level bit-masks for line numbers starting from 1.
Fold level masks are composed of an integer level combined with any of the
following bits:
* `lexer.FOLD_BASE`
The initial fold level.
* `lexer.FOLD_BLANK`
The line is blank.
* `lexer.FOLD_HEADER`
The line is a header, or fold point.
#### `lexer.fold_line_groups` (boolean)
Whether or not to fold multiple, consecutive line groups (such as line
comments and import statements) and only show the top line.
This option is disabled by default.
This is an alias for `lexer.property['fold.line.groups'] = '1|0'`.
#### `lexer.fold_on_zero_sum_lines` (boolean)
Whether or not to mark as a fold point lines that contain both an ending
and starting fold point. For example, `} else {` would be marked as a fold
point.
This option is disabled by default.
This is an alias for `lexer.property['fold.on.zero.sum.lines'] = '1|0'`.
#### `lexer.folding` (boolean)
Whether or not folding is enabled for the lexers that support it.
This option is disabled by default.
This is an alias for `lexer.property['fold'] = '1|0'`.
#### `lexer.graph` (pattern)
A pattern that matches any graphical character ('!' to '~').
#### `lexer.hex_num` (pattern)
A pattern that matches a hexadecimal number.
#### `lexer.indent_amount` (table, Read-only)
Table of indentation amounts in character columns, for line numbers
starting from 1.
#### `lexer.integer` (pattern)
A pattern that matches either a decimal, hexadecimal, or octal number.
#### `lexer.line_state` (table)
Table of integer line states for line numbers starting from 1.
Line states can be used by lexers for keeping track of persistent states.
#### `lexer.lower` (pattern)
A pattern that matches any lower case character ('a'-'z').
#### `lexer.newline` (pattern)
A pattern that matches a sequence of end of line characters.
#### `lexer.nonnewline` (pattern)
A pattern that matches any single, non-newline character.
#### `lexer.number` (pattern)
A pattern that matches a typical number, either a floating point, decimal,
hexadecimal, or octal number.
#### `lexer.oct_num` (pattern)
A pattern that matches an octal number.
#### `lexer.print` (pattern)
A pattern that matches any printable character (' ' to '~').
#### `lexer.property` (table)
Map of key-value string pairs.
#### `lexer.property_expanded` (table, Read-only)
Map of key-value string pairs with `$()` and `%()` variable replacement
performed in values.
#### `lexer.property_int` (table, Read-only)
Map of key-value pairs with values interpreted as numbers, or `0` if not
found.
#### `lexer.punct` (pattern)
A pattern that matches any punctuation character ('!' to '/', ':' to '@',
'[' to ''', '{' to '~').
#### `lexer.space` (pattern)
A pattern that matches any whitespace character ('\t', '\v', '\f', '\n',
'\r', space).
#### `lexer.style_at` (table, Read-only)
Table of style names at positions in the buffer starting from 1.
#### `lexer.upper` (pattern)
A pattern that matches any upper case character ('A'-'Z').
#### `lexer.word` (pattern)
A pattern that matches a typical word. Words begin with a letter or
underscore and consist of alphanumeric and underscore characters.
#### `lexer.xdigit` (pattern)
A pattern that matches any hexadecimal digit ('0'-'9', 'A'-'F', 'a'-'f').
### Functions defined by `lexer`
#### `lexer.add_fold_point`(*lexer, token\_name, start\_symbol, end\_symbol*)
Adds to lexer *lexer* a fold point whose beginning and end tokens are string
*token_name* tokens with string content *start_symbol* and *end_symbol*,
respectively.
In the event that *start_symbol* may or may not be a fold point depending on
context, and that additional processing is required, *end_symbol* may be a
function that ultimately returns `1` (indicating a beginning fold point),
`-1` (indicating an ending fold point), or `0` (indicating no fold point).
That function is passed the following arguments:
* `text`: The text being processed for fold points.
* `pos`: The position in *text* of the beginning of the line currently
being processed.
* `line`: The text of the line currently being processed.
* `s`: The position of *start_symbol* in *line*.
* `symbol`: *start_symbol* itself.
Parameters:
* *`lexer`*: The lexer to add a fold point to.
* *`token_name`*: The token name of text that indicates a fold point.
* *`start_symbol`*: The text that indicates the beginning of a fold point.
* *`end_symbol`*: Either the text that indicates the end of a fold point, or
a function that returns whether or not *start_symbol* is a beginning fold
point (1), an ending fold point (-1), or not a fold point at all (0).
Usage:
* `lex:add_fold_point(lexer.OPERATOR, '{', '}')`
* `lex:add_fold_point(lexer.KEYWORD, 'if', 'end')`
* `lex:add_fold_point(lexer.COMMENT, lexer.fold_consecutive_lines('#'))`
* `lex:add_fold_point('custom', function(text, pos, line, s, symbol)
... end)`
#### `lexer.add_rule`(*lexer, id, rule*)
Adds pattern *rule* identified by string *id* to the ordered list of rules
for lexer *lexer*.
Parameters:
* *`lexer`*: The lexer to add the given rule to.
* *`id`*: The id associated with this rule. It does not have to be the same
as the name passed to `token()`.
* *`rule`*: The LPeg pattern of the rule.
See also:
* [`lexer.modify_rule`](#lexer.modify_rule)
#### `lexer.add_style`(*lexer, token\_name, style*)
Associates string *token_name* in lexer *lexer* with style table *style*.
*style* may have the following fields:
* `font`: String font name.
* `size`: Integer font size.
* `bold`: Whether or not the font face is bold. The default value is `false`.
* `weight`: Integer weight or boldness of a font, between 1 and 999.
* `italics`: Whether or not the font face is italic. The default value is
`false`.
* `underlined`: Whether or not the font face is underlined. The default value
is `false`.
* `fore`: Font face foreground color in `0xBBGGRR` or `"#RRGGBB"` format.
* `back`: Font face background color in `0xBBGGRR` or `"#RRGGBB"` format.
* `eolfilled`: Whether or not the background color extends to the end of the
line. The default value is `false`.
* `case`: Font case, `'u'` for upper, `'l'` for lower, and `'m'` for normal,
mixed case. The default value is `'m'`.
* `visible`: Whether or not the text is visible. The default value is `true`.
* `changeable`: Whether the text is changeable instead of read-only. The
default value is `true`.
Field values may also contain "$(property.name)" expansions for properties
defined in Scintilla, theme files, etc.
Parameters:
* *`lexer`*: The lexer to add a style to.
* *`token_name`*: The name of the token to associated with the style.
* *`style`*: A style string for Scintilla.
Usage:
* `lex:add_style('longstring', lexer.styles.string)`
* `lex:add_style('deprecated_func', lexer.styles['function'] ..
{italics = true}`
* `lex:add_style('visible_ws', lexer.styles.whitespace ..
{back = lexer.colors.grey}`
#### `lexer.embed`(*lexer, child, start\_rule, end\_rule*)
Embeds child lexer *child* in parent lexer *lexer* using patterns
*start_rule* and *end_rule*, which signal the beginning and end of the
embedded lexer, respectively.
Parameters:
* *`lexer`*: The parent lexer.
* *`child`*: The child lexer.
* *`start_rule`*: The pattern that signals the beginning of the embedded
lexer.
* *`end_rule`*: The pattern that signals the end of the embedded lexer.
Usage:
* `html:embed(css, css_start_rule, css_end_rule)`
* `html:embed(lex, php_start_rule, php_end_rule) -- from php lexer`
#### `lexer.fold`(*lexer, text, start\_pos, start\_line, start\_level*)
Determines fold points in a chunk of text *text* using lexer *lexer*,
returning a table of fold levels associated with line numbers.
*text* starts at position *start_pos* on line number *start_line* with a
beginning fold level of *start_level* in the buffer.
Parameters:
* *`lexer`*: The lexer to fold text with.
* *`text`*: The text in the buffer to fold.
* *`start_pos`*: The position in the buffer *text* starts at, counting from
1.
* *`start_line`*: The line number *text* starts on, counting from 1.
* *`start_level`*: The fold level *text* starts on.
Return:
* table of fold levels associated with line numbers.
#### `lexer.fold_consecutive_lines`(*prefix*)
Returns for `lexer.add_fold_point()` the parameters needed to fold
consecutive lines that start with string *prefix*.
Parameters:
* *`prefix`*: The prefix string (e.g. a line comment).
Usage:
* `lex:add_fold_point(lexer.COMMENT, lexer.fold_consecutive_lines('--'))`
* `lex:add_fold_point(lexer.COMMENT, lexer.fold_consecutive_lines('//'))`
* `lex:add_fold_point(
lexer.KEYWORD, lexer.fold_consecutive_lines('import'))`
#### `lexer.get_rule`(*lexer, id*)
Returns the rule identified by string *id*.
Parameters:
* *`lexer`*: The lexer to fetch a rule from.
* *`id`*: The id of the rule to fetch.
Return:
* pattern
#### `lexer.last_char_includes`(*s*)
Creates and returns a pattern that verifies the first non-whitespace
character behind the current match position is in string set *s*.
Parameters:
* *`s`*: String character set like one passed to `lpeg.S()`.
Usage:
* `local regex = lexer.last_char_includes('+-*!%^&|=,([{') *
lexer.range('/')`
Return:
* pattern
#### `lexer.lex`(*lexer, text, init\_style*)
Lexes a chunk of text *text* (that has an initial style number of
*init_style*) using lexer *lexer*, returning a table of token names and
positions.
Parameters:
* *`lexer`*: The lexer to lex text with.
* *`text`*: The text in the buffer to lex.
* *`init_style`*: The current style. Multiple-language lexers use this to
determine which language to start lexing in.
Return:
* table of token names and positions.
#### `lexer.line_from_position`(*pos*)
Returns the line number (starting from 1) of the line that contains position
*pos*, which starts from 1.
Parameters:
* *`pos`*: The position to get the line number of.
Return:
* number
#### `lexer.load`(*name, alt\_name, cache*)
Initializes or loads and returns the lexer of string name *name*.
Scintilla calls this function in order to load a lexer. Parent lexers also
call this function in order to load child lexers and vice-versa. The user
calls this function in order to load a lexer when using Scintillua as a Lua
library.
Parameters:
* *`name`*: The name of the lexing language.
* *`alt_name`*: The alternate name of the lexing language. This is useful for
embedding the same child lexer with multiple sets of start and end tokens.
* *`cache`*: Flag indicating whether or not to load lexers from the cache.
This should only be `true` when initially loading a lexer (e.g. not from
within another lexer for embedding purposes).
The default value is `false`.
Return:
* lexer object
#### `lexer.modify_rule`(*lexer, id, rule*)
Replaces in lexer *lexer* the existing rule identified by string *id* with
pattern *rule*.
Parameters:
* *`lexer`*: The lexer to modify.
* *`id`*: The id associated with this rule.
* *`rule`*: The LPeg pattern of the rule.
#### `lexer.new`(*name, opts*)
Creates a returns a new lexer with the given name.
Parameters:
* *`name`*: The lexer's name.
* *`opts`*: Table of lexer options. Options currently supported:
* `lex_by_line`: Whether or not the lexer only processes whole lines of
text (instead of arbitrary chunks of text) at a time.
Line lexers cannot look ahead to subsequent lines.
The default value is `false`.
* `fold_by_indentation`: Whether or not the lexer does not define any fold
points and that fold points should be calculated based on changes in line
indentation.
The default value is `false`.
* `case_insensitive_fold_points`: Whether or not fold points added via
`lexer.add_fold_point()` ignore case.
The default value is `false`.
* `inherit`: Lexer to inherit from.
The default value is `nil`.
Usage:
* `lexer.new('rhtml', {inherit = lexer.load('html')})`
#### `lexer.range`(*s, e, single\_line, escapes, balanced*)
Creates and returns a pattern that matches a range of text bounded by strings
or patterns *s* and *e*.
This is a convenience function for matching more complicated ranges like
strings with escape characters, balanced parentheses, and block comments
(nested or not). *e* is optional and defaults to *s*. *single_line* indicates
whether or not the range must be on a single line; *escapes* indicates
whether or not to allow '\' as an escape character; and *balanced* indicates
whether or not to handle balanced ranges like parentheses, and requires *s*
and *e* to be different.
Parameters:
* *`s`*: String or pattern start of a range.
* *`e`*: Optional string or pattern end of a range. The default value is *s*.
* *`single_line`*: Optional flag indicating whether or not the range must be
on a single line.
* *`escapes`*: Optional flag indicating whether or not the range end may
be escaped by a '\' character.
The default value is `false` unless *s* and *e* are identical,
single-character strings. In that case, the default value is `true`.
* *`balanced`*: Optional flag indicating whether or not to match a balanced
range, like the "%b" Lua pattern. This flag only applies if *s* and *e* are
different.
Usage:
* `local dq_str_escapes = lexer.range('"')`
* `local dq_str_noescapes = lexer.range('"', false, false)`
* `local unbalanced_parens = lexer.range('(', ')')`
* `local balanced_parens = lexer.range('(', ')', false, false, true)`
Return:
* pattern
#### `lexer.starts_line`(*patt*)
Creates and returns a pattern that matches pattern *patt* only at the
beginning of a line.
Parameters:
* *`patt`*: The LPeg pattern to match on the beginning of a line.
Usage:
* `local preproc = token(lexer.PREPROCESSOR, lexer.starts_line('#') *
lexer.nonnewline^0)`
Return:
* pattern
#### `lexer.to_eol`(*prefix, escape*)
Creates and returns a pattern that matches from string or pattern *prefix*
until the end of the line.
*escape* indicates whether the end of the line can be escaped with a '\'
character.
Parameters:
* *`prefix`*: String or pattern prefix to start matching at.
* *`escape`*: Optional flag indicating whether or not newlines can be escaped
by a '\' character. The default value is `false`.
Usage:
* `local line_comment = lexer.to_eol('//')`
* `local line_comment = lexer.to_eol(P('#') + ';')`
Return:
* pattern
#### `lexer.token`(*name, patt*)
Creates and returns a token pattern with token name *name* and pattern
*patt*.
If *name* is not a predefined token name, its style must be defined via
`lexer.add_style()`.
Parameters:
* *`name`*: The name of token. If this name is not a predefined token name,
then a style needs to be assiciated with it via `lexer.add_style()`.
* *`patt`*: The LPeg pattern associated with the token.
Usage:
* `local ws = token(lexer.WHITESPACE, lexer.space^1)`
* `local annotation = token('annotation', '@' * lexer.word)`
Return:
* pattern
#### `lexer.word_match`(*words, case\_insensitive, word\_chars*)
Creates and returns a pattern that matches any single word in string *words*.
*case_insensitive* indicates whether or not to ignore case when matching
words.
This is a convenience function for simplifying a set of ordered choice word
patterns.
If *words* is a multi-line string, it may contain Lua line comments (`--`)
that will ultimately be ignored.
Parameters:
* *`words`*: A string list of words separated by spaces.
* *`case_insensitive`*: Optional boolean flag indicating whether or not the
word match is case-insensitive. The default value is `false`.
* *`word_chars`*: Unused legacy parameter.
Usage:
* `local keyword = token(lexer.KEYWORD, word_match[[foo bar baz]])`
* `local keyword = token(lexer.KEYWORD, word_match([[foo-bar foo-baz
bar-foo bar-baz baz-foo baz-bar]], true))`
Return:
* pattern
### Tables defined by `lexer`
#### `lexer.colors`
Map of color name strings to color values in `0xBBGGRR` or `"#RRGGBB"`
format.
Note: for applications running within a terminal emulator, only 16 color
values are recognized, regardless of how many colors a user's terminal
actually supports. (A terminal emulator's settings determines how to actually
display these recognized color values, which may end up being mapped to a
completely different color set.) In order to use the light variant of a
color, some terminals require a style's `bold` attribute must be set along
with that normal color. Recognized color values are black (0x000000), red
(0x000080), green (0x008000), yellow (0x008080), blue (0x800000), magenta
(0x800080), cyan (0x808000), white (0xC0C0C0), light black (0x404040), light
red (0x0000FF), light green (0x00FF00), light yellow (0x00FFFF), light blue
(0xFF0000), light magenta (0xFF00FF), light cyan (0xFFFF00), and light white
(0xFFFFFF).
#### `lexer.styles`
Map of style names to style definition tables.
Style names consist of the following default names as well as the token names
defined by lexers.
* `default`: The default style all others are based on.
* `line_number`: The line number margin style.
* `control_char`: The style of control character blocks.
* `indent_guide`: The style of indentation guides.
* `call_tip`: The style of call tip text. Only the `font`, `size`, `fore`,
and `back` style definition fields are supported.
* `fold_display_text`: The style of text displayed next to folded lines.
* `class`, `comment`, `constant`, `embedded`, `error`, `function`,
`identifier`, `keyword`, `label`, `number`, `operator`, `preprocessor`,
`regex`, `string`, `type`, `variable`, `whitespace`: Some token names used
by lexers. Some lexers may define more token names, so this list is not
exhaustive.
Style definition tables may contain the following fields:
* `font`: String font name.
* `size`: Integer font size.
* `bold`: Whether or not the font face is bold. The default value is `false`.
* `weight`: Integer weight or boldness of a font, between 1 and 999.
* `italics`: Whether or not the font face is italic. The default value is
`false`.
* `underlined`: Whether or not the font face is underlined. The default value
is `false`.
* `fore`: Font face foreground color in `0xBBGGRR` or `"#RRGGBB"` format.
* `back`: Font face background color in `0xBBGGRR` or `"#RRGGBB"` format.
* `eolfilled`: Whether or not the background color extends to the end of the
line. The default value is `false`.
* `case`: Font case, `'u'` for upper, `'l'` for lower, and `'m'` for normal,
mixed case. The default value is `'m'`.
* `visible`: Whether or not the text is visible. The default value is `true`.
* `changeable`: Whether the text is changeable instead of read-only. The
default value is `true`.
---
## The `lfs` Module
---
Extends the `lfs` library to find files in directories and determine absolute
file paths.
### Functions defined by `lfs`
#### `lfs.abspath`(*filename, prefix*)
Returns the absolute path to string *filename*.
*prefix* or `lfs.currentdir()` is prepended to a relative filename. The
returned path is not guaranteed to exist.
Parameters:
* *`filename`*: The relative or absolute path to a file.
* *`prefix`*: Optional prefix path prepended to a relative filename.
Return:
* string absolute path
#### `lfs.walk`(*dir, filter, n, include\_dirs*)
Returns an iterator that iterates over all files and sub-directories (up to
*n* levels deep) in directory *dir* and yields each file found.
String or list *filter* determines which files to yield, with the default
filter being `lfs.default_filter`. A filter consists of Lua patterns that
match file and directory paths to include or exclude. Exclusive patterns
begin with a '!'. If no inclusive patterns are given, any path is initially
considered. As a convenience, file extensions can be specified literally
instead of as a Lua pattern (e.g. '.lua' vs. '%.lua$'), and '/' also matches
the Windows directory separator ('[/\\]' is not needed).
Parameters:
* *`dir`*: The directory path to iterate over.
* *`filter`*: Optional filter for files and directories to include and
exclude. The default value is `lfs.default_filter`.
* *`n`*: Optional maximum number of directory levels to descend into.
The default value is `nil`, which indicates no limit.
* *`include_dirs`*: Optional flag indicating whether or not to yield
directory names too. Directory names are passed with a trailing '/' or '\',
depending on the current platform.
The default value is `false`.
See also:
* [`lfs.filter`](#lfs.filter)
### Tables defined by `lfs`
#### `lfs.default_filter`
The filter table containing common binary file extensions and version control
directories to exclude when iterating over files and directories using
`walk`.
Extensions excluded: a, bmp, bz2, class, dll, exe, gif, gz, jar, jpeg, jpg,
o, pdf, png, so, tar, tgz, tif, tiff, xz, and zip.
Directories excluded: .bzr, .git, .hg, .svn, _FOSSIL_, and node_modules.
See also:
* [`lfs.walk`](#lfs.walk)
---
## The `os` Module
---
Extends Lua's `os` library to provide process spawning capabilities.
### Functions defined by `os`
#### `os.spawn`(*cmd, cwd, env, stdout\_cb, stderr\_cb, exit\_cb*)
Spawns an interactive child process *cmd* in a separate thread, returning
a handle to that process.
On Windows, *cmd* is passed to `cmd.exe`: `%COMSPEC% /c [cmd]`.
At the moment, only the Windows terminal version spawns processes in the same
thread.
Parameters:
* *`cmd`*: A command line string that contains the program's name followed by
arguments to pass to it. `PATH` is searched for program names.
* *`cwd`*: Optional current working directory (cwd) for the child
process. When omitted, the parent's cwd is used.
* *`env`*: Optional table of environment variables for the child process.
When omitted, the parent's environment is used.
* *`stdout_cb`*: Optional Lua function that accepts a string parameter for a
block of standard output read from the child. Stdout is read asynchronously
in 1KB or 0.5KB blocks (depending on the platform), or however much data is
available at the time.
At the moment, only the Win32 terminal version sends all output, whether it
be stdout or stderr, to this callback after the process finishes.
* *`stderr_cb`*: Optional Lua function that accepts a string parameter for a
block of standard error read from the child. Stderr is read asynchronously
in 1KB or 0.5kB blocks (depending on the platform), or however much data is
available at the time.
* *`exit_cb`*: Optional Lua function that is called when the child process
finishes. The child's exit status is passed.
Usage:
* `os.spawn('lua ' .. buffer.filename, print)`
* `proc = os.spawn('lua -e "print(io.read())"', print)
proc:write('foo\n')`
Return:
* proc or nil plus an error message on failure
#### `spawn_proc:close`()
Closes standard input for process *spawn_proc*, effectively sending an EOF
(end of file) to it.
#### `spawn_proc:kill`(*signal*)
Kills running process *spawn_proc*, or sends it Unix signal *signal*.
Parameters:
* *`signal`*: Optional Unix signal to send to *spawn_proc*. The default value
is 9 (`SIGKILL`), which kills the process.
#### `spawn_proc:read`(*arg*)
Reads and returns stdout from process *spawn_proc*, according to string
format or number *arg*.
Similar to Lua's `io.read()` and blocks for input. *spawn_proc* must still be
running. If an error occurs while reading, returns `nil`, an error code, and
an error message.
Ensure any read operations read all stdout available, as the stdout callback
function passed to `os.spawn()` will not be called until the stdout buffer is
clear.
Parameters:
* *`arg`*: Optional argument similar to those in Lua's `io.read()`, but "n"
is not supported. The default value is "l", which reads a line.
Return:
* string of bytes read
#### `spawn_proc:status`()
Returns the status of process *spawn_proc*, which is either "running" or
"terminated".
Return:
* "running" or "terminated"
#### `spawn_proc:wait`()
Blocks until process *spawn_proc* finishes (if it has not already done so)
and returns its status code.
Return:
* integer status code
#### `spawn_proc:write`(*...*)
Writes string input to the stdin of process *spawn_proc*.
Note: On Linux, if more than 65536 bytes (64K) are to be written, it is
possible those bytes need to be written in 65536-byte (64K) chunks, or the
process may not receive all input. However, it is also possible that there is
a limit on how many bytes can be written in a short period of time, perhaps
196608 bytes (192K).
Parameters:
* *`...`*: Standard input for *spawn_proc*.
---
## The `string` Module
---
Extends Lua's `string` library to provide character set conversions.
### Functions defined by `string`
#### `string.iconv`(*text, new, old*)
Converts string *text* from encoding *old* to encoding *new* using GNU
libiconv, returning the string result.
Valid encodings are [GNU libiconv's encodings][] and include:
* European: ASCII, ISO-8859-{1,2,3,4,5,7,9,10,13,14,15,16}, KOI8-R, KOI8-U,
KOI8-RU, CP{1250,1251,1252,1253,1254,1257}, CP{850,866,1131},
Mac{Roman,CentralEurope,Iceland,Croatian,Romania},
Mac{Cyrillic,Ukraine,Greek,Turkish}, Macintosh.
* Semitic: ISO-8859-{6,8}, CP{1255,1256}, CP862, Mac{Hebrew,Arabic}.
* Japanese: EUC-JP, SHIFT_JIS, CP932, ISO-2022-JP, ISO-2022-JP-2,
ISO-2022-JP-1.
* Chinese: EUC-CN, HZ, GBK, CP936, GB18030, EUC-TW, BIG5, CP950,
BIG5-HKSCS, BIG5-HKSCS:2004, BIG5-HKSCS:2001, BIG5-HKSCS:1999,
ISO-2022-CN, ISO-2022-CN-EXT.
* Korean: EUC-KR, CP949, ISO-2022-KR, JOHAB.
* Armenian: ARMSCII-8.
* Georgian: Georgian-Academy, Georgian-PS.
* Tajik: KOI8-T.
* Kazakh: PT154, RK1048.
* Thai: ISO-8859-11, TIS-620, CP874, MacThai.
* Laotian: MuleLao-1, CP1133.
* Vietnamese: VISCII, TCVN, CP1258.
* Unicode: UTF-8, UCS-2, UCS-2BE, UCS-2LE, UCS-4, UCS-4BE, UCS-4LE, UTF-16,
UTF-16BE, UTF-16LE, UTF-32, UTF-32BE, UTF-32LE, UTF-7, C99, JAVA.
[GNU libiconv's encodings]: https://www.gnu.org/software/libiconv/
Parameters:
* *`text`*: The text to convert.
* *`new`*: The string encoding to convert to.
* *`old`*: The string encoding to convert from.
---
## The `textadept` Module
---
The textadept module.
It provides utilities for editing text in Textadept.
---
## The `textadept.bookmarks` Module
---
Bookmarks for Textadept.
### Fields defined by `textadept.bookmarks`
#### `textadept.bookmarks.MARK_BOOKMARK` (number)
The bookmark mark number.
### Functions defined by `textadept.bookmarks`
#### `textadept.bookmarks.clear`()
Clears all bookmarks in the current buffer.
#### `textadept.bookmarks.goto_mark`(*next*)
Prompts the user to select a bookmarked line to move the caret to the
beginning of unless *next* is given.
If *next* is `true` or `false`, moves the caret to the beginning of the next
or previously bookmarked line, respectively.
Parameters:
* *`next`*: Optional flag indicating whether to go to the next or previous
bookmarked line relative to the current line. The default value is `nil`,
prompting the user for a bookmarked line to go to.
#### `textadept.bookmarks.toggle`()
Toggles a bookmark on the current line.
---
## The `textadept.editing` Module
---
Editing features for Textadept.
### Fields defined by `textadept.editing`
#### `textadept.editing.INDIC_BRACEMATCH` (number)
The matching brace highlight indicator number.
#### `textadept.editing.INDIC_HIGHLIGHT` (number)
The word highlight indicator number.
#### `textadept.editing.auto_enclose` (bool)
Whether or not to auto-enclose selected text when typing a punctuation
character, taking [`textadept.editing.auto_pairs`](#textadept.editing.auto_pairs) into account.
The default value is `false`.
#### `textadept.editing.auto_indent` (bool)
Match the previous line's indentation level after inserting a new line.
The default value is `true`.
#### `textadept.editing.autocomplete_all_words` (bool)
Autocomplete the current word using words from all open buffers.
If `true`, performance may be slow when many buffers are open.
The default value is `false`.
#### `textadept.editing.highlight_words` (number)
The word highlight mode.
* `textadept.editing.HIGHLIGHT_CURRENT`
Automatically highlight all instances of the current word.
* `textadept.editing.HIGHLIGHT_SELECTED`
Automatically highlight all instances of the selected word.
* `textadept.editing.HIGHLIGHT_NONE`
Do not automatically highlight words.
The default value is `textadept.editing.HIGHLIGHT_NONE`.
#### `textadept.editing.strip_trailing_spaces` (bool)
Strip trailing whitespace before saving files.
The default value is `false`.
### Functions defined by `textadept.editing`
#### `textadept.editing.autocomplete`(*name*)
Displays an autocompletion list provided by the autocompleter function
associated with string *name*, and returns `true` if completions were found.
Parameters:
* *`name`*: The name of an autocompleter function in the `autocompleters`
table to use for providing autocompletions.
See also:
* [`textadept.editing.autocompleters`](#textadept.editing.autocompleters)
#### `textadept.editing.convert_indentation`()
Converts indentation between tabs and spaces according to `buffer.use_tabs`.
If `buffer.use_tabs` is `true`, `buffer.tab_width` indenting spaces are
converted to tabs. Otherwise, all indenting tabs are converted to
`buffer.tab_width` spaces.
See also:
* [`buffer.use_tabs`](#buffer.use_tabs)
#### `textadept.editing.enclose`(*left, right*)
Encloses the selected text or the current word within strings *left* and
*right*, taking multiple selections into account.
Parameters:
* *`left`*: The left part of the enclosure.
* *`right`*: The right part of the enclosure.
#### `textadept.editing.filter_through`(*command*)
Passes the selected text or all buffer text to string shell command *command*
as standard input (stdin) and replaces the input text with the command's
standard output (stdout). *command* may contain shell pipes ('|').
Standard input is as follows:
1. If no text is selected, the entire buffer is used.
2. If text is selected and spans a single line, only the selected text is
used.
3. If text is selected and spans multiple lines, all text on the lines that
have text selected is passed as stdin. However, if the end of the selection
is at the beginning of a line, only the line ending delimiters from the
previous line are included. The rest of the line is excluded.
Parameters:
* *`command`*: The Linux, BSD, macOS, or Windows shell command to filter text
through. May contain pipes.
#### `textadept.editing.goto_line`(*line*)
Moves the caret to the beginning of line number *line* or the user-specified
line, ensuring *line* is visible.
Parameters:
* *`line`*: Optional line number to go to. If `nil`, the user is prompted for
one.
#### `textadept.editing.join_lines`()
Joins the currently selected lines or the current line with the line below
it.
As long as any part of a line is selected, the entire line is eligible for
joining.
#### `textadept.editing.paste_reindent`()
Pastes the text from the clipboard, taking into account the buffer's
indentation settings and the indentation of the current and preceding lines.
#### `textadept.editing.select_enclosed`(*left, right*)
Selects the text between strings *left* and *right* that enclose the caret.
If that range is already selected, toggles between selecting *left* and
*right* as well.
If *left* and *right* are not provided, they are assumed to be one of the
delimiter pairs specified in `auto_pairs` and are inferred from the current
position or selection.
Parameters:
* *`left`*: Optional left part of the enclosure.
* *`right`*: Optional right part of the enclosure.
See also:
* [`textadept.editing.auto_pairs`](#textadept.editing.auto_pairs)
#### `textadept.editing.select_line`()
Selects the current line.
#### `textadept.editing.select_paragraph`()
Selects the current paragraph.
Paragraphs are surrounded by one or more blank lines.
#### `textadept.editing.select_word`(*all*)
Selects the current word or, if *all* is `true`, all occurrences of the
current word.
If a word is already selected, selects the next occurrence as a multiple
selection.
Parameters:
* *`all`*: Whether or not to select all occurrences of the current word.
The default value is `false`.
See also:
* [`buffer.word_chars`](#buffer.word_chars)
#### `textadept.editing.show_documentation`(*pos, ignore\_case*)
Displays a call tip with documentation for the symbol under or directly
behind position *pos* or the caret position.
Documentation is read from API files in the `api_files` table.
If a call tip is already shown, cycles to the next one if it exists.
Symbols are determined by using `buffer.word_chars`.
Parameters:
* *`pos`*: Optional position of the symbol to show documentation for. If
omitted, the caret position is used.
* *`ignore_case`*: Optional flag that indicates whether or not to search
API files case-insensitively for symbols. The default value is `false`.
See also:
* [`textadept.editing.api_files`](#textadept.editing.api_files)
* [`buffer.word_chars`](#buffer.word_chars)
#### `textadept.editing.toggle_comment`()
Comments or uncomments the selected lines based on the current language.
As long as any part of a line is selected, the entire line is eligible for
commenting/uncommenting.
See also:
* [`textadept.editing.comment_string`](#textadept.editing.comment_string)
#### `textadept.editing.transpose_chars`()
Transposes characters intelligently.
If the caret is at the end of a line, transposes the two characters before
the caret. Otherwise, the characters to the left and right are.
### Tables defined by `textadept.editing`
#### `textadept.editing.XPM_IMAGES`
Map of image names to registered image numbers.
Fields:
* `CLASS`: The image number for classes.
* `NAMESPACE`: The image number for namespaces.
* `METHOD`: The image number for methods.
* `SIGNAL`: The image number for signals.
* `SLOT`: The image number for slots.
* `VARIABLE`: The image number for variables.
* `STRUCT`: The image number for structures.
* `TYPEDEF`: The image number for type definitions.
#### `textadept.editing.api_files`
Map of lexer names to API documentation file tables.
File tables contain API file paths or functions that return such paths.
Each line in an API file consists of a symbol name (not a fully qualified
symbol name), a space character, and that symbol's documentation. "\n"
represents a newline character.
See also:
* [`textadept.editing.show_documentation`](#textadept.editing.show_documentation)
#### `textadept.editing.auto_pairs`
Map of auto-paired characters like parentheses, brackets, braces, and quotes.
The ASCII values of opening characters are assigned to strings that contain
complement characters. The default auto-paired characters are "()", "[]",
"{}", "''", and """".
Usage:
* `textadept.editing.auto_pairs[60] = '>' -- pair '<' and '>'`
* `textadept.editing.auto_pairs = nil -- disable completely`
#### `textadept.editing.autocompleters`
Map of autocompleter names to autocompletion functions.
Names are typically lexer names and autocompletion functions typically
autocomplete symbols.
Autocompletion functions must return two values: the number of characters
behind the caret that are used as the prefix of the entity to be
autocompleted, and a list of completions to be shown. Autocompletion lists
are sorted automatically.
See also:
* [`textadept.editing.autocomplete`](#textadept.editing.autocomplete)
#### `textadept.editing.brace_matches`
Table of brace characters to highlight.
The ASCII values of brace characters are keys and are assigned non-`nil`
values. The default brace characters are '(', ')', '[', ']', '{', and '}'.
Usage:
* `textadept.editing.brace_matches[60] = true -- '<'`
* `textadept.editing.brace_matches[62] = true -- '>'`
#### `textadept.editing.comment_string`
Map of lexer names to line comment strings for programming languages, used by
the `toggle_comment()` function.
Keys are lexer names and values are either the language's line comment
prefixes or block comment delimiters separated by a '|' character.
See also:
* [`textadept.editing.toggle_comment`](#textadept.editing.toggle_comment)
#### `textadept.editing.typeover_chars`
Table of characters to move over when typed.
The ASCII values of characters are keys and are assigned non-`nil` values.
The default characters are ')', ']', '}', ''', and '"'.
Usage:
* `textadept.editing.typeover_chars[62] = true -- '>'`
---
## The `textadept.file_types` Module
---
Handles file type detection for Textadept.
### Fields defined by `textadept.file_types`
#### `events.LEXER_LOADED` (string)
Emitted after loading a language lexer.
This is useful for overriding a language module's key bindings or other
properties since the module is not loaded when Textadept starts.
Arguments:
* _`name`_: The language lexer's name.
### Functions defined by `textadept.file_types`
#### `textadept.file_types.select_lexer`()
Prompts the user to select a lexer for the current buffer.
See also:
* [`buffer.set_lexer`](#buffer.set_lexer)
### Tables defined by `textadept.file_types`
#### `textadept.file_types.extensions`
Map of file extensions to their associated lexer names.
If the file type is not recognized by its first-line, each file extension is
matched against the file's extension.
#### `textadept.file_types.patterns`
Map of first-line patterns to their associated lexer names.
Each pattern is matched against the first line in the file.
---
## The `textadept.keys` Module
---
Defines key bindings for Textadept.
This set of key bindings is pretty standard among other text editors, at
least for basic editing commands and movements.
### Key Bindings
Win32, Linux, BSD|macOS|Terminal|Command
-----------------|-----|--------|--------
**File** | | |
Ctrl+N |⌘N |M-^N |New file
Ctrl+O |⌘O |^O |Open file
Ctrl+Alt+O |^⌘O |M-^O |Open recent file...
Ctrl+Shift+O |⌘⇧O |M-O |Reload file
Ctrl+S |⌘S |^S |Save file
Ctrl+Shift+S |⌘⇧S |M-^S |Save file as..
None |None |None |Save all files
Ctrl+W |⌘W |^W |Close file
Ctrl+Shift+W |⌘⇧W |M-^W |Close all files
None |None |None |Load session...
None |None |None |Save session...
Ctrl+Q |⌘Q |^Q |Quit
**Edit** | | |
Ctrl+Z
Alt+Bksp |⌘Z |^Z^(†)
M-Z|Undo
Ctrl+Y
Ctrl+Shift+Z |⌘⇧Z |^Y
M-S-Z |Redo
Ctrl+X
Shift+Del |⌘X
⇧⌦|^X |Cut
Ctrl+C
Ctrl+Ins |⌘C |^C |Copy
Ctrl+V
Shift+Ins |⌘V |^V |Paste
Ctrl+Shift+V |⌘⇧V |M-V |Paste Reindent
Ctrl+D |⌘D |None |Duplicate line
Del |⌦
^D |Del
^D |Delete
Alt+Del |^⌦ |M-Del
M-D |Delete word
Ctrl+A |⌘A |M-A |Select all
Ctrl+M |^M |M-M |Match brace
Ctrl+Enter |^Esc |M-Enter^(‡) |Complete word
Ctrl+/ |^/ |M-/ |Toggle block comment
Ctrl+T |^T |^T |Transpose characters
Ctrl+Shift+J |^J |M-J |Join lines
Ctrl+| |⌘| |^\ |Filter text through
Ctrl+Shift+M |^⇧M |M-S-M |Select between delimiters
Ctrl+< |⌘< |M-< |Select between XML tags
Ctrl+> |⌘> |None |Select in XML tag
Ctrl+Shift+D |⌘⇧D |M-S-W |Select word
Ctrl+Shift+N |⌘⇧N |M-S-N |Select line
Ctrl+Shift+P |⌘⇧P |M-S-P |Select paragraph
Ctrl+Alt+U |^U |M-^U |Upper case selection
Ctrl+Alt+Shift+U |^⇧U |M-^L |Lower case selection
Alt+< |^< |M-> |Enclose as XML tags
Alt+> |^> |None |Enclose as single XML tag
Alt+" |^" |None |Enclose in double quotes
Alt+' |^' |None |Enclose in single quotes
Alt+( |^( |M-) |Enclose in parentheses
Alt+[ |^[ |M-] |Enclose in brackets
Alt+{ |^{ |M-} |Enclose in braces
Ctrl+Shift+Up |^⇧⇡ |S-^Up |Move selected lines up
Ctrl+Shift+Down |^⇧⇣ |S-^Down |Move selected lines down
Ctrl+P |⌘, |M-~ |Preferences
**Search** | | |
Ctrl+F |⌘F |M-F
M-S-F|Find
Ctrl+G
F3 |⌘G |M-G |Find next
Ctrl+Shift+G
Shift+F3|⌘⇧G |M-S-G |Find previous
Ctrl+Alt+R |^R |M-R |Replace
Ctrl+Alt+Shift+R |^⇧R |M-S-R |Replace all
Ctrl+Alt+F |^⌘F |M-^F |Find incremental
Ctrl+Shift+F |⌘⇧F |None |Find in files
Ctrl+Alt+G |^⌘G |None |Goto next file found
Ctrl+Alt+Shift+G |^⌘⇧G|None |Goto previous file found
Ctrl+J |⌘J |^J |Jump to line
**Tools** | | |
Ctrl+E |⌘E |M-C |Command entry
Ctrl+Shift+E |⌘⇧E |M-S-C |Select command
Ctrl+R |⌘R |^R |Run
Ctrl+Shift+R |⌘⇧R |M-^R |Compile
Ctrl+Shift+A |⌘⇧A |None |Set Arguments...
Ctrl+Shift+B |⌘⇧B |M-^B |Build
Ctrl+Shift+X |⌘⇧X |M-^X |Stop
Ctrl+Alt+E |^⌘E |M-X |Next Error
Ctrl+Alt+Shift+E|^⌘⇧E |M-S-X |Previous Error
Ctrl+F2 |⌘F2 |F1 |Toggle bookmark
Ctrl+Shift+F2 |⌘⇧F2 |F6 |Clear bookmarks
F2 |F2 |F2 |Next bookmark
Shift+F2 |⇧F2 |F3 |Previous bookmark
Alt+F2 |⌥F2 |F4 |Goto bookmark...
F9 |F9 |F9 |Start/stop recording macro
Shift+F9 |⇧F9 |F10 |Play recorded macro
Ctrl+U |⌘U |^U |Quickly open `_USERHOME`
None |None |None |Quickly open `_HOME`
Ctrl+Alt+Shift+O|^⌘⇧O |M-S-O |Quickly open current directory
Ctrl+Alt+Shift+P|^⌘⇧P |M-^P |Quickly open current project
Ctrl+Shift+K |⌥⇧⇥ |M-S-K |Insert snippet...
Tab |⇥ |Tab |Expand snippet or next placeholder
Shift+Tab |⇧⇥ |S-Tab |Previous snippet placeholder
Esc |Esc |Esc |Cancel snippet
Ctrl+K |⌥⇥ |M-K |Complete trigger word
Ctrl+Space |⌥Esc |^Space |Complete symbol
Ctrl+H |^H |M-H
M-S-H|Show documentation
Ctrl+I |⌘I |M-S-I |Show style
**Buffer** | | |
Ctrl+Tab |^⇥ |M-N |Next buffer
Ctrl+Shift+Tab |^⇧⇥ |M-P |Previous buffer
Ctrl+B |⌘B |M-B
M-S-B|Switch to buffer...
None |None |None |Tab width: 2
None |None |None |Tab width: 3
None |None |None |Tab width: 4
None |None |None |Tab width: 8
Ctrl+Alt+Shift+T|^⇧T |M-T
M-S-T|Toggle use tabs
Ctrl+Alt+I |^I |M-I |Convert indentation
None |None |None |CR+LF EOL mode
None |None |None |LF EOL mode
None |None |None |UTF-8 encoding
None |None |None |ASCII encoding
None |None |None |CP-1252 encoding
None |None |None |UTF-16 encoding
Ctrl+Alt+\\ |^\\ |None |Toggle wrap mode
Ctrl+Alt+Shift+S|^⇧S |None |Toggle view whitespace
Ctrl+Shift+L |⌘⇧L |M-S-L |Select lexer...
**View** | | |
Ctrl+Alt+N |^⌥⇥ |M-^V N |Next view
Ctrl+Alt+P |^⌥⇧⇥ |M-^V P |Previous view
Ctrl+Alt+S
Ctrl+Alt+H|^S |M-^V S
M-^V H|Split view horizontal
Ctrl+Alt+V |^V |M-^V V |Split view vertical
Ctrl+Alt+W |^W |M-^V W |Unsplit view
Ctrl+Alt+Shift+W |^⇧W |M-^V S-W |Unsplit all views
Ctrl+Alt++
Ctrl+Alt+=|^+
^=|M-^V +
M-^V =|Grow view
Ctrl+Alt+- |^- |M-^V - |Shrink view
Ctrl+* |⌘* |M-* |Toggle current fold
Ctrl+Alt+Shift+I |^⇧I |N/A |Toggle indent guides
Ctrl+Alt+Shift+V |^⇧V |None |Toggle virtual space
Ctrl+= |⌘= |N/A |Zoom in
Ctrl+- |⌘- |N/A |Zoom out
Ctrl+0 |⌘0 |N/A |Reset zoom
**Help**| | |
F1 |F1 |None|Open manual
Shift+F1|⇧F1 |None|Open LuaDoc
None |None|None|About
**Movement** | | |
Down |⇣
^N |^N
Down |Line down
Shift+Down |⇧⇣
^⇧N |S-Down |Line down extend selection
Ctrl+Down |^⇣ |^Down |Scroll line down
Alt+Shift+Down |⌥⇧⇣ |M-S-Down |Line down extend rect. selection
Up |⇡
^P |^P
Up |Line up
Shift+Up |⇧⇡
^⇧P |S-Up |Line up extend selection
Ctrl+Up |^⇡ |^Up |Scroll line up
Alt+Shift+Up |⌥⇧⇡ |M-S-Up |Line up extend rect. selection
Left |⇠
^B |^B
Left |Char left
Shift+Left |⇧⇠
^⇧B |S-Left |Char left extend selection
Ctrl+Left |⌥⇠
^⌘B |^Left |Word left
Ctrl+Shift+Left |^⇧⇠
^⌘⇧B|S-^Left |Word left extend selection
Alt+Shift+Left |⌥⇧⇠ |M-S-Left |Char left extend rect. selection
Right |⇢
^F |^F
Right|Char right
Shift+Right |⇧⇢
^⇧F |S-Right |Char right extend selection
Ctrl+Right |⌥⇢
^⌘F |^Right |Word right
Ctrl+Shift+Right|^⇧⇢
^⌘⇧F|S-^Right |Word right extend selection
Alt+Shift+Right |⌥⇧⇢ |M-S-Right |Char right extend rect. selection
Home |⌘⇠
^A |^A
Home |Line start
Shift+Home |⌘⇧⇠
^⇧A |M-S-A |Line start extend selection
Ctrl+Home |⌘⇡
⌘↖ |M-^A |Document start
Ctrl+Shift+Home |⌘⇧⇡
⌘⇧↖ |None |Document start extend selection
Alt+Shift+Home |⌥⇧↖ |None |Line start extend rect. selection
End |⌘⇢
^E |^E
End |Line end
Shift+End |⌘⇧⇢
^⇧E |M-S-E |Line end extend selection
Ctrl+End |⌘⇣
⌘↘ |M-^E |Document end
Ctrl+Shift+End |⌘⇧⇣
⌘⇧↘ |None |Document end extend selection
Alt+Shift+End |⌥⇧↘ |None |Line end extend rect. selection
PgUp |⇞ |PgUp |Page up
Shift+PgUp |⇧⇞ |M-S-U |Page up extend selection
Alt+Shift+PgUp |⌥⇧⇞ |None |Page up extend rect. selection
PgDn |⇟ |PgDn |Page down
Shift+PgDn |⇧⇟ |M-S-D |Page down extend selection
Alt+Shift+PgDn |⌥⇧⇟ |None |Page down extend rect. selection
Ctrl+Del |⌘⌦ |^Del |Delete word right
Ctrl+Shift+Del |⌘⇧⌦ |S-^Del |Delete line right
Ins |Ins |Ins |Toggle overtype
Bksp |⌫
⇧⌫ |^H
Bksp |Delete back
Ctrl+Bksp |⌘⌫ |None |Delete word left
Ctrl+Shift+Bksp |⌘⇧⌫ |None |Delete line left
Tab |⇥ |Tab
^I |Insert tab or indent
Shift+Tab |⇧⇥ |S-Tab |Dedent
None |^K |^K |Cut to line end
None |^L |None |Center line vertically
N/A |N/A |^^ |Mark text at the caret position
N/A |N/A |^] |Swap caret and mark anchor
**UTF-8 Input** | | |
Ctrl+Shift+U *xxxx* Enter|⌘⇧U *xxxx* ↩|M-U *xxxx* Enter|Insert U-*xxxx* char.
**Find Fields**| | |
Left |⇠
^B |^B
Left |Cursor left
Right |⇢
^F |^F
Right|Cursor right
Del |⌦ |Del |Delete forward
Bksp |⌫ |^H
Bksp |Delete back
Ctrl+V |⌘V |^V |Paste
N/A |N/A |^X |Cut all
N/A |N/A |^Y |Copy all
N/A |N/A |^U |Erase all
Home |↖
⌘⇠
^A|^A |Home
End |↘
⌘⇢
^E|^E |End
N/A |N/A |^T |Transpose characters
N/A |N/A |Tab |Toggle find/replace buttons
Tab |⇥ |Down |Focus replace field
Shift+Tab |⇧⇥ |Up |Focus find field
Up |⇡ |^P |Cycle back through history
Down |⇣ |^N |Cycle forward through history
N/A |N/A |F1 |Toggle "Match Case"
N/A |N/A |F2 |Toggle "Whole Word"
N/A |N/A |F3 |Toggle "Regex"
N/A |N/A |F4 |Toggle "Find in Files"
†: Some terminals interpret ^Z as suspend; see FAQ for workaround.
‡: Ctrl+Enter in Windows terminal version.
---
## The `textadept.macros` Module
---
A module for recording, playing, saving, and loading keyboard macros.
Menu commands are also recorded.
At this time, typing into multiple cursors during macro playback is not
supported.
### Functions defined by `textadept.macros`
#### `textadept.macros.load`(*filename*)
Loads a macro from file *filename* or the user-selected file.
Parameters:
* *`filename`*: Optional macro file to load. If `nil`, the user is prompted
for one.
#### `textadept.macros.play`()
Plays a recorded or loaded macro.
See also:
* [`textadept.macros.load`](#textadept.macros.load)
#### `textadept.macros.record`()
Toggles between starting and stopping macro recording.
#### `textadept.macros.save`(*filename*)
Saves a recorded macro to file *filename* or the user-selected file.
Parameters:
* *`filename`*: Optional filename to save the recorded macro to. If `nil`,
the user is prompted for one.
---
## The `textadept.menu` Module
---
Defines the menus used by Textadept.
Menus are simply tables of menu items and submenus and may be edited in
place. A menu item itself is a table whose first element is a menu label and
whose second element is a menu command to run. Submenus have `title` keys
assigned to string text.
### Functions defined by `textadept.menu`
#### `textadept.menu.select_command`()
Prompts the user to select a menu command to run.
### Tables defined by `textadept.menu`
#### `textadept.menu.context_menu`
The default right-click context menu.
Submenus, and menu items can be retrieved by name in addition to table index
number.
Usage:
* `textadept.menu.context_menu[#textadept.menu.context_menu + 1] = {...}`
#### `textadept.menu.menubar`
The default main menubar.
Individual menus, submenus, and menu items can be retrieved by name in
addition to table index number.
Usage:
* `textadept.menu.menubar[_L['File']][_L['New']]`
* `textadept.menu.menubar[_L['File']][_L['New']][2] = function() .. end`
#### `textadept.menu.tab_context_menu`
The default tabbar context menu.
Submenus, and menu items can be retrieved by name in addition to table index
number.
---
## The `textadept.run` Module
---
Compile and run source code files with Textadept.
[Language modules](#compile-and-run) may tweak the `compile_commands`,
`run_commands`, and `error_patterns` tables for particular languages.
The user may tweak `build_commands` for particular projects.
### Fields defined by `textadept.run`
#### `textadept.run.MARK_ERROR` (number)
The run or compile error marker number.
#### `textadept.run.MARK_WARNING` (number)
The run or compile warning marker number.
#### `events.BUILD_OUTPUT` (string)
Emitted when executing a project's build shell command.
By default, output is printed to the message buffer. In order to override
this behavior, connect to the event with an index of `1` and return `true`.
Arguments:
* `output`: A line of string output from the command.
#### `events.COMPILE_OUTPUT` (string)
Emitted when executing a language's compile shell command.
By default, compiler output is printed to the message buffer. In order to
override this behavior, connect to the event with an index of `1` and
return `true`.
Arguments:
* `output`: A line of string output from the command.
* `ext_or_lexer`: The file extension or lexer name associated with the
executed compile command.
#### `events.RUN_OUTPUT` (string)
Emitted when executing a language's run shell command.
By default, output is printed to the message buffer. In order to override
this behavior, connect to the event with an index of `1` and return `true`.
Arguments:
* `output`: A line of string output from the command.
* `ext_or_lexer`: The file extension or lexer name associated with the
executed run command.
#### `textadept.run.run_in_background` (bool)
Run shell commands silently in the background.
This only applies when the message buffer is open, though it does not have
to be visible.
The default value is `false`.
### Functions defined by `textadept.run`
#### `textadept.run.build`(*root\_directory*)
Builds the project whose root path is *root_directory* or the current project
using the shell command from the `build_commands` table.
If a "makefile" type of build file is found, prompts the user for the full
build command.
The current project is determined by either the buffer's filename or the
current working directory.
Emits `BUILD_OUTPUT` events.
Parameters:
* *`root_directory`*: The path to the project to build. The default value is
the current project.
See also:
* [`textadept.run.build_commands`](#textadept.run.build_commands)
* [`events`](#events)
#### `textadept.run.compile`(*filename*)
Compiles file *filename* or the current file using an appropriate shell
command from the `compile_commands` table.
The shell command is determined from the file's filename, extension, or
language in that order.
Emits `COMPILE_OUTPUT` events.
Parameters:
* *`filename`*: Optional path to the file to compile. The default value is
the current file's filename.
See also:
* [`textadept.run.compile_commands`](#textadept.run.compile_commands)
* [`events`](#events)
#### `textadept.run.goto_error`(*line\_num, next*)
Jumps to the source of the recognized compile/run warning or error on line
number *line_num* in the message buffer.
If *line_num* is `nil`, jumps to the next or previous warning or error,
depending on boolean *next*. Displays an annotation with the warning or error
message if possible.
Parameters:
* *`line_num`*: Optional line number in the message buffer that contains the
compile/run warning or error to go to. This parameter may be omitted
completely.
* *`next`*: Optional flag indicating whether to go to the next recognized
warning/error or the previous one. Only applicable when *line_num* is
`nil`.
See also:
* [`textadept.run.error_patterns`](#textadept.run.error_patterns)
#### `textadept.run.run`(*filename*)
Runs file *filename* or the current file using an appropriate shell command
from the `run_commands` table.
The shell command is determined from the file's filename, extension, or
language in that order.
Emits `RUN_OUTPUT` events.
Parameters:
* *`filename`*: Optional path to the file to run. The default value is the
current file's filename.
See also:
* [`textadept.run.run_commands`](#textadept.run.run_commands)
* [`events`](#events)
#### `textadept.run.stop`()
Stops the currently running process, if any.
### Tables defined by `textadept.run`
#### `textadept.run.build_commands`
Map of project root paths and "makefiles" to their associated "build" shell
command line strings or functions that return such strings.
Functions may also return a working directory to operate in. By default, it
is the project's root directory.
#### `textadept.run.compile_commands`
Map of filenames, file extensions, and lexer names to their associated
"compile" shell command line strings or functions that return such strings.
Command line strings may have the following macros:
+ `%f`: The file's name, including its extension.
+ `%e`: The file's name, excluding its extension.
+ `%d`: The file's directory path.
+ `%p`: The file's full path.
Functions may also return a working directory to operate in. By default, it
is the current file's parent directory.
#### `textadept.run.error_patterns`
Map of file extensions and lexer names to their associated lists of string
patterns that match warning and error messages emitted by compile and run
commands for those file extensions and lexers.
Patterns match single lines and contain captures for a filename, line number,
column number (optional), and warning or error message (optional).
Double-clicking a warning or error message takes the user to the source of
that warning/error.
Note: `(.-)` captures in patterns are interpreted as filenames; `(%d+)`
captures are interpreted as line numbers first, and then column numbers; and
any other capture is treated as warning/error message text.
#### `textadept.run.run_commands`
Map of filenames, file extensions, and lexer names to their associated "run"
shell command line strings or functions that return strings.
Command line strings may have the following macros:
+ `%f`: The file's name, including its extension.
+ `%e`: The file's name, excluding its extension.
+ `%d`: The file's directory path.
+ `%p`: The file's full path.
Functions may also return a working directory to operate in. By default, it
is the current file's parent directory.
---
## The `textadept.session` Module
---
Session support for Textadept.
### Fields defined by `textadept.session`
#### `events.SESSION_LOAD` (string)
Emitted when loading a session.
Arguments:
* `session`: Table of session data to load. All handlers will have access
to this same table.
#### `events.SESSION_SAVE` (string)
Emitted when saving a session.
Arguments:
* `session`: Table of session data to save. All handlers will have access
to this same table, and Textadept's default handler reserves the use of
some keys.
Note that functions, userdata, and circular table values cannot be saved.
The latter case is not recognized at all, so beware.
#### `textadept.session.save_on_quit` (bool)
Save the session when quitting.
The default value is `true` unless the user passed the command line switch
`-n` or `--nosession` to Textadept.
### Functions defined by `textadept.session`
#### `textadept.session.load`(*filename*)
Loads session file *filename* or the user-selected session, returning `true`
if a session file was opened and read.
Textadept restores split views, opened buffers, cursor information, recent
files, and bookmarks.
Parameters:
* *`filename`*: Optional absolute path to the session file to load. If `nil`,
the user is prompted for one.
Usage:
* `textadept.session.load(filename)`
Return:
* `true` if the session file was opened and read; `nil` otherwise.
#### `textadept.session.save`(*filename*)
Saves the session to file *filename* or the user-selected file.
Saves split views, opened buffers, cursor information, recent files, and
bookmarks.
Upon quitting, the current session is saved to *filename* again, unless
`textadept.session.save_on_quit` is `false`.
Parameters:
* *`filename`*: Optional absolute path to the session file to save. If `nil`,
the user is prompted for one.
Usage:
* `textadept.session.save(filename)`
---
## The `textadept.snippets` Module
---
Snippets for Textadept.
### Overview
Define snippets in the global `snippets` table in key-value pairs. Each pair
consists of either a string trigger word and its snippet text, or a string
lexer name (from the *lexers/* directory) with a table of trigger words and
snippet texts. When searching for a snippet to insert based on a trigger
word, Textadept considers snippets in the current lexer to have priority,
followed by the ones in the global table. This means if there are two
snippets with the same trigger word, Textadept inserts the one specific to
the current lexer, not the global one.
### Special Sequences
#### `%`*n*`(`*text*`)`
Represents a placeholder, where *n* is an integer and *text* is default
placeholder text. Textadept moves the caret to placeholders in numeric order
each time it calls [`textadept.snippets.insert()`](#textadept.snippets.insert), finishing at either
the "%0" placeholder if it exists or at the end of the snippet. Examples are
snippets['foo'] = 'foobar%1(baz)'
snippets['bar'] = 'start\n\t%0\nend'
#### `%`*n*`{`*list*`}`
Also represents a placeholder (where *n* is an integer), but presents a list
of choices for placeholder text constructed from comma-separated *list*.
Examples are
snippets['op'] = 'operator(%1(1), %2(1), "%3{add,sub,mul,div}")'
#### `%`*n*
Represents a mirror, where *n* is an integer. Mirrors with the same *n* as a
placeholder mirror any user input in the placeholder. If no placeholder
exists for *n*, the first occurrence of that mirror in the snippet becomes
the placeholder, but with no default text. Examples are
snippets['foo'] = '%1(mirror), %1, on the wall'
snippets['q'] = '"%1"'
#### `%`*n*`<`*Lua code*`>`
`%`*n*`[`*Shell code*`]`
Represents a transform, where *n* is an integer that has an associated
placeholder, *Lua code* is arbitrary Lua code, and *Shell code* is arbitrary
Shell code. Textadept executes the code as text is typed into placeholder
*n*. If the transform omits *n*, Textadept executes the transform's code the
moment the editor inserts the snippet.
Textadept runs Lua code in its Lua State and replaces the transform with the
code's return text. The code may use the temporary `text` and `selected_text`
global variables which contain placeholder *n*'s text and the text originally
selected when the snippet was inserted, respectively. An example is
snippets['attr'] = [[
%1(int) %2(foo) = %3;
%1 get%2
() {
return %2;
}
void set%2(%1 value) {
%2 = value;
}
]]
Textadept executes shell code using Lua's [`io.popen()`][] and replaces the
transform with the process' standard output (stdout). The code may use a `%`
character to represent placeholder *n*'s text. An example is
snippets['env'] = '$%1(HOME) = %1[echo $%]'
#### `%%`
Stands for a single '%' since '%' by itself has a special meaning in
snippets.
#### `%(`
`%{`
Stands for a single '(' or '{', respectively, after a `%`*n* mirror.
Otherwise, the mirror would be interpreted as a placeholder or transform.
Note: it is currently not possible to escape a '<' or '[' immediately after
a `%`*n* mirror due to `%<...>` and `%[...]` sequences being interpreted as
code to execute.
#### `\t`
A single unit of indentation based on the buffer's indentation settings
([`buffer.use_tabs`](#buffer.use_tabs) and [`buffer.tab_width`](#buffer.tab_width)).
#### `\n`
A single set of line ending delimiters based on the buffer's end of line mode
([`buffer.eol_mode`](#buffer.eol_mode)).
[`io.popen()`]: https://www.lua.org/manual/5.3/manual.html#pdf-io.popen
### Fields defined by `textadept.snippets`
#### `textadept.snippets.INDIC_PLACEHOLDER` (number)
The snippet placeholder indicator number.
#### `textadept.editing.autocompleters.snippet` (function)
Autocompleter function for snippet trigger words.
### Functions defined by `textadept.snippets`
#### `textadept.snippets.cancel_current`()
Cancels the active snippet, removing all inserted text.
Returns `false` if no snippet is active.
Return:
* `false` if no snippet is active; `nil` otherwise.
#### `textadept.snippets.insert`(*text*)
Inserts snippet text *text* or the snippet assigned to the trigger word
behind the caret.
Otherwise, if a snippet is active, goes to the active snippet's next
placeholder. Returns `false` if no action was taken.
Parameters:
* *`text`*: Optional snippet text to insert. If `nil`, attempts to insert a
new snippet based on the trigger, the word behind caret, and the current
lexer.
Return:
* `false` if no action was taken; `nil` otherwise.
See also:
* [`buffer.word_chars`](#buffer.word_chars)
#### `textadept.snippets.previous`()
Jumps back to the previous snippet placeholder, reverting any changes from
the current one.
Returns `false` if no snippet is active.
Return:
* `false` if no snippet is active; `nil` otherwise.
#### `textadept.snippets.select`()
Prompts the user to select a snippet to insert from a list of global and
language-specific snippets.
### Tables defined by `textadept.snippets`
#### `_G.snippets`
Map of snippet triggers with their snippet text or functions that return such
text, with language-specific snippets tables assigned to a lexer name key.
#### `textadept.snippets.paths`
List of directory paths to look for snippet files in.
Filenames are of the form *lexer.trigger.ext* or *trigger.ext* (*.ext* is an
optional, arbitrary file extension). If the global `snippets` table does not
contain a snippet for a given trigger, this table is consulted for a matching
filename, and the contents of that file is inserted as a snippet.
Note: If a directory has multiple snippets with the same trigger, the snippet
chosen for insertion is not defined and may not be constant.
---
## The `ui` Module
---
Utilities for interacting with Textadept's user interface.
### Fields defined by `ui`
#### `ui.buffer_statusbar_text` (string, Write-only)
The text displayed in the buffer statusbar.
#### `ui.clipboard_text` (string)
The text on the clipboard.
#### `ui.context_menu` (userdata)
The buffer's context menu, a [`ui.menu()`](#ui.menu).
This is a low-level field. You probably want to use the higher-level
[`textadept.menu.context_menu`](#textadept.menu.context_menu).
#### `ui.maximized` (bool)
Whether or not Textadept's window is maximized.
#### `ui.silent_print` (bool)
Whether or not to print messages to buffers silently.
This is not guaranteed to be a constant value, as Textadept may change it
for the editor's own purposes. This flag should be used only in conjunction
with a group of [`ui.print()`](#ui.print) and [`ui._print()`](#ui._print) function calls.
The default value is `false`, and focuses buffers when messages are printed
to them.
#### `ui.statusbar_text` (string, Write-only)
The text displayed in the statusbar.
#### `ui.tab_context_menu` (userdata)
The context menu for the buffer's tab, a [`ui.menu()`](#ui.menu).
This is a low-level field. You probably want to use the higher-level
[`textadept.menu.tab_context_menu`](#textadept.menu.tab_context_menu).
#### `ui.tabs` (bool)
Whether or not to display the tab bar when multiple buffers are open.
The default value is `true`.
#### `ui.title` (string, Write-only)
The title text of Textadept's window.
### Functions defined by `ui`
#### `ui._print`(*buffer\_type, ...*)
Prints the given string messages to the buffer of string type *buffer_type*.
Opens a new buffer for printing messages to if necessary. If the message
buffer is already open in a view, the message is printed to that view.
Otherwise the view is split (unless `ui.tabs` is `true`) and the message
buffer is displayed before being printed to.
Parameters:
* *`buffer_type`*: String type of message buffer.
* *`...`*: Message strings.
Usage:
* `ui._print(_L['[Message Buffer]'], message)`
#### `ui.dialog`(*kind, ...*)
Low-level function for prompting the user with a [gtdialog][] of kind *kind*
with the given string and table arguments, returning a formatted string of
the dialog's output.
You probably want to use the higher-level functions in the [`ui.dialogs`](#ui.dialogs)
module.
Table arguments containing strings are allowed and expanded in place. This is
useful for filtered list dialogs with many items.
[gtdialog]: https://orbitalquark.github.io/gtdialog/manual.html
Parameters:
* *`kind`*: The kind of gtdialog.
* *`...`*: Parameters to the gtdialog.
Return:
* string gtdialog result.
#### `ui.get_split_table`()
Returns a split table that contains Textadept's current split view structure.
This is primarily used in session saving.
Return:
* table of split views. Each split view entry is a table with 4
fields: `1`, `2`, `vertical`, and `size`. `1` and `2` have values of either
nested split view entries or the views themselves; `vertical` is a flag
that indicates if the split is vertical or not; and `size` is the integer
position of the split resizer.
#### `ui.goto_file`(*filename, split, preferred\_view, sloppy*)
Switches to the existing view whose buffer's filename is *filename*.
If no view was found and *split* is `true`, splits the current view in order
to show the requested file. If *split* is `false`, shifts to the next or
*preferred_view* view in order to show the requested file. If *sloppy* is
`true`, requires only the basename of *filename* to match a buffer's
`filename`. If the requested file was not found, it is opened in the desired
view.
Parameters:
* *`filename`*: The filename of the buffer to go to.
* *`split`*: Optional flag that indicates whether or not to open the buffer
in a split view if there is only one view. The default value is `false`.
* *`preferred_view`*: Optional view to open the desired buffer in if the
buffer is not visible in any other view.
* *`sloppy`*: Optional flag that indicates whether or not to not match
*filename* to `buffer.filename` exactly. When `true`, matches *filename* to
only the last part of `buffer.filename` This is useful for run and compile
commands which output relative filenames and paths instead of full ones and
it is likely that the file in question is already open. The default value
is `false`.
#### `ui.goto_view`(*view*)
Shifts to view *view* or the view *view* number of views relative to the
current one.
Emits `VIEW_BEFORE_SWITCH` and `VIEW_AFTER_SWITCH` events.
Parameters:
* *`view`*: A view or relative view number (typically 1 or -1).
See also:
* [`_VIEWS`](#_VIEWS)
* [`events.VIEW_BEFORE_SWITCH`](#events.VIEW_BEFORE_SWITCH)
* [`events.VIEW_AFTER_SWITCH`](#events.VIEW_AFTER_SWITCH)
#### `ui.menu`(*menu\_table*)
Low-level function for creating a menu from table *menu_table* and returning
the userdata.
You probably want to use the higher-level `textadept.menu.menubar`,
`textadept.menu.context_menu`, or `textadept.menu.tab_context_menu` tables.
Emits a `MENU_CLICKED` event when a menu item is selected.
Parameters:
* *`menu_table`*: A table defining the menu. It is an ordered list of tables
with a string menu item, integer menu ID, and optional GDK keycode and
modifier mask. The latter two are used to display key shortcuts in the
menu. '_' characters are treated as a menu mnemonics. If the menu item is
empty, a menu separator item is created. Submenus are just nested
menu-structure tables. Their title text is defined with a `title` key.
Usage:
* `ui.menu{ {'_New', 1}, {'_Open', 2}, {''}, {'_Quit', 4} }`
* `ui.menu{ {'_New', 1, string.byte('n'), 4} } -- 'Ctrl+N'`
See also:
* [`events.MENU_CLICKED`](#events.MENU_CLICKED)
* [`textadept.menu.menubar`](#textadept.menu.menubar)
* [`textadept.menu.context_menu`](#textadept.menu.context_menu)
* [`textadept.menu.tab_context_menu`](#textadept.menu.tab_context_menu)
#### `ui.print`(*...*)
Prints the given string messages to the message buffer.
Opens a new buffer if one has not already been opened for printing messages.
Parameters:
* *`...`*: Message strings.
#### `ui.switch_buffer`(*zorder*)
Prompts the user to select a buffer to switch to.
Buffers are listed in the order they were opened unless `zorder` is `true`,
in which case buffers are listed by their z-order (most recently viewed to
least recently viewed).
Parameters:
* *`zorder`*: Flag that indicates whether or not to list buffers by their
z-order. The default value is `false`.
#### `ui.update`()
Processes pending GTK events, including reading from spawned processes.
This function is primarily used in unit tests.
### Tables defined by `ui`
#### `ui.menubar`
A table of menus defining a menubar. (Write-only).
This is a low-level field. You probably want to use the higher-level
`textadept.menu.menubar`.
See also:
* [`textadept.menu.menubar`](#textadept.menu.menubar)
#### `ui.size`
A table containing the width and height pixel values of Textadept's window.
---
## The `ui.command_entry` Module
---
Textadept's Command Entry.
It supports multiple modes that each have their own functionality (such as
running Lua code and filtering text through shell commands) and history.
### Fields defined by `ui.command_entry`
#### `ui.command_entry.active` (boolean)
Whether or not the command entry is active.
#### `ui.command_entry.height` (number)
The height in pixels of the command entry.
### Functions defined by `ui.command_entry`
#### `ui.command_entry.focus`()
Opens the command entry.
#### `ui.command_entry.run`(*f, keys, lang, height*)
Opens the command entry, subjecting it to any key bindings defined in table
*keys*, highlighting text with lexer name *lang*, and displaying
*height* number of lines at a time, and then when the `Enter` key is pressed,
closes the command entry and calls function *f* (if non-`nil`) with the
command entry's text as an argument.
By default with no arguments given, opens a Lua command entry.
The command entry does not respond to Textadept's default key bindings, but
instead to the key bindings defined in *keys* and in
`ui.command_entry.editing_keys`.
Parameters:
* *`f`*: Optional function to call upon pressing `Enter` in the command
entry, ending the mode. It should accept the command entry text as an
argument.
* *`keys`*: Optional table of key bindings to respond to. This is in
addition to the basic editing and movement keys defined in
`ui.command_entry.editing_keys`.
`Esc` and `Enter` are automatically defined to cancel and finish the
command entry, respectively.
This parameter may be omitted completely.
* *`lang`*: Optional string lexer name to use for command entry text. The
default value is `'text'`.
* *`height`*: Optional number of lines to display in the command entry. The
default value is `1`.
Usage:
* `ui.command_entry.run(ui.print)`
See also:
* [`ui.command_entry.editing_keys`](#ui.command_entry.editing_keys)
### Tables defined by `ui.command_entry`
#### `ui.command_entry.editing_keys`
A metatable with typical platform-specific key bindings for text entries.
This metatable may be used to add basic editing and movement keys to command
entry modes. It is automatically added to command entry modes unless a
metatable was previously set.
Usage:
* `setmetatable(mode_keys, ui.command_entry.editing_keys)`
---
## The `ui.dialogs` Module
---
Provides a set of interactive dialog prompts for user input.
### Functions defined by `ui.dialogs`
#### `ui.dialogs.colorselect`(*options*)
Prompts the user with a color selection dialog defined by dialog options
table *options*, returning the color selected.
If the user canceled the dialog, returns `nil`.
Parameters:
* *`options`*: Table of key-value option pairs for the option select dialog.
* `title`: The dialog's title text.
* `color`: The initially selected color as either a number in "0xBBGGRR"
format, or as a string in "#RRGGBB" format.
* `palette`: The list of colors to show in the dialog's color palette.
Up to 20 colors can be specified as either numbers in "0xBBGGRR" format
or as strings in "#RRGGBB" format. If `true` (no list was given), a
default palette is shown.
* `string_output`: Return the selected color in string "#RRGGBB" format
instead of numeric "0xBBGGRR" format. The default value is `false`.
* `float`: Show the dialog on top of all desktop windows. The default value
is `false`.
Usage:
* `ui.dialogs.colorselect{title = 'Foreground color', color = 0x000000,
palette = {'#000000', 0x0000FF, '#00FF00', 0xFF0000}}`
Return:
* selected color
#### `ui.dialogs.dropdown`(*options*)
Prompts the user with a drop-down item selection dialog defined by dialog
options table *options*, returning the selected button's index along with the
index of the selected item.
If *options*.`string_output` is `true`, returns the selected button's label
along with the selected item's text.
If the dialog closed due to *options*.`exit_onchange`, returns `4` along with
either the selected item's index or its text. If the dialog timed out,
returns `0` or `"timeout"`. If the user canceled the dialog, returns `-1` or
`"delete"`.
Parameters:
* *`options`*: Table of key-value option pairs for the drop-down dialog.
* `title`: The dialog's title text.
* `text`: The dialog's main message text.
* `items`: The list of string items to show in the drop-down.
* `button1`: The right-most button's label. The default value is
`_L['OK']`.
* `button2`: The middle button's label.
* `button3`: The left-most button's label. This option requires `button2`
to be set.
* `exit_onchange`: Close the dialog after selecting a new item. The default
value is `false`.
* `select`: The index of the initially selected list item. The default
value is `1`.
* `string_output`: Return the selected button's label (instead of its
index) and the selected item's text (instead of its index). If no item
was selected, returns the dialog's exit status (instead of its exit
code). The default value is `false`.
* `width`: The dialog's pixel width.
* `height`: The dialog's pixel height.
* `float`: Show the dialog on top of all desktop windows. The default value
is `false`.
* `timeout`: The integer number of seconds the dialog waits for the user to
select a button before timing out. Dialogs do not time out by default.
Usage:
* `ui.dialogs.dropdown{title = 'Select Encoding', width = 200,
items = io.encodings, string_output = true}`
Return:
* selected button or exit code, selected item
#### `ui.dialogs.filesave`(*options*)
Prompts the user with a file save dialog defined by dialog options table
*options*, returning the string file chosen.
If the user canceled the dialog, returns `nil`.
Parameters:
* *`options`*: Table of key-value option pairs for the dialog.
* `title`: The dialog's title text.
* `with_directory`: The initial filesystem directory to show.
* `with_file`: The initially chosen filename. This option requires
`with_directory` to be set.
* `with_extension`: The list of extensions selectable files must have.
* `no_create_directories`: Prevent the user from creating new directories.
The default value is `false`.
Return:
* filename or nil
#### `ui.dialogs.fileselect`(*options*)
Prompts the user with a file selection dialog defined by dialog options
table *options*, returning the string file selected.
If *options*.`select_multiple` is `true`, returns the list of files selected.
If the user canceled the dialog, returns `nil`.
Parameters:
* *`options`*: Table of key-value option pairs for the dialog.
* `title`: The dialog's title text.
* `with_directory`: The initial filesystem directory to show.
* `with_file`: The initially selected filename. This option requires
`with_directory` to be set.
* `with_extension`: The list of extensions selectable files must have.
* `select_multiple`: Allow the user to select multiple files. The default
value is `false`.
* `select_only_directories`: Only allow the user to select directories. The
default value is `false`.
Usage:
* `ui.dialogs.fileselect{title = 'Open C File', with_directory = _HOME,
with_extension = {'c', 'h'}, select_multiple = true}`
Return:
* filename, list of filenames, or nil
#### `ui.dialogs.filteredlist`(*options*)
Prompts the user with a filtered list item selection dialog defined by dialog
options table *options*, returning the selected button's index along with the
index or indices of the selected item or items (depending on whether or not
*options*.`select_multiple` is `true`).
If *options*.`string_output` is `true`, returns the selected button's label
along with the text of the selected item or items.
If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
dialog, returns `-1` or `"delete"`.
Spaces in the filter text are treated as wildcards.
Parameters:
* *`options`*: Table of key-value option pairs for the filtered list dialog.
* `title`: The dialog's title text.
* `informative_text`: The dialog's main message text.
* `text`: The dialog's initial input text.
* `columns`: The list of string column names for list rows.
* `items`: The list of string items to show in the filtered list.
* `button1`: The right-most button's label. The default value is
`_L['OK']`.
* `button2`: The middle button's label.
* `button3`: The left-most button's label. This option requires `button2`
to be set.
* `select_multiple`: Allow the user to select multiple items. The default
value is `false`.
* `search_column`: The column number to filter the input text against. The
default value is `1`. This option requires `columns` to be set and
contain at least *n* column names.
* `output_column`: The column number to use for `string_output`. The
default value is `1`. This option requires `columns` to be set and
contain at least *n* column names.
* `string_output`: Return the selected button's label (instead of its
index) and the selected item's text (instead of its index). If no item
was selected, returns the dialog's exit status (instead of its exit
code). The default value is `false`.
* `width`: The dialog's pixel width. The default width stretches nearly the
width of Textadept's window.
* `height`: The dialog's pixel height.
* `float`: Show the dialog on top of all desktop windows. The default value
is `false`.
* `timeout`: The integer number of seconds the dialog waits for the user to
select a button before timing out. Dialogs do not time out by default.
Usage:
* `ui.dialogs.filteredlist{title = 'Title', columns = {'Foo', 'Bar'},
items = {'a', 'b', 'c', 'd'}}`
Return:
* selected button or exit code, selected item or list of selected items
#### `ui.dialogs.fontselect`(*options*)
Prompts the user with a font selection dialog defined by dialog options
table *options*, returning the font selected (including style and size).
If the user canceled the dialog, returns `nil`.
Parameters:
* *`options`*: Table of key-value option pairs for the option select dialog.
* `title`: The dialog's title text.
* `text`: The font preview text.
* `font_name`: The initially selected font name.
* `font_size`: The initially selected font size. The default value is `12`.
* `font_style`: The initially selected font style. The available options
are `"regular"`, `"bold"`, `"italic"`, and `"bold italic"`. The default
value is `"regular"`.
* `float`: Show the dialog on top of all desktop windows. The default value
is `false`.
Usage:
* `ui.dialogs.fontselect{title = 'Font', font_name = 'Monospace',
font_size = 10}`
Return:
* selected font, including style and size
#### `ui.dialogs.inputbox`(*options*)
Prompts the user with an inputbox dialog defined by dialog options table
*options*, returning the selected button's index along with the user's
input text (the latter as a string or table, depending on the type of
*options*.`informative_text`).
If *options*.`string_output` is `true`, returns the selected button's label
along with the user's input text.
If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
dialog, returns `-1` or `"delete"`.
Parameters:
* *`options`*: Table of key-value option pairs for the inputbox.
* `title`: The dialog's title text.
* `informative_text`: The dialog's main message text. If the value is a
table, the first table value is the main message text and any subsequent
values are used as the labels for multiple entry boxes. Providing a
single label has no effect.
* `text`: The dialog's initial input text. If the value is a table, the
table values are used to populate the multiple entry boxes defined by
`informative_text`.
* `button1`: The right-most button's label. The default value is
`_L['OK']`.
* `button2`: The middle button's label.
* `button3`: The left-most button's label. This option requires `button2`
to be set.
* `string_output`: Return the selected button's label (instead of its
index) or the dialog's exit status instead of the button's index (instead
of its exit code). The default value is `false`.
* `width`: The dialog's pixel width.
* `height`: The dialog's pixel height.
* `float`: Show the dialog on top of all desktop windows. The default value
is `false`.
* `timeout`: The integer number of seconds the dialog waits for the user to
select a button before timing out. Dialogs do not time out by default.
Usage:
* `ui.dialogs.inputbox{title = 'Goto Line', informative_text = 'Line:',
text = '1'}`
Return:
* selected button or exit code, input text
#### `ui.dialogs.msgbox`(*options*)
Prompts the user with a generic message box dialog defined by dialog options
table *options*, returning the selected button's index.
If *options*.`string_output` is `true`, returns the selected button's label.
If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
dialog, returns `-1` or `"delete"`.
Parameters:
* *`options`*: Table of key-value option pairs for the message box.
* `title`: The dialog's title text.
* `text`: The dialog's main message text.
* `informative_text`: The dialog's extra informative text.
* `icon`: The dialog's GTK stock icon name. Examples are
"gtk-dialog-error", "gtk-dialog-info", "gtk-dialog-question", and
"gtk-dialog-warning". The dialog does not display an icon by default.
* `icon_file`: The dialog's icon file path. This option has no effect when
`icon` is set.
* `button1`: The right-most button's label. The default value is
`_L['OK']`.
* `button2`: The middle button's label.
* `button3`: The left-most button's label. This option requires `button2`
to be set.
* `string_output`: Return the selected button's label (instead of its
index) or the dialog's exit status instead of the button's index (instead
of its exit code). The default value is `false`.
* `width`: The dialog's pixel width.
* `height`: The dialog's pixel height.
* `float`: Show the dialog on top of all desktop windows. The default value
is `false`.
* `timeout`: The integer number of seconds the dialog waits for the user to
select a button before timing out. Dialogs do not time out by default.
Usage:
* `ui.dialogs.msgbox{title = 'EOL Mode', text = 'Which EOL?',
icon = 'gtk-dialog-question', button1 = 'CRLF', button2 = 'CR',
button3 = 'LF'}`
Return:
* selected button or exit code
#### `ui.dialogs.ok_msgbox`(*options*)
Prompts the user with a generic message box dialog defined by dialog options
table *options* and with localized "Ok" and "Cancel" buttons, returning the
selected button's index.
If *options*.`string_output` is `true`, returns the selected button's label.
If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
dialog, returns `-1` or `"delete"`.
Parameters:
* *`options`*: Table of key-value option pairs for the message box.
* `title`: The dialog's title text.
* `text`: The dialog's main message text.
* `informative_text`: The dialog's extra informative text.
* `icon`: The dialog's GTK stock icon name. Examples are
"gtk-dialog-error", "gtk-dialog-info", "gtk-dialog-question", and
"gtk-dialog-warning". The dialog does not display an icon by default.
* `icon_file`: The dialog's icon file path. This option has no effect when
`icon` is set.
* `no_cancel`: Do not display the "Cancel" button. The default value is
`false`.
* `string_output`: Return the selected button's label (instead of its
index) or the dialog's exit status instead of the button's index (instead
of its exit code). The default value is `false`.
* `width`: The dialog's pixel width.
* `height`: The dialog's pixel height.
* `float`: Show the dialog on top of all desktop windows. The default value
is `false`.
* `timeout`: The integer number of seconds the dialog waits for the user to
select a button before timing out. Dialogs do not time out by default.
Return:
* selected button or exit code
#### `ui.dialogs.optionselect`(*options*)
Prompts the user with an option selection dialog defined by dialog options
table *options*, returning the selected button's index along with the indices
of the selected options.
If *options*.`string_output` is `true`, returns the selected button's label
along with the text of the selected options.
If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
dialog, returns `-1` or `"delete"`.
Parameters:
* *`options`*: Table of key-value option pairs for the option select dialog.
* `title`: The dialog's title text.
* `text`: The dialog's main message text.
* `items`: The list of string options to show in the option group.
* `button1`: The right-most button's label. The default value is
`_L['OK']`.
* `button2`: The middle button's label.
* `button3`: The left-most button's label. This option requires `button2`
to be set.
* `select`: The indices of initially selected options.
* `string_output`: Return the selected button's label or the dialog's exit
status along with the selected options' text instead of the button's
index or the dialog's exit code along with the options' indices. The
default value is `false`.
* `width`: The dialog's pixel width.
* `height`: The dialog's pixel height.
* `float`: Show the dialog on top of all desktop windows. The default value
is `false`.
* `timeout`: The integer number of seconds the dialog waits for the user to
select a button before timing out. Dialogs do not time out by default.
Usage:
* `ui.dialogs.optionselect{title = 'Language',
informative_text = 'Check the languages you understand',
items = {'English', 'Romanian'}, select = 1, string_output = true}`
Return:
* selected button or exit code, list of selected options
#### `ui.dialogs.progressbar`(*options, f*)
Displays a progressbar dialog, defined by dialog options table *options*,
that receives updates from function *f*.
Returns "stopped" if *options*.`stoppable` is `true` and the user clicked the
"Stop" button. Otherwise, returns `nil`.
Parameters:
* *`options`*: Table of key-value option pairs for the progressbar dialog.
* `title`: The dialog's title text.
* `percent`: The initial progressbar percentage between 0 and 100.
* `text`: The initial progressbar display text (GTK only).
* `indeterminate`: Show the progress bar as "busy", with no percentage
updates.
* `stoppable`: Show the "Stop" button.
* `width`: The dialog's pixel width.
* `height`: The dialog's pixel height.
* *`f`*: Function repeatedly called to do work and provide progress updates.
The function is called without arguments and must return either `nil`,
which indicates work is complete, or a progress percentage number in the
range 0-100 and an optional string to display (GTK only). If the text is
either "stop disable" or "stop enable" and *options*.`stoppable` is `true`,
the "Stop" button is disabled or enabled, respectively.
Usage:
* `ui.dialogs.progressbar({stoppable = true},
function() if work() then return percent, status else return nil end end)`
Return:
* nil or "stopped"
#### `ui.dialogs.secure_inputbox`(*options*)
Prompts the user with a masked inputbox dialog defined by dialog options
table *options*, returning the selected button's index along with the user's
input text (the latter as a string or table, depending on the type of
*options*.`informative_text`).
If *options*.`string_output` is `true`, returns the selected button's label
along with the user's input text.
If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
dialog, returns `-1` or `"delete"`.
Parameters:
* *`options`*: Table of key-value option pairs for the inputbox.
* `title`: The dialog's title text.
* `informative_text`: The dialog's main message text. If the value is a
table, the first table value is the main message text and any subsequent
values are used as the labels for multiple entry boxes. Providing a
single label has no effect.
* `text`: The dialog's initial input text. If the value is a table, the
table values are used to populate the multiple entry boxes defined by
`informative_text`.
* `button1`: The right-most button's label. The default value is
`_L['OK']`.
* `button2`: The middle button's label.
* `button3`: The left-most button's label. This option requires `button2`
to be set.
* `string_output`: Return the selected button's label (instead of its
index) or the dialog's exit status instead of the button's index (instead
of its exit code). The default value is `false`.
* `width`: The dialog's pixel width.
* `height`: The dialog's pixel height.
* `float`: Show the dialog on top of all desktop windows. The default value
is `false`.
* `timeout`: The integer number of seconds the dialog waits for the user to
select a button before timing out. Dialogs do not time out by default.
Return:
* selected button or exit code, input text
#### `ui.dialogs.secure_standard_inputbox`(*options*)
Prompts the user with a masked inputbox dialog defined by dialog options
table *options* and with localized "Ok" and "Cancel" buttons, returning the
selected button's index along with the user's input text (the latter as a
string or table, depending on the type of *options*.`informative_text`).
If *options*.`string_output` is `true`, returns the selected button's label
along with the user's input text.
If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
dialog, returns `-1` or `"delete"`.
Parameters:
* *`options`*: Table of key-value option pairs for the inputbox.
* `title`: The dialog's title text.
* `informative_text`: The dialog's main message text. If the value is a
table, the first table value is the main message text and any subsequent
values are used as the labels for multiple entry boxes. Providing a
single label has no effect.
* `text`: The dialog's initial input text. If the value is a table, the
table values are used to populate the multiple entry boxes defined by
`informative_text`.
* `no_cancel`: Do not display the "Cancel" button. The default value is
`false`.
* `string_output`: Return the selected button's label (instead of its
index) or the dialog's exit status instead of the button's index (instead
of its exit code). The default value is `false`.
* `width`: The dialog's pixel width.
* `height`: The dialog's pixel height.
* `float`: Show the dialog on top of all desktop windows. The default value
is `false`.
* `timeout`: The integer number of seconds the dialog waits for the user to
select a button before timing out. Dialogs do not time out by default.
Return:
* selected button or exit code, input text
#### `ui.dialogs.standard_dropdown`(*options*)
Prompts the user with a drop-down item selection dialog defined by dialog
options table *options* and with localized "Ok" and "Cancel" buttons,
returning the selected button's index along with the selected item's index.
If *options*.`string_output` is `true`, returns the selected button's label
along with the selected item's text.
If the dialog closed due to *options*.`exit_onchange`, returns `4` along with
either the selected item's index or its text. If the dialog timed out,
returns `0` or `"timeout"`. If the user canceled the dialog, returns `-1` or
`"delete"`.
Parameters:
* *`options`*: Table of key-value option pairs for the drop-down dialog.
* `title`: The dialog's title text.
* `text`: The dialog's main message text.
* `items`: The list of string items to show in the drop-down.
* `no_cancel`: Do not display the "Cancel" button. The default value is
`false`.
* `exit_onchange`: Close the dialog after selecting a new item. The default
value is `false`.
* `select`: The index of the initially selected list item. The default
value is `1`.
* `string_output`: Return the selected button's label (instead of its
index) and the selected item's text (instead of its index). If no item
was selected, returns the dialog's exit status (instead of its exit
code). The default value is `false`.
* `width`: The dialog's pixel width.
* `height`: The dialog's pixel height.
* `float`: Show the dialog on top of all desktop windows. The default value
is `false`.
* `timeout`: The integer number of seconds the dialog waits for the user to
select a button before timing out. Dialogs do not time out by default.
Return:
* selected button or exit code, selected item
#### `ui.dialogs.standard_inputbox`(*options*)
Prompts the user with an inputbox dialog defined by dialog options table
*options* and with localized "Ok" and "Cancel" buttons, returning the
selected button's index along with the user's input text (the latter as a
string or table, depending on the type of *options*.`informative_text`).
If *options*.`string_output` is `true`, returns the selected button's label
along with the user's input text.
If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
dialog, returns `-1` or `"delete"`.
Parameters:
* *`options`*: Table of key-value option pairs for the inputbox.
* `title`: The dialog's title text.
* `informative_text`: The dialog's main message text. If the value is a
table, the first table value is the main message text and any subsequent
values are used as the labels for multiple entry boxes. Providing a
single label has no effect.
* `text`: The dialog's initial input text. If the value is a table, the
table values are used to populate the multiple entry boxes defined by
`informative_text`.
* `no_cancel`: Do not display the "Cancel" button. The default value is
`false`.
* `string_output`: Return the selected button's label (instead of its
index) or the dialog's exit status instead of the button's index (instead
of its exit code). The default value is `false`.
* `width`: The dialog's pixel width.
* `height`: The dialog's pixel height.
* `float`: Show the dialog on top of all desktop windows. The default value
is `false`.
* `timeout`: The integer number of seconds the dialog waits for the user to
select a button before timing out. Dialogs do not time out by default.
Return:
* selected button or exit code, input text
#### `ui.dialogs.textbox`(*options*)
Prompts the user with a multiple-line textbox dialog defined by dialog
options table *options*, returning the selected button's index.
If *options*.`string_output` is `true`, returns the selected button's label.
If *options*.`editable` is `true`, also returns the textbox's text. If the
dialog timed out, returns `0` or `"timeout"`. If the user canceled the
dialog, returns `-1` or `"delete"`.
Parameters:
* *`options`*: Table of key-value option pairs for the dialog.
* `title`: The dialog's title text.
* `informative_text`: The dialog's main message text.
* `text`: The dialog's initial textbox text.
* `text_from_file`: The filename whose contents are loaded into the
textbox. This option has no effect when `text` is given.
* `button1`: The right-most button's label. The default value is
`_L['OK']`.
* `button2`: The middle button's label.
* `button3`: The left-most button's label. This option requires `button2`
to be set.
* `editable`: Allows the user to edit the textbox's text. The default value
is `false`.
* `focus_textbox`: Focus the textbox instead of the buttons. The default
value is `false`.
* `scroll_to`: Where to scroll the textbox's text.
The available values are `"top"` and `"bottom"`. The default value is
`"top"`.
* `selected`: Select all of the textbox's text. The default value is
`false`.
* `monospaced_font`: Use a monospaced font in the textbox instead of a
proportional one. The default value is `false`.
* `string_output`: Return the selected button's label (instead of its
index) or the dialog's exit status instead of the button's index (instead
of its exit code). The default value is `false`.
* `width`: The dialog's pixel width.
* `height`: The dialog's pixel height.
* `float`: Show the dialog on top of all desktop windows. The default value
is `false`.
* `timeout`: The integer number of seconds the dialog waits for the user to
select a button before timing out. Dialogs do not time out by default.
Usage:
* `ui.dialogs.textbox{title = 'License Agreement',
informative_text = 'You agree to:', text_from_file = _HOME..'/LICENSE'}`
Return:
* selected button or exit code, textbox text
#### `ui.dialogs.yesno_msgbox`(*options*)
Prompts the user with a generic message box dialog defined by dialog options
table *options* and with localized "Yes", "No", and "Cancel" buttons,
returning the selected button's index.
If *options*.`string_output` is `true`, returns the selected button's label.
If the dialog timed out, returns `0` or `"timeout"`. If the user canceled the
dialog, returns `-1` or `"delete"`.
Parameters:
* *`options`*: Table of key-value option pairs for the message box.
* `title`: The dialog's title text.
* `text`: The dialog's main message text.
* `informative_text`: The dialog's extra informative text.
* `icon`: The dialog's GTK stock icon name. Examples are
"gtk-dialog-error", "gtk-dialog-info", "gtk-dialog-question", and
"gtk-dialog-warning". The dialog does not display an icon by default.
* `icon_file`: The dialog's icon file path. This option has no effect when
`icon` is set.
* `no_cancel`: Do not display the "Cancel" button. The default value is
`false`.
* `string_output`: Return the selected button's label (instead of its
index) or the dialog's exit status instead of the button's index (instead
of its exit code). The default value is `false`.
* `width`: The dialog's pixel width.
* `height`: The dialog's pixel height.
* `float`: Show the dialog on top of all desktop windows. The default value
is `false`.
* `timeout`: The integer number of seconds the dialog waits for the user to
select a button before timing out. Dialogs do not time out by default.
Return:
* selected button or exit code
---
## The `ui.find` Module
---
Textadept's Find & Replace pane.
### Fields defined by `ui.find`
#### `ui.find.INDIC_FIND` (number)
The find results highlight indicator number.
#### `events.FIND_RESULT_FOUND` (string)
Emitted when a result is found. It is selected and has been scrolled into
view.
#### `events.FIND_WRAPPED` (string)
Emitted when a text search wraps (passes through the beginning of the
buffer), 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.
#### `ui.find.active` (boolean)
Whether or not the Find & Replace pane is active.
#### `ui.find.find_entry_text` (string)
The text in the "Find" entry.
#### `ui.find.find_label_text` (string, Write-only)
The text of the "Find" label.
This is primarily used for localization.
#### `ui.find.find_next_button_text` (string, Write-only)
The text of the "Find Next" button.
This is primarily used for localization.
#### `ui.find.find_prev_button_text` (string, Write-only)
The text of the "Find Prev" button.
This is primarily used for localization.
#### `ui.find.highlight_all_matches` (boolean)
Whether or not to highlight all occurrences of found text in the current
buffer.
The default value is `false`.
#### `ui.find.in_files` (bool)
Find search text in a directory of files.
The default value is `false`.
#### `ui.find.in_files_label_text` (string, Write-only)
The text of the "In files" label.
This is primarily used for localization.
#### `ui.find.incremental` (bool)
Find search text incrementally as it is typed.
The default value is `false`.
#### `ui.find.match_case` (bool)
Match search text case sensitively.
The default value is `false`.
#### `ui.find.match_case_label_text` (string, Write-only)
The text of the "Match case" label.
This is primarily used for localization.
#### `ui.find.regex` (bool)
Interpret search text as a Regular Expression.
The default value is `false`.
#### `ui.find.regex_label_text` (string, Write-only)
The text of the "Regex" label.
This is primarily used for localization.
#### `ui.find.replace_all_button_text` (string, Write-only)
The text of the "Replace All" button.
This is primarily used for localization.
#### `ui.find.replace_button_text` (string, Write-only)
The text of the "Replace" button.
This is primarily used for localization.
#### `ui.find.replace_entry_text` (string)
The text in the "Replace" entry.
When searching for text in a directory of files, this is the current file
and directory filter.
#### `ui.find.replace_label_text` (string, Write-only)
The text of the "Replace" label.
This is primarily used for localization.
#### `ui.find.whole_word` (bool)
Match search text only when it is surrounded by non-word characters in
searches.
The default value is `false`.
#### `ui.find.whole_word_label_text` (string, Write-only)
The text of the "Whole word" label.
This is primarily used for localization.
### Functions defined by `ui.find`
#### `ui.find.find_in_files`(*dir, filter*)
Searches directory *dir* or the user-specified directory for files that match
search text and search options (subject to optional filter *filter*), and
prints the results to a buffer titled "Files Found", highlighting found text.
Use the `find_entry_text`, `match_case`, `whole_word`, and `regex` fields to
set the search text and option flags, respectively.
A filter determines which files to search in, with the default filter being
`ui.find.find_in_files_filters[dir]` (if it exists) or `lfs.default_filter`.
A filter consists of Lua patterns that match file and directory paths to
include or exclude. Patterns are inclusive by default. Exclusive patterns
begin with a '!'. If no inclusive patterns are given, any filename is
initially considered. As a convenience, file extensions can be specified
literally instead of as a Lua pattern (e.g. '.lua' vs. '%.lua$'), and '/'
also matches the Windows directory separator ('[/\\]' is not needed).
If *filter* is `nil`, the filter from the `ui.find.find_in_files_filters`
table for *dir* is used. If that filter does not exist, `lfs.default_filter`
is used.
Parameters:
* *`dir`*: Optional directory path to search. If `nil`, the user is prompted
for one.
* *`filter`*: Optional filter for files and directories to exclude. The
default value is `lfs.default_filter` unless a filter for *dir* is defined
in `ui.find.find_in_files_filters`.
See also:
* [`ui.find.find_in_files_filters`](#ui.find.find_in_files_filters)
#### `ui.find.find_next`()
Mimics pressing the "Find Next" button.
#### `ui.find.find_prev`()
Mimics pressing the "Find Prev" button.
#### `ui.find.focus`(*options*)
Displays and focuses the Find & Replace Pane.
Parameters:
* *`options`*: Optional table of options to initially set.
#### `ui.find.goto_file_found`(*line\_num, next*)
Jumps to the source of the find in files search result on line number
*line_num* in the buffer titled "Files Found" or, if *line_num* is `nil`,
jumps to the next or previous search result, depending on boolean *next*.
Parameters:
* *`line_num`*: Optional line number in the files found buffer that contains
the search result to go to. This parameter may be omitted completely.
* *`next`*: Optional flag indicating whether to go to the next search result
or the previous one. Only applicable when *line_num* is `nil`.
#### `ui.find.replace`()
Mimics pressing the "Replace" button.
#### `ui.find.replace_all`()
Mimics pressing the "Replace All" button.
### Tables defined by `ui.find`
#### `ui.find.find_in_files_filters`
Map of directory paths to filters used in `ui.find.find_in_files()`.
This table is updated when the user manually specifies a filter in the
"Filter" entry during an "In files" search.
See also:
* [`ui.find.find_in_files`](#ui.find.find_in_files)
---
## The `view` Module
---
A Textadept view object.
Constants are documented in the fields they apply to.
While you can work with individual view instances, it is often useful to work
with just the global one.
Many of these functions and fields are derived from view-specific
functionality of the Scintilla editing component, and additional information
can be found on the
[Scintilla website](https://scintilla.org/ScintillaDoc.html).
Note that with regard to Scintilla-specific functionality, this API is a
_suggestion_, not a hard requirement. All of that functionality also exists
in [`buffer`](#buffer), even if undocumented.
Any view fields set on startup (e.g. in *~/.textadept/init.lua*) will be the
default, initial values for all views.
### Fields defined by `view`
#### `view.ALPHA_NOALPHA` (number, Read-only)
#### `view.ALPHA_OPAQUE` (number, Read-only)
#### `view.ALPHA_TRANSPARENT` (number, Read-only)
#### `view.ANNOTATION_BOXED` (number, Read-only)
#### `view.ANNOTATION_HIDDEN` (number, Read-only)
#### `view.ANNOTATION_INDENTED` (number, Read-only)
#### `view.ANNOTATION_STANDARD` (number, Read-only)
#### `view.CARETSTYLE_BLOCK` (number, Read-only)
#### `view.CARETSTYLE_INVISIBLE` (number, Read-only)
#### `view.CARETSTYLE_LINE` (number, Read-only)
#### `view.CARET_EVEN` (number, Read-only)
#### `view.CARET_JUMPS` (number, Read-only)
#### `view.CARET_SLOP` (number, Read-only)
#### `view.CARET_STRICT` (number, Read-only)
#### `view.CASE_CAMEL` (number, Read-only)
#### `view.CASE_LOWER` (number, Read-only)
#### `view.CASE_MIXED` (number, Read-only)
#### `view.CASE_UPPER` (number, Read-only)
#### `view.CURSORARROW` (number, Read-only)
#### `view.CURSORNORMAL` (number, Read-only)
#### `view.CURSORREVERSEARROW` (number, Read-only)
#### `view.CURSORWAIT` (number, Read-only)
#### `view.EDGE_BACKGROUND` (number, Read-only)
#### `view.EDGE_LINE` (number, Read-only)
#### `view.EDGE_MULTILINE` (number, Read-only)
#### `view.EDGE_NONE` (number, Read-only)
#### `view.FOLDACTION_CONTRACT` (number, Read-only)
#### `view.FOLDACTION_EXPAND` (number, Read-only)
#### `view.FOLDACTION_TOGGLE` (number, Read-only)
#### `view.FOLDDISPLAYTEXT_BOXED` (number, Read-only)
#### `view.FOLDDISPLAYTEXT_HIDDEN` (number, Read-only)
#### `view.FOLDDISPLAYTEXT_STANDARD` (number, Read-only)
#### `view.FOLDFLAG_LEVELNUMBERS` (number, Read-only)
#### `view.FOLDFLAG_LINEAFTER_CONTRACTED` (number, Read-only)
#### `view.FOLDFLAG_LINEAFTER_EXPANDED` (number, Read-only)
#### `view.FOLDFLAG_LINEBEFORE_CONTRACTED` (number, Read-only)
#### `view.FOLDFLAG_LINEBEFORE_EXPANDED` (number, Read-only)
#### `view.FOLDFLAG_LINESTATE` (number, Read-only)
#### `view.INDIC_BOX` (number, Read-only)
#### `view.INDIC_COMPOSITIONTHICK` (number, Read-only)
#### `view.INDIC_COMPOSITIONTHIN` (number, Read-only)
#### `view.INDIC_DASH` (number, Read-only)
#### `view.INDIC_DIAGONAL` (number, Read-only)
#### `view.INDIC_DOTBOX` (number, Read-only)
#### `view.INDIC_DOTS` (number, Read-only)
#### `view.INDIC_FULLBOX` (number, Read-only)
#### `view.INDIC_GRADIENT` (number, Read-only)
#### `view.INDIC_GRADIENTCENTER` (number, Read-only)
#### `view.INDIC_HIDDEN` (number, Read-only)
#### `view.INDIC_PLAIN` (number, Read-only)
#### `view.INDIC_POINT` (number, Read-only)
#### `view.INDIC_POINTCHARACTER` (number, Read-only)
#### `view.INDIC_ROUNDBOX` (number, Read-only)
#### `view.INDIC_SQUIGGLE` (number, Read-only)
#### `view.INDIC_SQUIGGLELOW` (number, Read-only)
#### `view.INDIC_SQUIGGLEPIXMAP` (number, Read-only)
#### `view.INDIC_STRAIGHTBOX` (number, Read-only)
#### `view.INDIC_STRIKE` (number, Read-only)
#### `view.INDIC_TEXTFORE` (number, Read-only)
#### `view.INDIC_TT` (number, Read-only)
#### `view.IV_LOOKBOTH` (number, Read-only)
#### `view.IV_LOOKFORWARD` (number, Read-only)
#### `view.IV_NONE` (number, Read-only)
#### `view.IV_REAL` (number, Read-only)
#### `view.MARGINOPTION_NONE` (number, Read-only)
#### `view.MARGINOPTION_SUBLINESELECT` (number, Read-only)
#### `view.MARGIN_BACK` (number, Read-only)
#### `view.MARGIN_COLOR` (number, Read-only)
#### `view.MARGIN_FORE` (number, Read-only)
#### `view.MARGIN_NUMBER` (number, Read-only)
#### `view.MARGIN_RTEXT` (number, Read-only)
#### `view.MARGIN_SYMBOL` (number, Read-only)
#### `view.MARGIN_TEXT` (number, Read-only)
#### `view.MARK_ARROW` (number, Read-only)
#### `view.MARK_ARROWDOWN` (number, Read-only)
#### `view.MARK_ARROWS` (number, Read-only)
#### `view.MARK_BACKGROUND` (number, Read-only)
#### `view.MARK_BOOKMARK` (number, Read-only)
#### `view.MARK_BOXMINUS` (number, Read-only)
#### `view.MARK_BOXMINUSCONNECTED` (number, Read-only)
#### `view.MARK_BOXPLUS` (number, Read-only)
#### `view.MARK_BOXPLUSCONNECTED` (number, Read-only)
#### `view.MARK_CHARACTER` (number, Read-only)
#### `view.MARK_CIRCLE` (number, Read-only)
#### `view.MARK_CIRCLEMINUS` (number, Read-only)
#### `view.MARK_CIRCLEMINUSCONNECTED` (number, Read-only)
#### `view.MARK_CIRCLEPLUS` (number, Read-only)
#### `view.MARK_CIRCLEPLUSCONNECTED` (number, Read-only)
#### `view.MARK_DOTDOTDOT` (number, Read-only)
#### `view.MARK_EMPTY` (number, Read-only)
#### `view.MARK_FULLRECT` (number, Read-only)
#### `view.MARK_LCORNER` (number, Read-only)
#### `view.MARK_LCORNERCURVE` (number, Read-only)
#### `view.MARK_LEFTRECT` (number, Read-only)
#### `view.MARK_MINUS` (number, Read-only)
#### `view.MARK_PIXMAP` (number, Read-only)
#### `view.MARK_PLUS` (number, Read-only)
#### `view.MARK_RGBAIMAGE` (number, Read-only)
#### `view.MARK_ROUNDRECT` (number, Read-only)
#### `view.MARK_SHORTARROW` (number, Read-only)
#### `view.MARK_SMALLRECT` (number, Read-only)
#### `view.MARK_TCORNER` (number, Read-only)
#### `view.MARK_TCORNERCURVE` (number, Read-only)
#### `view.MARK_UNDERLINE` (number, Read-only)
#### `view.MARK_VERTICALBOOKMARK` (number, Read-only)
#### `view.MARK_VLINE` (number, Read-only)
#### `view.MASK_FOLDERS` (number, Read-only)
#### `view.MOD_ALT` (number, Read-only)
#### `view.MOD_CTRL` (number, Read-only)
#### `view.MOD_META` (number, Read-only)
#### `view.MOD_SHIFT` (number, Read-only)
#### `view.MOD_SUPER` (number, Read-only)
#### `view.MOUSE_DRAG` (number, Read-only)
#### `view.MOUSE_PRESS` (number, Read-only)
#### `view.MOUSE_RELEASE` (number, Read-only)
#### `view.STYLE_BRACEBAD` (number, Read-only)
#### `view.STYLE_BRACELIGHT` (number, Read-only)
#### `view.STYLE_CALLTIP` (number, Read-only)
#### `view.STYLE_CONTROLCHAR` (number, Read-only)
#### `view.STYLE_DEFAULT` (number, Read-only)
#### `view.STYLE_FOLDDISPLAYTEXT` (number, Read-only)
#### `view.STYLE_INDENTGUIDE` (number, Read-only)
#### `view.STYLE_LINENUMBER` (number, Read-only)
#### `view.STYLE_MAX` (number, Read-only)
#### `view.TD_LONGARROW` (number, Read-only)
#### `view.TD_STRIKEOUT` (number, Read-only)
#### `view.TIME_FOREVER` (number, Read-only)
#### `view.UPDATE_H_SCROLL` (number, Read-only)
#### `view.UPDATE_V_SCROLL` (number, Read-only)
#### `view.VISIBLE_SLOP` (number, Read-only)
#### `view.VISIBLE_STRICT` (number, Read-only)
#### `view.WRAPINDENT_DEEPINDENT` (number, Read-only)
#### `view.WRAPINDENT_FIXED` (number, Read-only)
#### `view.WRAPINDENT_INDENT` (number, Read-only)
#### `view.WRAPINDENT_SAME` (number, Read-only)
#### `view.WRAPVISUALFLAGLOC_DEFAULT` (number, Read-only)
#### `view.WRAPVISUALFLAGLOC_END_BY_TEXT` (number, Read-only)
#### `view.WRAPVISUALFLAGLOC_START_BY_TEXT` (number, Read-only)
#### `view.WRAPVISUALFLAG_END` (number, Read-only)
#### `view.WRAPVISUALFLAG_MARGIN` (number, Read-only)
#### `view.WRAPVISUALFLAG_NONE` (number, Read-only)
#### `view.WRAPVISUALFLAG_START` (number, Read-only)
#### `view.WRAP_CHAR` (number, Read-only)
#### `view.WRAP_NONE` (number, Read-only)
#### `view.WRAP_WHITESPACE` (number, Read-only)
#### `view.WRAP_WORD` (number, Read-only)
#### `view.WS_INVISIBLE` (number, Read-only)
#### `view.WS_VISIBLEAFTERINDENT` (number, Read-only)
#### `view.WS_VISIBLEALWAYS` (number, Read-only)
#### `view.WS_VISIBLEONLYININDENT` (number, Read-only)
#### `view.additional_caret_fore` (number)
The foreground color, in "0xBBGGRR" format, of additional carets.
#### `view.additional_carets_blink` (bool)
Allow additional carets to blink.
The default value is `true`.
#### `view.additional_carets_visible` (bool)
Display additional carets.
The default value is `true`.
#### `view.additional_sel_alpha` (number)
The alpha value, ranging from `0` (transparent) to `255` (opaque), of
additional selections.
The default value is `view.ALPHA_NOALPHA`, for no alpha.
#### `view.additional_sel_back` (number, Write-only)
The background color, in "0xBBGGRR" format, of additional selections.
This field has no effect when calling `view:set_sel_back(false, ...)`.
#### `view.additional_sel_fore` (number, Write-only)
The foreground color, in "0xBBGGRR" format, of additional selections.
This field has no effect when calling `view:set_sel_fore(false, ...)`.
#### `view.all_lines_visible` (bool, Read-only)
Whether or not all lines are visible.
#### `view.annotation_visible` (number)
The annotation visibility mode.
* `view.ANNOTATION_HIDDEN`
Annotations are invisible.
* `view.ANNOTATION_STANDARD`
Draw annotations left-justified with no decoration.
* `view.ANNOTATION_BOXED`
Indent annotations to match the annotated text and outline them with a
box.
* `view.ANNOTATION_INDENTED`
Indent non-decorated annotations to match the annotated text.
The default value is `view.ANNOTATION_HIDDEN`.
#### `view.auto_c_max_height` (number)
The maximum number of items per page to show in autocompletion and user
lists. The default value is `5`.
#### `view.auto_c_max_width` (number)
The maximum number of characters per item to show in autocompletion and
user lists.
The default value is `0`, which automatically sizes the width to fit the
longest item.
#### `view.call_tip_fore_hlt` (number, Write-only)
A call tip's highlighted text foreground color, in "0xBBGGRR" format.
#### `view.call_tip_pos_start` (number, Write-only)
The position in which backspacing beyond it hides a visible call tip.
#### `view.call_tip_position` (boolean)
Display a call tip above the current line instead of below it.
The default value is `false`.
#### `view.call_tip_use_style` (number)
The pixel width of tab characters in call tips.
When non-zero, also enables the use of style number `view.STYLE_CALLTIP`
instead of `view.STYLE_DEFAULT` for call tip styles.
The default value is `0`.
#### `view.caret_fore` (number)
The caret's foreground color, in "0xBBGGRR" format.
#### `view.caret_line_back` (number)
The background color, in "0xBBGGRR" format, of the line that contains the
caret.
#### `view.caret_line_back_alpha` (number)
The caret line's background alpha value, ranging from `0` (transparent) to
`255` (opaque).
The default value is `view.ALPHA_NOALPHA`, for no alpha.
#### `view.caret_line_frame` (number)
The caret line's frame width in pixels.
When non-zero, the line that contains the caret is framed instead of
colored in. The `view.caret_line_back` and `view.caret_line_back_alpha`
properties apply to the frame.
The default value is `0`.
#### `view.caret_line_visible` (bool)
Color the background of the line that contains the caret a different color.
The default value is `false`.
#### `view.caret_line_visible_always` (bool)
Always show the caret line, even when the window is not in focus.
The default value is `false`, showing the line only when the window is in
focus.
#### `view.caret_period` (number)
The time between caret blinks in milliseconds.
A value of `0` stops blinking.
The default value is `500`.
#### `view.caret_style` (number)
The caret's visual style.
* `view.CARETSTYLE_INVISIBLE`
No caret.
* `view.CARETSTYLE_LINE`
A line caret.
* `view.CARETSTYLE_BLOCK`
A block caret.
Any block setting may be combined with `view.CARETSTYLE_BLOCK_AFTER` via
bitwise OR (`|`) in order to draw the caret after the end of a selection,
as opposed to just inside it.
The default value is `view.CARETSTYLE_LINE`.
#### `view.caret_width` (number)
The line caret's pixel width in insert mode, either `0`, `1`, `2`, or `3`.
The default value is `1`.
#### `view.cursor` (number)
The display cursor type.
* `view.CURSORNORMAL`
The text insert cursor.
* `view.CURSORARROW`
The arrow cursor.
* `view.CURSORWAIT`
The wait cursor.
* `view.CURSORREVERSEARROW`
The reversed arrow cursor.
The default value is `view.CURSORNORMAL`.
#### `view.edge_color` (number)
The color, in "0xBBGGRR" format, of the single edge or background for long
lines according to `view.edge_mode`.
#### `view.edge_column` (number)
The column number to mark long lines at.
#### `view.edge_mode` (number)
The long line mark mode.
* `view.EDGE_NONE`
Long lines are not marked.
* `view.EDGE_LINE`
Draw a single vertical line whose color is [`view.edge_color`](#view.edge_color) at
column [`view.edge_column`](#view.edge_column).
* `view.EDGE_BACKGROUND`
Change the background color of text after column [`view.edge_column`](#view.edge_column)
to [`view.edge_color`](#view.edge_color).
* `view.EDGE_MULTILINE`
Draw vertical lines whose colors and columns are defined by calls to
[`view:multi_edge_add_line()`](#view.multi_edge_add_line).
#### `view.end_at_last_line` (bool)
Disable scrolling past the last line.
The default value is `true`.
#### `view.eol_annotation_visible` (number)
The EOL annotation visibility mode.
* `view.EOLANNOTATION_HIDDEN`
EOL Annotations are invisible.
* `view.EOLANNOTATION_STANDARD`
Draw EOL annotations no decoration.
* `view.EOLANNOTATION_BOXED`
Draw EOL annotations outlined with a box.
The default value is `view.EOLANNOTATION_HIDDEN`.
#### `view.extra_ascent` (number)
The amount of pixel padding above lines.
The default value is `0`.
#### `view.extra_descent` (number)
The amount of pixel padding below lines.
The default is `0`.
#### `view.first_visible_line` (number)
The line number of the line at the top of the view.
#### `view.fold_display_text_style` (number)
The fold display text mode.
* `view.FOLDDISPLAYTEXT_HIDDEN`
Fold display text is not shown.
* `view.FOLDDISPLAYTEXT_STANDARD`
Fold display text is shown with no decoration.
* `view.FOLDDISPLAYTEXT_BOXED`
Fold display text is shown outlined with a box.
The default value is `view.FOLDDISPLAYTEXT_HIDDEN`.
#### `view.fold_expanded` (table)
Table of flags per line number that indicate whether or not fold points are
expanded for those line numbers.
Setting expanded fold states does not toggle folds; it only updates fold
margin markers. Use [`view.toggle_fold()`](#view.toggle_fold) instead.
#### `view.fold_flags` (number, Read-only)
Bit-mask of folding lines to draw in the buffer.
* `view.FOLDFLAG_LINEBEFORE_EXPANDED`
Draw lines above expanded folds.
* `view.FOLDFLAG_LINEBEFORE_CONTRACTED`
Draw lines above collapsed folds.
* `view.FOLDFLAG_LINEAFTER_EXPANDED`
Draw lines below expanded folds.
* `view.FOLDFLAG_LINEAFTER_CONTRACTED`
Draw lines below collapsed folds.
* `view.FOLDFLAG_LEVELNUMBERS`
Show hexadecimal fold levels in line margins.
This option cannot be combined with `FOLDFLAG_LINESTATE`.
* `view.FOLDFLAG_LINESTATE`
Show line state in line margins.
This option cannot be combined with `FOLDFLAG_LEVELNUMBERS`.
The default value is `0`.
#### `view.h_scroll_bar` (bool)
Display the horizontal scroll bar.
The default value is `true`.
#### `view.highlight_guide` (number)
The indentation guide column number to also highlight when highlighting
matching braces, or `0` to stop indentation guide highlighting.
#### `view.idle_styling` (number)
The idle styling mode.
This mode has no effect when `view.wrap_mode` is on.
* `view.IDLESTYLING_NONE`
Style all the currently visible text before displaying it.
* `view.IDLESTYLING_TOVISIBLE`
Style some text before displaying it and then style the rest
incrementally in the background as an idle-time task.
* `view.IDLESTYLING_AFTERVISIBLE`
Style text after the currently visible portion in the background.
* `view.IDLESTYLING_ALL`
Style text both before and after the visible text in the background.
The default value is `view.IDLESTYLING_NONE`.
#### `view.indentation_guides` (number)
The indentation guide drawing mode.
Indentation guides are dotted vertical lines that appear within indentation
whitespace at each level of indentation.
* `view.IV_NONE`
Does not draw any guides.
* `view.IV_REAL`
Draw guides only within indentation whitespace.
* `view.IV_LOOKFORWARD`
Draw guides beyond the current line up to the next non-empty line's
indentation level, but with an additional level if the previous non-empty
line is a fold point.
* `view.IV_LOOKBOTH`
Draw guides beyond the current line up to either the indentation level of
the previous or next non-empty line, whichever is greater.
The default value is `view.IV_NONE`.
#### `view.indic_alpha` (table)
Table of fill color alpha values, ranging from `0` (transparent) to `255`
(opaque), for indicator numbers from `1` to `32` whose styles are either
`INDIC_ROUNDBOX`, `INDIC_STRAIGHTBOX`, or `INDIC_DOTBOX`.
The default values are `view.ALPHA_NOALPHA`, for no alpha.
#### `view.indic_fore` (table)
Table of foreground colors, in "0xBBGGRR" format, for indicator numbers
from `1` to `32`.
Changing an indicator's foreground color resets that indicator's hover
foreground color.
#### `view.indic_hover_fore` (table)
Table of hover foreground colors, in "0xBBGGRR" format, for indicator
numbers from `1` to `32`.
The default values are the respective indicator foreground colors.
#### `view.indic_hover_style` (table)
Table of hover styles for indicators numbers from `1` to `32`. An
indicator's hover style drawn when either the cursor hovers over that
indicator or the caret is within that indicator.
The default values are the respective indicator styles.
#### `view.indic_outline_alpha` (table)
Table of outline color alpha values, ranging from `0` (transparent) to
`255` (opaque), for indicator numbers from `1` to `32` whose styles are
either `INDIC_ROUNDBOX`, `INDIC_STRAIGHTBOX`, or `INDIC_DOTBOX`.
The default values are `view.ALPHA_NOALPHA`, for no alpha.
#### `view.indic_style` (table)
Table of styles for indicator numbers from `1` to `32`.
* `view.INDIC_PLAIN`
An underline.
* `view.INDIC_SQUIGGLE`
A squiggly underline 3 pixels in height.
* `view.INDIC_TT`
An underline of small 'T' shapes.
* `view.INDIC_DIAGONAL`
An underline of diagonal hatches.
* `view.INDIC_STRIKE`
Strike out.
* `view.INDIC_HIDDEN`
Invisible.
* `view.INDIC_BOX`
A bounding box.
* `view.INDIC_ROUNDBOX`
A translucent box with rounded corners around the text. Use
[`view.indic_alpha`](#view.indic_alpha) and [`view.indic_outline_alpha`](#view.indic_outline_alpha) to set the
fill and outline transparency, respectively. Their default values are
`30` and `50`.
* `view.INDIC_STRAIGHTBOX`
Similar to `INDIC_ROUNDBOX` but with sharp corners.
* `view.INDIC_DASH`
A dashed underline.
* `view.INDIC_DOTS`
A dotted underline.
* `view.INDIC_SQUIGGLELOW`
A squiggly underline 2 pixels in height.
* `view.INDIC_DOTBOX`
Similar to `INDIC_STRAIGHTBOX` but with a dotted outline.
Translucency alternates between [`view.indic_alpha`](#view.indic_alpha) and
[`view.indic_outline_alpha`](#view.indic_outline_alpha) starting with the top-left pixel.
* `view.INDIC_SQUIGGLEPIXMAP`
Identical to `INDIC_SQUIGGLE` but draws faster by using a pixmap instead
of multiple line segments.
* `view.INDIC_COMPOSITIONTHICK`
A 2-pixel thick underline at the bottom of the line inset by 1 pixel on
on either side. Similar in appearance to the target in Asian language
input composition.
* `view.INDIC_COMPOSITIONTHIN`
A 1-pixel thick underline just before the bottom of the line inset by 1
pixel on either side. Similar in appearance to the non-target ranges in
Asian language input composition.
* `view.INDIC_FULLBOX`
Similar to `INDIC_STRAIGHTBOX` but extends to the top of its line,
potentially touching any similar indicators on the line above.
* `view.INDIC_TEXTFORE`
Changes the color of text to an indicator's foreground color.
* `view.INDIC_POINT`
A triangle below the start of the indicator range.
* `view.INDIC_POINTCHARACTER`
A triangle below the center of the first character of the indicator
range.
* `view.INDIC_GRADIENT`
A box with a vertical gradient from solid on top to transparent on
bottom.
* `view.INDIC_GRADIENTCENTER`
A box with a centered gradient from solid in the middle to transparent on
the top and bottom.
Use [`_SCINTILLA.next_indic_number()`](#_SCINTILLA.next_indic_number) for custom indicators.
Changing an indicator's style resets that indicator's hover style.
#### `view.indic_under` (table)
Table of flags that indicate whether or not to draw indicators behind text
instead of over the top of it for indicator numbers from `1` to `32`.
The default values are `false`.
#### `view.line_visible` (table, Read-only)
Table of flags per line number that indicate whether or not lines are
visible for those line numbers.
#### `view.lines_on_screen` (number, Read-only)
The number of completely visible lines in the view.
It is possible to have a partial line visible at the bottom of the view.
#### `view.margin_back_n` (table)
Table of background colors, in "0xBBGGRR" format, of margin numbers from
`1` to `view.margins` (`5` by default).
Only affects margins of type `view.MARGIN_COLOR`.
#### `view.margin_cursor_n` (table)
Table of cursor types shown over margin numbers from `1` to
`view.margins` (`5` by default).
* `view.CURSORARROW`
Normal arrow cursor.
* `view.CURSORREVERSEARROW`
Reversed arrow cursor.
The default values are `view.CURSORREVERSEARROW`.
#### `view.margin_left` (number)
The pixel size of the left margin of the buffer text.
The default value is `1`.
#### `view.margin_mask_n` (table)
Table of bit-masks of markers whose symbols marker symbol margins can
display for margin numbers from `1` to `view.margins` (`5` by default).
Bit-masks are 32-bit values whose bits correspond to the 32 available
markers.
The default values are `0`, `view.MASK_FOLDERS`, `0`, `0`, and `0`, for
a line margin and logical marker margin.
#### `view.margin_options` (number)
A bit-mask of margin option settings.
* `view.MARGINOPTION_NONE`
None.
* `view.MARGINOPTION_SUBLINESELECT`
Select only a wrapped line's sub-line (rather than the entire line) when
the line number margin is clicked.
The default value is `view.MARGINOPTION_NONE`.
#### `view.margin_right` (number)
The pixel size of the right margin of the buffer text.
The default value is `1`.
#### `view.margin_sensitive_n` (table)
Table of flags that indicate whether or not mouse clicks in margins emit
`MARGIN_CLICK` events for margin numbers from `1` to `view.margins` (`5`
by default).
The default values are `false`.
#### `view.margin_type_n` (table)
Table of margin types for margin numbers from `1` to `view.margins` (`5`
by default).
* `view.MARGIN_SYMBOL`
A marker symbol margin.
* `view.MARGIN_NUMBER`
A line number margin.
* `view.MARGIN_BACK`
A marker symbol margin whose background color matches the default text
background color.
* `view.MARGIN_FORE`
A marker symbol margin whose background color matches the default text
foreground color.
* `view.MARGIN_TEXT`
A text margin.
* `view.MARGIN_RTEXT`
A right-justified text margin.
* `view.MARGIN_COLOR`
A marker symbol margin whose background color is configurable.
The default value for the first margin is `view.MARGIN_NUMBER`, followed
by `view.MARGIN_SYMBOL` for the rest.
#### `view.margin_width_n` (table)
Table of pixel margin widths for margin numbers from `1` to
`view.margins` (`5` by default).
#### `view.margins` (number)
The number of margins.
The default value is `5`.
#### `view.marker_alpha` (table, Write-only)
Table of alpha values, ranging from `0` (transparent) to `255` (opaque),
of markers drawn in the text area (not the margin) for markers numbers from
`1` to `32`.
The default values are `view.ALPHA_NOALPHA`, for no alpha.
#### `view.marker_back` (table, Write-only)
Table of background colors, in "0xBBGGRR" format, of marker numbers from
`1` to `32`.
#### `view.marker_back_selected` (table, Write-only)
Table of background colors, in "0xBBGGRR" format, of markers whose folding
blocks are selected for marker numbers from `1` to `32`.
#### `view.marker_fore` (table, Write-only)
Table of foreground colors, in "0xBBGGRR" format, of marker numbers from
`1` to `32`.
#### `view.mouse_dwell_time` (number)
The number of milliseconds the mouse must idle before generating a
`DWELL_START` event. A time of `view.TIME_FOREVER` will never generate
one.
#### `view.mouse_selection_rectangular_switch` (bool)
Whether or not pressing [`view.rectangular_selection_modifier`](#view.rectangular_selection_modifier) when
selecting text normally with the mouse turns on rectangular selection.
The default value is `false`.
#### `view.property` (table)
Map of key-value string pairs used by lexers.
#### `view.property_expanded` (table, Read-only)
Map of key-value string pairs used by lexers with `$()` and `%()` variable
replacement performed in values.
#### `view.property_int` (table, Read-only)
Map of key-value pairs used by lexers with values interpreted as numbers,
or `0` if not found.
#### `view.rectangular_selection_modifier` (number)
The modifier key used in combination with a mouse drag in order to create a
rectangular selection.
* `view.MOD_CTRL`
The "Control" modifier key.
* `view.MOD_ALT`
The "Alt" modifier key.
* `view.MOD_SUPER`
The "Super" modifier key, usually defined as the left "Windows" or
"Command" key.
The default value is `view.MOD_CTRL`.
#### `view.representation` (table)
The alternative string representations of characters.
Representations are displayed in the same way control characters are. Use
the empty string for the '\0' character when assigning its representation.
Characters are strings, not numeric codes.
Call [`view.clear_representation()`](#view.clear_representation) to remove a representation.
#### `view.rgba_image_height` (number)
The height of the RGBA image to be defined using
[`view.marker_define_rgba_image()`](#view.marker_define_rgba_image).
#### `view.rgba_image_scale` (number)
The scale factor in percent of the RGBA image to be defined using
[`view.marker_define_rgba_image()`](#view.marker_define_rgba_image).
This is useful on macOS with a retina display where each display unit is 2
pixels: use a factor of `200` so that each image pixel is displayed using a
screen pixel. The default scale, `100`, will stretch each image pixel to
cover 4 screen pixels on a retina display.
#### `view.rgba_image_width` (number)
The width of the RGBA image to be defined using
[`view.marker_define_rgba_image()`](#view.marker_define_rgba_image) and
[`view.register_rgba_image()`](#view.register_rgba_image).
#### `view.scroll_width` (number)
The horizontal scrolling pixel width.
For performance, the view does not measure the display width of the buffer
to determine the properties of the horizontal scroll bar, but uses an
assumed width instead. To ensure the width of the currently visible lines
can be scrolled use [`view.scroll_width_tracking`](#view.scroll_width_tracking).
The default value is `2000`.
#### `view.scroll_width_tracking` (bool)
Continuously update the horizontal scrolling width to match the maximum
width of a displayed line beyond [`view.scroll_width`](#view.scroll_width).
The default value is `false`.
#### `view.sel_alpha` (number)
The selection's alpha value, ranging from `0` (transparent) to `255`
(opaque).
The default value is `view.ALPHA_NOALPHA`, for no alpha.
#### `view.sel_eol_filled` (bool)
Extend the selection to the view's right margin.
The default value is `false`.
#### `view.size` (number)
The split resizer's pixel position if the view is a split one.
#### `view.style_back` (table)
Table of background colors, in "0xBBGGRR" format, of text for style numbers
from `1` to `256`.
#### `view.style_bold` (table)
Table of flags that indicate whether or not text is bold for style numbers
from `1` to `256`.
The default values are `false`.
#### `view.style_case` (table)
Table of letter case modes of text for style numbers from `1` to `256`.
* `view.CASE_MIXED`
Display text in normally.
* `view.CASE_UPPER`
Display text in upper case.
* `view.CASE_LOWER`
Display text in lower case.
* `view.CASE_CAMEL`
Display text in camel case.
The default values are `view.CASE_MIXED`.
#### `view.style_changeable` (table)
Table of flags that indicate whether or not text is changeable for style
numbers from `1` to `256`.
The default values are `true`.
Read-only styles do not allow the caret into the range of text.
#### `view.style_eol_filled` (table)
Table of flags that indicate whether or not the background colors of styles
whose characters occur last on lines extend all the way to the view's right
margin for style numbers from `1` to `256`.
The default values are `false`.
#### `view.style_font` (table)
Table of string font names of text for style numbers from `1` to `256`.
#### `view.style_fore` (table)
Table of foreground colors, in "0xBBGGRR" format, of text for style numbers
from `1` to `256`.
#### `view.style_italic` (table)
Table of flags that indicate whether or not text is italic for style
numbers from `1` to `256`.
The default values are `false`.
#### `view.style_size` (table)
Table of font sizes of text for style numbers from `1` to `256`.
#### `view.style_underline` (table)
Table of flags that indicate whether or not text is underlined for style
numbers from `1` to `256`.
The default values are `false`.
#### `view.style_visible` (table)
Table of flags that indicate whether or not text is visible for style
numbers from `1` to `256`.
The default values are `true`.
#### `view.tab_draw_mode` (number)
The draw mode of visible tabs.
* `view.TD_LONGARROW`
An arrow that stretches until the tabstop.
* `view.TD_STRIKEOUT`
A horizontal line that stretches until the tabstop.
The default value is `view.TD_LONGARROW`.
#### `view.v_scroll_bar` (bool)
Display the vertical scroll bar.
The default value is `true`.
#### `view.view_eol` (bool)
Display end of line characters.
The default value is `false`.
#### `view.view_ws` (number)
The whitespace visibility mode.
* `view.WS_INVISIBLE`
Whitespace is invisible.
* `view.WS_VISIBLEALWAYS`
Display all space characters as dots and tab characters as arrows.
* `view.WS_VISIBLEAFTERINDENT`
Display only non-indentation spaces and tabs as dots and arrows.
* `view.WS_VISIBLEONLYININDENT`
Display only indentation spaces and tabs as dots and arrows.
The default value is `view.WS_INVISIBLE`.
#### `view.whitespace_size` (number)
The pixel size of the dots that represent space characters when whitespace
is visible.
The default value is `1`.
#### `view.wrap_indent_mode` (number)
The wrapped line indent mode.
* `view.WRAPINDENT_FIXED`
Indent wrapped lines by [`view.wrap_start_indent`](#view.wrap_start_indent).
* `view.WRAPINDENT_SAME`
Indent wrapped lines the same amount as the first line.
* `view.WRAPINDENT_INDENT`
Indent wrapped lines one more level than the level of the first line.
* `view.WRAPINDENT_DEEPINDENT`
Indent wrapped lines two more levels than the level of the first line.
The default value is `view.WRAPINDENT_FIXED`.
#### `view.wrap_mode` (number)
Long line wrap mode.
* `view.WRAP_NONE`
Long lines are not wrapped.
* `view.WRAP_WORD`
Wrap long lines at word (and style) boundaries.
* `view.WRAP_CHAR`
Wrap long lines at character boundaries.
* `view.WRAP_WHITESPACE`
Wrap long lines at word boundaries (ignoring style boundaries).
The default value is `view.WRAP_NONE`.
#### `view.wrap_start_indent` (number)
The number of spaces of indentation to display wrapped lines with if
[`view.wrap_indent_mode`](#view.wrap_indent_mode) is `view.WRAPINDENT_FIXED`.
The default value is `0`.
#### `view.wrap_visual_flags` (number)
The wrapped line visual flag display mode.
* `view.WRAPVISUALFLAG_NONE`
No visual flags.
* `view.WRAPVISUALFLAG_END`
Show a visual flag at the end of a wrapped line.
* `view.WRAPVISUALFLAG_START`
Show a visual flag at the beginning of a sub-line.
* `view.WRAPVISUALFLAG_MARGIN`
Show a visual flag in the sub-line's line number margin.
The default value is `view.WRAPVISUALFLAG_NONE`.
#### `view.wrap_visual_flags_location` (number)
The wrapped line visual flag location.
* `view.WRAPVISUALFLAGLOC_DEFAULT`
Draw a visual flag near the view's right margin.
* `view.WRAPVISUALFLAGLOC_END_BY_TEXT`
Draw a visual flag near text at the end of a wrapped line.
* `view.WRAPVISUALFLAGLOC_START_BY_TEXT`
Draw a visual flag near text at the beginning of a subline.
The default value is `view.WRAPVISUALFLAGLOC_DEFAULT`.
#### `view.x_offset` (number)
The horizontal scroll pixel position.
A value of `0` is the normal position with the first text column visible at
the left of the view.
#### `view.zoom` (number)
The number of points to add to the size of all fonts.
Negative values are allowed, down to `-10`.
The default value is `0`.
### Functions defined by `view`
#### `view.brace_bad_light`(*view, pos*)
Highlights the character at position *pos* as an unmatched brace character
using the `'style.bracebad'` style.
Removes highlighting when *pos* is `-1`.
Parameters:
* *`view`*: A view.
* *`pos`*: The position in *view*'s buffer to highlight, or `-1` to remove
the highlight.
#### `view.brace_bad_light_indicator`(*view, use\_indicator, indicator*)
Highlights unmatched brace characters with indicator number *indicator*, in
the range of `1` to `32`, instead of the
`view.STYLE_BRACEBAD` style if *use_indicator* is `true`.
Parameters:
* *`view`*: A view.
* *`use_indicator`*: Whether or not to use an indicator.
* *`indicator`*: The indicator number to use.
#### `view.brace_highlight`(*view, pos1, pos2*)
Highlights the characters at positions *pos1* and *pos2* as matching braces
using the `'style.bracelight'` style.
If indent guides are enabled, locates the column with `buffer.column` and
sets `view.highlight_guide` in order to highlight the indent guide.
Parameters:
* *`view`*: A view.
* *`pos1`*: The first position in *view*'s buffer to highlight.
* *`pos2`*: The second position in *view*'s buffer to highlight.
#### `view.brace_highlight_indicator`(*view, use\_indicator, indicator*)
Highlights matching brace characters with indicator number *indicator*, in
the range of `1` to `32`, instead of the
`view.STYLE_BRACELIGHT` style if *use_indicator* is `true`.
Parameters:
* *`view`*: A view.
* *`use_indicator`*: Whether or not to use an indicator.
* *`indicator`*: The indicator number to use.
#### `view.call_tip_active`(*view*)
Returns whether or not a call tip is visible.
Parameters:
* *`view`*: A view.
Return:
* bool
#### `view.call_tip_cancel`(*view*)
Removes the displayed call tip from view.
Parameters:
* *`view`*: A view.
#### `view.call_tip_pos_start`(*view*)
Returns a call tip's display position.
Parameters:
* *`view`*: A view.
Return:
* number
#### `view.call_tip_set_hlt`(*view, start\_pos, end\_pos*)
Highlights a call tip's text between positions *start_pos* to *end_pos* with
the color `view.call_tip_fore_hlt`.
Parameters:
* *`view`*: A view.
* *`start_pos`*: The start position in a call tip text to highlight.
* *`end_pos`*: The end position in a call tip text to highlight.
#### `view.call_tip_show`(*view, pos, text*)
Displays a call tip at position *pos* with string *text* as the call tip's
contents.
Any "\001" or "\002" bytes in *text* are replaced by clickable up or down
arrow visuals, respectively. These may be used to indicate that a symbol has
more than one call tip, for example.
Parameters:
* *`view`*: A view.
* *`pos`*: The position in *view*'s buffer to show a call tip at.
* *`text`*: The call tip text to show.
#### `view.clear_registered_images`(*view*)
Clears all images registered using `view.register_image()` and
`view.register_rgba_image()`.
Parameters:
* *`view`*: A view.
#### `view.clear_representation`(*view, char*)
Removes the alternate string representation for character *char*.
Parameters:
* *`view`*: A view.
* *`char`*: The string character in `buffer.representations` to remove the
alternate string representation for.
#### `view.contracted_fold_next`(*view, line*)
Returns the line number of the next contracted fold point starting from line
number *line*, or `-1` if none exists.
Parameters:
* *`view`*: A view.
* *`line`*: The line number in *view* to start at.
Return:
* number
#### `view.doc_line_from_visible`(*view, display\_line*)
Returns the actual line number of displayed line number *display_line*,
taking wrapped, annotated, and hidden lines into account.
If *display_line* is less than or equal to `1`, returns `1`. If
*display_line* is greater than the number of displayed lines, returns
`buffer.line_count`.
Parameters:
* *`view`*: A view.
* *`display_line`*: The display line number to use.
Return:
* number
#### `view.ensure_visible`(*view, line*)
Ensures line number *line* is visible by expanding any fold points hiding it.
Parameters:
* *`view`*: A view.
* *`line`*: The line number in *view* to ensure visible.
#### `view.ensure_visible_enforce_policy`(*view, line*)
Ensures line number *line* is visible by expanding any fold points hiding it
based on the vertical caret policy previously defined in
`view.set_visible_policy()`.
Parameters:
* *`view`*: A view.
* *`line`*: The line number in *view* to ensure visible.
#### `view.fold_all`(*view, action*)
Contracts, expands, or toggles all fold points, depending on *action*.
When toggling, the state of the first fold point determines whether to
expand or contract.
Parameters:
* *`view`*: A view.
* *`action`*: The fold action to perform. Valid values are:
* `view.FOLDACTION_CONTRACT`
* `view.FOLDACTION_EXPAND`
* `view.FOLDACTION_TOGGLE`
#### `view.fold_children`(*view, line, action*)
Contracts, expands, or toggles the fold point on line number *line*, as well
as all of its children, depending on *action*.
Parameters:
* *`view`*: A view.
* *`line`*: The line number in *view* to set the fold states for.
* *`action`*: The fold action to perform. Valid values are:
* `view.FOLDACTION_CONTRACT`
* `view.FOLDACTION_EXPAND`
* `view.FOLDACTION_TOGGLE`
#### `view.fold_line`(*view, line, action*)
Contracts, expands, or toggles the fold point on line number *line*,
depending on *action*.
Parameters:
* *`view`*: A view.
* *`line`*: The line number in *view* to set the fold state for.
* *`action`*: The fold action to perform. Valid values are:
* `view.FOLDACTION_CONTRACT`
* `view.FOLDACTION_EXPAND`
* `view.FOLDACTION_TOGGLE`
#### `view.get_default_fold_display_text`(*view*)
Returns the default fold display text.
Parameters:
* *`view`*: A view.
#### `view.goto_buffer`(*view, buffer*)
Switches to buffer *buffer* or the buffer *buffer* number of buffers relative
to the current one.
Emits `BUFFER_BEFORE_SWITCH` and `BUFFER_AFTER_SWITCH` events.
Parameters:
* *`view`*: The view to switch buffers in.
* *`buffer`*: A buffer or relative buffer number (typically 1 or -1).
See also:
* [`_BUFFERS`](#_BUFFERS)
* [`events.BUFFER_BEFORE_SWITCH`](#events.BUFFER_BEFORE_SWITCH)
* [`events.BUFFER_AFTER_SWITCH`](#events.BUFFER_AFTER_SWITCH)
#### `view.hide_lines`(*view, start\_line, end\_line*)
Hides the range of lines between line numbers *start_line* to *end_line*.
This has no effect on fold levels or fold flags and the first line cannot be
hidden.
Parameters:
* *`view`*: A view.
* *`start_line`*: The start line of the range of lines in *view* to hide.
* *`end_line`*: The end line of the range of lines in *view* to hide.
#### `view.line_scroll`(*view, columns, lines*)
Scrolls the buffer right *columns* columns and down *lines* lines.
Negative values are allowed.
Parameters:
* *`view`*: A view.
* *`columns`*: The number of columns to scroll horizontally.
* *`lines`*: The number of lines to scroll vertically.
#### `view.line_scroll_down`(*view*)
Scrolls the buffer down one line, keeping the caret visible.
Parameters:
* *`view`*: A view.
#### `view.line_scroll_up`(*view*)
Scrolls the buffer up one line, keeping the caret visible.
Parameters:
* *`view`*: A view.
#### `view.marker_define`(*view, marker, symbol*)
Assigns marker symbol *symbol* to marker number *marker*, in the range of `1`
to `32`.
*symbol* is shown in marker symbol margins next to lines marked with
*marker*.
Parameters:
* *`view`*: A view.
* *`marker`*: The marker number in the range of `1` to `32` to set *symbol*
for.
* *`symbol`*: The marker symbol: `buffer.MARK_*`.
See also:
* [`_SCINTILLA.next_marker_number`](#_SCINTILLA.next_marker_number)
#### `view.marker_define_pixmap`(*view, marker, pixmap*)
Associates marker number *marker*, in the range of `1` to `32`, with XPM
image *pixmap*.
The `view.MARK_PIXMAP` marker symbol must be assigned to *marker*.
*pixmap* is shown in marker symbol margins next to lines marked with
*marker*.
Parameters:
* *`view`*: A view.
* *`marker`*: The marker number in the range of `1` to `32` to define
pixmap *pixmap* for.
* *`pixmap`*: The string pixmap data.
#### `view.marker_define_rgba_image`(*view, marker, pixels*)
Associates marker number *marker*, in the range of `1` to `32`, with RGBA
image *pixels*.
The dimensions for *pixels* (`view.rgba_image_width` and
`view.rgba_image_height`) must have already been defined. *pixels* is a
sequence of 4 byte pixel values (red, blue, green, and alpha) defining the
image line by line starting at the top-left pixel.
The `view.MARK_RGBAIMAGE` marker symbol must be assigned to *marker*.
*pixels* is shown in symbol margins next to lines marked with *marker*.
Parameters:
* *`view`*: A view.
* *`marker`*: The marker number in the range of `1` to `32` to define RGBA
data *pixels* for.
* *`pixels`*: The string sequence of 4 byte pixel values starting with the
pixels for the top line, with the leftmost pixel first, then continuing
with the pixels for subsequent lines. There is no gap between lines for
alignment reasons. Each pixel consists of, in order, a red byte, a green
byte, a blue byte and an alpha byte. The color bytes are not premultiplied
by the alpha value. That is, a fully red pixel that is 25% opaque will be
`[FF, 00, 00, 3F]`.
#### `view.marker_enable_highlight`(*view, enabled*)
Highlights the margin fold markers for the current fold block if *enabled* is
`true`.
Parameters:
* *`view`*: A view.
* *`enabled`*: Whether or not to enable highlight.
#### `view.marker_symbol_defined`(*view, marker*)
Returns the symbol assigned to marker number *marker*, in the range of `1` to
`32`, used in `view.marker_define()`,
`view.marker_define_pixmap()`, or `view.marker_define_rgba_image()`.
Parameters:
* *`view`*: A view.
* *`marker`*: The marker number in the range of `1` to `32` to get the symbol
of.
Return:
* number
#### `view.multi_edge_add_line`(*view, column, color*)
Adds a new vertical line at column number *column* with color *color*, in
"0xBBGGRR" format.
Parameters:
* *`view`*: A view.
* *`column`*: The column number to add a vertical line at.
* *`color`*: The color in "0xBBGGRR" format.
#### `view.multi_edge_clear_all`(*view*)
Clears all vertical lines created by `view:multi_edge_add_line()`.
Parameters:
* *`view`*: A view.
#### `view.register_image`(*view, type, xpm\_data*)
Registers XPM image *xpm_data* to type number *type* for use in
autocompletion and user lists.
Parameters:
* *`view`*: A view.
* *`type`*: Integer type to register the image with.
* *`xpm_data`*: The XPM data as described in `view.marker_define_pixmap()`.
#### `view.register_rgba_image`(*view, type, pixels*)
Registers RGBA image *pixels* to type number *type* for use in autocompletion
and user lists.
The dimensions for *pixels* (`view.rgba_image_width` and
`view.rgba_image_height`) must have already been defined. *pixels* is a
sequence of 4 byte pixel values (red, blue, green, and alpha) defining the
image line by line starting at the top-left pixel.
Parameters:
* *`view`*: A view.
* *`type`*: Integer type to register the image with.
* *`pixels`*: The RGBA data as described in
`view.marker_define_rgba_image()`.
#### `view.scroll_caret`(*view*)
Scrolls the caret into view based on the policies previously defined in
`view.set_x_caret_policy()` and `view.set_y_caret_policy()`.
Parameters:
* *`view`*: A view.
See also:
* [`view.set_x_caret_policy`](#view.set_x_caret_policy)
* [`view.set_y_caret_policy`](#view.set_y_caret_policy)
#### `view.scroll_range`(*view, secondary\_pos, primary\_pos*)
Scrolls into view the range of text between positions *primary_pos* and
*secondary_pos*, with priority given to *primary_pos*.
Similar to `view.scroll_caret()`, but with *primary_pos* instead of
`buffer.current_pos`.
This is useful for scrolling search results into view.
Parameters:
* *`view`*: A view.
* *`secondary_pos`*: The secondary range position to scroll into view.
* *`primary_pos`*: The primary range position to scroll into view.
#### `view.scroll_to_end`(*view*)
Scrolls to the end of the buffer without moving the caret.
Parameters:
* *`view`*: A view.
#### `view.scroll_to_start`(*view*)
Scrolls to the beginning of the buffer without moving the caret.
Parameters:
* *`view`*: A view.
#### `view.set_default_fold_display_text`(*view, text*)
Sets the default fold display text to string *text*.
Parameters:
* *`view`*: A view.
* *`text`*: The text to display by default next to folded lines.
See also:
* [`view.toggle_fold_show_text`](#view.toggle_fold_show_text)
#### `view.set_fold_margin_color`(*view, use\_setting, color*)
Overrides the fold margin's default color with color *color*, in "0xBBGGRR"
format,
if *use_setting* is `true`.
Parameters:
* *`view`*: A view.
* *`use_setting`*: Whether or not to use *color*.
* *`color`*: The color in "0xBBGGRR" format.
#### `view.set_fold_margin_hi_color`(*view, use\_setting, color*)
Overrides the fold margin's default highlight color with color *color*, in
"0xBBGGRR" format, if *use_setting* is `true`.
Parameters:
* *`view`*: A view.
* *`use_setting`*: Whether or not to use *color*.
* *`color`*: The color in "0xBBGGRR" format.
#### `view.set_sel_back`(*view, use\_setting, color*)
Overrides the selection's default background color with color *color*, in
"0xBBGGRR" format, if *use_setting* is `true`.
Overwrites any existing `view.additional_sel_back` color.
Parameters:
* *`view`*: A view.
* *`use_setting`*: Whether or not to use *color*.
* *`color`*: The color in "0xBBGGRR" format.
#### `view.set_sel_fore`(*view, use\_setting, color*)
Overrides the selection's default foreground color with color *color*, in
"0xBBGGRR" format, if *use_setting* is `true`.
Overwrites any existing `view.additional_sel_fore` color.
Parameters:
* *`view`*: A view.
* *`use_setting`*: Whether or not to use *color*.
* *`color`*: The color in "0xBBGGRR" format.
#### `view.set_theme`(*view, name, env*)
Sets the view's color theme to be string *name*, with the contents of table
*env* available as global variables.
User themes override Textadept's default themes when they have the same name.
If *name* contains slashes, it is assumed to be an absolute path to a theme
instead of a theme name.
Parameters:
* *`view`*: A view.
* *`name`*: The name or absolute path of a theme to set.
* *`env`*: Optional table of global variables themes can utilize to override
default settings such as font and size.
Usage:
* `view:set_theme('light', {font = 'Monospace', size = 12})`
See also:
* [`lexer.colors`](#lexer.colors)
* [`lexer.styles`](#lexer.styles)
#### `view.set_visible_policy`(*view, policy, y*)
Defines scrolling policy bit-mask *policy* as the policy for keeping the
caret *y* number of lines away from the vertical margins as
`view.ensure_visible_enforce_policy()` redisplays hidden or folded lines.
It is similar in operation to `view.set_y_caret_policy()`.
Parameters:
* *`view`*: A view.
* *`policy`*: The combination of `view.VISIBLE_SLOP` and
`view.VISIBLE_STRICT` policy flags to set.
* *`y`*: The number of lines from the vertical margins to keep the caret.
#### `view.set_whitespace_back`(*view, use\_setting, color*)
Overrides the background color of whitespace with color *color*, in
"0xBBGGRR" format, if *use_setting* is `true`.
Parameters:
* *`view`*: A view.
* *`use_setting`*: Whether or not to use *color*.
* *`color`*: The color in "0xBBGGRR" format.
#### `view.set_whitespace_fore`(*view, use\_setting, color*)
Overrides the foreground color of whitespace with color *color*, in
"0xBBGGRR" format, if *use_setting* is `true`.
Parameters:
* *`view`*:
* *`use_setting`*: Whether or not to use *color*.
* *`color`*: The color in "0xBBGGRR" format.
#### `view.set_x_caret_policy`(*view, policy, x*)
Defines scrolling policy bit-mask *policy* as the policy for keeping the
caret *x* number of pixels away from the horizontal margins.
Parameters:
* *`view`*: A view.
* *`policy`*: The combination of `view.CARET_SLOP`, `view.CARET_STRICT`,
`view.CARET_EVEN`, and `view.CARET_JUMPS` policy flags to set.
* *`x`*: The number of pixels from the horizontal margins to keep the caret.
#### `view.set_y_caret_policy`(*view, policy, y*)
Defines scrolling policy bit-mask *policy* as the policy for keeping the
caret *y* number of lines away from the vertical margins.
Parameters:
* *`view`*: A view.
* *`policy`*: The combination of `view.CARET_SLOP`, `view.CARET_STRICT`,
`view.CARET_EVEN`, and `view.CARET_JUMPS` policy flags to set.
* *`y`*: The number of lines from the vertical margins to keep the caret.
#### `view.show_lines`(*view, start\_line, end\_line*)
Shows the range of lines between line numbers *start_line* to *end_line*.
This has no effect on fold levels or fold flags and the first line cannot be
hidden.
Parameters:
* *`view`*: A view.
* *`start_line`*: The start line of the range of lines in *view* to show.
* *`end_line`*: The end line of the range of lines in *view* to show.
#### `view.split`(*view, vertical*)
Splits the view into top and bottom views (unless *vertical* is `true`),
focuses the new view, and returns both the old and new views.
If *vertical* is `false`, splits the view vertically into left and
right views.
Emits a `VIEW_NEW` event.
Parameters:
* *`view`*: The view to split.
* *`vertical`*: Optional flag indicating whether or not to split the view
vertically. The default value is `false`, for horizontal.
Return:
* old view and new view.
See also:
* [`events.VIEW_NEW`](#events.VIEW_NEW)
#### `view.style_clear_all`(*view*)
Reverts all styles to having the same properties as `view.STYLE_DEFAULT`.
Parameters:
* *`view`*: A view.
#### `view.style_reset_default`(*view*)
Resets `view.STYLE_DEFAULT` to its initial state.
Parameters:
* *`view`*: A view.
#### `view.text_height`(*view, line*)
Returns the pixel height of line number *line*.
Parameters:
* *`view`*: A view.
* *`line`*: The line number in *view* to get the pixel height of.
Return:
* number
#### `view.text_width`(*view, style\_num, text*)
Returns the pixel width string *text* would have when styled with style
number *style_num*, in the range of `1` to `256`.
Parameters:
* *`view`*: A view.
* *`style_num`*: The style number between `1` and `256` to use.
* *`text`*: The text to measure the width of.
Return:
* number
#### `view.toggle_fold`(*view, line*)
Toggles the fold point on line number *line* between expanded (where all of
its child lines are displayed) and contracted (where all of its child lines
are hidden).
Parameters:
* *`view`*: A view.
* *`line`*: The line number in *view* to toggle the fold on.
See also:
* [`view.set_default_fold_display_text`](#view.set_default_fold_display_text)
#### `view.toggle_fold_show_text`(*view, line, text*)
Toggles a fold point on line number *line* between expanded (where all of
its child lines are displayed) and contracted (where all of its child lines
are hidden), and shows string *text* next to that line.
*text* is drawn with style number `view.STYLE_FOLDDISPLAYTEXT`.
Parameters:
* *`view`*: A view.
* *`line`*: The line number in *view* to toggle the fold on and display
*text* after.
* *`text`*: The text to display after the line.
#### `view.unsplit`(*view*)
Unsplits the view if possible, returning `true` on success.
Parameters:
* *`view`*: The view to unsplit.
Return:
* boolean if the view was unsplit or not.
#### `view.vertical_center_caret`(*view*)
Centers current line in the view.
Parameters:
* *`view`*: A view.
#### `view.visible_from_doc_line`(*view, line*)
Returns the displayed line number of actual line number *line*, taking
wrapped, annotated, and hidden lines into account, or `-1` if *line* is
outside the range of lines in the buffer.
Lines can occupy more than one display line if they wrap.
Parameters:
* *`view`*: A view.
* *`line`*: The line number in *view* to use.
Return:
* number
#### `view.wrap_count`(*view, line*)
Returns the number of wrapped lines needed to fully display line number
*line*.
Parameters:
* *`view`*: A view.
* *`line`*: The line number in *view* to use.
Return:
* number
#### `view.zoom_in`(*view*)
Increases the size of all fonts by one point, up to 20.
Parameters:
* *`view`*: A view.
#### `view.zoom_out`(*view*)
Decreases the size of all fonts by one point, down to -10.
Parameters:
* *`view`*: A view.
### Tables defined by `view`
#### `view.buffer`
The [buffer](#buffer) the view currently contains. (Read-only)
---