diff options
Diffstat (limited to 'doc/classes/TextEdit.xml')
| -rw-r--r-- | doc/classes/TextEdit.xml | 200 |
1 files changed, 171 insertions, 29 deletions
diff --git a/doc/classes/TextEdit.xml b/doc/classes/TextEdit.xml index db0c1f17b0..75cad4d08b 100644 --- a/doc/classes/TextEdit.xml +++ b/doc/classes/TextEdit.xml @@ -5,7 +5,7 @@ </brief_description> <description> A multiline text editor. It also has limited facilities for editing code, such as syntax highlighting support. For more advanced facilities for editing code, see [CodeEdit]. - [b]Note:[/b] Most viewport, caret and edit methods contain a [code]caret_index[/code] argument for [member caret_multiple] support. The argument should be one of the following: [code]-1[/code] for all carets, [code]0[/code] for the main caret, or greater than [code]0[/code] for secondary carets. + [b]Note:[/b] Most viewport, caret, and edit methods contain a [code]caret_index[/code] argument for [member caret_multiple] support. The argument should be one of the following: [code]-1[/code] for all carets, [code]0[/code] for the main caret, or greater than [code]0[/code] for secondary carets in the order they were created. [b]Note:[/b] When holding down [kbd]Alt[/kbd], the vertical scroll wheel will scroll 5 times as fast as it would normally do. This also works in the Godot script editor. </description> <tutorials> @@ -58,7 +58,7 @@ <method name="add_caret"> <return type="int" /> <param index="0" name="line" type="int" /> - <param index="1" name="col" type="int" /> + <param index="1" name="column" type="int" /> <description> Adds a new caret at the given location. Returns the index of the new caret, or [code]-1[/code] if the location is invalid. </description> @@ -67,7 +67,7 @@ <return type="void" /> <param index="0" name="below" type="bool" /> <description> - Adds an additional caret above or below every caret. If [param below] is true the new caret will be added below and above otherwise. + Adds an additional caret above or below every caret. If [param below] is [code]true[/code] the new caret will be added below and above otherwise. </description> </method> <method name="add_gutter"> @@ -83,7 +83,7 @@ Adds a selection and a caret for the next occurrence of the current selection. If there is no active selection, selects word under caret. </description> </method> - <method name="adjust_carets_after_edit"> + <method name="adjust_carets_after_edit" deprecated="No longer necessary since methods now adjust carets themselves."> <return type="void" /> <param index="0" name="caret" type="int" /> <param index="1" name="from_line" type="int" /> @@ -91,7 +91,7 @@ <param index="3" name="to_line" type="int" /> <param index="4" name="to_col" type="int" /> <description> - Reposition the carets affected by the edit. This assumes edits are applied in edit order, see [method get_caret_index_edit_order]. + This method does nothing. </description> </method> <method name="adjust_viewport_to_caret"> @@ -120,6 +120,23 @@ Starts a multipart edit. All edits will be treated as one action until [method end_complex_operation] is called. </description> </method> + <method name="begin_multicaret_edit"> + <return type="void" /> + <description> + Starts an edit for multiple carets. The edit must be ended with [method end_multicaret_edit]. Multicaret edits can be used to edit text at multiple carets and delay merging the carets until the end, so the caret indexes aren't affected immediately. [method begin_multicaret_edit] and [method end_multicaret_edit] can be nested, and the merge will happen at the last [method end_multicaret_edit]. + Example usage: + [codeblock] + begin_complex_operation() + begin_multicaret_edit() + for i in range(get_caret_count()): + if multicaret_edit_ignore_caret(i): + continue + # Logic here. + end_multicaret_edit() + end_complex_operation() + [/codeblock] + </description> + </method> <method name="cancel_ime"> <return type="void" /> <description> @@ -145,6 +162,20 @@ Clears the undo history. </description> </method> + <method name="collapse_carets"> + <return type="void" /> + <param index="0" name="from_line" type="int" /> + <param index="1" name="from_column" type="int" /> + <param index="2" name="to_line" type="int" /> + <param index="3" name="to_column" type="int" /> + <param index="4" name="inclusive" type="bool" default="false" /> + <description> + Collapse all carets in the given range to the [param from_line] and [param from_column] position. + [param inclusive] applies to both ends. + If [method is_in_mulitcaret_edit] is [code]true[/code], carets that are collapsed will be [code]true[/code] for [method multicaret_edit_ignore_caret]. + [method merge_overlapping_carets] will be called if any carets were collapsed. + </description> + </method> <method name="copy"> <return type="void" /> <param index="0" name="caret_index" type="int" default="-1" /> @@ -185,6 +216,12 @@ Ends a multipart edit, started with [method begin_complex_operation]. If called outside a complex operation, the current operation is pushed onto the undo/redo stack. </description> </method> + <method name="end_multicaret_edit"> + <return type="void" /> + <description> + Ends an edit for multiple carets, that was started with [method begin_multicaret_edit]. If this was the last [method end_multicaret_edit] and [method merge_overlapping_carets] was called, carets will be merged. + </description> + </method> <method name="get_caret_column" qualifiers="const"> <return type="int" /> <param index="0" name="caret_index" type="int" default="0" /> @@ -205,7 +242,7 @@ Returns the caret pixel draw position. </description> </method> - <method name="get_caret_index_edit_order"> + <method name="get_caret_index_edit_order" deprecated="Carets no longer need to be edited in any specific order. If the carets need to be sorted, use [method get_sorted_carets] instead."> <return type="PackedInt32Array" /> <description> Returns a list of caret indexes in their edit order, this done from bottom to top. Edit order refers to the way actions such as [method insert_text_at_caret] are applied. @@ -363,6 +400,15 @@ [b]Note:[/b] The return value is influenced by [theme_item line_spacing] and [theme_item font_size]. And it will not be less than [code]1[/code]. </description> </method> + <method name="get_line_ranges_from_carets" qualifiers="const"> + <return type="Vector2i[]" /> + <param index="0" name="only_selections" type="bool" default="false" /> + <param index="1" name="merge_adjacent" type="bool" default="true" /> + <description> + Returns an [Array] of line ranges where [code]x[/code] is the first line and [code]y[/code] is the last line. All lines within these ranges will have a caret on them or be part of a selection. Each line will only be part of one line range, even if it has multiple carets on it. + If a selection's end column ([method get_selection_to_column]) is at column [code]0[/code], that line will not be included. If a selection begins on the line after another selection ends and [param merge_adjacent] is [code]true[/code], or they begin and end on the same line, one line range will include both selections. + </description> + </method> <method name="get_line_width" qualifiers="const"> <return type="int" /> <param index="0" name="line" type="int" /> @@ -514,7 +560,18 @@ Returns the text inside the selection of a caret, or all the carets if [param caret_index] is its default value [code]-1[/code]. </description> </method> - <method name="get_selection_column" qualifiers="const"> + <method name="get_selection_at_line_column" qualifiers="const"> + <return type="int" /> + <param index="0" name="line" type="int" /> + <param index="1" name="column" type="int" /> + <param index="2" name="include_edges" type="bool" default="true" /> + <param index="3" name="only_selections" type="bool" default="true" /> + <description> + Returns the caret index of the selection at the given [param line] and [param column], or [code]-1[/code] if there is none. + If [param include_edges] is [code]false[/code], the position must be inside the selection and not at either end. If [param only_selections] is [code]false[/code], carets without a selection will also be considered. + </description> + </method> + <method name="get_selection_column" qualifiers="const" deprecated="Use [method get_selection_origin_column] instead."> <return type="int" /> <param index="0" name="caret_index" type="int" default="0" /> <description> @@ -525,17 +582,17 @@ <return type="int" /> <param index="0" name="caret_index" type="int" default="0" /> <description> - Returns the selection begin column. + Returns the selection begin column. Returns the caret column if there is no selection. </description> </method> <method name="get_selection_from_line" qualifiers="const"> <return type="int" /> <param index="0" name="caret_index" type="int" default="0" /> <description> - Returns the selection begin line. + Returns the selection begin line. Returns the caret line if there is no selection. </description> </method> - <method name="get_selection_line" qualifiers="const"> + <method name="get_selection_line" qualifiers="const" deprecated="Use [method get_selection_origin_line] instead."> <return type="int" /> <param index="0" name="caret_index" type="int" default="0" /> <description> @@ -548,18 +605,40 @@ Returns the current selection mode. </description> </method> + <method name="get_selection_origin_column" qualifiers="const"> + <return type="int" /> + <param index="0" name="caret_index" type="int" default="0" /> + <description> + Returns the origin column of the selection. This is the opposite end from the caret. + </description> + </method> + <method name="get_selection_origin_line" qualifiers="const"> + <return type="int" /> + <param index="0" name="caret_index" type="int" default="0" /> + <description> + Returns the origin line of the selection. This is the opposite end from the caret. + </description> + </method> <method name="get_selection_to_column" qualifiers="const"> <return type="int" /> <param index="0" name="caret_index" type="int" default="0" /> <description> - Returns the selection end column. + Returns the selection end column. Returns the caret column if there is no selection. </description> </method> <method name="get_selection_to_line" qualifiers="const"> <return type="int" /> <param index="0" name="caret_index" type="int" default="0" /> <description> - Returns the selection end line. + Returns the selection end line. Returns the caret line if there is no selection. + </description> + </method> + <method name="get_sorted_carets" qualifiers="const"> + <return type="PackedInt32Array" /> + <param index="0" name="include_ignored_carets" type="bool" default="false" /> + <description> + Returns the carets sorted by selection beginning from lowest line and column to highest (from top to bottom of text). + If [param include_ignored_carets] is [code]false[/code], carets from [method multicaret_edit_ignore_caret] will be ignored. </description> </method> <method name="get_tab_size" qualifiers="const"> @@ -653,6 +732,19 @@ Inserts a new line with [param text] at [param line]. </description> </method> + <method name="insert_text"> + <return type="void" /> + <param index="0" name="text" type="String" /> + <param index="1" name="line" type="int" /> + <param index="2" name="column" type="int" /> + <param index="3" name="before_selection_begin" type="bool" default="true" /> + <param index="4" name="before_selection_end" type="bool" default="false" /> + <description> + Inserts the [param text] at [param line] and [param column]. + If [param before_selection_begin] is [code]true[/code], carets and selections that begin at [param line] and [param column] will moved to the end of the inserted text, along with all carets after it. + If [param before_selection_end] is [code]true[/code], selections that end at [param line] and [param column] will be extended to the end of the inserted text. These parameters can be used to insert text inside of or outside of selections. + </description> + </method> <method name="insert_text_at_caret"> <return type="void" /> <param index="0" name="text" type="String" /> @@ -661,6 +753,13 @@ Insert the specified text at the caret position. </description> </method> + <method name="is_caret_after_selection_origin" qualifiers="const"> + <return type="bool" /> + <param index="0" name="caret_index" type="int" default="0" /> + <description> + Returns [code]true[/code] if the caret of the selection is after the selection origin. This can be used to determine the direction of the selection. + </description> + </method> <method name="is_caret_visible" qualifiers="const"> <return type="bool" /> <param index="0" name="caret_index" type="int" default="0" /> @@ -671,7 +770,7 @@ <method name="is_dragging_cursor" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if the user is dragging their mouse for scrolling or selecting. + Returns [code]true[/code] if the user is dragging their mouse for scrolling, selecting, or text dragging. </description> </method> <method name="is_gutter_clickable" qualifiers="const"> @@ -695,6 +794,12 @@ Returns whether the gutter is overwritable. </description> </method> + <method name="is_in_mulitcaret_edit" qualifiers="const"> + <return type="bool" /> + <description> + Returns [code]true[/code] if a [method begin_multicaret_edit] has been called and [method end_multicaret_edit] has not yet been called. + </description> + </method> <method name="is_line_gutter_clickable" qualifiers="const"> <return type="bool" /> <param index="0" name="line" type="int" /> @@ -749,9 +854,18 @@ <return type="void" /> <description> Merges any overlapping carets. Will favor the newest caret, or the caret with a selection. + If [method is_in_mulitcaret_edit] is [code]true[/code], the merge will be queued to happen at the end of the multicaret edit. See [method begin_multicaret_edit] and [method end_multicaret_edit]. [b]Note:[/b] This is not called when a caret changes position but after certain actions, so it is possible to get into a state where carets overlap. </description> </method> + <method name="multicaret_edit_ignore_caret" qualifiers="const"> + <return type="bool" /> + <param index="0" name="caret_index" type="int" /> + <description> + Returns [code]true[/code] if the given [param caret_index] should be ignored as part of a multicaret edit. See [method begin_multicaret_edit] and [method end_multicaret_edit]. Carets that should be ignored are ones that were part of removed text and will likely be merged at the end of the edit, or carets that were added during the edit. + It is recommended to [code]continue[/code] within a loop iterating on multiple carets if a caret should be ignored. + </description> + </method> <method name="paste"> <return type="void" /> <param index="0" name="caret_index" type="int" default="-1" /> @@ -787,6 +901,15 @@ Removes the gutter from this [TextEdit]. </description> </method> + <method name="remove_line_at"> + <return type="void" /> + <param index="0" name="line" type="int" /> + <param index="1" name="move_carets_down" type="bool" default="true" /> + <description> + Removes the line of text at [param line]. Carets on this line will attempt to match their previous visual x position. + If [param move_carets_down] is [code]true[/code] carets will move to the next line down, otherwise carets will move up. + </description> + </method> <method name="remove_secondary_carets"> <return type="void" /> <description> @@ -801,7 +924,6 @@ <param index="3" name="to_column" type="int" /> <description> Removes text between the given positions. - [b]Note:[/b] This does not adjust the caret or selection, which as a result it can end up in an invalid position. </description> </method> <method name="search" qualifiers="const"> @@ -809,7 +931,7 @@ <param index="0" name="text" type="String" /> <param index="1" name="flags" type="int" /> <param index="2" name="from_line" type="int" /> - <param index="3" name="from_colum" type="int" /> + <param index="3" name="from_column" type="int" /> <description> Perform a search inside the text. Search flags can be specified in the [enum SearchFlags] enum. In the returned vector, [code]x[/code] is the column, [code]y[/code] is the line. If no results are found, both are equal to [code]-1[/code]. @@ -835,14 +957,15 @@ </method> <method name="select"> <return type="void" /> - <param index="0" name="from_line" type="int" /> - <param index="1" name="from_column" type="int" /> - <param index="2" name="to_line" type="int" /> - <param index="3" name="to_column" type="int" /> + <param index="0" name="origin_line" type="int" /> + <param index="1" name="origin_column" type="int" /> + <param index="2" name="caret_line" type="int" /> + <param index="3" name="caret_column" type="int" /> <param index="4" name="caret_index" type="int" default="0" /> <description> - Perform selection, from line/column to line/column. + Selects text from [param origin_line] and [param origin_column] to [param caret_line] and [param caret_column] for the given [param caret_index]. This moves the selection origin and the caret. If the positions are the same, the selection will be deselected. If [member selecting_enabled] is [code]false[/code], no selection will occur. + [b]Note:[/b] If supporting multiple carets this will not check for any overlap. See [method merge_overlapping_carets]. </description> </method> <method name="select_all"> @@ -878,9 +1001,10 @@ <param index="3" name="wrap_index" type="int" default="0" /> <param index="4" name="caret_index" type="int" default="0" /> <description> - Moves the caret to the specified [param line] index. + Moves the caret to the specified [param line] index. The caret column will be moved to the same visual position it was at the last time [method set_caret_column] was called, or clamped to the end of the line. If [param adjust_viewport] is [code]true[/code], the viewport will center at the caret position after the move occurs. If [param can_be_hidden] is [code]true[/code], the specified [param line] can be hidden. + If [param wrap_index] is [code]-1[/code], the caret column will be clamped to the [param line]'s length. If [param wrap_index] is greater than [code]-1[/code], the column will be moved to attempt to match the visual x position on the line's [param wrap_index] to the position from the last time [method set_caret_column] was called. [b]Note:[/b] If supporting multiple carets this will not check for any overlap. See [method merge_overlapping_carets]. </description> </method> @@ -945,7 +1069,8 @@ <param index="0" name="line" type="int" /> <param index="1" name="new_text" type="String" /> <description> - Sets the text for a specific line. + Sets the text for a specific [param line]. + Carets on the line will attempt to keep their visual x position. </description> </method> <method name="set_line_as_center_visible"> @@ -1049,13 +1174,30 @@ <method name="set_selection_mode"> <return type="void" /> <param index="0" name="mode" type="int" enum="TextEdit.SelectionMode" /> - <param index="1" name="line" type="int" default="-1" /> - <param index="2" name="column" type="int" default="-1" /> - <param index="3" name="caret_index" type="int" default="0" /> <description> Sets the current selection mode. </description> </method> + <method name="set_selection_origin_column"> + <return type="void" /> + <param index="0" name="column" type="int" /> + <param index="1" name="caret_index" type="int" default="0" /> + <description> + Sets the selection origin column to the [param column] for the given [param caret_index]. If the selection origin is moved to the caret position, the selection will deselect. + </description> + </method> + <method name="set_selection_origin_line"> + <return type="void" /> + <param index="0" name="line" type="int" /> + <param index="1" name="can_be_hidden" type="bool" default="true" /> + <param index="2" name="wrap_index" type="int" default="-1" /> + <param index="3" name="caret_index" type="int" default="0" /> + <description> + Sets the selection origin line to the [param line] for the given [param caret_index]. If the selection origin is moved to the caret position, the selection will deselect. + If [param can_be_hidden] is [code]false[/code], The line will be set to the nearest unhidden line below or above. + If [param wrap_index] is [code]-1[/code], the selection origin column will be clamped to the [param line]'s length. If [param wrap_index] is greater than [code]-1[/code], the column will be moved to attempt to match the visual x position on the line's [param wrap_index] to the position from the last time [method set_selection_origin_column] or [method select] was called. + </description> + </method> <method name="set_tab_size"> <return type="void" /> <param index="0" name="size" type="int" /> @@ -1089,7 +1231,7 @@ <param index="0" name="from_line" type="int" /> <param index="1" name="to_line" type="int" /> <description> - Swaps the two lines. + Swaps the two lines. Carets will be swapped with the lines. </description> </method> <method name="tag_saved_version"> @@ -1140,7 +1282,7 @@ If [code]true[/code], the selected text will be deselected when focus is lost. </member> <member name="drag_and_drop_selection_enabled" type="bool" setter="set_drag_and_drop_selection_enabled" getter="is_drag_and_drop_selection_enabled" default="true"> - If [code]true[/code], allow drag and drop of selected text. + If [code]true[/code], allow drag and drop of selected text. Text can still be dropped from other sources. </member> <member name="draw_control_chars" type="bool" setter="set_draw_control_chars" getter="get_draw_control_chars" default="false"> If [code]true[/code], control characters are displayed. @@ -1172,7 +1314,7 @@ [b]Note:[/b] This method is only implemented on Linux. </member> <member name="minimap_draw" type="bool" setter="set_draw_minimap" getter="is_drawing_minimap" default="false"> - If [code]true[/code], a minimap is shown, providing an outline of your source code. + If [code]true[/code], a minimap is shown, providing an outline of your source code. The minimap uses a fixed-width text size. </member> <member name="minimap_width" type="int" setter="set_minimap_width" getter="get_minimap_width" default="80"> The width, in pixels, of the minimap. @@ -1231,7 +1373,7 @@ <signals> <signal name="caret_changed"> <description> - Emitted when the caret changes position. + Emitted when any caret changes position. </description> </signal> <signal name="gutter_added"> |