tk

Tk GUI toolkit bindings for Kit - cross-platform windowed applications

Files

Dependencies

No Kit package dependencies.

Installation

kit add gitlab.com/kit-lang/packages/kit-tk.git

Usage

import Kit.Tk

License

MIT License - see LICENSE for details.

Exported Functions & Types

scrollbar-new

Creates a vertical scrollbar.

Interpreter -> String -> Result Widget TkError

scrollbar = scrollbar-new app ".scroll" |> Result.unwrap
# Connect to a listbox
scrollbar-connect app scrollbar listbox

scrollbar-new-horizontal

Creates a horizontal scrollbar.

Interpreter -> String -> Result Widget TkError

ttk-scrollbar-new

Creates a ttk scrollbar (themed).

Interpreter -> String -> Result Widget TkError

ttk-scrollbar-new-horizontal

Creates a ttk horizontal scrollbar.

Interpreter -> String -> Result Widget TkError

scrollbar-connect

Connects a scrollbar to a widget (listbox, text, canvas, etc.).

This sets up bidirectional scrolling.

Interpreter -> Widget -> Widget -> Result String TkError

scrollbar-connect-horizontal

Connects a horizontal scrollbar to a widget.

Interpreter -> Widget -> Widget -> Result String TkError

scrollable-frame-create

Creates a scrollable frame container.

Returns a tuple of (canvas, inner-frame) widgets. Add your widgets to the inner-frame.

Interpreter -> String -> String -> String -> Result Widget TkError

# Create scrollable area
eval app "canvas .c -yscrollcommand {.scroll set}"
scrollbar = scrollbar-new app ".scroll" |> Result.unwrap
eval app ".scroll configure -command {.c yview}"
inner = frame-new app ".c.inner" |> Result.unwrap
eval app ".c create window 0 0 -window .c.inner -anchor nw"

scrollable-frame-update

Updates the scroll region of a canvas to fit its contents.

Interpreter -> Widget -> Result String TkError

text-scrolled

Adds a text widget with vertical scrollbar.

Creates a frame containing the text widget and scrollbar.

Interpreter -> String -> String -> String -> Int -> Int -> Result Widget TkError

listbox-scrolled

Adds a listbox with vertical scrollbar.

Interpreter -> String -> String -> String -> Int -> Result Widget TkError

canvas-scrolled

Adds a canvas with both scrollbars.

Interpreter -> String -> String -> String -> String -> Int -> Int -> Result Widget TkError

label-new

Creates a new label widget.

Parameters:

Returns:

Interpreter -> String -> String -> Result Widget TkError

label = label-new app ".greeting" "Hello, World!" |> Result.unwrap
pack app label

label-set-text

Sets the text of a label.

Interpreter -> Widget -> String -> Result String TkError

label-set-text app label "New text"

label-get-text

Gets the current text of a label.

Interpreter -> Widget -> Result String TkError

text = label-get-text app label |> Result.unwrap

label-font

Sets the font of a label.

Interpreter -> Widget -> String -> Result String TkError

label-font app label "Helvetica 14 bold"

label-fg

Sets the foreground (text) color of a label.

Interpreter -> Widget -> String -> Result String TkError

label-bg

Sets the background color of a label.

Interpreter -> Widget -> String -> Result String TkError

button-new

Creates a new button widget.

Parameters:

Returns:

Interpreter -> String -> String -> Result Widget TkError

btn = button-new app ".quit" "Quit" |> Result.unwrap
button-on-click app btn "destroy ."
pack app btn

button-set-text

Sets the text of a button.

Interpreter -> Widget -> String -> Result String TkError

button-get-text

Gets the current text of a button.

Interpreter -> Widget -> Result String TkError

button-on-click

Sets the command to execute when the button is clicked.

The command is a Tcl script that will be evaluated when clicked. Common commands: - "destroy ." - Close the application - "set myVar value" - Set a Tcl variable - "puts \"clicked\"" - Print to console

Interpreter -> Widget -> String -> Result String TkError

button-on-click app btn "destroy ."

button-font

Sets the font of a button.

Interpreter -> Widget -> String -> Result String TkError

button-width

Sets the width of a button (in characters).

Interpreter -> Widget -> Int -> Result String TkError

button-disable

Disables a button.

Interpreter -> Widget -> Result String TkError

button-enable

Enables a button.

Interpreter -> Widget -> Result String TkError

entry-new

Creates a new entry (text input) widget.

Parameters:

Returns:

Interpreter -> String -> Result Widget TkError

entry = entry-new app ".nameEntry" |> Result.unwrap
pack app entry
# Later: get the text
text = entry-get-text app entry |> Result.unwrap

entry-get-text

Gets the current text from an entry widget.

Interpreter -> Widget -> Result String TkError

name = entry-get-text app nameEntry |> Result.unwrap

entry-set-text

Sets the text of an entry widget.

Interpreter -> Widget -> String -> Result String TkError

entry-set-text app entry "Default value"

entry-clear

Clears all text from an entry widget.

Interpreter -> Widget -> Result String TkError

entry-clear app entry

entry-width

Sets the width of an entry (in characters).

Interpreter -> Widget -> Int -> Result String TkError

entry-font

Sets the font of an entry.

Interpreter -> Widget -> String -> Result String TkError

entry-readonly

Makes an entry read-only.

Interpreter -> Widget -> Result String TkError

entry-editable

Makes an entry editable (normal state).

Interpreter -> Widget -> Result String TkError

entry-new-password

Creates a password entry (shows * instead of characters).

Interpreter -> String -> Result Widget TkError

frame-new

Creates a new frame container widget.

Interpreter -> String -> Result Widget TkError

frame = frame-new app ".toolbar" |> Result.unwrap

