TTkList

TTkList🌶️

class TTkList(*, items: List[TTkAbstractListItem | Any] = [], listWidget: TTkListWidget | None = None, selectionMode: SelectionMode = SelectionMode.SingleSelection, dragDropMode: DragDropMode = DragDropMode.NoDragDrop, showSearch: bool = True, **kwargs)[source]🌶️

Bases: TTkAbstractScrollArea

TTkList is a container widget which place TTkListWidget in a scrolling area with on-demand scroll bars.

TTkListWidget:

A widget that displays a scrollable list of selectable items with optional search functionality.

This widget supports single/multiple selection modes, drag-and-drop reordering, keyboard navigation, and incremental search. Items can be strings or custom TTkAbstractListItem widgets.

╔════════════════════════════════╗
║Search: te_                    ▲║ ← Search bar (optional)
║S-0) --Zero-3- officia         ▓║
║S-1) ad ipsum                  ┊║
║S-2) irure nisi                ┊║ ← Scrollable items
║S-3) minim --Zero-3-           ┊║
║S-4) ea sunt                   ┊║
║S-5) qui mollit                ┊║
║S-6) magna sunt                ┊║
║S-7) sunt officia              ▼║
╚════════════════════════════════╝

Demo: list.py (online)

import TermTk as ttk

root = ttk.TTk(layout=ttk.TTkGridLayout(), mouseTrack=True)

# Simple string list
l1 = ttk.TTkList(parent=root, items=[123, 456, 789])
id1 = l1.indexOf(456)
l1.setCurrentRow(id1)

# List with many items (scrollable)
ttk.TTkList(parent=root, items=[f"Item 0x{i:03X}" for i in range(100)])

# Multi-selection list with drag-drop
ttkList = ttk.TTkList(
    parent=root,
    selectionMode=ttk.TTkK.SelectionMode.MultiSelection,
    dragDropMode=ttk.TTkK.DragDropMode.AllowDragDrop
)
ttkList.addItems([f"Item 0x{i:04X}" for i in range(50)])

root.layout().addWidget(ttk.TTkLogViewer(),1,0,1,3)

# Handle selection
@ttk.pyTTkSlot(str)
def on_item_clicked(text):
    ttk.TTkLog.debug(f"Clicked: {text}")

ttkList.textClicked.connect(on_item_clicked)

root.mainloop()

Features:

Single or multiple selection modes
Keyboard navigation (arrows, page up/down, home/end)
Incremental search by typing
Drag-and-drop reordering (optional)
Custom item widgets via TTkAbstractListItem
Signals for item selection and search events

Parameters:: listWidget (TTkListWidget, optional) – a custom List Widget to be used instead of the default one.

TTkListWidget’s forwarded init params:

Parameters:

items (list, optional) – Initial list of items (Any or TTkAbstractListItem objects), defaults to []
selectionMode (TTkK.SelectionMode, optional) – Selection behavior (TTkK.SelectionMode.SingleSelection or TTkK.SelectionMode.MultiSelection), defaults to TTkK.SelectionMode.SingleSelection
dragDropMode (TTkK.DragDropMode, optional) – Drag and drop behavior (NoDragDrop, InternalMove, DragOnly, DropOnly, DragDrop), defaults to NoDragDrop
showSearch (bool, optional) – Whether to show the search hint at the top, defaults to True

TTkContainer’s inherited init params:

Parameters:

layout (TermTk.TTkLayouts) – the layout of this widget, optional, defaults to TTkLayout
padding (TTkPadding) – the padding (top, bottom, left, right) of the widget, defaults to (0,0,0,0)
paddingTop (int) – the Top padding, override Top padding if already defined, optional, default=0 if padding is not defined
paddingBottom (int) – the Bottom padding, override Bottom padding if already defined, optional, default=0 if padding is not defined
paddingLeft (int) – the Left padding, override Left padding if already defined, optional, default=0 if padding is not defined
paddingRight (int) – the Right padding, override Right padding if already defined, optional, default=0 if padding is not defined
forwardStyle (bool) – [Experimental] any change of style will reflect the children, defaults to False

TTkWidget’s inherited init params:

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.

Signals 🌶️

Signals linked to: TTkListWidget

