tk

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

Files

Dependencies

No Kit package dependencies.

This package uses Kit FFI and links against Tcl/Tk native libraries:

Native build settings are defined in kit.toml. The package currently links tcl9.0 and tcl9tk9.0 and includes common Homebrew and Linux Tcl/Tk include and library paths.

Installation

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

Usage

import Kit.Tk as Tk

main = fn =>
  match Tk.init
    | Err e ->
      println "Failed to initialize Tk: ${show e}"
    | Ok app ->
      Tk.set-title app "Hello from Kit!" |> Result.unwrap
      Tk.set-geometry app "400x300" |> Result.unwrap

      label = Tk.label-new app ".greeting" "Hello, Tk!" |> Result.unwrap
      Tk.pack-with app label "-padx 20 -pady 20" |> Result.unwrap

      button = Tk.button-new app ".quit" "Quit" |> Result.unwrap
      Tk.button-on-click app button "destroy ." |> Result.unwrap
      Tk.pack-with app button "-pady 10" |> Result.unwrap

      Tk.main-loop app
      Tk.cleanup app

main

API Areas

Kit.Tk re-exports the public API from the modules in src/, so most applications can import only Kit.Tk.

Key areas:

• Core lifecycle: init, main-loop, cleanup, eval, set-var, get-var
• Windows and layout: set-title, set-geometry, window-new, pack, grid, place
• Basic widgets: labels, buttons, entries, frames, text widgets, listboxes
• TTK widgets: themed buttons, labels, entries, notebooks, treeviews, progress bars, spinboxes
• Events and timers: keyboard, mouse, focus, close handlers, after, after-idle
• Dialogs and menus: message boxes, file dialogs, popup menus, menubars
• Drawing and media: canvas helpers, photo images, scrollbars

The lower-level eval function is available when a feature is easier to express directly in Tcl/Tk.

Development

Running Examples

Run a minimal GUI example with the interpreter:

kit run examples/hello.kit

Run the comprehensive demo:

kit run examples/demo.kit

Compile an example to a native binary:

kit build examples/hello.kit && ./hello

Note: Examples are GUI programs and need access to a desktop display/window server.

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

The tests focus on pure Kit types, constants, imports, and public API availability. Interactive GUI behavior is best checked with the examples.

Running kit dev

Run the standard development workflow:

kit dev

This will:

1. Build or refresh the native Tcl/Tk wrapper when needed
2. Format and check package files
3. Type check source files in src/
4. Type check examples in examples/
5. Run tests in tests/ with coverage

Use --no-spinner for log-friendly output:

kit dev --no-spinner

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html.

Cleaning Build Artifacts

Remove generated files, caches, coverage output, and native build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/tk/, making it available for import as Kit.Tk in other projects.

License

This package is released under the MIT License - see LICENSE for details.

Tcl/Tk is distributed under its own permissive license. See the Tcl/Tk project for upstream license details.

Exported Functions & Types

scrollbar-new

Creates a vertical scrollbar.

Interpreter -> NonEmptyString -> 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 -> NonEmptyString -> Result Widget TkError

ttk-scrollbar-new

Creates a ttk scrollbar (themed).

Interpreter -> NonEmptyString -> Result Widget TkError

ttk-scrollbar-new-horizontal

Creates a ttk horizontal scrollbar.

Interpreter -> NonEmptyString -> 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 -> NonEmptyString -> NonEmptyString -> NonEmptyString -> 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 -> NonEmptyString -> NonEmptyString -> NonEmptyString -> PositiveInt -> PositiveInt -> Result Widget TkError

listbox-scrolled

Adds a listbox with vertical scrollbar.

Interpreter -> NonEmptyString -> NonEmptyString -> NonEmptyString -> Int -> Result Widget TkError

canvas-scrolled

Adds a canvas with both scrollbars.

Interpreter -> NonEmptyString -> NonEmptyString -> NonEmptyString -> NonEmptyString -> PositiveInt -> PositiveInt -> Result Widget TkError

label-new

Creates a new label widget.

Parameters:

Returns:

Interpreter -> NonEmptyString -> 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 -> NonEmptyString -> 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 -> NonEmptyString -> 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 -> NonEmptyString -> Result Widget TkError

frame-new

Creates a new frame container widget.