frame-new-with-border

Creates a frame with a border.

Interpreter -> String -> Int -> Result Widget TkError

listbox-new

Creates a new listbox widget.

Parameters:

Interpreter -> String -> Int -> Result Widget TkError

listbox = listbox-new app ".items" 5 |> Result.unwrap

listbox-new-with-mode

Creates a listbox with selection mode.

Selection modes: "single", "browse", "multiple", "extended"

Interpreter -> String -> Int -> String -> Result Widget TkError

listbox-insert

Inserts an item at the end of the listbox.

Interpreter -> Widget -> String -> Result String TkError

listbox-insert app listbox "Item 1"

listbox-insert-at

Inserts an item at a specific index.

Interpreter -> Widget -> Int -> String -> Result String TkError

listbox-delete

Deletes an item at a specific index.

Interpreter -> Widget -> Int -> Result String TkError

listbox-delete-range

Deletes items in a range.

Interpreter -> Widget -> Int -> Int -> Result String TkError

listbox-clear

Clears all items from the listbox.

Interpreter -> Widget -> Result String TkError

listbox-get-selection

Gets the currently selected indices (as space-separated string).

Interpreter -> Widget -> Result String TkError

listbox-get

Gets the item at a specific index.

Interpreter -> Widget -> Int -> Result String TkError

listbox-size

Gets the number of items in the listbox.

Interpreter -> Widget -> Result String TkError

listbox-select

Selects an item by index.

Interpreter -> Widget -> Int -> Result String TkError

listbox-select-clear

Clears selection.

Interpreter -> Widget -> Result String TkError

TkError

Re-export core types

tcl-ok

Constants

init

Initialization

after

Schedules a command to execute after a delay.

Parameters:

Returns the timer ID (can be used with after-cancel).

Interpreter -> Int -> String -> Result String TkError

after app 1000 "puts {One second passed}"
after app 5000 "destroy ."

after-idle

Schedules a command to execute immediately when idle.

The command runs when the event loop has no pending events.

Interpreter -> String -> Result String TkError

after-idle app "update-display"

after-cancel

Cancels a scheduled timer.

Parameters:

Interpreter -> String -> Result String TkError

timer = after app 5000 "destroy ." |> Result.unwrap
after-cancel app timer

after-info

Gets information about pending timers.

Interpreter -> Result String TkError

after-repeat

Creates a repeating timer that calls a command at regular intervals.

The command should reschedule itself to create a loop. Returns the initial timer ID.

Interpreter -> Int -> String -> Result String TkError

# This Tcl proc creates a repeating timer
eval app "proc tick {} { puts {tick}; after 1000 tick }"
after app 1000 "tick"

sleep

Simple sleep/pause using after and vwait.

Note: This blocks the Tcl event loop for the duration. For non-blocking delays, use after with a callback.

Interpreter -> Int -> Result String TkError

# This is usually not recommended - prefer after with callbacks
sleep app 1000

focus

Sets keyboard focus to a widget.

Interpreter -> Widget -> Result String TkError

focus app entry

focus-force

Sets focus to a widget and raises its window.

Interpreter -> Widget -> Result String TkError

focus-get

Gets the widget that currently has focus.

Interpreter -> Result String TkError

focus-follows-mouse

Sets the focus to follow the mouse.

Interpreter -> Result String TkError

bind

Binds an event to a widget.

Parameters:

Common event patterns: - Mouse: <Button-1>, <Button-2>, <Button-3>, <Double-1>, <Motion>, <Enter>, <Leave> - Keyboard: <Key>, <Return>, <Escape>, <Tab>, <BackSpace>, <Delete> - Specific key: <Key-a>, <Key-space>, <Control-c>, <Alt-x>, <Shift-Tab> - Window: <Configure>, <FocusIn>, <FocusOut>, <Destroy>, <Map>, <Unmap>

Event substitutions in command: - %x, %y - Mouse coordinates relative to widget - %X, %Y - Mouse coordinates relative to screen - %K - Key symbol (e.g., "Return", "a", "space") - %k - Keycode - %W - Widget path - %w, %h - Window width/height (for <Configure>)

Interpreter -> Widget -> String -> String -> Result String TkError

bind app button "<Enter>" "puts {Mouse entered button}"
bind app entry "<Return>" "puts {Enter pressed}"
bind app canvas "<Button-1>" "puts {Clicked at %x,%y}"

bind-all

Binds an event to the root window (applies to all widgets).

Interpreter -> String -> String -> Result String TkError

bind-all app "<Control-q>" "destroy ."

bind-class

Binds an event to a widget class (affects all widgets of that type).

Interpreter -> String -> String -> String -> Result String TkError

bind-class app "Button" "<Enter>" ".status configure -text {Button hovered}"

unbind

Removes an event binding from a widget.

Interpreter -> Widget -> String -> Result String TkError

unbind app button "<Enter>"

on-key

Binds a key press event to a widget.

Key can be a single character or a key name. Key names: Return, Escape, Tab, BackSpace, Delete, space, Up, Down, Left, Right, etc.

Interpreter -> Widget -> String -> String -> Result String TkError

on-key app entry "Return" "puts {Enter pressed}"
on-key app window "Escape" "destroy ."

on-any-key

Binds any key press to a widget.

The command can use %K for the key symbol.

Interpreter -> Widget -> String -> Result String TkError

on-any-key app entry "puts {Key pressed: %K}"

on-ctrl-key

Binds a Control+key combination.

Interpreter -> Widget -> String -> String -> Result String TkError

on-ctrl-key app window "q" "destroy ."
on-ctrl-key app text "s" "puts {Save requested}"

on-alt-key

Binds an Alt+key combination.

Interpreter -> Widget -> String -> String -> Result String TkError