`TTkListWidget.itemClicked`	This signal is emitted whenever an item is clicked.
`TTkListWidget.searchModified`	This signal is emitted whenever the search text is modified.
`TTkListWidget.textClicked`	This signal is emitted whenever an item is clicked.

TTkList 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 🌶️

Slots Inherited from: TTkContainer

`hide`()	hide the widget
`show`()	show the widget

Slots Inherited from: TTkWidget

`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 disnabled
`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])	Update the scroll area and viewport

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🌶️

Methods linked to: TTkListWidget

`TTkListWidget.addItem`(item[, data])	Appends a single item to the end of the list.
`TTkListWidget.addItemAt`(item, pos[, data])	Inserts a single item at the specified position.
`TTkListWidget.addItems`(items)	Appends multiple items to the end of the list.
`TTkListWidget.addItemsAt`(items, pos)	Inserts multiple items at the specified position.
`TTkListWidget.dragDropMode`()	Returns the current drag-drop mode.
`TTkListWidget.indexOf`(item)	Returns the index of the given item.
`TTkListWidget.itemAt`(pos)	Returns the item at the specified index.
`TTkListWidget.items`()	Returns all items in the list.
`TTkListWidget.moveItem`(fr, to)	Moves an item from one position to another.
`TTkListWidget.removeAt`(pos)	Removes the item at the specified index.
`TTkListWidget.removeItem`(item)	Removes a single item from the list.
`TTkListWidget.removeItems`(items)	Removes multiple items from the list.
`TTkListWidget.search`()	Returns the current search text.
`TTkListWidget.searchVisibility`()	Returns whether the search hint is visible.
`TTkListWidget.selectedItems`()	Returns the list of currently selected items.
`TTkListWidget.selectedLabels`()	Returns the text of all selected items.
`TTkListWidget.selectionMode`()	Returns the current selection mode.
`TTkListWidget.setCurrentItem`(item)	Selects the specified item and emits the itemClicked signal.
`TTkListWidget.setCurrentRow`(row)	Selects the item at the specified row.
`TTkListWidget.setDragDropMode`(dndMode)	Sets the drag-drop mode for this list.
`TTkListWidget.setSearch`(search)	Sets the search text to filter items.
`TTkListWidget.setSearchVisibility`(visibility)	Sets the visibility of the search hint at the top of the list.
`TTkListWidget.setSelectionMode`(mode)	Sets the selection mode for this list.

TTkList methods:

addItem(item: TTkAbstractListItem | Any, data: Any = None) → None[source]🌶️

See also

this method is forwarded to TTkListWidget.addItem()

Appends a single item to the end of the list.

Parameters:

item (str or TTkAbstractListItem) – The item to add (string or TTkAbstractListItem)
data (Any, optional) – Optional user data to associate with the item

addItemAt(item: TTkAbstractListItem | Any, pos: int, data: Any = None) → None[source]🌶️

See also

this method is forwarded to TTkListWidget.addItemAt()

Inserts a single item at the specified position.

Parameters:

item (str or TTkAbstractListItem) – The item to insert (string or TTkAbstractListItem)
pos (int) – The index position to insert at
data (Any, optional) – Optional user data to associate with the item

addItems(items: List[TTkAbstractListItem | Any]) → None[source]🌶️

See also

this method is forwarded to TTkListWidget.addItems()

Appends multiple items to the end of the list.

Parameters:: items (list) – List of items to add (strings or TTkAbstractListItem objects)

addItemsAt(items: List[TTkAbstractListItem | Any], pos: int) → None[source]🌶️

See also

this method is forwarded to TTkListWidget.addItemsAt()

Inserts multiple items at the specified position.

Parameters:

items (list) – List of items to insert (strings or TTkAbstractListItem objects)
pos (int) – The index position to insert at

dragDropMode() → DragDropMode[source]🌶️

See also

this method is forwarded to TTkListWidget.dragDropMode()

Returns the current drag-drop mode.

Returns:: The drag-drop behavior setting
Return type:: TTkK.DragDropMode

indexOf(item: TTkAbstractListItem | Any) → int[source]🌶️

See also

this method is forwarded to TTkListWidget.indexOf()

Returns the index of the given item.

Parameters:: item (TTkAbstractListItem or the data or the text to be searched) – The item to find
Returns:: The index of the item, or -1 if not found
Return type:: int

