diff options
Diffstat (limited to 'core')
-rw-r--r-- | core/.buffer.luadoc | 2099 | ||||
-rw-r--r-- | core/.iconv.luadoc | 26 | ||||
-rw-r--r-- | core/.view.luadoc | 19 | ||||
-rw-r--r-- | core/args.lua | 21 | ||||
-rw-r--r-- | core/events.lua | 252 | ||||
-rw-r--r-- | core/file_io.lua | 69 | ||||
-rw-r--r-- | core/gui.lua | 101 | ||||
-rw-r--r-- | core/iface.lua | 25 | ||||
-rw-r--r-- | core/init.lua | 51 | ||||
-rw-r--r-- | core/keys.lua | 15 | ||||
-rw-r--r-- | core/locale.lua | 5 |
11 files changed, 1440 insertions, 1243 deletions
diff --git a/core/.buffer.luadoc b/core/.buffer.luadoc index 54b891a7..fe1cfa3b 100644 --- a/core/.buffer.luadoc +++ b/core/.buffer.luadoc @@ -10,598 +10,611 @@ -- -- [buffer]: _G.html#buffer -- @field additional_caret_fore (number) --- The foreground color of additional carets in "0xBBGGRR" format. +-- The foreground color, in "0xBBGGRR" format, of additional carets. -- @field additional_carets_blink (bool) --- Whether additional carets will blink. +-- Allow additional carets to blink. +-- The default value is `true`. -- @field additional_carets_visible (bool) --- Whether additional carets are visible. +-- Display additional carets. +-- The default value is `true`. -- @field additional_sel_alpha (number) --- The alpha of additional selections. Alpha ranges from `0` (transparent) to --- `255` (opaque) or `256` for no alpha. +-- The alpha value, ranging from `0` (transparent) to `255` (opaque), of +-- additional selections. +-- The default value is `256`, for no alpha. -- @field additional_sel_back (number) --- The background color of additional selections in "0xBBGGRR" format. --- `buffer:set_sel_back(true, ...)` must have been called previously for this --- to have an effect. +-- The background color, in "0xBBGGRR" format, of additional selections. +-- This field has no effect when calling `buffer:set_sel_back(false, ...)`. -- @field additional_sel_fore (number) --- The foreground color of additional selections in "0xBBGGRR" format. --- `buffer:set_sel_fore(true, ...)` must have been called previously for this --- to have an effect. +-- The foreground color, in "0xBBGGRR" format, of additional selections. +-- This field has no effect when calling `buffer:set_sel_fore(false, ...)`. -- @field additional_selection_typing (bool) --- Whether typing can be performed into multiple selections. +-- Type into multiple selections. +-- The default value is `false`. +-- @field all_lines_visible (bool, Read-only) +-- Whether or not all lines in the buffer are visible. -- @field anchor (number) --- The position of the opposite end of the selection to the caret. +-- The position of the beginning of the selected text. -- @field annotation_lines (table, Read-only) --- Table of the number of annotation lines for lines starting from zero. +-- Table of the number of annotation lines for line numbers starting from +-- zero. -- @field annotation_style (table) --- Table of style numbers for annotations for lines starting at zero. +-- Table of style numbers for annotations for line numbers starting from zero. -- Only some style attributes are active in annotations: font, -- size/size_fractional, bold/weight, italics, fore, back, and character_set. -- @field annotation_style_offset (number) --- The start of the range of style numbers used for annotations. +-- The beginning of the range of style numbers used for annotations. -- Annotation styles may be completely separated from standard text styles by -- setting a style offset. For example, setting this to `512` would allow the -- annotation styles to be numbered from `512` upto `767` so they do not -- overlap styles set by lexers (or margins if margins offset is `256`). Each --- style number set with `buffer.annotation_style` has the offset added before +-- style number set with `annotation_style` has the offset added before -- looking up the style. +-- The default value is `0`. -- @field annotation_text (table) --- Table of annotation text for lines starting from zero. +-- Table of annotation text for line numbers starting from zero. -- @field annotation_visible (number) --- The visibility of annotations. +-- The annotation visibility mode. -- -- * `_SCINTILLA.constants.ANNOTATION_HIDDEN` (0) --- Annotations are not displayed. +-- Annotations are invisible. -- * `_SCINTILLA.constants.ANNOTATION_STANDARD` (1) --- Annotations are drawn left justified with no adornment. +-- Draw annotations left-justified with no decoration. -- * `_SCINTILLA.constants.ANNOTATION_BOXED` (2) --- Annotations are indented to match the text and are surrounded by a box. +-- Indent annotations to match the text and outline with a box. +-- +-- The default value is `0`. -- @field auto_c_auto_hide (bool) --- Whether or not autocompletion is hidden automatically when nothing matches. --- By default, the list is cancelled if there are no viable matches (the user --- has typed characters that no longer match a list entry). +-- Automatically hide the autocompletion list when no entries match typed +-- text. +-- The default value is `true`. -- @field auto_c_cancel_at_start (bool) --- Whether auto-completion is cancelled by backspacing to a position before --- where the box was created. --- If `false`, the list is not cancelled until the caret moves at least one --- character before the word being completed. If `true`, cancel if the user --- backspaces to a position before where it was created. --- @field auto_c_case_insensitive (int) --- Auto-completion case insensitive behavior. --- When autocompletion is set to ignore case (`buffer.auto_c_ignore_case`), by --- default it will nonetheless select the first list member that matches in a --- case sensitive way to entered characters. +-- Cancel autocompletion when backspacing to a position before where +-- autocompletion started or before the word being completed. +-- The default value is `true`, to cancel when backspacing before where +-- autocompletion started. +-- @field auto_c_case_insensitive_behaviour (number) +-- The behavior setting for case insensitive autocompletion when +-- [`buffer.auto_c_ignore_case`](#auto_c_ignore_case) is `true`. -- -- * `_SCINTILLA.constants.SC_CASEINSENSITIVEBEHAVIOR_RESPECTCASE` (0) --- Prefer case-sensitive matches. +-- Prefer to select case-sensitive matches. -- * `_SCINTILLA.constants.SC_CASEINSENSITIVEBEHAVIOR_IGNORECASE` (1) -- No preference. +-- +-- The default value is `0`. -- @field auto_c_choose_single (bool) --- Whether a single item auto-completion list automatically choose the item. --- The default is to display the list even if there is only a single item. +-- Automatically choose the item in a single-item autocompletion list. +-- The default value is `false`. -- @field auto_c_current (number, Read-only) --- The currently selected item position in the auto-completion list. +-- The index of the currently selected item in the autocompletion list. -- @field auto_c_current_text (string, Read-only) --- The currently selected item text in the auto-completion list. +-- The text of the currently selected item in the autocompletion list. -- @field auto_c_drop_rest_of_word (bool) --- Whether or not autocompletion deletes any word characters after the --- inserted text upon completion. --- The default is `false`. +-- Delete word characters after autocompleted text. +-- The default value is `false`. -- @field auto_c_fill_ups (string, Write-only) --- A set of characters that when typed will cause the autocompletion to choose --- the selected item. --- By default, no fillup characters are set. +-- A set of characters that choose the currently selected item in an +-- autocompletion list when typed. +-- The default value is an empty string. -- @field auto_c_ignore_case (bool) --- Whether case is significant when performing auto-completion searches. --- By default, matching of characters to list members is case sensitive. +-- Ignore case when searching an autocompletion list for matches. +-- The default value is `false`. -- @field auto_c_max_height (number) --- The maximum height, in rows, of auto-completion and user lists. --- The default is 5 rows. +-- The maximum number of items to show in autocompletion and user lists. The +-- default value is `5`. -- @field auto_c_max_width (number) --- The maximum width, in characters, of auto-completion and user lists. --- Set to `0` to autosize to fit longest item, which is the default. +-- The maximum number of characters per row to show in autocompletion and user +-- lists. +-- The default value is `0`, which automatically sizes the list to fit the +-- longest item. -- @field auto_c_separator (number) --- The auto-completion list separator character byte. --- The default is the space character. +-- The character byte that separates autocompletion list items. +-- The default value is `32` (' '). -- @field auto_c_type_separator (number) --- The auto-completion list type-separator character byte. --- The default is `63` ('?'). Autocompletion list items may display an image --- as well as text. Each image is first registered with an integer type. Then --- this integer is included in the text of the list separated by a '?' from --- the text. +-- The character byte that separates autocompletion list items and their +-- image types. +-- Autocompletion list items can display both an image and text. Register +-- images and their types using [`buffer:register_image()`](#register_image) +-- or [`buffer:register_rgba_image()`](#register_rgba_image) before appending +-- image types to list items after type separator characters. +-- The default value is 63 ('?'). -- @field back_space_un_indents (bool) --- Whether a backspace pressed when caret is within indentation unindents. +-- Un-indent text when backspacing within indentation. +-- The default value is `false`. -- @field buffered_draw (bool) --- Whether drawing is buffered. --- If drawing is buffered then each line of text is drawn into a bitmap buffer --- before drawing it to the screen to avoid flicker. The default is for --- drawing to be buffered. first or directly onto the screen. +-- Buffer drawing to avoid flickering. +-- Buffering draws each line of text into a bitmap buffer before drawing the +-- bitmap to the screen. +-- The default value is `true`. -- @field call_tip_back (number, Write-only) --- The background color for the call tip in "0xBBGGRR" format. +-- The background color, in "0xBBGGRR" format, for a call tip. -- @field call_tip_fore (number, Write-only) --- The foreground color for the call tip in "0xBBGGRR" format. +-- The foreground color, in "0xBBGGRR" format, for a call tip. -- @field call_tip_fore_hlt (number, Write-only) --- The foreground color for the highlighted part of the call tip in "0xBBGGRR" --- format. +-- The foreground color, in "0xBBGGRR" format, for the highlighted part of a +-- call tip. -- @field call_tip_position (boolean) --- The position of calltip, above or below text. --- By default the calltip is displayed below the text. Setting to `true` will --- display it above the text. +-- Display the call tip above or below the text. +-- The default value is `false` to display the call tip below the text. -- @field call_tip_use_style (number) --- Enable use of `_SCINTILLA.constants.STYLE_CALLTIP` and set call tip tab --- size in pixels. --- If the tab size is less than `1`, Tab characters are not treated specially. +-- The size in pixels of tab characters in call tips. +-- When non-zero, also enables the use of `_SCINTILLA.constants.STYLE_CALLTIP` +-- instead of `_SCINTILLA.constants.STYLE_DEFAULT` for call tip styles. +-- The default value is `0`, which does not treat tab characters specially. -- @field caret_fore (number) --- The foreground color of the caret in "0xBBGGRR" format. +-- The foreground color, in "0xBBGGRR" format, of the caret. -- @field caret_line_back (number) --- The color of the background of the line containing the caret in "0xBBGGRR" --- format. +-- The background color, in "0xBBGGRR" format, of the line containing the +-- caret. -- @field caret_line_back_alpha (number) --- The background alpha of the caret line. --- Alpha ranges from `0` (transparent) to `255` (opaque) or `256` for no --- alpha. +-- The background alpha value, ranging from `0` (transparent) to `255` +-- (opaque), of the caret line. +-- The default value is `256`, for no alpha. -- @field caret_line_visible (bool) --- Whether the background of the line containing the caret is in a different --- color. +-- Color the background of the line containing the caret a different color. +-- The default value is `false`. -- @field caret_period (number) --- The time in milliseconds that the caret is on and off. --- Setting the period to `0` stops the caret blinking. The default value is --- 500 milliseconds. +-- The time in milliseconds between caret blinks. +-- A value of `0` stops blinking. +-- The default value is `500`. -- @field caret_sticky (number) --- The caret preferred x position changing when the user types. +-- The preferred horizontal position of the caret when moving between lines. -- -- * `_SCINTILLA.constants.SC_CARETSTICKY_OFF` (0) --- All text changes (and all caret position changes) will remember the --- caret's new horizontal position when moving to different lines. --- This is the default. +-- Use the same position as on the previous line. -- * `_SCINTILLA.constants.SC_CARETSTICKY_ON` (1) --- The only thing which will cause the editor to remember the horizontal --- caret position is moving the caret with mouse or keyboard (left/right --- arrow keys, home/end keys, etc). +-- Use the last position the caret was moved to via the mouse, left/right +-- arrow keys, home/end keys, etc. Typing text does not affect the position. -- * `_SCINTILLA.constants.SC_CARETSTICKY_WHITESPACE` (2) --- The caret acts like sticky off except under one special case; when space --- or tab characters are inserted. (Including pasting *only space/tabs* -- --- undo, redo, etc. do not exhibit this behavior.) +-- Use the same position as on the previous line, but prior to any inserted +-- indentation. +-- +-- The default value is `0`. -- @field caret_style (number) --- The style of the caret to be drawn. +-- The style of caret to draw. -- -- * `_SCINTILLA.constants.CARETSTYLE_INVISIBLE` (0) --- Not draw the caret at all. +-- No caret. -- * `_SCINTILLA.constants.CARETSTYLE_LINE` (1) --- A line caret. This is the default value. +-- A line caret. -- * `_SCINTILLA.constants.CARETSTYLE_BLOCK` (2) -- A block caret. +-- +-- The default value is `1`. -- @field caret_width (number) --- The width of the insert mode caret in pixels. --- Can be `0`, `1`, `2` or `3` pixels. The default width is 1 pixel. This --- setting only affects the width of the cursor when the cursor style is set --- to line caret mode, it does not affect the width for a block caret. +-- The pixel width of the caret in insert mode, either `0`, `1`, `2`, or `3`, +-- and only applicable to line carets. +-- The default value is `1`. -- @field char_at (table, Read-only) --- Table of character bytes at positions in the document starting at zero. +-- Table of character bytes at positions in the buffer starting from zero. -- @field code_page (number) --- The code page used to interpret the bytes of the document as characters. --- The `_SCINTILLA.constants.SC_CP_UTF8` value can be used to enter Unicode --- mode. +-- The code page used to interpret buffer bytes as characters. +-- +-- + `0` None. +-- + `932` Japanese Shift-JIS. +-- + `936` Simplified Chinese GBK. +-- + `949` Korean Unified Hangul Code. +-- + `950` Traditional Chinese Big5. +-- + `1361` Korean Johab. +-- + `_SCINTILLA.constants.SC_CP_UTF8` (65001) UTF-8. +-- +-- The default value is `0`. -- @field column (table, Read-only) --- Table of column numbers, taking tab widths into account, for positions --- starting from zero. +-- Table of column numbers, taking tab widths into account, for positions in +-- the buffer starting from zero. -- @field control_char_symbol (number) --- The way control characters are displayed. --- If less than `32`, keep the rounded rectangle as ASCII mnemonics. --- Otherwise, use the given character byte. The default value is `0`. +-- The byte value of the character displayed in place of control characters, +-- characters whose byte values are less than 32. Values less than 32 dispay +-- ASCII mnemonics instead. +-- The default value is `0`. -- @field current_pos (number) -- The position of the caret. --- When setting, the caret is not scrolled into view. +-- When set, does not scroll the caret into view. -- @field cursor (number) -- The cursor type. -- -- * `_SCINTILLA.constants.SC_CURSORNORMAL` (-1) --- The normal cursor is displayed. +-- The normal cursor. -- * `_SCINTILLA.constants.SC_CURSORWAIT` (4) --- The wait cursor is displayed when the mouse is over the view. --- @field direct_function (number, Read-only) --- A pointer to a function that processes messages for this view. --- @field direct_pointer (number, Read-only) --- A pointer value to use as the first argument when calling the function --- returned by direct_function. --- @field dirty (bool) --- Flag indicating whether or not the buffer has been modified since it was --- last saved. --- @field eol_mode (number) --- The current end of line mode. +-- The wait cursor. -- --- * `_SCINTILLA.constants.SC_EOL_CRLF` (0) --- "CR+LF" ("\r\n"). --- * `_SCINTILLA.constants.SC_EOL_CR` (1) --- "CR" ("\r"). --- * `_SCINTILLA.constants.SC_EOL_LF` (2) --- "LF" ("\n"). +-- The default value is `-1`. +-- @field dirty (bool) +-- Whether or not the buffer has unsaved changes. +-- Unlike [`buffer.modify`](#modify), this field is accessible from any +-- buffer, not just the global one. -- @field edge_colour (number) --- The color used in edge indication in "0xBBGGRR" format. +-- The color, in "0xBBGGRR" format, used for the long line marker. -- @field edge_column (number) --- The column number which text should be kept within. +-- The column number to display the long line marker at. -- @field edge_mode (number) --- The edge highlight mode. +-- The long line edge mode. -- -- * `_SCINTILLA.constants.EDGE_NONE` (0) --- Long lines are not marked. This is the default state. +-- Long lines are not marked. -- * `_SCINTILLA.constants.EDGE_LINE` (1) --- A vertical line is drawn at the column number set by --- `buffer.edge_column`. +-- Draw a vertical line whose color is [`buffer.edge_colour`](#edge_colour) +-- at column [`buffer.edge_column`](#edge_column). -- * `_SCINTILLA.constants.EDGE_BACKGROUND` (2) --- The background color of characters after the column limit is changed to --- the color set by `buffer.edge_colour`. +-- Change the background color of characters after column +-- [`buffer.edge_column`](#edge_column) to +-- [`buffer.edge_colour`](#edge_colour). -- @field encoding (string or nil) --- The encoding of the file on the hard disk. --- It will be `nil` if the file is a binary file. +-- The string encoding of the file on the hard drive or `nil` for binary +-- files. -- @field encoding_bom (string) --- The byte-order mark of the file encoding (if any). +-- The byte-order mark, if any, of the file encoding. -- @field end_at_last_line (bool) --- Whether the maximum scroll position has the last line at the bottom of the --- view. --- If `false`, allows scrolling one page below the last line. The default --- value is `true`. +-- Disable scrolling past the last line. +-- The default value is `true`. -- @field end_styled (number, Read-only) -- The position of the last correctly styled character. +-- @field eol_mode (number) +-- The current end of line mode. +-- +-- * `_SCINTILLA.constants.SC_EOL_CRLF` (0) +-- "CR+LF" ("\r\n"). +-- * `_SCINTILLA.constants.SC_EOL_CR` (1) +-- "CR" ("\r"). +-- * `_SCINTILLA.constants.SC_EOL_LF` (2) +-- "LF" ("\n"). +-- +-- The default value is `0` on Windows platforms, `2` otherwise. -- @field extra_ascent (number) --- The extra ascent, the maximum that any style extends above the baseline, --- added to each line. +-- The amount of pixel padding above line text. +-- The default value is `0`. -- @field extra_descent (number) --- The extra descent, the maximum that any style extends below the baseline, --- added to each line. +-- The amount of pixel padding below line text. +-- The default is `0`. -- @field filename (string) --- The absolute path to the file associated with this buffer. --- It is encoded in UTF-8. Use [`string.iconv()`](string.html#iconv) for --- charset conversions. +-- The UTF-8-encoded absolute path to the file associated with the buffer. +-- Use [`string.iconv()`][] and [`_G._CHARSET`][] for charset conversions. +-- +-- [`string.iconv()`]: string.html#iconv +-- [`_G._CHARSET`]: _G.html#_CHARSET -- @field first_visible_line (number) --- The display line at the top of the display. --- @field focus (bool) --- The internal focus flag. --- @field fold_expanded (bool) --- Expanded state of a header line. +-- The line number of the line at the top of the view, starting from zero. +-- @field fold_expanded (table) +-- Table of flags indicating whether or not folds are expanded for line +-- numbers starting from zero. +-- Setting expanded fold states does not toggle folds; it only updates fold +-- margin markers. Use [`buffer:toggle_fold()`](#toggle_fold) instead. -- @field fold_flags (number) --- The style options for folding. --- Bits set in flags determine where folding lines are drawn: +-- Bit-mask of options for drawing folding lines. -- -- * `_SCINTILLA.constants.SC_FOLDFLAG_LINEBEFORE_EXPANDED` (2) --- Draw above if expanded. +-- Draw lines above expanded folds. -- * `_SCINTILLA.constants.SC_FOLDFLAG_LINEBEFORE_CONTRACTED` (4) --- Draw above if not expanded. +-- Draw lines above collapsed folds. -- * `_SCINTILLA.constants.SC_FOLDFLAG_LINEAFTER_EXPANDED` (8) --- Draw below if expanded. +-- Draw lines below expanded folds. -- * `_SCINTILLA.constants.SC_FOLDFLAG_LINEAFTER_CONTRACTED` (16) --- Draw below if not expanded. +-- Draw lines below collapsed folds. +-- +-- The default value is `0`. -- @field fold_level (table) --- Table of fold levels for lines starting from zero. --- Fold levels encodes an integer level along with flags indicating whether --- the line is a header and whether it is effectively white space. +-- Table of fold level bit-masks for line numbers starting from zero. +-- Fold level masks are composed of an integer level combined with any of the +-- following bits: -- -- * `_SCINTILLA.constants.SC_FOLDLEVELBASE` (0x400) --- Initial fold level. +-- The initial fold level. -- * `_SCINTILLA.constants.SC_FOLDLEVELWHITEFLAG` (0x1000) --- Indicates that the line is blank. +-- The line is blank. -- * `_SCINTILLA.constants.SC_FOLDLEVELHEADERFLAG` (0x2000) --- Indicates that the line is a header (fold point). +-- The line is a header, or fold point. -- @field fold_parent (table, Read-only) --- Table of parent line numbers for child lines starting from zero. --- `-1` means no line was found. --- @field font_quality (number) (Windows only) --- The quality level for text. --- --- * `_SCINTILLA.constants.SC_EFF_QUALITY_DEFAULt` (0). --- * `_SCINTILLA.constants.SC_EFF_QUALITY_NON_ANTIALIASED` (1). --- * `_SCINTILLA.constants.SC_EFF_QUALITY_ANTIALIASED` (2). --- * `_SCINTILLA.constants.SC_EFF_QUALITY_LCD_OPTIMIZED` (3). --- @field gap_position (number, Read-only) --- A position which, to avoid performance costs, should not be within the --- range of a call to `buffer:get_range_pointer()`. +-- Table of parent line numbers (fold points) for child line numbers starting +-- from zero. +-- A line number of `-1` means no line was found. -- @field h_scroll_bar (bool) --- Whether the horizontal scroll bar is visible. --- Set to `false` to never see it and `true` to enable it again. The default --- state is to display it when needed. +-- Display the horizontal scroll bar. +-- The default value is `true`. -- @field highlight_guide (number) --- The highlighted indentation guide column. --- Set to `0` to cancel this highlight. +-- The indentation guide column number to highlight, or `0` to stop +-- highlighting. -- @field hotspot_active_underline (bool) --- Whether active hotspots are underlined. +-- Underline active hotspots. +-- The default value is `true`. -- @field hotspot_single_line (bool) --- Whether hotspots are limited to single line so hotspots on two lines do not --- merge. +-- Limit hotspots to a single line. +-- The default value is `true`. -- @field indent (number) --- Ihe number of spaces used for one level of indentation. --- For a width of `0`, the indent size is the same as the tab size. +-- The number of spaces used for one level of indentation. +-- The default value is `0`, which matches the tab size. -- @field indentation_guides (number) --- Indentation guides appearance. +-- The indentation guide drawing mode. -- Indentation guides are dotted vertical lines that appear within indentation --- white space every indent size columns. +-- whitespace at each level of indentation. -- -- * `_SCINTILLA.constants.SC_IV_NONE` (0) --- No indentation guides are shown. +-- Guides are not drawn. -- * `_SCINTILLA.constants.SC_IV_REAL` (1) --- Indentation guides are shown inside real indentation white space. +-- Draw guides only within indentation whitespace. -- * `_SCINTILLA.constants.SC_IV_LOOKFORWARD` (2) --- Indentation guides are shown beyond the actual indentation up to the --- level of the next non-empty line. --- If the previous non-empty line was a fold header then indentation guides --- are shown for one more level of indent than that line. This setting is --- good for Python. +-- Draw guides beyond the current line up to the level of the next non-empty +-- line, but with an additional level if the previous non-empty line is a +-- fold header. -- * `_SCINTILLA.constants.SC_IV_LOOKBOTH` (3) --- Indentation guides are shown beyond the actual indentation up to the --- level of the next non-empty line or previous non-empty line whichever is --- the greater. --- This setting is good for most languages. +-- Draw guides beyond the current line up to either the level of the +-- previous or next non-empty line, whichever is greater. +-- +-- The default value is `0`. -- @field indic_alpha (table) --- Table of alpha transparency values ranging from `0` (transparent) to `255` --- (opaque) or `256` (no alpha) for indicators from `0` to `31`. --- Used for drawing the fill color of the `INDIC_ROUNDBOX` and --- `INDIC_STRAIGHTBOX` rectangle. +-- Table of fill color alpha values, ranging from `0` (transparent) to `255` +-- (opaque), for indicator numbers from `0` to `31` whose styles are either +-- `INDIC_ROUNDBOX`, `INDIC_STRAIGHTBOX`, or `INDIC_DOTBOX`. +-- The default values are `256`, for no alpha. -- @field indic_fore (table) --- Table of foreground colors in "0xBBGGRR" format for indicators from `0` to --- `31`. +-- Table of foreground colors, in "0xBBGGRR" format, for indicator numbers +-- from `0` to `31`. -- @field indic_outline_alpha (table) --- Table of alpha transparency values ranging from `0` (transparent) to `255` --- (opaque) or `256` (no alpha) for indicators from `0` to `31`. --- Used for drawing the outline color of the `INDIC_ROUNDBOX` and --- `INDIC_STRAIGHTBOX` rectangle. +-- Table of outline color alpha values, ranging from `0` (transparent) to +-- `255` (opaque), for indicator numbers from `0` to `31` whose styles are +-- either `INDIC_ROUNDBOX`, `INDIC_STRAIGHTBOX`, or `INDIC_DOTBOX`. +-- The default values are `256`, for no alpha. -- @field indic_style (table) --- Table of styles for indicators from `0` to `31`. +-- Table of styles for indicator numbers from `0` to `31`. -- -- * `_SCINTILLA.constants.INDIC_PLAIN` (0) --- Underlined with a single, straight line. +-- An underline. -- * `_SCINTILLA.constants.INDIC_SQUIGGLE` (1) --- A squiggly underline. Requires 3 pixels of descender space. +-- A squiggly underline 3 pixels in height. -- * `_SCINTILLA.constants.INDIC_TT` (2) --- A line of small T shapes. +-- A line of small 'T' shapes. -- * `_SCINTILLA.constants.INDIC_DIAGONAL` (3) -- Diagonal hatching. -- * `_SCINTILLA.constants.INDIC_STRIKE` (4) -- Strike out. -- * `_SCINTILLA.constants.INDIC_HIDDEN` (5) --- An indicator with no visual effect. +-- Invisible. -- * `_SCINTILLA.constants.INDIC_BOX` (6) -- A rectangle around the text. -- * `_SCINTILLA.constants.INDIC_ROUNDBOX` (7) --- A rectangle with rounded corners around the text using translucent --- drawing with the interior usually more transparent than the border. Use --- `buffer.indic_alpha` and `buffer.indic_outline_alpha` to control the --- alpha transparency values. The default alpha values are `30` for fill --- color and `50` for outline color. +-- A translucent rectangle with rounded corners around the text. Use +-- [`buffer.indic_alpha`](#indic_alpha) and +-- [`buffer.indic_outline_alpha`](#indic_outline_alpha) to set the fill and +-- outline transparency, respectively. Their default values are `30` and +-- `50`. -- * `_SCINTILLA.constants.INDIC_STRAIGHTBOX` (8) --- A rectangle around the text using translucent drawing with the interior --- usually more transparent than the border. --- You can use `buffer.indic_alpha` and `buffer.indic_outline_alpha` to --- control the alpha transparency values. The default alpha values are `30` --- for fill color and `50` for outline color. +-- Similar to `INDIC_ROUNDBOX` but with sharp corners. -- * `_SCINTILLA.constants.INDIC_DASH` (9) -- A dashed underline. -- * `_SCINTILLA.constants.INDIC_DOTS` (10) -- A dotted underline. -- * `_SCINTILLA.constants.INDIC_SQUIGGLELOW` (11) --- Similar to `INDIC_SQUIGGLE` but only using 2 vertical pixels so will fit --- under small fonts. +-- A squiggly underline 2 pixels in height. -- * `_SCINTILLA.constants.INDIC_DOTBOX` (12) --- A dotted rectangle around the text using translucent drawing. --- Translucency alternates between the alpha and outline alpha settings with --- the top-left pixel using the alpha setting. `buffer.indic_alpha` and --- `buffer.indic_outline_alpha` control the alpha transparency values. --- The default values are `30` for alpha and `50` for outline alpha. To --- avoid excessive memory allocation the maximum width of a dotted box is --- 4000 pixels. +-- Similar to `INDIC_STRAIGHTBOX` but with a dotted outline. +-- Translucency alternates between [`buffer.indic_alpha`](#indic_alpha) and +-- [`buffer.indic_outline_alpha`](#indic_outline_alpha) starting with the +-- top-left pixel. -- * `_SCINTILLA.constants.INDIC_SQUIGGLEPIXMAP` (13) --- A version of `INDIC_SQUIGGLE` that draws using a pixmap instead of as a --- series of line segments for performance. Measured to be between 3 and 6 --- times faster than `INDIC_SQUIGGLE` on GTK+. Apperance will not be as good --- as `INDIC_SQUIGGLE` on OSX in HiDPI mode. --- * Use `_SCINTILLA.next_indic_number()` for custom indicators. +-- Identical to `INDIC_SQUIGGLE` but draws faster by using a pixmap instead +-- of multiple line segments. +-- +-- Use [`_SCINTILLA.next_indic_number()`][] for custom indicators. +-- +-- [`_SCINTILLA.next_indic_number()`]: _SCINTILLA.html#next_indic_number -- @field indic_under (table) --- Table of booleans for drawing under text or over (default) for indicators --- from `0` to `31`. +-- Table of flags indicating whether to draw indicators over text or under it +-- for indicator numbers from `0` to `31`. +-- For values to be `true`, [`buffer.two_phase_draw`](#two_phase_draw) must be +-- `true`. +-- The default values are `false` for drawing indicators over text. -- @field indicator_current (number) --- The indicator in the range of `0` to `31` used for --- `buffer:indicator_fill_range()` and `buffer:indicator_clear_range()`. +-- The indicator number in the range of `0` to `31` used by +-- [`buffer:indicator_fill_range()`](#indicator_fill_range) and +-- [`buffer:indicator_clear_range()`](#indicator_clear_range). -- @field indicator_value (number) --- The indicator value used for `buffer:indicator_fill_range()`. --- Currently all values are drawn the same. --- @field keys_unicode (bool) --- Interpret keyboard input as Unicode. +-- The indicator value used for +-- [`buffer:indicator_fill_range()`](#indicator_fill_range). +-- Currently, all values are drawn the same, but it may be possible to draw +-- different values in different styles in the future. -- @field layout_cache (number) --- The degree of caching of layout information. +-- The layout cache mode. -- -- * `_SCINTILLA.constants.SC_CACHE_NONE` (0) -- No lines are cached. -- * `_SCINTILLA.constants.SC_CACHE_CARET` (1) --- The line containing the text caret. --- This is the default. +-- Cache the line containing the caret. -- * `_SCINTILLA.constants.SC_CACHE_PAGE` (2) --- Visible lines plus the line containing the caret. +-- Cache visible lines. -- * `_SCINTILLA.constants.SC_CACHE_DOCUMENT` (3) --- All lines in the document. +-- Cache all lines in the buffer. +-- +-- The default value is `1`. -- @field length (number, Read-only) --- The number of bytes in the document. +-- The number of bytes in the buffer. -- @field lexer (number) --- The lexing language of the document. +-- The numeric ID of the Scintilla lexer used by the buffer. -- @field lexer_language (string) --- The name of the lexer. +-- The name of the Scintilla lexer used by the buffer. +-- You probably want to use [`buffer:get_lexer()`](#get_lexer) instead. -- @field line_count (number, Read-only) --- The number of lines in the document. +-- The number of lines in the buffer. -- There is always at least one. -- @field line_end_position (table, Read-only) --- Table of positions after the last visible characters on a line for lines --- starting from zero. +-- Table of positions at the ends of lines, but before any end of line +-- characters, for line numbers starting from zero. -- @field line_indent_position (table, Read-only) --- Table of positions before the first non indentation character on a line for --- lines starting from zero. +-- Table of positions at the ends of line indentation for line numbers +-- starting from zero. -- @field line_indentation (table) --- Table of line indentation amounts for lines starting from zero. --- The indentation is measured in character columns, which correspond to the --- width of space characters. +-- Table of line indentation amounts, measured in character columns, for line +-- numbers starting from zero. -- @field line_state (table) --- Table of extra styling information for lines starting from zero. --- As well as the 8 bits of lexical state stored for each character there is --- also an integer stored for each line. This can be used for longer lived --- parse states. --- @field line_visible (bool, Read-only) --- Is a line visible? +-- Table of integer line states for line numbers starting from zero. +-- Line states are used for storing longer lived parse states per line. They +-- are available in addition to the 8 bits of styling information per +-- character. +-- @field line_visible (table, Read-only) +-- Table of flags indicating whether or not lines are visible for line numbers +-- starting from zero. -- @field lines_on_screen (number, Read-only) --- The number of lines completely visible. --- @field lines_visible (bool, Read-only) --- Are all lines visible? +-- The number of completely visible lines in the view. +-- It is possible to have a partial line visible at the bottom of the view. -- @field main_selection (number) --- The main selection. --- The main selection may be displayed in different colors or with a --- differently styled caret. Only an already existing selection can be made --- main. +-- The main, or most recent, selection. +-- Only an existing selection can be made main. -- @field margin_cursor_n (table) --- Table of cursors shown for margins from zero to four. --- A reversed arrow cursor is normally shown over all margins. +-- Table of cursors shown for margin numbers from zero to four. -- --- * `_SCINTILLA.constants.SC_CURSORARROW` --- Normal arrow. --- * `_SCINTILLA.constants.SC_CURSORREVERSEARROW` --- Reversed arrow. +-- * `_SCINTILLA.constants.SC_CURSORARROW` (2) +-- Normal arrow cursor. +-- * `_SCINTILLA.constants.SC_CURSORREVERSEARROW` (7) +-- Reversed arrow cursor. +-- +-- The default values are `7`. -- @field margin_left (number) --- The size in pixels of the left margin. --- The default is to one pixel. +-- The size in pixels of the left margin of the buffer text. +-- The default value is `1`. -- @field margin_mask_n (table) --- Table of marker masks for margins from zero to four. --- A mask determines which markers are displayed in a margin. +-- Table of marker bit-masks for showing margin markers for margin numbers +-- from zero to four. +-- The default values are `0`, `0x1FFFFFF`, `0`, `0`, and `0`, for a line +-- margin and logical marker margin. -- @field margin_options (number) --- A bit mask of margin options. +-- A bit-mask of margin option settings. -- -- * `_SCINTILLA.constants.SC_MARGINOPTION_NONE` (0) --- None (default). +-- None. -- * `_SCINTILLA.constants.SC_MARGINOPTION_SUBLINESELECT` (1) --- Controls how wrapped lines are selected when clicking on margin in front --- of them. --- If set, only sub line of wrapped line is selected, otherwise whole --- wrapped line is selected. +-- Select only the sub-line of the wrapped line on margin click. +-- +-- The default value is `0`. -- @field margin_right (number) --- The size in pixels of the right margin. --- The default is to one pixel. +-- The size in pixels of the right margin of the buffer text. +-- The default value is `1`. -- @field margin_sensitive_n (table) --- Table of mouse click sensitivity booleans for margins from zero to four. --- A click in a sensitive margin emits a `MARGIN_CLICK` event. By default, all --- margins are insensitive. +-- Table of flags indicating whether or not mouse clicks in margins emit +-- `MARGIN_CLICK` events for margin numbers from zero to four. +-- The default values are `false`. -- @field margin_style (table) --- Table of style numbers for text margin lines starting from zero. +-- Table of style numbers for text margin line numbers starting from zero. -- Only some style attributes are active in text margins: font, -- size/size_fractional, bold/weight, italics, fore, back, and character_set. -- @field margin_style_offset (number) --- The start of the range of style numbers used for margin text. +-- The beginning of the range of style numbers used for margin text. -- Margin styles may be completely separated from standard text styles by -- setting a style offset. For example, setting this to `256` would allow the -- margin styles to be numbered from `256` upto `511` so they do not overlap --- styles set by lexers. Each style number set with `buffer.margin_style` has +-- styles set by lexers. Each style number set with `margin_style` has -- the offset added before looking up the style. -- @field margin_text (table) --- Table of text in the text margin for lines starting from zero. +-- Table of text in the text margin for line numbers starting from zero. -- @field margin_type_n (table) --- Table of margin types for margins from zero to four. +-- Table of margin types for margin numbers from zero to four. -- -- * `_SCINTILLA.constants.SC_MARGIN_SYMBOL` (0) -- A symbol margin. -- * `_SCINTILLA.constants.SC_MARGIN_NUMBER` (1) -- A line number margin. -- * `_SCINTILLA.constants.SC_MARGIN_BACK` (2) --- A symbol margin that sets its background color to match the default --- text background color. +-- A symbol margin whose background color matches the default text +-- background color. -- * `_SCINTILLA.constants.SC_MARGIN_FORE` (3) --- A symbol margin that sets its background color to match the default --- text foreground color. +-- A symbol margin whose foreground color matches the default text +-- foreground color. -- * `_SCINTILLA.constants.SC_MARGIN_TEXT` (4) -- A text margin. -- * `_SCINTILLA.constants.SC_MARGIN_RTEXT` (5) --- A right justified text margin. +-- A right-justified text margin. +-- +-- The default values are `true`, `false`, `false`, `false`, and `false`, for +-- a line number margin and symbol margins. -- @field margin_width_n (table) --- Table of margin widths expressed in pixes for margins from zero to four. +-- Table of margin widths in pixels for margin numbers from zero to four. -- @field marker_alpha (table, Write-only) --- Table of alpha values used for markers that are drawn in the text area, not --- the margin. --- Markers are numbers in the range of `0` to `31`. Alpha values are between --- `0` (transparent) and `255` (opaque), or `256` for no alpha. +-- Table of alpha values, ranging from `0` (transparent) to `255` (opaque), +-- used for markers drawn in the text area, not the margin, for markers +-- numbers from `0` to `31`. +-- The default values are `256`, for no alpha. -- @field marker_back (table, Write-only) --- Table of the background colors used for particular marker numbers. --- Marker numbers are in the range of `0` to `31`. Colors are in "0xBBGGRR" --- format. +-- Table of background colors, in "0xBBGGRR" format, used for marker numbers +-- from `0` to `31`. -- @field marker_back_selected (table, Write-only) --- Table of the background colors used for particular marker numbers when --- their folding blocks are selected. --- Marker numbers are in the range of `0` to `31`. Colors are in "0xBBGGRR" --- format. The default color is `0x0000FF`. +-- Table of background colors, in "0xBBGGRR" format, used for markers whose +-- folding blocks are selected for marker numbers from `0` to `31`. +-- The default values are `0x0000FF`. -- @field marker_fore (table, Write-only) --- Table of the foreground colors used for particular marker numbers. --- Marker numbers are in the range of `0` to `31`. Colors are in "0xBBGGRR" --- format. +-- Table of foreground colors, in "0xBBGGRR" format, used for marker numbers +-- from `0` to `31`. -- @field max_line_state (number, Read-only) --- The last line number that has line state. +-- The last line number with a non-zero line state. -- @field modify (bool) --- Whether the document is different from when it was last saved. --- @field mouse_down_captures (bool) --- Whether the mouse is captured when its button is pressed. +-- Whether or not the buffer has unsaved changes. +-- Unlike [`buffer.dirty`](#dirty), this field is accessible only from the +-- global buffer. -- @field mouse_dwell_time (number) --- The time the mouse must sit still to generate a mouse dwell event. --- If set to `_SCINTILLA.constants.SC_TIME_FOREVER`, the default, no dwell --- events are generated. --- @field multi_paste (bool) --- The effect of pasting when there are multiple selections. +-- The number of milliseconds the mouse must idle in order to generate a +-- `DWELL_START` event, or `_SCINTILLA.constants.SC_TIME_FOREVER` to never +-- generate one. +-- @field multi_paste (number) +-- The multiple selection paste mode. -- -- * `_SCINTILLA.constants.SC_MULTIPASTE_ONCE` (0) --- Pasted text can go into just the main selection (default). +-- Paste into only the main selection. -- * `_SCINTILLA.constants.SC_MULTIPASTE_EACH` (1) --- Pasted text can go into each selection. +-- Paste into all selections. +-- +-- The default value is `0`. -- @field multiple_selection (bool) --- Whether multiple selections can be made. --- When multiple selection is disabled, it is not possible to select multiple --- ranges by holding down the Ctrl key while dragging with the mouse. +-- Enable multiple selection. +-- The default value is `false`. -- @field overtype (bool) --- Overtype mode. +-- Enable overtype mode, where typed characters overwrite existing ones. +-- The default value is `false`. -- @field position_cache (number) -- The number of entries in the position cache. -- The position cache stores position information for short runs of text so -- that their layout can be determined more quickly if the run recurs. +-- The default value is `1024`. -- @field print_colour_mode (number) -- The print color mode. -- -- * `_SCINTILLA.constants.SC_PRINT_NORMAL` (0) --- Print using the current screen colors. --- This is the default. +-- Print with the current set of colors. -- * `_SCINTILLA.constants.SC_PRINT_INVERTLIGHT` (1) --- If you use a dark screen background this saves ink by inverting the light --- value of all colors and printing on a white background. +-- Print on a white background with the light values of the current color +-- set. +-- This mode is good for a dark background color. -- * `_SCINTILLA.constants.SC_PRINT_BLACKONWHITE` (2) --- Print all text as black on a white background. +-- Print black text on a white background. -- * `_SCINTILLA.constants.SC_PRINT_COLOURONWHITE` (3) --- Everything prints in its own color on a white background. +-- Print on a white background with the current color set. -- * `_SCINTILLA.constants.SC_PRINT_COLOURONWHITEDEFAULTBG` (4) --- Everything prints in its own color on a white background except that line --- numbers use their own background color. +-- Print on a white background with the current color set except for line +-- numbers which use their own background color. -- @field print_magnification (number) --- The print magnification added to the point size of each style for printing. +-- The number of points to add to the size of each font when printing. +-- Negative values are allowed. +-- The default value is `0`. -- @field print_wrap_mode (number) --- Printing line wrap mode. +-- The print line wrap mode. -- -- * `_SCINTILLA.constants.SC_WRAP_NONE` (0) --- Each line of text generates one line of output and the line is truncated --- if it is too long to fit into the print area. +-- Truncate long lines. -- * `_SCINTILLA.constants.SC_WRAP_WORD` (1) --- Wraps printed output so that all characters fit into the print rectangle. --- Tries to wrap only between words as indicated by white space or style --- changes although if a word is longer than a line, it will be wrapped --- before the line end. This is the default. --- * `_SCINTILLA.constants.SC_WRAP_CHAR` (2). +-- Wrap long lines at word boundaries if possible. +-- * `_SCINTILLA.constants.SC_WRAP_CHAR` (2) +-- Wrap long lines at character boundaries. -- @field property (table) --- Table of keyword:value string pairs used by a lexer for some optional --- features. --- @field property_expanded (table) --- Table of keyword:value string pairs used by a lexer for some optional --- features with `$()` variable replacement on returned string. +-- Map of key-value string pairs used by lexers. +-- @field property_expanded (table, Read-only) +-- Map of key-value string pairs used by lexers with `$()` variable +-- replacement performed in values. -- @field property_int (table, Read-only) --- Interprets `buffer.property[keyword]` as an integer if found or returns --- `0`. +-- Map of key-value pairs used by lexers with values interpreted as numbers, +-- or `0` if not found. -- @field punctuation_chars (string) --- The set of characters making up punctuation characters. --- Use after setting `buffer.word_chars`. +-- The set of characters considered to be punctuation characters. +-- Set this only after setting [`buffer.word_chars`](#word_chars). +-- The default value is a string containing all characters not considered to +-- be whitespace or word characters. -- @field read_only (bool) --- Read-only mode. +-- Whether or not the buffer is read-only. +-- The default value is `false`. -- @field rectangular_selection_anchor (number) -- The position of the anchor of the rectangular selection. -- @field rectangular_selection_anchor_virtual_space (number) @@ -611,161 +624,198 @@ -- @field rectangular_selection_caret_virtual_space (number) -- The amount of virtual space for the caret of the rectangular selection. -- @field rectangular_selection_modifier (number) --- The modifier key used to indicate that a rectangular selection should be --- created when combined with a mouse drag. +-- The modifier key used in combination with a mouse drag to create a +-- rectangular selection. -- -- * `_SCINTILLA.constants.SCMOD_CTRL` (2) --- Control key (default). +-- The "Control" modifier key. -- * `_SCINTILLA.constants.SCMOD_ALT` (4) --- Alt key. +-- The "Alt" modifier key. -- * `_SCINTILLA.constants.SCMOD_SUPER` (8) --- Left Windows key on a Windows keyboard or the Command key on a Mac. +-- The "Super" modifier key, usually defined as the left "Windows" or +-- "Command" key. +-- +-- The default value is `2`. -- @field rgba_image_height (number) --- The height for future RGBA image data. +-- The height for an RGBA image to be defined using +-- [`buffer:marker_define_rgba_image()`](#marker_define_rgba_image). -- @field rgba_image_scale (number) --- The scale factor in percent for future RGBA image data. +-- The scale factor in percent for an RGBA image to be defined using +-- [`buffer:marker_define_rgba_image()`](#marker_define_rgba_image). -- This is useful on OSX with a retina display where each display unit is 2 -- pixels: use a factor of `200` so that each image pixel is dsplayed using a -- screen pixel. The default scale, `100`, will stretch each image pixel to -- cover 4 screen pixels on a retina display. -- @field rgba_image_width (number) --- The width for future RGBA image data. +-- The width for an RGBA image to be defined using +-- [`buffer:marker_define_rgba_image()`](#marker_define_rgba_image). -- @field scroll_width (number) --- The document width assumed for scrolling. --- For performance, the view does not measure the display width of the --- document to determine the properties of the horizontal scroll bar. Instead, --- an assumed width is used. The default value is `2000`. To ensure the width --- of the currently visible lines can be scrolled use --- `buffer.scroll_width_tracking`. +-- The assumed document width for horizontal scrolling purposes. +-- 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 +-- [`buffer.scroll_width_tracking`](#scroll_width_tracking). +-- The default value is `2000`. -- @field scroll_width_tracking (bool) --- Whether the maximum width line displayed is used to set scroll width. +-- Set the scroll width to the maximum width of a displayed line beyond +-- [`buffer.scroll_width`](#scroll_width). +-- The default value is `false`. -- @field search_flags (number) --- The search flags used by `buffer:search_in_target()`. +-- The bit-mask of search flags used by +-- [`buffer:search_in_target()`](#search_in_target). -- -- * `_SCINTILLA.constants.SCFIND_WHOLEWORD` (2) --- A match only occurs with text that matches the case of the search string. +-- Match text surrounded by non-word characters. -- * `_SCINTILLA.constants.SCFIND_MATCHCASE` (4) --- A match only occurs if the characters before and after are not word --- characters. +-- Match text case sensitively. -- * `_SCINTILLA.constants.SCFIND_WORDSTART` (0x00100000) --- A match only occurs if the character before is not a word character. +-- Match text when the previous character is a non-word character. -- * `_SCINTILLA.constants.SCFIND_REGEXP` (0x00200000) --- The search string should be interpreted as a regular expression. +-- Interpret the search string as a regular expression. -- * `_SCINTILLA.constants.SCFIND_POSIX` (0x00400000) --- Treat regular expression in a more POSIX compatible manner by --- interpreting bare '(' and ')' for tagged sections rather than "\\(" and --- "\\)". +-- Interpret '(' and ')' as tags instead of "\\(" and "\\)" in a regular +-- expression. +-- +-- The default value is `0`. -- @field sel_alpha (number) --- The alpha of the selection, between `0` (transparent) and `255` (opaque), --- or `256` for no alpha. +-- The alpha value, ranging from `0` (transparent) to `255` (opaque), of the +-- selection. +-- The default value is `256`, for no alpha. -- @field sel_eol_filled (bool) --- The selection end of line fill. --- The selection can be drawn up to the right hand border by setting this --- property. +-- Extend the selection to the right margin of the view. +-- The default value is `false`. -- @field selection_empty (bool, Read-only) --- Is every selected range empty? +-- Whether or not no text is selected. -- @field selection_end (number) --- The position that ends the selection - this becomes the current position. --- This does not make the caret visible. +-- The position of the end of the selected text. +-- When set, becomes the current position, but is not scrolled into view. -- @field selection_is_rectangle (bool, Read-only) --- Is the selection rectangular? --- The alternative is the more common stream selection. +-- Whether or not the selection is a rectangular selection. -- @field selection_mode (number) --- The mode of the current selection. +-- The selection mode. -- -- * `_SCINTILLA.constants.SC_SEL_STREAM` (0) --- Stream. +-- Character selection. -- * `_SCINTILLA.constants.SC_SEL_RECTANGLE` (1) --- Rectangle. +-- Rectangular selection. -- * `_SCINTILLA.constants.SC_SEL_LINES` (2) --- Lines. +-- Line selection. -- * `_SCINTILLA.constants.SC_SEL_THIN` (3) --- Thin rectangular. +-- Thin rectangular selection. This is the mode after a rectangular +-- selection has been typed into and ensures that no characters are +-- selected. +-- +-- When set, caret movement alters the selected text until this field is set +-- again to the same value or [`buffer:cancel()`](#cancel) is called. -- @field selection_n_anchor (table) --- Table of anchor positions for existing selections starting from zero, the +-- Table of anchor positions for existing selections numbered from zero, the -- main selection. -- @field selection_n_anchor_virtual_space (table) -- Table of the amount of virtual space for anchors for existing selections --- starting from zero, the main selection. +-- numbered from zero, the main selection. -- @field selection_n_caret (table) --- Table of caret positions for existing selections starting from zero, the +-- Table of caret positions for existing selections numbered from zero, the -- main selection. -- @field selection_n_caret_virtual_space (table) -- Table of the amount of virtual space for carets for existing selections --- starting from zero, the main selection. +-- numbered from zero, the main selection. -- @field selection_n_end (table) --- Table of positions that end selections for existing selections starting --- from zero, the main selection. +-- Table of positions at the end of existing selections numbered from zero, +-- the main selection. -- @field selection_n_start (table) --- Table of positions that start selections for existing selections starting --- from zero, the main selection. +-- Table of positions at the beginning of existing selections numbered from +-- zero, the main selection. -- @field selection_start (number) --- The position that starts the selection - this becomes the anchor. --- This does not make the caret visible. +-- The position of the beginning of the selected text. +-- When set, becomes the anchor, but is not scrolled into view. -- @field selections (number, Read-only) --- The number of selections currently active. --- @field status (number) --- The error status. --- --- * `_SCINTILLA.constants.SC_STATUS_OK` (0) --- No failures. --- * `_SCINTILLA.constants.SC_STATUS_FAILURE` (1) --- Generic failure. --- * `_SCINTILLA.constants.SC_STATUS_BADALLOC` (2) --- Memory is exhausted. +-- The number of active selections. -- @field style_at (table, Read-only) --- Table of style bytes at positions in the document starting at zero. +-- Table of style bytes at positions in the buffer starting from zero. -- @field style_back (table) --- Table of background colors in "0xBBGGRR" format for styles from `0` to --- `255`. +-- Table of background colors, in "0xBBGGRR" format, for style numbers from +-- `0` to `255`. -- @field style_bits (number) --- The number of bits in style bytes used to hold the lexical state. +-- The number of bits in an 8-bit style byte to use for styling. +-- The number of styling bits required by the current lexer is +-- [`buffer.style_bits_needed`](#style_bits_needed). +-- The default value is `5`. -- @field style_bits_needed (number, Read-only) --- The number of bits the current lexer needs for styling. +-- The number of styling bits required by the current lexer. -- @field style_bold (table) --- Table of booleans for bold styles from `0` to `255`. +-- Table of flags indicating whether or not text within styles has a bold font +-- face for style numbers from `0` to `255`. +-- The default values are `false`. -- @field style_case (table) --- Table of cases for styles from `0` to `255`. +-- Table of letter case modes for text within styles for style numbers from +-- `0` to `255`. -- -- * `_SCINTILLA.constants.SC_CASE_MIXED` (0) --- Normal, mixed case. +-- Display text in mixed case. -- * `_SCINTILLA.constants.SC_CASE_UPPER` (1) --- Upper case. +-- Display text in upper case. -- * `_SCINTILLA.constants.SC_CASE_LOWER` (2) --- Lower case. +-- Display text in lower case. +-- +-- The default values are `0`. -- @field style_changeable (table) --- Table of booleans for changeable styles from `0` to `255`. --- The default setting is `true`. +-- Table of flags indicating whether or not text within styles is changeable +-- for style numbers from `0` to `255`. +-- The default values are `true`. +-- Currently, read-only styles do not allow the caret into the range of text, +-- but ranges containing read-only text are deletable. -- @field style_character_set (table) --- Table of character sets for styles from `0` to `255`. +-- Table of character sets for style numbers from `0` to `255`. +-- +-- * `_SCINTILLA.constants.SC_CHARSET_ANSI` (0) +-- * `_SCINTILLA.constants.SC_CHARSET_DEFAULT` (1) +-- * `_SCINTILLA.constants.SC_CHARSET_CYRILLIC` (1251) +-- * `_SCINTILLA.constants.SC_CHARSET_EASTEUROPE` (238) +-- * `_SCINTILLA.constants.SC_CHARSET_GB2312` (134) +-- * `_SCINTILLA.constants.SC_CHARSET_HANGUL` (129) +-- * `_SCINTILLA.constants.SC_CHARSET_RUSSIAN` (204) +-- * `_SCINTILLA.constants.SC_CHARSET_SHIFTJIS` (128) +-- * `_SCINTILLA.constants.SC_CHARSET_8859_15` (1000) +-- +-- The default values are `1`. -- @field style_eol_filled (table) --- Table of booleans for end of line filled styles from `0` to `255`. +-- Table of flags indicating whether or not to extend the background colors of +-- styles whose characters occur last on lines all the way to the right margin +-- of the view for style numbers from `0` to `255`. +-- The default values are `false`. -- @field style_font (table) --- Table of font faces for styles from `0` to `255`. +-- Table of font faces for style numbers from `0` to `255`. -- @field style_fore (table) --- Table of foreground colors in "0xBBGGRR" format for styles from `0` to --- `255`. +-- Table of foreground colors, in "0xBBGGRR" format, for style numbers from +-- `0` to `255`. -- @field style_hot_spot (table) --- Table of boolean hotspot styles from `0` to `255`. +-- Table of flags indicating whether or not text within styles is clickable +-- for style numbers from `0` to `255`. +-- The default values are `false`. -- @field style_italic (table) --- Table of booleans for italic styles from `0` to `255`. +-- Table of flags indicating whether or not text within styles has an italic +-- font face for style numbers from `0` to `255`. +-- The default values are `false`. -- @field style_size (table) --- Table of font sizes for styles from `0` to `255`. --- Font size is a whole number of points. +-- Table of font sizes, expressed in whole number points, for style numbers +-- from `0` to `255`. -- @field style_size_fractional (table) --- Table of sizes of characters for styles from `0` to `255`. --- Size is in hundreths of a point and multiplied by 100 internally. For --- example, a text size of 9.4 points is set with 940. +-- Table of character sizes, expressed in hundredths of a point, for style +-- numbers from `0` to `255`. +-- For example, a text size of 9.4 points is set using `940`. -- @field style_underline (table) --- Table of booleans for underlined styles from `0` to `255`. +-- Table of flags indicating whether or not text within styles has an +-- underlined font face for style numbers from `0` to `255`. +-- The default values are `false`. -- @field style_visible (table) --- Table of booleans for visible styles from `0` to `255`. +-- Table of flags indicating whether or not text within styles is visible for +-- style numbers from `0` to `255`. +-- The default values are `true`. -- @field style_weight (table) --- Table of character weights for styles from `0` to `255`. --- The weight or boldness of a font can be set with a number between 1 and 999 --- with 1 being very light and 999 very heavy. While any value can be used, --- fonts often only support between 2 and 4 weights with three weights being --- common enough to use symbolic names: +-- Table of character weights ranging from `1` (very light) to `999` (very +-- heavy) for text within styles for style numbers from `0` to `255`. +-- However, most fonts only support a small number of weights: -- -- * `_SCINTILLA.constants.SC_WEIGHT_NORMAL` (400) -- Normal. @@ -773,422 +823,444 @@ -- Semi-bold. -- * `_SCINTILLA.constants.SC_WEIGHT_BOLD` (700) -- Bold. +-- +-- The default values are `400`. -- @field tab_indents (bool) --- Whether a tab pressed when caret is within indentation indents. +-- Tabbing indents within indentation. +-- The default value is `false`. -- @field tab_width (number) --- The visible size of a tab as a multiple of the width of a space character. --- The default tab width is 8 characters. +-- The number of space characters represented by a tab character. +-- The default value is `8`. -- @field tag (table) --- Table of values of tags from a regular expression search. +-- List of tag match values from a regular expression search. -- @field target_end (number) --- The position that ends the target which is used for updating the document --- without affecting the scroll position. --- The target is also set by a successful `buffer:search_in_target()`. +-- The position of the end of the target range. +-- This is also set by a successful +-- [`buffer:search_in_target()`](#search_in_target). -- @field target_start (number) --- The position that starts the target which is used for updating the document --- without affecting the scroll position. --- The target is also set by a successful `buffer:search_in_target()`. +-- The position of the beginning of the target range. +-- This is also set by a successful +-- [`buffer:search_in_target()`](#search_in_target). -- @field text_length (number, Read-only) --- The number of characters in the document. +-- The number of characters in the buffer. -- @field two_phase_draw (bool) --- Two phase drawing mode. --- When `true`, drawing is performed in two phases, first the background and --- then the foreground. This avoids chopping off characters that overlap the --- next run. The default is for drawing to be two phase. +-- Draw in two phases: first the background and then the foreground. +-- The default is `true`. -- @field undo_collection (bool) --- Whether to collect undo information. --- When stopping collection, use `buffer:empty_undo_buffer()` to avoid the --- undo buffer being unsynchronized with the data in the buffer. +-- Collect undo information. +-- When setting to `false`, call +-- [`buffer:empty_undo_buffer()`](#empty_undo_buffer) to avoid desynchronizing +-- the undo buffer with the buffer text. +-- The default value is `true`. -- @field use_tabs (bool) --- Whether tabs will be used in indentation. --- The default is `true`. `false` will only use space characters. +-- Use tabs or spaces in indentation. +-- The default value is `true`, for using tabs. -- @field v_scroll_bar (bool) --- Whether the vertical scroll bar is visible. --- Set to `false` to never see it and `true` to enable it again. The default --- state is to display it when required. +-- Display the vertical scroll bar. +-- The default value is `true`. -- @field view_eol (bool) --- Whether the end of line characters are visible. --- Normally, the end of line characters are hidden. +-- Display end of line characters. +-- The default value is `false`. -- @field view_ws (number) --- The visibility of white space characters. +-- The whitespace character visibility mode. -- -- * `_SCINTILLA.constants.SCWS_INVISIBLE` (0) --- The normal display mode with white space displayed as an empty background --- color. +-- Whitespace is invisible. -- * `_SCINTILLA.constants.SCWS_VISIBLEALWAYS` (1) --- White space characters are drawn as dots and arrows. +-- Display whitespace as dots and arrows. -- * `_SCINTILLA.constants.SCWS_VISIBLEAFTERINDENT` (2) --- White space used for indentation is displayed normally but after the --- first visible character, it is shown as dots and arrows. +-- Display non-indentation whitespace as dots and arrows. +-- +-- The default value is `0`. -- @field virtual_space_options (number) --- Virtual space options. +-- The virtual space mode. -- -- * `_SCINTILLA.constants.SCVS_NONE` (0) --- Disables all use of virtual space (default). +-- Disable virtual space. -- * `_SCINTILLA.constants.SCVS_RECTANGULARSELECTION` (1) --- Enabled only for rectangular selections. +-- Enable virtual space only for rectangular selections. -- * `_SCINTILLA.constants.SCVS_USERACCESSIBLE` (2) --- Enabled. +-- Enable virtual space. +-- +-- The default value is `0`. -- @field whitespace_chars (string) --- The set of characters making up whitespace for when moving or selecting by --- word. --- Use after setting `buffer.word_chars`. +-- The set of characters considered to be whitespace characters when moving +-- or selecting text by word. +-- Set this only after setting [`buffer.word_chars`](#word_chars). +-- The default value is a string containing all non-newline characters less +-- than ASCII value 33. -- @field whitespace_size (number) --- The size of the dots used to mark space characters. +-- The size of the dots in pixels used to represent space characters when +-- whitespace is visible. +-- The default value is `1`. -- @field word_chars (string) --- The set of characters making up words when moving or selecting by word. +-- The set of characters considered to be word characters when moving or +-- selecting text by word. +-- The default value is a string containing alphanumeric characters, an +-- underscore, and all characters greater than ASCII value 127. -- @field wrap_indent_mode (number) --- How wrapped sublines are placed. --- Default is fixed. +-- The wrapped line indent mode. -- -- * `_SCINTILLA.constants.SC_WRAP_INDENT_FIXED` (0) --- Wrapped sublines aligned to left of window plus amount set by --- `buffer.wrap_start_indent`. +-- Indent wrapped lines by [`buffer.wrap_start_indent`](#wrap_start_indent). -- * `_SCINTILLA.constants.SC_WRAP_INDENT_SAME` (1) --- Wrapped sublines are aligned to first subline indent. +-- Indent wrapped lines the same as the first line. -- * `_SCINTILLA.constants.SC_WRAP_INDENT_INDENT` (2) --- Wrapped sublines are aligned to first subline indent plus one more level --- of indentation. +-- Indent wrapped lines one more level than the first line. -- @field wrap_mode (number) --- Text word wrap mode. +-- Long line wrap mode. -- -- * `_SCINTILLA.constants.SC_WRAP_NONE` (0) --- Disable line wrapping. +-- Long lines are not wrapped. -- * `_SCINTILLA.constants.SC_WRAP_WORD` (1) --- Enable wrapping on word boundaries. +-- Wrap long lines at word boundaries. -- * `_SCINTILLA.constants.SC_WRAP_CHAR` (2) --- Enable wrapping between any characters. +-- Wrap long lines at character boundaries. +-- +-- The default value is `0`. -- @field wrap_start_indent (number) --- The start indent for wrapped lines. +-- The number of spaces to indent wrapped lines by if +-- [`buffer.wrap_indent_mode`](#wrap_indent_mode) is +-- `_SCINTILLA.constants.SC_WRAP_INDENT_FIXED`. +-- The default value is `0`. -- @field wrap_visual_flags (number) --- The display mode of visual flags for wrapped lines. +-- The wrapped line visual display mode. -- -- * `_SCINTILLA.constants.SC_WRAPVISUALFLAG_NONE` (0) -- No visual flags. -- * `_SCINTILLA.constants.SC_WRAPVISUALFLAG_END` (1) --- Visual flag at end of subline of a wrapped line. +-- Show visual flag at the end of the line. -- * `_SCINTILLA.constants.SC_WRAPVISUALFLAG_START` (2) --- Visual flag at begin of subline of a wrapped line. --- Subline is indented by at least 1 to make room for the flag. +-- Show visual flag at the beginning of the sub-line. +-- * `_SCINTILLA.constants.SC_WRAPVISUALFLAG_MARGIN` (4) +-- Show visual flag in the line number margin of the sub-line. +-- +-- The default value is `0`. -- @field wrap_visual_flags_location (number) --- The location of visual flags for wrapped lines. +-- The wrapped line visual flag drawing mode. -- -- * `_SCINTILLA.constants.SC_WRAPVISUALFLAGLOC_DEFAULT` (0) --- Visual flags drawn near border. +-- Draw the visual flag near the right border. -- * `_SCINTILLA.constants.SC_WRAPVISUALFLAGLOC_END_BY_TEXT` (1) --- Visual flag at end of subline drawn near text. +-- Draw the visual flag near text at the end of the line. -- * `_SCINTILLA.constants.SC_WRAPVISUALFLAGLOC_START_BY_TEXT` (2) --- Visual flag at beginning of subline drawn near text. +-- Draw the visual flag near text at the beginning of the subline. +-- +-- The default value is `0`. -- @field x_offset (number) --- The horizontal scroll position. +-- The horizontal scroll position in pixels. -- A value of `0` is the normal position with the first text column visible at -- the left of the view. -- @field zoom (number) --- The number of points added to the size of all fonts. --- It may be positive to magnify or negative to reduce. +-- The number of points to add to the size of all fonts. +-- Negative values are allowed. +-- The default value is `0`. module('buffer') --- --- Add a selection from anchor to caret as the main selection. --- Retainings all other selections as additional selections. Since there is --- always at least one selection, to set a list of selections, the first --- selection should be added with `buffer:set_selection()` and later selections --- added with this function. +-- Adds a new selection to a text range from *anchor* to *caret* as the main +-- selection, retaining all other selections as additional selections. +-- Even if no text is selected, the current position counts as an empty +-- selection. Use `buffer:set_selection()` first when setting a list of +-- selections. -- @param buffer The global buffer. -- @param caret The caret. -- @param anchor The anchor. function add_selection(buffer, caret, anchor) end --- --- Add text to the document at current position. --- The current position is set at the end of the inserted text, but it is not --- scrolled into view. +-- Adds string *text* to the buffer at the current position and moves the +-- current position to the end of the added text, but does not scroll it into +-- view. -- @param buffer The global buffer. -- @param text The text to add. function add_text(buffer, text) end --- --- Enlarge the document to a particular size of text bytes. --- The document will not be made smaller than its current contents. +-- Enlarges the buffer to store *bytes* number of bytes, but never shrinks it +-- beyond the size of its contents. -- @param buffer The global buffer. --- @param bytes The number of bytes the document can store. +-- @param bytes The number of bytes the buffer can store. function allocate(buffer, bytes) end --- --- Clear the annotations from all lines. +-- Clears annotations from all lines. -- @param buffer The global buffer. function annotation_clear_all(buffer) end --- --- Append a string to the end of the document without changing the selection. --- The current selection is not changed and the new text is not scrolled into --- view. +-- Appends string *text* to the end of the buffer without changing the selected +-- text or scrolling the text into view. -- @param buffer The global buffer. -- @param text The text. function append_text(buffer, text) end --- --- Is there an auto-completion list visible? +-- Returns whether or not an autocompletion list is visible. -- @param buffer The global buffer. -- @return bool function auto_c_active(buffer) end --- --- Remove the auto-completion list from the screen. --- A set of characters that will cancel autocompletion can be specified with --- `buffer:auto_c_stops()`. +-- Cancels the autocompletion list. -- @param buffer The global buffer. function auto_c_cancel(buffer) end --- --- User has selected an item so remove the list and insert the selection. --- This has the same effect as the tab key. +-- Autocompletes the selected word in the list. -- @param buffer The global buffer. function auto_c_complete(buffer) end --- --- Retrieve the position of the caret when the auto-completion list was --- displayed. +-- Returns the position where autocompletion started at. -- @param buffer The global buffer. -- @return number function auto_c_pos_start(buffer) end --- --- Select the item in the auto-completion list that starts with a string. --- By default, comparisons are case sensitive, but this can change with --- `buffer.auto_c_ignore_case`. +-- Selects the first item in the autocompletion list that starts with *string*, +-- considering case sensitiveness depending on `buffer.auto_c_ignore_case`. -- @param buffer The global buffer. -- @param string The item in the list to select. function auto_c_select(buffer, string) end --- --- Display an auto-completion list. +-- Displays an autocompletion list from *item_list*, a sorted string whose items +-- are delimited by `buffer.auto_c_separator` characters, using *len_entered* +-- number of characters behind the caret as the prefix of the word to +-- autocomplete. -- @param buffer The global buffer. -- @param len_entered The number of characters before the caret used to provide -- the context. --- @param item_list List of words separated by separator characters (initially --- spaces). The list of words should be in sorted order. +-- @param item_list Sorted list of words separated by separator characters +-- (initially spaces). function auto_c_show(buffer, len_entered, item_list) end --- --- Define a set of characters that when typed cancel the auto-completion list. +-- Defines *chars* as the set of characters that cancel autocompletion when +-- typed. +-- The default set is an empty string. -- @param buffer The global buffer. -- @param chars String list of characters. This list is empty by default. function auto_c_stops(buffer, chars) end --- --- Dedent the selected lines. +-- Dedents the selected lines. -- @param buffer The global buffer. function back_tab(buffer) end --- --- Start a sequence of actions that is undone and redone as a unit. +-- Starts a sequence of actions to undo or redo as a single action. -- May be nested. -- @param buffer The global buffer. function begin_undo_action(buffer) end --- --- Highlight the character at a position indicating there is no matching brace. +-- Highlights the character at position *pos* as an unmatched brace character in +-- the `_SCINTILLA.constants.STYLE_BRACEBAD` style. +-- Removes highlighting when *pos* is `-1`. -- @param buffer The global buffer. -- @param pos The position or `-1` to remove the highlight. function brace_bad_light(buffer, pos) end --- --- Use specified indicator to highlight non matching brace instead of changing --- its style. +-- Highlights unmatched brace characters with indicator number *indic_num*, in +-- the range of `0` to `31`, instead of the +-- `_SCINTILLA.constants.STYLE_BRACEBAD` style if *use_indicator* is `true`. -- @param buffer The global buffer. -- @param use_indicator Use an indicator. -- @param indic_num The indicator number. function brace_bad_light_indicator(buffer, use_indicator, indic_num) end --- --- Highlight the characters at two positions. --- If indent guides are enabled, the indent that corresponds with the brace can --- be highlighted by locating the column with `buffer.column` and highlight the --- indent with `buffer.highlight_guide`. +-- Highlights the characters at positions *pos1* and *pos2* as matching braces +-- in the `_SCINTILLA.constants.STYLE_BRACELIGHT` style. +-- If indent guides are enabled, locate the column with `buffer.column` and +-- set `buffer.highlight_guide` in order to highlight the indent guide. -- @param buffer The global buffer. -- @param pos1 The first position. -- @param pos2 The second position. function brace_highlight(buffer, pos1, pos2) end --- --- Use specified indicator to highlight matching braces instead of changing --- their style. +-- Highlights matching brace characters with indicator number *indic_num*, in +-- the range of `0` to `31`, instead of the +-- `_SCINTILLA.constants.STYLE_BRACELIGHT` style if *use_indicator* is `true`. -- @param buffer The global buffer. -- @param use_indicator Use an indicator. -- @param indic_num The indicator number. function brace_highlight_indicator(buffer, use_indicator, indic_num) end --- --- Find the position of a matching brace or `-1` if no match. --- The brace characters handled are '(', ')', '[', ']', '{', '}', '<', and '>'. --- The search is forwards from an opening brace and backwards from a closing --- brace. A match only occurs if the style of the matching brace is the same as --- the starting brace or the matching brace is beyond the end of styling. Nested --- braces are handled correctly. +-- Returns the position of the matching brace for the brace character at +-- position *pos*, taking nested braces into account, or `-1`. +-- The brace characters recognized are '(', ')', '[', ']', '{', '}', '<', and +-- '>' and must have the same style. -- @param buffer The global buffer. -- @param pos The position. -- @return number. function brace_match(buffer, pos) end --- --- Is there an active call tip? +-- Returns whether or not a call tip is visible. -- @param buffer The global buffer. -- @return bool function call_tip_active(buffer) end --- --- Remove the call tip from the screen. --- Call tips are also removed if any keyboard commands that are not compatible --- with editing the argument list of a function are used. +-- Removes the call tip from view. -- @param buffer The global buffer. function call_tip_cancel(buffer) end --- --- Retrieve the position where the caret was before displaying the call tip. +-- Returns the position where the call tip displayed at. -- @param buffer The global buffer. -- @return number function call_tip_pos_start(buffer) end --- --- Highlights a segment of a call tip. +-- Highlights call tip text from *start_pos*, starting from zero, to *end_pos* +-- with the color `buffer.call_tip_fore_hlt`. -- @param buffer The global buffer. -- @param start_pos The start position. -- @param end_pos The end position. function call_tip_set_hlt(buffer, start_pos, end_pos) end --- --- Show a call tip containing a definition near position pos. --- The call tip text is aligned to start 1 line below this character unless up --- and/or down arrows have been included in the call tip text in which case the --- tip is aligned to the right-hand edge of the rightmost arrow. The assumption --- is that the text starts with something like `"\001 1 of 3 \002"`. +-- Displays a call tip containing string *text* for the word behind position +-- *pos*. +-- Any "\001" or "\002" bytes in *text* are replaced by arrow visuals, +-- indicating the word has more than one call tip. -- @param buffer The global buffer. -- @param pos The position. -- @param text The text. function call_tip_show(buffer, pos, text) end --- --- Will a paste succeed? +-- Returns whether or not the clipboard has text to paste. -- @param buffer The global buffer. -- @return bool function can_paste(buffer) end --- --- Are there any redoable actions in the undo history? +-- Returns whether or not there is an action to redo. -- @param buffer The global buffer. -- @return bool function can_redo(buffer) end --- --- Are there any undoable actions in the undo history? +-- Returns whether or not there is an action to undo. -- @param buffer The global buffer. -- @return bool function can_undo(buffer) end --- --- Cancel any modes such as call tip or auto-completion list display. +-- Cancels the active call tip, autocompletion list, user list, selection mode, +-- etc. -- @param buffer The global buffer. function cancel(buffer) end --- --- Indicate that the internal state of a lexer has changed over a range and --- therefore there may be a need to redraw. +-- Tells the lexer to re-process the range of text from *start_pos* to +-- *end_pos*. -- @param buffer The global buffer. -- @param start_pos The start position. -- @param end_pos The end position. function change_lexer_state(buffer, start_pos, end_pos) end --- --- Move caret left one character. +-- Moves the caret left one character. -- @param buffer The global buffer. function char_left(buffer) end --- --- Move caret left one character extending selection to new caret position. +-- Moves the caret left one character, extending the selection to the new +-- position. -- @param buffer The global buffer. function char_left_extend(buffer) end --- --- Move caret left one character, extending rectangular selection to new caret --- position. +-- Moves the caret left one character, extending the rectangular selection to +-- the new position. -- @param buffer The global buffer. function char_left_rect_extend(buffer) end --- --- Find the position of a character from a point within the window. +-- Returns the character position closest to view coordinates *x* and *y*. -- @param buffer The global buffer. --- @param x The x-coordinate in the window. --- @param y The y-coordinate in the window. +-- @param x The x-coordinate in the view. +-- @param y The y-coordinate in the view. -- @return number function char_position_from_point(buffer, x, y) end --- --- Find the position of a character from a point within the window. --- Return `-1` if not close to text. +-- Returns the character position closest to view coordinates *x* and *y*, or +-- `-1` if the point is outside the window or not close to any text. -- @param buffer The global buffer. --- @param x The x-coordinate in the window. --- @param y The y-coordinate in the window. +-- @param x The x-coordinate in the view. +-- @param y The y-coordinate in the view. -- @return number function char_position_from_point_close(buffer, x, y) end --- --- Move caret right one character. +-- Moves the caret right one character. -- @param buffer The global buffer. function char_right(buffer) end --- --- Move caret right one character extending selection to new caret position. +-- Moves the caret right one character, extending the selection to the new +-- position. -- @param buffer The global buffer. function char_right_extend(buffer) end --- --- Move caret right one character, extending rectangular selection to new caret --- position. +-- Moves the caret right one character, extending the rectangular selection to +-- the new position. -- @param buffer The global buffer. function char_right_rect_extend(buffer) end --- --- Set the last x chosen value to be the caret x position. --- The view remembers the x value of the last position horizontally moved to --- explicitly by the user and this value is then used when moving vertically --- such as by using the up and down keys. This function sets the current x --- position of the caret as the remembered value. +-- Sets the preferred horizontal position of the caret when moving between +-- lines to the current position. -- @param buffer The global buffer. +-- @see caret_sticky function choose_caret_x(buffer) end --- --- Clear the selection. +-- Deletes the selected text or the character at the current position. -- @param buffer The global buffer. function clear(buffer) end --- --- Delete all text in the document. +-- Deletes all of the text in the buffer unless the buffer is read-only. -- @param buffer The global buffer. function clear_all(buffer) end --- --- Drop all key mappings. +-- Clears Scintilla's internal key bindings. -- @param buffer The global buffer. function clear_all_cmd_keys(buffer) end --- --- Set all style bytes to `0`, remove all folding information. +-- Clears all styling and folding information in the buffer. -- @param buffer The global buffer. function clear_document_style(buffer) end --- --- Clear all the registered XPM images. +-- Clears all images registered using `buffer:register_image()` and +-- `buffer:register_rgba_image()`. -- @param buffer The global buffer. function clear_registered_images(buffer) end --- --- Clear selections to a single empty stream selection. +-- Removes all selections and moves the caret to the beginning of the buffer. -- @param buffer The global buffer. function clear_selections(buffer) end --- --- Colorise a segment of the document using the current lexing language. +-- Tells the lexer to style and fold the range of text from *start_pos* to +-- *end_pos*. +-- If *end_pos* is `-1`, styles and folds to the end of the buffer. -- @param buffer The global buffer. -- @param start_pos The start position. -- @param end_pos The end position or `-1` to style from `start_pos` to the end @@ -1196,16 +1268,15 @@ function clear_selections(buffer) end function colourise(buffer, start_pos, end_pos) end --- --- Find the next line at or after line_start that is a contracted fold header --- line. --- Return `-1` when no more lines. +-- Returns the line number of the next contracted fold header line starting at +-- *line_start*, or `-1`. -- @param buffer The global buffer. -- @param line_start The start line number. -- @return number function contracted_fold_next(buffer, line_start) end --- --- Converts all line endings in the document to one mode. +-- Converts all line endings to end of line mode *mode*. -- @param buffer The global buffer. -- @param mode The line ending mode. Valid values are: -- * `_SCINTILLA.constants.SC_EOL_CRLF` (0) @@ -1214,31 +1285,34 @@ function contracted_fold_next(buffer, line_start) end function convert_eo_ls(buffer, mode) end --- --- Copy the selection to the clipboard. +-- Copies the selected text to the clipboard. +-- Multiple selections are copied in order with no delimiters. Rectangular +-- selections are copied from top to bottom with line ending delimiters. Virtual +-- space is not copied. -- @param buffer The global buffer. function copy(buffer) end --- --- Copy the selection, if selection empty copy the line with the caret. +-- Copies the selected text or the current line to the clipboard. -- @param buffer The global buffer. function copy_allow_line(buffer) end --- --- Copy a range of text to the clipboard. Positions are clipped into the --- document. +-- Copies the range of text from *start_pos* to *end_pos* to the clipboard. -- @param buffer The global buffer. -- @param start_pos The start position. -- @param end_pos The end position. function copy_range(buffer, start_pos, end_pos) end --- --- Copy argument text to the clipboard. +-- Copies string *text* to the clipboard. -- @param buffer The global buffer. -- @param text The text. function copy_text(buffer, text) end --- --- Count characters between two positions. +-- Returns the number of whole characters in-between positions *start_pos* and +-- *end_pos*. -- @param buffer The global buffer. -- @param start_pos The start position. -- @param end_pos The end position. @@ -1246,216 +1320,232 @@ function copy_text(buffer, text) end function count_characters(buffer, start_pos, end_pos) end --- --- Cut the selection to the clipboard. +-- Cuts the selected text to the clipboard. +-- Multiple selections are copied in order with no delimiters. Rectangular +-- selections are copied from top to bottom with line ending delimiters. Virtual +-- space is not copied. -- @param buffer The global buffer. function cut(buffer) end --- --- Delete back from the current position to the start of the line. +-- Deletes text from the current position to the beginning of the line. -- @param buffer The global buffer. function del_line_left(buffer) end --- --- Delete forwards from the current position to the end of the line. +-- Deletes text from the current position to the end of the line. -- @param buffer The global buffer. function del_line_right(buffer) end --- --- Delete the word to the left of the caret. +-- Deletes the word to the left of the caret, including any leading non-word +-- characters. +-- `buffer.word_chars` contains word characters. -- @param buffer The global buffer. function del_word_left(buffer) end --- --- Delete the word to the right of the caret. +-- Deletes the word to the right of the caret, including any trailing non-word +-- characters. +-- `buffer.word_chars` contains word characters. -- @param buffer The global buffer. function del_word_right(buffer) end --- --- Delete the word to the right of the caret, but not the trailing non-word +-- Deletes the word to the right of the caret, excluding any trailing non-word -- characters. +-- `buffer.word_chars` contains word characters. -- @param buffer The global buffer. function del_word_right_end(buffer) end --- --- Delete the selection or if no selection, the character before the caret. +-- Deletes the selected text or the character behind the caret. -- @param buffer The global buffer. function delete_back(buffer) end --- --- Delete the selection or if no selection, the character before the caret. --- Will not delete the character before at the start of a line. +-- Deletes the selected text or the character behind the caret unless the caret +-- is at the beginning of a line. -- @param buffer The global buffer. function delete_back_not_line(buffer) end --- --- Delete a range of text in the document. +-- Deletes the range of text from *pos* to *pos* + *length* in the buffer. -- @param buffer The global buffer. -- @param pos The start position of the range to delete. -- @param length The length of the range to delete. function delete_range(buffer, pos, length) end --- --- Find the document line of a display line taking hidden lines into account. +-- Returns the actual line number of displayed line number *display_line*, +-- taking hidden lines into account. +-- If *display_line* is less than or equal to zero, returns `0`. If +-- *display_line* is greater than or equal to the number of displayed lines, +-- returns `buffer.line_count`. -- @param buffer The global buffer. +-- @param display_line The display line number. -- @return number -function doc_line_from_visible(buffer) end +function doc_line_from_visible(buffer, display_line) end --- --- Move caret to last position in document. +-- Moves the caret to the end of the buffer. -- @param buffer The global buffer. function document_end(buffer) end --- --- Move caret to last position in document extending selection to new caret +-- Moves the caret to the end of the buffer, extending the selection to the new -- position. -- @param buffer The global buffer. function document_end_extend(buffer) end --- --- Move caret to first position in document. +-- Moves the caret to the beginning of the buffer. -- @param buffer The global buffer. function document_start(buffer) end --- --- Move caret to first position in document extending selection to new caret --- position. +-- Moves the caret to the beginning of the buffer, extending selection to the +-- new position. -- @param buffer The global buffer. function document_start_extend(buffer) end --- --- Switch from insert to overtype mode or the reverse. +-- Toggles `buffer.overtype`. -- @param buffer The global buffer. function edit_toggle_overtype(buffer) end --- --- Delete the undo history. --- It also sets the save point to the start of the undo buffer, so the document --- will appear to be unmodified. +-- Deletes the undo and redo history and sets `buffer.modify` to `false`. -- @param buffer The global buffer. function empty_undo_buffer(buffer) end --- --- Translates a UTF8 string into the document encoding. --- Return the length of the result in bytes. On error return `0`. +-- Returns the result of UTF-8-encoded string *string* converted into the +-- buffer's encoding. -- @param buffer The global buffer. -- @param string The string. -- @return number function encoded_from_utf8(buffer, string) end --- --- End a sequence of actions that is undone and redone as a unit. +-- Ends a sequence of actions to undo or redo as a single action. -- @param buffer The global buffer. function end_undo_action(buffer) end --- --- Ensure a particular line is visible by expanding any header line hiding it. +-- Ensures line number *line* is visible by expanding any fold header lines +-- hiding it. -- @param buffer The global buffer. -- @param line The line number. function ensure_visible(buffer, line) end --- --- Ensure a particular line is visible by expanding any header line hiding it. --- Use the currently set visibility policy to determine which range to display. +-- Ensures line number *line* is visible by expanding any fold header lines +-- hiding it and applies the vertical caret policy set with +-- `buffer:set_visible_policy()`. -- @param buffer The global buffer. -- @param line The line number. function ensure_visible_enforce_policy(buffer, line) end --- --- Find the position of a column on a line taking into account tabs and --- multi-byte characters. --- If beyond end of line, return line end position. +-- Returns the position of column number *column* on line number *line*, taking +-- tab and multi-byte characters into account, or the position at the end of +-- line *line*. -- @param buffer The global buffer. -- @param line The line number. -- @param column The column number. function find_column(buffer, line, column) end --- --- Insert a Form Feed character. +-- Inserts a Form Feed ("\f") character at the current position. -- @param buffer The global buffer. function form_feed(buffer) end --- --- Retrieve the text of the line containing the caret. --- Also returns the index of the caret on the line. +-- Returns the current line's text and the index of the caret on the line, +-- starting from zero. -- @param buffer The global buffer. -- @return string, number function get_cur_line(buffer) end --- --- Get the back color for active hotspots in "0xBBGGRR" format. +-- Returns the numeric background color for active hotspots. -- @param buffer The global buffer. -- @return number function get_hotspot_active_back(buffer) end --- --- Get the fore color for active hotspots. +-- Returns the numeric foreground color for active hotspots. -- @param buffer The global buffer. -- @return number function get_hotspot_active_fore(buffer) end --- --- Find the last child line of a header line. +-- Returns the line number of the last line after line number *start_line* whose +-- fold level is greater than *level* or the level of *start_line* if *level* is +-- `-1`. -- @param buffer The global buffer. --- @param header_line The line number of a header line. --- @param level The level or `-1` for the level of `header_line`. -function get_last_child(buffer, header_line, level) end +-- @param start_line The line number of a header line. +-- @param level The level or `-1` for the level of `start_line`. +function get_last_child(buffer, start_line, level) end --- --- Retrieve the contents of a line. --- Also returns the length of the line. +-- Returns the text on line number *line*, including end of line characters, and +-- the length of the line. -- @param buffer The global buffer. -- @param line The line number. -- @return string, number function get_line(buffer, line) end --- --- Retrieve the position of the end of the selection at the given line (`-1` if --- no selection on this line). +-- Returns the position of the end of the selected text on line number *line*, +-- or `-1`. -- @param buffer The global buffer. -- @param line The line number. function get_line_sel_end_position(buffer, line) end --- --- Retrieve the position of the start of the selection at the given line (`-1` --- if no selection on this line). +-- Returns the position of the beginning of the selected text on line number +-- *line*, or `-1`. -- @param buffer The global buffer. -- @param line The line number. function get_line_sel_start_position(buffer, line) end --- --- Retrieve the selected text. --- Also returns the length of the text. +-- Returns the selected text and its length. +-- Multiple selections are included in order with no delimiters. Rectangular +-- selections are included from top to bottom with line ending delimiters. +-- Virtual space is not included. -- @param buffer The global buffer. -- @return string, number function get_sel_text(buffer) end --- --- Retrieve all the text in the document. --- Also returns number of characters retrieved. +-- Returns all of the text in the buffer and its length. -- @param buffer The global buffer. function get_text(buffer) end --- --- Set caret to start of a line and ensure it is visible. +-- Places the caret an anchor at the beginning of line number *line* and scrolls +-- them into view. -- @param buffer The global buffer. -- @param line The line number. function goto_line(buffer, line) end --- --- Set caret to a position and ensure it is visible. --- The anchor position is set the same as the current position. +-- Places the caret and anchor at position *pos* and scrolls them into view. -- @param buffer The global buffer. -- @param pos The position. function goto_pos(buffer, pos) end --- --- Set the focus to this view. +-- Sets the focus to the buffer's view. -- @param buffer The global buffer. function grab_focus(buffer) end --- --- Make a range of lines invisible. --- This has no effect on fold levels or fold flags. `start_line` can not be +-- Hides the range of lines from line number *start_line* to *end_line*. +-- This has no effect on fold levels or fold flags and the first line cannot be -- hidden. -- @param buffer The global buffer. -- @param start_line The start line. @@ -1463,91 +1553,93 @@ function grab_focus(buffer) end function hide_lines(buffer, start_line, end_line) end --- --- Draw the selection in normal style or with selection highlighted. +-- Do not highlight selected text if *normal* is `true`. -- @param buffer The global buffer. -- @param normal Draw normal selection. function hide_selection(buffer, normal) end --- --- Move caret to first position on line. +-- Moves the caret to the beginning of the current line. -- @param buffer The global buffer. function home(buffer) end --- --- Move caret to first position on display line. +-- Moves the caret to the beginning of the current wrapped line. -- @param buffer The global buffer. function home_display(buffer) end --- --- Move caret to first position on display line extending selection to new caret --- position. +-- Moves the caret to the beginning of the current wrapped line, extending the +-- selection to the new position. -- @param buffer The global buffer. function home_display_extend(buffer) end --- --- Move caret to first position on line extending selection to new caret --- position. +-- Moves the caret to the beginning of the current line, extending selection to +-- the new position. -- @param buffer The global buffer. function home_extend(buffer) end --- --- Move caret to first position on line, extending rectangular selection to new --- caret position. +-- Moves the caret to beginning of the current line, extending the rectangular +-- selection to the new position. -- @param buffer The global buffer. function home_rect_extend(buffer) end --- --- Move caret to the start of the display line when word-wrap is enabled. --- If already there, go to the start of the document line. +-- Moves the caret to beginning of the current wrapped line, or if already +-- there, to the beginning of the actual line. -- @param buffer The global buffer. function home_wrap(buffer) end --- --- Like `buffer:home_wrap()` but extending selection to new caret position. +-- Like `buffer:home_wrap()`, but extends the selection to the new position. -- @param buffer The global buffer. function home_wrap_extend(buffer) end --- --- Retrieve a bitmap value representing which indicators are non-zero at a --- position. --- Bit 0 is set if indicator 0 is present, bit 1 for indicator 1 and so on. +-- Returns a bit-mask representing which indicators are on at position *pos*. +-- Bit 0 is set if indicator 0 is on, bit 1 for indicator 1, etc. -- @param buffer The global buffer. -- @param pos The position. -- @return number function indicator_all_on_for(buffer, pos) end --- --- Turn a indicator off over a range. +-- Clears indicator `buffer.indicator_current` over the range of text from *pos* +-- to *pos* + *clear_length*. -- @param buffer The global buffer. -- @param pos The start position. -- @param clear_length The length. function indicator_clear_range(buffer, pos, clear_length) end --- --- Find the position where a particular indicator ends. +-- Returns the end position of indicator number *indicator*, in the range of `0` +-- to `31`, at position *pos*. -- @param buffer The global buffer. -- @param indicator An indicator number in the range of `0` to `31`. -- @param pos The position of the indicator. function indicator_end(buffer, indicator, pos) end --- --- Turn a indicator on over a range. --- This function fills with the current indicator value. +-- Sets indicator `buffer.indicator_value` or `buffer.indicator_current` over +-- the range of text from *pos* to *pos* + *fill_length*. -- @param buffer The global buffer. -- @param pos The start position. -- @param fill_length The length. function indicator_fill_range(buffer, pos, fill_length) end --- --- Find the position where a particular indicator starts. +-- Returns the position of the beginning of indicator number *indicator*, in the +-- range of `0` to `31`, at position *pos*. -- @param buffer The global buffer. -- @param indicator An indicator number in the range of `0` to `31`. -- @param pos The position of the indicator. function indicator_start(buffer, indicator, pos) end --- --- Retrieve the value of a particular indicator at a position. --- Currently all values are drawn the same. +-- Returns the value of indicator number *indicator*, in the range of `0` to +-- `31`, at position *pos*. -- @param buffer The global buffer. -- @param indicator The indicator number in the range of `0` to `31`. -- @param pos The position. @@ -1555,99 +1647,103 @@ function indicator_start(buffer, indicator, pos) end function indicator_value_at(buffer, indicator, pos) end --- --- Insert string at a position. --- If the current position is after the insertion point then it is moved along --- with its surrounding text but no scrolling is performed. +-- Inserts string *text* at position *pos* or the current position if *pos* is +-- `-1`. +-- If the current position is after the *pos*, it is moved appropriately, but +-- not scrolled into view. -- @param buffer The global buffer. -- @param pos The position to insert text at or `-1` for the current position. -- @param text The text to insert. function insert_text(buffer, pos, text) end --- --- Copy the line containing the caret. +-- Copies the current line to the clipboard. -- @param buffer The global buffer. function line_copy(buffer) end --- --- Cut the line containing the caret. +-- Cuts the current line to the clipboard. -- @param buffer The global buffer. function line_cut(buffer) end --- --- Delete the line containing the caret. +-- Deletes the current line. -- @param buffer The global buffer. function line_delete(buffer) end --- --- Move caret down one line. +-- Moves the caret down one line. -- @param buffer The global buffer. function line_down(buffer) end --- --- Move caret down one line extending selection to new caret position. +-- Moves the caret down one line, extending the selection to the new position. -- @param buffer The global buffer. function line_down_extend(buffer) end --- --- Move caret down one line, extending rectangular selection to new caret +-- Moves the caret down one line, extending the rectangular selection to the new -- position. -- @param buffer The global buffer. function line_down_rect_extend(buffer) end --- --- Duplicate the current line. +-- Duplicates the current line below the line. -- @param buffer The global buffer. function line_duplicate(buffer) end --- --- Move caret to last position on line. +-- Moves the caret to the end of the current line. -- @param buffer The global buffer. function line_end(buffer) end --- --- Move caret to last position on display line. +-- Moves the caret to the end of the current wrapped line. -- @param buffer The global buffer. function line_end_display(buffer) end --- --- Move caret to last position on display line extending selection to new caret --- position. +-- Moves the caret to the end of the current wrapped line, extending the +-- selection to the new position. -- @param buffer The global buffer. function line_end_display_extend(buffer) end --- --- Move caret to last position on line extending selection to new caret --- position. +-- Moves the caret to the end of the current line, extending the selection to +-- the new position. -- @param buffer The global buffer. function line_end_extend(buffer) end --- --- Move caret to last position on line, extending rectangular selection to new --- caret position. +-- Moves the caret to the end of the current line, extending the rectangular +-- selection to the new position. -- @param buffer The global buffer. function line_end_rect_extend(buffer) end --- --- Move caret to the end of the display line when word-wrap is enabled. --- If already there, go to the end of the document line. +-- Moves the caret to the end of the current wrapped line, or if already there, +-- to the end of the actual line. -- @param buffer The global buffer. function line_end_wrap(buffer) end --- --- Like `buffer:line_end_wrap()` but extending selection to new caret position. +-- Like `buffer:line_end_wrap()`, but extends the selection to the new position. -- @param buffer The global buffer. function line_end_wrap_extend(buffer) end --- --- Retrieve the line containing a position. +-- Returns the line number containing position *pos*. +-- Returns `0` if *pos* is less than 0 or `buffer.line_count` if *pos* is +-- greater than `buffer.length`. -- @param buffer The global buffer. -- @param pos The position. -- @return number function line_from_position(buffer, pos) end --- --- Returns how many characters are on a line, including end of line characters. --- To get the length of the line not including any end of line characters, use +-- Returns the number of characters on line number *line*, including end of line +-- characters. +-- To get line length excluding end of line characters, use -- `buffer.line_end_position[line] - buffer:position_from_line(line)`. -- @param buffer The global buffer. -- @param line The line number. @@ -1655,70 +1751,72 @@ function line_from_position(buffer, pos) end function line_length(buffer, line) end --- --- Scroll horizontally and vertically. +-- Scroll right *columns* columns and down *lines* lines. +-- Negative values are allowed. -- @param buffer The global buffer. -- @param columns The number of columns to scroll horizontally. -- @param lines The number of lines to scroll vertically. function line_scroll(buffer, columns, lines) end --- --- Scroll the document down, keeping the caret visible. +-- Scroll the buffer down one line, keeping the current position visible. -- @param buffer The global buffer. function line_scroll_down(buffer) end --- --- Scroll the document up, keeping the caret visible. +-- Scroll the buffer up one line, keeping the current position visible. -- @param buffer The global buffer. function line_scroll_up(buffer) end --- --- Switch the current line with the previous. +-- Switch the current line with the previous one. -- @param buffer The global buffer. function line_transpose(buffer) end --- --- Move caret up one line. +-- Moves the caret up one line. -- @param buffer The global buffer. function line_up(buffer) end --- --- Move caret up one line extending selection to new caret position. +-- Moves the caret up one line, extending the selection to the new position. -- @param buffer The global buffer. function line_up_extend(buffer) end --- --- Move caret up one line, extending rectangular selection to new caret +-- Moves the caret up one line, extending the rectangular selection to the new -- position. -- @param buffer The global buffer. function line_up_rect_extend(buffer) end --- --- Join the lines in the target. --- Where this would lead to no space between words, an extra space is inserted. +-- Joins the lines in the target range, inserting spaces in-between words on +-- separate lines. -- @param buffer The global buffer. function lines_join(buffer) end --- --- Split the lines in the target into lines that are less wide than --- `pixel_width` where possible. +-- Splits the lines in the target range into lines of width at most +-- *pixel_width* or the width of the view if *pixel_width* is `0`. -- @param buffer The global buffer. -- @param pixel_width The pixel width. When `0`, the width of the view is used. function lines_split(buffer, pixel_width) end --- --- Transform the selection to lower case. +-- Converts the selected text to lower case letters. -- @param buffer The global buffer. function lower_case(buffer) end --- --- Clear the margin text on all lines. +-- Clears margin text on all lines. -- @param buffer The global buffer. function margin_text_clear_all(buffer) end --- --- Add a marker to a line, returning an ID which can be used to find or delete --- the marker. --- Returns `-1` if this fails (illegal line number, out of memory). +-- Adds marker number *marker_num*, in the range of `0` to `31`, on line number +-- *line*, returning a marker handle which can be used in +-- `buffer:marker_delete_handle()` and `buffer:marker_line_from_handle()`, or +-- `-1` if the marker cannot be added. -- @param buffer The global buffer. -- @param line The line number. -- @param marker_num A marker number in the range of `0` to `31`. @@ -1726,7 +1824,9 @@ function margin_text_clear_all(buffer) end function marker_add(buffer, line, marker_num) end --- --- Add a set of markers to a line. +-- Adds the markers specified in the marker bit-mask *marker_mask* to line +-- number *line*. +-- Bit 0 is set to add marker 0, bit 1 for marker 1, etc., up to marker 31. -- @param buffer The global buffer. -- @param line The line number. -- @param marker_mask A mask of markers to set. Set bit 0 to set marker 0, bit @@ -1734,7 +1834,8 @@ function marker_add(buffer, line, marker_num) end function marker_add_set(buffer, line, marker_mask) end --- --- Set the symbol used for a particular marker number. +-- Sets the symbol *marker_symbol* shown in the margin for marker number +-- *marker_num*, in the range of `0` to `31`. -- @param buffer The global buffer. -- @param marker_num A marker number in the range of `0` to `31`. -- @param marker_symbol A marker symbol: `_SCINTILLA.constants.SC_MARK_*`. @@ -1742,16 +1843,22 @@ function marker_add_set(buffer, line, marker_mask) end function marker_define(buffer, marker_num, marker_symbol) end --- --- Define a marker from a pixmap. +-- Defines XPM image *pixmap* for marker number *marker_num*, in the range of +-- `0` to `31`. +-- Pixmap markers use the `_SCINTILLA.constants.SC_MARK_PIXMAP` marker symbol. -- @param buffer The global buffer. -- @param marker_num A marker number in the range of `0` to `31`. -- @param pixmap `NULL`-terminated pixmap data. function marker_define_pixmap(buffer, marker_num, pixmap) end --- --- Define a marker from RGBA data. --- It has the width and height from `buffer.rgba_image_width` and --- `buffer.rgba_image_height`. +-- Defines RGBA image *pixels* for marker number *marker_num*, in the range of +-- `0` to `31`. +-- RGBA image markers use the `_SCINTILLA.constants.SC_MARK_RGBAIMAGE` marker +-- symbol. The dimensions for *pixels*, `buffer.rgba_image_width` and +-- `buffer.rgba_image_height`, must be already 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. -- @param buffer The global buffer. -- @param marker_num A marker number in the range of `0` to `31`. -- @param pixels A sequence of 4 byte pixel values starting with the pixels for @@ -1764,7 +1871,8 @@ function marker_define_pixmap(buffer, marker_num, pixmap) end function marker_define_rgba_image(buffer, marker_num, pixels) end --- --- Delete a marker from a line. +-- Deletes marker number *marker_num*, in the range of `0` to `31` or `-1` for +-- all markers, from line number *line*. -- @param buffer The global buffer. -- @param line The line number. -- @param marker_num A marker number in the range of `0` to `31` or `-1` to @@ -1772,44 +1880,47 @@ function marker_define_rgba_image(buffer, marker_num, pixels) end function marker_delete(buffer, line, marker_num) end --- --- Delete all markers with a particular number from all lines. +-- Deletes marker number *marker_num*, in the range of `0` to `31` or `-1` for +-- all markers, from all lines in the buffer. -- @param buffer The global buffer. -- @param marker_num A marker number in the range of `0` to `31` or `-1` to -- delete all markers from the line. function marker_delete_all(buffer, marker_num) end --- --- Delete a marker. +-- Deletes the marker with handle *handle* returned by `buffer:marker_add()`. -- @param buffer The global buffer. -- @param handle The identifier of a marker returned by `buffer:marker_add()`. function marker_delete_handle(buffer, handle) end --- --- Enable/disable highlight for current folding block (smallest one that --- contains the caret) +-- Highlights the margin fold markers for the current fold block if *enabled* is +-- `true`. -- @param buffer The global buffer. -- @param enabled Whether to enable highlight. function marker_enable_highlight(buffer, enabled) end --- --- Get a bit mask of all the markers set on a line. --- Bit 0 is set if marker 0 is present, bit 1 for marker 1 and so on. +-- Returns a bit-mask representing which markers are set line number *line*. +-- Bit 0 is set if marker 0 is set, bit 1 for marker 1, etc. -- @param buffer The global buffer. -- @param line The line number. -- @return number. function marker_get(buffer, line) end --- --- Retrieve the line number at which a particular marker is located. --- Returns `-1` if it not found. +-- Returns the line number the marker with handle *handle*, returned by +-- `buffer:marker_add()`, is on, or `-1`. -- @param buffer The global buffer. -- @param handle The identifier of a marker returned by `buffer:marker_add()`. -- @return number function marker_line_from_handle(buffer, handle) end --- --- Find the next line at or after start_line that includes a marker in mask. --- Return `-1` when no more lines. +-- Returns the first line number starting at line number *start_line* that has +-- all of the markers represented by marker bit-mask *marker_mask* set on, or +-- `-1`. +-- Bit 0 is set if marker 0 is set, bit 1 for marker 1, etc., up to marker 31. -- @param buffer The global buffer. -- @param start_line The start line. -- @param marker_mask A mask of markers to find. Set bit 0 to find marker 0, bit @@ -1818,7 +1929,10 @@ function marker_line_from_handle(buffer, handle) end function marker_next(buffer, start_line, marker_mask) end --- --- Find the previous line before `start_line` that includes a marker in mask. +-- Returns the last line number before or on line number *start_line* that has +-- all of the markers represented by marker bit-mask *marker_mask* set on, or +-- `-1`. +-- Bit 0 is set if marker 0 is set, bit 1 for marker 1, etc., up to marker 31. -- @param buffer The global buffer. -- @param start_line The start line. -- @param marker_mask A mask of markers to find. Set bit 0 to find marker 0, bit @@ -1827,180 +1941,176 @@ function marker_next(buffer, start_line, marker_mask) end function marker_previous(buffer, start_line, marker_mask) end --- --- Return the symbol defined for marker_num with `buffer:marker_define()`. +-- Returns the symbol defined for marker number *marker_num*, in the range of +-- `0` to `31`, used in `buffer:marker_define()`, +-- `buffer:marker_define_pixmap()`, or `buffer:marker_define_rgba_image()`. -- @param buffer The global buffer. -- @param marker_num A marker number in the range of `0` to `31`. -- @return number function marker_symbol_defined(buffer, marker_num) end --- --- Move the caret inside current view if it is not there already. --- Any selection is lost. +-- Moves the current position to be visible inside the view if it is not +-- already, removing any selections. -- @param buffer The global buffer. function move_caret_inside_view(buffer) end --- --- Move the selected lines down one line, shifting the line below before the --- selection. --- The selection will be automatically extended to the beginning of the --- selection's first line and the end of the seletion's last line. If nothing --- was selected, the line the cursor is currently at will be selected. +-- Moves the selected lines down one line. -- @param buffer The global buffer. function move_selected_lines_down(buffer) end --- --- Move the selected lines up one line, shifting the line above after the --- selection. --- The selection will be automatically extended to the beginning of the --- selection's first line and the end of the seletion's last line. If nothing --- was selected, the line the cursor is currently at will be selected. +-- Moves the selected lines up one line. -- @param buffer The global buffer. function move_selected_lines_up(buffer) end --- --- Insert a new line, may use a CRLF, CR or LF depending on EOL mode. +-- Inserts a new line character(s) at the current position depending on the end +-- of line mode. -- @param buffer The global buffer. function new_line(buffer) end --- --- Move caret one page down. +-- Moves the caret one page down. -- @param buffer The global buffer. function page_down(buffer) end --- --- Move caret one page down extending selection to new caret position. +-- Moves the caret one page down, extending the selection to the new position. -- @param buffer The global buffer. function page_down_extend(buffer) end --- --- Move caret one page down, extending rectangular selection to new caret +-- Moves the caret one page down, extending the rectangular selection to the new -- position. -- @param buffer The global buffer. function page_down_rect_extend(buffer) end --- --- Move caret one page up. +-- Moves the caret one page up. -- @param buffer The global buffer. function page_up(buffer) end --- --- Move caret one page up extending selection to new caret position. +-- Moves the caret one page up, extending the selection to the new position. -- @param buffer The global buffer. function page_up_extend(buffer) end --- --- Move caret one page up, extending rectangular selection to new caret +-- Moves the caret one page up, extending the rectangular selection to the new -- position. -- @param buffer The global buffer. function page_up_rect_extend(buffer) end --- --- Move caret one paragraph down (delimited by empty lines). +-- Moves the caret one paragraph down. +-- Paragraphs are surrounded by one or more blank lines. -- @param buffer The global buffer. function para_down(buffer) end --- --- Move caret one paragraph down (delimited by empty lines) extending selection --- to new caret position. +-- Moves the caret one paragraph down, extending the selection to the new +-- position. +-- Paragraphs are surrounded by one or more blank lines. -- @param buffer The global buffer. function para_down_extend(buffer) end --- --- Move caret one paragraph up (delimited by empty lines). +-- Moves the caret one paragraph up. +-- Paragraphs are surrounded by one or more blank lines. -- @param buffer The global buffer. function para_up(buffer) end --- --- Move caret one paragraph up (delimited by empty lines) extending selection to --- new caret position. +-- Moves the caret one paragraph up, extending the selection to the new +-- position. +-- Paragraphs are surrounded by one or more blank lines. -- @param buffer The global buffer. function para_up_extend(buffer) end --- --- Paste the contents of the clipboard into the document replacing the --- selection. +-- Pastes the contents of the clipboard into the buffer, replacing the selected +-- text depending on `buffer.multi_paste`. -- @param buffer The global buffer. function paste(buffer) end --- --- For private communication between an application and a known lexer. --- @param buffer The global buffer. --- @param operation An operation number. --- @param data Number data. -function private_lexer_call(buffer, operation, data) end - ---- --- Retrieve the x value of the point in the window where a position is --- displayed. +-- Returns the x-coordinate in the view of position *pos*. -- @param buffer The global buffer. -- @param pos The position. -- @return number function point_x_from_position(buffer, pos) end --- --- Retrieve the y value of the point in the window where a position is --- displayed. +-- Returns the y-coordinate in the view of position *pos*. -- @param buffer The global buffer. -- @param pos The position. -- @return number function point_y_from_position(buffer, pos) end --- --- Given a valid document position, return the next position taking code page --- into account. Maximum value returned is the last position in the document. +-- Returns the position of the next character after position *pos*, taking code +-- page into account, or `buffer.length - 1`. -- @param buffer The global buffer. -- @param pos The position. function position_after(buffer, pos) end --- --- Given a valid document position, return the previous position taking code --- page into account. Returns `0` if passed `0`. +-- Returns the position of the previous character before position *pos*, taking +-- code page into account, or `0`. -- @param buffer The global buffer. -- @param pos The position. -- @return number function position_before(buffer, pos) end --- --- Retrieve the position at the start of a line. --- If line is greater than the lines in the document, returns `-1`. +-- Returns the position at the beginning of line number *line*. +-- Returns `-1` if *line* is greater than `buffer.line_count`. -- @param buffer The global buffer. -- @param line The line. -- @return number function position_from_line(buffer, line) end --- --- Find the position from a point within the window. +-- Returns the position closest to view coordinates *x* and *y*, which may be +-- in-between multi-byte characters. -- @param buffer The global buffer. --- @param x The x-coordinate in the window. --- @param y The y-coordinate in the window. +-- @param x The x-coordinate in the view. +-- @param y The y-coordinate in the view. -- @return number function position_from_point(buffer, x, y) end --- --- Returns the position from a point within the window, but return `-1` if not --- close to text. +-- Returns the position closest to view coordinates *x* and *y*, which may be +-- in-between multi-byte characters, or `-1` if the point is outside the window +-- or not close to any text. -- @param buffer The global buffer. --- @param x The x-coordinate in the window. --- @param y The y-coordinate in the window. +-- @param x The x-coordinate in the view. +-- @param y The y-coordinate in the view. -- @return number function position_from_point_close(buffer, x, y) end --- --- Redoes the next action on the undo history. +-- Redoes the next undone action. -- @param buffer The global buffer. function redo(buffer) end --- --- Register an XPM image for use in autocompletion lists. +-- Registers XPM image *xpm_data* to type number *type* for use in +-- autocompletion lists. -- @param buffer The global buffer. -- @param type Integer type to register the image with. -- @param xpm_data XPM data as is described for `buffer:marker_define_pixmap()`. function register_image(buffer, type, xpm_data) end --- --- Register an RGBA image for use in autocompletion lists. --- It has the width and height from `buffer.rgba_image_width` and --- `buffer.rgba_image_height`. +-- Registers RGBA image *pixels* to type number *type* for use in autocompletion +-- lists. +-- The dimensions for *pixels*, `buffer.rgba_image_width` and +-- `buffer.rgba_image_height`, must be already 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. -- @param buffer The global buffer. -- @param type Integer type to register the image with. -- @param pixels RGBA data as is described for @@ -2008,75 +2118,75 @@ function register_image(buffer, type, xpm_data) end function register_rgba_image(buffer, type, pixels) end --- --- Replace the selected text with the argument text. --- The caret is positioned after the inserted text and the caret is scrolled --- into view. +-- Replaces the selected text with string *text*, scrolling the caret into view. -- @param buffer The global buffer. -- @param text The text. function replace_sel(buffer, text) end --- --- Replace the target text with the argument text. --- After replacement, the target range refers to the replacement text. --- Returns the length of the replacement text. +-- Replaces the text in the target range with string *text*, returning the +-- length of *text*. +-- The recommended way to delete text in the buffer is to set the target to the +-- text to be removed, and to call this function with an empty string. -- @param buffer The global buffer. -- @param text The text (can contain null bytes). -- @return number function replace_target(buffer, text) end --- --- Replace the target text with the argument text after `\d` processing. --- Looks for `\d` where `d` is between `1` and `9` and replaces these with the --- strings matched in the last search operation which were surrounded by `\(` --- and `\)`. Returns the length of the replacement text including any change --- caused by processing the `\d` patterns. +-- Replaces the text in the target range with string *text* after replacing any +-- "\d" sequences, where `d` is a number in the range of `1` to `9`, with the +-- tag match values from the regular expression or the entire match for "\0", +-- returning the length of the replacement text. -- @param buffer The global buffer. -- @param text The text (can contain null bytes). -- @return number function replace_target_re(buffer, text) end --- --- Set the main selection to the next selection. +-- Sets the next additional selection to be the main selection. -- @param buffer The global buffer. function rotate_selection(buffer) end --- --- Ensure the caret is visible. +-- Scrolls the current position into view based on the policies set with +-- `buffer:set_x_caret_policy()` and `buffer:set_y_caret_policy()`. -- @param buffer The global buffer. +-- @see set_x_caret_policy +-- @see set_y_caret_policy function scroll_caret(buffer) end --- --- Scroll to end of document. +-- Scroll to the end of the buffer without moving the caret. -- @param buffer The global buffer. function scroll_to_end(buffer) end --- --- Scroll to start of document. +-- Scroll to the beginning of the buffer without moving the caret. -- @param buffer The global buffer. function scroll_to_start(buffer) end --- --- Sets the current caret position to be the search anchor. --- Always call this before calling either of `buffer:search_next()` or --- `buffer:search_prev()`. +-- Sets the current position to anchor subsequent searches with +-- `buffer:search_next()` and `buffer:search_prev()`. -- @param buffer The global buffer. function search_anchor(buffer) end --- --- Search for a counted string in the target and set the target to the found --- range. --- Returns length of range or `-1` for failure in which case target is not --- moved. +-- Searches for the first occurrence of string *text* in the target range +-- bounded by `buffer.target_start` and `buffer.target_end` using search flags +-- `buffer.search_flags` and, if found, sets the new target range to that +-- occurrence, returning its position or `-1` otherwise. -- @param buffer The global buffer. -- @param text The text (can contain null bytes). -- @return number function search_in_target(buffer, text) end --- --- Find some text starting at the search anchor. --- The return value is `-1` if nothing is found, otherwise the return value is --- the start position of the matching text. The selection is updated to show the --- matched text, but is not scrolled into view. +-- Searches for and selects the first occurrence of string *text* starting at +-- the search anchor using search flags *flags*, returning the position of the +-- occurrence or `-1`. +-- Selected text is not scrolled into view. -- @param buffer The global buffer. -- @param flags Search flags. See `buffer.search_flags`. -- @param text The text. @@ -2085,10 +2195,9 @@ function search_in_target(buffer, text) end function search_next(buffer, flags, text) end --- --- Find some text starting at the search anchor and moving backwards. --- The return value is `-1` if nothing is found, otherwise the return value is --- the start position of the matching text. The selection is updated to show the --- matched text, but is not scrolled into view. +-- Searches for and selects the last occurrence of string *text* before the +-- search anchor using search flags *flags*, returning the position of the +-- occurrence or `-1`. -- @param buffer The global buffer. -- @param flags Search flags. See `buffer.search_flags`. -- @param text The text. @@ -2097,75 +2206,75 @@ function search_next(buffer, flags, text) end function search_prev(buffer, flags, text) end --- --- Select all the text in the document. --- The current position is not scrolled into view. +-- Selects all of the text in the buffer without scrolling the view. -- @param buffer The global buffer. function select_all(buffer) end --- --- Duplicate the selection. --- If selection empty duplicate the line containing the caret. +-- Duplicates the selected text or the current line. -- @param buffer The global buffer. function selection_duplicate(buffer) end --- --- Reset the set of characters for whitespace and word characters to the --- defaults. --- This sets whitespace to space, tab and other characters with codes less than --- 0x20, with word characters set to alphanumeric and '_'. +-- Resets the set of whitespace and word characters to their default characters. -- @param buffer The global buffer. +-- @see whitespace_chars +-- @see word_chars function set_chars_default(buffer) end --- --- Set caret to a position, while removing any existing selection. --- The caret is not scrolled into view. +-- Sets the current position to position *pos* without scrolling the view, +-- removing any selections. -- @param buffer The buffer -- @param pos The position to move to. function set_empty_selection(buffer, pos) end --- --- Set the colors used as a chequerboard pattern in the fold margin. +-- Overrides the default color of the fold margin with *color*, in "0xBBGGRR" +-- format, if *use_setting* is `true`. -- @param buffer The global buffer. -- @param use_setting Enable color change. -- @param color A color in "0xBBGGRR" format. function set_fold_margin_colour(buffer, use_setting, color) end --- --- Set the colors used as a checkerboard pattern in the fold margin. +-- Overrides the default highlight color of the fold margin with *color*, in +-- "0xBBGGRR" format, if *use_setting* is `true`. -- @param buffer The global buffer. -- @param use_setting Enable color change. -- @param color A color in "0xBBGGRR" format. function set_fold_margin_hi_colour(buffer, use_setting, color) end --- --- Set a back color for active hotspots. +-- Overrides the default background color of active hotspots with *color*, in +-- "0xBBGGRR" format, if *use_setting* is `true`. -- @param buffer The global buffer. -- @param use_setting Enable the color change. -- @param color A color in "0xBBGGRR" format. function set_hotspot_active_back(buffer, use_setting, color) end --- --- Set a fore color for active hotspots. +-- Overrides the default foreground color of active hotspots with *color*, in +-- "0xBBGGRR" format, if *use_setting* is `true`. -- @param buffer The global buffer. -- @param use_setting Enable the color change. -- @param color A color in "0xBBGGRR" format. function set_hotspot_active_fore(buffer, use_setting, color) end --- --- Set the length of the utf8 argument for calling `buffer:encoded_from_utf8()`. +-- Sets the length of *string* in `buffer:encoded_from_utf8()` to *bytes*. -- @param buffer The global buffer. -- @param bytes Bytes or `-1` for measuring to first null byte. function set_length_for_encode(buffer, bytes) end --- --- Remember the current position in the undo history as the position at which --- the document was saved. +-- Tells Scintilla the buffer has no unsaved changes. -- @param buffer The global buffer. function set_save_point(buffer) end --- --- Select a range of text. --- The caret is scrolled into view after this operation. +-- Selects the range of text from *start_pos* to *end_pos* in the buffer, +-- scrolling the selected text into view. -- @param buffer The global buffer. -- @param start_pos Start position. If negative, it means the end of the -- document. @@ -2174,45 +2283,48 @@ function set_save_point(buffer) end function set_sel(buffer, start_pos, end_pos) end --- --- Set the background color of the main and additional selections and whether to --- use this setting. +-- Overrides the default background color of all selected text with *color*, in +-- "0xBBGGRR" format, if *use_setting* is `true`. -- @param buffer The global buffer. -- @param use_setting Enable color change. -- @param color A color in "0xBBGGRR" format. function set_sel_back(buffer, use_setting, color) end --- --- Set the foreground color of the main and additional selections and whether --- to use this setting. +-- Overrides the default foreground color of all selected text with *color*, in +-- "0xBBGGRR" format, if *use_setting* is `true`. -- @param buffer The global buffer. -- @param use_setting Enable color change. -- @param color A color in "0xBBGGRR" format. function set_sel_fore(buffer, use_setting, color) end --- --- Set a simple selection from anchor to caret. +-- Selects the range of text from *anchor* to *caret* in the buffer, removing +-- all other selections. -- @param buffer The global buffer. -- @param caret The caret. -- @param anchor The anchor. function set_selection(buffer, caret, anchor) end --- --- Change style from current styling position for length characters to a style --- and move the current styling position to after this newly styled segment. +-- Sets the style of the next *length* characters, from the current styling +-- position, to style number *style*, in the range from `0` to `255`, and +-- increments the styling position by *length*. -- @param buffer The global buffer. -- @param length The length to style. -- @param style The style number to set. function set_styling(buffer, length, style) end --- --- Replace the contents of the document with the argument text. +-- Replaces all of the text in the buffer with string *text*. -- @param buffer The global buffer. -- @param text The text. function set_text(buffer, text) end --- --- Set the way the display area is determined when a particular line is to be --- moved to by `buffer:goto_line()`, etc. +-- Sets the visible policy bit-mask *visible_policy* for displaying lines using +-- `buffer:ensure_visible_enforce_policy()` to *visible_slop* number of lines +-- from the bottom of the view. -- It is similar in operation to `buffer:set_y_caret_policy()`. -- @param buffer The global buffer. -- @param visible_policy A combination of `_SCINTILLA.constants.VISIBLE_SLOP` @@ -2221,15 +2333,16 @@ function set_text(buffer, text) end function set_visible_policy(buffer, visible_policy, visible_slop) end --- --- Set the background color of all whitespace and whether to use this setting. +-- Overrides the background color of whitespace with *color*, in "0xBBGGRR" +-- format, if *use_setting* is `true`. -- @param buffer The global buffer. -- @param use_setting Enable color change. -- @param color A color in "0xBBGGRR" format. function set_whitespace_back(buffer, use_setting, color) end --- --- Set the foreground color of all whitespace and whether to use this setting. --- @param buffer The global buffer. +-- Overrides the foreground color of whitespace with *color*, in "0xBBGGRR" +-- format, if *use_setting* is `true`. -- @param use_setting Enable color change. -- @param color A color in "0xBBGGRR" format. function set_whitespace_fore(buffer, use_setting, color) end @@ -2256,8 +2369,8 @@ function set_x_caret_policy(buffer, caret_policy, caret_slop) end function set_y_caret_policy(buffer, caret_policy, caret_slop) end --- --- Make a range of lines visible. --- This has no effect on fold levels or fold flags. `start_line` can not be +-- Shows the range of lines from line number *start_line* to *end_line*. +-- This has no effect on fold levels or fold flags and the first line cannot be -- hidden. -- @param buffer The global buffer. -- @param start_line The start line. @@ -2265,88 +2378,81 @@ function set_y_caret_policy(buffer, caret_policy, caret_slop) end function show_lines(buffer, start_line, end_line) end --- --- Start notifying the container of all key presses and commands. --- @param buffer The global buffer. -function start_record(buffer) end - ---- --- Set the current styling position to pos and the styling mask to mask. --- The styling mask can be used to protect some bits in each styling byte from --- modification. +-- Begin styling at position *position* with the 8-bit styling bit-mask *mask* +-- that determines which style bits can be set with `buffer:set_styling()`. -- @param buffer The global buffer. -- @param position The styling position. -- @param mask The bit mask of the style bytes that can be set. +-- @usage buffer:start_styling(0, 0xFF) function start_styling(buffer, position, mask) end --- --- Stop notifying the container of all key presses and commands. --- @param buffer The global buffer. -function stop_record(buffer) end - ---- --- Move caret to bottom of page, or one page down if already at bottom of page. +-- Moves the caret to the bottom of the page, or if already there, one page +-- down. -- @param buffer The global buffer. function stuttered_page_down(buffer) end --- --- Move caret to bottom of page, or one page down if already at bottom of page, --- extending selection to new caret position. +-- Like `buffer:stuttered_page_down()`, but extends the selection to the new +-- position. -- @param buffer The global buffer. function stuttered_page_down_extend(buffer) end --- --- Move caret to top of page, or one page up if already at top of page. +-- Moves the caret to the top of the page, or if already there, one page up. -- @param buffer The global buffer. function stuttered_page_up(buffer) end --- --- Move caret to top of page, or one page up if already at top of page, --- extending selection to new caret position. +-- Like `buffer:stuttered_page_up()`, but extends the selection to the new +-- position. -- @param buffer The global buffer. function stuttered_page_up_extend(buffer) end --- --- Clear all the styles and make equivalent to the global default style. +-- Sets all styles to have the same properties as +-- `_SCINTILLA.constants.STYLE_DEFAULT`. -- @param buffer The global buffer. function style_clear_all(buffer) end --- --- Reset the default style to its state at startup. +-- Resets `_SCINTILLA.constants.STYLE_DEFAULT` to its initial state. -- @param buffer The global buffer. function style_reset_default(buffer) end --- --- Swap that caret and anchor of the main selection. +-- Swaps the anchor and caret positions of the main selection. -- @param buffer The global buffer. function swap_main_anchor_caret(buffer) end --- --- If selection is empty or all on one line replace the selection with a tab --- character, or if more than one line selected, indent the lines. +-- Indents the selected lines, replaces the selected text on a line with a Tab +-- character ("\t"), or inserts a Tab character at the current position. -- @param buffer The global buffer. function tab(buffer) end --- --- Returns the target converted to UTF8. +-- Returns the result of the text in the target range converted from the +-- buffer's code page into UTF-8. -- @param buffer The global buffer. function target_as_utf8(buffer) end --- --- Make the target range start and end be the same as the selection range start --- and end. +-- Sets the beginning and end positions of the target range to be the beginning +-- and end positions of the main selection. -- @param buffer The global buffer. function target_from_selection(buffer) end --- --- Retrieve the height of a particular line of text in pixels. +-- Returns the height in pixels of line number *line*. -- @param buffer The global buffer. -- @param line The line number. -- @return number function text_height(buffer, line) end --- --- Measure the pixel width of some text in a particular style. --- Does not handle tab or control characters. +-- Returns the width in pixels of string *text* styled with style number +-- *style_num*, in the range of `0` to `255`. -- @param buffer The global buffer. -- @param style_num The style number between `0` and `255`. -- @param text The text. @@ -2354,36 +2460,37 @@ function text_height(buffer, line) end function text_width(buffer, style_num, text) end --- --- Switch between sticky and non-sticky: meant to be bound to a key. --- See `buffer.caret_sticky`. +-- Cycles between caret sticky option settings +-- `_SCINTILLA.constants.SC_CARETSTICKY_ON`, +-- `_SCINTILLA.constants.SC_CARETSTICKY_WHITESPACE`, and +-- `_SCINTILLA.constants.SC_CARETSTICKY_OFF`. -- @param buffer The global buffer. +-- @see caret_sticky function toggle_caret_sticky(buffer) end --- --- Switch a header line between expanded and contracted. +-- Toggles the fold state of a fold header line between expanded, where all +-- of its child lines are displayed, and contracted, where all of its child +-- lines are hidden. -- @param buffer The global buffer. -- @param line The line number. function toggle_fold(buffer, line) end --- --- Undo one action in the undo history. +-- Undoes the most recent action. -- @param buffer The global buffer. function undo(buffer) end --- --- Transform the selection to upper case. +-- Converts the selected text to upper case letters. -- @param buffer The global buffer. function upper_case(buffer) end --- --- Sets whether a pop up menu is displayed automatically when the user presses --- the wrong mouse button. --- @param buffer The global buffer. --- @param allow_popup Allow popup menu. -function use_pop_up(buffer, allow_popup) end - ---- --- Display a list of strings and send notification when user chooses one. +-- Displays a list from *item_list*, a sorted string whose items are delimited +-- by `buffer.auto_c_separator` characters, using the list identifier number +-- *list_type* which is greater than zero and sent in a `USER_LIST_SELECTION` +-- event after selecting an item. -- @param buffer The global buffer. -- @param list_type A list identifier number greater than zero. -- @param item_list List of words separated by separator characters (initially @@ -2392,63 +2499,65 @@ function use_pop_up(buffer, allow_popup) end function user_list_show(buffer, list_type, item_list) end --- --- Move caret to before first visible character on line. --- If already there move to first character on line. +-- Moves the caret to the first visible character on the current line, or if +-- already there, to the beginning of the current line. -- @param buffer The global buffer. function vc_home(buffer) end --- --- Move caret to before first visible character on display line. --- If already there move to first character on display line. +-- Moves the caret to the first visible character on the current wrapped line, +-- or if already there, to the beginning of the current wrapped line. -- @param buffer The global buffer. function vc_home_display(buffer) end --- --- Like `buffer:vc_home_display()` but extending selection to new caret +-- Like `buffer:vc_home_display()`, but extends the selection to the new -- position. -- @param buffer The global buffer. function vc_home_display_extend(buffer) end --- --- Like `buffer:vc_home()` but extending selection to new caret position. +-- Like `buffer:vc_home()`, but extends the selection to the new position. -- @param buffer The global buffer. function vc_home_extend(buffer) end --- --- Move caret to before first visible character on line. --- If already there move to first character on line. In either case, extend --- rectangular selection to new caret position. +-- Like `buffer:vc_home()`, but extends the rectangular selection to the new +-- position. -- @param buffer The global buffer. function vc_home_rect_extend(buffer) end --- --- Move caret to before first visible character on display line when word-wrap --- is enabled. --- If already there, go to first character on display line. +-- Moves the caret to the first visible character on the wrapped line, or if +-- already there, to the beginning of the actual line. -- @param buffer The global buffer. function vc_home_wrap(buffer) end --- --- Like `buffer:vc_home_wrap()` but extending selection to new caret position. +-- Like `buffer:vc_home_wrap()`, but extends the selection to the new position. -- @param buffer The global buffer. function vc_home_wrap_extend(buffer) end --- --- Center current line in window. +-- Centers current line in the view. -- @param buffer The global buffer. function vertical_centre_caret(buffer) end --- --- Find the display line of a document line taking hidden lines into account. --- If there is folding and line is outside the range of lines in the document, --- the return value is `-1`. +-- Returns the displayed line number of actual line number *line*, taking 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. -- @param buffer The global buffer. -- @param line The line number. -- @return number function visible_from_doc_line(buffer, line) end --- --- Get position of end of word. +-- Returns the position of the end of the word at position *pos*. +-- `buffer.word_chars` contains word characters. If *pos* has a non-word +-- character to its right and *only_word_chars* is `false`, returns the position +-- of the first word character. -- @param buffer The global buffer. -- @param pos The position. -- @param only_word_chars If `true`, stops searching at the first non-word @@ -2459,71 +2568,87 @@ function visible_from_doc_line(buffer, line) end function word_end_position(buffer, pos, only_word_chars) end --- --- Move caret left one word. +-- Moves the caret left one word. +-- `buffer.word_chars` contains word characters. -- @param buffer The global buffer. function word_left(buffer) end --- --- Move caret left one word, position cursor at end of word. +-- Moves the caret left one word, positioning the current position at the end of +-- the previous word. +-- `buffer.word_chars` contains word characters. -- @param buffer The global buffer. function word_left_end(buffer) end --- --- Move caret left one word, position cursor at end of word, extending selection --- to new caret position. +-- Like `buffer:word_left_end()`, but extends the selection to the new position. -- @param buffer The global buffer. function word_left_end_extend(buffer) end --- --- Move caret left one word extending selection to new caret position. +-- Moves the caret left one word, extending the selection to the new position. +-- `buffer.word_chars` contains word characters. -- @param buffer The global buffer. function word_left_extend(buffer) end --- --- Move to the previous change in capitalisation or underscores. +-- Moves to the previous underscore or change in capitalization within the +-- current word. +-- `buffer.word_chars` contains word characters. -- @param buffer The global buffer. function word_part_left(buffer) end --- --- Move to the previous change in capitalisation or underscores extending --- selection to new caret position. +-- Moves to the previous underscore or change in capitalization within the +-- current word, extending the selection to the new position. +-- `buffer.word_chars` contains word characters. -- @param buffer The global buffer. function word_part_left_extend(buffer) end --- --- Move to the next change in capitalisation or underscores. +-- Moves to the next underscore or change in capitalization within the current +-- word. +-- `buffer.word_chars` contains word characters. -- @param buffer The global buffer. function word_part_right(buffer) end --- --- Move to the next change in capitalisation or underscores extending selection --- to new caret position. +-- Moves to the next underscore or change in capitalization within the current +-- word, extending the selection to the new position. +-- `buffer.word_chars` contains word characters. -- @param buffer The global buffer. function word_part_right_extend(buffer) end --- --- Move caret right one word. +-- Moves the caret right one word. +-- `buffer.word_chars` contains word characters. -- @param buffer The global buffer. function word_right(buffer) end --- --- Move caret right one word, position cursor at end of word. +-- Moves the caret right one word, positioning the cursor at the end of the +-- current word. +-- `buffer.word_chars` contains word characters. -- @param buffer The global buffer. function word_right_end(buffer) end --- --- Move caret right one word, position cursor at end of word, extending --- selection to new caret position. +-- Like `buffer:word_right_end()`, but extends the selection to the new +-- position. -- @param buffer The global buffer. function word_right_end_extend(buffer) end --- --- Move caret right one word extending selection to new caret position. +-- Moves the caret right one word, extending the selection to the new position. +-- `buffer.word_chars` contains word characters. -- @param buffer The global buffer. function word_right_extend(buffer) end --- --- Get position of start of word. +-- Returns the position of the beginning of the word at position *pos*. +-- `buffer.word_chars` contains word characters. If *pos* has a non-word +-- character to its left and *only_word_chars* is `false`, returns the position +-- of the last word character. -- @param buffer The global buffer. -- @param pos The position. -- @param only_word_chars If `true`, stops searching at the first non-word @@ -2534,58 +2659,56 @@ function word_right_extend(buffer) end function word_start_position(buffer, pos, only_word_chars) end --- --- Returns the number of display lines needed to wrap a document line. +-- Returns the number of wrapped lines needed to display line number *line*. -- @param buffer The global buffer. -- @param line The line number. -- @return number function wrap_count(buffer, line) end --- --- Magnify the displayed text by increasing the sizes by 1 point if the current --- zoom factor is less than 20 points. +-- Increases the size of all fonts by one point, up to 20. -- @param buffer The global buffer. function zoom_in(buffer) end --- --- Make the displayed text smaller by decreasing the sizes by 1 point if the --- current zoom factor is greater than -10 points. +-- Decreases the size of all fonts by one point, down to -10. -- @param buffer The global buffer. function zoom_out(buffer) end -- External functions. --- --- Checks whether the given buffer is the global one. --- If not, throws an error indicating so. It is necessary to call this at the --- top of all buffer functions to avoid unexpected behavior since most buffer --- functions operate on `_G.buffer`, which is not necessarily the given one. +-- Ensures the buffer is the global one, `_G.buffer`, throwing an error +-- otherwise. +-- This function must be called in all buffer functions because only the global +-- buffer can be worked with. -- @param buffer The buffer to check. -- @see _G._G.buffer function check_global(buffer) end --- --- Deletes the current buffer. --- WARNING: this function should NOT be called via scripts. Use `buffer:close()` --- instead, which prompts for confirmation if necessary. Emits a +-- Deletes the buffer. +-- **Do not call this function.** Call `buffer:close()` instead. Emits a -- `BUFFER_DELETED` event. -- @param buffer The global buffer. -- @see events.BUFFER_DELETED function delete(buffer) end --- --- Gets a range of text from the current buffer. +-- Returns the range of text from *start_pos* to *end_pos* in the buffer. -- @param buffer The global buffer. -- @param start_pos The beginning position of the range of text to get. -- @param end_pos The end position of the range of text to get. function text_range(buffer, start_pos, end_pos) end --- --- Reloads the file in a given buffer. +-- Reloads the file in the buffer. -- @param buffer The global buffer. function reload(buffer) end --- --- Sets the encoding for the buffer, converting its contents in the process. +-- Sets the encoding for the buffer to *encoding*, converting its contents from +-- the old encoding to the new one. -- @param buffer The global buffer. -- @param encoding The encoding to set. Valid encodings are ones that GNU iconv -- accepts. @@ -2593,14 +2716,14 @@ function reload(buffer) end function set_encoding(buffer, encoding) end --- --- Saves the current buffer to a file. +-- Saves the buffer to the file. -- Emits `FILE_BEFORE_SAVE` and `FILE_AFTER_SAVE` events. -- @param buffer The global buffer. -- @see _G.events function save(buffer) end --- --- Saves the current buffer to a file different than its filename property. +-- Saves the buffer to the *utf8_filename* or user-specified filename. -- Emits a `FILE_SAVED_AS` event. -- @param buffer The global buffer. -- @param utf8_filename The new filepath to save the buffer to. Must be UTF-8 @@ -2609,46 +2732,50 @@ function save(buffer) end function save_as(buffer, utf8_filename) end --- --- Closes the current buffer. +-- Closes the buffer, prompting the user to continue if there are unsaved +-- changes, and returns `true` if the buffer was closed. -- @param buffer The global buffer. --- If the buffer is dirty, the user is prompted to continue. The buffer is not --- saved automatically. It must be done manually. -- @return `true` if the buffer was closed; `nil` otherwise. function close(buffer) end --- --- Replacement for `buffer.lexer_language =`. --- Sets a `buffer._lexer` field so it can be restored without querying the --- mime-types tables. Also if the user manually sets the lexer, it should be --- restored. --- Loads the language-specific module if it exists. --- This function is added by `_M.textadept.mime_types`. +-- Sets the name of the lexer used by the buffer to *lang*, loading its +-- language-specific module if the module exists. -- @param buffer The global buffer. -- @param lang The string language to set. -- @usage buffer.set_lexer(buffer, 'language_name') function set_lexer(buffer, lang) end --- --- Replacement for `buffer.lexer_language`. +-- Returns the name of the lexer used by the buffer, or the name of the lexer at +-- the current position in a multiple-language lexer if *current* is `true`. -- @param buffer The global buffer. -- @param current Whether to get the lexer at the current caret position in -- multi-language lexers. The default is `false` and returns the parent lexer. function get_lexer(buffer, current) end --- --- Returns the name of the style associated with a style number. +-- Returns the name of style number *style_num*, in the range of `0` to `255`. -- @param buffer The global buffer. -- @param style_num A style number from `0` to `255`. -- @see buffer.style_at function get_style_name(buffer, style_num) end -- Unused Fields. +-- * status +-- * mouse_down_captures +-- * focus -- * use_palette +-- * font_quality +-- * keys_unicode -- * doc_pointer -- * mod_event_mask -- * paste_convert_endings +-- * direct_function +-- * direct_pointer -- * character_pointer -- * get_range_pointer +-- * field gap_position -- * identifier -- * key_words -- * technology @@ -2662,6 +2789,9 @@ function get_style_name(buffer, style_num) end -- * find_text -- * format_range -- * null +-- * use_pop_up +-- * start_record +-- * stop_record -- * create_document -- * add_ref_document -- * release_document @@ -2679,3 +2809,4 @@ function get_style_name(buffer, style_num) end -- * describe_property -- * describe_key_word_sets -- * create_loader +-- * private_lexer_call diff --git a/core/.iconv.luadoc b/core/.iconv.luadoc index 78616a30..b21f6c5a 100644 --- a/core/.iconv.luadoc +++ b/core/.iconv.luadoc @@ -6,8 +6,30 @@ module('string') --- --- Converts a string from one character set to another using iconv. --- Valid character sets are [GNU iconv's character sets][]. +-- Converts string *text* from character set *from* to character set *to* using +-- iconv. +-- Valid character sets are [GNU iconv's character sets][] 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 iconv's character sets]: http://www.gnu.org/software/libiconv/ -- @param text The text to convert. diff --git a/core/.view.luadoc b/core/.view.luadoc index 6913baa6..269c818d 100644 --- a/core/.view.luadoc +++ b/core/.view.luadoc @@ -15,29 +15,34 @@ module('view') local buffer --- --- Splits the given view vertically or horizontally and focuses the new view. +-- 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. -- @param view The view to split. --- @param vertical Flag indicating a vertical split. The default value is --- `false` for horizontal. +-- @param 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 events.VIEW_NEW function split(view, vertical) end --- --- Unsplits the given view if possible. +-- Unsplits the view if possible, returning `true` on success. -- @param view The view to unsplit. -- @return boolean if the view was unsplit or not. function unsplit(view) end --- --- Goes to the specified buffer in the given view. +-- Goes to buffer number *n* in the view. +-- If *relative* is `true`, *n* is an index relative to the index of the current +-- buffer in `_G._BUFFERS` instead of an absolute index. -- Emits `BUFFER_BEFORE_SWITCH` and `BUFFER_AFTER_SWITCH` events. -- @param view The view to switch buffers in. -- @param n A relative or absolute buffer index in `_G._BUFFERS`. An absolute -- index of `-1` goes to the last buffer. --- @param relative Flag indicating if `n` is a relative index or not. The --- default value is `false`. +-- @param relative Optional flag indicating whether *n* is a relative or +-- absolute index. The default value is `false` for an absolute index. -- @see _G._G._BUFFERS -- @see events.BUFFER_BEFORE_SWITCH -- @see events.BUFFER_AFTER_SWITCH diff --git a/core/args.lua b/core/args.lua index 1a410ba4..b7ddde8d 100644 --- a/core/args.lua +++ b/core/args.lua @@ -20,23 +20,26 @@ local arg = arg local switches = {} --- --- Registers a command line switch. --- @param switch1 String switch (short version). --- @param switch2 String switch (long version). +-- Registers a command line switch with short and long versions *short* and +-- *long*, respectively. *narg* is the number of arguments the switch accepts, +-- *f* is the function called when the switch is tripped, and *description* is +-- the switch's description when displaying help. +-- @param short String short version of the switch. +-- @param long String long version of the switch. -- @param narg The number of expected parameters for the switch. -- @param f The Lua function to run when the switch is tripped. -- @param description Description of the switch for command line help. -- @name register -function M.register(switch1, switch2, narg, f, description) +function M.register(short, long, narg, f, description) local t = {f, narg, description} - switches[switch1], switches[switch2] = t, t + switches[short], switches[long] = t, t end --- --- Processes command line arguments. --- Add command line switches with `args.register()`. Any unrecognized arguments --- are treated as filepaths and opened. --- Emits an `'arg_none'` event when no args are present. +-- Processes command line argument table *arg*, handling switches previously +-- defined using `args.register()` and treating unrecognized arguments as +-- filenames to open. +-- Emits an `'arg_none'` event when no arguments are present. -- @param arg Argument table. -- @see register -- @see events diff --git a/core/events.lua b/core/events.lua index 9139a30a..46ee8f6c 100644 --- a/core/events.lua +++ b/core/events.lua @@ -27,241 +27,233 @@ local M = {} -- Called when Mac OSX tells Textadept to open a document. -- Arguments: -- --- * `uri`: The URI to open encoded in UTF-8. +-- * _`uri`_: The UTF-8-encoded URI to open. -- @field AUTO_C_CHAR_DELETED (string) --- Called when the user deleted a character while the autocompletion list was --- active. +-- Called when deleting a character while the autocompletion list is active. -- @field AUTO_C_RELEASE (string) --- Called when the user has cancelled the autocompletion list. +-- Called when canceling the autocompletion list. -- @field AUTO_C_SELECTION (string) --- Called when the user has selected an item in an autocompletion list and --- before the selection is inserted. +-- Called when selecting an item in the autocompletion list and before +-- inserting the selection. -- Automatic insertion can be cancelled by calling -- [`buffer:auto_c_cancel()`][] before returning from the event handler. -- Arguments: -- --- * `text`: The text of the selection. --- * `position`: The start position of the word being completed. +-- * _`text`_: The text of the selection. +-- * _`position`_: The position in the buffer of the beginning of the +-- autocompleted word. -- @field BUFFER_AFTER_SWITCH (string) --- Called right after a buffer is switched to. --- This is emitted by [`view:goto_buffer()`][]. +-- Called right after switching to another buffer. +-- Emitted by [`view:goto_buffer()`][]. -- @field BUFFER_BEFORE_SWITCH (string) --- Called right before another buffer is switched to. --- This is emitted by [`view:goto_buffer()`][]. +-- Called right before switching to another buffer. +-- Emitted by [`view:goto_buffer()`][]. -- @field BUFFER_DELETED (string) --- Called after a buffer was deleted. --- This is emitted by [`buffer:delete()`][]. +-- Called after deleting a buffer. +-- Emitted by [`buffer:delete()`][]. -- @field BUFFER_NEW (string) --- Called when a new buffer is created. --- This is emitted on startup and by [`new_buffer()`][]. +-- Called after creating a new buffer. +-- Emitted on startup and by [`new_buffer()`][]. -- @field CALL_TIP_CLICK (string) --- Called when the user clicks on a calltip. +-- Called when clicking on a calltip. -- Arguments: -- --- * `position`: Set to 1 if the click is in an up arrow, 2 if in a down --- arrow, and 0 if elsewhere. +-- * _`position`_: `1` if the up arrow was clicked, 2 if the down arrow was +-- clicked, and 0 otherwise. -- @field CHAR_ADDED (string) --- Called when an ordinary text character is added to the buffer. +-- Called after adding an ordinary text character to the buffer. -- Arguments: -- --- * `ch`: The text character byte. +-- * _`ch`_: The text character byte. -- @field COMMAND_ENTRY_COMMAND (string) --- Called when a command is entered into the Command Entry. +-- Called to run the command entered into the Command Entry. -- If any handler returns `true`, the Command Entry does not hide -- automatically. -- Arguments: -- --- * `command`: The command text. +-- * _`command`_: The command text. -- @field COMMAND_ENTRY_KEYPRESS (string) --- Called when a key is pressed in the Command Entry. +-- Called when pressing a key in the Command Entry. -- If any handler returns `true`, the key is not inserted into the entry. -- Arguments: -- --- * `code`: The key code. --- * `shift`: The "Shift" modifier key is held down. --- * `ctrl`: The "Control"/"Command" modifier key is held down. --- * `alt`: The "Alt"/"Option" modifier key is held down. --- * `meta`: The "Control" modifier key on Mac OSX is held down. +-- * _`code`_: The numeric key code. +-- * _`shift`_: The "Shift" modifier key is held down. +-- * _`ctrl`_: The "Control"/"Command" modifier key is held down. +-- * _`alt`_: The "Alt"/"Option" modifier key is held down. +-- * _`meta`_: The "Control" modifier key on Mac OSX is held down. -- @field DOUBLE_CLICK (string) --- Called when the mouse button is double-clicked. +-- Called after double-clicking the mouse button. -- Arguments: -- --- * `position`: The text position of the double click. --- * `line`: The line of the double click. --- * `modifiers`: The key modifiers held down. It is a combination of zero or --- more of `_SCINTILLA.constants.SCMOD_ALT`, --- `_SCINTILLA.constants.SCMOD_CTRL`, +-- * _`position`_: The position in the buffer double-clicked. +-- * _`line`_: The line number double-clicked. +-- * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are +-- `_SCINTILLA.constants.SCMOD_ALT`, `_SCINTILLA.constants.SCMOD_CTRL`, -- `_SCINTILLA.constants.SCMOD_SHIFT`, and -- `_SCINTILLA.constants.SCMOD_META`. -- Note: If you set `buffer.rectangular_selection_modifier` to -- `_SCINTILLA.constants.SCMOD_CTRL`, the "Control" modifier is reported as -- *both* "Control" and "Alt" due to a Scintilla limitation with GTK+. -- @field DWELL_END (string) --- Called after a `DWELL_START` and the mouse is moved or other activity such --- as key press indicates the dwell is over. +-- Called after a `DWELL_START` when the mouse moves, a key is pressed, etc. -- Arguments: -- --- * `position`: The nearest position in the document to the position where --- the mouse pointer was lingering. --- * `x`: Where the pointer lingered. --- * `y`: Where the pointer lingered. +-- * _`position`_: The position in the buffer closest to *x* and *y*. +-- * _`x`_: The x-coordinate of the mouse in the view. +-- * _`y`_: The y-coordinate of the mouse in the view. -- @field DWELL_START (string) --- Called when the user keeps the mouse in one position for the dwell period --- (see `_SCINTILLA.constants.SCI_SETMOUSEDWELLTIME`). +-- Called after keeping the mouse stationary for the [dwell period][] -- Arguments: -- --- * `position`: The nearest position in the document to the position where --- the mouse pointer was lingering. --- * `x`: Where the pointer lingered. --- * `y`: Where the pointer lingered. +-- * _`position`_: The position in the buffer closest to *x* and *y*. +-- * _`x`_: The x-coordinate of the mouse in the view. +-- * _`y`_: The y-coordinate of the mouse in the view. -- @field ERROR (string) -- Called when an error occurs. -- Arguments: -- --- * `text`: The error text. +-- * _`text`_: The error text. -- @field FIND (string) --- Called when finding text via the Find dialog box. +-- Called to find text via the Find dialog box. -- Arguments: -- --- * `text`: The text to search for. --- * `next`: Search forward. +-- * _`text`_: The text to search for. +-- * _`next`_: Whether or not to search forward. -- @field HOTSPOT_CLICK (string) --- Called when the user clicks on text that is in a style with the hotspot --- attribute set. +-- Called when clicking on text that is in a style with the hotspot attribute +-- set. -- Arguments: -- --- * `position`: The text position of the click. --- * `modifiers`: The key modifiers held down. It is a combination of zero or --- more of `_SCINTILLA.constants.SCMOD_ALT`, --- `_SCINTILLA.constants.SCMOD_CTRL`, +-- * _`position`_: The position in the buffer clicked. +-- * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are +-- `_SCINTILLA.constants.SCMOD_ALT`, `_SCINTILLA.constants.SCMOD_CTRL`, -- `_SCINTILLA.constants.SCMOD_SHIFT`, and -- `_SCINTILLA.constants.SCMOD_META`. -- Note: If you set `buffer.rectangular_selection_modifier` to -- `_SCINTILLA.constants.SCMOD_CTRL`, the "Control" modifier is reported as -- *both* "Control" and "Alt" due to a Scintilla limitation with GTK+. -- @field HOTSPOT_DOUBLE_CLICK (string) --- Called when the user double clicks on text that is in a style with the --- hotspot attribute set. +-- Called when double-clicking on text that is in a style with the hotspot +-- attribute set. -- Arguments: -- --- * `position`: The text position of the double click. --- * `modifiers`: The key modifiers held down. It is a combination of zero or --- more of `_SCINTILLA.constants.SCMOD_ALT`, --- `_SCINTILLA.constants.SCMOD_CTRL`, +-- * _`position`_: The position in the buffer double-clicked. +-- * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are +-- `_SCINTILLA.constants.SCMOD_ALT`, `_SCINTILLA.constants.SCMOD_CTRL`, -- `_SCINTILLA.constants.SCMOD_SHIFT`, and -- `_SCINTILLA.constants.SCMOD_META`. -- Note: If you set `buffer.rectangular_selection_modifier` to -- `_SCINTILLA.constants.SCMOD_CTRL`, the "Control" modifier is reported as -- *both* "Control" and "Alt" due to a Scintilla limitation with GTK+. -- @field HOTSPOT_RELEASE_CLICK (string) --- Called when the user releases the mouse on text that is in a style with the --- hotspot attribute set. +-- Called after releasing the mouse after clicking on text that was in a style +-- with the hotspot attribute set. -- Arguments: -- --- * `position`: The text position of the release. +-- * _`position`_: The position in the buffer unclicked. -- @field INDICATOR_CLICK (string) --- Called when the user clicks the mouse on text that has an indicator. +-- Called when clicking the mouse on text that has an indicator. -- Arguments: -- --- * `position`: The text position of the click. --- * `modifiers`: The key modifiers held down. It is a combination of zero or --- more of `_SCINTILLA.constants.SCMOD_ALT`, --- `_SCINTILLA.constants.SCMOD_CTRL`, +-- * _`position`_: The position in the buffer clicked. +-- * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are +-- `_SCINTILLA.constants.SCMOD_ALT`, `_SCINTILLA.constants.SCMOD_CTRL`, -- `_SCINTILLA.constants.SCMOD_SHIFT`, and -- `_SCINTILLA.constants.SCMOD_META`. -- Note: If you set `buffer.rectangular_selection_modifier` to -- `_SCINTILLA.constants.SCMOD_CTRL`, the "Control" modifier is reported as -- *both* "Control" and "Alt" due to a Scintilla limitation with GTK+. -- @field INDICATOR_RELEASE (string) --- Called when the user releases the mouse on text that has an indicator. +-- Called after releasing the mouse after clicking on text that had an +-- indicator. -- Arguments: -- --- * `position`: The text position of the release. +-- * _`position`_: The position in the buffer unclicked. -- @field KEYPRESS (string) --- Called when a key is pressed. +-- Called when pressing a key. -- If any handler returns `true`, the key is not inserted into the buffer. -- Arguments: -- --- * `code`: The key code. --- * `shift`: The "Shift" modifier key is held down. --- * `ctrl`: The "Control"/"Command" modifier key is held down. --- * `alt`: The "Alt"/"Option" modifier key is held down. --- * `meta`: The "Control" modifier key on Mac OSX is held down. +-- * _`code`_: The numeric key code. +-- * _`shift`_: The "Shift" modifier key is held down. +-- * _`ctrl`_: The "Control"/"Command" modifier key is held down. +-- * _`alt`_: The "Alt"/"Option" modifier key is held down. +-- * _`meta`_: The "Control" modifier key on Mac OSX is held down. -- @field MARGIN_CLICK (string) --- Called when the mouse is clicked inside a margin. +-- Called when clicking the mouse inside a margin. -- Arguments: -- --- * `margin`: The margin number that was clicked. --- * `position`: The position of the start of the line in the buffer that --- corresponds to the margin click. --- * `modifiers`: The appropriate combination of --- `_SCINTILLA.constants.SCI_SHIFT`, `_SCINTILLA.constants.SCI_CTRL`, --- and `_SCINTILLA.constants.SCI_ALT` to indicate the keys that were held --- down at the time of the margin click. +-- * _`margin`_: The margin number clicked. +-- * _`position`_: The position of the start of the line in the buffer whose +-- margin line was clicked. +-- * _`modifiers`_: A bit-mask of modifier keys held down. Modifiers are +-- `_SCINTILLA.constants.SCMOD_ALT`, `_SCINTILLA.constants.SCMOD_CTRL`, +-- `_SCINTILLA.constants.SCMOD_SHIFT`, and +-- `_SCINTILLA.constants.SCMOD_META`. -- Note: If you set `buffer.rectangular_selection_modifier` to -- `_SCINTILLA.constants.SCMOD_CTRL`, the "Control" modifier is reported as -- *both* "Control" and "Alt" due to a Scintilla limitation with GTK+. -- @field MENU_CLICKED (string) --- Called when a menu item is selected. +-- Called after selecting a menu item. -- Arguments: -- --- * `menu_id`: The numeric ID of the menu item set in [`gui.menu()`][]. +-- * _`menu_id`_: The numeric ID of the menu item set in [`gui.menu()`][]. -- @field QUIT (string) -- Called when quitting Textadept. -- When connecting to this event, connect with an index of 1 or the handler -- will be ignored. --- This is emitted by [`quit()`][]. +-- Emitted by [`quit()`][]. -- @field REPLACE (string) -- Called to replace selected (found) text. -- Arguments: -- --- * `text`: The text to replace selected text with. +-- * _`text`_: The text to replace the selected text with. -- @field REPLACE_ALL (string) --- Called to replace all occurances of found text. +-- Called to replace all occurrences of found text. -- Arguments: -- --- * `find_text`: The text to search for. --- * `repl_text`: The text to replace found text with. +-- * _`find_text`_: The text to search for. +-- * _`repl_text`_: The text to replace found text with. -- @field RESET_AFTER (string) -- Called after resetting the Lua state. --- This is emitted by [`reset()`][]. +-- Emitted by [`reset()`][]. -- @field RESET_BEFORE (string) -- Called before resetting the Lua state. --- This is emitted by [`reset()`][]. +-- Emitted by [`reset()`][]. -- @field SAVE_POINT_LEFT (string) --- Called when a save point is left. +-- Called after leaving a save point. -- @field SAVE_POINT_REACHED (string) --- Called when a save point is entered. +-- Called after reaching a save point. -- @field UPDATE_UI (string) --- Called when either the text or styling of the buffer has changed or the --- selection range has changed. +-- Called when the text, styling, or selection range in the buffer changes. -- @field URI_DROPPED (string) --- Called when the user has dragged a URI such as a file name onto the view. +-- Called after dragging and dropping a URI such as a file name onto the view. -- Arguments: -- --- * `text`: The URI text encoded in UTF-8. +-- * _`text`_: The UTF-8-encoded URI text. -- @field USER_LIST_SELECTION (string) --- Called when the user has selected an item in a user list. +-- Called after selecting an item in a user list. -- Arguments: -- --- * `list_type`: This is set to the list_type parameter from the --- [`buffer:user_list_show()`][] call that initiated the list. --- * `text`: The text of the selection. --- * `position`: The position the list was displayed at. +-- * _`list_type`_: The *list_type* from [`buffer:user_list_show()`][]. +-- * _`text`_: The text of the selection. +-- * _`position`_: The position in the buffer the list was displayed at. -- @field VIEW_NEW (string) --- Called when a new view is created. --- This is emitted on startup and by [`view:split()`][]. +-- Called after creating a new view. +-- Emitted on startup and by [`view:split()`][]. -- @field VIEW_BEFORE_SWITCH (string) --- Called right before another view is switched to. --- This is emitted by [`gui.goto_view()`][]. +-- Called right before switching to another view. +-- Emitted by [`gui.goto_view()`][]. -- @field VIEW_AFTER_SWITCH (string) --- Called right after another view is switched to. --- This is emitted by [`gui.goto_view()`][]. +-- Called right after switching to another view. +-- Emitted by [`gui.goto_view()`][]. -- -- [`buffer:auto_c_cancel()`]: buffer.html#auto_c_cancel -- [`view:goto_buffer()`]: view.html#goto_buffer -- [`new_buffer()`]: _G.html#new_buffer -- [`buffer:delete()`]: buffer.html#delete +-- [dwell period]: buffer.html#mouse_dwell_time -- [`gui.menu()`]: gui.html#menu -- [`quit()`]: _G.html#quit -- [`reset()`]: _G.html#reset @@ -271,18 +263,19 @@ local M = {} module('events')]] --- --- A table of event names and a table of functions connected to them. +-- Map of event names with tables of the functions connected to them. -- @class table -- @name handlers M.handlers = {} --- --- Adds a handler function to an event. --- @param event The string event name. It is arbitrary and does not need to be --- defined previously. +-- Adds function *f* to the set of event handlers for *event* at position +-- *index*, returning a handler ID for *f*. *event* is an arbitrary event name +-- that does not need to have been previously defined. +-- @param event The string event name. -- @param f The Lua function to add. -- @param index Optional index to insert the handler into. --- @return Index of handler. +-- @return handler ID. -- @usage events.connect('my_event', function(msg) gui.print(msg) end) -- @see disconnect -- @name connect @@ -295,25 +288,28 @@ function M.connect(event, f, index) end --- --- Disconnects a handler function from an event. +-- Removes handler ID *id*, returned by `events.connect()`, from the set of +-- event handlers for *event*. -- @param event The string event name. --- @param index Index of the handler returned by `events.connect()`. +-- @param id ID of the handler returned by `events.connect()`. -- @see connect -- @name disconnect -function M.disconnect(event, index) +function M.disconnect(event, id) if not M.handlers[event] then return end - table.remove(M.handlers[event], index) + table.remove(M.handlers[event], id) end local error_emitted = false --- --- Calls all handlers for the given event in sequence. --- If `true` or `false` is explicitly returned by any handler, the event is not --- propagated any further; iteration ceases. This is useful if you want to stop --- the propagation of an event like a keypress. --- @param event The string event name. It is arbitrary and does not need to be --- defined previously. +-- Sequentially calls all handler functions for *event* with the given +-- arguments. +-- *event* is an arbitrary event name that does not need to have been previously +-- defined. If any handler explicitly returns `true` or `false`, the event is +-- not propagated any further, iteration ceases, and `emit()` returns that +-- value. This is useful for stopping the propagation of an event like a +-- keypress after it has been handled. +-- @param event The string event name. -- @param ... Arguments passed to the handler. -- @return `true` or `false` if any handler explicitly returned such; `nil` -- otherwise. diff --git a/core/file_io.lua b/core/file_io.lua index 3af44694..6d858d81 100644 --- a/core/file_io.lua +++ b/core/file_io.lua @@ -25,33 +25,33 @@ -- [`string.iconv()`]: string.html#iconv -- [`_CHARSET`]: _G.html#_CHARSET -- @field _G.events.FILE_OPENED (string) --- Called when a file is opened in a new buffer. --- This is emitted by [`open_file()`](#open_file) +-- Called when opening a file in a new buffer. +-- Emitted by [`open_file()`](#open_file). -- Arguments: -- --- * `filename`: The filename encoded in UTF-8. +-- * _`filename`_: The UTF-8-encoded filename. -- @field _G.events.FILE_BEFORE_SAVE (string) --- Called right before a file is saved to disk. --- This is emitted by [`buffer:save()`][] +-- Called right before saving a file to disk. +-- Emitted by [`buffer:save()`][]. -- Arguments: -- --- * `filename`: The filename encoded in UTF-8. +-- * _`filename`_: The UTF-8-encoded filename. -- -- [`buffer:save()`]: buffer.html#save -- @field _G.events.FILE_AFTER_SAVE (string) --- Called right after a file is saved to disk. --- This is emitted by [`buffer:save()`][] +-- Called right after saving a file to disk. +-- Emitted by [`buffer:save()`][]. -- Arguments: -- --- * `filename`: The filename encoded in UTF-8. +-- * _`filename`_: The UTF-8-encoded filename. -- -- [`buffer:save()`]: buffer.html#save -- @field _G.events.FILE_SAVED_AS (string) --- Called when a file is saved under a different filename. --- This is emitted by [`buffer:save_as()`][] +-- Called after saving a file under a different filename. +-- Emitted by [`buffer:save_as()`][]. -- Arguments: -- --- * `filename`: The filename encoded in UTF-8. +-- * _`filename`_: The UTF-8-encoded filename. -- -- [`buffer:save_as()`]: buffer.html#save_as module('io')]] @@ -64,8 +64,7 @@ events.FILE_AFTER_SAVE = 'file_after_save' events.FILE_SAVED_AS = 'file_saved_as' --- --- List of recently opened files. --- The most recent are towards the top. +-- List of recently opened files, the most recent being towards the top. -- @class table -- @name recent_files io.recent_files = {} @@ -109,19 +108,41 @@ end -- List of encodings to try to decode files as. -- You should add to this list if you get a "Conversion failed" error when -- trying to open a file whose encoding is not recognized. Valid encodings are --- [GNU iconv's encodings][]. +-- [GNU iconv'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 iconv's encodings]: http://www.gnu.org/software/libiconv/ +-- @usage io.try_encodings[#io.try_encodings + 1] = 'UTF-16' -- @class table -- @name try_encodings io.try_encodings = {'UTF-8', 'ASCII', 'ISO-8859-1', 'MacRoman'} --- --- Opens a list of files. +-- Opens *utf8_filenames*, a "\n" delimited string of UTF-8-encoded filenames, +-- or user-selected files. -- Emits a `FILE_OPENED` event. --- @param utf8_filenames A "\n" separated list of UTF-8-encoded filenames to --- open. If `nil`, the user is prompted with a fileselect dialog. --- @usage io.open_file(utf8_encoded_filename) +-- @param utf8_filenames Optional list of filenames to open. If `nil`, the user +-- is prompted with a fileselect dialog. -- @see _G.events -- @name open_file function io.open_file(utf8_filenames) @@ -276,8 +297,7 @@ local function save_as(buffer, utf8_filename) end --- --- Saves all dirty buffers to their respective files. --- @usage io.save_all() +-- Saves all unsaved buffers to their respective files. -- @see buffer.save -- @name save_all function io.save_all() @@ -308,10 +328,9 @@ local function close(buffer) end --- --- Closes all open buffers. --- If any buffer is dirty, the user is prompted to continue. No buffers are --- saved automatically. They must be saved manually. --- @usage io.close_all() +-- Closes all open buffers, prompting the user to continue with unsaved buffers, +-- and returning `true` if the user did not cancel. +-- No buffers are saved automatically. They must be saved manually. -- @return `true` if user did not cancel. -- @see buffer.close -- @name close_all diff --git a/core/gui.lua b/core/gui.lua index 635ea7d6..9d86f8f8 100644 --- a/core/gui.lua +++ b/core/gui.lua @@ -4,11 +4,13 @@ local gui = gui --[[ This comment is for LuaDoc. --- --- Utilities for Textadept's user interface. +-- Utilities for interacting with Textadept's user interface. -- @field title (string, Write-only) -- The title of the Textadept window. -- @field context_menu --- A [`gui.menu`](#menu) defining the editor's context menu. +-- The editor's context menu, a [`gui.menu()`](#menu). +-- This is a low-level field. You probably want to use the higher-level +-- `_M.textadept.menu.set_contextmenu()`. -- @field clipboard_text (string, Read-only) -- The text on the clipboard. -- @field statusbar_text (string, Write-only) @@ -65,15 +67,19 @@ function gui._print(buffer_type, ...) pcall(_print, buffer_type, ...) end function gui.print(...) gui._print(_L['[Message Buffer]'], ...) end --- --- Shortcut function for `gui.dialog('filteredlist', ...)` with "Ok" and --- "Cancel" buttons. +-- Convenience function for `gui.dialog('filteredlist', ...)` with "Ok" and +-- "Cancel" buttons that returns the text or index of the selection depending on +-- the boolean value of *int_return*. +-- *title* is the title of the dialog,*columns* is a list of column names, and +-- *items* is a list of items to show. -- @param title The title for the filtered list dialog. -- @param columns A column name or list of column names. -- @param items An item or list of items. --- @param int_return If `true`, returns the integer index of the selected item --- in the filtered list and is not compatible with the `'--select-multiple'` --- option. The default value is `false`, which returns the string item(s). --- @param ... Additional parameters to pass to `gui.dialog()`. +-- @param int_return Optional flag indicating whether to return the integer +-- index of the selected item in the filtered list or the string selected +-- item. A `true` value is not compatible with the `'--select-multiple'` +-- option. The default value is `false`. +-- @param ... Optional additional parameters to pass to `gui.dialog()`. -- @return Either a string or integer on success; `nil` otherwise. In strings, -- multiple items are separated by newlines. -- @usage gui.filteredlist('Title', 'Foo', {'Bar', 'Baz'}) @@ -99,8 +105,7 @@ function gui.filteredlist(title, columns, items, int_return, ...) end --- --- Displays a dialog with a list of buffers to switch to and switches to the --- selected one, if any. +-- Prompts the user to select a buffer to switch to. -- @name switch_buffer function gui.switch_buffer() local columns, items = {_L['Name'], _L['File']}, {} @@ -116,20 +121,22 @@ function gui.switch_buffer() end --- --- Goes to the buffer with the given filename. --- If the desired buffer is open in a view, goes to that view. Otherwise, opens --- the buffer in either the `preferred_view` if given, the first view that is --- not the current one, a split view if `split` is `true`, or the current view. +-- Goes to the buffer whose filename is *filename* in an existing view, +-- otherwise splitting the current view if *split* is `true` or going to the +-- next or *preferred_view* view instead of staying in the current one. +-- If *sloppy* is `true`, only the last part of *filename* is matched to a +-- buffer's `filename`. -- @param filename The filename of the buffer to go to. --- @param split If there is only one view, split it and open the buffer in the --- other view. --- @param preferred_view When multiple views exist and the desired buffer is not --- open in any of them, open it in this one. --- @param sloppy Flag indicating 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`. +-- @param split Optional flag indicating whether or not to open the buffer in a +-- split view if there is only one view. The default value is `false`. +-- @param preferred_view Optional view to open the desired buffer in if the +-- buffer is not visible in any other view. +-- @param sloppy Optional flag indicating 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`. -- @name goto_file function gui.goto_file(filename, split, preferred_view, sloppy) local patt = not sloppy and '^'..filename..'$' or filename..'$' @@ -152,15 +159,15 @@ end local theme_file = not NCURSES and 'theme' or 'theme_term' local THEME --- --- Sets the editor theme from the given name. --- Themes with the given name in the *`_USERHOME`/themes/* directory override --- themes of the same name in *`_HOME`/themes/*. If the name contains slashes --- ('\' on Windows, '/' otherwise), it is assumed to be an absolute path to a --- theme instead of a theme name. An error is thrown if the theme is not found. --- Any errors in the theme are printed to `io.stderr`. Running Textadept from a +-- Sets the editor theme name to *name* or the default platform theme. +-- Themes with *name* in the *`_USERHOME`/themes/* directory override themes of +-- the same name in *`_HOME`/themes/*. If *name* contains slashes ('\' on +-- Windows, '/' otherwise), it is assumed to be an absolute path to a theme +-- instead of a theme name. An error is thrown if the theme is not found. Any +-- errors in the theme are printed to `io.stderr`. Running Textadept from a -- terminal is the easiest way to see errors as they occur. --- @param name The name or absolute path of a theme. If `nil`, sets the default --- theme. +-- @param name Optional name or absolute path of a theme. If `nil`, sets the +-- default platform theme. -- @name set_theme function gui.set_theme(name) if not name then @@ -213,9 +220,8 @@ function gui.set_theme(name) end --- --- Prompts the user to select an editor theme from a filtered list dialog. --- Themes in the *`_HOME`/themes/* and *`_USERHOME`/themes/* directories are --- listed. +-- Prompts the user to select an editor theme from a list of themes found in the +-- *`_HOME`/themes/* and *`_USERHOME`/themes/* directories. -- @name select_theme function gui.select_theme() local themes, themes_found = {}, {} @@ -444,10 +450,10 @@ local size The functions below are Lua C functions. --- --- Displays a [gtdialog][1] of a specified type with the given string arguments. --- Each argument is like a string in Lua's `arg` table. Tables of strings are --- allowed as arguments and are expanded in place. This is useful for --- filtered list dialogs with many items. +-- Displays a *kind* [gtdialog][1] with the given string arguments to pass to +-- the dialog and returns a formatted string of the dialog's output. +-- Table arguments containing strings are allowed and expanded in place. This is +-- useful for filtered list dialogs with many items. -- For more information on gtdialog, see [http://foicica.com/gtdialog][1]. -- -- [1]: http://foicica.com/gtdialog @@ -459,7 +465,7 @@ The functions below are Lua C functions. local dialog --- --- Gets the current split view structure. +-- Returns the 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 @@ -471,11 +477,13 @@ local dialog local get_split_table --- --- Goes to the specified view. +-- Goes to view number *n*. +-- If *relative* is `true`, *n* is an index relative to the index of the current +-- view in `_G._VIEWS` instead of an absolute index. -- Emits `VIEW_BEFORE_SWITCH` and `VIEW_AFTER_SWITCH` events. -- @param n A relative or absolute view index in `_G._VIEWS`. --- @param relative Flag indicating if n is a relative index or not. The default --- value is `false`. +-- @param relative Optional flag indicating whether *n* is a relative or +-- absolute index. The default value is `false` for an absolute index. -- @see _G._G._VIEWS -- @see events.VIEW_BEFORE_SWITCH -- @see events.VIEW_AFTER_SWITCH @@ -484,10 +492,11 @@ local get_split_table local goto_view --- --- Creates a menu, returning the userdata. --- This is a low-level function. You probably want to use the higher-level --- `_M.textadept.menu.set_menubar()` or `_M.textadept.menu.set_contextmenu()` --- functions. Emits a `MENU_CLICKED` event when a menu item is selected. +-- Low-level function for creating a menu from table *menu_table* and returning +-- the userdata. +-- You probably want to use the higher-level `_M.textadept.menu.set_menubar()` +-- or `_M.textadept.menu.set_contextmenu()` functions. Emits a `MENU_CLICKED` +-- event when a menu item is selected. -- @param 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 diff --git a/core/iface.lua b/core/iface.lua index d71f7db7..decc97b0 100644 --- a/core/iface.lua +++ b/core/iface.lua @@ -10,22 +10,20 @@ local M = {} module('_SCINTILLA')]] --- --- Scintilla constants. --- Each key is a Scintilla constant with its associated numeric value. +-- Map of Scintilla constant names to their numeric values. -- @class table -- @name constants M.constants = {ANNOTATION_BOXED=2,ANNOTATION_HIDDEN=0,ANNOTATION_STANDARD=1,CARETSTYLE_BLOCK=2,CARETSTYLE_INVISIBLE=0,CARETSTYLE_LINE=1,CARET_EVEN=0x08,CARET_JUMPS=0x10,CARET_SLOP=0x01,CARET_STRICT=0x04,EDGE_BACKGROUND=2,EDGE_LINE=1,EDGE_NONE=0,INDIC0_MASK=0x20,INDIC1_MASK=0x40,INDIC2_MASK=0x80,INDICS_MASK=0xE0,INDIC_BOX=6,INDIC_CONTAINER=8,INDIC_DASH=9,INDIC_DIAGONAL=3,INDIC_DOTBOX=12,INDIC_DOTS=10,INDIC_HIDDEN=5,INDIC_MAX=31,INDIC_PLAIN=0,INDIC_ROUNDBOX=7,INDIC_SQUIGGLE=1,INDIC_SQUIGGLELOW=11,INDIC_SQUIGGLEPIXMAP=13,INDIC_STRAIGHTBOX=8,INDIC_STRIKE=4,INDIC_TT=2,INVALID_POSITION=-1,KEYWORDSET_MAX=8,MARKER_MAX=31,SCEN_CHANGE=768,SCEN_KILLFOCUS=256,SCEN_SETFOCUS=512,SCFIND_MATCHCASE=4,SCFIND_POSIX=0x00400000,SCFIND_REGEXP=0x00200000,SCFIND_WHOLEWORD=2,SCFIND_WORDSTART=0x00100000,SCI_ANNOTATIONGETLINES=2546,SCI_ANNOTATIONGETSTYLE=2543,SCI_ANNOTATIONGETSTYLEOFFSET=2551,SCI_ANNOTATIONGETSTYLES=2545,SCI_ANNOTATIONGETTEXT=2541,SCI_ANNOTATIONGETVISIBLE=2549,SCI_ANNOTATIONSETSTYLE=2542,SCI_ANNOTATIONSETSTYLEOFFSET=2550,SCI_ANNOTATIONSETSTYLES=2544,SCI_ANNOTATIONSETTEXT=2540,SCI_ANNOTATIONSETVISIBLE=2548,SCI_AUTOCGETAUTOHIDE=2119,SCI_AUTOCGETCANCELATSTART=2111,SCI_AUTOCGETCASEINSENSITIVEBEHAVIOUR=2635,SCI_AUTOCGETCHOOSESINGLE=2114,SCI_AUTOCGETCURRENT=2445,SCI_AUTOCGETCURRENTTEXT=2610,SCI_AUTOCGETDROPRESTOFWORD=2271,SCI_AUTOCGETIGNORECASE=2116,SCI_AUTOCGETMAXHEIGHT=2211,SCI_AUTOCGETMAXWIDTH=2209,SCI_AUTOCGETSEPARATOR=2107,SCI_AUTOCGETTYPESEPARATOR=2285,SCI_AUTOCSETAUTOHIDE=2118,SCI_AUTOCSETCANCELATSTART=2110,SCI_AUTOCSETCASEINSENSITIVEBEHAVIOUR=2634,SCI_AUTOCSETCHOOSESINGLE=2113,SCI_AUTOCSETDROPRESTOFWORD=2270,SCI_AUTOCSETFILLUPS=2112,SCI_AUTOCSETIGNORECASE=2115,SCI_AUTOCSETMAXHEIGHT=2210,SCI_AUTOCSETMAXWIDTH=2208,SCI_AUTOCSETSEPARATOR=2106,SCI_AUTOCSETTYPESEPARATOR=2286,SCI_CALLTIPSETBACK=2205,SCI_CALLTIPSETFORE=2206,SCI_CALLTIPSETFOREHLT=2207,SCI_CALLTIPSETPOSITION=2213,SCI_CALLTIPUSESTYLE=2212,SCI_GETADDITIONALCARETFORE=2605,SCI_GETADDITIONALCARETSBLINK=2568,SCI_GETADDITIONALCARETSVISIBLE=2609,SCI_GETADDITIONALSELALPHA=2603,SCI_GETADDITIONALSELECTIONTYPING=2566,SCI_GETALLLINESVISIBLE=2236,SCI_GETANCHOR=2009,SCI_GETBACKSPACEUNINDENTS=2263,SCI_GETBUFFEREDDRAW=2034,SCI_GETCARETFORE=2138,SCI_GETCARETLINEBACK=2097,SCI_GETCARETLINEBACKALPHA=2471,SCI_GETCARETLINEVISIBLE=2095,SCI_GETCARETPERIOD=2075,SCI_GETCARETSTICKY=2457,SCI_GETCARETSTYLE=2513,SCI_GETCARETWIDTH=2189,SCI_GETCHARACTERPOINTER=2520,SCI_GETCHARAT=2007,SCI_GETCODEPAGE=2137,SCI_GETCOLUMN=2129,SCI_GETCONTROLCHARSYMBOL=2389,SCI_GETCURRENTPOS=2008,SCI_GETCURSOR=2387,SCI_GETDIRECTFUNCTION=2184,SCI_GETDIRECTPOINTER=2185,SCI_GETDOCPOINTER=2357,SCI_GETEDGECOLOUR=2364,SCI_GETEDGECOLUMN=2360,SCI_GETEDGEMODE=2362,SCI_GETENDATLASTLINE=2278,SCI_GETENDSTYLED=2028,SCI_GETEOLMODE=2030,SCI_GETEXTRAASCENT=2526,SCI_GETEXTRADESCENT=2528,SCI_GETFIRSTVISIBLELINE=2152,SCI_GETFOCUS=2381,SCI_GETFOLDEXPANDED=2230,SCI_GETFOLDLEVEL=2223,SCI_GETFOLDPARENT=2225,SCI_GETFONTQUALITY=2612,SCI_GETGAPPOSITION=2644,SCI_GETHIGHLIGHTGUIDE=2135,SCI_GETHOTSPOTACTIVEUNDERLINE=2496,SCI_GETHOTSPOTSINGLELINE=2497,SCI_GETHSCROLLBAR=2131,SCI_GETIDENTIFIER=2623,SCI_GETINDENT=2123,SCI_GETINDENTATIONGUIDES=2133,SCI_GETINDICATORCURRENT=2501,SCI_GETINDICATORVALUE=2503,SCI_GETKEYSUNICODE=2522,SCI_GETLAYOUTCACHE=2273,SCI_GETLENGTH=2006,SCI_GETLEXER=4002,SCI_GETLEXERLANGUAGE=4012,SCI_GETLINECOUNT=2154,SCI_GETLINEENDPOSITION=2136,SCI_GETLINEINDENTATION=2127,SCI_GETLINEINDENTPOSITION=2128,SCI_GETLINESTATE=2093,SCI_GETLINEVISIBLE=2228,SCI_GETMAINSELECTION=2575,SCI_GETMARGINCURSORN=2249,SCI_GETMARGINLEFT=2156,SCI_GETMARGINMASKN=2245,SCI_GETMARGINOPTIONS=2557,SCI_GETMARGINRIGHT=2158,SCI_GETMARGINSENSITIVEN=2247,SCI_GETMARGINTYPEN=2241,SCI_GETMARGINWIDTHN=2243,SCI_GETMAXLINESTATE=2094,SCI_GETMODEVENTMASK=2378,SCI_GETMODIFY=2159,SCI_GETMOUSEDOWNCAPTURES=2385,SCI_GETMOUSEDWELLTIME=2265,SCI_GETMULTIPASTE=2615,SCI_GETMULTIPLESELECTION=2564,SCI_GETOVERTYPE=2187,SCI_GETPASTECONVERTENDINGS=2468,SCI_GETPOSITIONCACHE=2515,SCI_GETPRINTCOLOURMODE=2149,SCI_GETPRINTMAGNIFICATION=2147,SCI_GETPRINTWRAPMODE=2407,SCI_GETPROPERTY=4008,SCI_GETPROPERTYEXPANDED=4009,SCI_GETPROPERTYINT=4010,SCI_GETPUNCTUATIONCHARS=2649,SCI_GETREADONLY=2140,SCI_GETRECTANGULARSELECTIONANCHOR=2591,SCI_GETRECTANGULARSELECTIONANCHORVIRTUALSPACE=2595,SCI_GETRECTANGULARSELECTIONCARET=2589,SCI_GETRECTANGULARSELECTIONCARETVIRTUALSPACE=2593,SCI_GETRECTANGULARSELECTIONMODIFIER=2599,SCI_GETSCROLLWIDTH=2275,SCI_GETSCROLLWIDTHTRACKING=2517,SCI_GETSEARCHFLAGS=2199,SCI_GETSELALPHA=2477,SCI_GETSELECTIONEMPTY=2650,SCI_GETSELECTIONEND=2145,SCI_GETSELECTIONMODE=2423,SCI_GETSELECTIONNANCHOR=2579,SCI_GETSELECTIONNANCHORVIRTUALSPACE=2583,SCI_GETSELECTIONNCARET=2577,SCI_GETSELECTIONNCARETVIRTUALSPACE=2581,SCI_GETSELECTIONNEND=2587,SCI_GETSELECTIONNSTART=2585,SCI_GETSELECTIONS=2570,SCI_GETSELECTIONSTART=2143,SCI_GETSELEOLFILLED=2479,SCI_GETSTATUS=2383,SCI_GETSTYLEAT=2010,SCI_GETSTYLEBITS=2091,SCI_GETSTYLEBITSNEEDED=4011,SCI_GETTABINDENTS=2261,SCI_GETTABWIDTH=2121,SCI_GETTAG=2616,SCI_GETTARGETEND=2193,SCI_GETTARGETSTART=2191,SCI_GETTECHNOLOGY=2631,SCI_GETTEXTLENGTH=2183,SCI_GETTWOPHASEDRAW=2283,SCI_GETUNDOCOLLECTION=2019,SCI_GETUSETABS=2125,SCI_GETVIEWEOL=2355,SCI_GETVIEWWS=2020,SCI_GETVIRTUALSPACEOPTIONS=2597,SCI_GETVSCROLLBAR=2281,SCI_GETWHITESPACECHARS=2647,SCI_GETWHITESPACESIZE=2087,SCI_GETWORDCHARS=2646,SCI_GETWRAPINDENTMODE=2473,SCI_GETWRAPMODE=2269,SCI_GETWRAPSTARTINDENT=2465,SCI_GETWRAPVISUALFLAGS=2461,SCI_GETWRAPVISUALFLAGSLOCATION=2463,SCI_GETXOFFSET=2398,SCI_GETZOOM=2374,SCI_INDICGETALPHA=2524,SCI_INDICGETFORE=2083,SCI_INDICGETOUTLINEALPHA=2559,SCI_INDICGETSTYLE=2081,SCI_INDICGETUNDER=2511,SCI_INDICSETALPHA=2523,SCI_INDICSETFORE=2082,SCI_INDICSETOUTLINEALPHA=2558,SCI_INDICSETSTYLE=2080,SCI_INDICSETUNDER=2510,SCI_LEXER_START=4000,SCI_LINESONSCREEN=2370,SCI_MARGINGETSTYLE=2533,SCI_MARGINGETSTYLEOFFSET=2538,SCI_MARGINGETSTYLES=2535,SCI_MARGINGETTEXT=2531,SCI_MARGINSETSTYLE=2532,SCI_MARGINSETSTYLEOFFSET=2537,SCI_MARGINSETSTYLES=2534,SCI_MARGINSETTEXT=2530,SCI_MARKERSETALPHA=2476,SCI_MARKERSETBACK=2042,SCI_MARKERSETBACKSELECTED=2292,SCI_MARKERSETFORE=2041,SCI_OPTIONAL_START=3000,SCI_RGBAIMAGESETHEIGHT=2625,SCI_RGBAIMAGESETSCALE=2651,SCI_RGBAIMAGESETWIDTH=2624,SCI_SELECTIONISRECTANGLE=2372,SCI_SETADDITIONALCARETFORE=2604,SCI_SETADDITIONALCARETSBLINK=2567,SCI_SETADDITIONALCARETSVISIBLE=2608,SCI_SETADDITIONALSELALPHA=2602,SCI_SETADDITIONALSELBACK=2601,SCI_SETADDITIONALSELECTIONTYPING=2565,SCI_SETADDITIONALSELFORE=2600,SCI_SETANCHOR=2026,SCI_SETBACKSPACEUNINDENTS=2262,SCI_SETBUFFEREDDRAW=2035,SCI_SETCARETFORE=2069,SCI_SETCARETLINEBACK=2098,SCI_SETCARETLINEBACKALPHA=2470,SCI_SETCARETLINEVISIBLE=2096,SCI_SETCARETPERIOD=2076,SCI_SETCARETSTICKY=2458,SCI_SETCARETSTYLE=2512,SCI_SETCARETWIDTH=2188,SCI_SETCODEPAGE=2037,SCI_SETCONTROLCHARSYMBOL=2388,SCI_SETCURRENTPOS=2141,SCI_SETCURSOR=2386,SCI_SETDOCPOINTER=2358,SCI_SETEDGECOLOUR=2365,SCI_SETEDGECOLUMN=2361,SCI_SETEDGEMODE=2363,SCI_SETENDATLASTLINE=2277,SCI_SETEOLMODE=2031,SCI_SETEXTRAASCENT=2525,SCI_SETEXTRADESCENT=2527,SCI_SETFIRSTVISIBLELINE=2613,SCI_SETFOCUS=2380,SCI_SETFOLDEXPANDED=2229,SCI_SETFOLDFLAGS=2233,SCI_SETFOLDLEVEL=2222,SCI_SETFONTQUALITY=2611,SCI_SETHIGHLIGHTGUIDE=2134,SCI_SETHOTSPOTACTIVEUNDERLINE=2412,SCI_SETHOTSPOTSINGLELINE=2421,SCI_SETHSCROLLBAR=2130,SCI_SETIDENTIFIER=2622,SCI_SETINDENT=2122,SCI_SETINDENTATIONGUIDES=2132,SCI_SETINDICATORCURRENT=2500,SCI_SETINDICATORVALUE=2502,SCI_SETKEYSUNICODE=2521,SCI_SETKEYWORDS=4005,SCI_SETLAYOUTCACHE=2272,SCI_SETLEXER=4001,SCI_SETLEXERLANGUAGE=4006,SCI_SETLINEINDENTATION=2126,SCI_SETLINESTATE=2092,SCI_SETMAINSELECTION=2574,SCI_SETMARGINCURSORN=2248,SCI_SETMARGINLEFT=2155,SCI_SETMARGINMASKN=2244,SCI_SETMARGINOPTIONS=2539,SCI_SETMARGINRIGHT=2157,SCI_SETMARGINSENSITIVEN=2246,SCI_SETMARGINTYPEN=2240,SCI_SETMARGINWIDTHN=2242,SCI_SETMODEVENTMASK=2359,SCI_SETMOUSEDOWNCAPTURES=2384,SCI_SETMOUSEDWELLTIME=2264,SCI_SETMULTIPASTE=2614,SCI_SETMULTIPLESELECTION=2563,SCI_SETOVERTYPE=2186,SCI_SETPASTECONVERTENDINGS=2467,SCI_SETPOSITIONCACHE=2514,SCI_SETPRINTCOLOURMODE=2148,SCI_SETPRINTMAGNIFICATION=2146,SCI_SETPRINTWRAPMODE=2406,SCI_SETPROPERTY=4004,SCI_SETPUNCTUATIONCHARS=2648,SCI_SETREADONLY=2171,SCI_SETRECTANGULARSELECTIONANCHOR=2590,SCI_SETRECTANGULARSELECTIONANCHORVIRTUALSPACE=2594,SCI_SETRECTANGULARSELECTIONCARET=2588,SCI_SETRECTANGULARSELECTIONCARETVIRTUALSPACE=2592,SCI_SETRECTANGULARSELECTIONMODIFIER=2598,SCI_SETSCROLLWIDTH=2274,SCI_SETSCROLLWIDTHTRACKING=2516,SCI_SETSEARCHFLAGS=2198,SCI_SETSELALPHA=2478,SCI_SETSELECTIONEND=2144,SCI_SETSELECTIONMODE=2422,SCI_SETSELECTIONNANCHOR=2578,SCI_SETSELECTIONNANCHORVIRTUALSPACE=2582,SCI_SETSELECTIONNCARET=2576,SCI_SETSELECTIONNCARETVIRTUALSPACE=2580,SCI_SETSELECTIONNEND=2586,SCI_SETSELECTIONNSTART=2584,SCI_SETSELECTIONSTART=2142,SCI_SETSELEOLFILLED=2480,SCI_SETSTATUS=2382,SCI_SETSTYLEBITS=2090,SCI_SETTABINDENTS=2260,SCI_SETTABWIDTH=2036,SCI_SETTARGETEND=2192,SCI_SETTARGETSTART=2190,SCI_SETTECHNOLOGY=2630,SCI_SETTWOPHASEDRAW=2284,SCI_SETUNDOCOLLECTION=2012,SCI_SETUSETABS=2124,SCI_SETVIEWEOL=2356,SCI_SETVIEWWS=2021,SCI_SETVIRTUALSPACEOPTIONS=2596,SCI_SETVSCROLLBAR=2280,SCI_SETWHITESPACECHARS=2443,SCI_SETWHITESPACESIZE=2086,SCI_SETWORDCHARS=2077,SCI_SETWRAPINDENTMODE=2472,SCI_SETWRAPMODE=2268,SCI_SETWRAPSTARTINDENT=2464,SCI_SETWRAPVISUALFLAGS=2460,SCI_SETWRAPVISUALFLAGSLOCATION=2462,SCI_SETXOFFSET=2397,SCI_SETZOOM=2373,SCI_START=2000,SCI_STYLEGETBACK=2482,SCI_STYLEGETBOLD=2483,SCI_STYLEGETCASE=2489,SCI_STYLEGETCHANGEABLE=2492,SCI_STYLEGETCHARACTERSET=2490,SCI_STYLEGETEOLFILLED=2487,SCI_STYLEGETFONT=2486,SCI_STYLEGETFORE=2481,SCI_STYLEGETHOTSPOT=2493,SCI_STYLEGETITALIC=2484,SCI_STYLEGETSIZE=2485,SCI_STYLEGETSIZEFRACTIONAL=2062,SCI_STYLEGETUNDERLINE=2488,SCI_STYLEGETVISIBLE=2491,SCI_STYLEGETWEIGHT=2064,SCI_STYLESETBACK=2052,SCI_STYLESETBOLD=2053,SCI_STYLESETCASE=2060,SCI_STYLESETCHANGEABLE=2099,SCI_STYLESETCHARACTERSET=2066,SCI_STYLESETEOLFILLED=2057,SCI_STYLESETFONT=2056,SCI_STYLESETFORE=2051,SCI_STYLESETHOTSPOT=2409,SCI_STYLESETITALIC=2054,SCI_STYLESETSIZE=2055,SCI_STYLESETSIZEFRACTIONAL=2061,SCI_STYLESETUNDERLINE=2059,SCI_STYLESETVISIBLE=2074,SCI_STYLESETWEIGHT=2063,SCK_ADD=310,SCK_BACK=8,SCK_DELETE=308,SCK_DIVIDE=312,SCK_DOWN=300,SCK_END=305,SCK_ESCAPE=7,SCK_HOME=304,SCK_INSERT=309,SCK_LEFT=302,SCK_MENU=315,SCK_NEXT=307,SCK_PRIOR=306,SCK_RETURN=13,SCK_RIGHT=303,SCK_RWIN=314,SCK_SUBTRACT=311,SCK_TAB=9,SCK_UP=301,SCK_WIN=313,SCMOD_ALT=4,SCMOD_CTRL=2,SCMOD_META=16,SCMOD_NORM=0,SCMOD_SHIFT=1,SCMOD_SUPER=8,SCVS_NONE=0,SCVS_RECTANGULARSELECTION=1,SCVS_USERACCESSIBLE=2,SCWS_INVISIBLE=0,SCWS_VISIBLEAFTERINDENT=2,SCWS_VISIBLEALWAYS=1,SC_ALPHA_NOALPHA=256,SC_ALPHA_OPAQUE=255,SC_ALPHA_TRANSPARENT=0,SC_CACHE_CARET=1,SC_CACHE_DOCUMENT=3,SC_CACHE_NONE=0,SC_CACHE_PAGE=2,SC_CARETSTICKY_OFF=0,SC_CARETSTICKY_ON=1,SC_CARETSTICKY_WHITESPACE=2,SC_CASEINSENSITIVEBEHAVIOUR_IGNORECASE=1,SC_CASEINSENSITIVEBEHAVIOUR_RESPECTCASE=0,SC_CASE_LOWER=2,SC_CASE_MIXED=0,SC_CASE_UPPER=1,SC_CHARSET_8859_15=1000,SC_CHARSET_ANSI=0,SC_CHARSET_ARABIC=178,SC_CHARSET_BALTIC=186,SC_CHARSET_CHINESEBIG5=136,SC_CHARSET_CYRILLIC=1251,SC_CHARSET_DEFAULT=1,SC_CHARSET_EASTEUROPE=238,SC_CHARSET_GB2312=134,SC_CHARSET_GREEK=161,SC_CHARSET_HANGUL=129,SC_CHARSET_HEBREW=177,SC_CHARSET_JOHAB=130,SC_CHARSET_MAC=77,SC_CHARSET_OEM=255,SC_CHARSET_RUSSIAN=204,SC_CHARSET_SHIFTJIS=128,SC_CHARSET_SYMBOL=2,SC_CHARSET_THAI=222,SC_CHARSET_TURKISH=162,SC_CHARSET_VIETNAMESE=163,SC_CP_UTF8=65001,SC_CURSORARROW=2,SC_CURSORNORMAL=-1,SC_CURSORREVERSEARROW=7,SC_CURSORWAIT=4,SC_EFF_QUALITY_ANTIALIASED=2,SC_EFF_QUALITY_DEFAULT=0,SC_EFF_QUALITY_LCD_OPTIMIZED=3,SC_EFF_QUALITY_MASK=0xF,SC_EFF_QUALITY_NON_ANTIALIASED=1,SC_EOL_CR=1,SC_EOL_CRLF=0,SC_EOL_LF=2,SC_FOLDFLAG_LEVELNUMBERS=0x0040,SC_FOLDFLAG_LINEAFTER_CONTRACTED=0x0010,SC_FOLDFLAG_LINEAFTER_EXPANDED=0x0008,SC_FOLDFLAG_LINEBEFORE_CONTRACTED=0x0004,SC_FOLDFLAG_LINEBEFORE_EXPANDED=0x0002,SC_FOLDLEVELBASE=0x400,SC_FOLDLEVELHEADERFLAG=0x2000,SC_FOLDLEVELNUMBERMASK=0x0FFF,SC_FOLDLEVELWHITEFLAG=0x1000,SC_FONT_SIZE_MULTIPLIER=100,SC_IV_LOOKBOTH=3,SC_IV_LOOKFORWARD=2,SC_IV_NONE=0,SC_IV_REAL=1,SC_LASTSTEPINUNDOREDO=0x100,SC_MARGINOPTION_NONE=0,SC_MARGINOPTION_SUBLINESELECT=1,SC_MARGIN_BACK=2,SC_MARGIN_FORE=3,SC_MARGIN_NUMBER=1,SC_MARGIN_RTEXT=5,SC_MARGIN_SYMBOL=0,SC_MARGIN_TEXT=4,SC_MARKNUM_FOLDER=30,SC_MARKNUM_FOLDEREND=25,SC_MARKNUM_FOLDERMIDTAIL=27,SC_MARKNUM_FOLDEROPEN=31,SC_MARKNUM_FOLDEROPENMID=26,SC_MARKNUM_FOLDERSUB=29,SC_MARKNUM_FOLDERTAIL=28,SC_MARK_ARROW=2,SC_MARK_ARROWDOWN=6,SC_MARK_ARROWS=24,SC_MARK_AVAILABLE=28,SC_MARK_BACKGROUND=22,SC_MARK_BOXMINUS=14,SC_MARK_BOXMINUSCONNECTED=15,SC_MARK_BOXPLUS=12,SC_MARK_BOXPLUSCONNECTED=13,SC_MARK_CHARACTER=10000,SC_MARK_CIRCLE=0,SC_MARK_CIRCLEMINUS=20,SC_MARK_CIRCLEMINUSCONNECTED=21,SC_MARK_CIRCLEPLUS=18,SC_MARK_CIRCLEPLUSCONNECTED=19,SC_MARK_DOTDOTDOT=23,SC_MARK_EMPTY=5,SC_MARK_FULLRECT=26,SC_MARK_LCORNER=10,SC_MARK_LCORNERCURVE=16,SC_MARK_LEFTRECT=27,SC_MARK_MINUS=7,SC_MARK_PIXMAP=25,SC_MARK_PLUS=8,SC_MARK_RGBAIMAGE=30,SC_MARK_ROUNDRECT=1,SC_MARK_SHORTARROW=4,SC_MARK_SMALLRECT=3,SC_MARK_TCORNER=11,SC_MARK_TCORNERCURVE=17,SC_MARK_UNDERLINE=29,SC_MARK_VLINE=9,SC_MASK_FOLDERS=-33554432,SC_MODEVENTMASKALL=0xFFFFF,SC_MOD_BEFOREDELETE=0x800,SC_MOD_BEFOREINSERT=0x400,SC_MOD_CHANGEANNOTATION=0x20000,SC_MOD_CHANGEFOLD=0x8,SC_MOD_CHANGEINDICATOR=0x4000,SC_MOD_CHANGELINESTATE=0x8000,SC_MOD_CHANGEMARGIN=0x10000,SC_MOD_CHANGEMARKER=0x200,SC_MOD_CHANGESTYLE=0x4,SC_MOD_CONTAINER=0x40000,SC_MOD_DELETETEXT=0x2,SC_MOD_INSERTTEXT=0x1,SC_MOD_LEXERSTATE=0x80000,SC_MULTILINEUNDOREDO=0x1000,SC_MULTIPASTE_EACH=1,SC_MULTIPASTE_ONCE=0,SC_MULTISTEPUNDOREDO=0x80,SC_PERFORMED_REDO=0x40,SC_PERFORMED_UNDO=0x20,SC_PERFORMED_USER=0x10,SC_PRINT_BLACKONWHITE=2,SC_PRINT_COLOURONWHITE=3,SC_PRINT_COLOURONWHITEDEFAULTBG=4,SC_PRINT_INVERTLIGHT=1,SC_PRINT_NORMAL=0,SC_SEL_LINES=2,SC_SEL_RECTANGLE=1,SC_SEL_STREAM=0,SC_SEL_THIN=3,SC_STARTACTION=0x2000,SC_STATUS_BADALLOC=2,SC_STATUS_FAILURE=1,SC_STATUS_OK=0,SC_TECHNOLOGY_DEFAULT=0,SC_TECHNOLOGY_DIRECTWRITE=1,SC_TIME_FOREVER=10000000,SC_TYPE_BOOLEAN=0,SC_TYPE_INTEGER=1,SC_TYPE_STRING=2,SC_UPDATE_CONTENT=0x1,SC_UPDATE_H_SCROLL=0x8,SC_UPDATE_SELECTION=0x2,SC_UPDATE_V_SCROLL=0x4,SC_WEIGHT_BOLD=700,SC_WEIGHT_NORMAL=400,SC_WEIGHT_SEMIBOLD=600,SC_WRAPINDENT_FIXED=0,SC_WRAPINDENT_INDENT=2,SC_WRAPINDENT_SAME=1,SC_WRAPVISUALFLAGLOC_DEFAULT=0x0000,SC_WRAPVISUALFLAGLOC_END_BY_TEXT=0x0001,SC_WRAPVISUALFLAGLOC_START_BY_TEXT=0x0002,SC_WRAPVISUALFLAG_END=0x0001,SC_WRAPVISUALFLAG_MARGIN=0x0004,SC_WRAPVISUALFLAG_NONE=0x0000,SC_WRAPVISUALFLAG_START=0x0002,SC_WRAP_CHAR=2,SC_WRAP_NONE=0,SC_WRAP_WORD=1,STYLE_BRACEBAD=35,STYLE_BRACELIGHT=34,STYLE_CALLTIP=38,STYLE_CONTROLCHAR=36,STYLE_DEFAULT=32,STYLE_INDENTGUIDE=37,STYLE_LASTPREDEFINED=39,STYLE_LINENUMBER=33,STYLE_MAX=255,UNDO_MAY_COALESCE=1,VISIBLE_SLOP=0x01,VISIBLE_STRICT=0x04,SCN_DOUBLECLICK=2006,SCN_AUTOCCHARDELETED=2027,SCN_SAVEPOINTLEFT=2003,SCN_PAINTED=2013,SCN_HOTSPOTRELEASECLICK=2028,SCN_UPDATEUI=2007,SCN_STYLENEEDED=2000,SCN_AUTOCCANCELLED=2026,SCN_MACRORECORD=2009,SCN_INDICATORRELEASE=2024,SCN_MODIFIED=2008,SCN_SAVEPOINTREACHED=2002,SCN_HOTSPOTDOUBLECLICK=2020,SCN_NEEDSHOWN=2011,SCN_CALLTIPCLICK=2021,SCN_AUTOCSELECTION=2022,SCN_DWELLEND=2017,SCN_ZOOM=2018,SCN_CHARADDED=2001,SCN_HOTSPOTCLICK=2019,SCN_KEY=2005,SCN_DWELLSTART=2016,SCN_MARGINCLICK=2010,SCN_USERLISTSELECTION=2014,SCN_URIDROPPED=2015,SCN_INDICATORCLICK=2023,SCN_MODIFYATTEMPTRO=2004,SCLEX_CONTAINER=0,SCLEX_AUTOMATIC=1000,SCLEX_LPEG=999,SCLEX_NULL=1} --- --- Scintilla functions. --- Each key is a Scintilla function name with a table value containing its ID, --- return type, wParam type, and lParam type. Types are as follows: +-- Map of Scintilla function names to tables containing their IDs, return types, +-- wParam types, and lParam types. Types are as follows: -- -- + `0`: Void. -- + `1`: Integer. -- + `2`: Length of the given lParam string. -- + `3`: Integer position. --- + `4`: Colour in "0xBBGGRR" format. +-- + `4`: Color, in "0xBBGGRR" format. -- + `5`: Boolean `true` or `false`. -- + `6`: Bitmask of Scintilla key modifiers and a key value. -- + `7`: String parameter. @@ -35,11 +33,10 @@ M.constants = {ANNOTATION_BOXED=2,ANNOTATION_HIDDEN=0,ANNOTATION_STANDARD=1,CARE M.functions = {add_ref_document={2376,0,0,1},add_selection={2573,1,1,1},add_styled_text={2002,0,2,9},add_text={2001,0,2,7},add_undo_action={2560,0,1,1},allocate={2446,0,1,0},annotation_clear_all={2547,0,0,0},append_text={2282,0,2,7},assign_cmd_key={2070,0,6,1},auto_c_active={2102,5,0,0},auto_c_cancel={2101,0,0,0},auto_c_complete={2104,0,0,0},auto_c_pos_start={2103,3,0,0},auto_c_select={2108,0,0,7},auto_c_show={2100,0,1,7},auto_c_stops={2105,0,0,7},back_tab={2328,0,0,0},begin_undo_action={2078,0,0,0},brace_bad_light={2352,0,3,0},brace_bad_light_indicator={2499,0,5,1},brace_highlight={2351,0,3,3},brace_highlight_indicator={2498,0,5,1},brace_match={2353,3,3,0},call_tip_active={2202,5,0,0},call_tip_cancel={2201,0,0,0},call_tip_pos_start={2203,3,0,0},call_tip_set_hlt={2204,0,1,1},call_tip_show={2200,0,3,7},can_paste={2173,5,0,0},can_redo={2016,5,0,0},can_undo={2174,5,0,0},cancel={2325,0,0,0},change_lexer_state={2617,1,3,3},char_left={2304,0,0,0},char_left_extend={2305,0,0,0},char_left_rect_extend={2428,0,0,0},char_position_from_point={2561,3,1,1},char_position_from_point_close={2562,3,1,1},char_right={2306,0,0,0},char_right_extend={2307,0,0,0},char_right_rect_extend={2429,0,0,0},choose_caret_x={2399,0,0,0},clear={2180,0,0,0},clear_all={2004,0,0,0},clear_all_cmd_keys={2072,0,0,0},clear_cmd_key={2071,0,6,0},clear_document_style={2005,0,0,0},clear_registered_images={2408,0,0,0},clear_selections={2571,0,0,0},colourise={4003,0,3,3},contracted_fold_next={2618,1,1,0},convert_eo_ls={2029,0,1,0},copy={2178,0,0,0},copy_allow_line={2519,0,0,0},copy_range={2419,0,3,3},copy_text={2420,0,2,7},count_characters={2633,1,1,1},create_document={2375,1,0,0},create_loader={2632,1,1,0},cut={2177,0,0,0},del_line_left={2395,0,0,0},del_line_right={2396,0,0,0},del_word_left={2335,0,0,0},del_word_right={2336,0,0,0},del_word_right_end={2518,0,0,0},delete_back={2326,0,0,0},delete_back_not_line={2344,0,0,0},delete_range={2645,0,3,1},describe_key_word_sets={4017,1,0,8},describe_property={4016,1,7,8},doc_line_from_visible={2221,1,1,0},document_end={2318,0,0,0},document_end_extend={2319,0,0,0},document_start={2316,0,0,0},document_start_extend={2317,0,0,0},edit_toggle_overtype={2324,0,0,0},empty_undo_buffer={2175,0,0,0},encoded_from_utf8={2449,1,7,8},end_undo_action={2079,0,0,0},ensure_visible={2232,0,1,0},ensure_visible_enforce_policy={2234,0,1,0},find_column={2456,1,1,1},find_indicator_flash={2641,0,3,3},find_indicator_hide={2642,0,0,0},find_indicator_show={2640,0,3,3},find_text={2150,3,1,11},form_feed={2330,0,0,0},format_range={2151,3,5,12},get_cur_line={2027,1,2,8},get_hotspot_active_back={2495,4,0,0},get_hotspot_active_fore={2494,4,0,0},get_last_child={2224,1,1,1},get_line={2153,1,1,8},get_line_sel_end_position={2425,3,1,0},get_line_sel_start_position={2424,3,1,0},get_range_pointer={2643,1,1,1},get_sel_text={2161,1,0,8},get_styled_text={2015,1,0,10},get_text={2182,1,2,8},get_text_range={2162,1,0,10},goto_line={2024,0,1,0},goto_pos={2025,0,3,0},grab_focus={2400,0,0,0},hide_lines={2227,0,1,1},hide_selection={2163,0,5,0},home={2312,0,0,0},home_display={2345,0,0,0},home_display_extend={2346,0,0,0},home_extend={2313,0,0,0},home_rect_extend={2430,0,0,0},home_wrap={2349,0,0,0},home_wrap_extend={2450,0,0,0},indicator_all_on_for={2506,1,1,0},indicator_clear_range={2505,0,1,1},indicator_end={2509,1,1,1},indicator_fill_range={2504,0,1,1},indicator_start={2508,1,1,1},indicator_value_at={2507,1,1,1},insert_text={2003,0,3,7},line_copy={2455,0,0,0},line_cut={2337,0,0,0},line_delete={2338,0,0,0},line_down={2300,0,0,0},line_down_extend={2301,0,0,0},line_down_rect_extend={2426,0,0,0},line_duplicate={2404,0,0,0},line_end={2314,0,0,0},line_end_display={2347,0,0,0},line_end_display_extend={2348,0,0,0},line_end_extend={2315,0,0,0},line_end_rect_extend={2432,0,0,0},line_end_wrap={2451,0,0,0},line_end_wrap_extend={2452,0,0,0},line_from_position={2166,1,3,0},line_length={2350,1,1,0},line_scroll={2168,0,1,1},line_scroll_down={2342,0,0,0},line_scroll_up={2343,0,0,0},line_transpose={2339,0,0,0},line_up={2302,0,0,0},line_up_extend={2303,0,0,0},line_up_rect_extend={2427,0,0,0},lines_join={2288,0,0,0},lines_split={2289,0,1,0},load_lexer_library={4007,0,0,7},lower_case={2340,0,0,0},margin_text_clear_all={2536,0,0,0},marker_add={2043,1,1,1},marker_add_set={2466,0,1,1},marker_define={2040,0,1,1},marker_define_pixmap={2049,0,1,7},marker_define_rgba_image={2626,0,1,7},marker_delete={2044,0,1,1},marker_delete_all={2045,0,1,0},marker_delete_handle={2018,0,1,0},marker_enable_highlight={2293,0,5,0},marker_get={2046,1,1,0},marker_line_from_handle={2017,1,1,0},marker_next={2047,1,1,1},marker_previous={2048,1,1,1},marker_symbol_defined={2529,1,1,0},move_caret_inside_view={2401,0,0,0},move_selected_lines_down={2621,0,0,0},move_selected_lines_up={2620,0,0,0},new_line={2329,0,0,0},null={2172,0,0,0},page_down={2322,0,0,0},page_down_extend={2323,0,0,0},page_down_rect_extend={2434,0,0,0},page_up={2320,0,0,0},page_up_extend={2321,0,0,0},page_up_rect_extend={2433,0,0,0},para_down={2413,0,0,0},para_down_extend={2414,0,0,0},para_up={2415,0,0,0},para_up_extend={2416,0,0,0},paste={2179,0,0,0},point_x_from_position={2164,1,0,3},point_y_from_position={2165,1,0,3},position_after={2418,3,3,0},position_before={2417,3,3,0},position_from_line={2167,3,1,0},position_from_point={2022,3,1,1},position_from_point_close={2023,3,1,1},private_lexer_call={4013,1,1,1},property_names={4014,1,0,8},property_type={4015,1,7,0},redo={2011,0,0,0},register_image={2405,0,1,7},register_rgba_image={2627,0,1,7},release_document={2377,0,0,1},replace_sel={2170,0,0,7},replace_target={2194,1,2,7},replace_target_re={2195,1,2,7},rotate_selection={2606,0,0,0},scroll_caret={2169,0,0,0},scroll_to_end={2629,0,0,0},scroll_to_start={2628,0,0,0},search_anchor={2366,0,0,0},search_in_target={2197,1,2,7},search_next={2367,1,1,7},search_prev={2368,1,1,7},select_all={2013,0,0,0},selection_duplicate={2469,0,0,0},set_chars_default={2444,0,0,0},set_empty_selection={2556,0,3,0},set_fold_margin_colour={2290,0,5,4},set_fold_margin_hi_colour={2291,0,5,4},set_hotspot_active_back={2411,0,5,4},set_hotspot_active_fore={2410,0,5,4},set_length_for_encode={2448,0,1,0},set_save_point={2014,0,0,0},set_sel={2160,0,3,3},set_sel_back={2068,0,5,4},set_sel_fore={2067,0,5,4},set_selection={2572,1,1,1},set_styling={2033,0,2,1},set_styling_ex={2073,0,2,7},set_text={2181,0,0,7},set_visible_policy={2394,0,1,1},set_whitespace_back={2085,0,5,4},set_whitespace_fore={2084,0,5,4},set_x_caret_policy={2402,0,1,1},set_y_caret_policy={2403,0,1,1},show_lines={2226,0,1,1},start_record={3001,0,0,0},start_styling={2032,0,3,1},stop_record={3002,0,0,0},stuttered_page_down={2437,0,0,0},stuttered_page_down_extend={2438,0,0,0},stuttered_page_up={2435,0,0,0},stuttered_page_up_extend={2436,0,0,0},style_clear_all={2050,0,0,0},style_reset_default={2058,0,0,0},swap_main_anchor_caret={2607,0,0,0},tab={2327,0,0,0},target_as_utf8={2447,1,0,8},target_from_selection={2287,0,0,0},text_height={2279,1,1,0},text_width={2276,1,1,7},toggle_caret_sticky={2459,0,0,0},toggle_fold={2231,0,1,0},undo={2176,0,0,0},upper_case={2341,0,0,0},use_pop_up={2371,0,5,0},user_list_show={2117,0,1,7},vc_home={2331,0,0,0},vc_home_display={2652,0,0,0},vc_home_display_extend={2653,0,0,0},vc_home_extend={2332,0,0,0},vc_home_rect_extend={2431,0,0,0},vc_home_wrap={2453,0,0,0},vc_home_wrap_extend={2454,0,0,0},vertical_centre_caret={2619,0,0,0},visible_from_doc_line={2220,1,1,0},word_end_position={2267,1,3,5},word_left={2308,0,0,0},word_left_end={2439,0,0,0},word_left_end_extend={2440,0,0,0},word_left_extend={2309,0,0,0},word_part_left={2390,0,0,0},word_part_left_extend={2391,0,0,0},word_part_right={2392,0,0,0},word_part_right_extend={2393,0,0,0},word_right={2310,0,0,0},word_right_end={2441,0,0,0},word_right_end_extend={2442,0,0,0},word_right_extend={2311,0,0,0},word_start_position={2266,1,3,5},wrap_count={2235,1,1,0},zoom_in={2333,0,0,0},zoom_out={2334,0,0,0}} --- --- Scintilla properties. --- Each key is a Scintilla property name with a table value containing the ID of --- its "get" function, the ID of its "set" function, its return type, and its --- wParam type. The wParam type will be non-zero if the property is an indexable --- property. Types are the same as in the `functions` table. +-- Map of Scintilla property names to table values containing their "get" +-- function IDs, "set" function IDs, return types, and wParam types. +-- The wParam type will be non-zero if the property is indexable. +-- Types are the same as in the `functions` table. -- @see functions -- @class table -- @name properties @@ -48,7 +45,7 @@ M.properties = {additional_caret_fore={2605,2604,4,0},additional_carets_blink={2 local marker_number, indic_number, list_type = -1, 7, 0 --- --- Returns a unique marker number. +-- Returns a unique marker number for use with `buffer.marker_define()`. -- Use this function for custom markers in order to prevent clashes with -- identifiers of other custom markers. -- @usage local marknum = _SCINTILLA.next_marker_number() @@ -60,7 +57,7 @@ function M.next_marker_number() end --- --- Returns a unique indicator number. +-- Returns a unique indicator number for use with custom indicators. -- Use this function for custom indicators in order to prevent clashes with -- identifiers of other custom indicators. -- @usage local indic_num = _SCINTILLA.next_indic_number() @@ -72,7 +69,7 @@ function M.next_indic_number() end --- --- Returns a unique user list type. +-- Returns a unique user list type for use with `buffer.user_list_show()`. -- Use this function for custom user lists in order to prevent clashes with -- list identifiers of other custom user lists. -- @usage local list_type = _SCINTILLA.next_user_list_type() diff --git a/core/init.lua b/core/init.lua index e0efd459..8ac2dade 100644 --- a/core/init.lua +++ b/core/init.lua @@ -23,16 +23,16 @@ _M = {} -- modules table --- -- Extends Lua's _G table to provide extra functions and fields for Textadept. -- @field _HOME (string) --- Path to the directory containing Textadept. +-- The path to the directory containing Textadept. -- @field _LEXERPATH (string) --- Paths to lexers, formatted like [`package.path`][]. +-- The paths to lexers, formatted like Lua's [`package.path`][]. -- -- [`package.path`]: http://lua.org/manual/5.2/manual.html#pdf-package.path -- @field _RELEASE (string) --- The Textadept release version. +-- The Textadept release version string. -- @field _USERHOME (string) --- Path to the user's *~/.textadept/*, where all preferences and user-data is --- stored. +-- The path to the user's *~/.textadept/* directory, where all preferences and +-- user-data is stored. -- On Windows machines *~/* is the value of the "USERHOME" environment -- variable, typically *C:\Users\username\\* or -- *C:\Documents and Settings\username\\*. On Linux, BSD, and Mac OSX @@ -53,16 +53,12 @@ _M = {} -- modules table -- ncurses feature incompatibilities are listed in the [Appendix][]. -- -- [Appendix]: ../14_Appendix.html#Ncurses.Compatibility --- @field buffer The current [buffer][] in the current [view](#view). --- --- [buffer]: buffer.html --- @field view The currently focused [view](view.html). module('_G')]] --[[ The tables below were defined in C. --- --- Command line parameters passed to Textadept. +-- Table of command line parameters passed to Textadept. -- @class table -- @see _G.args -- @name arg @@ -73,8 +69,8 @@ local arg -- Numeric keys have buffer values and buffer keys have their associated numeric -- keys. -- @class table --- @usage _BUFFERS[1] contains the first buffer. --- @usage _BUFFERS[buffer] returns the index of the current buffer in _BUFFERS. +-- @usage _BUFFERS[n] --> buffer at index n +-- @usage _BUFFERS[buffer] --> index of buffer in _BUFFERS -- @see _G.buffer -- @name _BUFFERS local _BUFFERS @@ -84,16 +80,28 @@ local _BUFFERS -- Numeric keys have view values and view keys have their associated numeric -- keys. -- @class table --- @usage _VIEWS[1] contains the first view. --- @usage _VIEWS[view] returns the index of the current view in _VIEWS. +-- @usage _VIEWS[n] --> view at index n +-- @usage _VIEWS[view] --> index of view in _VIEWS -- @see _G.view -- @name _VIEWS local _VIEWS +--- +-- The current [buffer](buffer.html) in the current [view](#view). +-- @class table +-- @name buffer +local buffer + +--- +-- The currently focused [view](view.html). +-- @class table +-- @name view +local view + -- The functions below are Lua C functions. --- --- Creates a new buffer. +-- Creates and returns a new buffer. -- Emits a `BUFFER_NEW` event. -- @return the new buffer. -- @class function @@ -102,16 +110,15 @@ local _VIEWS local new_buffer --- --- Quits Textadept. --- Emits a `QUIT` event. If any handler returns `false`, Textadept does not --- quit. +-- Emits a `QUIT` event, and unless any handler returns `false`, quits +-- Textadept. -- @see events.QUIT -- @class function -- @name quit local quit --- --- Resets the Lua state by reloading all init scripts. +-- Resets the Lua state by reloading all initialization scripts. -- Language-specific modules for opened files are NOT reloaded. Re-opening the -- files that use them will reload those modules instead. -- This function is useful for modifying user scripts (such as @@ -125,9 +132,9 @@ local quit local reset --- --- Calls a given function after an interval of time. --- To repeatedly call the function, return `true` inside the function. A `nil` --- or `false` return value stops repetition. +-- Calls the function *f* with the given arguments after *interval* seconds and +-- then repeatedly while *f* returns `true`. A `nil` or `false` return value +-- stops repetition. -- @param interval The interval in seconds to call the function after. -- @param f The function to call. -- @param ... Additional arguments to pass to `f`. diff --git a/core/keys.lua b/core/keys.lua index ba1df7b4..7d2b06a0 100644 --- a/core/keys.lua +++ b/core/keys.lua @@ -83,9 +83,9 @@ local M = {} -- The default value is `'esc'` for the `Esc` (`⎋` on Mac OSX | `Esc` in -- ncurses) key. -- @field LANGUAGE_MODULE_PREFIX (string) --- The starting key command of the key chain reserved for language-specific --- modules. --- The default value is `Ctrl+L` (`⌘L` on Mac OSX | `M-L` in ncurses). +-- The starting key of the key chain reserved for language-specific modules. +-- The default value is `'cl'` on platforms other than Mac OSX, `'ml'` +-- otherwise. Equivalent to `Ctrl+L` (`⌘L` on Mac OSX | `M-L` in ncurses). module('keys')]] local ADD = '' @@ -107,7 +107,7 @@ local error = function(e) events.emit(events.ERROR, e) end --- -- Lookup table for string representations of key codes higher than 255. -- Key codes can be identified by temporarily uncommenting the `print()` --- statements in *core/keys.lua* +-- statements in *core/keys.lua*. -- @class table -- @name KEYSYMS M.KEYSYMS = { @@ -282,4 +282,11 @@ local function get_gdk_key(key_seq) end M.get_gdk_key = get_gdk_key -- export for menu.lua without generating LuaDoc +--- +-- Map of key bindings to commands, with language-specific key tables assigned +-- to a lexer name key. +-- @class table +-- @name _G.keys +local keys + return M diff --git a/core/locale.lua b/core/locale.lua index 715e817e..87123183 100644 --- a/core/locale.lua +++ b/core/locale.lua @@ -4,7 +4,7 @@ local M = {} --[[ This comment is for LuaDoc. --- --- Table of all messages used by Textadept for localization. +-- Map of all messages used by Textadept to their localized form. -- If the table does not contain the localized version of a given message, it -- returns a string indicating so via a metamethod. module('_L')]] @@ -12,10 +12,11 @@ module('_L')]] local none = 'No Localization: ' --- --- Returns whether or not a localized message exists for the given message. +-- Returns whether or not *message* is localized. -- This function is necessary since `_L[message]` never returns `nil`. -- @param message The message to localize. -- @return `true` if a localization exists, `false` otherwise. +-- @name _EXISTS function M._EXISTS(message) return M[message] ~= none..message end local f = io.open(_USERHOME..'/locale.conf', 'rb') |