on-alt-key app window "x" "destroy ."

on-shift-key

Binds a Shift+key combination.

Interpreter -> Widget -> String -> String -> Result String TkError

on-shift-key app entry "Return" "puts {Shift+Enter pressed}"

on-cmd-key

Binds Command+key (macOS) / Control+key combination. Uses the platform-appropriate modifier.

Interpreter -> Widget -> String -> String -> Result String TkError

on-cmd-key app window "q" "destroy ."

on-click

Binds a left mouse button click to a widget.

Interpreter -> Widget -> String -> Result String TkError

on-click app label "puts {Label clicked}"

on-right-click

Binds a right mouse button click to a widget.

Interpreter -> Widget -> String -> Result String TkError

on-right-click app label "puts {Right clicked at %x,%y}"

on-middle-click

Binds a middle mouse button click to a widget.

Interpreter -> Widget -> String -> Result String TkError

on-double-click

Binds a double-click to a widget.

Interpreter -> Widget -> String -> Result String TkError

on-double-click app listbox "puts {Double-clicked item}"

on-enter

Binds mouse enter event (hover start).

Interpreter -> Widget -> String -> Result String TkError

on-enter app button "puts {Mouse entered}"

on-leave

Binds mouse leave event (hover end).

Interpreter -> Widget -> String -> Result String TkError

on-leave app button "puts {Mouse left}"

on-motion

Binds mouse motion (movement) event.

Interpreter -> Widget -> String -> Result String TkError

on-motion app canvas "puts {Mouse at %x,%y}"

on-drag

Binds mouse drag event (motion with button pressed).

Interpreter -> Widget -> String -> Result String TkError

on-drag app canvas "draw-line %x %y"

on-release

Binds mouse button release event.

Interpreter -> Widget -> String -> Result String TkError

on-release app canvas "puts {Button released at %x,%y}"

on-scroll

Binds mouse wheel scroll event.

On macOS/Windows, use %D for scroll delta.

Interpreter -> Widget -> String -> Result String TkError

on-scroll app canvas "puts {Scrolled: %D}"

on-configure

Binds window configure (resize/move) event.

Command can use %w and %h for new width/height.

Interpreter -> Widget -> String -> Result String TkError

on-configure app window "puts {Resized to %wx%h}"

on-focus-in

Binds window focus in event.

Interpreter -> Widget -> String -> Result String TkError

on-focus-in app entry "puts {Entry focused}"

on-focus-out

Binds window focus out event.

Interpreter -> Widget -> String -> Result String TkError

on-focus-out app entry "validate-input"

on-destroy

Binds window destroy event.

Interpreter -> Widget -> String -> Result String TkError

on-destroy app window "puts {Window closing}"

on-map

Binds window map event (window becomes visible).

Interpreter -> Widget -> String -> Result String TkError

on-unmap

Binds window unmap event (window becomes hidden/minimized).

Interpreter -> Widget -> String -> Result String TkError

on-close

Sets up the window close protocol (WM_DELETE_WINDOW).

This is the proper way to handle the window close button (X).

Interpreter -> String -> Result String TkError

on-close app "puts {Closing...}; destroy ."

on-window-close

Sets up window close protocol for a specific toplevel window.

Interpreter -> Widget -> String -> Result String TkError

on-window-close app dialog "puts {Dialog closing}; destroy .dialog"

window-new

Creates a new toplevel window.

Parameters:

Returns:

Interpreter -> String -> String -> Int -> Int -> Result Widget TkError

dialog = window-new app ".dialog" "Settings" 300 200 |> Result.unwrap

window-set-title

Sets the title of a window.

Interpreter -> Widget -> String -> Result String TkError

window-set-title app dialog "New Title"

window-get-title

Gets the title of a window.

Interpreter -> Widget -> Result String TkError

window-set-geometry

Sets the geometry (size and position) of a window.

Parameters:

Interpreter -> Widget -> String -> Result String TkError

window-set-geometry app dialog "500x400"

window-get-geometry

Gets the current geometry of a window.

Interpreter -> Widget -> Result String TkError

window-min-size

Sets the minimum size of a window.

Interpreter -> Widget -> Int -> Int -> Result String TkError

window-max-size

Sets the maximum size of a window.

Interpreter -> Widget -> Int -> Int -> Result String TkError

window-resizable

Makes a window resizable or not.

Interpreter -> Widget -> Bool -> Bool -> Result String TkError

window-destroy

Destroys a window.

Interpreter -> Widget -> Result String TkError

window-destroy app dialog

set-title

Sets the title of the main window.

Interpreter -> String -> Result String TkError

set-geometry

Sets the geometry of the main window.

Interpreter -> String -> Result String TkError

set-min-size

Sets the minimum size of the main window.

Interpreter -> Int -> Int -> Result String TkError

destroy

Destroys the main window and exits the application.

Interpreter -> Result String TkError

window-icon

Sets the window icon (from a file).

Note: Icon support varies by platform.

Interpreter -> String -> Result String TkError

window-alpha

Sets the window transparency (alpha).

Alpha is 0.0 (fully transparent) to 1.0 (fully opaque). Note: Not supported on all platforms.

Interpreter -> Float -> Result String TkError

window-topmost

Makes the window stay on top of others.

Interpreter -> Bool -> Result String TkError

window-fullscreen

Makes the window fullscreen.

Interpreter -> Bool -> Result String TkError

window-type

Sets window type (on X11/Linux).

Types: normal, dialog, toolbar, utility, splash

Interpreter -> String -> Result String TkError

messagebox-info

Shows an information message box.

Parameters:

Interpreter -> String -> String -> Result String TkError

messagebox-info app "Success" "Operation completed!"

messagebox-warning

