feat: add Date and Time widgets (#501)

Author: ceccopierangiolieugenio

.github/copilot-instructions.md

@@ -0,0 +1,186 @@
+# pyTermTk Copilot Instructions
+
+## Project Overview
+
+pyTermTk is a Text-based User Interface (TUI) library for Python inspired by Qt5, GTK, and tkinter APIs. It creates cross-platform terminal applications with rich widgets, layouts, and an event-driven architecture.
+
+## Architecture
+
+### Core Structure
+- **`libs/pyTermTk/TermTk/`** - Main library code organized into logical modules:
+  - `TTkCore/` - Core functionality (signals, colors, canvas, configuration)
+  - `TTkWidgets/` - All UI widgets inherit from `TTkWidget` base class
+  - `TTkLayouts/` - Layout managers (GridLayout, HBoxLayout, VBoxLayout)
+  - `TTkGui/` - GUI components (drag & drop, application management)
+  - `TTkTemplates/` - Mixin classes for event handling (`TKeyEvents`, `TMouseEvents`, `TDragEvents`)
+
+### Widget Inheritance Pattern
+All widgets follow this pattern:
+```python
+class TTkMyWidget(TTkWidget):  # Or TTkContainer for composite widgets
+    # Class-level styling
+    classStyle = {
+        'default':  {'color': TTkColor.fg("#dddd88"), 'borderColor': TTkColor.RST},
+        'hover':    {'color': TTkColor.fg("#ffffff"), 'borderColor': TTkColor.BOLD},
+        'focus':    {'borderColor': TTkColor.fg("#ffff00")},
+        'disabled': {'color': TTkColor.fg('#888888')}
+    }
+
+    # Signal declarations
+    mySignal: pyTTkSignal
+
+    __slots__ = ('_private_vars',)  # Always use slots for performance
+
+    def __init__(self, **kwargs):
+        self.mySignal = pyTTkSignal(int)  # Define signals in __init__
+        super().__init__(**kwargs|{'size': (w, h)})  # Merge kwargs, set default size
+```
+
+### Signal-Slot System (Qt-inspired)
+Use type-safe signal-slot patterns:
+```python
+# Define signals with types
+signal = pyTTkSignal(int)
+# Define slots with decorators
+@pyTTkSlot(int)
+def my_slot(value: int):
+    pass
+# Connect them
+signal.connect(my_slot)
+```
+
+### Event Handling
+Widgets handle events by overriding template methods:
+- `keyEvent()`, `mousePressEvent()`, `paintEvent()` - Core events
+- `focusInEvent()`, `focusOutEvent()` - Focus management
+- `dropEvent()`, `dragEnterEvent()` - Drag & drop
+- Always return `True` if event is handled, `False` to propagate
+
+## Development Workflows
+
+### Testing
+- **Unit tests**: `pytest tests/pytest/` (run via Makefile: `make test`)
+- **Performance tests**: `tests/timeit/` - Contains signal/slot benchmarks and optimization tests
+- **Manual tests**: `tests/t.*/` - Interactive UI tests
+- **CI**: Tests run on Python 3.9-3.14 with flake8 linting
+
+### Build & Deploy
+- **Local build**: `pip install -e libs/pyTermTk` (uses `pip`)
+- **Documentation**: `make doc` (Sphinx-based, outputs to `docs/source/_build/html/`)
+- **Apps deployment**: Individual apps in `apps/` have their own `pyproject.toml`
+
+### Running Examples
+- **Demo**: `python demo/demo.py -f`
+- **Designer**: `pip install -e apps/ttkDesigner ; ttkDesigner`
+- **Individual tests**: `python tests/t.ui/test.ui.036.datetime.01.py`
+
+## Project-Specific Patterns
+
+### Widget State Management
+Many widgets use internal state classes (see `datetime_date_form.py`):
+```python
+class _TTkWidgetState:
+    __slots__ = ('_data', 'signal_name')
+    def __init__(self):
+        self.signal_name = pyTTkSignal()
+```
+
+### File Organization
+- One widget per file in `TTkWidgets/`
+- Use `__all__ = ['ClassName']` exports
+- Import from `TermTk.TTkCore`, `TermTk.TTkWidgets` etc (not relative imports)
+- Apps in `apps/` are self-contained with `pyproject.toml`
+
+### Color & Theming
+Use `TTkColor` constants and theme system:
+```python
+TTkColor.fg("#ffffff") + TTkColor.bg("#000044") + TTkColor.BOLD
+style = self.currentStyle()  # Get theme-aware colors
+```
+
+### Cross-Platform Considerations
+- Platform-specific code in `TTkCore/drivers/`
+- Terminal compatibility testing in `tests/ansi.images.json`
+- HTML5 export capabilities via `tools/webExporter/`
+
+### Documentation & Docstrings
+Use **Sphinx-compatible docstring format** with Epytext-style field lists:
+```python
+def setGeometry(self, x: int, y: int, width: int, height: int):
+    ''' Resize and move the widget
+
+    :param x: the horizontal position
+    :type x: int
+    :param y: the vertical position
+    :type y: int
+    :param width: the new width
+    :type width: int
+    :param height: the new height
+    :type height: int
+    '''
+
+# For class/module docstrings include ASCII art examples:
+class TTkButton(TTkWidget):
+    ''' TTkButton:
+
+    Border = True
+    ::
+
+         ┌────────┐
+         │  Text  │
+         ╘════════╛
+
+    Demo: `formwidgets.py <https://github.com/ceccopierangiolieugenio/pyTermTk/blob/main/demo/showcase/formwidgets.py>`_
+    '''
+
+# For signals, document parameters:
+toggled:pyTTkSignal
+'''
+This signal is emitted whenever the button state changes if checkeable,
+i.e., whenever the user checks or unchecks it.
+
+:param checked: True if checked otherwise False
+:type checked: bool
+'''
+```
+
+**Key conventions**:
+- Use single quotes `'''` for docstrings
+- Include ASCII art for visual widgets showing borders/layout
+- Link to demo files with full GitHub URLs
+- Use `:py:class:` for cross-references to other classes
+- Document all parameters with `:param name:` and `:type name:`
+- Include `:return:` and `:rtype:` for non-void methods
+- Signal docstrings document emitted parameters, not the signal itself
+
+## Apps Ecosystem
+The project includes several full applications demonstrating patterns:
+- **ttkDesigner** - Visual UI designer (like Qt Designer)
+- **ttkode** - Code editor with syntax highlighting
+- **dumbPaintTool** - ASCII art editor
+- **tlogg** - Log file viewer
+
+### Testing App Integration
+Apps use the main library via path manipulation:
+```python
+sys.path.append(os.path.join(sys.path[0],'../../libs/pyTermTk'))
+import TermTk as ttk
+```
+
+## Key Integration Points
+
+### Layout System
+Use Qt-like layout managers:
+```python
+layout = TTkGridLayout()
+layout.addWidget(widget, row, col, rowspan, colspan)
+container.setLayout(layout)
+```
+
+### Focus & Input Handling
+Set focus policy and handle keyboard navigation:
+```python
+self.setFocusPolicy(TTkK.ClickFocus | TTkK.TabFocus)
+```
+
+When implementing new widgets, study existing patterns in `TTkWidgets/` and ensure signal-slot integration follows the established type-safe patterns shown in `tests/pytest/test_004_signals_slots.py`.

demo/demo.py

@@ -54,6 +54,7 @@
 from  showcase.dndtabs       import demoDnDTabs
 from  showcase.sigmask       import demoSigmask
 from  showcase.apptemplate   import demoAppTemplate
+from  showcase.datetime      import demoDateTimePicker
 
 def stupidPythonHighlighter(txt):
     def _colorize(regex, txt, color):
@@ -181,9 +182,10 @@ def demoShowcase(root=None, border=True):
 
     listMenu.addItem(f"Pickers")
     tabPickers = ttk.TTkTabWidget(parent=mainFrame, border=False, visible=False)
-    tabPickers.addTab(demoFilePicker(),  " File Picker ",  'showcase/filepicker.py')
-    tabPickers.addTab(demoColorPicker(), " Color Picker ", 'showcase/colorpicker.py')
-    tabPickers.addTab(demoTextPicker(), " Text Picker ",  'showcase/textpicker.py')
+    tabPickers.addTab(demoFilePicker(),     " File Picker ",     'showcase/filepicker.py')
+    tabPickers.addTab(demoColorPicker(),    " Color Picker ",    'showcase/colorpicker.py')
+    tabPickers.addTab(demoTextPicker(),     " Text Picker ",     'showcase/textpicker.py')
+    tabPickers.addTab(demoDateTimePicker(), " DateTime Picker ", 'showcase/datetime.py')
     tabPickers.addMenu("sources", ttk.TTkK.RIGHT, tabPickers).menuButtonClicked.connect(lambda _menuButton : showSource(_menuButton.data().currentData()))
 
     listMenu.addItem(f"Graphs")

demo/showcase/datetime.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+
+# MIT License
+#
+# Copyright (c) 2025 Eugenio Parodi <ceccopierangiolieugenio AT googlemail DOT com>
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import sys, os, argparse
+import datetime
+
+sys.path.append(os.path.join(sys.path[0],'../../libs/pyTermTk'))
+import TermTk as ttk
+
+
+def demoDateTimePicker(root=None):
+    frame = ttk.TTkFrame(parent=root, border=False)
+
+    frameDateForm = ttk.TTkFrame(parent=frame, pos=(0,0), size=(24,10), title='Date Form', titleAlign=ttk.TTkK.Alignment.RIGHT_ALIGN, border=True)
+    dateFormWidget = ttk.TTkDateForm(parent=frameDateForm, pos=(1,0))
+
+    frameDateTime = ttk.TTkFrame(parent=frame, pos=(24,0), size=(26,3), title='DateTime widget', titleAlign=ttk.TTkK.Alignment.LEFT_ALIGN, border=True)
+    datetimeWidget = ttk.TTkDateTime(parent=frameDateTime, pos=(1,0))
+
+    frameDate = ttk.TTkFrame(parent=frame, pos=(24,3), size=(17,3), title='Date', titleAlign=ttk.TTkK.Alignment.LEFT_ALIGN, border=True)
+    dateWidget = ttk.TTkDate(parent=frameDate, pos=(1,0))
+
+    frameTime = ttk.TTkFrame(parent=frame, pos=(24,6), size=(12,3), title='Time', titleAlign=ttk.TTkK.Alignment.LEFT_ALIGN, border=True)
+    timeWidget = ttk.TTkTime(parent=frameTime, pos=(1,0))
+
+    ttk.pyTTkSlot(datetime.datetime)
+    def _changedDatetime(dt:datetime.datetime):
+        dateWidget.setDate(dt.date())
+        timeWidget.setTime(dt.time())
+        dateFormWidget.setDate(dt.date())
+
+    ttk.pyTTkSlot(datetime.time)
+    def _changedTime(time:datetime.time):
+        dt = datetimeWidget.datetime()
+        new_dt = datetime.datetime.combine(dt.date(),time)
+        datetimeWidget.setDatetime(new_dt)
+
+    ttk.pyTTkSlot(datetime.date)
+    def _changedDate(date:datetime.date):
+        dt = datetimeWidget.datetime()
+        new_dt = datetime.datetime.combine(date,dt.time())
+        datetimeWidget.setDatetime(new_dt)
+        dateFormWidget.setDate(date)
+        dateWidget.setDate(date)
+
+    timeWidget.timeChanged.connect(_changedTime)
+    dateWidget.dateChanged.connect(_changedDate)
+    dateFormWidget.dateChanged.connect(_changedDate)
+    datetimeWidget.datetimeChanged.connect(_changedDatetime)
+
+    return frame
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument('-f', help='Full Screen', action='store_true')
+    args = parser.parse_args()
+
+    root = ttk.TTk(mouseTrack=True)
+    if args.f:
+        root.setLayout(ttk.TTkGridLayout())
+        winColor1 = root
+    else:
+        winColor1 = ttk.TTkWindow(parent=root,pos = (0,0), size=(52,14), title="Test DateTime Picker", border=True, layout=ttk.TTkGridLayout())
+
+    demoDateTimePicker(winColor1)
+
+    root.mainloop()
+
+if __name__ == "__main__":
+    main()

libs/pyTermTk/TermTk/TTkAbstract/abstractscrollarea.py

@@ -167,7 +167,7 @@ def setHorizontalScrollBarPolicy(self, policy):
             self._horizontalScrollBarPolicy = policy
             self._viewportChanged()
 
-    def viewport(self):
+    def viewport(self) -> TTkAbstractScrollViewInterface:
         return self._viewport
 
     def update(self, repaint=True, updateLayout=False, updateParent=False):

libs/pyTermTk/TermTk/TTkCore/canvas.py

@@ -298,7 +298,6 @@ def drawBoxTitle(self, pos, size, text, align=TTkK.CENTER_ALIGN, color=TTkColor.
         x,y = pos
         w,h = size
         if w < 4: return
-        gg = TTkCfg.theme.grid[grid]
 
         if text.termWidth() > w-4:
             text = text.substring(to=w-4)
@@ -307,12 +306,12 @@ def drawBoxTitle(self, pos, size, text, align=TTkK.CENTER_ALIGN, color=TTkColor.
         elif align == TTkK.LEFT_ALIGN:
             l=1
         else:
-            l = w-2-text.termWidth()
+            l = w-3-text.termWidth()
         l+=x
         r = l+text.termWidth()+1
 
-        self._set(y,l, gg[0x0B], color)
-        self._set(y,r, gg[0x08], color)
+        self._set(y,l, '╸', color)
+        self._set(y,r, '╺', color)
         self.drawText(pos=(l+1,y),text=text,color=colorText)
 
 

libs/pyTermTk/TermTk/TTkTemplates/mouseevents.py

@@ -127,7 +127,15 @@ def enterEvent(self, evt:TTkMouseEvent) -> bool:
         '''
         This event handler, can be reimplemented in a subclass to receive mouse enter events for the widget.
 
-        .. note:: Reimplement this function to handle this event
+        .. note::
+
+            This handler reimplementation require the `super()` method to be called.
+
+            .. code:: python
+
+                def enterEvent(self, evt):
+                    TTkLog.debug('Enter Event')
+                    return super().enterEvent(evt)
 
         :param evt: The mouse event
         :type evt: :py:class:`TTkMouseEvent`
@@ -141,7 +149,15 @@ def leaveEvent(self, evt:TTkMouseEvent) -> bool:
         '''
         This event handler, can be reimplemented in a subclass to receive mouse leave events for the widget.
 
-        .. note:: Reimplement this function to handle this event
+        .. note::
+
+            This handler reimplementation require the `super()` method to be called.
+
+            .. code:: python
+
+                def leaveEvent(self, evt):
+                    TTkLog.debug('Leave Event')
+                    return super().leaveEvent(evt)
 
         :param evt: The mouse event
         :type evt: :py:class:`TTkMouseEvent`