Interpreter -> NonEmptyString -> Result Widget TkError

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

frame-new-with-border

Creates a frame with a border.

Interpreter -> NonEmptyString -> Int -> Result Widget TkError

listbox-new

Creates a new listbox widget.

Parameters:

Interpreter -> NonEmptyString -> 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 -> NonEmptyString -> 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 -> NonNegativeInt -> String -> Result String TkError

listbox-delete

Deletes an item at a specific index.

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

listbox-delete-range

Deletes items in a range.

Interpreter -> Widget -> NonNegativeInt -> NonNegativeInt -> 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 -> NonNegativeInt -> 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 -> NonNegativeInt -> Result String TkError

listbox-select-clear

Clears selection.

Interpreter -> Widget -> Result String TkError

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 -> NonEmptyString -> 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 -> NonEmptyString -> 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 -> NonEmptyString -> 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 -> NonEmptyString -> String -> Result String TkError

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

on-shift-key

Binds a Shift+key combination.

Interpreter -> Widget -> NonEmptyString -> 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 -> NonEmptyString -> 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 -> NonEmptyString -> NonEmptyString -> PositiveInt -> PositiveInt -> Result Widget TkError

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

window-set-title

Sets the title of a window.

Interpreter -> Widget -> NonEmptyString -> 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 -> PositiveInt -> PositiveInt -> Result String TkError

window-max-size

Sets the maximum size of a window.

Interpreter -> Widget -> PositiveInt -> PositiveInt -> 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 -> NonEmptyString -> 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 -> PositiveInt -> PositiveInt -> 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 -> NonEmptyString -> 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 -> UnitFloat -> 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 -> NonEmptyString -> String -> Result String TkError

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

messagebox-warning

Shows a warning message box.

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

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

messagebox-error

Shows an error message box.

Interpreter -> NonEmptyString -> 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 -> NonEmptyString -> 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 -> NonEmptyString -> 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 -> NonEmptyString -> String -> Result String TkError

messagebox-retrycancel

Shows a retry/cancel dialog.

Returns "retry" or "cancel".

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

messagebox-custom

Shows a custom message box with all options.

Parameters:

Interpreter -> String -> String -> NonEmptyString -> 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 -> NonEmptyString -> 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 -> NonEmptyString -> 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 -> NonEmptyString -> Result String TkError

filedialog-open-in

Opens a file open dialog with initial directory.

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

filedialog-save

Opens a file save dialog.

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

Interpreter -> NonEmptyString -> 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 -> NonEmptyString -> String -> Result String TkError

filedialog-save-default-ext

Opens a file save dialog with default extension.

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

filedialog-save-initial

Opens a file save dialog with initial filename.

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

filedialog-directory

Opens a directory selection dialog.

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

Interpreter -> NonEmptyString -> 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 -> NonEmptyString -> String -> Result String TkError

filedialog-color

Opens a color chooser dialog.

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

Interpreter -> NonEmptyString -> 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 -> NonEmptyString -> String -> Result String TkError

menu-new

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

Parameters:

Interpreter -> NonEmptyString -> Result Widget TkError

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

menu-new-tearoff

Creates a menu with tearoff enabled.

Interpreter -> NonEmptyString -> 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 -> NonNegativeInt -> Result String TkError

menu-disable

Disables a menu item by index.

Interpreter -> Widget -> NonNegativeInt -> 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 -> NonEmptyString -> 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 -> NonEmptyString -> String -> String -> Result Widget TkError

ttk-label-new

Creates a themed label (ttk).

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

ttk-entry-new

Creates a themed entry (ttk).

Interpreter -> NonEmptyString -> Result Widget TkError

ttk-entry-new-var

Creates a themed entry with textvariable.

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

ttk-frame-new

Creates a themed frame (ttk).

Interpreter -> NonEmptyString -> Result Widget TkError

ttk-frame-new-padded

Creates a themed frame with padding.

Interpreter -> NonEmptyString -> Int -> Result Widget TkError

ttk-labelframe-new

Creates a themed labelframe (frame with label).

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

ttk-checkbutton-new

Creates a themed checkbutton (ttk).

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

ttk-radiobutton-new

Creates a themed radiobutton (ttk).

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

ttk-scale-new

Creates a themed scale/slider (ttk).

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

ttk-scale-new-vertical