Shows a warning message box.

Interpreter -> String -> String -> Result String TkError

messagebox-warning app "Warning" "This action cannot be undone."

messagebox-error

Shows an error message box.

Interpreter -> String -> String -> Result String TkError

messagebox-error app "Error" "Failed to save file."

messagebox-yesno

Shows a yes/no question dialog.

Returns "yes" or "no".

Interpreter -> String -> String -> Result String TkError

match messagebox-yesno app "Confirm" "Delete this file?"
  | Ok "yes" -> delete-file()
  | _ -> println "Cancelled"

messagebox-okcancel

Shows an ok/cancel question dialog.

Returns "ok" or "cancel".

Interpreter -> String -> String -> Result String TkError

match messagebox-okcancel app "Confirm" "Proceed with operation?"
  | Ok "ok" -> proceed()
  | _ -> println "Cancelled"

messagebox-yesnocancel

Shows a yes/no/cancel question dialog.

Returns "yes", "no", or "cancel".

Interpreter -> String -> String -> Result String TkError

messagebox-retrycancel

Shows a retry/cancel dialog.

Returns "retry" or "cancel".

Interpreter -> String -> String -> Result String TkError

messagebox-custom

Shows a custom message box with all options.

Parameters:

Interpreter -> String -> String -> String -> String -> Result String TkError

messagebox-custom app "abortretryignore" "error" "Error" "Operation failed."

filedialog-open

Opens a file open dialog.

Returns the selected file path, or empty string if cancelled.

Interpreter -> String -> Result String TkError

match filedialog-open app "Open File"
  | Ok "" -> println "Cancelled"
  | Ok path -> println "Selected: ${path}"
  | Err e -> println "Error: ${show e}"

filedialog-open-with

Opens a file open dialog with file type filters.

Parameters:

Interpreter -> String -> String -> Result String TkError

filedialog-open-with app "Open" "{{Kit Files} {.kit}} {{All Files} {*}}"

filedialog-open-multiple

Opens a file open dialog allowing multiple file selection.

Returns a Tcl list of selected file paths.

Interpreter -> String -> Result String TkError

filedialog-open-in

Opens a file open dialog with initial directory.

Interpreter -> String -> String -> Result String TkError

filedialog-save

Opens a file save dialog.

Returns the selected file path, or empty string if cancelled.

Interpreter -> String -> Result String TkError

match filedialog-save app "Save File"
  | Ok "" -> println "Cancelled"
  | Ok path -> save-to-file path
  | Err e -> println "Error: ${show e}"

filedialog-save-with

Opens a file save dialog with file type filters.

Interpreter -> String -> String -> Result String TkError

filedialog-save-default-ext

Opens a file save dialog with default extension.

Interpreter -> String -> String -> Result String TkError

filedialog-save-initial

Opens a file save dialog with initial filename.

Interpreter -> String -> String -> Result String TkError

filedialog-directory

Opens a directory selection dialog.

Returns the selected directory path, or empty string if cancelled.

Interpreter -> String -> Result String TkError

match filedialog-directory app "Select Folder"
  | Ok "" -> println "Cancelled"
  | Ok dir -> println "Selected: ${dir}"
  | Err e -> println "Error: ${show e}"

filedialog-directory-in

Opens a directory selection dialog with initial directory.

Interpreter -> String -> String -> Result String TkError

filedialog-color

Opens a color chooser dialog.

Returns the selected color in #RRGGBB format, or empty string if cancelled.

Interpreter -> String -> Result String TkError

match filedialog-color app "Choose Color"
  | Ok "" -> println "Cancelled"
  | Ok color -> set-background color
  | Err e -> println "Error: ${show e}"

filedialog-color-initial

Opens a color chooser with initial color.

Interpreter -> String -> String -> Result String TkError

menu-new

Creates a new menu widget (popup or as part of menubar).

Parameters:

Interpreter -> String -> Result Widget TkError

menu = menu-new app ".popup" |> Result.unwrap

menu-new-tearoff

Creates a menu with tearoff enabled.

Interpreter -> String -> Result Widget TkError

menu-add-command

Adds a command item to a menu.

Interpreter -> Widget -> String -> String -> Result String TkError

menu-add-command app file-menu "Open" "open-file"

menu-add-command-accel

Adds a command item with keyboard accelerator.

Interpreter -> Widget -> String -> String -> String -> Result String TkError

menu-add-command-accel app file-menu "Open" "Ctrl+O" "open-file"

menu-add-separator

Adds a separator line to a menu.

Interpreter -> Widget -> Result String TkError

menu-add-checkbutton

Adds a checkbutton item to a menu.

Interpreter -> Widget -> String -> String -> Result String TkError

menu-add-checkbutton app view-menu "Show Toolbar" "show_toolbar"

menu-add-checkbutton-cmd

Adds a checkbutton item with command.

Interpreter -> Widget -> String -> String -> String -> Result String TkError

menu-add-radiobutton

Adds a radiobutton item to a menu.

Interpreter -> Widget -> String -> String -> String -> Result String TkError

menu-add-radiobutton app view-menu "Small" "font_size" "small"

menu-add-cascade

Adds a cascade (submenu) to a menu.

Interpreter -> Widget -> String -> Widget -> Result String TkError

submenu = menu-new app ".menubar.file.recent" |> Result.unwrap
menu-add-cascade app file-menu "Recent Files" submenu

menu-popup

Posts (shows) a popup menu at the specified coordinates.

Interpreter -> Widget -> Int -> Int -> Result String TkError

on-right-click app canvas "tk_popup .popup %X %Y"

menu-clear

Removes all items from a menu.

Interpreter -> Widget -> Result String TkError

menu-enable

Enables a menu item by index.

