diff options
Diffstat (limited to 'core/.buffer.luadoc')
| -rw-r--r-- | core/.buffer.luadoc | 2099 |
1 files changed, 1115 insertions, 984 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 |