TTkWidget

class TTkWidget(parent: TTkContainer | None = None, x: int = 0, y: int = 0, width: int = 0, height: int = 0, pos: Tuple[int, int] | None = None, size: Tuple[int, int] | None = None, maxSize: Tuple[int, int] | None = None, maxWidth: int = 65536, maxHeight: int = 65536, minSize: Tuple[int, int] | None = None, minWidth: int = 0, minHeight: int = 0, name: str | None = None, visible: bool = True, enabled: bool = True, toolTip: TTkString | str = '', style: Dict[str, Any] | None = None, addStyle: Dict[str, Any] | None = None, **kwargs)

Bases: TMouseEvents, TKeyEvents, TDragEvents

Widget sizes:

Terminal area (i.e. XTerm) = TTk
┌─────────────────────────────────────────┐
│                                         │
│    TTkWidget     width                  │
│ (x,y)┌─────────────────────────┐        │
│      │                         │        │
│      │                         │ height │
│      │                         │        │
│      │                         │        │
│      │                         │        │
│      └─────────────────────────┘        │
└─────────────────────────────────────────┘

The TTkWidget class is the base class of all user interface objects

Parameters:

• name (str, optional) – the name of the widget, defaults to “”

• parent (TTkWidget, optional) – the parent widget, defaults to None

• x (int, optional) – the x position, defaults to 0

• y (int, optional) – the y position, defaults to 0

• pos ((int,int), optional) – the [x,y] position (override the previously defined x, y), defaults to (x,y)

• width (int, optional) – the width of the widget, defaults to 0

• height (int, optional) – the height of the widget, defaults to 0

• size ((int,int), optional) – the size [width, height] of the widget (override the previously defined sizes), defaults to (width,height)

• maxWidth (int, optional) – the maxWidth of the widget, defaults to 0x10000

• maxHeight (int, optional) – the maxHeight of the widget, defaults to 0x10000

• maxSize ((int,int), optional) – the max [width,height] of the widget, optional, defaults to (maxWidth,maxHeight)

• minWidth (int, optional) – the minWidth of the widget, defaults to 0

• minHeight (int, optional) – the minHeight of the widget, defaults to 0

• minSize ((int,int), optional) – the minSize [width,height] of the widget, optional, defaults to (minWidth,minHeight)

• toolTip (TTkString, optional) – This property holds the widget’s tooltip, defaults to ‘’

• style (dict, optional) – this field hold the custom style to be used by this widget

• addStyle (dict, optional) – this field is required to override/merge the new style on top of the current one, useful if only few params need to be changed

• visible (bool, optional) – the visibility, optional, defaults to True

• enabled (bool, optional) – the ability to handle input events, optional, defaults to True

TMouseEvents’s inherited init params:

Initialize self. See help(type(self)) for accurate signature.

TDragEvents’s inherited init params:

Initialize self. See help(type(self)) for accurate signature.

Style

classStyle = {
            'default':     {'color': TTkColor.RST,           'borderColor': TTkColor.RST},
            'disabled':    {'color': TTkColor.fg('#888888'), 'borderColor': TTkColor.fg('#888888')},
            # 'hover':       {'color': TTkColor.fg('#00FF00')+TTkColor.bg('#0077FF')},
            # 'checked':     {'color': TTkColor.fg('#00FF00')+TTkColor.bg('#00FFFF')},
            # 'clicked':     {'color': TTkColor.fg('#FFFF00')},
            # 'focus':       {'color': TTkColor.fg('#FFFF88')},
        }

Signals

closed	This signal is emitted whenever the widget is closed
currentStyleChanged	This signal is emitted whenever the widget stye change
focusChanged	This signal is emitted whenever the focus status change i.e. with the setFocus() or clearFocus() methods.
sizeChanged	This signal is emitted whenever the widget size change

Slots

close()	Close (Destroy/Remove) the widget
hide()	hide the widget
lowerWidget()	Lower the Widget below its relatives
raiseWidget([raiseParent])	Raise the Widget above its relatives
setDisabled([disabled])	This property holds whether the widget is disabled
setEnabled([enabled])	This property holds whether the widget is enabled
setFocus()	Focus the widget
setVisible(visible)	Set the visibility status of this widget
show()	show the widget
update([repaint, updateLayout, updateParent])	Notify the drawing routine that the widget changed and needs to draw its new content.

Members

closed: pyTTkSignal

This signal is emitted whenever the widget is closed

Parameters:

widget (TTkWidget) – the widget closed (=self)

currentStyleChanged: pyTTkSignal

This signal is emitted whenever the widget stye change

Parameters:

style (dict) – the new style applied

focusChanged: pyTTkSignal

This signal is emitted whenever the focus status change i.e. with the setFocus() or clearFocus() methods

Parameters:

status (bool) – the curent focus status

