OpenParable
Skip to content
← Back to skills

Widget Creation

Development
widget-creation

Widget Creation is an Agent Skill for development published in the ceccopierangiolieugenio/pyTermTk repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when: creating new TTkWidget subclasses with proper structure, signals, slots, and documentation

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/ceccopierangiolieugenio/pyTermTk/blob/HEAD/.github/skills/widget-creation/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/widget-creation, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Widget Creation Skill

Overview

This skill scaffolds new pyTermTk widgets following project patterns:

  • Proper class structure with __slots__
  • Signal definitions with type hints
  • Event handlers with correct return semantics
  • Sphinx documentation with ASCII art
  • Test file structure
  • Example/demo integration

When to Use

  • Building new interactive widgets (button, input, selector variants)
  • Creating container widgets (custom layouts, panels)
  • Adding display widgets (custom text renderers, charts)

File Structure

1. Widget File

Location: libs/pyTermTk/TermTk/TTkWidgets/ttk_<widget_name>.py

Template:

"""
Module: TTkMyWidget
Implements a custom widget for [purpose]
"""

from TermTk import TTkWidget, TTkColor, pyTTkSignal, pyTTkSlot

class TTkMyWidget(TTkWidget):
    '''TTkMyWidget: [One-line description]

    [Longer description of purpose and behavior]

    (`demo <https://ceccopierangiolieugenio.github.io/pyTermTk-Docs/sandbox/...>`__)

    ::

        [ASCII art showing visual representation]
        [Multiple lines if needed]

    .. code:: python

        import TermTk as ttk

        root = ttk.TTk()
        widget = ttk.TTkMyWidget(parent=root)
        root.mainloop()
    '''

    # Performance: always use __slots__
    __slots__ = (
        '_privateVar',
        '_anotherVar',
        'stateChanged',
    )

    _privateVar: int
    _anotherVar: int
    stateChanged: pyTTkSignal
    '''
    Emitted when widget state changes.

    :param value: new state value
    :type value: [type]
    '''

    # 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')}
    }

    def __init__(self, **kwargs):
        '''Initialize the widget.

        :param parent: parent widget
        :type parent: TTkWidget
        [Other parameters as needed]
        '''
        # Instantiate signals in __init__ (do not instantiate at class level)
        self.stateChanged = pyTTkSignal(int)

        # Initialize private variables
        self._privateVar = 0  # Replace with appropriate default for your widget

        # Call parent with merged kwargs and default size
        super().__init__(**kwargs|{'size': (10, 3)})  # Replace with appropriate default dimensions

    # Property getters/setters
    def getValue(self) -> int:
        '''Get the current value.

        :return: current value
        :rtype: int
        '''
        return self._privateVar

    def setValue(self, value: int) -> None:
        '''Set the value.

        :param value: new value
        :type value: int
        '''
        if self._privateVar != value:
            self._privateVar = value
            self.stateChanged.emit(value)
            self.update()

    # Return True when this widget fully processes the event; otherwise return False to let parent widgets handle it.
    def keyEvent(self, evt) -> bool:
        '''Handle keyboard events.'''
        if evt.key == 'Enter':
            self.stateChanged.emit(self._privateVar)
            return True
        return False

    def mousePressEvent(self, evt) -> bool:
        '''Handle mouse press events.'''
        # Handle click, return True if consumed
        return False

    def paintEvent(self) -> None:
        '''Render the widget.'''
        # Use currentStyle() for theme-aware colors
        canvas = self.canvas
        style = self.currentStyle()

        # Draw widget content
        canvas.drawText(pos=(0, 0), text="MyWidget")

__all__ = ['TTkMyWidget']

2. Test File

Location: tests/pytest/widgets/<widget_name>/test_<widget_name>.py

Template:

import pytest
from TermTk import TTkMyWidget

class TestTTkMyWidget:
    '''Test suite for TTkMyWidget'''

    def test_initialization(self):
        """Widget initializes with defaults"""
        widget = TTkMyWidget()
        assert widget.getValue() == 0  # Or expected default

    def test_signal_emission(self):
        """Signal emits when state changes"""
        widget = TTkMyWidget()
        emitted = []
        widget.stateChanged.connect(lambda val: emitted.append(val))

        widget.setValue(42)
        assert emitted == [42]

    def test_key_event_handling(self):
        """Key events handled correctly"""
        widget = TTkMyWidget()
        from TermTk import TTkKeyEvent

        evt = TTkKeyEvent(key='Enter')
        result = widget.keyEvent(evt)
        assert result == True  # Event was handled

    def test_disabled_state(self):
        """Widget respects disabled state"""
        widget = TTkMyWidget()
        widget.setDisabled(True)
        # Verify widget doesn't respond to events, etc.

3. Example/Demo

Add to demo/showcase/ or tutorial/examples/ if creating showcase:

"""
Example: TTkMyWidget

Demonstrates the TTkMyWidget in action.
"""

import TermTk as ttk

def main():
    root = ttk.TTk()

    # Create and configure widget
    widget = ttk.TTkMyWidget(parent=root)
    widget.setValue(10)

    # Connect signal
    @ttk.pyTTkSlot(int)
    def on_state_changed(value):
        print(f"State changed to: {value}")

    widget.stateChanged.connect(on_state_changed)

    root.mainloop()

if __name__ == '__main__':
    main()

Key Patterns to Follow

Signals

  • Keep signal entries in __slots__ and type-annotate them there
  • Instantiate signals in __init__ with specific type: pyTTkSignal(int) not pyTTkSignal()
  • Emit with actual value: self.stateChanged.emit(value)

slots

__slots__ = (
    '_variable1',
    '_variable2',
    'valueChanged',
    # Always use slots for memory efficiency
)

_variable1: int
_variable2: int
valueChanged: pyTTkSignal

Rules:

  • All non-signal slot names must start with _.
  • Public (non-underscore) slot names are allowed only for exposed signals.
  • Add a class-level type annotation for each slot entry immediately below __slots__.

Class Styling

classStyle = {
    'default':  {...},
    'hover':    {...},
    'focus':    {...},
    'disabled': {...}
}

Event Return Values

  • Return True if event fully handled (don't propagate)
  • Return False to let event propagate up widget tree

Documentation

  • ASCII art for visual widgets
  • Demo/sandbox links
  • Runnable code examples
  • Sphinx cross-references: :py:class:, :py:meth:

Checklist

File and Class Structure

  • File location: libs/pyTermTk/TermTk/TTkWidgets/ttk_*.py
  • Inherits from TTkWidget or TTkContainer
  • __slots__ defined
  • Non-signal slot names use leading _
  • Public slot names are signals only
  • Every slot entry has a class-level type annotation
  • __all__ export defined
  • Register the widget export in libs/pyTermTk/TermTk/TTkWidgets/__init__.py with from .ttk_<widget_name> import TTkMyWidget

Signals and Events

  • Signals with type hints
  • Signals initialized in __init__
  • Event methods return bool

Documentation and Examples

  • Sphinx docstring with ASCII art
  • Example added to demo or tutorial

Testing and Quality

  • Test file created
  • Tests cover initialization, signals, events, edge cases
  • Flake8 passes

Common Mistakes to Avoid

  • ❌ Signals instantiated at class level instead of __init__
  • ❌ Event handlers don't return bool (should always return True/False)
  • ❌ Missing __slots__ (memory waste)
  • ❌ Hardcoded colors instead of using theme via currentStyle()
  • ❌ Tests that only check implementation, not behavior
  • ❌ No documentation or examples