diff options
Diffstat (limited to 'core')
| -rw-r--r-- | core/.buffer.luadoc | 555 | ||||
| -rw-r--r-- | core/.ui.dialogs.luadoc | 2 | ||||
| -rw-r--r-- | core/.view.luadoc | 2 | ||||
| -rw-r--r-- | core/events.lua | 37 | ||||
| -rw-r--r-- | core/file_io.lua | 8 | ||||
| -rw-r--r-- | core/init.lua | 16 | ||||
| -rw-r--r-- | core/locale.conf | 2 | ||||
| -rw-r--r-- | core/locales/locale.fr.conf | 2 | ||||
| -rw-r--r-- | core/ui.lua | 35 |
9 files changed, 328 insertions, 331 deletions
diff --git a/core/.buffer.luadoc b/core/.buffer.luadoc index 990cc2d3..5ddcf908 100644 --- a/core/.buffer.luadoc +++ b/core/.buffer.luadoc @@ -67,43 +67,41 @@ -- -- The default value is `buffer.ANNOTATION_HIDDEN`. -- @field auto_c_auto_hide (bool) --- Automatically cancel the autocompletion or user list when no entries match +-- Automatically cancel an autocompletion or user list when no entries match -- typed text. -- The default value is `true`. -- @field auto_c_cancel_at_start (bool) --- Cancel an autocompletion or user list when backspacing to a position before --- where autocompletion started (instead of before the word being completed) --- or where the user list was shown. +-- Cancel an autocompletion list when backspacing to a position before where +-- autocompletion started (instead of before the word being completed). +-- This option has no effect for a user list. -- The default value is `true`. -- @field auto_c_case_insensitive_behaviour (number) -- The behavior mode for a case insensitive autocompletion or user list when -- [`buffer.auto_c_ignore_case`](#auto_c_ignore_case) is `true`. -- --- * `buffer.CASEINSENSITIVEBEHAVIOR_RESPECTCASE` +-- * `buffer.CASEINSENSITIVEBEHAVIOUR_RESPECTCASE` -- Prefer to select case-sensitive matches. --- * `buffer.CASEINSENSITIVEBEHAVIOR_IGNORECASE` +-- * `buffer.CASEINSENSITIVEBEHAVIOUR_IGNORECASE` -- No preference. -- --- The default value is `buffer.CASEINSENSITIVEBEHAVIOR_RESPECTCASE`. +-- The default value is `buffer.CASEINSENSITIVEBEHAVIOUR_RESPECTCASE`. -- @field auto_c_choose_single (bool) --- Automatically choose the item in a single-item autocompletion list. This --- option has no effect for a user list. +-- Automatically choose the item in a single-item autocompletion list. +-- This option has no effect for a user list. -- The default value is `false`. -- @field auto_c_current (number, Read-only) --- The index of the currently selected item in the autocompletion or user --- list. +-- The index of the currently selected item in an autocompletion or user list. -- @field auto_c_current_text (string, Read-only) --- The text of the currently selected item in the autocompletion or user list. +-- The text of the currently selected item in an autocompletion or user list. -- @field auto_c_drop_rest_of_word (bool) --- Delete word characters after autocompleted text. +-- Delete any word characters immediately to the right of autocompleted text. -- The default value is `false`. -- @field auto_c_fill_ups (string, Write-only) -- The set of characters that choose the currently selected item in an --- autocompletion or user list when typed. --- The default value is an empty string. +-- autocompletion or user list when the user types one of them. +-- The default value is `''`. -- @field auto_c_ignore_case (bool) --- Ignore case when searching an autocompletion or user list for --- matches. +-- Ignore case when searching an autocompletion or user list for matches. -- The default value is `false`. -- @field auto_c_max_height (number) -- The maximum number of items per page to show in autocompletion and user @@ -148,9 +146,9 @@ -- bitmap to the screen. -- The default value is `true`. -- @field call_tip_fore_hlt (number, Write-only) --- The call tip's highlighted text foreground color, in "0xBBGGRR" format. +-- A call tip's highlighted text foreground color, in "0xBBGGRR" format. -- @field call_tip_position (boolean) --- Display the call tip above the current line instead of below it. +-- Display a call tip above the current line instead of below it. -- The default value is `false`. -- @field call_tip_use_style (number) -- The pixel width of tab characters in call tips. @@ -160,14 +158,14 @@ -- @field caret_fore (number) -- The caret's foreground color, in "0xBBGGRR" format. -- @field caret_line_back (number) --- The background color, in "0xBBGGRR" format, of the line containing the +-- The background color, in "0xBBGGRR" format, of the line that contains the -- caret. -- @field caret_line_back_alpha (number) -- The caret line's background alpha value, ranging from `0` (transparent) to -- `255` (opaque). -- The default value is `buffer.ALPHA_NOALPHA`, for no alpha. -- @field caret_line_visible (bool) --- Color the background of the line containing the caret a different color. +-- Color the background of the line that contains the caret a different color. -- The default value is `false`. -- @field caret_line_visible_always (bool) -- Always show the caret line, even when the window is not in focus. @@ -207,8 +205,9 @@ -- @field char_at (table, Read-only) -- Table of character bytes at positions starting from zero. -- @field column (table, Read-only) --- Table of column numbers, taking tab widths into account, for positions +-- Table of column numbers (taking tab widths into account) for positions -- starting from zero. +-- Multi-byte characters count as single characters. -- @field current_pos (number) -- The caret's position. -- When set, does not scroll the caret into view. @@ -227,7 +226,7 @@ -- The default value is `buffer.CURSORNORMAL`. -- @field edge_colour (number) -- The color, in "0xBBGGRR" format, of the edge or background for long lines --- based on `buffer.edge_mode`. +-- according to `buffer.edge_mode`. -- @field edge_column (number) -- The column number to mark long lines at. -- @field edge_mode (number) @@ -245,7 +244,7 @@ -- @field encoding (string or nil) -- The string encoding of the file, or `nil` for binary files. -- @field encoding_bom (string) --- The byte-order mark, if any, of the file. +-- The byte-order mark (if any) of the file. -- @field end_at_last_line (bool) -- Disable scrolling past the last line. -- The default value is `true`. @@ -254,7 +253,7 @@ -- position. -- @field eol_mode (number) -- The current end of line mode. Changing the current mode does not convert --- existing end of line characters. +-- any of the buffer's existing end of line characters. -- Use [`buffer:convert_eols()`](#convert_eols) to do so. -- -- * `buffer.EOL_CRLF` @@ -277,8 +276,8 @@ -- @field first_visible_line (number) -- 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 fold points are expanded for line --- numbers starting from zero. +-- Table of flags that indicate whether or not fold points 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) @@ -335,11 +334,11 @@ -- Draw guides only within indentation whitespace. -- * `buffer.IV_LOOKFORWARD` -- Draw guides beyond the current line up to the next non-empty line's --- level, but with an additional level if the previous non-empty line is a --- fold point. +-- indentation level, but with an additional level if the previous non-empty +-- line is a fold point. -- * `buffer.IV_LOOKBOTH` --- Draw guides beyond the current line up to either the level of the --- previous or next non-empty line, whichever is greater. +-- Draw guides beyond the current line up to either the indentation level of +-- the previous or next non-empty line, whichever is greater. -- -- The default value is `buffer.IV_NONE`. -- @field indic_alpha (table) @@ -403,7 +402,7 @@ -- -- [`_SCINTILLA.next_indic_number()`]: _SCINTILLA.html#next_indic_number -- @field indic_under (table) --- Table of flags indicating whether or not to draw indicators behind text +-- Table of flags that indicate whether or not to draw indicators behind text -- instead of over the top of it for indicator numbers from `0` to `31`. -- For values to be `true`, [`buffer.two_phase_draw`](#two_phase_draw) must be -- `true`. @@ -430,8 +429,8 @@ -- Line states are unaffected by changes in styling and 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. +-- Table of flags that indicate whether or not lines are visible for line +-- numbers starting from zero. -- @field lines_on_screen (number, Read-only) -- The number of completely visible lines in the view. -- It is possible to have a partial line visible at the bottom of the view. @@ -463,15 +462,15 @@ -- * `buffer.MARGINOPTION_NONE` -- None. -- * `buffer.MARGINOPTION_SUBLINESELECT` --- Select only the wrapped line's sub-line, rather than the entire line, on --- margin click. +-- Select only a wrapped line's sub-line (rather than the entire line) when +-- the line number margin is clicked. -- -- The default value is `buffer.MARGINOPTION_NONE`. -- @field margin_right (number) -- The pixel size of the right margin of the buffer text. -- The default value is `1`. -- @field margin_sensitive_n (table) --- Table of flags indicating whether or not mouse clicks in margins emit +-- Table of flags that indicate 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) @@ -516,7 +515,7 @@ -- Table of pixel margin widths for margin numbers from zero to four. -- @field marker_alpha (table, Write-only) -- Table of alpha values, ranging from `0` (transparent) to `255` (opaque), --- of markers drawn in the text area, not the margin, for markers numbers from +-- of markers drawn in the text area (not the margin) for markers numbers from -- `0` to `31`. -- The default values are `buffer.ALPHA_NOALPHA`, for no alpha. -- @field marker_back (table, Write-only) @@ -562,7 +561,7 @@ -- @field punctuation_chars (string) -- The string set of characters recognized as punctuation characters. -- Set this only after setting [`buffer.word_chars`](#word_chars). --- The default value is a string containing all non-word and non-whitespace +-- The default value is a string that contains all non-word and non-whitespace -- characters. -- @field read_only (bool) -- Whether or not the buffer is read-only. @@ -619,14 +618,14 @@ -- [`buffer:search_in_target()`](#search_in_target). -- -- * `buffer.FIND_WHOLEWORD` --- Match the search text surrounded by non-word characters. +-- Match search text only when it is surrounded by non-word characters. -- * `buffer.FIND_MATCHCASE` --- Match the search text case sensitively. +-- Match search text case sensitively. -- * `buffer.FIND_WORDSTART` --- Match the search text only when the previous character is a non-word +-- Match search text only when the previous character is a non-word -- character. -- * `buffer.FIND_REGEXP` --- Interpret the search text as a regular expression. +-- Interpret search text as a regular expression. -- -- The default value is `0`. -- @@ -689,7 +688,7 @@ -- 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. +-- again to the same value or until [`buffer:cancel()`](#cancel) is called. -- @field selection_n_anchor (table) -- Table of positions at the beginning of existing selections numbered from -- zero, the main selection. @@ -719,7 +718,7 @@ -- Table of background colors, in "0xBBGGRR" format, of text for style numbers -- from `0` to `255`. -- @field style_bold (table) --- Table of flags indicating whether or not text is bold for style numbers +-- Table of flags that indicate whether or not text is bold for style numbers -- from `0` to `255`. -- The default values are `false`. -- @field style_case (table) @@ -734,13 +733,13 @@ -- -- The default values are `buffer.CASE_MIXED`. -- @field style_changeable (table) --- Table of flags indicating whether or not text is changeable for style +-- Table of flags that indicate whether or not text 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. +-- but ranges that contain read-only text are deletable. -- @field style_eol_filled (table) --- Table of flags indicating whether or not the background colors of styles +-- Table of flags that indicate whether or not the background colors of styles -- whose characters occur last on lines extend all the way to the view's right -- margin for style numbers from `0` to `255`. -- The default values are `false`. @@ -750,24 +749,24 @@ -- Table of foreground colors, in "0xBBGGRR" format, of text for style numbers -- from `0` to `255`. -- @field style_hot_spot (table) --- Table of flags indicating whether or not text is clickable for style +-- Table of flags that indicate whether or not text is clickable for style -- numbers from `0` to `255`. -- The default values are `false`. -- @field style_italic (table) --- Table of flags indicating whether or not text is italic for style numbers --- from `0` to `255`. +-- Table of flags that indicate whether or not text is italic for style +-- numbers from `0` to `255`. -- The default values are `false`. -- @field style_name (table, Read-only) -- Table of style names for style numbers from `0` to `255`. -- @field style_size (table) -- Table of font sizes of text for style numbers from `0` to `255`. -- @field style_underline (table) --- Table of flags indicating whether or not text is underlined for style +-- Table of flags that indicate whether or not text is underlined for style -- numbers from `0` to `255`. -- The default values are `false`. -- @field style_visible (table) --- Table of flags indicating whether or not text is visible for style numbers --- from `0` to `255`. +-- Table of flags that indicate whether or not text is visible for style +-- numbers from `0` to `255`. -- The default values are `true`. -- @field tab_indents (bool) -- Indent text when tabbing within indentation. @@ -795,12 +794,12 @@ -- @field undo_collection (bool) -- 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. +-- [`buffer:empty_undo_buffer()`](#empty_undo_buffer) to synchronize the undo +-- buffer with the buffer text. -- The default value is `true`. -- @field use_tabs (bool) -- Use tabs instead of spaces in indentation. Changing the current setting --- does not convert existing indentation. Use +-- does not convert any of the buffer's existing indentation. Use -- [`textadept.editing.convert_indentation()`][] to do so. -- The default value is `true`. -- @field v_scroll_bar (bool) @@ -836,15 +835,15 @@ -- @field whitespace_chars (string) -- The string set of characters recognized as whitespace characters. -- Set this only after setting [`buffer.word_chars`](#word_chars). --- The default value is a string containing all non-newline characters less +-- The default value is a string that contains all non-newline characters less -- than ASCII value 33. -- @field whitespace_size (number) --- The pixel size of the dots representing space characters when whitespace is --- visible. +-- The pixel size of the dots that represent space characters when whitespace +-- is visible. -- The default value is `1`. -- @field word_chars (string) -- The string set of characters recognized as word characters. --- The default value is a string containing alphanumeric characters, an +-- The default value is a string that contains alphanumeric characters, an -- underscore, and all characters greater than ASCII value 127. -- @field wrap_indent_mode (number) -- The wrapped line indent mode. @@ -874,27 +873,27 @@ -- `buffer.WRAP_INDENT_FIXED`. -- The default value is `0`. -- @field wrap_visual_flags (number) --- The wrapped line visual display mode. +-- The wrapped line visual flag display mode. -- -- * `buffer.WRAPVISUALFLAG_NONE` -- No visual flags. -- * `buffer.WRAPVISUALFLAG_END` --- Show visual flag at the end of the line. +-- Show a visual flag at the end of a wrapped line. -- * `buffer.WRAPVISUALFLAG_START` --- Show visual flag at the beginning of the sub-line. +-- Show a visual flag at the beginning of a sub-line. -- * `buffer.WRAPVISUALFLAG_MARGIN` --- Show visual flag in the sub-line's line number margin. +-- Show a visual flag in the sub-line's line number margin. -- -- The default value is `buffer.WRAPVISUALFLAG_NONE`. -- @field wrap_visual_flags_location (number) -- The wrapped line visual flag drawing mode. -- -- * `buffer.WRAPVISUALFLAGLOC_DEFAULT` --- Draw the visual flag near the view's right margin. +-- Draw a visual flag near the view's right margin. -- * `buffer.WRAPVISUALFLAGLOC_END_BY_TEXT` --- Draw the visual flag near text at the end of the line. +-- Draw a visual flag near text at the end of a wrapped line. -- * `buffer.WRAPVISUALFLAGLOC_START_BY_TEXT` --- Draw the visual flag near text at the beginning of the subline. +-- Draw a visual flag near text at the beginning of a subline. -- -- The default value is `buffer.WRAPVISUALFLAGLOC_DEFAULT`. -- @field x_offset (number) @@ -957,47 +956,47 @@ function append_text(buffer, text) end function auto_c_active(buffer) end --- --- Cancels the autocompletion or user list. +-- Cancels an autocompletion or user list. -- @param buffer The buffer. function auto_c_cancel(buffer) end --- --- Autocompletes the selected word in the autocompletion list. +-- Completes the current word with the one selected in an autocompletion list. -- @param buffer The buffer. function auto_c_complete(buffer) end --- --- Returns the position where autocompletion started or where the user list was +-- Returns the position where autocompletion started or where a user list was -- shown. -- @param buffer The buffer. -- @return number function auto_c_pos_start(buffer) end --- --- Selects the first item in the autocompletion or user list that starts with --- string *prefix*, using case sensitivity setting `buffer.auto_c_ignore_case`. +-- Selects the first item that starts with string *prefix* in an autocompletion +-- or user list, using the case sensitivity setting `buffer.auto_c_ignore_case`. -- @param buffer The buffer. -- @param prefix The item in the list to select. function auto_c_select(buffer, prefix) end --- --- Displays an autocompletion list constructed from string *item_list*, 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. --- `buffer.auto_c_order`, the sorted order of *item_list*, must have already --- been defined. +-- Displays an autocompletion list constructed from string *items* (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 be +-- autocompleted. +-- The sorted order of *items* (`buffer.auto_c_order`) must have already been +-- defined. -- @param buffer The buffer. -- @param len_entered The number of characters before the caret used to provide -- the context. --- @param item_list The sorted string of words to show, separated by +-- @param items The sorted string of words to show, separated by -- `buffer.auto_c_separator` characters (initially spaces). -function auto_c_show(buffer, len_entered, item_list) end +function auto_c_show(buffer, len_entered, items) end --- --- Defines string *chars* as the set of characters that cancels an --- autocompletion or user list when typed. --- The default set is an empty string. +-- Allows the user to type any character in string set *chars* in order to +-- cancel an autocompletion or user list. +-- The default set is empty. -- @param buffer The buffer. -- @param chars The string of characters that cancel autocompletion. This string -- is empty by default. @@ -1009,7 +1008,7 @@ function auto_c_stops(buffer, chars) end function back_tab(buffer) end --- --- Starts a sequence of actions to undo or redo as a single action. +-- Starts a sequence of actions to be undone or redone as a single action. -- May be nested. -- @param buffer The buffer. function begin_undo_action(buffer) end @@ -1024,13 +1023,13 @@ function begin_undo_action(buffer) end function brace_bad_light(buffer, pos) end --- --- Highlights unmatched brace characters with indicator number *indic_num*, in +-- Highlights unmatched brace characters with indicator number *indicator*, in -- the range of `0` to `31`, instead of the -- `buffer.STYLE_BRACEBAD` style if *use_indicator* is `true`. -- @param buffer The buffer. -- @param use_indicator Whether or not to use an indicator. --- @param indic_num The indicator number to use. -function brace_bad_light_indicator(buffer, use_indicator, indic_num) end +-- @param indicator The indicator number to use. +function brace_bad_light_indicator(buffer, use_indicator, indicator) end --- -- Highlights the characters at positions *pos1* and *pos2* as matching braces @@ -1043,13 +1042,13 @@ function brace_bad_light_indicator(buffer, use_indicator, indic_num) end function brace_highlight(buffer, pos1, pos2) end --- --- Highlights matching brace characters with indicator number *indic_num*, in +-- Highlights matching brace characters with indicator number *indicator*, in -- the range of `0` to `31`, instead of the -- `buffer.STYLE_BRACELIGHT` style if *use_indicator* is `true`. -- @param buffer The buffer. -- @param use_indicator Whether or not to use an indicator. --- @param indic_num The indicator number to use. -function brace_highlight_indicator(buffer, use_indicator, indic_num) end +-- @param indicator The indicator number to use. +function brace_highlight_indicator(buffer, use_indicator, indicator) end --- -- Returns the position of the matching brace for the brace character at @@ -1062,48 +1061,49 @@ function brace_highlight_indicator(buffer, use_indicator, indic_num) end function brace_match(buffer, pos) end --- --- Returns whether or not the call tip is visible. +-- Returns whether or not a call tip is visible. -- @param buffer The buffer. -- @return bool function call_tip_active(buffer) end --- --- Removes the call tip from view. +-- Removes a call tip from view. -- @param buffer The buffer. function call_tip_cancel(buffer) end --- --- Returns the call tip's display position. +-- Returns a call tip's display position. -- @param buffer The buffer. -- @return number function call_tip_pos_start(buffer) end --- --- Highlights the call tip text between positions *start_pos*, starting from +-- Highlights a call tip's text between positions *start_pos*, starting from -- zero, to *end_pos* with the color `buffer.call_tip_fore_hlt`. -- @param buffer The buffer. --- @param start_pos The start position in the call tip text to highlight. --- @param end_pos The end position in the call tip text to highlight. +-- @param start_pos The start position in a call tip text to highlight. +-- @param end_pos The end position in a call tip text to highlight. function call_tip_set_hlt(buffer, start_pos, end_pos) end --- --- Displays a call tip containing string *text* for the word behind position --- *pos*. --- Any "\001" or "\002" bytes in *text* are replaced by up or down arrow --- visuals, respectively, indicating the word has more than one call tip. +-- Displays a call tip at position *pos* with string *text* as the call tip's +-- contents. +-- Any "\001" or "\002" bytes in *text* are replaced by clickable up or down +-- arrow visuals, respectively. These may be used to indicate that a symbol has +-- more than one call tip, for example. -- @param buffer The buffer. --- @param pos The position in *buffer* to show the call tip at. +-- @param pos The position in *buffer* to show a call tip at. -- @param text The call tip text to show. function call_tip_show(buffer, pos, text) end --- --- Returns whether or not there is an action to redo. +-- Returns whether or not there is an action to be redone. -- @param buffer The buffer. -- @return bool function can_redo(buffer) end --- --- Returns whether or not there is an action to undo. +-- Returns whether or not there is an action to be undone. -- @param buffer The buffer. -- @return bool function can_undo(buffer) end @@ -1115,16 +1115,6 @@ function can_undo(buffer) end function cancel(buffer) end --- --- Instructs the lexer to reprocess the range of text between *start_pos* and --- *end_pos* due to a change in state. --- @param buffer The buffer. --- @param start_pos The start position of the range of text in *buffer* to --- reprocess. --- @param end_pos The end position of the range of text in *buffer* to --- reprocess. -function change_lexer_state(buffer, start_pos, end_pos) end - ---- -- Moves the caret left one character. -- @param buffer The buffer. function char_left(buffer) end @@ -1192,9 +1182,9 @@ function clear_registered_images(buffer) end function clear_selections(buffer) end --- --- Instructs the lexer to style and fold the range of text between *start_pos* --- and *end_pos*. --- If *end_pos* is `-1`, styles and folds to the end of the buffer. +-- Instructs the lexer to style and mark fold points in the range of text +-- between *start_pos* and *end_pos*. +-- If *end_pos* is `-1`, styles and marks to the end of the buffer. -- @param buffer The buffer. -- @param start_pos The start position of the range of text in *buffer* to -- process. @@ -1203,15 +1193,15 @@ function clear_selections(buffer) end function colourise(buffer, start_pos, end_pos) end --- --- Returns the line number of the next contracted fold point starting at line --- number *line_start*, or `-1`. +-- Returns the line number of the next contracted fold point starting from line +-- number *line*, or `-1` if none exists. -- @param buffer The buffer. --- @param line_start The line number in *buffer* to start at. +-- @param line The line number in *buffer* to start at. -- @return number -function contracted_fold_next(buffer, line_start) end +function contracted_fold_next(buffer, line) end --- --- Converts all end of line characters to the ones in end of line mode *mode*. +-- Converts all end of line characters to those in end of line mode *mode*. -- @param buffer The buffer. -- @param mode The end of line mode to convert to. Valid values are: -- * `buffer.EOL_CRLF` @@ -1247,9 +1237,8 @@ function copy_range(buffer, start_pos, end_pos) end function copy_text(buffer, text) end --- --- Returns the number of whole characters, taking multi-byte characters into --- account, between positions *start_pos* and --- *end_pos*. +-- Returns the number of whole characters (taking multi-byte characters into +-- account) between positions *start_pos* and *end_pos*. -- @param buffer The buffer. -- @param start_pos The start position of the range of text in *buffer* to start -- counting at. @@ -1267,12 +1256,13 @@ function count_characters(buffer, start_pos, end_pos) end function cut(buffer) end --- --- Deletes the range of text from the caret to the beginning of the line. +-- Deletes the range of text from the caret to the beginning of the current +-- line. -- @param buffer The buffer. function del_line_left(buffer) end --- --- Deletes the range of text from the caret to the end of the line. +-- Deletes the range of text from the caret to the end of the current line. -- @param buffer The buffer. function del_line_right(buffer) end @@ -1298,13 +1288,15 @@ function del_word_right(buffer) end function del_word_right_end(buffer) end --- --- Deletes the selected text or the character behind the caret. +-- Deletes the character behind the caret if no text is selected. +-- Otherwise, deletes the selected text. -- @param buffer The buffer. function delete_back(buffer) end --- --- Deletes the selected text or the character behind the caret unless the caret --- is at the beginning of a line. +-- Deletes the character behind the caret unless either the caret is at the +-- beginning of a line or text is selected. +-- If text is selected, deletes it. -- @param buffer The buffer. function delete_back_not_line(buffer) end @@ -1359,7 +1351,7 @@ function edit_toggle_overtype(buffer) end function empty_undo_buffer(buffer) end --- --- Ends a sequence of actions to undo or redo as a single action. +-- Ends a sequence of actions to be undone or redone as a single action. -- @param buffer The buffer. function end_undo_action(buffer) end @@ -1378,8 +1370,8 @@ function ensure_visible(buffer, line) end function ensure_visible_enforce_policy(buffer, line) end --- --- 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 +-- 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 buffer. -- @param line The line number in *buffer* to use. @@ -1387,7 +1379,7 @@ function ensure_visible_enforce_policy(buffer, line) end function find_column(buffer, line, column) end --- --- Expands, contracts, or toggles all fold points, depending on *action*. +-- Contracts, expands, or toggles all fold points, depending on *action*. -- When toggling, the state of the first fold point determines whether to -- expand or contract. -- @param buffer The buffer. @@ -1398,7 +1390,7 @@ function find_column(buffer, line, column) end function fold_all(buffer, action) end --- --- Expands, contracts, or toggles the fold point on line number *line* as well +-- Contracts, expands, or toggles the fold point on line number *line*, as well -- as all of its children, depending on *action*. -- @param buffer The buffer. -- @param line The line number in *buffer* to set the fold states for. @@ -1409,7 +1401,7 @@ function fold_all(buffer, action) end function fold_children(buffer, line, action) end --- --- Expands, contracts, or toggles the fold point on line number *line*, +-- Contracts, expands, or toggles the fold point on line number *line*, -- depending on *action*. -- @param buffer The buffer. -- @param line The line number in *buffer* to set the fold state for. @@ -1425,7 +1417,7 @@ function fold_line(buffer, line, action) end function form_feed(buffer) end --- --- Returns the current line's text and the caret's position on the line, +-- Returns the current line's text and the caret's position on that line, -- starting from zero. -- @param buffer The buffer. -- @return string, number @@ -1444,13 +1436,13 @@ function get_hotspot_active_back(buffer) end function get_hotspot_active_fore(buffer) end --- --- Returns the line number of the last line after line number *start_line* whose --- fold level is greater than *level* or, if *level* is `-1`, the level of --- *start_line*. +-- Returns the line number of the last line after line number *line* whose fold +-- level is greater than *level*. +-- If *level* is `-1`, returns the level of *line*. -- @param buffer The buffer. --- @param start_line The line number in *buffer* of a header line. --- @param level The fold level, or `-1` for the level of *start_line*. -function get_last_child(buffer, start_line, level) end +-- @param line The line number in *buffer* of a header line. +-- @param level The fold level, or `-1` for the level of *line*. +function get_last_child(buffer, line, level) end --- -- Returns the text on line number *line*, including end of line characters. @@ -1461,14 +1453,14 @@ function get_line(buffer, line) end --- -- Returns the position of the end of the selected text on line number *line*, --- or `-1`. +-- or `-1` if *line* has no selection. -- @param buffer The buffer. -- @param line The line number in *buffer* to use. function get_line_sel_end_position(buffer, line) end --- -- Returns the position of the beginning of the selected text on line number --- *line*, or `-1`. +-- *line*, or `-1` if *line* has no selection. -- @param buffer The buffer. -- @param line The line number in *buffer* to use. function get_line_sel_start_position(buffer, line) end @@ -1501,7 +1493,7 @@ function goto_line(buffer, line) end function goto_pos(buffer, pos) end --- --- Hides the range of lines from line number *start_line* to *end_line*. +-- Hides the range of lines between line numbers *start_line* to *end_line*. -- This has no effect on fold levels or fold flags and the first line cannot be -- hidden. -- @param buffer The buffer. @@ -1555,7 +1547,7 @@ function home_wrap(buffer) end function home_wrap_extend(buffer) end --- --- Returns a bit-mask representing which indicators are on at position *pos*. +-- Returns a bit-mask that represents 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 buffer. -- @param pos The position in *buffer* to get indicators at. @@ -1564,35 +1556,37 @@ function indicator_all_on_for(buffer, pos) end --- -- Clears indicator number `buffer.indicator_current` over the range of text --- from position *pos* to *pos* + *clear_length*. +-- from position *pos* to *pos* + *length*. -- @param buffer The buffer. -- @param pos The start position of the range of text in *buffer* to clear -- indicators over. --- @param clear_length The number of characters in the range of text to clear +-- @param length The number of characters in the range of text to clear -- indicators over. -function indicator_clear_range(buffer, pos, clear_length) end +function indicator_clear_range(buffer, pos, length) end --- --- Returns the end position of indicator number *indicator*, in the range of `0` --- to `31`, at position *pos*. +-- Returns the next boundary position, starting from position *pos*, of +-- indicator number *indicator*, in the range of `0` to `31`. +-- Returns `buffer.length` if *indicator* was not found. -- @param buffer The buffer. -- @param indicator An indicator number in the range of `0` to `31`. -- @param pos The position in *buffer* of the indicator. function indicator_end(buffer, indicator, pos) end --- --- Fills the range of text from position *pos* to *pos* + *fill_length* with +-- Fills the range of text from position *pos* to *pos* + *length* with -- indicator number `buffer.indicator_current`. -- @param buffer The buffer. -- @param pos The start position of the range of text in *buffer* to set -- indicators over. --- @param fill_length The number of characters in the range of text to set --- indicators over. -function indicator_fill_range(buffer, pos, fill_length) end +-- @param length The number of characters in the range of text to set indicators +-- over. +function indicator_fill_range(buffer, pos, length) end --- --- Returns the position of the beginning of indicator number *indicator*, in the --- range of `0` to `31`, at position *pos*. +-- Returns the previous boundary position, starting from position *pos*, of +-- indicator number *indicator*, in the range of `0` to `31`. +-- Returns `0` if *indicator* was not found. -- @param buffer The buffer. -- @param indicator An indicator number in the range of `0` to `31`. -- @param pos The position in *buffer* of the indicator. @@ -1687,7 +1681,7 @@ function line_end_wrap(buffer) end function line_end_wrap_extend(buffer) end --- --- Returns the line number of the line containing position *pos*. +-- Returns the line number of the line that contains position *pos*. -- Returns `0` if *pos* is less than 0 or `buffer.line_count` if *pos* is -- greater than `buffer.length`. -- @param buffer The buffer. @@ -1745,14 +1739,15 @@ function line_up_extend(buffer) end function line_up_rect_extend(buffer) end --- --- Joins the lines in the target range, inserting spaces between joined --- words at line boundaries. +-- Joins the lines in the target range, inserting spaces between the words +-- joined at line boundaries. -- @param buffer The buffer. function lines_join(buffer) end --- --- Splits the lines in the target range into lines at most *width* pixels wide --- or, if *width* is `0`, lines as wide as the view. +-- Splits the lines in the target range into lines *width* pixels wide. +-- If *width* is `0`, splits the lines in the target range into lines as wide as +-- the view. -- @param buffer The buffer. -- @param width The pixel width to split lines at. When `0`, uses the width of -- the view. @@ -1769,15 +1764,15 @@ function lower_case(buffer) end function margin_text_clear_all(buffer) end --- --- Adds marker number *marker_num*, in the range of `0` to `31`, to line number --- *line*, returning a marker handle which can be used in +-- Adds marker number *marker*, in the range of `0` to `31`, to line number +-- *line*, returning the added marker's handle which can be used in -- `buffer:marker_delete_handle()` and `buffer:marker_line_from_handle()`, or --- `-1` if the marker cannot be added. +-- `0` if *line* is invalid. -- @param buffer The buffer. -- @param line The line number to add the marker on. --- @param marker_num The marker number in the range of `0` to `31` to add. +-- @param marker The marker number in the range of `0` to `31` to add. -- @return number -function marker_add(buffer, line, marker_num) end +function marker_add(buffer, line, marker) end --- -- Adds the markers specified in marker bit-mask *marker_mask* to line number @@ -1791,42 +1786,41 @@ function marker_add(buffer, line, marker_num) end function marker_add_set(buffer, line, marker_mask) end --- --- Assigns marker symbol *marker_symbol* to marker number *marker_num*, in the --- range of `0` to `31`. --- *marker_symbol* is shown in marker symbol margins next to lines marked with --- *marker_num*. +-- Assigns marker symbol *symbol* to marker number *marker*, in the range of `0` +-- to `31`. +-- *symbol* is shown in marker symbol margins next to lines marked with +-- *marker*. -- @param buffer The buffer. --- @param marker_num The marker number in the range of `0` to `31` to set --- *marker_symbol* for. --- @param marker_symbol The marker symbol: `buffer.MARK_*`. +-- @param marker The marker number in the range of `0` to `31` to set *symbol* +-- for. +-- @param symbol The marker symbol: `buffer.MARK_*`. -- @see _SCINTILLA.next_marker_number -function marker_define(buffer, marker_num, marker_symbol) end +function marker_define(buffer, marker, symbol) end --- --- Associates marker number *marker_num*, in the range of `0` to `31`, with XPM +-- Associates marker number *marker*, in the range of `0` to `31`, with XPM -- image *pixmap*. --- The `buffer.MARK_PIXMAP` marker symbol must be assigned to *marker_num*. --- The image is shown in marker symbol margins next to lines marked with --- *marker_num*. +-- The `buffer.MARK_PIXMAP` marker symbol must be assigned to *marker*. +-- *pixmap* is shown in marker symbol margins next to lines marked with +-- *marker*. -- @param buffer The buffer. --- @param marker_num The marker number in the range of `0` to `31` to define +-- @param marker The marker number in the range of `0` to `31` to define -- pixmap *pixmap* for. -- @param pixmap The string pixmap data. -function marker_define_pixmap(buffer, marker_num, pixmap) end +function marker_define_pixmap(buffer, marker, pixmap) end --- --- Associates marker number *marker_num*, in the range of `0` to `31`, with RGBA +-- Associates marker number *marker*, in the range of `0` to `31`, with RGBA -- image *pixels*. --- The dimensions for *pixels*, `buffer.rgba_image_width` and --- `buffer.rgba_image_height`, must have already been defined. *pixels* is a +-- The dimensions for *pixels* (`buffer.rgba_image_width` and +-- `buffer.rgba_image_height`) must have already been defined. *pixels* is a -- sequence of 4 byte pixel values (red, blue, green, and alpha) defining the -- image line by line starting at the top-left pixel. --- The `buffer.MARK_RGBAIMAGE` marker symbol must be assigned to *marker_num*. --- The image is shown in symbol margins next to lines marked with *marker_num*. --- RGBA image markers use the `buffer.MARK_RGBAIMAGE` marker symbol. +-- The `buffer.MARK_RGBAIMAGE` marker symbol must be assigned to *marker*. +-- *pixels* is shown in symbol margins next to lines marked with *marker*. -- @param buffer The buffer. --- @param marker_num The marker number in the range of `0` to `31` to define --- RGBA data *pixels* for. +-- @param marker The marker number in the range of `0` to `31` to define RGBA +-- data *pixels* for. -- @param pixels The string sequence of 4 byte pixel values starting with the -- pixels for the top line, with the leftmost pixel first, then continuing -- with the pixels for subsequent lines. There is no gap between lines for @@ -1834,25 +1828,25 @@ function marker_define_pixmap(buffer, marker_num, pixmap) end -- byte, a blue byte and an alpha byte. The colour bytes are not premultiplied -- by the alpha value. That is, a fully red pixel that is 25% opaque will be -- `[FF, 00, 00, 3F]`. -function marker_define_rgba_image(buffer, marker_num, pixels) end +function marker_define_rgba_image(buffer, marker, pixels) end --- --- Deletes marker number *marker_num*, in the range of `0` to `31` or `-1` for --- all markers, from line number *line*. +-- Deletes marker number *marker*, in the range of `0` to `31`, from line number +-- *line*. If *marker* is `-1`, deletes all markers from *line*. -- @param buffer The buffer. -- @param line The line number to delete the marker on. --- @param marker_num The marker number in the range of `0` to `31` to delete --- from *line*, or `-1` to delete all markers from the line. -function marker_delete(buffer, line, marker_num) end +-- @param marker The marker number in the range of `0` to `31` to delete from +-- *line*, or `-1` to delete all markers from the line. +function marker_delete(buffer, line, marker) end --- --- Deletes marker number *marker_num*, in the range of `0` to `31`, from any --- line that has it. --- If *marker_num* is `-1`, deletes all markers from all lines. +-- Deletes marker number *marker*, in the range of `0` to `31`, from any line +-- that has it. +-- If *marker* is `-1`, deletes all markers from all lines. -- @param buffer The buffer. --- @param marker_num The marker number in the range of `0` to `31` to delete --- from all lines, or `-1` to delete all markers from all lines. -function marker_delete_all(buffer, marker_num) end +-- @param marker The marker number in the range of `0` to `31` to delete from +-- all lines, or `-1` to delete all markers from all lines. +function marker_delete_all(buffer, marker) end --- -- Deletes the marker with handle *handle* returned by `buffer:marker_add()`. @@ -1868,7 +1862,7 @@ function marker_delete_handle(buffer, handle) end function marker_enable_highlight(buffer, enabled) end --- --- Returns a bit-mask representing the markers that were added to line number +-- Returns a bit-mask that represents the markers that were added to line number -- *line*. -- The first bit is set if marker number 0 is present, the second bit for marker -- number 1, and so on. @@ -1879,45 +1873,45 @@ function marker_get(buffer, line) end --- -- Returns the line number that marker handle *handle*, returned by --- `buffer:marker_add()`, was added to, or `-1`. +-- `buffer:marker_add()`, was added to, or `-1` if the line was not found. -- @param buffer The buffer. -- @param handle The identifier of a marker returned by `buffer:marker_add()`. -- @return number function marker_line_from_handle(buffer, handle) end --- --- Returns the first line number, starting at line number *start_line*, that has --- had all of the markers represented by marker bit-mask *marker_mask* added to --- it, or `-1` if no line was found. +-- Returns the first line number, starting at line number *line*, that has had +-- all of the markers represented by marker bit-mask *marker_mask* added to it. +-- Returns `-1` if no line was found. -- Bit 0 is set if marker 0 is set, bit 1 for marker 1, etc., up to marker 31. -- @param buffer The buffer. --- @param start_line The start line to search from. +-- @param line The start line to search from. -- @param marker_mask The mask of markers to find. Set bit 0 to find marker 0, -- bit 1 for marker 1 and so on. -- @return number -function marker_next(buffer, start_line, marker_mask) end +function marker_next(buffer, line, marker_mask) end --- --- Returns the last line number, before or on line number *start_line*, that has --- had all of the markers represented by marker bit-mask *marker_mask* added to --- it, or `-1` if no line was found. +-- Returns the last line number, before or on line number *line*, that has had +-- all of the markers represented by marker bit-mask *marker_mask* added to it. +-- Returns `-1` if no line was found. -- Bit 0 is set if marker 0 is set, bit 1 for marker 1, etc., up to marker 31. -- @param buffer The buffer. --- @param start_line The start line to search from. +-- @param line The start line to search from. -- @param marker_mask The mask of markers to find. Set bit 0 to find marker 0, -- bit 1 for marker 1 and so on. -- @return number -function marker_previous(buffer, start_line, marker_mask) end +function marker_previous(buffer, line, marker_mask) end --- --- Returns the symbol assigned to marker number *marker_num*, in the range of --- `0` to `31`, used in `buffer:marker_define()`, +-- Returns the symbol assigned to marker number *marker*, 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 buffer. --- @param marker_num The marker number in the range of `0` to `31` to get the --- symbol of. +-- @param marker The marker number in the range of `0` to `31` to get the symbol +-- of. -- @return number -function marker_symbol_defined(buffer, marker_num) end +function marker_symbol_defined(buffer, marker) end --- -- Moves the caret into view if it is not already, removing any selections. @@ -1935,7 +1929,7 @@ function move_selected_lines_down(buffer) end function move_selected_lines_up(buffer) end --- --- Types a new line at the caret position based on +-- Types a new line at the caret position according to -- [`buffer.eol_mode`](#eol_mode). -- @param buffer The buffer. function new_line(buffer) end @@ -2001,20 +1995,22 @@ function para_up_extend(buffer) end --- -- Pastes the clipboard's contents into the buffer, replacing any selected text --- depending on `buffer.multi_paste`. +-- according to `buffer.multi_paste`. -- @param buffer The buffer. function paste(buffer) end --- --- Returns the position of the next character after position *pos*, taking --- multi-byte characters into account, or `buffer.length`. +-- Returns the position of the character after position *pos* (taking multi-byte +-- characters into account), or `buffer.length` if there is no character after +-- *pos*. -- @param buffer The buffer. -- @param pos The position in *buffer* to get the position after from. function position_after(buffer, pos) end --- --- Returns the position of the previous character before position *pos*, taking --- multi-byte characters into account, or `0`. +-- Returns the position of the character before position *pos* (taking +-- multi-byte characters into account), or `0` if there is no character before +-- *pos*. -- @param buffer The buffer. -- @param pos The position in *buffer* to get the position before from. -- @return number @@ -2044,8 +2040,8 @@ function register_image(buffer, type, xpm_data) end --- -- Registers RGBA image *pixels* to type number *type* for use in autocompletion -- and user lists. --- The dimensions for *pixels*, `buffer.rgba_image_width` and --- `buffer.rgba_image_height`, must have already been defined. *pixels* is a +-- The dimensions for *pixels* (`buffer.rgba_image_width` and +-- `buffer.rgba_image_height`) must have already been defined. *pixels* is a -- sequence of 4 byte pixel values (red, blue, green, and alpha) defining the -- image line by line starting at the top-left pixel. -- @param buffer The buffer. @@ -2087,7 +2083,7 @@ function replace_target(buffer, text) end function replace_target_re(buffer, text) end --- --- Taps the next additional selection to be the main selection. +-- Designates the next additional selection to be the main selection. -- @param buffer The buffer. function rotate_selection(buffer) end @@ -2100,8 +2096,8 @@ function rotate_selection(buffer) end function scroll_caret(buffer) end --- --- Scrolls the range of text between positions *primary_pos* and *secondary_pos* --- into view, with priority given to *primary_pos*. +-- Scrolls into view the range of text between positions *primary_pos* and +-- *secondary_pos*, with priority given to *primary_pos*. -- Similar to `buffer:scroll_caret()`, but with *primary_pos* instead of -- `buffer.current_pos`. -- This is useful for scrolling search results into view. @@ -2122,7 +2118,7 @@ function scroll_to_start(buffer) end --- -- Anchors the position that `buffer:search_next()` and `buffer:search_prev()` --- begin at to the caret position. +-- start at to the caret position. -- @param buffer The buffer. function search_anchor(buffer) end @@ -2130,7 +2126,7 @@ function search_anchor(buffer) end -- 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. +-- occurrence, returning its position or `-1` if *text* was not found. -- @param buffer The buffer. -- @param text The text to search the target range for. -- @return number @@ -2139,8 +2135,8 @@ function search_in_target(buffer, text) end --- -- Searches for and selects the first occurrence of string *text* starting at --- the search anchor using search flags *flags*, returning the occurrence's --- position or `-1`. +-- the search anchor using search flags *flags*, returning that occurrence's +-- position or `-1` if *text* was not found. -- Selected text is not scrolled into view. -- @param buffer The buffer. -- @param flags The search flags to use. See `buffer.search_flags`. @@ -2151,8 +2147,8 @@ function search_next(buffer, flags, text) end --- -- Searches for and selects the last occurrence of string *text* before the --- search anchor using search flags *flags*, returning the occurrence's position --- or `-1`. +-- search anchor using search flags *flags*, returning that occurrence's +-- position or `-1` if *text* was not found. -- @param buffer The buffer. -- @param flags The search flags to use. See `buffer.search_flags`. -- @param text The text to search for. @@ -2166,8 +2162,8 @@ function search_prev(buffer, flags, text) end function select_all(buffer) end --- --- Duplicates the selected text to its right or the current line on a new line --- below. +-- Duplicates the selected text to its right. +-- If no text is selected, duplicates the current line on a new line below. -- @param buffer The buffer. function selection_duplicate(buffer) end @@ -2262,8 +2258,8 @@ function set_sel_fore(buffer, use_setting, color) end function set_selection(buffer, end_pos, start_pos) end --- --- Assigns the style of the next *length* characters, from the current styling --- position, to style number *style*, in the range from `0` to `255`, and +-- Assigns style number *style*, in the range from `0` to `255`, to the next +-- *length* characters, starting from the current styling position, and -- increments the styling position by *length*. -- @param buffer The buffer. -- @param length The number of characters to style. @@ -2277,15 +2273,15 @@ function set_styling(buffer, length, style) end function set_text(buffer, text) end --- --- Sets the visible policy bit-mask *visible_policy* to *visible_slop* number of --- lines away from the vertical margins when redisplaying hidden or folded lines --- using `buffer:ensure_visible_enforce_policy()`. +-- Defines scrolling policy bit-mask *policy* as the policy for keeping the +-- caret *y* number of lines away from the vertical margins as +-- `buffer:ensure_visible_enforce_policy()` redisplays hidden or folded lines. -- It is similar in operation to `buffer:set_y_caret_policy()`. -- @param buffer The buffer. --- @param visible_policy The combination of `buffer.VISIBLE_SLOP` and +-- @param policy The combination of `buffer.VISIBLE_SLOP` and -- `buffer.VISIBLE_STRICT` policy flags to set. --- @param visible_slop The slop value to use. -function set_visible_policy(buffer, visible_policy, visible_slop) end +-- @param y The number of lines from the vertical margins to keep the caret. +function set_visible_policy(buffer, policy, y) end --- -- Overrides the background color of whitespace with color *color*, in @@ -2303,26 +2299,25 @@ function set_whitespace_back(buffer, use_setting, color) end function set_whitespace_fore(buffer, use_setting, color) end --- --- Set the way the caret is kept visible when going sideways. --- The exclusion zone is given in pixels. +-- Defines scrolling policy bit-mask *policy* as the policy for keeping the +-- caret *x* number of pixels away from the horizontal margins. -- @param buffer The buffer. --- @param caret_policy The combination of `buffer.CARET_SLOP`, --- `buffer.CARET_STRICT`, `buffer.CARET_EVEN`, and `buffer.CARET_JUMPS` policy --- flags to set. --- @param caret_slop The slop value to use. -function set_x_caret_policy(buffer, caret_policy, caret_slop) end +-- @param policy The combination of `buffer.CARET_SLOP`, `buffer.CARET_STRICT`, +-- `buffer.CARET_EVEN`, and `buffer.CARET_JUMPS` policy flags to set. +-- @param x The number of pixels from the horizontal margins to keep the caret. +function set_x_caret_policy(buffer, policy, x) end --- --- Set the way the line the caret is on is kept visible. +-- Defines scrolling policy bit-mask *policy* as the policy for keeping the +-- caret *y* number of lines away from the vertical margins. -- @param buffer The buffer. --- @param caret_policy The combination of `buffer.CARET_SLOP`, --- `buffer.CARET_STRICT`, `buffer.CARET_EVEN`, and `buffer.CARET_JUMPS` policy --- flags to set. --- @param caret_slop The slop value to use. -function set_y_caret_policy(buffer, caret_policy, caret_slop) end +-- @param policy The combination of `buffer.CARET_SLOP`, `buffer.CARET_STRICT`, +-- `buffer.CARET_EVEN`, and `buffer.CARET_JUMPS` policy flags to set. +-- @param y The number of lines from the vertical margins to keep the caret. +function set_y_caret_policy(buffer, policy, y) end --- --- Shows the range of lines from line number *start_line* to *end_line*. +-- Shows the range of lines between line numbers *start_line* to *end_line*. -- This has no effect on fold levels or fold flags and the first line cannot be -- hidden. -- @param buffer The buffer. @@ -2364,7 +2359,7 @@ function stuttered_page_up(buffer) end function stuttered_page_up_extend(buffer) end --- --- Reverts all styles to have the same properties as `buffer.STYLE_DEFAULT`. +-- Reverts all styles to having the same properties as `buffer.STYLE_DEFAULT`. -- @param buffer The buffer. function style_clear_all(buffer) end @@ -2398,8 +2393,8 @@ function target_from_selection(buffer) end function text_height(buffer, line) end --- --- Returns the pixel width of string *text* styled with style number --- *style_num*, in the range of `0` to `255`. +-- Returns the pixel width string *text* would have when styled with style +-- number *style_num*, in the range of `0` to `255`. -- @param buffer The buffer. -- @param style_num The style number between `0` and `255` to use. -- @param text The text to measure the width of. @@ -2407,16 +2402,16 @@ function text_height(buffer, line) end function text_width(buffer, style_num, text) end --- --- Cycles between `buffer.caret_sticky` option settings `buffer.CARETSTICKY_ON`, --- `buffer.CARETSTICKY_WHITESPACE`, and `buffer.CARETSTICKY_OFF`. +-- Cycles between `buffer.caret_sticky` option settings `buffer.CARETSTICKY_ON` +-- and `buffer.CARETSTICKY_OFF`. -- @param buffer The buffer. -- @see caret_sticky function toggle_caret_sticky(buffer) end --- --- Toggles the fold point on line number *line* between expanded, where all of --- its child lines are displayed, and contracted, where all of its child lines --- are hidden. +-- Toggles the fold point on line number *line* between expanded (where all of +-- its child lines are displayed) and contracted (where all of its child lines +-- are hidden). -- @param buffer The buffer. -- @param line The line number in *buffer* to toggle the fold on. function toggle_fold(buffer, line) end @@ -2432,18 +2427,18 @@ function undo(buffer) end function upper_case(buffer) end --- --- Displays a user list identified by list identifier number *list_item* and --- constructed from string *item_list*, whose items are delimited by --- `buffer.auto_c_separator` characters. --- `buffer.auto_c_order`, the sorted order of *item_list*, must have already --- been defined. When the user selects an item, *list_type* is sent in a +-- Displays a user list identified by list identifier number *id* and +-- constructed from string *items* (whose items are delimited by +-- `buffer.auto_c_separator` characters). +-- The sorted order of *items* (`buffer.auto_c_order`) must have already been +-- defined. When the user selects an item, *id* is sent in a -- `USER_LIST_SELECTION` event along with the selection. -- @param buffer The buffer. --- @param list_type The list identifier number greater than zero to use. --- @param item_list The sorted string of words to show, separated by +-- @param id The list identifier number greater than zero to use. +-- @param items The sorted string of words to show, separated by -- `buffer.auto_c_separator` characters (initially spaces). -- @see _SCINTILLA.next_user_list_type -function user_list_show(buffer, list_type, item_list) end +function user_list_show(buffer, id, items) end --- -- Moves the caret to the first visible character on the current line or, if @@ -2659,8 +2654,9 @@ function new() end function text_range(buffer, start_pos, end_pos) end --- --- Returns the buffer's lexer name, or the name of the lexer under the caret in --- a multiple-language lexer if *current* is `true`. +-- Returns the buffer's lexer name. +-- If *current* is `true`, returns the name of the lexer under the caret in +-- a multiple-language lexer. -- @param buffer The buffer. -- @param current Whether or not to get the lexer at the current caret position -- in multi-language lexers. The default is `false` and returns the parent @@ -2669,7 +2665,7 @@ function get_lexer(buffer, current) end --- -- Associates lexer name *lexer* or the auto-detected lexer name with the buffer --- and then loads the appropriate language module if the module exists. +-- and then loads the appropriate language module if that module exists. -- @param buffer The buffer. -- @param lexer Optional string lexer name to set. If `nil`, attempts to -- auto-detect the buffer's lexer. @@ -2731,6 +2727,7 @@ function set_lexer(buffer, lexer) end -- * allocate_sub_styles+ -- * assign_cmd_key -- * can_paste +-- * change_lexer_state -- * char_position_from_point -- * char_position_from_point_close -- * clear_cmd_key diff --git a/core/.ui.dialogs.luadoc b/core/.ui.dialogs.luadoc index 68c33c3a..2ff99827 100644 --- a/core/.ui.dialogs.luadoc +++ b/core/.ui.dialogs.luadoc @@ -277,7 +277,7 @@ function filesave(options) end -- is `false`. -- * `focus_textbox`: Focus the textbox instead of the buttons. The default -- value is `false`. --- * `scroll_to`: Where to scroll the textbox text when it is not all visible. +-- * `scroll_to`: Where to scroll the textbox text. -- The available values are `"top"` and `"bottom"`. The default value is -- `"top"`. -- * `selected`: Select all of the textbox's text. The default value is diff --git a/core/.view.luadoc b/core/.view.luadoc index 7dbb0aca..f5db67a8 100644 --- a/core/.view.luadoc +++ b/core/.view.luadoc @@ -14,7 +14,7 @@ module('view') local buffer --- --- Splits the view into top and bottom views unless *vertical* is `true`, +-- Splits the view into top and bottom views (unless *vertical* is `true`), -- focuses the new view, and returns both the old and new views. -- If *vertical* is `false`, splits the view vertically into left and -- right views. diff --git a/core/events.lua b/core/events.lua index 20cb6cb9..53896cbe 100644 --- a/core/events.lua +++ b/core/events.lua @@ -34,13 +34,13 @@ local M = {} -- -- * _`uri`_: The UTF-8-encoded URI to open. -- @field AUTO_C_CHAR_DELETED (string) --- Emitted when deleting a character while the autocompletion or user list is +-- Emitted after deleting a character while an autocompletion or user list is -- active. -- @field AUTO_C_CANCELED (string) --- Emitted when canceling the autocompletion or user list. +-- Emitted when canceling an autocompletion or user list. -- @field AUTO_C_SELECTION (string) --- Emitted when selecting an item in the autocompletion list and before --- inserting the selection. +-- Emitted after selecting an item from an autocompletion list, but before +-- inserting that item into the buffer. -- Automatic insertion can be cancelled by calling -- [`buffer:auto_c_cancel()`][] before returning from the event handler. -- Arguments: @@ -85,15 +85,15 @@ local M = {} -- Arguments: -- -- * _`position`_: The position double-clicked. --- * _`line`_: The line number double-clicked. +-- * _`line`_: The line number of the position double-clicked. -- * _`modifiers`_: A bit-mask of any modifier keys used: `buffer.MOD_CTRL`, -- `buffer.MOD_SHIFT`, `buffer.MOD_ALT`, and `buffer.MOD_META`. -- Note: If you set `buffer.rectangular_selection_modifier` to -- `buffer.MOD_CTRL`, the "Control" modifier is reported as *both* "Control" -- and "Alt" due to a Scintilla limitation with GTK+. -- @field DWELL_END (string) --- Emitted after a `DWELL_START` when the user moves the mouse, presses a key, --- etc. +-- Emitted after `DWELL_START` when the user moves the mouse, presses a key, +-- or scrolls the view. -- Arguments: -- -- * _`position`_: The position closest to *x* and *y*. @@ -119,8 +119,8 @@ local M = {} -- * _`text`_: The text to search for. -- * _`next`_: Whether or not to search forward. -- @field HOTSPOT_CLICK (string) --- Emitted when clicking on text that is in a style with the hotspot attribute --- set. +-- Emitted when clicking on text that is in a style that has the hotspot +-- attribute set. -- Arguments: -- -- * _`position`_: The clicked text's position. @@ -130,8 +130,8 @@ local M = {} -- `buffer.MOD_CTRL`, the "Control" modifier is reported as *both* "Control" -- and "Alt" due to a Scintilla limitation with GTK+. -- @field HOTSPOT_DOUBLE_CLICK (string) --- Emitted when double-clicking on text that is in a style with the hotspot --- attribute set. +-- Emitted when double-clicking on text that is in a style that has the +-- hotspot attribute set. -- Arguments: -- -- * _`position`_: The double-clicked text's position. @@ -142,7 +142,7 @@ local M = {} -- and "Alt" due to a Scintilla limitation with GTK+. -- @field HOTSPOT_RELEASE_CLICK (string) -- Emitted when releasing the mouse after clicking on text that is in a style --- with the hotspot attribute set. +-- that has the hotspot attribute set. -- Arguments: -- -- * _`position`_: The clicked text's position. @@ -179,7 +179,7 @@ local M = {} -- Arguments: -- -- * _`margin`_: The margin number clicked. --- * _`position`_: The position of the start of the clicked margin's line. +-- * _`position`_: The beginning position of the clicked margin's line. -- * _`modifiers`_: A bit-mask of any modifier keys used: `buffer.MOD_CTRL`, -- `buffer.MOD_SHIFT`, `buffer.MOD_ALT`, and `buffer.MOD_META`. -- Note: If you set `buffer.rectangular_selection_modifier` to @@ -217,18 +217,17 @@ local M = {} -- @field SAVE_POINT_REACHED (string) -- Emitted after reaching a save point. -- @field UPDATE_UI (string) --- Emitted when buffer content, styling, selection, or scroll position --- changes. +-- Emitted after the view is visually updated. -- @field URI_DROPPED (string) -- Emitted after dragging and dropping a URI into a view. -- Arguments: -- -- * _`text`_: The UTF-8-encoded URI dropped. -- @field USER_LIST_SELECTION (string) --- Emitted after selecting an item in the user list. +-- Emitted after selecting an item in a user list. -- Arguments: -- --- * _`list_type`_: The *list_type* from [`buffer:user_list_show()`][]. +-- * _`id`_: The *id* from [`buffer:user_list_show()`][]. -- * _`text`_: The selection's text. -- * _`position`_: The position the list was displayed at. -- @field VIEW_NEW (string) @@ -259,8 +258,8 @@ local handlers = {} --- -- Adds function *f* to the set of event handlers for event *event* at position -- *index*. --- *event* may be any arbitrary string and does not need to have been previously --- defined. +-- If *index* not given, appends *f* to the set of handlers. *event* may be any +-- arbitrary string and does not need to have been previously defined. -- @param event The string event name. -- @param f The Lua function to connect to *event*. -- @param index Optional index to insert the handler into. diff --git a/core/file_io.lua b/core/file_io.lua index cf877a37..9abc3580 100644 --- a/core/file_io.lua +++ b/core/file_io.lua @@ -35,7 +35,7 @@ -- -- * _`filename`_: The filename externally modified. -- @field SNAPOPEN_MAX (number) --- The maximum number of files to list in the snapopen dialog. +-- The maximum number of files listed in the snapopen dialog. -- The default value is `1000`. module('io')]] @@ -340,7 +340,7 @@ events_connect(events.FILE_OPENED, function(filename) end) --- --- Prompts the user to select a recently opened file to reopen. +-- Prompts the user to select a recently opened file to be reopened. -- @see recent_files -- @name open_recent_file function io.open_recent_file() @@ -356,8 +356,8 @@ function io.open_recent_file() end --- --- Prompts the user to select files to open from *paths*, a string directory --- path or list of directory paths, using a filtered list dialog. +-- Prompts the user to select files to be opened from *paths*, a string +-- directory path or list of directory paths, using a filtered list dialog. -- Files shown in the dialog do not match any pattern in either string or table -- *filter* or, unless *exclude_FILTER* is `true`, in `lfs.FILTER`. A filter -- table contains Lua patterns that match filenames to exclude, an optional diff --git a/core/init.lua b/core/init.lua index b7429940..4d03bb01 100644 --- a/core/init.lua +++ b/core/init.lua @@ -21,17 +21,17 @@ if jit then module, package.searchers, bit32 = nil, package.loaders, bit end --- -- Extends Lua's _G table to provide extra functions and fields for Textadept. -- @field _HOME (string) --- The path to Textadept's home, or installation directory. +-- The path to Textadept's home, or installation, directory. -- @field _RELEASE (string) -- The Textadept release version string. -- @field _USERHOME (string) -- The path to the user's *~/.textadept/* directory, where all preferences and -- user-data is stored. -- On Windows machines *~/* is the value of the "USERHOME" environment --- variable, typically *C:\Users\username\\* or --- *C:\Documents and Settings\username\\*. On Linux, BSD, and Mac OSX --- machines *~/* is the value of "$HOME", typically */home/username/* and --- */Users/username/* respectively. +-- variable (typically *C:\Users\username\\* or +-- *C:\Documents and Settings\username\\*). On Linux, BSD, and Mac OSX +-- machines *~/* is the value of "$HOME" (typically */home/username/* and +-- */Users/username/* respectively). -- @field _CHARSET (string) -- The filesystem's character encoding. -- This is used when [working with files](io.html). @@ -113,9 +113,9 @@ local quit local reset --- --- Calls function *f* with the given arguments after number *interval* seconds --- and then repeatedly while *f* returns `true`. A `nil` or `false` return value --- stops repetition. +-- Calls function *f* with the given arguments after *interval* seconds. +-- If *f* returns `true`, calls *f* repeatedly every *interval* seconds as long +-- as *f* returns `true`. A `nil` or `false` return value stops repetition. -- @param interval The interval in seconds to call *f* after. -- @param f The function to call. -- @param ... Additional arguments to pass to *f*. diff --git a/core/locale.conf b/core/locale.conf index ab7ea05d..76ab5c39 100644 --- a/core/locale.conf +++ b/core/locale.conf @@ -35,7 +35,7 @@ File = File % core/gui.lua [Message Buffer] = [Message Buffer] -_OK = _Ok +_OK = _OK _Cancel = _Cancel Name = Name %File = File diff --git a/core/locales/locale.fr.conf b/core/locales/locale.fr.conf index 167a910b..69149204 100644 --- a/core/locales/locale.fr.conf +++ b/core/locales/locale.fr.conf @@ -36,7 +36,7 @@ File = Fichier % core/gui.lua [Message Buffer] = [Buffer des messages] -_OK = _Ok +_OK = _OK _Cancel = _Annuler Name = Nom %File = Fichier diff --git a/core/ui.lua b/core/ui.lua index 3d98acab..4cbdab4d 100644 --- a/core/ui.lua +++ b/core/ui.lua @@ -137,22 +137,23 @@ function ui.switch_buffer() end --- --- Switches to the buffer whose filename is *filename* in an existing view, --- otherwise splitting the current view if *split* is `true` or shifting to the --- next or *preferred_view* view instead of staying in the current one. --- *sloppy* indicates whether or not to only match the last part of *filename* --- to a buffer's `filename`. +-- Switches to the existing view whose buffer's filename is *filename*. +-- If no view was found and *split* is `true`, splits the current view in order +-- to show the requested file. If *split* is `false`, shifts to the next or +-- *preferred_view* view in order to show the requested file. If *sloppy* is +-- `true`, requires only the last part of *filename* to match a buffer's +-- `filename`. -- @param filename The filename of the buffer to go to. --- @param split Optional flag indicating whether or not to open the buffer in a --- split view if there is only one view. The default value is `false`. +-- @param split Optional flag that indicates whether or not to open the buffer +-- in a split view if there is only one view. The default value is `false`. -- @param preferred_view Optional view to open the desired buffer in if the -- buffer is not visible in any other view. --- @param sloppy Optional flag indicating whether or not to not match *filename* --- to `buffer.filename` exactly. When `true`, matches *filename* to only the --- last part of `buffer.filename` This is useful for run and compile commands --- which output relative filenames and paths instead of full ones and it is --- likely that the file in question is already open. The default value is --- `false`. +-- @param sloppy Optional flag that indicates whether or not to not match +-- *filename* to `buffer.filename` exactly. When `true`, matches *filename* to +-- only the last part of `buffer.filename` This is useful for run and compile +-- commands which output relative filenames and paths instead of full ones and +-- it is likely that the file in question is already open. The default value +-- is `false`. -- @name goto_file function ui.goto_file(filename, split, preferred_view, sloppy) local patt = '^'..filename..'$' @@ -177,7 +178,7 @@ function ui.goto_file(filename, split, preferred_view, sloppy) end --- --- Switches the editor theme to string *name* and optionally assigns the +-- Switches the editor theme to string *name* and (optionally) assigns the -- properties contained in table *props*. -- User themes override Textadept's default themes when they have the same name. -- If *name* contains slashes, it is assumed to be an absolute path to a theme @@ -406,12 +407,12 @@ The functions below are Lua C functions. local dialog --- --- Returns a split table containing Textadept's current split view structure. +-- Returns a split table that contains Textadept's current split view structure. -- This is primarily used in session saving. -- @return table of split views. Each split view entry is a table with 4 -- fields: `1`, `2`, `vertical`, and `size`. `1` and `2` have values of either -- nested split view entries or the views themselves; `vertical` is a flag --- indicating if the split is vertical or not; and `size` is the integer +-- that indicates if the split is vertical or not; and `size` is the integer -- position of the split resizer. -- @class function -- @name get_split_table @@ -423,7 +424,7 @@ local get_split_table -- view's index in `_G._VIEWS` instead of an absolute index. -- Emits `VIEW_BEFORE_SWITCH` and `VIEW_AFTER_SWITCH` events. -- @param n A relative or absolute view index in `_G._VIEWS`. --- @param relative Optional flag indicating whether *n* is a relative or +-- @param relative Optional flag that indicates whether *n* is a relative or -- absolute index. The default value is `false`, for an absolute index. -- @see _G._G._VIEWS -- @see events.VIEW_BEFORE_SWITCH |