Interpreter -> Widget -> Int -> Result String TkError

menu-disable

Disables a menu item by index.

Interpreter -> Widget -> Int -> Result String TkError

menubar-new

Creates a menubar for the main window.

Interpreter -> Result Widget TkError

menubar = menubar-new app |> Result.unwrap
file-menu = menu-new app ".menubar.file" |> Result.unwrap
menu-add-command app file-menu "Quit" "destroy ."
menubar-add app menubar "File" file-menu

menubar-new-for

Creates a menubar for a specific toplevel window.

Interpreter -> Widget -> Result Widget TkError

menubar-add

Adds a menu to the menubar.

Interpreter -> Widget -> String -> Widget -> Result String TkError

menubar-add app menubar "File" file-menu

pack

Packs any widget.

Interpreter -> Widget -> Result String TkError

pack-with

Packs any widget with options.

Interpreter -> Widget -> String -> Result String TkError

pack-with app label "-side left -padx 10"

grid

Places a widget in a grid cell.

Parameters:

Interpreter -> Widget -> Int -> Int -> Result String TkError

grid app label 0 0  # Place label at row 0, column 0

grid-with

Places a widget in a grid with options.

Common options: - "-sticky nsew" - Stick to all sides (expand) - "-padx 5 -pady 5" - Add padding - "-columnspan 2" - Span multiple columns - "-rowspan 2" - Span multiple rows

Interpreter -> Widget -> Int -> Int -> String -> Result String TkError

grid-with app entry 1 0 "-sticky ew -padx 5"

grid-column-configure

Configures a grid column's properties.

Parameters:

Interpreter -> String -> Int -> String -> Result String TkError

grid-column-configure app "." 1 "-weight 1"  # Column 1 expands

grid-row-configure

Configures a grid row's properties.

Interpreter -> String -> Int -> String -> Result String TkError

grid-row-configure app "." 0 "-weight 1"  # Row 0 expands

grid-forget

Removes a widget from grid management.

Interpreter -> Widget -> Result String TkError

place

Places a widget at absolute coordinates.

Parameters:

Interpreter -> Widget -> Int -> Int -> Result String TkError

place app button 100 50  # Place button at (100, 50)

place-with

Places a widget with options.

Common options: - "-width 100 -height 30" - Set size - "-relx 0.5 -rely 0.5" - Relative position (0.0-1.0) - "-anchor center" - Anchor point (n, s, e, w, ne, nw, se, sw, center) - "-relwidth 0.5" - Relative width

Interpreter -> Widget -> Int -> Int -> String -> Result String TkError

place-with app button 0 0 "-relx 0.5 -rely 0.5 -anchor center"  # Center in parent

place-relative

Places a widget using relative positioning only.

Interpreter -> Widget -> Float -> Float -> String -> Result String TkError

place-relative app button 0.5 0.5 "-anchor center"  # Center in parent

place-forget

Removes a widget from place management.

Interpreter -> Widget -> Result String TkError

widget-destroy

Destroys any widget.

Interpreter -> Widget -> Result String TkError

widget-name

Gets the widget path name as a string.

Widget -> String

ttk-button-new

Creates a themed button (ttk).

TTK widgets automatically use the platform's native look.

Interpreter -> String -> String -> Result Widget TkError

btn = ttk-button-new app ".btn" "Click Me" |> Result.unwrap

ttk-button-new-cmd

Creates a themed button with command.

Interpreter -> String -> String -> String -> Result Widget TkError

ttk-label-new

Creates a themed label (ttk).

Interpreter -> String -> String -> Result Widget TkError

ttk-entry-new

Creates a themed entry (ttk).

Interpreter -> String -> Result Widget TkError

ttk-entry-new-var

Creates a themed entry with textvariable.

Interpreter -> String -> String -> Result Widget TkError

ttk-frame-new

Creates a themed frame (ttk).

Interpreter -> String -> Result Widget TkError

ttk-frame-new-padded

Creates a themed frame with padding.

Interpreter -> String -> Int -> Result Widget TkError

ttk-labelframe-new

Creates a themed labelframe (frame with label).

Interpreter -> String -> String -> Result Widget TkError

ttk-checkbutton-new

Creates a themed checkbutton (ttk).

Interpreter -> String -> String -> String -> Result Widget TkError

ttk-radiobutton-new

Creates a themed radiobutton (ttk).

Interpreter -> String -> String -> String -> String -> Result Widget TkError

ttk-scale-new

Creates a themed scale/slider (ttk).

Interpreter -> String -> Int -> Int -> String -> Result Widget TkError

ttk-scale-new-vertical

Creates a themed vertical scale (ttk).

Interpreter -> String -> Int -> Int -> String -> Result Widget TkError

ttk-progressbar-new

Creates a themed progressbar (ttk).

Parameters:

Interpreter -> String -> Int -> String -> Result Widget TkError

progress = ttk-progressbar-new app ".progress" 100 "determinate" |> Result.unwrap

ttk-progressbar-set

Sets the value of a progressbar.

Interpreter -> Widget -> Int -> Result String TkError

ttk-progressbar-start

Starts an indeterminate progressbar animation.

Interpreter -> Widget -> Result String TkError

ttk-progressbar-stop

Stops a progressbar animation.

Interpreter -> Widget -> Result String TkError

ttk-separator-new

Creates a themed separator (ttk).

Parameters:

Interpreter -> String -> String -> Result Widget TkError

ttk-notebook-new

Creates a themed notebook (tabbed container).

Interpreter -> String -> Result Widget TkError

notebook = ttk-notebook-new app ".tabs" |> Result.unwrap
tab1 = ttk-frame-new app ".tabs.tab1" |> Result.unwrap
ttk-notebook-add app notebook tab1 "Tab 1"

