refactor: layout item type checks and add type hints to widgets (#644)

Co-authored-by: Eugenio Parodi <eugenio.parodi@sky.uk>
Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

Author: 3 people

.github/codeql/codeql-config.yml

@@ -7,3 +7,8 @@ paths-ignore:
   - '**/*.egg-info/**'
   - '**/__pycache__/**'
   - docs/source/_build/**
+
+query-filters:
+  # Suppress "Module-level cyclic import" findings.
+  - exclude:
+      id: py/cyclic-import

libs/pyTermTk/TermTk/TTkCore/constant.py

@@ -622,7 +622,7 @@ class ItemFlag(Flag):
         '''The user can interact with the item.'''
 
     # LayoutItem Types
-    class LayoutItemTypes(int):
+    class LayoutItemTypes(IntEnum):
         '''Types used internally in :mod:`~TermTk.TTkLayouts`
 
         .. autosummary::

libs/pyTermTk/TermTk/TTkLayouts/__init__.py

@@ -6,6 +6,7 @@
 
 Info and examples are available in the :ref:`Tutorial <Layout-Tutorial_Intro>`
 '''
+from .layoutitem import *
 from .layout     import *
 from .gridlayout import *
 from .boxlayout  import *

libs/pyTermTk/TermTk/TTkLayouts/boxlayout.py

@@ -27,10 +27,11 @@
 __all__ = ['TTkHBoxLayout', 'TTkVBoxLayout']
 
 from TermTk.TTkCore.constant import TTkK
-from TermTk.TTkLayouts.gridlayout import TTkGridLayout
+
+from .gridlayout import TTkGridLayout
 
 class TTkHBoxLayout(TTkGridLayout):
-    ''' The TTkHBoxLayout class lines up widgets horizontally
+    '''The :py:class:`TTkHBoxLayout` class lines up widgets horizontally.
 
     ::
 
@@ -47,7 +48,7 @@ class TTkHBoxLayout(TTkGridLayout):
     pass
 
 class TTkVBoxLayout(TTkGridLayout):
-    ''' The TTkVBoxLayout class lines up widgets vertically
+    '''The :py:class:`TTkVBoxLayout` class lines up widgets vertically.
 
     ::
 
@@ -63,10 +64,33 @@ class TTkVBoxLayout(TTkGridLayout):
          ╚═════════════════════════════╝
     '''
     def addItem(self, item):
+        '''Add a layout item on the next available vertical slot.
+
+        :param item: the item to be added
+        :type item: :py:class:`TTkLayoutItem`
+        '''
         TTkGridLayout.addItems(self, [item], direction=TTkK.VERTICAL)
+
     def addItems(self, items):
+        '''Add layout items stacked vertically.
+
+        :param items: the items to be added
+        :type items: list[:py:class:`TTkLayoutItem`]
+        '''
         TTkGridLayout.addItems(self,  items, direction=TTkK.VERTICAL)
+
     def addWidget(self, widget):
+        '''Add a widget on the next available vertical slot.
+
+        :param widget: the widget to be added
+        :type widget: :py:class:`TTkWidget`
+        '''
         TTkGridLayout.addWidgets(self, [widget], direction=TTkK.VERTICAL)
+
     def addWidgets(self, widgets):
+        '''Add widgets stacked vertically.
+
+        :param widgets: the widgets to be added
+        :type widgets: list[:py:class:`TTkWidget`]
+        '''
         TTkGridLayout.addWidgets(self,  widgets, direction=TTkK.VERTICAL)