Skip to content

Commit

Permalink
Merge pull request #4995 from wiktor-obrebski/widgets/text-area
Browse files Browse the repository at this point in the history
Widgets/text area
  • Loading branch information
myk002 authored Nov 28, 2024
2 parents 9e04b22 + c005846 commit 3aeb7e2
Show file tree
Hide file tree
Showing 7 changed files with 4,479 additions and 0 deletions.
149 changes: 149 additions & 0 deletions docs/dev/Lua API.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5513,6 +5513,155 @@ 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.

Cursor Behavior
~~~~~~~~~~~~~~~

The cursor in the ``TextArea`` class is index-based, starting from 1,
consistent with Lua's text indexing conventions.

Each character, including newlines (``string.char(10)``),
occupies a single index in the text content.

Cursor movement and position are fully aware of line breaks,
meaning they count as one unit in the offset.

The cursor always points to the position between characters,
with 1 being the position before the first character and
``#text + 1`` representing the position after the last character.

Cursor positions are preserved during text operations like insertion,
deletion, or replacement. If changes affect the cursor's position,
it will be adjusted to the nearest valid index.

TextArea Attributes:

* ``init_text``: The initial text content for the text area.

* ``init_cursor``: The initial cursor position within the text content.
If not specified, defaults to end of the text (length of ``init_text`` + 1).

* ``text_pen``: Optional pen used to draw the text. Default is ``COLOR_LIGHTCYAN``.

* ``select_pen``: Optional pen used for text selection. Default is ``COLOR_CYAN``.

* ``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, old_text)``.

* ``on_cursor_change``: Callback function called whenever the cursor position changes.
Expected function signature is ``on_cursor_change(new_cursor, old_cursor)``.

* ``one_line_mode``: If set to ``true``, disables multi-line text features.
In this mode the :kbd:`Enter` key is not handled by the widget
as if it were included in ``ignore_keys``.
If multiline text (including ``\n`` chars) is pasted into the widget, newlines are removed.

TextArea Functions:

* ``textarea:getText()``

Returns the current text content of the ``TextArea`` widget as a string.
"\n" characters (``string.char(10)``) should be interpreted as new lines

* ``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 happens automatically when the user interactively moves the cursor or
pastes text into the widget, but may need to be called when ``setCursor`` is
called programmatically.

* ``textarea:clearHistory()``

Clears undo/redo history of the widget.

Functionality
~~~~~~~~~~~~~

The TextArea widget provides a familiar and intuitive text editing experience with baseline features such as:

- Text Wrapping: Automatically fits text within the display area.
- Mouse and Keyboard Support: Standard keys like :kbd:`Home`, :kbd:`End`, :kbd:`Backspace`, and :kbd:`Delete` are supported,
along with gestures like double-click to select a word or triple-click to select a line.
- Clipboard Operations: copy, cut, and paste,
with intuitive defaults when no text is selected.
- Undo/Redo: :kbd:`Ctrl` + :kbd:`Z` and :kbd:`Ctrl` + :kbd:`Y` for quick changes.
- Additional features include advanced navigation, line management,
and smooth scrolling for handling long text efficiently.

Detailed list:

- Cursor Control: Navigate through text using arrow keys (Left, Right, Up,
and Down) for precise cursor placement.
- Mouse Control: Use the mouse to position the cursor within the text,
providing an alternative to keyboard navigation.
- Text Selection: Select text with the mouse, with support for replacing or
removing selected text.
- Select Word/Line: Use double click to select current word, or triple click to
select current line.
- Move By Word: Use :kbd:`Ctrl` + :kbd:`Left` and :kbd:`Ctrl` + :kbd:`Right` to
move the cursor one word back or forward.
- Line Navigation: :kbd:`Home` moves the cursor to the beginning of the current
line, and :kbd:`End` moves it to the end.
- 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`.
- Longest X Position Memory: The cursor remembers the longest x position when
moving up or down, making vertical navigation more intuitive.
- 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.
- Scrolling for long text entries.
- 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.
- 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.
- 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

Scrollbar class
---------------

Expand Down
1 change: 1 addition & 0 deletions library/lua/gui/widgets.lua
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ FilteredList = require('gui.widgets.filtered_list')
TabBar = require('gui.widgets.tab_bar')
RangeSlider = require('gui.widgets.range_slider')
DimensionsTooltip = require('gui.widgets.dimensions_tooltip')
TextArea = require('gui.widgets.text_area')

Tab = TabBar.Tab
makeButtonLabelText = Label.makeButtonLabelText
Expand Down
183 changes: 183 additions & 0 deletions library/lua/gui/widgets/text_area.lua
Original file line number Diff line number Diff line change
@@ -0,0 +1,183 @@
-- Multiline text area control

local Panel = require('gui.widgets.containers.panel')
local Scrollbar = require('gui.widgets.scrollbar')
local TextAreaContent = require('gui.widgets.text_area.text_area_content')
local HistoryStore = require('gui.widgets.text_area.history_store')

local HISTORY_ENTRY = HistoryStore.HISTORY_ENTRY

TextArea = defclass(TextArea, Panel)

TextArea.ATTRS{
init_text = '',
init_cursor = DEFAULT_NIL,
text_pen = COLOR_LIGHTCYAN,
ignore_keys = {},
select_pen = COLOR_CYAN,
on_text_change = DEFAULT_NIL,
on_cursor_change = DEFAULT_NIL,
one_line_mode = false,
debug = false
}

function TextArea:init()
self.render_start_line_y = 1

self.text_area = TextAreaContent{
frame={l=0,r=3,t=0},
text=self.init_text,

text_pen=self.text_pen,
ignore_keys=self.ignore_keys,
select_pen=self.select_pen,
debug=self.debug,
one_line_mode=self.one_line_mode,

on_text_change=function (text, old_text)
self:updateLayout()
if self.on_text_change then
self.on_text_change(text, old_text)
end
end,
on_cursor_change=self:callback('onCursorChange')
}
self.scrollbar = Scrollbar{
frame={r=0,t=1},
on_scroll=self:callback('onScrollbar'),
visible=not self.one_line_mode
}

self:addviews{
self.text_area,
self.scrollbar,
}
end

function TextArea:getText()
return self.text_area.text
end

function TextArea:setText(text)
self.text_area.history:store(
HISTORY_ENTRY.OTHER,
self:getText(),
self:getCursor()
)

return self.text_area:setText(text)
end

function TextArea:getCursor()
return self.text_area.cursor
end

function TextArea:setCursor(cursor_offset)
return self.text_area:setCursor(cursor_offset)
end

function TextArea:clearHistory()
return self.text_area.history:clear()
end

function TextArea:onCursorChange(cursor, old_cursor)
local x, y = self.text_area.wrapped_text:indexToCoords(
self.text_area.cursor
)

if y >= self.render_start_line_y + self.text_area.frame_body.height then
self:updateScrollbar(
y - self.text_area.frame_body.height + 1
)
elseif (y < self.render_start_line_y) then
self:updateScrollbar(y)
end

if self.on_cursor_change then
self.on_cursor_change(cursor, old_cursor)
end
end

function TextArea:scrollToCursor(cursor_offset)
if self.scrollbar.visible then
local _, cursor_line_y = self.text_area.wrapped_text:indexToCoords(
cursor_offset
)
self:updateScrollbar(cursor_line_y)
end
end

function TextArea:getPreferredFocusState()
return true
end

function TextArea:postUpdateLayout()
self:updateScrollbar(self.render_start_line_y)

if self.text_area.cursor == nil then
local cursor = self.init_cursor or #self.init_text + 1
self.text_area:setCursor(cursor)
self:scrollToCursor(cursor)
end
end

function TextArea:onScrollbar(scroll_spec)
local height = self.text_area.frame_body.height

local render_start_line = self.render_start_line_y
if scroll_spec == 'down_large' then
render_start_line = render_start_line + math.ceil(height / 2)
elseif scroll_spec == 'up_large' then
render_start_line = render_start_line - math.ceil(height / 2)
elseif scroll_spec == 'down_small' then
render_start_line = render_start_line + 1
elseif scroll_spec == 'up_small' then
render_start_line = render_start_line - 1
else
render_start_line = tonumber(scroll_spec)
end

self:updateScrollbar(render_start_line)
end

function TextArea:updateScrollbar(scrollbar_current_y)
local lines_count = #self.text_area.wrapped_text.lines

local render_start_line_y = math.min(
#self.text_area.wrapped_text.lines - self.text_area.frame_body.height + 1,
math.max(1, scrollbar_current_y)
)

self.scrollbar:update(
render_start_line_y,
self.frame_body.height,
lines_count
)

if (self.frame_body.height >= lines_count) then
render_start_line_y = 1
end

self.render_start_line_y = render_start_line_y
self.text_area:setRenderStartLineY(self.render_start_line_y)
end

function TextArea:renderSubviews(dc)
self.text_area.frame_body.y1 = self.frame_body.y1-(self.render_start_line_y - 1)
-- only visible lines of text_area will be rendered
TextArea.super.renderSubviews(self, dc)
end

function TextArea:onInput(keys)
if (self.scrollbar.is_dragging) then
return self.scrollbar:onInput(keys)
end

if keys._MOUSE_L and self:getMousePos() then
self:setFocus(true)
end

return TextArea.super.onInput(self, keys)
end

return TextArea
Loading

0 comments on commit 3aeb7e2

Please sign in to comment.