ttk-notebook-add

Adds a tab to a notebook.

Interpreter -> Widget -> Widget -> String -> Result String TkError

ttk-notebook-select

Selects a tab by index.

Interpreter -> Widget -> Int -> Result String TkError

ttk-treeview-new

Creates a themed treeview widget.

Columns is a space-separated list of column IDs.

Interpreter -> String -> String -> Result Widget TkError

tree = ttk-treeview-new app ".tree" "name size date" |> Result.unwrap

ttk-treeview-column

Configures a treeview column.

Interpreter -> Widget -> String -> String -> Int -> Result String TkError

ttk-treeview-insert

Inserts an item into a treeview.

Parameters:

Returns the item ID.

Interpreter -> Widget -> String -> String -> String -> String -> Result String TkError

ttk-treeview-delete

Deletes an item from a treeview.

Interpreter -> Widget -> String -> Result String TkError

ttk-treeview-selection

Gets the selected items from a treeview.

Interpreter -> Widget -> Result String TkError

ttk-spinbox-new

Creates a themed spinbox (ttk).

Interpreter -> String -> Int -> Int -> Result Widget TkError

ttk-spinbox-new-values

Creates a spinbox with a list of values.

Interpreter -> String -> String -> Result Widget TkError

theme-list

Gets the list of available themes.

Common themes: clam, alt, default, classic macOS adds: aqua Windows adds: winnative, xpnative, vista

Interpreter -> Result String TkError

theme-current

Gets the current theme name.

Interpreter -> Result String TkError

theme-set

Sets the current theme.

Interpreter -> String -> Result String TkError

theme-set app "clam"

style-configure

Configures a style option.

Interpreter -> String -> String -> Result String TkError

style-configure app "TButton" "-font {Helvetica 12}"

style-create

Creates a new style with custom options.

In ttk, inheritance is based on naming convention: - "Big.TButton" automatically inherits from "TButton" - "Custom.TLabel" inherits from "TLabel"

Interpreter -> String -> String -> Result String TkError

style-create app "Big.TButton" "-font {Helvetica 16 bold}"

style-map

Maps style options to widget states.

Interpreter -> String -> String -> String -> Result String TkError

style-map app "TButton" "-background" "{active #ff0000} {!active #cccccc}"

style-lookup

Gets style option value.

Interpreter -> String -> String -> Result String TkError

font-create

Creates a named font.

Parameters:

Interpreter -> String -> String -> Int -> Result String TkError

font-create app "myFont" "Helvetica" 14

font-create-full

Creates a named font with weight and slant.

Parameters:

Interpreter -> String -> String -> Int -> String -> String -> Result String TkError

font-configure

Configures an existing font.

Interpreter -> String -> String -> Result String TkError

font-delete

Deletes a named font.

Interpreter -> String -> Result String TkError

font-families

Gets the list of available font families.

Interpreter -> Result String TkError

font-info

Gets information about a font.

Interpreter -> String -> Result String TkError

font-names

Gets the names of all created fonts.

Interpreter -> Result String TkError

font-measure

Measures the width of text in a font (in pixels).

Interpreter -> String -> String -> Result String TkError

widget-bg

Sets the background color of a widget.

Color can be: - Named color: "red", "blue", "green", "white", "black", etc. - Hex color: "#FF0000", "#00FF00", "#0000FF" - RGB: Not directly supported, use hex

Interpreter -> Widget -> String -> Result String TkError

widget-bg app label "#f0f0f0"

widget-fg

Sets the foreground (text) color of a widget.

Interpreter -> Widget -> String -> Result String TkError

widget-font

Sets the font of a widget.

Font can be: - A font name created with font-create - A font specification: "{Helvetica 12 bold}"

Interpreter -> Widget -> String -> Result String TkError

widget-font app label "{Helvetica 14 bold}"

widget-cursor

Sets the cursor for a widget.

Common cursors: arrow, hand2, watch, xterm, crosshair, fleur

Interpreter -> Widget -> String -> Result String TkError

widget-relief

Sets the relief (border style) of a widget.

Relief values: flat, raised, sunken, groove, ridge, solid

Interpreter -> Widget -> String -> Result String TkError

widget-border

Sets the border width of a widget.

Interpreter -> Widget -> Int -> Result String TkError

widget-padding

Sets padding for a widget.

Interpreter -> Widget -> Int -> Result String TkError

widget-padding-xy

Sets horizontal and vertical padding separately.

Interpreter -> Widget -> Int -> Int -> Result String TkError

widget-cget

Gets a widget option value.

Interpreter -> Widget -> String -> Result String TkError

widget-configure

Configures multiple widget options at once.

Interpreter -> Widget -> String -> Result String TkError

combobox-new

Creates a new combobox (dropdown) widget.

Parameters:

Interpreter -> String -> String -> Result Widget TkError

combo = combobox-new app ".colors" "Red Green Blue" |> Result.unwrap

combobox-new-readonly

Creates a read-only combobox (user can only select, not type).

Interpreter -> String -> String -> Result Widget TkError

combobox-get

Gets the current value of the combobox.

Interpreter -> Widget -> Result String TkError

combobox-set

Sets the current value of the combobox.

Interpreter -> Widget -> String -> Result String TkError

combobox-set-values

Sets the available values.

Interpreter -> Widget -> String -> Result String TkError

combobox-current

Gets the index of the current selection (-1 if none).

Interpreter -> Widget -> Result String TkError

combobox-current-set

Sets the selection by index.

Interpreter -> Widget -> Int -> Result String TkError

checkbutton-new

Creates a new checkbutton widget.

Parameters:

Interpreter -> String -> String -> String -> Result Widget TkError

