celina/widgets/list

Search:
Group by:

List widget

This module provides list widgets for displaying and interacting with collections of items, with support for selection, scrolling, and styling.

Types

List = ref object of Widget
  items*: seq[ListItem]
  state*: ListState
  selectionMode*: SelectionMode
  selectedIndices*: seq[int]
  highlightedIndex*: int
  scrollOffset*: int
  visibleCount*: int
  normalStyle*: Style
  selectedStyle*: Style
  highlightedStyle*: Style
  disabledStyle*: Style
  bulletPrefix*: string
  showScrollbar*: bool
  onSelect*: proc (index: int)
  onMultiSelect*: proc (indices: seq[int])
  onHighlight*: proc (index: int)
List widget for displaying items 
ListItem = object
  text*: string
  style*: Option[Style]
  selectable*: bool
Individual list item with optional custom style 
ListState = enum
  Normal, Focused, Disabled
List visual states 
SelectionMode = enum
  None, Single, Multiple
List selection behavior

Procs

proc addItem(widget: List; item: ListItem) {....raises: [], tags: [], forbids: [].}
Add an item to the list 
proc addItem(widget: List; text: string) {....raises: [], tags: [], forbids: [].}
Add a simple text item to the list 
proc bulletList(items: seq[string]; bullet: string = "• "): List {....raises: [],
    tags: [], forbids: [].}
Create a bulleted list 
proc checkList(items: seq[string]; onMultiSelect: proc (indices: seq[int]) = nil): List {.
    ...raises: [], tags: [], forbids: [].}
Create a multiple-selection checklist 
proc clearItems(widget: List) {....raises: [], tags: [], forbids: [].}
Clear all items from the list 
proc clearSelection(widget: List) {....raises: [Exception], tags: [RootEffect],
                                    forbids: [].}
Clear all selections 
proc deselectItem(widget: List; index: int) {....raises: [Exception],
    tags: [RootEffect], forbids: [].}
Deselect an item (for multiple selection mode) 
proc getItemStyle(widget: List; index: int): Style {....raises: [], tags: [],
    forbids: [].}
Get the style for a specific item 
proc handleKeyEvent(widget: List; event: KeyEvent): bool {....raises: [Exception],
    tags: [RootEffect], forbids: [].}
Handle keyboard input for the list Returns true if the event was handled 
proc handleMouseEvent(widget: List; event: MouseEvent; area: Rect): bool {.
    ...raises: [Exception], tags: [RootEffect], forbids: [].}
Handle mouse input for the list Returns true if the event was handled 
proc highlightFirst(widget: List) {....raises: [Exception], tags: [RootEffect],
                                    forbids: [].}
Move highlight to first selectable item 
proc highlightLast(widget: List) {....raises: [Exception], tags: [RootEffect],
                                   forbids: [].}
Move highlight to last selectable item 
proc highlightNext(widget: List) {....raises: [Exception], tags: [RootEffect],
                                   forbids: [].}
Move highlight to next selectable item 
proc highlightPrevious(widget: List) {....raises: [Exception], tags: [RootEffect],
                                       forbids: [].}
Move highlight to previous selectable item 
proc isEnabled(widget: List): bool {....raises: [], tags: [], forbids: [].}
Check if the list is enabled 
proc isSelected(widget: List; index: int): bool {....raises: [], tags: [],
    forbids: [].}
Check if an item is selected 
proc list(items: seq[string]; selectionMode: SelectionMode = Single): List {.
    ...raises: [], tags: [], forbids: [].}
Convenience constructor for List widget from strings 
proc listItem(text: string): ListItem {....raises: [], tags: [], forbids: [].}
Convenience constructor for simple list item 
proc listItem(text: string; style: Style): ListItem {....raises: [], tags: [],
    forbids: [].}
