chore(textedit): add fastwrap (#615)

Co-authored-by: Copilot <copilot@github.com>

Author: ceccopierangiolieugenio

demo/showcase/_showcasehelper.py

@@ -71,7 +71,7 @@ def getUtfColoredWords(n):
     www = [random.choice(utfwords) for _ in range(n)]
     return ttk.TTkString(" ".join(www), randColor())
 def getUtfColoredSentence(a,b):
-    return ttk.TTkString(" ").join([getUtfColoredWords(random.randint(1,4)) for _ in range(0,random.randint(a,b))])
+    return ttk.TTkString(" ").join([getUtfColoredWords(random.randint(1,8)) for _ in range(0,random.randint(a,b))])
 
 def main():
     root = ttk.TTk()

docs/MDNotes/internals/textedit.md

@@ -0,0 +1,7 @@
+# Elements
+
+```
+TTkTextEdit <- TTkTextEditView <- TTkTextWrap <- TTkTextDocument
+                     \                             /
+                      \---- TTkTextCursor <-------/
+```

libs/pyTermTk/TermTk/TTkCore/constant.py

@@ -371,8 +371,8 @@ class WrapEngine(Enum):
         '''No Wrapping'''
         FullWrap = auto()
         '''Full document Wrap at any change, Ideal for small documents (~300 Lines) [Precise] (Slow)'''
-        # FastWrap = auto()
-        # '''Chunk based document Wrap, Default wrap [Fast] (Scrolling position is estimated)'''
+        FastWrap = auto()
+        '''Chunk based document Wrap, Default wrap [Fast] (Scrolling position is estimated)'''
         VimWrap = auto()
         '''Wrap applied only in the displayed area, [Fastest] (the scrolling is snap to the beginning of the lines)'''
 

libs/pyTermTk/TermTk/TTkGui/TTkTextWrap/text_wrap.py

@@ -29,15 +29,15 @@
 from TermTk.TTkCore.signal import pyTTkSignal, pyTTkSlot
 from TermTk.TTkGui.textdocument import TTkTextDocument
 
-from .text_wrap_data import _RetScreenRows, _WrapState, _ReWrapData
+from .text_wrap_data import _RetScreenPositions, _RetScreenRows, _WrapState, _ReWrapData
 from .text_wrap_engine import _WrapEngine_Interface
 from .text_wrap_engine_no_wrap import _WrapEngine_NoWrap
 from .text_wrap_engine_vim_wrap import _WrapEngine_VimWrap
 from .text_wrap_engine_fast_wrap import _WrapEngine_FastWrap
 from .text_wrap_engine_full_wrap import _WrapEngine_FullWrap
 
 _wrapEngines = {
-    # TTkK.WrapEngine.FastWrap : _WrapEngine_FastWrap,
+    TTkK.WrapEngine.FastWrap : _WrapEngine_FastWrap,
     TTkK.WrapEngine.FullWrap : _WrapEngine_FullWrap,
     TTkK.WrapEngine.VimWrap : _WrapEngine_VimWrap,
     TTkK.WrapEngine.NoWrap : _WrapEngine_NoWrap,
@@ -101,7 +101,8 @@ def setEngine(self, engine:TTkK.WrapEngine, width:Optional[int]=None) -> None:
 
         :param engine: engine selector from :py:class:`TTkK.WrapEngine`.
         :type engine: :py:class:`TTkK.WrapEngine`
-        :param width: optional wrap width applied before switching engines.
+        :param width: optional wrap width applied before switching engines
+            when the engine type actually changes.
         :type width: Optional[int]
         '''
         engine_class = _wrapEngines.get(engine, _WrapEngine_NoWrap)
@@ -171,10 +172,10 @@ def screenRows(self, y:int, h:int) -> _RetScreenRows:
         :type h: int
 
         :return: wrapped row slices.
-        :rtype: List[:py:class:`_WrapLine`]
+        :rtype: :py:class:`_RetScreenRows`
         '''
         if h <= 0:
-            return _RetScreenRows(y=y, rows=[])
+            return _RetScreenRows(rows=[])
         return self._wrapEngine.screenRows(y=y,h=h)
 
     def rewrap(self) -> None:
@@ -186,15 +187,15 @@ def rewrap(self) -> None:
         self._wrapEngine.rewrap()
         self.wrapChanged.emit()
 
-    def dataToScreenPosition(self, line:int, pos:int) -> Tuple[int, int]:
+    def dataToScreenPosition(self, line:int, pos:int) -> _RetScreenPositions:
         '''Map a document position to wrapped screen coordinates.
 
         :param line: logical line index.
         :type line: int
         :param pos: character position in the logical line.
         :type pos: int
-        :return: ``(x, y)`` wrapped screen coordinates.
-        :rtype: Tuple[int, int]
+        :return: wrapped screen coordinates.
+        :rtype: :py:class:`_RetScreenPositions`
         '''
         return self._wrapEngine.dataToScreenPosition(line=line, pos=pos)
 

libs/pyTermTk/TermTk/TTkGui/TTkTextWrap/text_wrap_data.py

@@ -23,7 +23,7 @@
 __all__:list = []
 
 from dataclasses import dataclass
-from typing import List
+from typing import List, Optional, Tuple
 
 from TermTk.TTkCore.constant import TTkK
 
@@ -54,11 +54,15 @@ class _WrapLine():
     :type start: int
     :param stop: exclusive stop character offset in the source line.
     :type stop: int
+    :param last_slice: ``True`` when this fragment is the final wrapped slice
+        for :py:attr:`line`, ``False`` otherwise.
+    :type last_slice: bool
     '''
-    __slots__ = ('line', 'start', 'stop')
+    __slots__ = ('line', 'start', 'stop', 'last_slice')
     line:int
     start: int
     stop:int
+    last_slice:bool
 
 
 @dataclass
@@ -82,5 +86,17 @@ class _WrapState():
 
 @dataclass
 class _RetScreenRows():
-    y:int
     rows: List[_WrapLine]
+
+@dataclass
+class _RetScreenPosition():
+    x: int
+    y: int
+    def to_xy(self) -> Tuple[int,int]:
+        return self.x, self.y
+@dataclass
+class _RetScreenPositions():
+    main: _RetScreenPosition
+    extra: Optional[_RetScreenPosition] = None
+    def to_xy(self) -> Tuple[int,int]:
+        return self.main.to_xy()

libs/pyTermTk/TermTk/TTkGui/TTkTextWrap/text_wrap_engine.py

@@ -28,7 +28,7 @@
 from TermTk.TTkCore.constant import TTkK
 from TermTk.TTkCore.string import TTkString
 
-from .text_wrap_data import _RetScreenRows, _WrapLine, _WrapState, _ReWrapData
+from .text_wrap_data import _RetScreenPosition, _RetScreenPositions, _RetScreenRows, _WrapLine, _WrapState, _ReWrapData
 
 class _WrapEngine_Interface():
     '''Base interface for text wrap engines.
@@ -41,8 +41,8 @@ class _WrapEngine_Interface():
       :py:attr:`TTkTextDocument.contentsChange` signal.
     * :py:class:`_WrapEngine_VimWrap` -- lazily wraps only the visible window,
       caching the last viewport for coordinate conversions.
-    * :py:class:`_WrapEngine_FastWrap` -- placeholder for a future incremental
-      wrapping strategy.
+        * :py:class:`_WrapEngine_FastWrap` -- chunk-based lazy wrapping strategy
+            for large documents.
     '''
     __slots__ = ('_wrapState')
 
@@ -77,10 +77,13 @@ def rewrap(self, data: Optional[_ReWrapData]=None) -> None:
         :py:class:`_WrapEngine_FullWrap`) rebuild it here; engines
         that wrap lazily (e.g. :py:class:`_WrapEngine_NoWrap`,
         :py:class:`_WrapEngine_VimWrap`) may be a no-op.
+
+        :param data: optional incremental change descriptor.
+        :type data: Optional[:py:class:`_ReWrapData`]
         '''
         raise NotImplementedError()
 
-    def dataToScreenPosition(self, line:int, pos:int) -> Tuple[int, int]:
+    def dataToScreenPosition(self, line:int, pos:int) -> _RetScreenPositions:
         '''Map a document position to wrapped screen coordinates.
 
         Converts a logical ``(line, pos)`` pair in the source document
@@ -92,9 +95,9 @@ def dataToScreenPosition(self, line:int, pos:int) -> Tuple[int, int]:
         :param pos: character offset within the document line.
         :type pos: int
 
-        :return: ``(x, y)`` screen coordinates where *x* is the
-                 terminal-cell column and *y* is the wrapped row index.
-        :rtype: Tuple[int, int]
+        :return: wrapped screen coordinates where *main.x* is the
+             terminal-cell column and *main.y* is the wrapped row index.
+        :rtype: :py:class:`_RetScreenPositions`
         '''
         raise NotImplementedError()
 
@@ -144,8 +147,8 @@ def screenRows(self, y:int, h:int) -> _RetScreenRows:
         :param h: number of rows to retrieve.
         :type h: int
 
-        :return: list of wrapped row descriptors.
-        :rtype: List[:py:class:`_WrapLine`]
+        :return: wrapped row descriptors.
+        :rtype: :py:class:`_RetScreenRows`
         '''
         raise NotImplementedError()
 
@@ -188,12 +191,12 @@ def _wrapLine(self, _w:int, _i:int, _l:TTkString) -> List[_WrapLine]:
         wordWrapMode = self._wrapState.wordWrapMode
         fr = 0
         if not len(_l): # if the line is empty append it
-            ret.append(_WrapLine(_i,0,0))
+            ret.append(_WrapLine(_i,0,0,True))
             return ret
         while len(_l):
             to = _l.tabCharPos(_w, tabSpaces)
             if to >= len(_l):
-                ret.append(_WrapLine(_i,fr,fr+len(_l)+1))
+                ret.append(_WrapLine(_i,fr,fr+len(_l)+1,True))
                 return ret
             to = max(1,to)
             if wordWrapMode == TTkK.WordWrap: # Find the index of the first white space
@@ -202,7 +205,9 @@ def _wrapLine(self, _w:int, _i:int, _l:TTkString) -> List[_WrapLine]:
                 while newTo and ( s[newTo] != ' ' and s[newTo] != '\t' ): newTo-=1
                 if newTo: to = newTo
 
-            ret.append(_WrapLine(_i,fr,fr+to))
+            ret.append(_WrapLine(_i,fr,fr+to,False))
             _l = _l.substring(to)
             fr += to
+        if ret:
+            ret[-1].last_slice=True
         return ret