itemAt(pos: int) → TTkAbstractListItem[source]🌶️

See also

this method is forwarded to TTkListWidget.itemAt()

Returns the item at the specified index.

Parameters:: pos (int) – The index position
Returns:: The item at that position
Return type:: TTkAbstractListItem

items() → List[TTkAbstractListItem][source]🌶️

See also

this method is forwarded to TTkListWidget.items()

Returns all items in the list.

Returns:: Complete list of items
Return type:: list[TTkAbstractListItem]

moveItem(fr: int, to: int) → None[source]🌶️

See also

this method is forwarded to TTkListWidget.moveItem()

Moves an item from one position to another.

Parameters:

fr (int) – The source index
to (int) – The destination index

removeAt(pos: int) → None[source]🌶️

See also

this method is forwarded to TTkListWidget.removeAt()

Removes the item at the specified index.

Parameters:: pos (int) – The index of the item to remove

removeItem(item: TTkAbstractListItem) → None[source]🌶️

See also

this method is forwarded to TTkListWidget.removeItem()

Removes a single item from the list.

Parameters:: item (TTkAbstractListItem) – The item to remove

removeItems(items: List[TTkAbstractListItem]) → None[source]🌶️

See also

this method is forwarded to TTkListWidget.removeItems()

Removes multiple items from the list.

Parameters:: items (list[TTkAbstractListItem]) – List of items to remove

search() → str[source]🌶️

See also

this method is forwarded to TTkListWidget.search()

Returns the current search text.

Returns:: The active search filter string
Return type:: str

searchVisibility() → bool[source]🌶️

See also

this method is forwarded to TTkListWidget.searchVisibility()

Returns whether the search hint is visible.

Returns:: True if search hint is shown
Return type:: bool

selectedItems() → List[TTkAbstractListItem][source]🌶️

See also

this method is forwarded to TTkListWidget.selectedItems()

Returns the list of currently selected items.

Returns:: List of selected item widgets
Return type:: list[TTkAbstractListItem]

selectedLabels() → List[str][source]🌶️

See also

this method is forwarded to TTkListWidget.selectedLabels()

Returns the text of all selected items.

Returns:: List of selected item texts
Return type:: list[str]

selectionMode() → SelectionMode[source]🌶️

See also

this method is forwarded to TTkListWidget.selectionMode()

Returns the current selection mode.

Returns:: The selection behavior setting
Return type:: TTkK.SelectionMode

setCurrentItem(item: TTkAbstractListItem) → None[source]🌶️

See also

this method is forwarded to TTkListWidget.setCurrentItem()

Selects the specified item and emits the itemClicked signal.

Parameters:: item (TTkAbstractListItem) – The item to select

setCurrentRow(row: int) → None[source]🌶️

See also

this method is forwarded to TTkListWidget.setCurrentRow()

Selects the item at the specified row.

Parameters:: row (int) – The row index to select

setDragDropMode(dndMode: DragDropMode) → None[source]🌶️

See also

this method is forwarded to TTkListWidget.setDragDropMode()

Sets the drag-drop mode for this list.

Parameters:: dndMode (TTkK.DragDropMode) – The new drag-drop behavior

setSearch(search: str) → None[source]🌶️

See also

this method is forwarded to TTkListWidget.setSearch()

Sets the search text to filter items.

Parameters:: search (str) – The search string to filter by

setSearchVisibility(visibility: bool) → None[source]🌶️

See also

this method is forwarded to TTkListWidget.setSearchVisibility()

Sets the visibility of the search hint at the top of the list.

Parameters:: visibility (bool) – True to show search hint, False to hide

setSelectionMode(mode: SelectionMode) → None[source]🌶️

See also

this method is forwarded to TTkListWidget.setSelectionMode()

Sets the selection mode for this list.

Parameters:: mode (TTkK.SelectionMode) – The new selection behavior (SingleSelection or MultiSelection)

Methods Inherited from: TTkAbstractScrollArea

`resizeEvent`(w, h)	Handle resize events
`setHorizontalScrollBarPolicy`(policy)	Set the horizontal scroll bar policy
`setVerticalScrollBarPolicy`(policy)	Set the vertical scroll bar policy
`setViewport`(viewport)	Set the viewport widget
`update`([repaint, updateLayout, updateParent])	Update the scroll area and viewport
`viewport`()	Return the current viewport