sizeChanged: pyTTkSignal

This signal is emitted whenever the widget size change

Parameters:

• width (int) – the new widget width

• height (int) – the new widget height

Methods

clearFocus() → None

Remove the Focus state of this widget

close() → None

Close (Destroy/Remove) the widget

currentStyle() → Dict[str, Any]

Retrieve the currently active style

Returns:

a dictionary containing the active style

Return type:

dict

disableWidgetCursor(disable: bool = True) → None

Disable or enable the widget cursor

This is a convenience method that is equivalent to enableWidgetCursor(not disable).

Parameters:

disable (bool) – True to disable the cursor, False to enable

enableWidgetCursor(enable: bool = True) → None

Enable or disable the widget cursor

Parameters:

enable (bool) – True to enable the cursor, False to disable

focusInEvent() → None

Callback triggered when the widget receives focus

Note

Override this method to handle focus in events

focusOutEvent() → None

Callback triggered when the widget loses focus

Note

Override this method to handle focus out events

focusPolicy() → FocusPolicy

Retrieve the focus policy of this widget

Returns:

the focus policy

Return type:

TTkK.FocusPolicy

geometry() → tuple[int, int, int, int]

Retrieve the widget geometry

Returns:

a tuple of (x, y, width, height)

Return type:

tuple[int, int, int, int]

getCanvas() → TTkCanvas

Retrieve the widget canvas

Returns:

the canvas object used for drawing

Return type:

TTkCanvas

getPixmap() → TTkCanvas

Convenience function which return a pixmap representing the current widget status

Returns:

TTkCanvas

getWidgetByName(name: str) → TTkWidget | None

Get a widget by its name (recursively searches this widget and its children)

Parameters:

name (str) – the widget name to search for

Returns:

the widget with the given name, or None if not found

Return type:

TTkWidget or None

hasFocus() → bool

This property holds the focus status of this widget

Returns:

bool

height() → int

Retrieve the widget height

Returns:

the height in characters

Return type:

int

hide() → None

hide the widget

isEnabled() → bool

This property holds whether the widget is enabled

use setEnabled() or setDisabled() to change this property

Returns:

bool

isEntered() → bool

Check if the mouse cursor is currently over this widget

Returns:

True if the mouse is over this widget, False otherwise

Return type:

bool

isVisible() → bool

Retrieve the visibility status of this widget

Returns:

bool

isVisibleAndParent() → bool

Check if the widget and all its parents are visible

Returns:

True if the widget and all its parents are visible, False otherwise

Return type:

bool

lowerWidget() → None

Lower the Widget below its relatives

maxDimension(orientation: Direction) → int

Retrieve the maximum dimension for the given orientation

Parameters:

orientation (TTkK.Direction) – the orientation (TTkK.HORIZONTAL or TTkK.VERTICAL)

Returns:

the maximum dimension

Return type:

int

maximumHeight() → int

Retrieve the maximum height

Returns:

the maximum height in characters

Return type:

int

maximumSize() → tuple[int, int]

Retrieve the maximum size

Returns:

a tuple of (max_width, max_height)

Return type:

tuple[int, int]

maximumWidth() → int

Retrieve the maximum width

Returns:

the maximum width in characters

Return type:

int

mergeStyle(style: Dict[str, Any]) → None

Merge additional style properties with the existing style

This allows updating only specific style properties without replacing the entire style.

Parameters:

style (dict) – a dictionary with style properties to merge

minDimension(orientation: Direction) → int

Retrieve the minimum dimension for the given orientation

Parameters:

orientation (TTkK.Direction) – the orientation (TTkK.HORIZONTAL or TTkK.VERTICAL)

Returns:

the minimum dimension

Return type:

int

minimumHeight() → int

Retrieve the minimum height

Returns:

the minimum height in characters

Return type:

int

minimumSize() → tuple[int, int]

Retrieve the minimum size

Returns:

a tuple of (min_width, min_height)

Return type:

tuple[int, int]

minimumWidth() → int

Retrieve the minimum width

Returns:

the minimum width in characters

Return type:

int

mouseEvent(evt: TTkMouseEvent) → bool

Handle mouse events for this widget and its children

This method handles all mouse-related events including clicks, movement, dragging, and wheel events. It manages focus, hover states, and delegates events to child widgets and event handlers.

Note

This is an internal method

Parameters:

evt (TTkMouseEvent) – the mouse event

Returns:

True if the event was handled, False otherwise

Return type:

bool

move(x: int, y: int) → None

Move the widget

Parameters:

• x (int) – the horizontal position

• y (int) – the vertical position

moveEvent(x: int, y: int) → None

Convenience function, Event Callback triggered after a successful move

Note

Override this method to handle this event

Parameters:

• x (int) – the new horizontal position

• y (int) – the new vertical position