check = checkbutton-new app ".agree" "I agree" "agreed" |> Result.unwrap
# Later: get-var app "agreed" returns "0" or "1"

checkbutton-new-with-values

Creates a checkbutton with custom on/off values.

Interpreter -> String -> String -> String -> String -> String -> Result Widget TkError

checkbutton-select

Programmatically selects (checks) the checkbutton.

Interpreter -> Widget -> Result String TkError

checkbutton-deselect

Programmatically deselects (unchecks) the checkbutton.

Interpreter -> Widget -> Result String TkError

checkbutton-toggle

Toggles the checkbutton state.

Interpreter -> Widget -> Result String TkError

checkbutton-on-toggle

Sets the command to execute when the checkbutton is toggled.

Interpreter -> Widget -> String -> Result String TkError

radiobutton-new

Creates a new radiobutton widget.

Parameters:

Interpreter -> String -> String -> String -> String -> Result Widget TkError

# Create a group of radio buttons sharing the same variable
r1 = radiobutton-new app ".r1" "Option A" "choice" "a" |> Result.unwrap
r2 = radiobutton-new app ".r2" "Option B" "choice" "b" |> Result.unwrap
r3 = radiobutton-new app ".r3" "Option C" "choice" "c" |> Result.unwrap
# get-var app "choice" returns "a", "b", or "c"

radiobutton-select

Programmatically selects the radiobutton.

Interpreter -> Widget -> Result String TkError

radiobutton-on-select

Sets the command to execute when the radiobutton is selected.

Interpreter -> Widget -> String -> Result String TkError

scale-new

Creates a new horizontal scale (slider) widget.

Parameters:

Interpreter -> String -> Int -> Int -> String -> Result Widget TkError

slider = scale-new app ".volume" 0 100 "volume_level" |> Result.unwrap

scale-new-vertical

Creates a vertical scale widget.

Interpreter -> String -> Int -> Int -> String -> Result Widget TkError

scale-new-with-label

Creates a scale with label display.

Interpreter -> String -> Int -> Int -> String -> String -> Result Widget TkError

scale-get

Gets the current value of the scale.

Interpreter -> Widget -> Result String TkError

scale-set

Sets the current value of the scale.

Interpreter -> Widget -> Int -> Result String TkError

scale-on-change

Sets the command to execute when the scale value changes. The command receives the new value as an argument.

Interpreter -> Widget -> String -> Result String TkError

scale-tick-interval

Sets the tick interval (marks on the scale).

Interpreter -> Widget -> Int -> Result String TkError

scale-resolution

Sets the resolution (step size).

Interpreter -> Widget -> Int -> Result String TkError

scale-length

Sets the length of the scale in pixels.

Interpreter -> Widget -> Int -> Result String TkError

create-label

Creates a label widget (legacy). @deprecated Use label-new instead.

Interpreter -> String -> String -> Result String TkError

create-button

Creates a button widget (legacy). @deprecated Use button-new instead.

Interpreter -> String -> String -> Result String TkError

create-entry

Creates an entry widget (legacy). @deprecated Use entry-new instead.

Interpreter -> String -> Result String TkError

create-frame

Creates a frame widget (legacy). @deprecated Use frame-new instead.

Interpreter -> String -> Result String TkError

button-command

Sets button command (legacy). @deprecated Use button-on-click instead.

Interpreter -> String -> String -> Result String TkError

image-create

Creates a photo image from a file.

Supported formats: GIF, PNG (with Img package), PPM/PGM

Parameters:

Interpreter -> String -> String -> Result String TkError

img = image-create app "myImage" "/path/to/image.gif" |> Result.unwrap
label-image app label img

image-create-empty

Creates an empty photo image with specified dimensions.

Interpreter -> String -> Int -> Int -> Result String TkError

image-create-data

Creates a photo image from base64 data.

Interpreter -> String -> String -> Result String TkError

image-delete

Deletes an image.

Interpreter -> String -> Result String TkError

image-width

Gets the width of an image.

Interpreter -> String -> Result String TkError

image-height

Gets the height of an image.

Interpreter -> String -> Result String TkError

image-copy

Copies a region from one image to another.

Interpreter -> String -> String -> Result String TkError

image-copy-subsample

Copies a region with zoom/subsample.

Interpreter -> String -> String -> Int -> Int -> Result String TkError

image-copy-zoom

Copies a region with zoom.

Interpreter -> String -> String -> Int -> Int -> Result String TkError

image-put

Sets a pixel in an image.

Interpreter -> String -> Int -> Int -> String -> Result String TkError

image-put-region

Fills a region with a color.

Interpreter -> String -> Int -> Int -> Int -> Int -> String -> Result String TkError

image-get

Gets the color of a pixel.

Interpreter -> String -> Int -> Int -> Result String TkError

image-blank

Clears an image (makes it transparent).

Interpreter -> String -> Result String TkError

image-write

Writes an image to a file.

Interpreter -> String -> String -> Result String TkError

image-write-format

Writes an image to a file with format specification.

Interpreter -> String -> String -> String -> Result String TkError

image-names

Gets a list of all image names.

Interpreter -> Result String TkError

image-type

Gets the type of an image.

Interpreter -> String -> Result String TkError

label-image

Sets a label to display an image.

Interpreter -> Widget -> String -> Result String TkError

button-image

Sets a button to display an image.

Interpreter -> Widget -> String -> Result String TkError

button-image-compound

Sets a button to display both text and image.

Compound values: top, bottom, left, right, center, none

Interpreter -> Widget -> String -> String -> Result String TkError

canvas-create-image

Creates a canvas image item.

Interpreter -> Widget -> Int -> Int -> String -> Result String TkError

canvas-create-image-anchor

Creates a canvas image item with anchor.