Creates a themed vertical scale (ttk).

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

ttk-progressbar-new

Creates a themed progressbar (ttk).

Parameters:

Interpreter -> NonEmptyString -> 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 -> NonEmptyString -> String -> Result Widget TkError

ttk-notebook-new

Creates a themed notebook (tabbed container).

Interpreter -> NonEmptyString -> 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 -> NonNegativeInt -> Result String TkError

ttk-treeview-new

Creates a themed treeview widget.

Columns is a space-separated list of column IDs.

Interpreter -> NonEmptyString -> 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 -> PositiveInt -> 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 -> NonEmptyString -> Int -> Int -> Result Widget TkError

ttk-spinbox-new-values

Creates a spinbox with a list of values.

Interpreter -> NonEmptyString -> 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 -> NonEmptyString -> 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 -> NonEmptyString -> String -> String -> Result String TkError

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

style-lookup

Gets style option value.

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

font-create

Creates a named font.

Parameters:

Interpreter -> NonEmptyString -> String -> PositiveInt -> Result String TkError

font-create app "myFont" "Helvetica" 14

font-create-full

Creates a named font with weight and slant.

Parameters:

Interpreter -> NonEmptyString -> String -> PositiveInt -> String -> String -> Result String TkError

font-configure

Configures an existing font.

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

font-delete

Deletes a named font.

Interpreter -> NonEmptyString -> Result String TkError

font-families

Gets the list of available font families.

Interpreter -> Result String TkError

font-info

Gets information about a font.

Interpreter -> NonEmptyString -> 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 -> NonEmptyString -> 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 -> NonEmptyString -> 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 -> NonEmptyString -> 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 -> NonNegativeInt -> Result String TkError

checkbutton-new

Creates a new checkbutton widget.

Parameters:

Interpreter -> NonEmptyString -> 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 -> NonEmptyString -> 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 -> NonEmptyString -> 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 -> NonEmptyString -> 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 -> NonEmptyString -> Int -> Int -> String -> Result Widget TkError

scale-new-with-label

Creates a scale with label display.

Interpreter -> NonEmptyString -> 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 -> NonEmptyString -> String -> Result String TkError

create-button

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

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

create-entry

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

Interpreter -> NonEmptyString -> Result String TkError

create-frame

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

Interpreter -> NonEmptyString -> 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 -> NonEmptyString -> NonEmptyString -> 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 -> NonEmptyString -> PositiveInt -> PositiveInt -> Result String TkError

image-create-data

Creates a photo image from base64 data.

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

image-delete

Deletes an image.

Interpreter -> NonEmptyString -> Result String TkError

image-width

Gets the width of an image.

Interpreter -> NonEmptyString -> Result String TkError

image-height

Gets the height of an image.

Interpreter -> NonEmptyString -> 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 -> NonEmptyString -> Int -> Int -> String -> Result String TkError

image-put-region

Fills a region with a color.

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

image-get

Gets the color of a pixel.

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

image-blank

Clears an image (makes it transparent).

Interpreter -> NonEmptyString -> Result String TkError

image-write

Writes an image to a file.

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

image-write-format

Writes an image to a file with format specification.

Interpreter -> NonEmptyString -> NonEmptyString -> 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 -> NonEmptyString -> Result String TkError

label-image

Sets a label to display an image.

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

button-image

Sets a button to display an image.

Interpreter -> Widget -> NonEmptyString -> 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 -> NonEmptyString -> String -> Result String TkError

canvas-create-image

Creates a canvas image item.

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

canvas-create-image-anchor

Creates a canvas image item with anchor.

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

text-new

Creates a new multiline text widget.

Parameters:

Returns:

Interpreter -> NonEmptyString -> PositiveInt -> PositiveInt -> 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 -> NonEmptyString -> PositiveInt -> PositiveInt -> 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 -> NonEmptyString -> 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 -> NonEmptyString -> Result String TkError

incr-var

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

Interpreter -> NonEmptyString -> Result String TkError

canvas-new

Creates a new canvas widget.

Parameters:

Interpreter -> NonEmptyString -> PositiveInt -> PositiveInt -> Result Widget TkError

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

canvas-new-with-bg

Creates a canvas with a background color.

Interpreter -> NonEmptyString -> PositiveInt -> PositiveInt -> 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