name() → str

Retrieve the name of this widget

Returns:

the widget name

Return type:

str

paintChildCanvas() → None

Paint child widgets on the canvas

This method is called during the paint process to render child widgets. Override in container widgets to implement custom child rendering.

Note

Override this method in subclasses to handle child widget painting

paintEvent(canvas: TTkCanvas) → None

Paint Event callback, this need to be overridden in the widget.

Note

Override this method to handle this event

Parameters:

canvas (TTkCanvas) – the canvas where the content need to be drawn

parentWidget() → TTkContainer | None

Retrieve the parent widget

Returns:

the parent widget or None if top-level

Return type:

TTkContainer or None

pasteEvent(txt: str) → bool

Callback triggered when a paste event is forwarded to this widget.

Note

Reimplement this function to handle this event

Parameters:

txt (str) – the paste object

Returns:

the state of the paste operation

Return type:

bool

pos() → tuple[int, int]

Retrieve the widget position

Returns:

a tuple of (x, y) coordinates

Return type:

tuple[int, int]

raiseWidget(raiseParent: bool = True) → None

Raise the Widget above its relatives

resize(width: int, height: int) → None

Resize the widget

Parameters:

• width (int) – the new width

• height (int) – the new height

resizeEvent(width: int, height: int) → None

Convenience function, Event Callback triggered after a successful resize

Note

Override this method to handle this event

Parameters:

• width (int) – the new width

• height (int) – the new height

setCurrentStyle(style: Dict[str, Any]) → None

Set the currently active style

Parameters:

style (dict) – the style dictionary to apply

setDefaultSize(arg, width: int, height: int) → None

Set default size if not already specified in arguments

This is a helper method for widgets to set default dimensions when no explicit size was provided.

Note

This is typically called during widget initialization

Parameters:

• arg (dict) – the arguments dictionary

• width (int) – the default width in characters

• height (int) – the default height in characters

setDisabled(disabled: bool = True) → None

This property holds whether the widget is disabled

This is a convenience function wrapped around setEnabled() where (not disabled) is used

Parameters:

disabled (bool) – the disabled status, defaults to True

setDropEventProxy(proxy: Callable[[...], Any]) → None

Warning

This is an alpha Method to prototype the Drag and Drop proxy feature and may change in the future

setEnabled(enabled: bool = True) → None

This property holds whether the widget is enabled

In general an enabled widget handles keyboard and mouse events; a disabled widget does not.

Some widgets display themselves differently when they are disabled. For example a button might draw its label grayed out. If your widget needs to know when it becomes enabled or disabled.

Disabling a widget implicitly disables all its children. Enabling respectively enables all child widgets unless they have been explicitly disabled.

By default, this property is true.

Parameters:

enabled (bool) – the enabled status, defaults to True

setFocus() → None

Focus the widget

setFocusPolicy(policy: FocusPolicy) → None

This property holds the way the widget accepts keyboard focus

The policy is TTkK.FocusPolicy.TabFocus if the widget accepts keyboard focus by tabbing, TTkK.FocusPolicy.ClickFocus if the widget accepts focus by clicking, TTkK.FocusPolicy.StrongFocus if it accepts both, and TTkK.FocusPolicy.NoFocus (the default) if it does not accept focus at all.

You must enable keyboard focus for a widget if it processes keyboard events. This is normally done from the widget’s constructor. For instance, the TTkLineEdit constructor calls setFocusPolicy() with TTkK.FocusPolicy.StrongFocus.

If the widget has a focus proxy, then the focus policy will be propagated to it.

Parameters:

policy (TTkK.FocusPolicy) – the focus policy

setGeometry(x: int, y: int, width: int, height: int) → None

Resize and move the widget

Parameters:

• x (int) – the horizontal position

• y (int) – the vertical position

• width (int) – the new width

• height (int) – the new height

setMaximumHeight(maxh: int) → None

Set the maximum height of the widget

If the current height exceeds the new maximum, the widget will be resized. If the minimum height exceeds the new maximum, the minimum height is adjusted.

Parameters:

maxh (int) – the maximum height in characters

setMaximumSize(maxw: int, maxh: int) → None

Set the maximum size of the widget

Parameters:

• maxw (int) – the maximum width in characters

• maxh (int) – the maximum height in characters

setMaximumWidth(maxw: int) → None

Set the maximum width of the widget

If the current width exceeds the new maximum, the widget will be resized. If the minimum width exceeds the new maximum, the minimum width is adjusted.

Parameters:

maxw (int) – the maximum width in characters

setMinimumHeight(minh: int) → None

Set the minimum height of the widget

If the current height is less than the new minimum, the widget will be resized. If the maximum height is less than the new minimum, the maximum height is adjusted.

Parameters:

minh (int) – the minimum height in characters

setMinimumSize(minw: int, minh: int) → None