Interpreter -> Widget -> Int -> Int -> String -> String -> Result String TkError

text-new

Creates a new multiline text widget.

Parameters:

Returns:

Interpreter -> String -> Int -> Int -> Result Widget TkError

text = text-new app ".editor" 40 10 |> Result.unwrap
pack app text

text-new-with-wrap

Creates a text widget with wrap mode.

Wrap modes: "none", "char", "word"

Interpreter -> String -> Int -> Int -> String -> Result Widget TkError

text-get-all

Gets all text content from a text widget.

Interpreter -> Widget -> Result String TkError

content = text-get-all app editor |> Result.unwrap

text-get

Gets text content within a range.

Indices use "line.column" format (1-based lines, 0-based columns). Special indices: "1.0" (start), "end" (after last char), "end-1c" (last char)

Interpreter -> Widget -> String -> String -> Result String TkError

first-line = text-get app editor "1.0" "1.end" |> Result.unwrap

text-set-all

Sets the entire text content (replaces existing).

Interpreter -> Widget -> String -> Result String TkError

text-set-all app editor "Hello, World!"

text-insert

Inserts text at a specific index.

Interpreter -> Widget -> String -> String -> Result String TkError

text-insert app editor "end" "New text at end"

text-delete

Deletes text within a range.

Interpreter -> Widget -> String -> String -> Result String TkError

text-delete app editor "1.0" "1.end"  # Delete first line

text-clear

Clears all text content.

Interpreter -> Widget -> Result String TkError

text-readonly

Makes a text widget read-only.

Interpreter -> Widget -> Result String TkError

text-editable

Makes a text widget editable.

Interpreter -> Widget -> Result String TkError

text-font

Sets the font of a text widget.

Interpreter -> Widget -> String -> Result String TkError

TkError

Tk error type for typed error handling.

Interpreter

Tcl interpreter handle.

TkWindow

Tk window handle (pointer to Tk_Window).

Widget

Widget path name (e.g., ".myButton", ".frame.label").

tcl-ok

Tcl success return code.

tcl-error

Tcl error return code.

tcl-dont-wait

Event flag: don't block waiting for events.

tcl-all-events

Event flag: process all event types.

init

Initializes Tcl and Tk, returning an interpreter ready for GUI operations.

Returns:

Result Interpreter TkError

app = init() ?!
main-loop app

cleanup

Cleans up and destroys a Tk application.

Interpreter -> Unit

main-loop

Runs the Tk main event loop (blocks until all windows are closed).

Interpreter -> Unit

get-main-window

Gets the main window of the application.

Interpreter -> TkWindow

process-event?

Processes one event without blocking. Returns true if an event was processed.

Interpreter -> Bool

eval

Evaluates a Tcl script and returns the result.

Interpreter -> String -> Result String TkError

result = eval app "expr 2 + 2"

set-var

Sets a Tcl variable.

Useful for button callbacks that update state.

Interpreter -> String -> String -> Result String TkError

set-var app "counter" "0"
button-on-click app btn "incr counter"

get-var

Gets a Tcl variable's value.

Interpreter -> String -> Result String TkError

incr-var

Increments a Tcl variable (assumes it's a number).

Interpreter -> String -> Result String TkError

canvas-new

Creates a new canvas widget.

Parameters:

Interpreter -> String -> Int -> Int -> Result Widget TkError

canvas = canvas-new app ".drawing" 400 300 |> Result.unwrap

canvas-new-with-bg

Creates a canvas with a background color.

Interpreter -> String -> Int -> Int -> String -> Result Widget TkError

canvas-draw-line

Draws a line on the canvas.

Returns the item ID of the created line.

Interpreter -> Widget -> Int -> Int -> Int -> Int -> Result String TkError

canvas-draw-line-with

Draws a line with options (color, width, etc.).

Interpreter -> Widget -> Int -> Int -> Int -> Int -> String -> Result String TkError

canvas-draw-rect

Draws a rectangle on the canvas.

Interpreter -> Widget -> Int -> Int -> Int -> Int -> Result String TkError

canvas-draw-rect-with

Draws a rectangle with options (fill, outline, etc.).

Interpreter -> Widget -> Int -> Int -> Int -> Int -> String -> Result String TkError

canvas-draw-oval

Draws an oval (ellipse) on the canvas.

Interpreter -> Widget -> Int -> Int -> Int -> Int -> Result String TkError

canvas-draw-oval-with

Draws an oval with options.

Interpreter -> Widget -> Int -> Int -> Int -> Int -> String -> Result String TkError

canvas-draw-text

Draws text on the canvas.

Interpreter -> Widget -> Int -> Int -> String -> Result String TkError

canvas-draw-text-with

Draws text with options (anchor, font, fill, etc.).

Interpreter -> Widget -> Int -> Int -> String -> String -> Result String TkError

canvas-draw-arc

Draws an arc on the canvas.

Interpreter -> Widget -> Int -> Int -> Int -> Int -> String -> Result String TkError

canvas-draw-polygon

Draws a polygon on the canvas. coords should be space-separated "x1 y1 x2 y2 x3 y3 ..."

Interpreter -> Widget -> String -> String -> Result String TkError

canvas-delete

Deletes an item from the canvas by its ID.

Interpreter -> Widget -> String -> Result String TkError

canvas-clear

Deletes all items from the canvas.

Interpreter -> Widget -> Result String TkError

canvas-move

Moves an item by a delta.

Interpreter -> Widget -> String -> Int -> Int -> Result String TkError

canvas-itemconfig

Configures an existing canvas item.

Interpreter -> Widget -> String -> String -> Result String TkError

canvas-bind

Binds an event to a canvas item.

Interpreter -> Widget -> String -> String -> String -> Result String TkError