Methods Inherited from: TTkContainer

`addWidget`(widget)
`getPadding`()	Retrieve the `TTkContainer`'s paddings sizes as shown in Layout Topology
`getWidgetByName`(name)	Return the widget from its name.
`hide`()	hide the widget
`keyEvent`(evt)	This event handler, can be reimplemented in a subclass to receive key events for the widget.
`layout`()	Get the Layout
`maximumHeight`()
`maximumWidth`()
`minimumHeight`()
`minimumWidth`()
`paintChildCanvas`()
`removeWidget`(widget)
`rootLayout`()	This is a root layout mainly used to place items that are not supposed to be inside the main layout (i.e. the menu elements).
`setCurrentStyle`(args, *kwargs)
`setLayout`(layout)	Set the Layout used by this widget to place all the child widgets.
`setPadding`(top, bottom, left, right)	Set the `TTkContainer`'s paddings sizes as shown in Layout Topology
`show`()	show the widget
`update`([repaint, updateLayout, updateParent])	Update the scroll area and viewport

Methods Inherited from: TTkWidget

`clearFocus`()	Remove the Focus state of this widget
`close`()	Close (Destroy/Remove) the widget
`currentStyle`()
`disableWidgetCursor`([disable])
`enableWidgetCursor`([enable])
`focusInEvent`()
`focusOutEvent`()
`focusPolicy`()
`geometry`()
`getCanvas`()
`getPixmap`()	Convenience function which return a pixmap representing the current widget status
`getWidgetByName`(name)	Return the widget from its name.
`hasFocus`()	This property holds the focus status of this widget
`height`()
`hide`()	hide the widget
`isEnabled`()	This property holds whether the widget is enabled
`isEntered`()
`isVisible`()	Retrieve the visibility status of this widget
`isVisibleAndParent`()
`lowerWidget`()	Lower the Widget below its relatives
`maxDimension`(orientation)
`maximumHeight`()
`maximumSize`()
`maximumWidth`()
`mergeStyle`(style)
`minDimension`(orientation)
`minimumHeight`()
`minimumSize`()
`minimumWidth`()
`mouseEvent`(evt)
`move`(x, y)	Move the widget
`moveEvent`(x, y)	Convenience function, Event Callback triggered after a successful move
`name`()
`paintChildCanvas`()
`paintEvent`(canvas)	Paint Event callback, this need to be overridden in the widget.
`parentWidget`()
`pasteEvent`(txt)	Callback triggered when a paste event is forwarded to this widget.
`pos`()
`raiseWidget`([raiseParent])	Raise the Widget above its relatives
`resize`(width, height)	Resize the widget
`resizeEvent`(w, h)	Handle resize events
`setCurrentStyle`(args, *kwargs)
`setDefaultSize`(arg, width, height)
`setDisabled`([disabled])	This property holds whether the widget is disnabled
`setDropEventProxy`(proxy)
`setEnabled`([enabled])	This property holds whether the widget is enabled
`setFocus`()	Focus the widget
`setFocusPolicy`(policy)	This property holds the way the widget accepts keyboard focus
`setGeometry`(x, y, width, height)	Resize and move the widget
`setMaximumHeight`(maxh)
`setMaximumSize`(maxw, maxh)
`setMaximumWidth`(maxw)
`setMinimumHeight`(minh)
`setMinimumSize`(minw, minh)
`setMinimumWidth`(minw)
`setName`(name)	Set the name of this Instance
`setParent`(parent)
`setStyle`([style])
`setToolTip`(toolTip)
`setVisible`(visible)	Set the visibility status of this widget
`setWidgetCursor`([pos, type])
`show`()	show the widget
`size`()
`style`()
`toolTip`()
`update`([repaint, updateLayout, updateParent])	Update the scroll area and viewport
`widgetItem`()
`width`()
`x`()
`y`()

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.

TTkList Attributes🌶️

`classStyle`
`itemClicked`
`searchModified`
`textClicked`

TTkList

Contents

TTkList🌶️

Signals🌶️

Slots🌶️

Members🌶️

Methods🌶️

TTkList Attributes🌶️

Signals 🌶️

Slots 🌶️