chore: improve typing (#562)

Author: ceccopierangiolieugenio

libs/pyTermTk/TermTk/TTkAbstract/abstractscrollarea.py

@@ -23,14 +23,15 @@
 __all__ = ['TTkAbstractScrollArea']
 
 from dataclasses import dataclass
-from typing import List,Any,Type
+from typing import List,Any,Type,Optional
 
 from TermTk.TTkCore.constant import TTkK
 # from TermTk.TTkCore.log import TTkLog
 from TermTk.TTkCore.signal import pyTTkSlot
 from TermTk.TTkWidgets.widget import TTkWidget
 from TermTk.TTkWidgets.container import TTkContainer
 from TermTk.TTkWidgets.scrollbar import TTkScrollBar
+from TermTk.TTkLayouts.layout import TTkLayout
 from TermTk.TTkLayouts.gridlayout import TTkGridLayout
 from TermTk.TTkAbstract.abstractscrollview import TTkAbstractScrollViewInterface
 
@@ -42,12 +43,25 @@ class _ForwardData():
     methods: List[str]
 
 class TTkAbstractScrollArea(TTkContainer):
+    '''
+    The :py:class:`TTkAbstractScrollArea` provides a scrolling area with on-demand scroll bars.
+
+    This abstract class manages vertical and horizontal scroll bars that appear automatically
+    based on the viewport size and content.
+    '''
     __slots__ = (
         '_processing', # this flag is required to avoid unnecessary loop on edge cases
         '_viewport',
         '_verticalScrollBar',   '_verticalScrollBarPolicy',
         '_horizontalScrollBar', '_horizontalScrollBarPolicy',)
 
+    _processing:bool
+    _viewport:Optional[TTkAbstractScrollViewInterface]
+    _verticalScrollBar:TTkScrollBar
+    _horizontalScrollBar:TTkScrollBar
+    _verticalScrollBarPolicy:TTkK.ScrollBarPolicy
+    _horizontalScrollBarPolicy:TTkK.ScrollBarPolicy
+
     def __init__(self, *,
                  verticalScrollBarPolicy:TTkK.ScrollBarPolicy=TTkK.ScrollBarPolicy.ScrollBarAsNeeded,
                  horizontalScrollBarPolicy:TTkK.ScrollBarPolicy=TTkK.ScrollBarPolicy.ScrollBarAsNeeded,
@@ -63,8 +77,10 @@ def __init__(self, *,
         self.layout().addWidget(self._verticalScrollBar)
         self.layout().addWidget(self._horizontalScrollBar)
 
-    def _resizeEvent(self):
-        if self._processing: return
+    def _resizeEvent(self) -> None:
+        ''' Internal method to handle resize events and reposition scroll bars '''
+        if self._processing:
+            return
         self._processing = True
         w,h = self.size()
         vert = 1 if self._verticalScrollBar.isVisible() else 0
@@ -73,16 +89,24 @@ def _resizeEvent(self):
             self._verticalScrollBar.setGeometry(w-1,0,1,h-hori)
         if hori:
             self._horizontalScrollBar.setGeometry(0,h-1,w-vert,1)
-        if self._viewport:
+        if isinstance(self._viewport, (TTkWidget, TTkLayout)):
             self._viewport.setGeometry(0,0,w-vert,h-hori)
         self._processing = False
 
-    def resizeEvent(self, w: int, h: int):
+    def resizeEvent(self, w: int, h: int) -> None:
+        ''' Handle resize events
+
+        :param w: the new width
+        :type w: int
+        :param h: the new height
+        :type h: int
+        '''
         self._resizeEvent()
 
     @pyTTkSlot()
-    def _viewportChanged(self):
-        if not self.isVisible(): return
+    def _viewportChanged(self) -> None:
+        ''' Internal slot to handle viewport changes and update scroll bar ranges and visibility '''
+        if not self._viewport or not self.isVisible(): return
         w,h = self.size()
         fw, fh = self._viewport.viewFullAreaSize()
         dw, dh = self._viewport.viewDisplayedSize()
@@ -125,16 +149,37 @@ def _viewportChanged(self):
         self._resizeEvent()
 
     @pyTTkSlot(int)
-    def _vscrollMoved(self, val):
+    def _vscrollMoved(self, val: int) -> None:
+        ''' Internal slot to handle vertical scroll bar movement
+
+        :param val: the new vertical scroll position
+        :type val: int
+        '''
+        if not self._viewport:
+            return
         ox, _ = self._viewport.getViewOffsets()
         self._viewport.viewMoveTo(ox, val)
 
     @pyTTkSlot(int)
-    def _hscrollMoved(self, val):
+    def _hscrollMoved(self, val: int) -> None:
+        ''' Internal slot to handle horizontal scroll bar movement
+
+        :param val: the new horizontal scroll position
+        :type val: int
+        '''
+        if not self._viewport:
+            return
         _, oy = self._viewport.getViewOffsets()
         self._viewport.viewMoveTo(val, oy)
 
-    def setViewport(self, viewport):
+    def setViewport(self, viewport: TTkAbstractScrollViewInterface) -> None:
+        ''' Set the viewport widget
+
+        :param viewport: the viewport widget implementing TTkAbstractScrollViewInterface
+        :type viewport: :py:class:`TTkAbstractScrollViewInterface`
+
+        :raises TypeError: if viewport does not implement TTkAbstractScrollViewInterface
+        '''
         if not isinstance(viewport, TTkAbstractScrollViewInterface):
             raise TypeError("TTkAbstractScrollViewInterface is required in TTkAbstractScrollArea.setVewport(viewport)")
         if self._viewport:
@@ -157,20 +202,44 @@ def setViewport(self, viewport):
             self.layout().addItem(viewport)
         self._resizeEvent()
 
-    def setVerticalScrollBarPolicy(self, policy):
+    def setVerticalScrollBarPolicy(self, policy: TTkK.ScrollBarPolicy) -> None:
+        ''' Set the vertical scroll bar policy
+
+        :param policy: the scroll bar policy (ScrollBarAsNeeded, ScrollBarAlwaysOn, ScrollBarAlwaysOff)
+        :type policy: :py:class:`TTkK.ScrollBarPolicy`
+        '''
         if policy != self._verticalScrollBarPolicy:
             self._verticalScrollBarPolicy = policy
             self._viewportChanged()
 
-    def setHorizontalScrollBarPolicy(self, policy):
+    def setHorizontalScrollBarPolicy(self, policy: TTkK.ScrollBarPolicy) -> None:
+        ''' Set the horizontal scroll bar policy
+
+        :param policy: the scroll bar policy (ScrollBarAsNeeded, ScrollBarAlwaysOn, ScrollBarAlwaysOff)
+        :type policy: :py:class:`TTkK.ScrollBarPolicy`
+        '''
         if policy != self._horizontalScrollBarPolicy:
             self._horizontalScrollBarPolicy = policy
             self._viewportChanged()
 
-    def viewport(self) -> TTkAbstractScrollViewInterface:
+    def viewport(self) -> Optional[TTkAbstractScrollViewInterface]:
+        ''' Return the current viewport
+
+        :return: the viewport widget or None
+        :rtype: :py:class:`TTkAbstractScrollViewInterface`, optional
+        '''
         return self._viewport
 
-    def update(self, repaint=True, updateLayout=False, updateParent=False):
-        if self._viewport:
+    def update(self, repaint: bool = True, updateLayout: bool = False, updateParent: bool = False) -> None:
+        ''' Update the scroll area and viewport
+
+        :param repaint: trigger a repaint, defaults to True
+        :type repaint: bool, optional
+        :param updateLayout: trigger a layout update, defaults to False
+        :type updateLayout: bool, optional
+        :param updateParent: trigger a parent update, defaults to False
+        :type updateParent: bool, optional
+        '''
+        if isinstance(self._viewport, (TTkWidget, TTkLayout)):
             self._viewport.update(repaint, updateLayout, updateParent=False)
         return super().update(repaint, updateLayout, updateParent)