Create a styled list item 
proc newList(items: seq[ListItem] = @[]; selectionMode: SelectionMode = Single;
             normalStyle: Style = defaultStyle();
             selectedStyle: Style = style(Black, White);
             highlightedStyle: Style = style(White, BrightBlack);
             disabledStyle: Style = style(BrightBlack, Reset);
             bulletPrefix: string = ""; showScrollbar: bool = true;
             onSelect: proc (index: int) = nil;
             onMultiSelect: proc (indices: seq[int]) = nil;
             onHighlight: proc (index: int) = nil): List {....raises: [], tags: [],
    forbids: [].}
Create a new List widget 
proc newListItem(text: string; style: Option[Style] = none(Style);
                 selectable: bool = true): ListItem {....raises: [], tags: [],
    forbids: [].}
Create a new list item 
proc pageDown(widget: List) {....raises: [], tags: [], forbids: [].}
Scroll down by one page 
proc pageUp(widget: List) {....raises: [], tags: [], forbids: [].}
Scroll up by one page 
proc removeItem(widget: List; index: int) {....raises: [], tags: [], forbids: [].}
Remove an item from the list 
proc renderScrollbar(widget: List; area: Rect; buf: var Buffer) {....raises: [],
    tags: [], forbids: [].}
Render a scrollbar on the right edge 
proc scrollDown(widget: List; lines: int = 1) {....raises: [], tags: [],
    forbids: [].}
Scroll the list down 
proc scrollUp(widget: List; lines: int = 1) {....raises: [], tags: [], forbids: [].}
Scroll the list up 
proc selectItem(widget: List; index: int) {....raises: [Exception],
    tags: [RootEffect], forbids: [].}
Select an item (respecting selection mode) 
proc selectList(items: seq[string]; onSelect: proc (index: int) = nil): List {.
    ...raises: [], tags: [], forbids: [].}
Create a single-selection list 
proc setEnabled(widget: List; enabled: bool) {....raises: [], tags: [], forbids: [].}
Enable or disable the list 
proc setItems(widget: List; items: seq[ListItem]) {....raises: [], tags: [],
    forbids: [].}
Replace all items in the list 
proc setItems(widget: List; items: seq[string]) {....raises: [], tags: [],
    forbids: [].}
Replace all items with simple text items 
proc setState(widget: List; newState: ListState) {....raises: [], tags: [],
    forbids: [].}
Set the list state 
proc simpleList(items: seq[string]): List {....raises: [], tags: [], forbids: [].}
Create a simple list with no selection 
proc toggleSelection(widget: List; index: int) {....raises: [Exception],
    tags: [RootEffect], forbids: [].}
Toggle selection of an item 
proc withBulletPrefix(widget: List; prefix: string): List {....raises: [],
    tags: [], forbids: [].}
Create a copy with different bullet prefix 
proc withItems(widget: List; items: seq[ListItem]): List {....raises: [], tags: [],
    forbids: [].}
Create a copy with different items 
proc withScrollbar(widget: List; show: bool): List {....raises: [], tags: [],
    forbids: [].}
Create a copy with scrollbar visibility setting 
proc withSelectionMode(widget: List; mode: SelectionMode): List {....raises: [],
    tags: [], forbids: [].}
Create a copy with different selection mode 
proc withStyles(widget: List; normal: Style = defaultStyle();
                selected: Style = defaultStyle();
                highlighted: Style = defaultStyle();
                disabled: Style = defaultStyle()): List {....raises: [], tags: [],
    forbids: [].}
Create a copy with different styles

Methods

method canFocus(widget: List): bool {....raises: [], tags: [], forbids: [].}
Lists can receive focus when enabled and have selectable items 
method getMinSize(widget: List): Size {....raises: [], tags: [], forbids: [].}
Get minimum size for list widget 
method getPreferredSize(widget: List; available: Size): Size {....raises: [],
    tags: [], forbids: [].}
Get preferred size for list widget 
method render(widget: List; area: Rect; buf: var Buffer) {....raises: [], tags: [],
    forbids: [].}
Render the list widget

Made with Nim. Generated: 2025-09-16 21:40:19 UTC