Add documentation for new TextArea widget

docs/dev/Lua API.rst

@@ -5513,6 +5513,120 @@ The ``EditField`` class also provides the following functions:
 
   Inserts the given text at the current cursor position.
 
+TextArea class
+--------------
+
+Subclass of Panel; implements a multi-line text field with features such as
+text wrapping, mouse control, text selection, clipboard support, history,
+and typical text editor shortcuts.
+
+Attributes:
+
+* ``init_text``: 
+  The initial text content for the text area.
+
+* ``init_cursor``: 
+  The initial cursor position within the text content.
+
+* ``text_pen``: 
+  Optional pen used to draw the text.
+
+* ``select_pen``: 
+  Optional pen used for text selection.
+
+* ``ignore_keys``: 
+  List of input keys to ignore.
+  Functions similarly to the ``ignore_keys`` attribute in the ``EditField`` class.
+
+* ``on_text_change``: 
+  Callback function called whenever the text changes.
+  The function signature should be ``on_text_change(new_text)``.
+
+* ``on_cursor_change``: 
+  Callback function called whenever the cursor position changes.
+  The function signature should be ``on_cursor_change(new_cursor_pos)``.
+
+* ``one_line_mode``: 
+  Boolean attribute that, when set to ``true``, disables multi-line
+  text features and restricts the text area to a single line.
+
+Functions:
+
+* ``textarea:getText()``
+
+    Returns the current text content of the ``TextArea`` widget as a string.
+
+* ``textarea:setText(text)``
+
+    Sets the content of the ``TextArea`` to the specified string ``text``.
+    The cursor position will not be adjusted, so should be set separately.
+
+* ``textarea:getCursor()``
+
+    Returns the current cursor position within the text content.
+    The position is represented as a single integer, starting from 1.
+
+* ``textarea:setCursor(cursor)``
+
+    Sets the cursor position within the text content.
+
+* ``textarea:scrollToCursor()``
+
+    Scrolls the text area view to ensure that the current cursor position is visible.
+    This is useful for automatically scrolling when the user moves the cursor
+    beyond the visible region of the text area.
+
+Functionality:
+
+- Cursor Control: Navigate through text using arrow keys (Left, Right, Up,
+    and Down) for precise cursor placement.
+- Fast Rewind: Use :kbd:`Ctrl` + :kbd:`Left` and :kbd:`Ctrl` + :kbd:`Right` to
+    move the cursor one word back or forward.
+- Longest X Position Memory: The cursor remembers the longest x position when
+    moving up or down, making vertical navigation more intuitive.
+- Mouse Control: Use the mouse to position the cursor within the text,
+    providing an alternative to keyboard navigation.
+- New Lines: Easily insert new lines using the :kbd:`Enter` key, supporting
+    multiline text input.
+- Text Wrapping: Text automatically wraps within the editor, ensuring lines fit
+    within the display without manual adjustments.
+- Backspace Support: Use the backspace key to delete characters to the left of
+    the cursor.
+- Delete Character: :kbd:`Delete` deletes the character under the cursor.
+- Line Navigation: :kbd:`Home` moves the cursor to the beginning of the current
+    line, and :kbd:`End` moves it to the end.
+- Delete Current Line: :kbd:`Ctrl` + :kbd:`U` deletes the entire current line
+    where the cursor is located.
+- Delete Rest of Line: :kbd:`Ctrl` + :kbd:`K` deletes text from the cursor to
+    the end of the line.
+- Delete Last Word: :kbd:`Ctrl` + :kbd:`W` removes the word immediately before
+    the cursor.
+- Text Selection: Select text with the mouse, with support for replacing or
+    removing selected text.
+- Jump to Beginning/End: Quickly move the cursor to the beginning or end of the
+    text using :kbd:`Ctrl` + :kbd:`Home` and :kbd:`Ctrl` + :kbd:`End`.
+- Select Word/Line: Use double click to select current word, or triple click to
+    select current line
+- Select All: Select entire text by :kbd:`Ctrl` + :kbd:`A`
+- Undo/Redo: Undo/Redo changes by :kbd:`Ctrl` + :kbd:`Z` / :kbd:`Ctrl` +
+    :kbd:`Y`
+- Clipboard Operations: Perform OS clipboard cut, copy, and paste operations on
+    selected text, allowing you to paste the copied content into other
+    applications.
+- Copy Text: Use :kbd:`Ctrl` + :kbd:`C` to copy selected text.
+    - copy selected text, if available
+    - If no text is selected it copy the entire current line, including the
+      terminating newline if present.
+- Cut Text: Use :kbd:`Ctrl` + :kbd:`X` to cut selected text.
+    - cut selected text, if available
+    - If no text is selected it will cut the entire current line, including the
+      terminating newline if present
+- Paste Text: Use :kbd:`Ctrl` + :kbd:`V` to paste text from the clipboard into
+    the editor.
+    - replace selected text, if available
+    - If no text is selected, paste text in the cursor position
+- Scrolling behaviour for long text build-in
+
 Scrollbar class
 ---------------