summaryrefslogtreecommitdiff
path: root/doc/classes
diff options
context:
space:
mode:
authorRémi Verschelde <rverschelde@gmail.com>2022-10-06 08:56:34 +0200
committerRémi Verschelde <rverschelde@gmail.com>2022-10-06 08:56:34 +0200
commitf5903215d01c649567926a23249341a4232f49cf (patch)
treeb64948ceeec48433fc5cd78561b237a5c77239af /doc/classes
parente541f05c62944d8604cf44fecceb2006e2c2383e (diff)
parent5f8f4842bb08227f31cecc50cfac86d504703205 (diff)
Merge pull request #61902 from Paulb23/multi-caret
Add Multi-caret support to TextEdit
Diffstat (limited to 'doc/classes')
-rw-r--r--doc/classes/TextEdit.xml128
1 files changed, 127 insertions, 1 deletions
diff --git a/doc/classes/TextEdit.xml b/doc/classes/TextEdit.xml
index 0905c0c20b..2f9b971fc8 100644
--- a/doc/classes/TextEdit.xml
+++ b/doc/classes/TextEdit.xml
@@ -5,6 +5,7 @@
</brief_description>
<description>
TextEdit is meant for editing large, multiline text. It also has facilities for editing code, such as syntax highlighting support and multiple levels of undo/redo.
+ [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] 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>
@@ -12,18 +13,21 @@
<methods>
<method name="_backspace" qualifiers="virtual">
<return type="void" />
+ <param index="0" name="caret_index" type="int" />
<description>
Override this method to define what happens when the user presses the backspace key.
</description>
</method>
<method name="_copy" qualifiers="virtual">
<return type="void" />
+ <param index="0" name="caret_index" type="int" />
<description>
Override this method to define what happens when the user performs a copy operation.
</description>
</method>
<method name="_cut" qualifiers="virtual">
<return type="void" />
+ <param index="0" name="caret_index" type="int" />
<description>
Override this method to define what happens when the user performs a cut operation.
</description>
@@ -31,23 +35,34 @@
<method name="_handle_unicode_input" qualifiers="virtual">
<return type="void" />
<param index="0" name="unicode_char" type="int" />
+ <param index="1" name="caret_index" type="int" />
<description>
Override this method to define what happens when the user types in the provided key [param unicode_char].
</description>
</method>
<method name="_paste" qualifiers="virtual">
<return type="void" />
+ <param index="0" name="caret_index" type="int" />
<description>
Override this method to define what happens when the user performs a paste operation.
</description>
</method>
<method name="_paste_primary_clipboard" qualifiers="virtual">
<return type="void" />
+ <param index="0" name="caret_index" type="int" />
<description>
Override this method to define what happens when the user performs a paste operation with middle mouse button.
[b]Note:[/b] This method is only implemented on Linux.
</description>
</method>
+ <method name="add_caret">
+ <return type="int" />
+ <param index="0" name="line" type="int" />
+ <param index="1" name="col" 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>
+ </method>
<method name="add_gutter">
<return type="void" />
<param index="0" name="at" type="int" default="-1" />
@@ -55,14 +70,27 @@
Register a new gutter to this [TextEdit]. Use [param at] to have a specific gutter order. A value of [code]-1[/code] appends the gutter to the right.
</description>
</method>
+ <method name="adjust_carets_after_edit">
+ <return type="void" />
+ <param index="0" name="caret" type="int" />
+ <param index="1" name="from_line" type="int" />
+ <param index="2" name="from_col" type="int" />
+ <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].
+ </description>
+ </method>
<method name="adjust_viewport_to_caret">
<return type="void" />
+ <param index="0" name="caret_index" type="int" default="0" />
<description>
Adjust the viewport so the caret is visible.
</description>
</method>
<method name="backspace">
<return type="void" />
+ <param index="0" name="caret_index" type="int" default="-1" />
<description>
Called when the user presses the backspace key. Can be overridden with [method _backspace].
</description>
@@ -75,6 +103,7 @@
</method>
<method name="center_viewport_to_caret">
<return type="void" />
+ <param index="0" name="caret_index" type="int" default="0" />
<description>
Centers the viewport on the line the editing caret is at. This also resets the [member scroll_horizontal] value to [code]0[/code].
</description>
@@ -93,28 +122,38 @@
</method>
<method name="copy">
<return type="void" />
+ <param index="0" name="caret_index" type="int" default="-1" />
<description>
Copies the current text selection. Can be overridden with [method _copy].
</description>
</method>
<method name="cut">
<return type="void" />
+ <param index="0" name="caret_index" type="int" default="-1" />
<description>
Cut's the current selection. Can be overridden with [method _cut].
</description>
</method>
<method name="delete_selection">
<return type="void" />
+ <param index="0" name="caret_index" type="int" default="-1" />
<description>
Deletes the selected text.
</description>
</method>
<method name="deselect">
<return type="void" />
+ <param index="0" name="caret_index" type="int" default="-1" />
<description>
Deselects the current selection.
</description>
</method>
+ <method name="end_action">
+ <return type="void" />
+ <description>
+ Marks the end of steps in the current action started with [method start_action].
+ </description>
+ </method>
<method name="end_complex_operation">
<return type="void" />
<description>
@@ -123,24 +162,40 @@
</method>
<method name="get_caret_column" qualifiers="const">
<return type="int" />
+ <param index="0" name="caret_index" type="int" default="0" />
<description>
Returns the column the editing caret is at.
</description>
</method>
+ <method name="get_caret_count" qualifiers="const">
+ <return type="int" />
+ <description>
+ Returns the number of carets in this [TextEdit].
+ </description>
+ </method>
<method name="get_caret_draw_pos" qualifiers="const">
<return type="Vector2" />
+ <param index="0" name="caret_index" type="int" default="0" />
<description>
Returns the caret pixel draw position.
</description>
</method>
+ <method name="get_caret_index_edit_order">
+ <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.
+ </description>
+ </method>
<method name="get_caret_line" qualifiers="const">
<return type="int" />
+ <param index="0" name="caret_index" type="int" default="0" />
<description>
Returns the line the editing caret is on.
</description>
</method>
<method name="get_caret_wrap_index" qualifiers="const">
<return type="int" />
+ <param index="0" name="caret_index" type="int" default="0" />
<description>
Returns the wrap index the editing caret is on.
</description>
@@ -381,32 +436,37 @@
Returns the scroll position for [param wrap_index] of [param line].
</description>
</method>
- <method name="get_selected_text" qualifiers="const">
+ <method name="get_selected_text">
<return type="String" />
+ <param index="0" name="caret_index" type="int" default="-1" />
<description>
Returns the text inside the selection.
</description>
</method>
<method name="get_selection_column" qualifiers="const">
<return type="int" />
+ <param index="0" name="caret_index" type="int" default="0" />
<description>
Returns the original start column of the selection.
</description>
</method>
<method name="get_selection_from_column" qualifiers="const">
<return type="int" />
+ <param index="0" name="caret_index" type="int" default="0" />
<description>
Returns the selection begin column.
</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.
</description>
</method>
<method name="get_selection_line" qualifiers="const">
<return type="int" />
+ <param index="0" name="caret_index" type="int" default="0" />
<description>
Returns the original start line of the selection.
</description>
@@ -419,12 +479,14 @@
</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.
</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.
</description>
@@ -476,6 +538,7 @@
</method>
<method name="get_word_under_caret" qualifiers="const">
<return type="String" />
+ <param index="0" name="caret_index" type="int" default="-1" />
<description>
Returns a [String] text with the word under the caret's location.
</description>
@@ -494,6 +557,7 @@
</method>
<method name="has_selection" qualifiers="const">
<return type="bool" />
+ <param index="0" name="caret_index" type="int" default="-1" />
<description>
Returns [code]true[/code] if the user has selected text.
</description>
@@ -515,12 +579,14 @@
<method name="insert_text_at_caret">
<return type="void" />
<param index="0" name="text" type="String" />
+ <param index="1" name="caret_index" type="int" default="-1" />
<description>
Insert the specified text at the caret position.
</description>
</method>
<method name="is_caret_visible" qualifiers="const">
<return type="bool" />
+ <param index="0" name="caret_index" type="int" default="0" />
<description>
Returns [code]true[/code] if the caret is visible on the screen.
</description>
@@ -576,6 +642,7 @@
<method name="is_mouse_over_selection" qualifiers="const">
<return type="bool" />
<param index="0" name="edges" type="bool" />
+ <param index="1" name="caret_index" type="int" default="-1" />
<description>
Returns whether the mouse is over selection. If [param edges] is [code]true[/code], the edges are considered part of the selection.
</description>
@@ -601,18 +668,41 @@
Merge the gutters from [param from_line] into [param to_line]. Only overwritable gutters will be copied.
</description>
</method>
+ <method name="merge_overlapping_carets">
+ <return type="void" />
+ <description>
+ Merges any overlapping carets. Will favour the newest caret, or the caret with a selection.
+ [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="paste">
<return type="void" />
+ <param index="0" name="caret_index" type="int" default="-1" />
<description>
Paste at the current location. Can be overridden with [method _paste].
</description>
</method>
+ <method name="paste_primary_clipboard">
+ <return type="void" />
+ <param index="0" name="caret_index" type="int" default="-1" />
+ <description>
+ Pastes the primary clipboard.
+ </description>
+ </method>
<method name="redo">
<return type="void" />
<description>
Perform redo operation.
</description>
</method>
+ <method name="remove_caret">
+ <return type="void" />
+ <param index="0" name="caret" type="int" />
+ <description>
+ Removes the given caret index.
+ [b]Note:[/b] This can result in adjustment of all other caret indices.
+ </description>
+ </method>
<method name="remove_gutter">
<return type="void" />
<param index="0" name="gutter" type="int" />
@@ -620,6 +710,12 @@
Removes the gutter from this [TextEdit].
</description>
</method>
+ <method name="remove_secondary_carets">
+ <return type="void" />
+ <description>
+ Removes all additional carets.
+ </description>
+ </method>
<method name="remove_text">
<return type="void" />
<param index="0" name="from_line" type="int" />
@@ -666,6 +762,7 @@
<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="caret_index" type="int" default="0" />
<description>
Perform selection, from line/column to line/column.
If [member selecting_enabled] is [code]false[/code], no selection will occur.
@@ -680,6 +777,7 @@
</method>
<method name="select_word_under_caret">
<return type="void" />
+ <param index="0" name="caret_index" type="int" default="-1" />
<description>
Selects the word under the caret.
</description>
@@ -688,9 +786,11 @@
<return type="void" />
<param index="0" name="column" type="int" />
<param index="1" name="adjust_viewport" type="bool" default="true" />
+ <param index="2" name="caret_index" type="int" default="0" />
<description>
Moves the caret to the specified [param column] index.
If [param adjust_viewport] is [code]true[/code], the viewport will center at the caret position after the move occurs.
+ [b]Note:[/b] If supporting multiple carets this will not check for any overlap. See [method merge_overlapping_carets].
</description>
</method>
<method name="set_caret_line">
@@ -699,10 +799,12 @@
<param index="1" name="adjust_viewport" type="bool" default="true" />
<param index="2" name="can_be_hidden" type="bool" default="true" />
<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.
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 [code]line[/code] can be hidden.
+ [b]Note:[/b] If supporting multiple carets this will not check for any overlap. See [method merge_overlapping_carets].
</description>
</method>
<method name="set_gutter_clickable">
@@ -872,6 +974,7 @@
<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>
@@ -890,6 +993,14 @@
Provide custom tooltip text. The callback method must take the following args: [code]hovered_word: String[/code]
</description>
</method>
+ <method name="start_action">
+ <return type="void" />
+ <param index="0" name="action" type="int" enum="TextEdit.EditAction" />
+ <description>
+ Starts an action, will end the current action if [code]action[/code] is different.
+ An action will also end after a call to [method end_action], after [member ProjectSettings.gui/timers/text_edit_idle_detect_sec] is triggered or a new undoable step outside the [method start_action] and [method end_action] calls.
+ </description>
+ </method>
<method name="swap_lines">
<return type="void" />
<param index="0" name="from_line" type="int" />
@@ -926,6 +1037,9 @@
If [code]true[/code], a right-click moves the caret at the mouse position before displaying the context menu.
If [code]false[/code], the context menu disregards mouse location.
</member>
+ <member name="caret_multiple" type="bool" setter="set_multiple_carets_enabled" getter="is_multiple_carets_enabled" default="true">
+ Sets if multiple carets are allowed.
+ </member>
<member name="caret_type" type="int" setter="set_caret_type" getter="get_caret_type" enum="TextEdit.CaretType" default="0">
Set the type of caret to draw.
</member>
@@ -1154,6 +1268,18 @@
<constant name="MENU_MAX" value="28" enum="MenuItems">
Represents the size of the [enum MenuItems] enum.
</constant>
+ <constant name="ACTION_NONE" value="0" enum="EditAction">
+ No current action.
+ </constant>
+ <constant name="ACTION_TYPING" value="1" enum="EditAction">
+ A typing action.
+ </constant>
+ <constant name="ACTION_BACKSPACE" value="2" enum="EditAction">
+ A backwards delete action.
+ </constant>
+ <constant name="ACTION_DELETE" value="3" enum="EditAction">
+ A forward delete action.
+ </constant>
<constant name="SEARCH_MATCH_CASE" value="1" enum="SearchFlags">
Match case when searching.
</constant>