Set the minimum size of the widget

Parameters:

• minw (int) – the minimum width in characters

• minh (int) – the minimum height in characters

setMinimumWidth(minw: int) → None

Set the minimum width of the widget

If the current width is less than the new minimum, the widget will be resized. If the maximum width is less than the new minimum, the maximum width is adjusted.

Parameters:

minw (int) – the minimum width in characters

setName(name: str) → None

Set the name of this Instance

Parameters:

name (str) – the name to be set

setParent(parent: TTkContainer | None) → None

Set the parent widget

Parameters:

parent (TTkContainer) – the parent widget

setStyle(style: Dict[str, Dict[str, Any]] = {}) → None

Set the style for the widget

The style dictionary should have keys for different states like ‘default’, ‘hover’, ‘focus’, ‘disabled’, ‘clicked’. Each state has its own style dictionary.

Parameters:

style (dict[str, dict]) – the style configuration dictionary

setToolTip(toolTip: TTkString) → None

Set the widget tooltip

Parameters:

toolTip (TTkString) – the tooltip text to display

setVisible(visible: bool) → None

Set the visibility status of this widget

Parameters:

visible (bool) – status

setWidgetCursor(pos: Tuple[int, int] | None = None, type: int | None = None) → None

Set the widget cursor position and type

Parameters:

• pos (tuple[int, int] or None) – the cursor position as (x, y) tuple, or None to keep current

• type (int or None) – the cursor type (e.g., TTkK.Cursor_Blinking_Bar), or None to keep current

show() → None

show the widget

size() → tuple[int, int]

Retrieve the widget size

Returns:

a tuple of (width, height)

Return type:

tuple[int, int]

style() → Dict[str, Any]

Retrieve a copy of the widget style dictionary

Returns:

a dictionary containing the style configuration

Return type:

dict

toolTip() → TTkString

Retrieve the widget tooltip

Returns:

the tooltip text

Return type:

TTkString

update(repaint: bool = True, updateLayout: bool = False, updateParent: bool = False) → None

Notify the drawing routine that the widget changed and needs to draw its new content.

It is important to call this method anytime a canvas update is required after a a status update.

Once update() is called, the paintEvent() is executed during the next screen refresh.

i.e.

class NewLabel(TTkWidget):
    def __init__(self,**kwargs) -> None:
        self.text = ""
        super().__init__(**kwargs)

    def setText(self, text:str) -> None:
        self.text = text
        # Notify the runtime that un update
        # is required will trigger the paintEvent
        # at the next screen (terminal) refresh
        self.update()

    def paintEvent(self, canvas:TTkCanvas) -> None:
        canvas.drawText(pos=(0,0), text=self.text)

widgetItem() → TTkWidgetItem

Retrieve the widget item (layout item wrapper)

Returns:

the layout item for this widget

Return type:

TTkWidgetItem

width() → int

Retrieve the widget width

Returns:

the width in characters

Return type:

int

x() → int

Retrieve the horizontal position

Returns:

the x coordinate

Return type:

int

y() → int

Retrieve the vertical position

Returns:

the y coordinate

Return type:

int

Methods Inherited from: TMouseEvents

enterEvent(evt)	This event handler, can be reimplemented in a subclass to receive mouse enter events for the widget.
leaveEvent(evt)	This event handler, can be reimplemented in a subclass to receive mouse leave events for the widget.
mouseDoubleClickEvent(evt)	This event handler, can be reimplemented in a subclass to receive mouse click events for the widget.
mouseDragEvent(evt)	This event handler, can be reimplemented in a subclass to receive mouse drag events for the widget.
mouseMoveEvent(evt)	This event handler, can be reimplemented in a subclass to receive mouse move events for the widget.
mousePressEvent(evt)	This event handler, can be reimplemented in a subclass to receive mouse press events for the widget.
mouseReleaseEvent(evt)	This event handler, can be reimplemented in a subclass to receive mouse release events for the widget.
mouseTapEvent(evt)	This event handler, can be reimplemented in a subclass to receive mouse click events for the widget.
wheelEvent(evt)	This event handler, can be reimplemented in a subclass to receive mouse wheel events for the widget.

Methods Inherited from: TKeyEvents

keyEvent(evt)

This event handler, can be reimplemented in a subclass to receive key events for the widget.

Methods Inherited from: TDragEvents

dragEnterEvent(evt)	This event handler, can be reimplemented in a subclass to receive drag events for the widget.
dragLeaveEvent(evt)	This event handler, can be reimplemented in a subclass to receive drag events for the widget.
dragMoveEvent(evt)	This event handler, can be reimplemented in a subclass to receive drag events for the widget.
dropEvent(evt)	This event handler, can be reimplemented in a subclass to receive drag events for the widget.

TTkWidget Attributes

classStyle